Apply underscore pattern (OpenZeppelin#993)

* feat: apply underscore pattern * fix: mocks * feat: update PausableComponent * feat: apply review updates * fix: signatures * feat: apply review updates * Update CHANGELOG.md Co-authored-by: Andrew Fleming <[email protected]> * feat: apply review updates * feat: apply review update * fix: tests --------- Co-authored-by: Andrew Fleming <[email protected]>
andrew-fleming · Jun 13, 2024 · 7bf2945 · 7bf2945
1 parent 26d875f
commit 7bf2945
Show file tree

Hide file tree

Showing 43 changed files with 1,244 additions and 1,199 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -18,6 +18,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Presets are not public anymore, since they should be copied into projects, and not directly imported.
   - `Trace` and `Checkpoint` structs are not public anymore, since they are intended to be used in `ERC20Votes`, and not as generic utilities.
   - `StorageArray` is not public anymore, since this implementation is specific to `ERC20Votes`, and is not intended as a generic utility, but as a temporary solution until Starknet native implementation arrives.
+- Apply underscore pattern to modules (#993)
+  - AccessControlComponent
+    - `_set_role_admin` function renamed to `set_role_admin`
+  - PausableComponent
+    - `_pause` function renamed to `pause`
+    - `_unpause` function renamed to `unpause`
+  - UpgradeableComponent
+    - `_upgrade` function renamed to `upgrade`
+  - ERC20Component:
+    - `_mint` function renamed to `mint`
+    - `_burn` function renamed to `burn`
+    - `_update` function renamed to `update`
+  - ERC721Component:
+    - `_safe_transfer` function renamed to `safe_transfer`
+    - `_safe_mint` function renamed to `safe_mint`
+    - `_mint` function renamed to `mint`
+    - `_transfer` function renamed to `transfer`
+    - `_burn` function renamed to `burn`
+    - `_update` function renamed to `update`
+  - ERC1155Component:
+    - `set_base_uri` function renamed to `_set_base_uri`
 
 ## 0.13.0 (2024-05-20)
 

diff --git a/README.md b/README.md
@@ -98,7 +98,7 @@ mod MyToken {
         let symbol = "MTK";
 
         self.erc20.initializer(name, symbol);
-        self.erc20._mint(recipient, initial_supply);
+        self.erc20.mint(recipient, initial_supply);
     }
 }
 ```

diff --git a/docs/modules/ROOT/pages/access.adoc b/docs/modules/ROOT/pages/access.adoc
@@ -231,7 +231,7 @@ mod MyContract {
     ) {
         // ERC20-related initialization
         self.erc20.initializer(name, symbol);
-        self.erc20._mint(recipient, initial_supply);
+        self.erc20.mint(recipient, initial_supply);
 
         // AccessControl-related initialization
         self.accesscontrol.initializer();
@@ -242,7 +242,7 @@ mod MyContract {
     #[external(v0)]
     fn mint(ref self: ContractState, recipient: ContractAddress, amount: u256) {
         self.accesscontrol.assert_only_role(MINTER_ROLE);
-        self.erc20._mint(recipient, amount);
+        self.erc20.mint(recipient, amount);
     }
 }
 ----
@@ -323,7 +323,7 @@ mod MyContract {
     ) {
         // ERC20-related initialization
         self.erc20.initializer(name, symbol);
-        self.erc20._mint(recipient, initial_supply);
+        self.erc20.mint(recipient, initial_supply);
 
         // AccessControl-related initialization
         self.accesscontrol.initializer();
@@ -335,14 +335,14 @@ mod MyContract {
     #[external(v0)]
     fn mint(ref self: ContractState, recipient: ContractAddress, amount: u256) {
         self.accesscontrol.assert_only_role(MINTER_ROLE);
-        self.erc20._mint(recipient, amount);
+        self.erc20.mint(recipient, amount);
     }
 
     /// This function can only be called by a burner.
     #[external(v0)]
     fn burn(ref self: ContractState, account: ContractAddress, amount: u256) {
         self.accesscontrol.assert_only_role(BURNER_ROLE);
-        self.erc20._burn(account, amount);
+        self.erc20.burn(account, amount);
     }
 }
 ----
@@ -426,7 +426,7 @@ mod MyContract {
     ) {
         // ERC20-related initialization
         self.erc20.initializer(name, symbol);
-        self.erc20._mint(recipient, initial_supply);
+        self.erc20.mint(recipient, initial_supply);
 
         // AccessControl-related initialization
         self.accesscontrol.initializer();
@@ -437,14 +437,14 @@ mod MyContract {
     #[external(v0)]
     fn mint(ref self: ContractState, recipient: ContractAddress, amount: u256) {
         self.accesscontrol.assert_only_role(MINTER_ROLE);
-        self.erc20._mint(recipient, amount);
+        self.erc20.mint(recipient, amount);
     }
 
     /// This function can only be called by a burner.
     #[external(v0)]
     fn burn(ref self: ContractState, account: ContractAddress, amount: u256) {
         self.accesscontrol.assert_only_role(BURNER_ROLE);
-        self.erc20._burn(account, amount);
+        self.erc20.burn(account, amount);
     }
 }
 ----

diff --git a/docs/modules/ROOT/pages/api/access.adoc b/docs/modules/ROOT/pages/api/access.adoc
@@ -3,7 +3,7 @@
 :Ownable: xref:OwnableComponent[Ownable]
 :src5: https://github.com/starknet-io/SNIPs/blob/main/SNIPS/snip-5.md[SRC5]
 :inner-src5: xref:api/introspection.adoc#ISRC5[SRC5 ID]
-:_set_role_admin: xref:#AccessControlComponent-_set_role_admin[_set_role_admin]
+:set_role_admin: xref:#AccessControlComponent-set_role_admin[set_role_admin]
 
 = Access Control
 
@@ -87,9 +87,9 @@ This module includes the internal `assert_only_owner` to restrict a function to
 
 * xref:OwnableComponent-initializer[`++initializer(self, owner)++`]
 * xref:OwnableComponent-assert_only_owner[`++assert_only_owner(self)++`]
-* xref:OwnableComponent-_accept_ownership[`++_accept_ownership(self)++`]
-* xref:OwnableComponent-_propose_owner[`++_propose_owner(self, new_owner)++`]
 * xref:OwnableComponent-_transfer_ownership[`++_transfer_ownership(self, new_owner)++`]
+* xref:OwnableComponent-_propose_owner[`++_propose_owner(self, new_owner)++`]
+* xref:OwnableComponent-_accept_ownership[`++_accept_ownership(self)++`]
 --
 
 [.contract-index]
@@ -221,16 +221,13 @@ Emits an xref:OwnableComponent-OwnershipTransferred[OwnershipTransferred] event.
 Panics if called by any account other than the owner.
 
 [.contract-item]
-[[OwnableComponent-_accept_ownership]]
-==== `[.contract-item-name]#++_accept_ownership++#++(ref self: ContractState)++` [.item-kind]#internal#
-
-Transfers ownership to the pending owner. Resets pending owner to zero address.
-Calls xref:OwnableComponent-_transfer_ownership[_transfer_ownership].
+[[OwnableComponent-_transfer_ownership]]
+==== `[.contract-item-name]#++_transfer_ownership++#++(ref self: ContractState, new_owner: ContractAddress)++` [.item-kind]#internal#
 
+Transfers ownership of the contract to a new account (`new_owner`).
 Internal function without access restriction.
 
-[.contract-item]
-[[OwnableComponent-_transfer_ownership]]
+Emits an xref:OwnableComponent-OwnershipTransferred[OwnershipTransferred] event.
 
 [.contract-item]
 [[OwnableComponent-_propose_owner]]
@@ -243,10 +240,12 @@ Internal function without access restriction.
 Emits an xref:OwnableComponent-OwnershipTransferStarted[OwnershipTransferStarted] event.
 
 [.contract-item]
-[[OwnableComponent-_transfer_ownership]]
-==== `[.contract-item-name]#++_transfer_ownership++#++(ref self: ContractState, new_owner: ContractAddress)++` [.item-kind]#internal#
+[[OwnableComponent-_accept_ownership]]
+==== `[.contract-item-name]#++_accept_ownership++#++(ref self: ContractState)++` [.item-kind]#internal#
+
+Transfers ownership to the pending owner. Resets pending owner to zero address.
+Calls xref:OwnableComponent-_transfer_ownership[_transfer_ownership].
 
-Transfers ownership of the contract to a new account (`new_owner`).
 Internal function without access restriction.
 
 Emits an xref:OwnableComponent-OwnershipTransferred[OwnershipTransferred] event.
@@ -323,7 +322,7 @@ Returns `true` if `account` has been granted `role`.
 Returns the admin role that controls `role`. See {grant_role} and
 {revoke_role}.
 
-To change a role's admin, use {_set_role_admin}.
+To change a role's admin, use {set_role_admin}.
 
 [.contract-item]
 [[IAccessControl-grant_role]]
@@ -439,7 +438,7 @@ accounts that have a role's admin role can call {grant_role} and {revoke_role}.
 By default, the admin role for all roles is `DEFAULT_ADMIN_ROLE`, which means
 that only accounts with this role will be able to grant or revoke other
 roles. More complex role relationships can be created by using
-{_set_role_admin}.
+{set_role_admin}.
 
 WARNING: The `DEFAULT_ADMIN_ROLE` is also its own admin: it has permission to
 grant and revoke this role. Extra precautions should be taken to secure
@@ -488,7 +487,7 @@ accounts that have been granted it.
 
 * xref:#AccessControlComponent-initializer[`++initializer(self)++`]
 * xref:#AccessControlComponent-assert_only_role[`++assert_only_role(self, role)++`]
-* xref:#AccessControlComponent-_set_role_admin[`++_set_role_admin(self, role, admin_role)++`]
+* xref:#AccessControlComponent-set_role_admin[`++set_role_admin(self, role, admin_role)++`]
 * xref:#AccessControlComponent-_grant_role[`++_grant_role(self, role, account)++`]
 * xref:#AccessControlComponent-_revoke_role[`++_revoke_role(self, role, account)++`]
 --
@@ -518,7 +517,7 @@ Returns `true` if `account` has been granted `role`.
 Returns the admin role that controls `role`. See {grant_role} and
 {revoke_role}.
 
-To change a role's admin, use {_set_role_admin}.
+To change a role's admin, use {set_role_admin}.
 
 [.contract-item]
 [[AccessControlComponent-grant_role]]
@@ -620,11 +619,13 @@ Initializes the contract by registering the xref:#IAccessControl[IAccessControl]
 Panics if called by any account without the given `role`.
 
 [.contract-item]
-[[AccessControlComponent-_set_role_admin]]
-==== `[.contract-item-name]#++_set_role_admin++#++(ref self: ContractState, role: felt252, admin_role: felt252)++` [.item-kind]#internal#
+[[AccessControlComponent-set_role_admin]]
+==== `[.contract-item-name]#++set_role_admin++#++(ref self: ContractState, role: felt252, admin_role: felt252)++` [.item-kind]#internal#
 
 Sets `admin_role` as ``role``'s admin role.
 
+Internal function without access restriction.
+
 Emits a {RoleAdminChanged} event.
 
 [.contract-item]

diff --git a/docs/modules/ROOT/pages/api/erc1155.adoc b/docs/modules/ROOT/pages/api/erc1155.adoc
@@ -220,13 +220,13 @@ NOTE: See xref:#ERC1155Component-Hooks[Hooks] to understand how are hooks used.
 --
 .InternalImpl
 * xref:#ERC1155Component-initializer[`++initializer(self, base_uri)++`]
-* xref:#ERC1155Component-update[`++update(self, from, to, token_ids, values)++`]
-* xref:#ERC1155Component-update_with_acceptance_check[`++update_with_acceptance_check(self, from, to, token_ids, values, data)++`]
 * xref:#ERC1155Component-mint_with_acceptance_check[`++mint_with_acceptance_check(self, to, token_id, value, data)++`]
 * xref:#ERC1155Component-batch_mint_with_acceptance_check[`++batch_mint_with_acceptance_check(self, to, token_ids, values, data)++`]
 * xref:#ERC1155Component-burn[`++burn(self, from, token_id, value)++`]
 * xref:#ERC1155Component-batch_burn[`++batch_burn(self, from, token_ids, values)++`]
-* xref:#ERC1155Component-set_base_uri[`++set_base_uri(self, base_uri)++`]
+* xref:#ERC1155Component-update_with_acceptance_check[`++update_with_acceptance_check(self, from, to, token_ids, values, data)++`]
+* xref:#ERC1155Component-update[`++update(self, from, to, token_ids, values)++`]
+* xref:#ERC1155Component-_set_base_uri[`++_set_base_uri(self, base_uri)++`]
 --
 
 [.contract-index]
@@ -401,42 +401,6 @@ See <<ERC1155Component-is_approved_for_all,ERC1155Component::is_approved_for_all
 Initializes the contract by setting the token's base URI as `base_uri`, and registering the supported interfaces.
 This should only be used inside the contract's constructor.
 
-[.contract-item]
-[[ERC1155Component-update]]
-==== `[.contract-item-name]#++update++#++(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>)++` [.item-kind]#internal#
-
-Transfers a `value` amount of tokens of type `id` from `from` to `to`.
-Will mint (or burn) if `from` (or `to`) is the zero address.
-
-Requirements:
-
-- `token_ids` and `values` must have the same length.
-
-Emits a <<ERC1155Component-TransferSingle,TransferSingle>> event if the arrays contain one element,
-and <<ERC1155Component-TransferBatch,TransferBatch>> otherwise.
-
-NOTE: This function can be extended using the xref:ERC1155Component-ERC1155HooksTrait[ERC1155HooksTrait], to add
-functionality before and/or after the transfer, mint, or burn.
-
-NOTE: The ERC1155 acceptance check is not performed in this function.
-See <<ERC1155Component-update_with_acceptance_check,update_with_acceptance_check>> instead.
-
-[.contract-item]
-[[ERC1155Component-update_with_acceptance_check]]
-==== `[.contract-item-name]#++update_with_acceptance_check++#++(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data: Span<felt252>)++` [.item-kind]#internal#
-
-Version of `update` that performs the token acceptance check by calling
-`onERC1155Received` or `onERC1155BatchReceived` in the receiver if
-it implements `IERC1155Receiver`, otherwise by checking if it is an account.
-
-Requirements:
-
-- `to` is either an account contract or supports the `IERC1155Receiver` interface.
-- `token_ids` and `values` must have the same length.
-
-Emits a <<ERC1155Component-TransferSingle,TransferSingle>> event if the arrays contain one element,
-and <<ERC1155Component-TransferBatch,TransferBatch>> otherwise.
-
 [.contract-item]
 [[ERC1155Component-mint_with_acceptance_check]]
 ==== `[.contract-item-name]#++mint_with_acceptance_check++#++(ref self: ContractState, to: ContractAddress, token_id: u256, value: u256, data: Span<felt252>)++` [.item-kind]#internal#
@@ -494,8 +458,44 @@ Requirements:
 Emits a <<ERC1155Component-TransferBatch,TransferBatch>> event.
 
 [.contract-item]
-[[ERC1155Component-set_base_uri]]
-==== `[.contract-item-name]#++set_base_uri++#++(ref self: ContractState, base_uri: ByteArray)++` [.item-kind]#internal#
+[[ERC1155Component-update_with_acceptance_check]]
+==== `[.contract-item-name]#++update_with_acceptance_check++#++(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data: Span<felt252>)++` [.item-kind]#internal#
+
+Version of `update` that performs the token acceptance check by calling
+`onERC1155Received` or `onERC1155BatchReceived` in the receiver if
+it implements `IERC1155Receiver`, otherwise by checking if it is an account.
+
+Requirements:
+
+- `to` is either an account contract or supports the `IERC1155Receiver` interface.
+- `token_ids` and `values` must have the same length.
+
+Emits a <<ERC1155Component-TransferSingle,TransferSingle>> event if the arrays contain one element,
+and <<ERC1155Component-TransferBatch,TransferBatch>> otherwise.
+
+[.contract-item]
+[[ERC1155Component-update]]
+==== `[.contract-item-name]#++update++#++(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>)++` [.item-kind]#internal#
+
+Transfers a `value` amount of tokens of type `id` from `from` to `to`.
+Will mint (or burn) if `from` (or `to`) is the zero address.
+
+Requirements:
+
+- `token_ids` and `values` must have the same length.
+
+Emits a <<ERC1155Component-TransferSingle,TransferSingle>> event if the arrays contain one element,
+and <<ERC1155Component-TransferBatch,TransferBatch>> otherwise.
+
+NOTE: This function can be extended using the xref:ERC1155Component-ERC1155HooksTrait[ERC1155HooksTrait], to add
+functionality before and/or after the transfer, mint, or burn.
+
+NOTE: The ERC1155 acceptance check is not performed in this function.
+See <<ERC1155Component-update_with_acceptance_check,update_with_acceptance_check>> instead.
+
+[.contract-item]
+[[ERC1155Component-_set_base_uri]]
+==== `[.contract-item-name]#++_set_base_uri++#++(ref self: ContractState, base_uri: ByteArray)++` [.item-kind]#internal#
 
 Sets a new URI for all token types, by relying on the token type ID
 substitution mechanism