diff --git a/contracts/src/access/control.rs b/contracts/src/access/control.rs index 6942a1d7a..5367f89de 100644 --- a/contracts/src/access/control.rs +++ b/contracts/src/access/control.rs @@ -145,8 +145,8 @@ impl AccessControl { /// /// # Errors /// - /// If [`msg::sender`] has not been granted `role`, then the error - /// [`Error::UnauthorizedAccount`] is returned. + /// * [`Error::UnauthorizedAccount`] - If [`msg::sender`] has not been + /// granted `role`. pub fn only_role(&self, role: B256) -> Result<(), Error> { self._check_role(role, msg::sender()) } @@ -170,7 +170,7 @@ impl AccessControl { /// If `account` had not been already granted `role`, emits a /// [`RoleGranted`] event. /// - /// # Requirements: + /// # Requirements /// /// * The caller must have `role`'s admin role. /// @@ -182,12 +182,12 @@ impl AccessControl { /// /// # Errors /// - /// If [`msg::sender`] has not been granted `role`, then the error - /// [`Error::UnauthorizedAccount`] is returned. + /// * [`Error::UnauthorizedAccount`] - If [`msg::sender`] has not been + /// granted `role`. /// /// # Events /// - /// May emit a [`RoleGranted`] event. + /// * [`RoleGranted`] pub fn grant_role( &mut self, role: B256, @@ -203,7 +203,7 @@ impl AccessControl { /// /// If `account` had been granted `role`, emits a [`RoleRevoked`] event. /// - /// # Requirements: + /// # Requirements /// /// * The caller must have `role`'s admin role. /// @@ -215,12 +215,12 @@ impl AccessControl { /// /// # Errors /// - /// If [`msg::sender`] has not been granted `role`, then the error - /// [`Error::UnauthorizedAccount`] is returned. + /// * [`Error::UnauthorizedAccount`] - If [`msg::sender`] has not been + /// granted `role`. /// /// # Events /// - /// May emit a [`RoleRevoked`] event. + /// * [`RoleRevoked`]. pub fn revoke_role( &mut self, role: B256, @@ -239,7 +239,7 @@ impl AccessControl { /// for accounts to lose their privileges if they are compromised (such as /// when a trusted device is misplaced). /// - /// # Requirements: + /// # Requirements /// /// * The caller must be `confirmation`. /// @@ -251,13 +251,12 @@ impl AccessControl { /// /// # Errors /// - /// If [`msg::sender`] is not the `confirmation` address, then the error - /// [`Error::BadConfirmation`] is returned. + /// * [`Error::BadConfirmation`] - If [`msg::sender`] is not the + /// `confirmation` address. /// /// # Events /// - /// If the calling account has its `role` revoked, emits a [`RoleRevoked`] - /// event. + /// * [`RoleRevoked`] - If the calling account has its `role` revoked. pub fn renounce_role( &mut self, role: B256, @@ -288,7 +287,7 @@ impl AccessControl { /// /// # Events /// - /// Emits a [`RoleAdminChanged`] event. + /// * [`RoleAdminChanged`]. pub fn _set_role_admin(&mut self, role: B256, new_admin_role: B256) { let previous_admin_role = self.get_role_admin(role); self._roles.setter(role).admin_role.set(new_admin_role); @@ -309,8 +308,8 @@ impl AccessControl { /// /// # Errors /// - /// If [`msg::sender`] has not been granted `role`, then the error - /// [`Error::UnauthorizedAccount`] is returned. + /// * [`Error::UnauthorizedAccount`] - If [`msg::sender`] has not been + /// granted `role`. pub fn _check_role( &self, role: B256, @@ -338,7 +337,7 @@ impl AccessControl { /// /// # Events /// - /// May emit a [`RoleGranted`] event. + /// * [`RoleGranted`]. pub fn _grant_role(&mut self, role: B256, account: Address) -> bool { if self.has_role(role, account) { false @@ -362,7 +361,7 @@ impl AccessControl { /// /// # Events /// - /// May emit a [`RoleRevoked`] event. + /// * [`RoleRevoked`]. pub fn _revoke_role(&mut self, role: B256, account: Address) -> bool { if self.has_role(role, account) { self._roles.setter(role).has_role.insert(account, false); diff --git a/contracts/src/access/ownable.rs b/contracts/src/access/ownable.rs index 2ad282c53..c533e6e89 100644 --- a/contracts/src/access/ownable.rs +++ b/contracts/src/access/ownable.rs @@ -96,12 +96,11 @@ pub trait IOwnable { /// /// # Errors /// - /// If `new_owner` is the zero address, then the error - /// [`OwnableInvalidOwner`] is returned. + /// * [`OwnableInvalidOwner`] - If `new_owner` is the `Address::ZERO`. /// /// # Events /// - /// Emits a [`OwnershipTransferred`] event. + /// * [`OwnershipTransferred`]. fn transfer_ownership( &mut self, new_owner: Address, @@ -120,12 +119,11 @@ pub trait IOwnable { /// /// # Errors /// - /// If not called by the owner, then the error - /// [`Error::UnauthorizedAccount`] is returned. + /// * [`Error::UnauthorizedAccount`] - If not called by the owner. /// /// # Events /// - /// Emits a [`OwnershipTransferred`] event. + /// * [`OwnershipTransferred`]. fn renounce_ownership(&mut self) -> Result<(), Self::Error>; } @@ -170,8 +168,8 @@ impl Ownable { /// /// # Errors /// - /// If called by any account other than the owner, then the error - /// [`Error::UnauthorizedAccount`] is returned. + /// * [`Error::UnauthorizedAccount`] - If called by any account other than + /// the owner. pub fn only_owner(&self) -> Result<(), Error> { let account = msg::sender(); if self.owner() != account { @@ -193,7 +191,7 @@ impl Ownable { /// /// # Events /// - /// Emits a [`OwnershipTransferred`] event. + /// * [`OwnershipTransferred`]. pub fn _transfer_ownership(&mut self, new_owner: Address) { let previous_owner = self._owner.get(); self._owner.set(new_owner); diff --git a/contracts/src/access/ownable_two_step.rs b/contracts/src/access/ownable_two_step.rs index 8dca87d9f..08520f794 100644 --- a/contracts/src/access/ownable_two_step.rs +++ b/contracts/src/access/ownable_two_step.rs @@ -103,12 +103,12 @@ pub trait IOwnable2Step { /// /// # Errors /// - /// If called by any account other than the owner, then the error - /// [`OwnableError::UnauthorizedAccount`] is returned. + /// * [`OwnableError::UnauthorizedAccount`] - If called by any account other + /// than the owner. /// /// # Events /// - /// Emits a [`OwnershipTransferStarted`] event. + /// * [`OwnershipTransferStarted`]. fn transfer_ownership( &mut self, new_owner: Address, @@ -123,12 +123,12 @@ pub trait IOwnable2Step { /// /// # Errors /// - /// If called by any account other than the pending owner, then the error - /// [`OwnableError::UnauthorizedAccount`] is returned. + /// * [`OwnableError::UnauthorizedAccount`] - If called by any account other + /// than the pending owner. /// /// # Events /// - /// Emits a [`crate::access::ownable::OwnershipTransferred`] event. + /// * [`crate::access::ownable::OwnershipTransferred`]. fn accept_ownership(&mut self) -> Result<(), Self::Error>; /// Leaves the contract without owner. It will not be possible to call @@ -139,14 +139,16 @@ pub trait IOwnable2Step { /// thereby disabling any functionality that is only available to the owner. /// /// # Arguments + /// + /// * `&mut self` - Write access to the contract's state. + /// /// # Errors /// - /// If not called by the owner, then the error - /// [`OwnableError::UnauthorizedAccount`] is returned. + /// * [`OwnableError::UnauthorizedAccount`] - If not called by the owner. /// /// # Events /// - /// Emits a [`crate::access::ownable::OwnershipTransferred`] event. + /// * [`crate::access::ownable::OwnershipTransferred`]. fn renounce_ownership(&mut self) -> Result<(), Self::Error>; } @@ -212,7 +214,7 @@ impl Ownable2Step { /// /// # Events /// - /// Emits a [`crate::access::ownable::OwnershipTransferred`] event. + /// * [`crate::access::ownable::OwnershipTransferred`]. fn _transfer_ownership(&mut self, new_owner: Address) { self._pending_owner.set(Address::ZERO); self._ownable._transfer_ownership(new_owner); diff --git a/contracts/src/finance/vesting_wallet.rs b/contracts/src/finance/vesting_wallet.rs index 0e5f52656..b483826b7 100644 --- a/contracts/src/finance/vesting_wallet.rs +++ b/contracts/src/finance/vesting_wallet.rs @@ -162,14 +162,14 @@ pub trait IVestingWallet { /// /// # Errors /// - /// If called by any account other than the owner, then the error - /// [`ownable::Error::UnauthorizedAccount`] is returned. - /// If `new_owner` is the `Address::ZERO`, then the error - /// [`ownable::Error::InvalidOwner`] is returned. + /// * [`ownable::Error::UnauthorizedAccount`] - If called by any account + /// other than the owner. + /// * [`ownable::Error::InvalidOwner`] - If `new_owner` is the + /// `Address::ZERO`. /// /// # Events /// - /// Emits an [`ownable::OwnershipTransferred`] event. + /// * [`ownable::OwnershipTransferred`]. fn transfer_ownership( &mut self, new_owner: Address, @@ -190,12 +190,11 @@ pub trait IVestingWallet { /// /// # Errors /// - /// If not called by the owner, then the error - /// [`ownable::Error::UnauthorizedAccount`] is returned. + /// * [`ownable::Error::UnauthorizedAccount`] - If not called by the owner. /// /// # Events /// - /// Emits an [`ownable::OwnershipTransferred`] event. + /// * [`ownable::OwnershipTransferred`]. fn renounce_ownership(&mut self) -> Result<(), Self::Error>; /// The contract should be able to receive Ether. @@ -251,8 +250,8 @@ pub trait IVestingWallet { /// /// # Panics /// - /// If total allocation exceeds `U256::MAX`. - /// If scaled, total allocation (mid calculation) exceeds `U256::MAX`. + /// * If total allocation exceeds `U256::MAX`. + /// * If scaled, total allocation (mid calculation) exceeds `U256::MAX`. #[selector(name = "releasable")] fn releasable_eth(&self) -> U256; @@ -266,13 +265,12 @@ pub trait IVestingWallet { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::InvalidToken`] is returned. + /// * [`Error::InvalidToken`] - If the `token` address is not a contract. /// /// # Panics /// - /// If total allocation exceeds `U256::MAX`. - /// If scaled, total allocation (mid calculation) exceeds `U256::MAX`. + /// * If total allocation exceeds `U256::MAX`. + /// * If scaled, total allocation (mid calculation) exceeds `U256::MAX`. #[selector(name = "releasable")] fn releasable_erc20(&mut self, token: Address) -> Result; @@ -285,17 +283,16 @@ pub trait IVestingWallet { /// /// # Errors /// - /// If Ether transfer fails, then the error [`Error::ReleaseEtherFailed`] is - /// returned. + /// * [`Error::ReleaseEtherFailed`] - If Ether transfer fails. /// /// # Events /// - /// Emits an [`EtherReleased`] event. + /// * [`EtherReleased`]. /// /// # Panics /// - /// If total allocation exceeds `U256::MAX`. - /// If scaled total allocation (mid calculation) exceeds `U256::MAX`. + /// * If total allocation exceeds `U256::MAX`. + /// * If scaled total allocation (mid calculation) exceeds `U256::MAX`. #[selector(name = "release")] fn release_eth(&mut self) -> Result<(), Self::Error>; @@ -308,19 +305,18 @@ pub trait IVestingWallet { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::InvalidToken`] is returned. - /// If the contract fails to execute the call, then the error - /// [`safe_erc20::Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::InvalidToken`] - If the `token` address is not a contract. + /// * [`safe_erc20::Error::SafeErc20FailedOperation`] - If the contract + /// fails to execute the call. /// /// # Events /// - /// Emits an [`ERC20Released`] event. + /// * [`ERC20Released`]. /// /// # Panics /// - /// If total allocation exceeds `U256::MAX`. - /// If scaled, total allocation (mid calculation) exceeds `U256::MAX`. + /// * If total allocation exceeds `U256::MAX`. + /// * If scaled, total allocation (mid calculation) exceeds `U256::MAX`. #[selector(name = "release")] fn release_erc20(&mut self, token: Address) -> Result<(), Self::Error>; @@ -334,8 +330,8 @@ pub trait IVestingWallet { /// /// # Panics /// - /// If total allocation exceeds `U256::MAX`. - /// If scaled, total allocation (mid calculation) exceeds `U256::MAX`. + /// * If total allocation exceeds `U256::MAX`. + /// * If scaled, total allocation (mid calculation) exceeds `U256::MAX`. #[selector(name = "vestedAmount")] fn vested_amount_eth(&self, timestamp: u64) -> U256; @@ -350,13 +346,12 @@ pub trait IVestingWallet { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::InvalidToken`] is returned. + /// * [`Error::InvalidToken`] - If the `token` address is not a contract. /// /// # Panics /// - /// If total allocation exceeds `U256::MAX`. - /// If scaled, total allocation (mid calculation) exceeds `U256::MAX`. + /// * If total allocation exceeds `U256::MAX`. + /// * If scaled, total allocation (mid calculation) exceeds `U256::MAX`. #[selector(name = "vestedAmount")] fn vested_amount_erc20( &mut self, @@ -505,7 +500,7 @@ impl VestingWallet { /// /// # Panics /// - /// If scaled, total allocation (mid calculation) exceeds `U256::MAX`. + /// * If scaled, total allocation (mid calculation) exceeds `U256::MAX`. fn vesting_schedule(&self, total_allocation: U256, timestamp: U64) -> U256 { let timestamp = U256::from(timestamp); diff --git a/contracts/src/token/erc1155/extensions/burnable.rs b/contracts/src/token/erc1155/extensions/burnable.rs index bae3789f6..a09efd1a9 100644 --- a/contracts/src/token/erc1155/extensions/burnable.rs +++ b/contracts/src/token/erc1155/extensions/burnable.rs @@ -26,13 +26,11 @@ pub trait IErc1155Burnable { /// /// # Errors /// - /// If the caller is not `account` address and the `account` has not been - /// approved, then the error [`Error::MissingApprovalForAll`] is - /// returned. - /// If `from` is the `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. + /// * [`Error::MissingApprovalForAll`] - If the caller is not `account` + /// address and the `account` has not been approved. + /// * [`Error::InvalidSender`] - If `from` is the `Address::ZERO`. + /// * [`Error::InsufficientBalance`] - If `value` is greater than the + /// balance of the `from` account. fn burn( &mut self, account: Address, @@ -51,16 +49,14 @@ pub trait IErc1155Burnable { /// /// # Errors /// - /// If the caller is not `account` address and the `account` has not been - /// approved, then the error [`Error::MissingApprovalForAll`] is - /// returned. - /// If `from` is the `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If any of the `values` is greater than the balance of the respective - /// token from `tokens` of the `from` account, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::MissingApprovalForAll`] - If the caller is not `account` + /// address and the `account` has not been approved. + /// * [`Error::InvalidSender`] - If `from` is the `Address::ZERO`. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to + /// length of `values`. + /// * [`Error::InsufficientBalance`] - If any of the `values` is greater + /// than the balance of the respective token from `tokens` of the `from` + /// account. fn burn_batch( &mut self, account: Address, diff --git a/contracts/src/token/erc1155/extensions/supply.rs b/contracts/src/token/erc1155/extensions/supply.rs index eb3e4f1ca..61e90d9cc 100644 --- a/contracts/src/token/erc1155/extensions/supply.rs +++ b/contracts/src/token/erc1155/extensions/supply.rs @@ -196,6 +196,9 @@ impl Erc1155Supply { /// Extended version of [`Erc1155::_update`] that updates the supply of /// tokens. /// + /// NOTE: The ERC-1155 acceptance check is not performed in this function. + /// See [`Self::_update_with_acceptance_check`] instead. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -206,23 +209,21 @@ impl Erc1155Supply { /// /// # Errors /// - /// If length of `ids` is not equal to length of `values`, then the - /// error [`erc1155::Error::InvalidArrayLength`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`erc1155::Error::InsufficientBalance`] is returned. - /// - /// NOTE: The ERC-1155 acceptance check is not performed in this function. - /// See [`Self::_update_with_acceptance_check`] instead. + /// * [`erc1155::Error::InvalidArrayLength`] - If length of `ids` is not + /// equal to length of `values`. + /// * [`erc1155::Error::InsufficientBalance`] - If `value` is greater than + /// the balance of the `from` account. /// /// # Events /// - /// Emits a [`erc1155::TransferSingle`] event if the arrays contain one - /// element, and [`erc1155::TransferBatch`] otherwise. + /// * [`erc1155::TransferSingle`] - If the arrays contain one element. + /// * [`erc1155::TransferBatch`] - If the arrays contain more than one + /// element. /// /// # Panics /// - /// If updated balance and/or supply exceeds `U256::MAX`, may happen during - /// the `mint` operation. + /// * If updated balance and/or supply exceeds `U256::MAX`, may happen + /// during the `mint` operation. fn _update( &mut self, from: Address, diff --git a/contracts/src/token/erc1155/extensions/uri_storage.rs b/contracts/src/token/erc1155/extensions/uri_storage.rs index 0c62d875d..485953fe9 100644 --- a/contracts/src/token/erc1155/extensions/uri_storage.rs +++ b/contracts/src/token/erc1155/extensions/uri_storage.rs @@ -26,6 +26,12 @@ pub struct Erc1155UriStorage { impl Erc1155UriStorage { /// Returns the Uniform Resource Identifier (URI) for `token_id` token. /// + /// NOTE: To expose this function in your contract's ABI, implement it as + /// shown in the Examples section below, accepting only the `token_id` + /// parameter. The `metadata_uri` reference should come from your contract's + /// state. The implementation should forward the call to your internal + /// storage instance along with the metadata reference. + /// /// # Arguments /// /// * `&self` - Read access to the contract's state. @@ -33,15 +39,13 @@ impl Erc1155UriStorage { /// * `metadata_uri` - Read access to a contract providing /// [`IErc1155MetadataUri`] interface. /// - /// NOTE: In order to have [`Erc1155UriStorage::uri`] exposed in ABI, - /// you need to do this manually. - /// /// # Examples /// /// ```rust,ignore /// pub fn uri(&self, token_id: U256) -> String { /// self.uri_storage.uri(token_id, &self.metadata_uri) /// } + /// ``` pub fn uri( &self, token_id: U256, @@ -68,7 +72,7 @@ impl Erc1155UriStorage { /// /// # Events /// - /// Emits a [`URI`] event. + /// * [`URI`]. pub fn set_token_uri( &mut self, token_id: U256, diff --git a/contracts/src/token/erc1155/mod.rs b/contracts/src/token/erc1155/mod.rs index ae93e4764..30f3fd899 100644 --- a/contracts/src/token/erc1155/mod.rs +++ b/contracts/src/token/erc1155/mod.rs @@ -239,8 +239,8 @@ pub trait IErc1155 { /// /// # Errors /// - /// * If the length of `accounts` is not equal to the length of `ids`, - /// then the error [`Error::InvalidArrayLength`] is returned. + /// * [`Error::InvalidArrayLength`] - If the length of `accounts` is not + /// equal to the length of `ids`. fn balance_of_batch( &self, accounts: Vec
, @@ -250,6 +250,10 @@ pub trait IErc1155 { /// Grants or revokes permission to `operator` /// to transfer the caller's tokens, according to `approved`. /// + /// # Requirements + /// + /// * The `operator` cannot be the `Address::ZERO`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -260,16 +264,11 @@ pub trait IErc1155 { /// /// # Errors /// - /// * If `operator` is `Address::ZERO`, then the error - /// [`Error::InvalidOperator`] is returned. - /// - /// # Requirements - /// - /// * The `operator` cannot be the `Address::ZERO`. + /// * [`Error::InvalidOperator`] - If `operator` is `Address::ZERO`. /// /// # Events /// - /// Emits an [`ApprovalForAll`] event. + /// * [`ApprovalForAll`]. fn set_approval_for_all( &mut self, operator: Address, @@ -289,6 +288,17 @@ pub trait IErc1155 { /// Transfers a `value` amount of tokens of type `id` from `from` to /// `to`. /// + /// # Requirements + /// + /// * `to` cannot be the `Address::ZERO`. + /// * If the caller is not `from`, it must have been approved to spend + /// `from`'s tokens via [`IErc1155::set_approval_for_all`]. + /// * `from` must have a balance of tokens of type `id` of at least `value` + /// amount. + /// * If `to` refers to a smart contract, it must implement + /// [`IERC1155Receiver::on_erc_1155_received`] and return the acceptance + /// value. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -301,37 +311,23 @@ pub trait IErc1155 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If `from` is `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If the `from` is not the caller (`msg::sender()`), - /// and the caller does not have the right to approve, then the error - /// [`Error::MissingApprovalForAll`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// - /// # Requirements - /// - /// * `to` cannot be the `Address::ZERO`. - /// * If the caller is not `from`, it must have been approved to spend - /// `from`'s tokens via [`IErc1155::set_approval_for_all`]. - /// * `from` must have a balance of tokens of type `id` of at least `value` - /// amount. - /// * If `to` refers to a smart contract, it must implement - /// [`IERC1155Receiver::on_erc_1155_received`] and return the acceptance - /// value. + /// * [`Error::InvalidReceiver`] - Returned when `to` is `Address::ZERO` or + /// when `IERC1155Receiver::on_erc_1155_received` hasn't returned its + /// interface id or returned with error. + /// * [`Error::InvalidSender`] - Returned when `from` is `Address::ZERO`. + /// * [`Error::MissingApprovalForAll`] - Returned when `from` is not the + /// caller (`msg::sender()`), and the caller does not have the right to + /// approve. + /// * [`Error::InsufficientBalance`] - Returned when `value` is greater than + /// the balance of the `from` account. /// /// # Events /// - /// Emits a [`TransferSingle`] event. + /// * [`TransferSingle`]. /// /// # Panics /// - /// Should not panic. + /// * Should not panic. fn safe_transfer_from( &mut self, from: Address, @@ -343,6 +339,18 @@ pub trait IErc1155 { /// Batched version of [`IErc1155::safe_transfer_from`]. /// + /// # Requirements + /// + /// * `to` cannot be the `Address::ZERO`. + /// * If the caller is not `from`, it must have been approved to spend + /// `from`'s tokens via [`IErc1155::set_approval_for_all`]. + /// * `from` must have a balance of tokens being transferred of at least + /// transferred amount. + /// * `ids` and `values` must have the same length. + /// * If `to` refers to a smart contract, it must implement + /// [`IERC1155Receiver::on_erc_1155_batch_received`] and return the + /// acceptance magic value. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -355,41 +363,26 @@ pub trait IErc1155 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If `from` is `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. - /// If the `from` is not the caller (`msg::sender()`), - /// and the caller does not have the right to approve, then the error - /// [`Error::MissingApprovalForAll`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// - /// # Requirements - /// - /// * `to` cannot be the `Address::ZERO`. - /// * If the caller is not `from`, it must have been approved to spend - /// `from`'s tokens via [`IErc1155::set_approval_for_all`]. - /// * `from` must have a balance of tokens being transferred of at least - /// transferred amount. - /// * `ids` and `values` must have the same length. - /// * If `to` refers to a smart contract, it must implement - /// [`IERC1155Receiver::on_erc_1155_batch_received`] and return the - /// acceptance magic value. + /// * [`Error::InvalidReceiver`] - Returned when `to` is `Address::ZERO` or + /// when `IERC1155Receiver::on_erc_1155_batch_received` hasn't returned + /// its interface id or returned with error. + /// * [`Error::InvalidSender`] - Returned when `from` is `Address::ZERO`. + /// * [`Error::InvalidArrayLength`] - Returned when the length of `ids` is + /// not equal to the length of `values`. + /// * [`Error::InsufficientBalance`] - Returned when any of the `values` is + /// greater than the balance of the `from` account. + /// * [`Error::MissingApprovalForAll`] - Returned when `from` is not the + /// caller (`msg::sender()`), and the caller does not have the right to + /// approve. /// /// # Events /// - /// Emits either a [`TransferSingle`] or a [`TransferBatch`] event, - /// depending on the length of the array arguments. + /// * [`TransferSingle`] - if the arrays contain one element. + /// * [`TransferBatch`] - if the arrays contain multiple elements. /// /// # Panics /// - /// Should not panic. + /// * Should not panic. fn safe_batch_transfer_from( &mut self, from: Address, @@ -472,6 +465,9 @@ impl Erc1155 { /// Transfers a `value` amount of tokens of type `ids` from `from` to /// `to`. Will mint (or burn) if `from` (or `to`) is the `Address::ZERO`. /// + /// NOTE: The ERC-1155 acceptance check is not performed in this function. + /// See [`Self::_update_with_acceptance_check`] instead. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -482,22 +478,20 @@ impl Erc1155 { /// /// # Errors /// - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to + /// length of `values`. + /// * [`Error::InsufficientBalance`] - If `value` is greater than the + /// balance of the `from` account. /// - /// NOTE: The ERC-1155 acceptance check is not performed in this function. - /// See [`Self::_update_with_acceptance_check`] instead. /// /// # Events /// - /// Emits a [`TransferSingle`] event if the arrays contain one element, and - /// [`TransferBatch`] otherwise. + /// * [`TransferSingle`] - if the arrays contain one element. + /// * [`TransferBatch`] - if the arrays contain multiple elements. /// /// # Panics /// - /// If updated balance exceeds `U256::MAX`, may happen during `mint` + /// * If updated balance exceeds `U256::MAX`, may happen during `mint` /// operation. fn _update( &mut self, @@ -542,26 +536,26 @@ impl Erc1155 { /// /// # Errors /// - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidArrayLength`] - Returned when length of `ids` is not + /// equal to length of `values`. + /// * [`Error::InsufficientBalance`] - Returned when `value` is greater than + /// the balance of the `from` account. + /// * [`Error::InvalidReceiver`] - Returned + /// when`IERC1155Receiver::on_erc_1155_received` hasn't returned its + /// interface id or returned with error. + /// * [`Error::InvalidReceiver`] - Returned when + /// `IERC1155Receiver::on_erc_1155_batch_received` hasn't returned its + /// interface id or returned with error. /// /// # Events /// - /// Emits a [`TransferSingle`] event if the arrays contain one element, and - /// [`TransferBatch`] otherwise. + /// * [`TransferSingle`] - if the arrays contain one element. + /// * [`TransferBatch`] - if the arrays contain multiple elements. /// /// # Panics /// - /// If updated balance exceeds `U256::MAX`, may happen during `mint` - /// operation. + /// * If updated balance exceeds `U256::MAX`, may happen during `mint` + /// operation. fn _update_with_acceptance_check( &mut self, from: Address, @@ -599,19 +593,18 @@ impl Erc1155 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its + /// interface id or returned with error. /// /// # Events /// - /// Emits a [`TransferSingle`] event. + /// * [`TransferSingle`]. /// /// # Panics /// - /// If updated balance exceeds `U256::MAX`. + /// * If updated balance exceeds `U256::MAX`. pub fn _mint( &mut self, to: Address, @@ -635,25 +628,23 @@ impl Erc1155 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to + /// length of `values`. + /// * [`IERC1155Receiver::on_erc_1155_received`] - If hasn't returned its + /// * [`Error::InvalidReceiver`] - interface id or returned with error. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its + /// interface id or returned with error. /// /// # Events /// - /// Emits a [`TransferSingle`] event if the arrays contain one element, and - /// [`TransferBatch`] otherwise. + /// * [`TransferSingle`] - if the arrays contain one element. + /// * [`TransferBatch`] - if the arrays contain multiple elements. /// /// # Panics /// - /// If updated balance exceeds `U256::MAX`. + /// * If updated balance exceeds `U256::MAX`. pub fn _mint_batch( &mut self, to: Address, @@ -675,18 +666,17 @@ impl Erc1155 { /// /// # Errors /// - /// If `from` is the `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidSender`] - If `from` is the `Address::ZERO`. + /// * [`Error::InsufficientBalance`] - If `value` is greater than the + /// balance of the `from` account. /// /// # Events /// - /// Emits a [`TransferSingle`] event. + /// * [`TransferSingle`]. /// /// # Panics /// - /// Should not panic. + /// * Should not panic. pub fn _burn( &mut self, from: Address, @@ -707,22 +697,21 @@ impl Erc1155 { /// /// # Errors /// - /// If `from` is the `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If any of the `values` is greater than the balance of the respective - /// token from `tokens` of the `from` account, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidSender`] - If `from` is the `Address::ZERO`. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to + /// length of `values`. + /// * [`Error::InsufficientBalance`] - If any of the `values` is greater + /// than the balance of the respective token from `tokens` of the `from` + /// account. /// /// # Events /// - /// Emits a [`TransferSingle`] event if the arrays contain one element, and - /// [`TransferBatch`] otherwise. + /// * [`TransferSingle`] - if the arrays contain one element. + /// * [`TransferBatch`] - if the arrays contain multiple elements. /// /// # Panics /// - /// Should not panic. + /// * Should not panic. pub fn _burn_batch( &mut self, from: Address, @@ -745,12 +734,11 @@ impl Erc1155 { /// /// # Errors /// - /// If `operator` is the `Address::ZERO`, then the error - /// [`Error::InvalidOperator`] is returned. + /// * [`Error::InvalidOperator`] - If `operator` is the `Address::ZERO`. /// /// # Events /// - /// Emits an [`ApprovalForAll`] event. + /// * [`ApprovalForAll`]. fn _set_approval_for_all( &mut self, owner: Address, @@ -795,12 +783,12 @@ impl Erc1155 { /// /// # Errors /// - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its + /// interface id or returned with error. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its + /// interface id or returned with error. fn _check_on_erc1155_received( &mut self, operator: Address, @@ -850,8 +838,8 @@ impl Erc1155 { /// Creates `values` of tokens specified by `ids`, and assigns /// them to `to`. Performs the token acceptance check by /// calling [`IERC1155Receiver::on_erc_1155_received`] or - /// [`IERC1155Receiver::on_erc_1155_batch_received`] on the `to` address - /// if it contains code. + /// [`IERC1155Receiver::on_erc_1155_batch_received`] on the `to` address if + /// it contains code. /// /// # Arguments /// @@ -864,25 +852,24 @@ impl Erc1155 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its + /// interface id or returned with error. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its + /// interface id or returned with error. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to + /// length of `values`. /// /// # Events /// - /// Emits a [`TransferSingle`] event if the arrays contain one element, and - /// [`TransferBatch`] otherwise. + /// * [`TransferSingle`] - if the arrays contain one element. + /// * [`TransferBatch`] - if the array contain multiple elements. /// /// # Panics /// - /// If updated balance exceeds `U256::MAX`. + /// * If updated balance exceeds `U256::MAX`. fn _do_mint( &mut self, to: Address, @@ -916,22 +903,21 @@ impl Erc1155 { /// /// # Errors /// - /// If `from` is the `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If any of the `values` is greater than the balance of the respective - /// token from `tokens` of the `from` account, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidSender`] - If `from` is the `Address::ZERO`. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to + /// length of `values`. + /// * [`Error::InsufficientBalance`] -If any of the `values` is greater than + /// the balance of the respective token from `tokens` of the `from` + /// account. /// /// # Events /// - /// Emits a [`TransferSingle`] event if the arrays contain one element, and - /// [`TransferBatch`] otherwise. + /// * [`TransferSingle`] - if the arrays contain one element. + /// * [`TransferBatch`] - if the arrays contain multiple elements. /// /// # Panics /// - /// Should not panic. + /// * Should not panic. fn _do_burn( &mut self, from: Address, @@ -967,29 +953,27 @@ impl Erc1155 { /// /// # Errors /// - /// If `to` is the `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If `from` is the `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidReceiver`] - If `to` is the `Address::ZERO`. + /// * [`Error::InvalidSender`] - If `from` is the `Address::ZERO`. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to + /// length of `values`. + /// * [`Error::InsufficientBalance`] - If `value` is greater than the + /// balance of the `from` account. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its + /// interface id or returned with error. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its + /// interface id or returned with error. /// /// # Events /// - /// Emits a [`TransferSingle`] event if the arrays contain one element, and - /// [`TransferBatch`] otherwise. + /// * [`TransferSingle`] - if the arrays contain one element. + /// * [`TransferBatch`] - if the arrays contain multiple elements. /// /// # Panics /// - /// If updated balance exceeds `U256::MAX`. + /// * If updated balance exceeds `U256::MAX`. fn do_safe_transfer_from( &mut self, from: Address, @@ -1024,12 +1008,12 @@ impl Erc1155 { /// /// # Errors /// - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. + /// * [`Error::InsufficientBalance`] - If `value` is greater than the + /// balance of the `from` account. /// /// # Panics /// - /// If updated balance exceeds `U256::MAX`. + /// * If updated balance exceeds `U256::MAX`. fn do_update( &mut self, from: Address, @@ -1074,8 +1058,8 @@ impl Erc1155 { /// /// # Errors /// - /// If length of `ids` is not equal to length of `values`, then the error - /// [`Error::InvalidArrayLength`] is returned. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to + /// length of `values`. fn require_equal_arrays_length( ids: &[T], values: &[U], @@ -1098,9 +1082,8 @@ impl Erc1155 { /// /// # Errors /// - /// If the `from` is not the caller (`msg::sender()`), - /// and the caller does not have the right to approve, then the error - /// [`Error::MissingApprovalForAll`] is returned. + /// * [`Error::MissingApprovalForAll`] - If the `from` is not the caller + /// (`msg::sender()`), and the caller does not have the right to approve. fn authorize_transfer(&self, from: Address) -> Result<(), Error> { let sender = msg::sender(); if from != sender && !self.is_approved_for_all(from, sender) { diff --git a/contracts/src/token/erc1155/receiver.rs b/contracts/src/token/erc1155/receiver.rs index b316d067d..8cc4afebe 100644 --- a/contracts/src/token/erc1155/receiver.rs +++ b/contracts/src/token/erc1155/receiver.rs @@ -19,6 +19,8 @@ sol_interface! { /// this must return [`super::SINGLE_TRANSFER_FN_SELECTOR`], /// or its own function selector. /// + /// # Arguments + /// /// * `operator` - The address which initiated the transfer. /// * `from` - The address which previously owned the token. /// * `id` - The ID of the token being transferred. @@ -42,6 +44,8 @@ sol_interface! { /// this must return [`super::BATCH_TRANSFER_FN_SELECTOR`], /// or its own function selector. /// + /// # Arguments + /// /// * `operator` - The address which initiated the batch transfer. /// * `from` - The address which previously owned the token. /// * `ids` - An array containing ids of each token being transferred diff --git a/contracts/src/token/erc20/extensions/burnable.rs b/contracts/src/token/erc20/extensions/burnable.rs index 683531720..5b08157e9 100644 --- a/contracts/src/token/erc20/extensions/burnable.rs +++ b/contracts/src/token/erc20/extensions/burnable.rs @@ -15,7 +15,7 @@ pub trait IErc20Burnable { /// Destroys a `value` amount of tokens from the caller, lowering the total /// supply. /// - /// Relies on the `update` mechanism. + /// NOTE: Relies on the `update` mechanism. /// /// # Arguments /// @@ -23,18 +23,18 @@ pub trait IErc20Burnable { /// /// # Errors /// - /// If the `from` address doesn't have enough tokens, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InsufficientBalance`] - If the `from` address doesn't have + /// enough tokens. /// /// # Events /// - /// Emits a [`super::super::Transfer`] event. + /// * [`erc20::Transfer`]. fn burn(&mut self, value: U256) -> Result<(), Self::Error>; /// Destroys a `value` amount of tokens from `account`, lowering the total /// supply. /// - /// Relies on the `update` mechanism. + /// NOTE: Relies on the `update` mechanism. /// /// # Arguments /// @@ -43,16 +43,15 @@ pub trait IErc20Burnable { /// /// # Errors /// - /// If not enough allowance is available, then the error - /// [`Error::InsufficientAllowance`] is returned. - /// If the `from` address is `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If the `from` address doesn't have enough tokens, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InsufficientAllowance`] - If not enough allowance is + /// available. + /// * [`Error::InvalidSender`] - If the `from` address is `Address::ZERO`. + /// * [`Error::InsufficientBalance`] - If the `from` address doesn't have + /// enough tokens. /// /// # Events /// - /// Emits a [`super::super::Transfer`] event. + /// * [`super::super::Transfer`]. fn burn_from( &mut self, account: Address, diff --git a/contracts/src/token/erc20/extensions/flash_mint.rs b/contracts/src/token/erc20/extensions/flash_mint.rs index 9f1629941..4f7bc5afb 100644 --- a/contracts/src/token/erc20/extensions/flash_mint.rs +++ b/contracts/src/token/erc20/extensions/flash_mint.rs @@ -172,8 +172,7 @@ pub trait IErc3156FlashLender { /// /// # Errors /// - /// * If the token is not supported, then the error - /// [`Error::UnsupportedToken`] is returned. + /// * [`Error::UnsupportedToken`] - If the token is not supported. /// /// # Examples /// @@ -213,22 +212,19 @@ pub trait IErc3156FlashLender { /// /// # Errors /// - /// * If the `value` is greater than the value returned by - /// [`IErc3156FlashLender::max_flash_loan`], then the error - /// [`Error::ExceededMaxLoan`] is returned. - /// * If `token` is not supported, then the error - /// [`Error::UnsupportedToken`] is returned. - /// * If the `token` address is not a contract, then the error - /// [`Error::InvalidReceiver`] is returned. - /// * If the contract fails to execute the call, then the error - /// [`Error::InvalidReceiver`] is returned. - /// * If the receiver does not return [`BORROWER_CALLBACK_VALUE`], then the - /// error [`Error::InvalidReceiver`] is returned. + /// * [`Error::ExceededMaxLoan`] - If the `value` is greater than the value + /// returned by [`IErc3156FlashLender::max_flash_loan`]. + /// * [`Error::UnsupportedToken`] - If `token` is not supported. + /// * [`Error::InvalidReceiver`] - If the `token` address is not a contract. + /// * [`Error::InvalidReceiver`] - If the contract fails to execute the + /// call. + /// * [`Error::InvalidReceiver`] - If the receiver does not return + /// [`BORROWER_CALLBACK_VALUE`]. /// /// # Events /// - /// * Emits an [`erc20::Transfer`] event. - /// * Emits an [`erc20::Approval`] event. + /// * [`erc20::Transfer`]. + /// * [`erc20::Approval`]. /// /// # Panics /// diff --git a/contracts/src/token/erc20/extensions/metadata.rs b/contracts/src/token/erc20/extensions/metadata.rs index 3e7d0db99..e5ac874df 100644 --- a/contracts/src/token/erc20/extensions/metadata.rs +++ b/contracts/src/token/erc20/extensions/metadata.rs @@ -52,14 +52,14 @@ pub trait IErc20Metadata { /// between Ether and Wei. This is the default value returned by this /// function ([`DEFAULT_DECIMALS`]), unless it's overridden. /// - /// # Arguments - /// - /// * `&self` - Read access to the contract's state. - /// /// NOTE: This information is only used for *display* purposes: in /// no way it affects any of the arithmetic of the contract, including /// [`super::super::IErc20::balance_of`] and /// [`super::super::IErc20::transfer`]. + /// + /// # Arguments + /// + /// * `&self` - Read access to the contract's state. fn decimals(&self) -> u8; } diff --git a/contracts/src/token/erc20/extensions/permit.rs b/contracts/src/token/erc20/extensions/permit.rs index d46dd8f4d..cddc7f63f 100644 --- a/contracts/src/token/erc20/extensions/permit.rs +++ b/contracts/src/token/erc20/extensions/permit.rs @@ -117,6 +117,14 @@ impl Erc20Permit { /// Sets `value` as the allowance of `spender` over `owner`'s tokens, /// given `owner`'s signed approval. /// + /// # Requirements + /// + /// * `spender` cannot be the ``Address::ZERO``. + /// * `deadline` must be a timestamp in the future. + /// * `v`, `r` and `s` must be a valid secp256k1 signature from `owner` over + /// the EIP712-formatted function arguments. + /// * The signature must use `owner`'s current nonce. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. given address. @@ -131,28 +139,19 @@ impl Erc20Permit { /// /// # Errors /// - /// If the `deadline` param is from the past, than the error - /// [`ERC2612ExpiredSignature`] is returned. - /// If signer is not an `owner`, than the error - /// [`ERC2612InvalidSigner`] is returned. - /// * If the `s` value is grater than [`ecdsa::SIGNATURE_S_UPPER_BOUND`], - /// then the error [`ecdsa::Error::InvalidSignatureS`] is returned. - /// * If the recovered address is `Address::ZERO`, then the error - /// [`ecdsa::Error::InvalidSignature`] is returned. - /// If the `spender` address is `Address::ZERO`, then the error - /// [`erc20::Error::InvalidSpender`] is returned. + /// * [`ERC2612ExpiredSignature`] - If the `deadline` param is from the + /// past. + /// * [`ERC2612InvalidSigner`] - If signer is not an `owner`. + /// * [`ecdsa::Error::InvalidSignatureS`] - If the `s` value is grater than + /// [`ecdsa::SIGNATURE_S_UPPER_BOUND`]. + /// * [`ecdsa::Error::InvalidSignature`] - If the recovered address is + /// `Address::ZERO`. + /// * [`erc20::Error::InvalidSpender`] - If the `spender` address is + /// `Address::ZERO`. /// /// # Events /// - /// Emits an [`crate::token::erc20::Approval`] event. - /// - /// # Requirements - /// - /// * `spender` cannot be the ``Address::ZERO``. - /// * `deadline` must be a timestamp in the future. - /// * `v`, `r` and `s` must be a valid secp256k1 signature from `owner` - /// over the EIP712-formatted function arguments. - /// * the signature must use `owner`'s current nonce. + /// * [`erc20::Approval`]. #[allow(clippy::too_many_arguments)] pub fn permit( &mut self, @@ -221,14 +220,14 @@ impl Erc20Permit { /// /// # Errors /// - /// * If the `to` address is `Address::ZERO`, then the error - /// [`crate::token::erc20::Error::InvalidReceiver`] is returned. - /// * If the caller doesn't have a balance of at least `value`, then the - /// error [`crate::token::erc20::Error::InsufficientBalance`] is returned. + /// * [`crate::token::erc20::Error::InvalidReceiver`] - If the `to` address + /// is `Address::ZERO`. + /// * [`crate::token::erc20::Error::InsufficientBalance`] - If the caller + /// doesn't have a balance of at least `value`. /// /// # Events /// - /// Emits a [`crate::token::erc20::Transfer`] event. + /// * [`crate::token::erc20::Transfer`]. pub fn transfer( &mut self, to: Address, @@ -273,12 +272,12 @@ impl Erc20Permit { /// /// # Errors /// - /// If the `spender` address is `Address::ZERO`, then the error - /// [`crate::token::erc20::Error::InvalidSpender`] is returned. + /// [`crate::token::erc20::Error::InvalidSpender`] - If the `spender` + /// address is `Address::ZERO`. /// /// # Events /// - /// Emits an [`crate::token::erc20::Approval`] event. + /// * [`crate::token::erc20::Approval`]. pub fn approve( &mut self, spender: Address, @@ -306,16 +305,16 @@ impl Erc20Permit { /// /// # Errors /// - /// * If the `from` address is `Address::ZERO`, then the error - /// [`crate::token::erc20::Error::InvalidSender`] is returned. - /// * If the `to` address is `Address::ZERO`, then the error - /// [`crate::token::erc20::Error::InvalidReceiver`] is returned. - /// * If not enough allowance is available, then the error - /// [`crate::token::erc20::Error::InsufficientAllowance`] is returned. + /// * [`crate::token::erc20::Error::InvalidSender`] - If the `from` address + /// is `Address::ZERO`. + /// * [`crate::token::erc20::Error::InvalidReceiver`] - If the `to` address + /// is `Address::ZERO`. + /// * [`crate::token::erc20::Error::InsufficientAllowance`] - If not enough + /// allowance is available. /// /// # Events /// - /// Emits a [`crate::token::erc20::Transfer`] event. + /// * [`erc20::Transfer`]. pub fn transfer_from( &mut self, from: Address, diff --git a/contracts/src/token/erc20/mod.rs b/contracts/src/token/erc20/mod.rs index cf20cfa7d..3dae94391 100644 --- a/contracts/src/token/erc20/mod.rs +++ b/contracts/src/token/erc20/mod.rs @@ -171,14 +171,13 @@ pub trait IErc20 { /// /// # Errors /// - /// * If the `to` address is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// * If the caller doesn't have a balance of at least `value`, then the - /// error [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidReceiver`] - If the `to` address is `Address::ZERO`. + /// * [`Error::InsufficientBalance`] - If the caller doesn't have a balance + /// of at least `value`. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. fn transfer( &mut self, to: Address, @@ -218,12 +217,12 @@ pub trait IErc20 { /// /// # Errors /// - /// If the `spender` address is `Address::ZERO`, then the error - /// [`Error::InvalidSpender`] is returned. + /// * [`Error::InvalidSpender`] - If the `spender` address is + /// `Address::ZERO`. /// /// # Events /// - /// Emits an [`Approval`] event. + /// * [`Approval`]. fn approve( &mut self, spender: Address, @@ -249,16 +248,14 @@ pub trait IErc20 { /// /// # Errors /// - /// * If the `from` address is `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// * If the `to` address is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// * If not enough allowance is available, then the error - /// [`Error::InsufficientAllowance`] is returned. + /// * [`Error::InvalidSender`] - If the `from` address is `Address::ZERO`. + /// * [`Error::InvalidReceiver`] - If the `to` address is `Address::ZERO`. + /// * [`Error::InsufficientAllowance`] - If not enough allowance is + /// available. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. fn transfer_from( &mut self, from: Address, @@ -336,12 +333,12 @@ impl Erc20 { /// /// # Errors /// - /// If the `spender` address is `Address::ZERO`, then the error - /// [`Error::InvalidSpender`] is returned. + /// * [`Error::InvalidSpender`] - If the `spender` address is + /// `Address::ZERO`. /// /// # Events /// - /// Emits an [`Approval`] event. + /// * [`Approval`]. fn _approve( &mut self, owner: Address, @@ -379,16 +376,14 @@ impl Erc20 { /// /// # Errors /// - /// * If the `from` address is `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// * If the `to` address is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// * If the `from` address doesn't have enough tokens, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidSender`] - If the `from` address is `Address::ZERO`. + /// * [`Error::InvalidReceiver`] - If the `to` address is `Address::ZERO`. + /// * [`Error::InsufficientBalance`] - If the `from` address doesn't have + /// enough tokens. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. fn _transfer( &mut self, from: Address, @@ -416,18 +411,18 @@ impl Erc20 { /// /// Relies on the `_update` mechanism. /// - /// # Panics - /// - /// If `_total_supply` exceeds `U256::MAX`. - /// /// # Errors /// - /// If the `account` address is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidReceiver`] - If the `account` address is + /// `Address::ZERO`. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. + /// + /// # Panics + /// + /// * If `_total_supply` exceeds `U256::MAX`. pub fn _mint( &mut self, account: Address, @@ -453,19 +448,19 @@ impl Erc20 { /// * `to` - Recipient's address. /// * `value` - Amount to be transferred. /// - /// # Panics - /// - /// If `_total_supply` exceeds `U256::MAX`. It may happen during `mint` - /// operation. - /// /// # Errors /// - /// If the `from` address doesn't have enough tokens, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InsufficientBalance`] - If the `from` address doesn't have + /// enough tokens. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. + /// + /// # Panics + /// + /// * If `_total_supply` exceeds `U256::MAX`. It may happen during `mint` + /// operation. pub fn _update( &mut self, from: Address, @@ -524,14 +519,13 @@ impl Erc20 { /// /// # Errors /// - /// * If the `from` address is `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// * If the `from` address doesn't have enough tokens, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidSender`] - If the `from` address is `Address::ZERO`. + /// * [`Error::InsufficientBalance`] - If the `from` address doesn't have + /// enough tokens. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _burn( &mut self, account: Address, @@ -558,12 +552,12 @@ impl Erc20 { /// /// # Errors /// - /// If not enough allowance is available, then the error - /// [`Error::InsufficientAllowance`] is returned. + /// * [`Error::InsufficientAllowance`] - If not enough allowance is + /// available. /// /// # Events /// - /// Emits an [`Approval`] event. + /// * [`Approval`]. pub fn _spend_allowance( &mut self, owner: Address, diff --git a/contracts/src/token/erc20/utils/safe_erc20.rs b/contracts/src/token/erc20/utils/safe_erc20.rs index 7066a1b8a..22aa3b379 100644 --- a/contracts/src/token/erc20/utils/safe_erc20.rs +++ b/contracts/src/token/erc20/utils/safe_erc20.rs @@ -112,12 +112,12 @@ pub trait ISafeErc20 { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the contract fails to execute the call, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the call returns value that is not `true`, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the `token` address is not a + /// contract. + /// * [`Error::SafeErc20FailedOperation`] - If the contract fails to + /// execute the call. + /// * [`Error::SafeErc20FailedOperation`] - If the call returns value that + /// is not `true`. fn safe_transfer( &mut self, token: Address, @@ -139,12 +139,12 @@ pub trait ISafeErc20 { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the contract fails to execute the call, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the call returns value that is not `true`, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the `token` address is not a + /// contract. + /// * [`Error::SafeErc20FailedOperation`] - If the contract fails to + /// execute the call. + /// * [`Error::SafeErc20FailedOperation`] - If the call returns value that + /// is not `true`. fn safe_transfer_from( &mut self, token: Address, @@ -166,16 +166,16 @@ pub trait ISafeErc20 { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the contract fails to execute the call, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the call returns value that is not `true`, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the `token` address is not a + /// contract. + /// * [`Error::SafeErc20FailedOperation`] - If the contract fails to execute + /// the call. + /// * [`Error::SafeErc20FailedOperation`] - If the call returns value that + /// is not `true`. /// /// # Panics /// - /// If increased allowance exceeds `U256::MAX`. + /// * If increased allowance exceeds `U256::MAX`. fn safe_increase_allowance( &mut self, token: Address, @@ -196,14 +196,14 @@ pub trait ISafeErc20 { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the current allowance is less than `requested_decrease`, then the - /// error [`Error::SafeErc20FailedDecreaseAllowance`] is returned. - /// If the contract fails to execute the call, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the call returns value that is not `true`, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the `token` address is not a + /// contract. + /// * [`Error::SafeErc20FailedDecreaseAllowance`] - If the current allowance + /// is less than `requested_decrease`. + /// * [`Error::SafeErc20FailedOperation`] - If the contract fails to execute + /// the call. + /// * [`Error::SafeErc20FailedOperation`] - If the call returns value that + /// is not `true`. fn safe_decrease_allowance( &mut self, token: Address, @@ -225,12 +225,12 @@ pub trait ISafeErc20 { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the contract fails to execute the call, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the call returns value that is not `true`, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the `token` address is not a + /// contract. + /// * [`Error::SafeErc20FailedOperation`] - If the contract fails to execute + /// the call. + /// * [`Error::SafeErc20FailedOperation`] - If the call returns value that + /// is not `true`. fn force_approve( &mut self, token: Address, @@ -337,12 +337,12 @@ impl SafeErc20 { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the contract fails to execute the call, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the call returns value that is not `true`, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the `token` address is not a + /// contract. + /// * [`Error::SafeErc20FailedOperation`] - If the contract fails to execute + /// the call. + /// * [`Error::SafeErc20FailedOperation`] - If the call returns value that + /// is not `true`. fn call_optional_return( token: Address, call: &impl SolCall, @@ -370,10 +370,10 @@ impl SafeErc20 { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the contract fails to read `spender`'s allowance, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the `token` address is not a + /// contract. + /// * [`Error::SafeErc20FailedOperation`] - If the contract fails to read + /// `spender`'s allowance. fn allowance(token: Address, spender: Address) -> Result { if !Address::has_code(&token) { return Err(SafeErc20FailedOperation { token }.into()); diff --git a/contracts/src/token/erc721/extensions/burnable.rs b/contracts/src/token/erc721/extensions/burnable.rs index f06a90535..15b5e5cd7 100644 --- a/contracts/src/token/erc721/extensions/burnable.rs +++ b/contracts/src/token/erc721/extensions/burnable.rs @@ -15,25 +15,24 @@ pub trait IErc721Burnable { /// The approval is cleared when the token is burned. Relies on the `_burn` /// mechanism. /// + /// # Requirements: + /// + /// * `token_id` must exist. + /// * The caller must own `token_id` or be an approved operator. + /// /// # Arguments /// /// * `value` - Amount to be burnt. /// /// # Errors /// - /// If token does not exist, then the error [`Error::NonexistentToken`] is - /// returned. - /// If the caller does not have the right to approve, then the error - /// [`Error::InsufficientApproval`] is returned. - /// - /// # Requirements: - /// - /// * `token_id` must exist. - /// * The caller must own `token_id` or be an approved operator. + /// * [`Error::NonexistentToken`] - If token does not exist. + /// * [`Error::InsufficientApproval`] - If the caller does not have the + /// right to approve. /// /// # Events /// - /// Emits a [`super::super::Transfer`] event. + /// * [`erc721::Transfer`]. fn burn(&mut self, token_id: U256) -> Result<(), Self::Error>; } diff --git a/contracts/src/token/erc721/extensions/consecutive.rs b/contracts/src/token/erc721/extensions/consecutive.rs index 8211493f0..37ea27a6a 100644 --- a/contracts/src/token/erc721/extensions/consecutive.rs +++ b/contracts/src/token/erc721/extensions/consecutive.rs @@ -278,21 +278,20 @@ impl Erc721Consecutive { /// `batch_size` is 0, returns the number of consecutive ids minted so /// far. /// - /// Requirements: + /// CAUTION: Does not emit a [`Transfer`] event. This is ERC-721 compliant + /// as long as it is done inside of the constructor, which is enforced by + /// this function. + /// + /// CAUTION: Does not invoke + /// [`erc721::IERC721Receiver::on_erc_721_received`] on the receiver. + /// + /// # Requirements /// /// * `batch_size` must not be greater than /// [`Erc721Consecutive::_max_batch_size`]. /// * The function is called in the constructor of the contract (directly or /// indirectly). /// - /// CAUTION: Does not emit a [Transfer] event. - /// This is ERC-721 compliant as - /// long as it is done inside of the constructor, which is enforced by - /// this function. - /// - /// CAUTION: Does not invoke - /// [`erc721::IERC721Receiver::on_erc_721_received`] on the receiver. - /// /// # Arguments /// /// * `&self` - Write access to the contract's state. @@ -300,14 +299,13 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`erc721::Error::InvalidReceiver`] is returned. - /// If `batch_size` exceeds [`Erc721Consecutive::_max_batch_size`], - /// then the error [`Error::ExceededMaxBatchMint`] is returned. + /// * [`erc721::Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`Error::ExceededMaxBatchMint`] - If `batch_size` exceeds + /// [`Erc721Consecutive::_max_batch_size`]. /// /// # Events /// - /// Emits a [`ConsecutiveTransfer`] event. + /// * [`ConsecutiveTransfer`]. #[cfg(all(test, feature = "std"))] fn _mint_consecutive( &mut self, @@ -367,15 +365,15 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If token does not exist and `auth` is not `Address::ZERO`, then the - /// error [`erc721::Error::NonexistentToken`] is returned. - /// If `auth` is not `Address::ZERO` and `auth` does not have a right to - /// approve this token, then the error - /// [`erc721::Error::InsufficientApproval`] is returned. + /// * [`erc721::Error::NonexistentToken`] - If token does not exist and + /// `auth` is not `Address::ZERO`. + /// * [`erc721::Error::InsufficientApproval`] - If `auth` is not + /// `Address::ZERO` and `auth` does not have a right to approve this + /// token. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _update( &mut self, to: Address, @@ -414,6 +412,10 @@ impl Erc721Consecutive { /// Used to offset the first token id in /// [`Erc721Consecutive::_next_consecutive_id`]. + /// + /// # Arguments + /// + /// * `&self` - Read access to the contract's state. fn _first_consecutive_id(&self) -> U96 { self._first_consecutive_id.get() } @@ -422,6 +424,10 @@ impl Erc721Consecutive { /// This is designed to limit stress on off-chain indexing services that /// have to record one entry per token, and have protections against /// "unreasonably large" batches of tokens. + /// + /// # Arguments + /// + /// * `&self` - Read access to the contract's state. fn _max_batch_size(&self) -> U96 { self._max_batch_size.get() } @@ -481,6 +487,11 @@ impl Erc721Consecutive { /// WARNING: Usage of this method is discouraged, use [`Self::_safe_mint`] /// whenever possible. /// + /// # Requirements + /// + /// * `token_id` must not exist. + /// * `to` cannot be `Address::ZERO`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -489,19 +500,12 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If `token_id` already exists, then the error - /// [`erc721::Error::InvalidSender`] is returned. - /// If `to` is `Address::ZERO`, then the error - /// [`erc721::Error::InvalidReceiver`] is returned. - /// - /// # Requirements: - /// - /// * `token_id` must not exist. - /// * `to` cannot be `Address::ZERO`. + /// * [`erc721::Error::InvalidSender`] - If `token_id` already exists. + /// * [`erc721::Error::InvalidReceiver`] - If `to` is `Address::ZERO`. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _mint(&mut self, to: Address, token_id: U256) -> Result<(), Error> { if to.is_zero() { return Err(erc721::Error::InvalidReceiver( @@ -520,12 +524,19 @@ impl Erc721Consecutive { Ok(()) } - /// Mints `token_id`, transfers it to `to`, - /// and checks for `to`'s acceptance. + /// Mints `token_id`, transfers it to `to`, and checks for `to`'s + /// acceptance. /// /// An additional `data` parameter is forwarded to /// [`erc721::IERC721Receiver::on_erc_721_received`] to contract recipients. /// + /// # Requirements + /// + /// * `token_id` must not exist. + /// * If `to` refers to a smart contract, it must implement + /// [`erc721::IERC721Receiver::on_erc_721_received`], which is called upon + /// a `safe_transfer`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -536,24 +547,15 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If `token_id` already exists, then the error - /// [`erc721::Error::InvalidSender`] is returned. - /// If `to` is `Address::ZERO`, then the error - /// [`erc721::Error::InvalidReceiver`] is returned. - /// If [`erc721::IERC721Receiver::on_erc_721_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`erc721::Error::InvalidReceiver`] is returned. - /// - /// # Requirements: - /// - /// * `token_id` must not exist. - /// * If `to` refers to a smart contract, it must implement - /// [`erc721::IERC721Receiver::on_erc_721_received`], which is called upon - /// a `safe_transfer`. + /// * [`erc721::Error::InvalidSender`] - If `token_id` already exists. + /// * [`erc721::Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`erc721::Error::InvalidReceiver`] - If + /// [`erc721::IERC721Receiver::on_erc_721_received`] hasn't returned its + /// interface id or returned with error. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _safe_mint( &mut self, to: Address, @@ -576,6 +578,10 @@ impl Erc721Consecutive { /// internal function that does not check if the sender is authorized /// to operate on the token. /// + /// # Requirements + /// + /// * `token_id` must exist. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -583,16 +589,11 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If token does not exist, then the error - /// [`erc721::Error::NonexistentToken`] is returned. - /// - /// # Requirements: - /// - /// * `token_id` must exist. + /// * [`erc721::Error::NonexistentToken`] - If token does not exist. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _burn(&mut self, token_id: U256) -> Result<(), Error> { let previous_owner = self._update(Address::ZERO, token_id, Address::ZERO)?; @@ -610,6 +611,11 @@ impl Erc721Consecutive { /// As opposed to [`Self::transfer_from`], this imposes no restrictions on /// `msg::sender`. /// + /// # Requirements + /// + /// * `to` cannot be `Address::ZERO`. + /// * The `token_id` token must be owned by `from`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -619,21 +625,14 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`erc721::Error::InvalidReceiver`] is returned. - /// If `token_id` does not exist, then the error - /// [`erc721::Error::NonexistentToken`] is returned. - /// If the previous owner is not `from`, then the error - /// [`erc721::Error::IncorrectOwner`] is returned. - /// - /// # Requirements: - /// - /// * `to` cannot be `Address::ZERO`. - /// * The `token_id` token must be owned by `from`. + /// * [`erc721::Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`erc721::Error::NonexistentToken`] - If `token_id` does not exist. + /// * [`erc721::Error::IncorrectOwner`] - If the previous owner is not + /// `from`. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _transfer( &mut self, from: Address, @@ -676,6 +675,16 @@ impl Erc721Consecutive { /// receiver, and can be used to e.g. implement alternative mechanisms /// to perform token transfer, such as signature-based. /// + /// + /// # Requirements + /// + /// * The `token_id` token must exist and be owned by `from`. + /// * `to` cannot be `Address::ZERO`. + /// * `from` cannot be `Address::ZERO`. + /// * If `to` refers to a smart contract, it must implement + /// [`erc721::IERC721Receiver::on_erc_721_received`], which is called upon + /// a `safe_transfer`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -687,25 +696,14 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`erc721::Error::InvalidReceiver`] is returned. - /// If `token_id` does not exist, then the error - /// [`erc721::Error::NonexistentToken`] is returned. - /// If the previous owner is not `from`, then the error - /// [`erc721::Error::IncorrectOwner`] is returned. - /// - /// # Requirements: - /// - /// * The `token_id` token must exist and be owned by `from`. - /// * `to` cannot be `Address::ZERO`. - /// * `from` cannot be `Address::ZERO`. - /// * If `to` refers to a smart contract, it must implement - /// [`erc721::IERC721Receiver::on_erc_721_received`], which is called upon - /// a `safe_transfer`. + /// * [`erc721::Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`erc721::Error::NonexistentToken`] - If `token_id` does not exist. + /// * [`erc721::Error::IncorrectOwner`] - If the previous owner is not + /// `from`. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _safe_transfer( &mut self, from: Address, @@ -740,14 +738,13 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`erc721::Error::NonexistentToken`] is returned. - /// If `auth` does not have a right to approve this token, then the error - /// [`erc721::Error::InvalidApprover`] is returned. + /// * [`erc721::Error::NonexistentToken`] - If the token does not exist. + /// * [`erc721::Error::InvalidApprover`] - If `auth` does not have a right + /// to approve this token. /// /// # Events /// - /// Emits an [`Approval`] event. + /// * [`Approval`]. pub fn _approve( &mut self, to: Address, @@ -786,15 +783,14 @@ impl Erc721Consecutive { /// Overrides to ownership logic should be done to /// [`Self::_owner_of`]. /// - /// # Errors - /// - /// If token does not exist, then the error - /// [`erc721::Error::NonexistentToken`] is returned. - /// /// # Arguments /// /// * `&self` - Read access to the contract's state. /// * `token_id` - Token id as a number. + /// + /// # Errors + /// + /// * [`erc721::Error::NonexistentToken`] - If token does not exist. pub fn _require_owned(&self, token_id: U256) -> Result { let owner = self._owner_of(token_id); if owner.is_zero() { diff --git a/contracts/src/token/erc721/extensions/enumerable.rs b/contracts/src/token/erc721/extensions/enumerable.rs index 34e3dc901..16d5481da 100644 --- a/contracts/src/token/erc721/extensions/enumerable.rs +++ b/contracts/src/token/erc721/extensions/enumerable.rs @@ -94,11 +94,13 @@ pub trait IErc721Enumerable { /// # Arguments /// /// * `&self` - Read access to the contract's state. + /// * `owner` - Address of token's owner. + /// * `index` - Index of the token at `owner`'s tokens list. /// /// # Errors /// - /// * If an `owner`'s token query is out of bounds for `index`, then the - /// error [`Error::OutOfBoundsIndex`] is returned. + /// * [`Error::OutOfBoundsIndex`] - If an `owner`'s token query is out of + /// bounds for `index`. fn token_of_owner_by_index( &self, owner: Address, @@ -121,11 +123,12 @@ pub trait IErc721Enumerable { /// # Arguments /// /// * `&self` - Read access to the contract's state. + /// * `index` - Index of the token in all tokens list. /// /// # Errors /// - /// * If an `owner`'s token query is out of bounds for `index`, - /// then the error [`Error::OutOfBoundsIndex`] is returned. + /// * [`Error::OutOfBoundsIndex`] - If an `owner`'s token query is out of + /// bounds for `index`. fn token_by_index(&self, index: U256) -> Result; } @@ -180,8 +183,7 @@ impl Erc721Enumerable { /// /// # Errors /// - /// If owner address is `Address::ZERO`, then the error - /// [`crate::token::erc721::Error::InvalidOwner`] is returned. + /// * [`erc721::Error::InvalidOwner`] - If owner address is `Address::ZERO`. pub fn _add_token_to_owner_enumeration( &mut self, to: Address, @@ -231,8 +233,8 @@ impl Erc721Enumerable { /// /// # Errors /// - /// If owner address is `Address::ZERO`, then the error - /// [`crate::token::erc721::Error::InvalidOwner`] is returned. + /// * [`crate::token::erc721::Error::InvalidOwner`] - If owner address is + /// `Address::ZERO`. pub fn _remove_token_from_owner_enumeration( &mut self, from: Address, @@ -326,8 +328,8 @@ impl Erc721Enumerable { /// /// # Errors /// - /// * If an `amount` is greater than `0`, then the error - /// [`Error::EnumerableForbiddenBatchMint`] is returned. + /// * [`Error::EnumerableForbiddenBatchMint`] - If an `amount` is greater + /// than `0`. pub fn _check_increase_balance(amount: u128) -> Result<(), Error> { if amount > 0 { Err(ERC721EnumerableForbiddenBatchMint {}.into()) diff --git a/contracts/src/token/erc721/extensions/metadata.rs b/contracts/src/token/erc721/extensions/metadata.rs index cc417c674..420d8e9d0 100644 --- a/contracts/src/token/erc721/extensions/metadata.rs +++ b/contracts/src/token/erc721/extensions/metadata.rs @@ -84,27 +84,32 @@ impl Erc721Metadata { /// Returns the Uniform Resource Identifier (URI) for `token_id` token. /// + /// NOTE: To expose this function in your contract's ABI, implement it as + /// shown in the Examples section below, accepting only the `token_id` + /// parameter. The `erc721` reference should come from your contract's + /// state. The implementation should use `#[selector(name = "tokenURI")]` to + /// match Solidity's camelCase naming convention and it should forward the + /// call to your internal storage instance along with the `erc721` + /// reference. + /// /// # Arguments /// /// * `&self` - Read access to the contract's state. - /// * `token_id` - Id of a token. + /// * `token_id` - ID of a token. /// * `erc721` - Read access to a contract providing [`IErc721`] interface. /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// - /// NOTE: In order to have [`Erc721Metadata::token_uri`] exposed in ABI, - /// you need to do this manually. + /// * [`Error::NonexistentToken`] - If the token does not exist. /// - /// # Examples + /// # Example /// /// ```rust,ignore /// #[selector(name = "tokenURI")] /// pub fn token_uri(&self, token_id: U256) -> Result> { /// Ok(self.metadata.token_uri(token_id, &self.erc721)?) /// } + /// ``` pub fn token_uri( &self, token_id: U256, diff --git a/contracts/src/token/erc721/extensions/uri_storage.rs b/contracts/src/token/erc721/extensions/uri_storage.rs index 96fdc33a4..fdf6390c4 100644 --- a/contracts/src/token/erc721/extensions/uri_storage.rs +++ b/contracts/src/token/erc721/extensions/uri_storage.rs @@ -42,7 +42,7 @@ pub struct Erc721UriStorage { } impl Erc721UriStorage { - /// Sets `token_uri` as the tokenURI of `token_id`. + /// Sets `token_uri` as the token URI of `token_id`. /// /// # Arguments /// @@ -51,7 +51,8 @@ impl Erc721UriStorage { /// * `token_uri` - URI for the token. /// /// # Events - /// Emits a [`MetadataUpdate`] event. + /// + /// * [`MetadataUpdate`]. pub fn _set_token_uri(&mut self, token_id: U256, token_uri: String) { self._token_uris.setter(token_id).set_str(token_uri); evm::log(MetadataUpdate { token_id }); @@ -59,6 +60,14 @@ impl Erc721UriStorage { /// Returns the Uniform Resource Identifier (URI) for `token_id` token. /// + /// NOTE: To expose this function in your contract's ABI, implement it as + /// shown in the Examples section below, accepting only the `token_id` + /// parameter. Both the `erc721` and `metadata` references should come from + /// your contract's state. The implementation should use + /// `#[selector(name = "tokenURI")]` to match Solidity's camelCase naming + /// convention and it should forward the call to your internal storage + /// instance along with both references. + /// /// # Arguments /// /// * `&self` - Read access to the contract's state. @@ -68,11 +77,7 @@ impl Erc721UriStorage { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// - /// NOTE: In order to have [`Erc721UriStorage::token_uri`] exposed in ABI, - /// you need to do this manually. + /// * [`Error::NonexistentToken`] - If the token does not exist. /// /// # Examples /// diff --git a/contracts/src/token/erc721/mod.rs b/contracts/src/token/erc721/mod.rs index 21a9b0c4f..6b795e47a 100644 --- a/contracts/src/token/erc721/mod.rs +++ b/contracts/src/token/erc721/mod.rs @@ -212,12 +212,15 @@ pub trait IErc721 { /// /// # Errors /// - /// If owner address is `Address::ZERO`, then the error - /// [`Error::InvalidOwner`] is returned. + /// * [`Error::InvalidOwner`] - If owner address is `Address::ZERO`. fn balance_of(&self, owner: Address) -> Result; /// Returns the owner of the `token_id` token. /// + /// # Requirements + /// + /// * `token_id` must exist. + /// /// # Arguments /// /// * `&self` - Read access to the contract's state. @@ -225,18 +228,24 @@ pub trait IErc721 { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// - /// # Requirements - /// - /// * `token_id` must exist. + /// * [`Error::NonexistentToken`] - If the token does not exist. fn owner_of(&self, token_id: U256) -> Result; /// Safely transfers `token_id` token from `from` to `to`, checking first /// that contract recipients are aware of the [`Erc721`] protocol to /// prevent tokens from being forever locked. /// + /// # Requirements + /// + /// * `from` cannot be the `Address::ZERO`. + /// * `to` cannot be the `Address::ZERO`. + /// * The `token_id` token must exist and be owned by `from`. + /// * If the caller is not `from`, it must have been allowed to move this + /// token by either [`Self::approve`] or [`Self::set_approval_for_all`]. + /// * If `to` refers to a smart contract, it must implement + /// [`IERC721Receiver::on_erc_721_received`], which is called upon a + /// `safe_transfer`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -246,32 +255,18 @@ pub trait IErc721 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If the previous owner is not `from`, then the error - /// [`Error::IncorrectOwner`] is returned. - /// If the caller does not have the right to approve, then the error - /// [`Error::InsufficientApproval`] is returned. - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// If [`IERC721Receiver::on_erc_721_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// - /// # Requirements - /// - /// * `from` cannot be the zero address. - /// * `to` cannot be the zero address. - /// * The `token_id` token must exist and be owned by `from`. - /// * If the caller is not `from`, it must have been allowed to move this - /// token by either [`Self::approve`] or [`Self::set_approval_for_all`]. - /// * If `to` refers to a smart contract, it must implement - /// [`IERC721Receiver::on_erc_721_received`], which is called upon a - /// `safe_transfer`. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`Error::IncorrectOwner`] - If the previous owner is not `from`. + /// * [`Error::InsufficientApproval`] - If the caller does not have the + /// right to approve. + /// * [`Error::NonexistentToken`] - If the token does not exist. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC721Receiver::on_erc_721_received`] hasn't returned its + /// interface id or returned with error. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. fn safe_transfer_from( &mut self, from: Address, @@ -281,6 +276,17 @@ pub trait IErc721 { /// Safely transfers `token_id` token from `from` to `to`. /// + /// # Requirements + /// + /// * `from` cannot be the `Address::ZERO`. + /// * `to` cannot be the `Address::ZERO`. + /// * The `token_id` token must exist and be owned by `from`. + /// * If the caller is not `from`, it must be approved to move this token by + /// either [`Erc721::_approve`] or [`Self::set_approval_for_all`]. + /// * If `to` refers to a smart contract, it must implement + /// [`IERC721Receiver::on_erc_721_received`], which is called upon a + /// `safe_transfer`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -292,32 +298,18 @@ pub trait IErc721 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If the previous owner is not `from`, then the error - /// [`Error::IncorrectOwner`] is returned. - /// If the caller does not have the right to approve, then the error - /// [`Error::InsufficientApproval`] is returned. - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// If [`IERC721Receiver::on_erc_721_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// - /// # Requirements - /// - /// * `from` cannot be the zero address. - /// * `to` cannot be the zero address. - /// * The `token_id` token must exist and be owned by `from`. - /// * If the caller is not `from`, it must be approved to move this token by - /// either [`Erc721::_approve`] or [`Self::set_approval_for_all`]. - /// * If `to` refers to a smart contract, it must implement - /// [`IERC721Receiver::on_erc_721_received`], which is called upon a - /// `safe_transfer`. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`Error::IncorrectOwner`] - If the previous owner is not `from`. + /// * [`Error::InsufficientApproval`] - If the caller does not have the + /// right to approve. + /// * [`Error::NonexistentToken`] - If the token does not exist. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC721Receiver::on_erc_721_received`] hasn't returned its + /// interface id or returned with error. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. #[selector(name = "safeTransferFrom")] fn safe_transfer_from_with_data( &mut self, @@ -335,6 +327,14 @@ pub trait IErc721 { /// though the caller must understand this adds an external call which /// potentially creates a reentrancy vulnerability, unless it is disabled. /// + /// # Requirements + /// + /// * `from` cannot be the `Address::ZERO`. + /// * `to` cannot be the `Address::ZERO`. + /// * The `token_id` token must be owned by `from`. + /// * If the caller is not `from`, it must be approved to move this token by + /// either [`Self::approve`] or [`Self::set_approval_for_all`]. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -344,26 +344,15 @@ pub trait IErc721 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If the previous owner is not `from`, then the error - /// [`Error::IncorrectOwner`] is returned. - /// If the caller does not have the right to approve, then the error - /// [`Error::InsufficientApproval`] is returned. - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// - /// # Requirements: - /// - /// * `from` cannot be the zero address. - /// * `to` cannot be the zero address. - /// * The `token_id` token must be owned by `from`. - /// * If the caller is not `from`, it must be approved to move this token by - /// either [`Self::approve`] or [`Self::set_approval_for_all`]. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`Error::IncorrectOwner`] - If the previous owner is not `from`. + /// * [`Error::InsufficientApproval`] - If the caller does not have the + /// right to approve. + /// * [`Error::NonexistentToken`] - If the token does not exist. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. fn transfer_from( &mut self, from: Address, @@ -377,6 +366,11 @@ pub trait IErc721 { /// Only a single account can be approved at a time, /// so approving the `Address::ZERO` clears previous approvals. /// + /// # Requirements + /// + /// * The caller must own the token or be an approved operator. + /// * `token_id` must exist. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -385,20 +379,13 @@ pub trait IErc721 { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// If `auth` (param of [`Erc721::_approve`]) does not have a right to - /// approve this token, then the error - /// [`Error::InvalidApprover`] is returned. - /// - /// # Requirements: - /// - /// * The caller must own the token or be an approved operator. - /// * `token_id` must exist. + /// * [`Error::NonexistentToken`] - If the token does not exist. + /// * [`Error::InvalidApprover`] - If `auth` (param of [`Erc721::_approve`]) + /// does not have a right to approve this token. /// /// # Events /// - /// Emits an [`Approval`] event. + /// * [`Approval`]. fn approve( &mut self, to: Address, @@ -410,6 +397,10 @@ pub trait IErc721 { /// Operators can call [`Self::transfer_from`] or /// [`Self::safe_transfer_from`] for any token owned by the caller. /// + /// # Requirements + /// + /// * The `operator` cannot be the `Address::ZERO`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -420,16 +411,11 @@ pub trait IErc721 { /// /// # Errors /// - /// * If `operator` is `Address::ZERO`, then the error - /// [`Error::InvalidOperator`] is returned. - /// - /// # Requirements: - /// - /// * The `operator` cannot be the `Address::ZERO`. + /// * [`Error::InvalidOperator`] - If `operator` is `Address::ZERO`. /// /// # Events /// - /// Emits an [`ApprovalForAll`] event. + /// * [`ApprovalForAll`]. fn set_approval_for_all( &mut self, operator: Address, @@ -438,6 +424,10 @@ pub trait IErc721 { /// Returns the account approved for `token_id` token. /// + /// # Requirements + /// + /// * `token_id` must exist. + /// /// # Arguments /// /// * `&self` - Read access to the contract's state. @@ -445,12 +435,7 @@ pub trait IErc721 { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// - /// # Requirements: - /// - /// * `token_id` must exist. + /// * [`Error::NonexistentToken`] - If the token does not exist. fn get_approved(&self, token_id: U256) -> Result; /// Returns whether the `operator` is allowed to manage all the assets of @@ -633,10 +618,9 @@ impl Erc721 { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// If `spender` does not have the right to approve, then the error - /// [`Error::InsufficientApproval`] is returned. + /// * [`Error::NonexistentToken`] - If the token does not exist. + /// * [`Error::InsufficientApproval`] - If `spender` does not have the right + /// to approve. pub fn _check_authorized( &self, owner: Address, @@ -696,15 +680,14 @@ impl Erc721 { /// /// # Errors /// - /// If token does not exist and `auth` is not `Address::ZERO`, then the - /// error [`Error::NonexistentToken`] is returned. - /// If `auth` is not `Address::ZERO` and `auth` does not have a right to - /// approve this token, then the error - /// [`Error::InsufficientApproval`] is returned. + /// * [`Error::NonexistentToken`] - If the token does not exist and `auth` + /// is not `Address::ZERO`. + /// * [`Error::InsufficientApproval`] - If `auth` is not `Address::ZERO` and + /// `auth` does not have a right to approve this token. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _update( &mut self, to: Address, @@ -740,6 +723,11 @@ impl Erc721 { /// WARNING: Usage of this method is discouraged, use [`Self::_safe_mint`] /// whenever possible. /// + /// # Requirements + /// + /// * `token_id` must not exist. + /// * `to` cannot be the `Address::ZERO`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -748,19 +736,12 @@ impl Erc721 { /// /// # Errors /// - /// If `token_id` already exists, then the error - /// [`Error::InvalidSender`] is returned. - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// - /// # Requirements: - /// - /// * `token_id` must not exist. - /// * `to` cannot be the zero address. + /// * [`Error::InvalidSender`] - If `token_id` already exists. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _mint(&mut self, to: Address, token_id: U256) -> Result<(), Error> { if to.is_zero() { return Err( @@ -781,6 +762,13 @@ impl Erc721 { /// An additional `data` parameter is forwarded to /// [`IERC721Receiver::on_erc_721_received`] to contract recipients. /// + /// # Requirements + /// + /// * `token_id` must not exist. + /// * If `to` refers to a smart contract, it must implement + /// [`IERC721Receiver::on_erc_721_received`], which is called upon a + /// `safe_transfer`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -791,24 +779,15 @@ impl Erc721 { /// /// # Errors /// - /// If `token_id` already exists, then the error - /// [`Error::InvalidSender`] is returned. - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC721Receiver::on_erc_721_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// - /// # Requirements: - /// - /// * `token_id` must not exist. - /// * If `to` refers to a smart contract, it must implement - /// [`IERC721Receiver::on_erc_721_received`], which is called upon a - /// `safe_transfer`. + /// * [`Error::InvalidSender`] - If `token_id` already exists. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC721Receiver::on_erc_721_received`] hasn't returned its interface + /// id or returned with an error. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _safe_mint( &mut self, to: Address, @@ -831,6 +810,10 @@ impl Erc721 { /// internal function that does not check if the sender is authorized /// to operate on the token. /// + /// # Requirements + /// + /// * `token_id` must exist. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -838,16 +821,11 @@ impl Erc721 { /// /// # Errors /// - /// If token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// - /// # Requirements: - /// - /// * `token_id` must exist. + /// * [`Error::NonexistentToken`] - If the token does not exist. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _burn(&mut self, token_id: U256) -> Result<(), Error> { let previous_owner = self._update(Address::ZERO, token_id, Address::ZERO)?; @@ -862,6 +840,11 @@ impl Erc721 { /// As opposed to [`Self::transfer_from`], this imposes no restrictions on /// `msg::sender`. /// + /// # Requirements + /// + /// * `to` cannot be the `Address::ZERO`. + /// * The `token_id` token must be owned by `from`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -871,21 +854,13 @@ impl Erc721 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If `token_id` does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// If the previous owner is not `from`, then the error - /// [`Error::IncorrectOwner`] is returned. - /// - /// # Requirements: - /// - /// * `to` cannot be the zero address. - /// * The `token_id` token must be owned by `from`. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`Error::NonexistentToken`] - If `token_id` does not exist. + /// * [`Error::IncorrectOwner`] - If the previous owner is not `from`. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _transfer( &mut self, from: Address, @@ -924,6 +899,15 @@ impl Erc721 { /// and can be used to e.g. implement alternative mechanisms to perform /// token transfer, such as signature-based. /// + /// # Requirements + /// + /// * The `token_id` token must exist and be owned by `from`. + /// * `to` cannot be the `Address::ZERO`. + /// * `from` cannot be the `Address::ZERO`. + /// * If `to` refers to a smart contract, it must implement + /// [`IERC721Receiver::on_erc_721_received`], which is called upon a + /// `safe_transfer`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -935,25 +919,13 @@ impl Erc721 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If `token_id` does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// If the previous owner is not `from`, then the error - /// [`Error::IncorrectOwner`] is returned. - /// - /// # Requirements: - /// - /// * The `token_id` token must exist and be owned by `from`. - /// * `to` cannot be the zero address. - /// * `from` cannot be the zero address. - /// * If `to` refers to a smart contract, it must implement - /// [`IERC721Receiver::on_erc_721_received`], which is called upon a - /// `safe_transfer`. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`. + /// * [`Error::NonexistentToken`] - If `token_id` does not exist. + /// * [`Error::IncorrectOwner`] - If the previous owner is not `from`. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * [`Transfer`]. pub fn _safe_transfer( &mut self, from: Address, @@ -981,14 +953,13 @@ impl Erc721 { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// If `auth` does not have a right to approve this token, then the error - /// [`Error::InvalidApprover`] is returned. + /// * [`Error::NonexistentToken`] - If the token does not exist. + /// * [`Error::InvalidApprover`] - If `auth` does not have a right to + /// approve this token. /// /// # Events /// - /// Emits an [`Approval`] event. + /// * [`Approval`]. pub fn _approve( &mut self, to: Address, @@ -1020,6 +991,10 @@ impl Erc721 { /// Approve `operator` to operate on all of `owner`'s tokens. /// + /// # Requirements + /// + /// * `operator` can't be the `Address::ZERO`. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -1029,16 +1004,11 @@ impl Erc721 { /// /// # Errors /// - /// If `operator` is `Address::ZERO`, then the error - /// [`Error::InvalidOperator`] is returned. - /// - /// # Requirements: - /// - /// * `operator` can't be the address zero. + /// * [`Error::InvalidOperator`] - If `operator` is `Address::ZERO`. /// /// # Events /// - /// Emits an [`ApprovalForAll`] event. + /// * [`ApprovalForAll`]. pub fn _set_approval_for_all( &mut self, owner: Address, @@ -1060,15 +1030,14 @@ impl Erc721 { /// Overrides to ownership logic should be done to /// [`Self::_owner_of`]. /// - /// # Errors - /// - /// If token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// /// # Arguments /// /// * `&self` - Read access to the contract's state. /// * `token_id` - Token id as a number. + /// + /// # Errors + /// + /// * [`Error::NonexistentToken`] - If token does not exist. pub fn _require_owned(&self, token_id: U256) -> Result { let owner = self._owner_of(token_id); if owner.is_zero() { @@ -1099,9 +1068,9 @@ impl Erc721 { /// /// # Errors /// - /// If [`IERC721Receiver::on_erc_721_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC721Receiver::on_erc_721_received`] hasn't returned its interface + /// id or returned with error. pub fn _check_on_erc721_received( &mut self, operator: Address, diff --git a/contracts/src/utils/cryptography/ecdsa.rs b/contracts/src/utils/cryptography/ecdsa.rs index 73d7d6152..bc2908d46 100644 --- a/contracts/src/utils/cryptography/ecdsa.rs +++ b/contracts/src/utils/cryptography/ecdsa.rs @@ -85,10 +85,9 @@ impl MethodError for ecdsa::Error { /// /// # Errors /// -/// * If the `s` value is grater than [`SIGNATURE_S_UPPER_BOUND`], then the -/// error [`Error::InvalidSignatureS`] is returned. -/// * If the recovered address is `Address::ZERO`, then the error -/// [`Error::InvalidSignature`] is returned. +/// * [`Error::InvalidSignatureS`] - If the `s` value is grater than +/// [`SIGNATURE_S_UPPER_BOUND`]. +/// * [`Error::InvalidSignature`] - If the recovered address is `Address::ZERO`. /// /// # Panics /// @@ -106,6 +105,7 @@ pub fn recover( } /// Calls `ecrecover` EVM precompile. +/// /// The `ecrecover` EVM precompile allows for malleable (non-unique) signatures: /// this function rejects them by requiring the `s` value to be in the lower /// half order, and the `v` value to be either 27 or 28. @@ -120,8 +120,7 @@ pub fn recover( /// /// # Errors /// -/// * If the recovered address is `Address::ZERO`, then the error -/// [`Error::InvalidSignature`] is returned. +/// * [`Error::InvalidSignature`] - If the recovered address is `Address::ZERO`. /// /// # Panics /// @@ -194,8 +193,8 @@ fn encode_calldata(hash: B256, v: u8, r: B256, s: B256) -> Vec { /// /// # Errors /// -/// * If the `s` value is grater than [`SIGNATURE_S_UPPER_BOUND`], then the -/// error [`Error::InvalidSignatureS`] is returned. +/// * [`Error::InvalidSignatureS`] - If the `s` value is greater than +/// [`SIGNATURE_S_UPPER_BOUND`]. /// /// [Ethereum Yellow paper]: https://ethereum.github.io/yellowpaper/paper.pdf fn check_if_malleable(s: &B256) -> Result<(), Error> { diff --git a/contracts/src/utils/introspection/erc165.rs b/contracts/src/utils/introspection/erc165.rs index bace27998..9d1be9ebb 100644 --- a/contracts/src/utils/introspection/erc165.rs +++ b/contracts/src/utils/introspection/erc165.rs @@ -16,11 +16,17 @@ use openzeppelin_stylus_proc::interface_id; #[interface_id] pub trait IErc165 { /// Returns true if this contract implements the interface defined by - /// `interface_id`. See the corresponding [ERC section] - /// to learn more about how these ids are created. + /// `interface_id`. See the corresponding [ERC] to learn more about how + /// these ids are created. /// - /// Method [`IErc165::supports_interface`] should be reexported with - /// `#[public]` macro manually like this: + /// NOTE: Method [`IErc165::supports_interface`] should be reexported with + /// `#[public]` macro manually, see the Example section. + /// + /// # Arguments + /// + /// * `interface_id` - The interface identifier, as specified in the [ERC]. + /// + /// # Example /// /// ```rust,ignore /// #[public] @@ -32,12 +38,7 @@ pub trait IErc165 { /// } /// ``` /// - /// # Arguments - /// - /// * `interface_id` - The interface identifier, as specified in [ERC - /// section] - /// - /// [ERC section]: https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified + /// [ERC]: https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified fn supports_interface(interface_id: FixedBytes<4>) -> bool; } diff --git a/contracts/src/utils/nonces.rs b/contracts/src/utils/nonces.rs index 4a588af5f..353f04733 100644 --- a/contracts/src/utils/nonces.rs +++ b/contracts/src/utils/nonces.rs @@ -67,7 +67,7 @@ impl Nonces { /// /// # Panics /// - /// If the nonce for the given `owner` exceeds `U256::MAX`. + /// * If the nonce for the given `owner` exceeds `U256::MAX`. pub fn use_nonce(&mut self, owner: Address) -> U256 { let nonce = self._nonces.get(owner); @@ -89,12 +89,12 @@ impl Nonces { /// /// # Errors /// - /// Returns an error if the `nonce` is not the next valid nonce for the - /// owner. + /// * [`Error::InvalidAccountNonce`] - Returns an error if the `nonce` is + /// not the next valid nonce for the owner. /// /// # Panics /// - /// If the nonce for the given `owner` exceeds `U256::MAX`. + /// * If the nonce for the given `owner` exceeds `U256::MAX`. pub fn use_checked_nonce( &mut self, owner: Address, diff --git a/contracts/src/utils/pausable.rs b/contracts/src/utils/pausable.rs index 60e369628..118ad8518 100644 --- a/contracts/src/utils/pausable.rs +++ b/contracts/src/utils/pausable.rs @@ -93,8 +93,7 @@ impl Pausable { /// /// # Errors /// - /// If the contract is in `Paused` state, then the error - /// [`Error::EnforcedPause`] is returned. + /// * [`Error::EnforcedPause`] - If the contract is in `Paused` state. pub fn pause(&mut self) -> Result<(), Error> { self.when_not_paused()?; self._paused.set(true); @@ -110,8 +109,7 @@ impl Pausable { /// /// # Errors /// - /// If the contract is in `Unpaused` state, then the error - /// [`Error::ExpectedPause`] is returned. + /// * [`Error::ExpectedPause`] - If the contract is in `Unpaused` state. pub fn unpause(&mut self) -> Result<(), Error> { self.when_paused()?; self._paused.set(false); @@ -128,8 +126,7 @@ impl Pausable { /// /// # Errors /// - /// If the contract is in the `Paused` state, then the error - /// [`Error::EnforcedPause`] is returned. + /// * [`Error::EnforcedPause`] - If the contract is in the `Paused` state. pub fn when_not_paused(&self) -> Result<(), Error> { if self._paused.get() { return Err(Error::EnforcedPause(EnforcedPause {})); @@ -146,8 +143,7 @@ impl Pausable { /// /// # Errors /// - /// If the contract is in `Unpaused` state, then the error - /// [`Error::ExpectedPause`] is returned. + /// * [`Error::ExpectedPause`] - If the contract is in `Unpaused` state. pub fn when_paused(&self) -> Result<(), Error> { if !self._paused.get() { return Err(Error::ExpectedPause(ExpectedPause {})); diff --git a/contracts/src/utils/structs/checkpoints/mod.rs b/contracts/src/utils/structs/checkpoints/mod.rs index 81d522f58..837237f63 100644 --- a/contracts/src/utils/structs/checkpoints/mod.rs +++ b/contracts/src/utils/structs/checkpoints/mod.rs @@ -83,9 +83,9 @@ impl Trace { /// /// # Errors /// - /// If the `key` is lower than previously pushed checkpoint's key, the error - /// [`Error::CheckpointUnorderedInsertion`] is returned (necessary to - /// maintain sorted order). + /// * [`Error::CheckpointUnorderedInsertion`] - If the `key` is lower than + /// previously pushed checkpoint's key (necessary to maintain sorted + /// order). pub fn push( &mut self, key: S::Key, @@ -233,9 +233,8 @@ impl Trace { /// /// # Errors /// - /// To maintain the sorted order if the `key` is lower than the previously - /// inserted one, the error [`Error::CheckpointUnorderedInsertion`] is - /// returned. + /// * [`Error::CheckpointUnorderedInsertion`] - If the `key` is lower than + /// the previously inserted one. fn _insert( &mut self, key: S::Key, @@ -330,14 +329,14 @@ impl Trace { /// Immutable access on an element of the checkpoint's array. The position /// is assumed to be within bounds. /// - /// # Panics - /// - /// If `pos` exceeds [`Self::length`]. - /// /// # Arguments /// /// * `&self` - Read access to the checkpoint's state. /// * `pos` - Index of the checkpoint. + /// + /// # Panics + /// + /// * If `pos` exceeds [`Self::length`]. fn _index(&self, pos: U256) -> StorageGuard> { self._checkpoints .get(pos) @@ -347,14 +346,14 @@ impl Trace { /// Mutable access on an element of the checkpoint's array. The position is /// assumed to be within bounds. /// - /// # Panics - /// - /// If `pos` exceeds [`Self::length`]. - /// /// # Arguments /// /// * `&mut self` - Write access to the checkpoint's state. /// * `pos` - Index of the checkpoint. + /// + /// # Panics + /// + /// * If `pos` exceeds [`Self::length`]. fn _index_mut(&mut self, pos: U256) -> StorageGuardMut> { self._checkpoints .setter(pos) diff --git a/lib/crypto/src/merkle.rs b/lib/crypto/src/merkle.rs index 973073fde..bf94a4137 100644 --- a/lib/crypto/src/merkle.rs +++ b/lib/crypto/src/merkle.rs @@ -100,11 +100,11 @@ impl Verifier { /// /// # Errors /// - /// Will return `Err` if the arguments are well-formed, but invalid. + /// * [`MultiProofError`] - If the arguments are well-formed, but invalid. /// /// # Panics /// - /// Will panic with an out-of-bounds error if the proof is malicious. See + /// * Will panic with an out-of-bounds error if the proof is malicious. See /// /// /// # Examples @@ -235,7 +235,7 @@ where /// /// # Errors /// - /// Will return `Err` if the arguments are well-formed, but invalid. + /// * [`MultiProofError`] - If the arguments are well-formed, but invalid. /// /// # Examples ///