doc: updated natspect

thesandboxgame · Dec 16, 2024 · 251f57e · 251f57e
1 parent 3d37021
commit 251f57e
Show file tree

Hide file tree

Showing 4 changed files with 8 additions and 67 deletions.
diff --git a/packages/avatar/contracts/nft-collection/ERC721BurnMemoryUpgradeable.sol b/packages/avatar/contracts/nft-collection/ERC721BurnMemoryUpgradeable.sol
@@ -72,7 +72,6 @@ abstract contract ERC721BurnMemoryUpgradeable is ERC721Upgradeable {
 
     /**
      * @notice enables burning of tokens
-     * @custom:event TokenBurningEnabled
      */
     function _enableBurning() internal {
         ERC721BurnMemoryUpgradeableStorage storage $ = _getERC721BurnMemoryUpgradableStorage();
@@ -85,7 +84,6 @@ abstract contract ERC721BurnMemoryUpgradeable is ERC721Upgradeable {
 
     /**
      * @notice disables burning of tokens
-     * @custom:event TokenBurningDisabled
      */
     function _disableBurning() internal {
         ERC721BurnMemoryUpgradeableStorage storage $ = _getERC721BurnMemoryUpgradableStorage();
@@ -98,7 +96,6 @@ abstract contract ERC721BurnMemoryUpgradeable is ERC721Upgradeable {
 
     /**
      * @notice Burns `tokenId`. The caller must own `tokenId` or be an approved operator.
-     * @custom:event TokenBurned
      * @param tokenId the token id to be burned
      */
     function _burnWithCheck(uint256 tokenId) internal virtual {

diff --git a/packages/avatar/contracts/nft-collection/NFTCollection.md b/packages/avatar/contracts/nft-collection/NFTCollection.md
@@ -32,9 +32,10 @@ There are two ways of minting tokens:
 2. The backend gives a signed message to the user. Using this authorization a user can mint certain amount of tokens to
    his wallet paying a price in Sand or any other configured ERC20 token.
 
-Minting is done in waves set the price of the tokens and some limits on the amount of tokens that can be minted and are
-configured by the owner of the contract. After setting an initial wave the owner can set a new wave at any time, the
-previous wave is cancelled each time a new wave is set.
+Minting is done in waves, a wave set the price of the tokens and some limits on the amount of tokens that can be minted.
+Waves are configured by the owner of the contract. After setting an initial wave the owner can set a new wave at any
+time. Usually the previous wave is cancelled each time a new wave is set, but, the owner can choose to leave a wave open
+so two waves can run in parallel (to use this new functionality the user must claim using `waveMint` method).
 
 ### Minting Limits
 
@@ -160,8 +161,6 @@ function setupWave(
 function to setup a new wave. A wave is defined as a combination of allowed number tokens to be minted in total, per
 wallet and minting price
 
-event: {WaveSetup}
-
 Parameters:
 
 | Name                    | Type    | Description                                                                                    |
@@ -184,7 +183,7 @@ function mint(
 token minting function on the last wave. Price is set by wave and is paid in tokens denoted by the allowedToExecuteMint
 contract
 
-this method is backward compatible with the previous contract, so, it uses last configured wave event: {Transfer}
+this method is backward compatible with the previous contract, so, it uses last configured wave
 
 Parameters:
 
@@ -210,8 +209,6 @@ function waveMint(
 token minting function on a certain wave. Price is set by wave and is paid in tokens denoted by the allowedToExecuteMint
 contract
 
-event: {Transfer}
-
 Parameters:
 
 | Name        | Type    | Description                         |
@@ -231,8 +228,6 @@ function cancelWave(uint256 waveIndex) external onlyOwner
 function to setup wave parameters. A wave is defined as a combination of allowed number tokens to be minted in total,
 per wallet and minting price
 
-event: {WaveSetup}
-
 Parameters:
 
 | Name      | Type    | Description                          |
@@ -252,8 +247,6 @@ batch minting function, used by owner to airdrop directly to users.
 
 this methods takes a list of destination wallets and can only be used by the owner of the contract
 
-event: {Transfer}
-
 Parameters:
 
 | Name      | Type                                    | Description                             |
@@ -277,8 +270,6 @@ reveal.
 
 will revert if owner of token is not caller or if signature is not valid
 
-event: {MetadataUpdate}
-
 Parameters:
 
 | Name        | Type    | Description                                                    |
@@ -302,8 +293,6 @@ personalize token traits according to the provided personalization bit-mask
 
 after checks, it is reduced to personalizationTraits[_tokenId] = _personalizationMask
 
-event: {MetadataUpdate}
-
 Parameters:
 
 | Name                | Type    | Description                                         |
@@ -327,8 +316,6 @@ on an in-game action
 
 reverts if token does not exist or if not authorized
 
-event: {MetadataUpdate}
-
 Parameters:
 
 | Name                | Type    | Description                                        |
@@ -346,8 +333,6 @@ Burns `tokenId`. The caller must own `tokenId` or be an approved operator.
 
 See {ERC721BurnMemoryEnumerableUpgradeable.burn}.
 
-event: TokenBurned
-
 Parameters:
 
 | Name    | Type    | Description               |
@@ -364,8 +349,6 @@ enables burning of tokens
 
 reverts if burning already enabled.
 
-event: TokenBurningEnabled
-
 ### disableBurning (0x98603cca)
 
 ```solidity
@@ -376,8 +359,6 @@ disables burning of tokens
 
 reverts if burning already disabled.
 
-event: TokenBurningDisabled
-
 ### pause (0x8456cb59)
 
 ```solidity
@@ -406,8 +387,6 @@ function setTreasury(address treasury) external onlyOwner
 
 update the treasury address
 
-event: {TreasurySet}
-
 Parameters:
 
 | Name     | Type    | Description                      |
@@ -422,8 +401,6 @@ function setSignAddress(address _signAddress) external onlyOwner
 
 updates the sign address.
 
-event: {SignAddressSet}
-
 Parameters:
 
 | Name         | Type    | Description                  |
@@ -438,8 +415,6 @@ function setMaxSupply(uint256 _maxSupply) external onlyOwner
 
 updates the sign address.
 
-event: {MaxSupplySet}
-
 Parameters:
 
 | Name       | Type    | Description                                 |
@@ -456,8 +431,6 @@ updates which address is allowed to execute the mint function.
 
 also resets default mint price
 
-event: {DefaultMintingValuesSet}
-
 Parameters:
 
 | Name        | Type                    | Description                                                   |
@@ -472,8 +445,6 @@ function setBaseURI(string calldata baseURI) external onlyOwner
 
 updates the base token URI for the contract
 
-event: {BaseURISet}
-
 Parameters:
 
 | Name    | Type   | Description                                        |

diff --git a/packages/avatar/contracts/nft-collection/NFTCollection.sol b/packages/avatar/contracts/nft-collection/NFTCollection.sol
@@ -202,7 +202,7 @@ INFTCollection
             revert InvalidSymbol(_symbol);
         }
         __ReentrancyGuard_init();
-        // @dev we don't want to set the owner to _msgSender, so, we don't call __Ownable_init
+        // We don't want to set the owner to _msgSender, so, we call _transferOwnership instead of __Ownable_init
         _transferOwnership(_collectionOwner);
         __ERC2981_init();
         _setTrustedForwarder(_initialTrustedForwarder);
@@ -228,7 +228,6 @@ INFTCollection
     /**
      * @notice function to setup a new wave. A wave is defined as a combination of allowed number tokens to be
      *         minted in total, per wallet and minting price
-     * @custom:event {WaveSetup}
      * @param _waveMaxTokensOverall the allowed number of tokens to be minted in this wave (cumulative by all minting wallets)
      * @param _waveMaxTokensPerWallet max tokens to buy, per wallet in a given wave
      * @param _waveSingleTokenPrice the price to mint a token in a given wave, in wei
@@ -258,7 +257,6 @@ INFTCollection
     /**
      * @notice token minting function on the last wave. Price is set by wave and is paid in tokens denoted
      *         by the allowedToExecuteMint contract
-     * @custom:event {Transfer}
      * @param wallet minting wallet
      * @param amount number of token to mint
      * @param signatureId signing signature ID
@@ -287,7 +285,6 @@ INFTCollection
     /**
      * @notice token minting function on a certain wave. Price is set by wave and is paid in tokens denoted
      *         by the allowedToExecuteMint contract
-     * @custom:event {Transfer}
      * @param wallet minting wallet
      * @param amount number of token to mint
      * @param waveIndex the index of the wave used to mint
@@ -316,7 +313,6 @@ INFTCollection
     /**
      * @notice function to setup wave parameters. A wave is defined as a combination of allowed number tokens to be
      *         minted in total, per wallet and minting price
-     * @custom:event {WaveSetup}
      * @param waveIndex the index of the wave to be canceled
      */
     function cancelWave(uint256 waveIndex) external onlyOwner {
@@ -331,7 +327,6 @@ INFTCollection
     /**
      * @notice batch minting function, used by owner to airdrop directly to users.
      * @dev this methods takes a list of destination wallets and can only be used by the owner of the contract
-     * @custom:event {Transfer}
      * @param waveIndex the index of the wave used to mint
      * @param wallets list of destination wallets and amounts
      */
@@ -368,7 +363,6 @@ INFTCollection
      *         refresh metadata, for the provided token ID. Off-chain, gaming mechanics are done and this
      *         function is ultimately called to signal the end of a reveal.
      * @dev will revert if owner of token is not caller or if signature is not valid
-     * @custom:event {MetadataUpdate}
      * @param tokenId the ID belonging to the NFT token for which to emit the event
      * @param signatureId validation signature ID
      * @param signature validation signature
@@ -390,8 +384,6 @@ INFTCollection
     /**
      * @notice personalize token traits according to the provided personalization bit-mask
      * @dev after checks, it is reduced to personalizationTraits[_tokenId] = _personalizationMask
-     * @custom:event {Personalized}
-     * @custom:event {MetadataUpdate}
      * @param tokenId what token to personalize
      * @param personalizationMask a mask where each bit has a custom meaning in-game
      * @param signatureId the ID of the provided signature
@@ -416,8 +408,6 @@ INFTCollection
      * @notice personalize token traits but can be called by owner or special roles address
      *         Used to change the traits of a token based on an in-game action
      * @dev reverts if token does not exist or if not authorized
-     * @custom:event {Personalized}
-     * @custom:event {MetadataUpdate}
      * @param tokenId what token to personalize
      * @param personalizationMask a mask where each bit has a custom meaning in-game
      */
@@ -433,7 +423,6 @@ INFTCollection
     /**
      * @notice Burns `tokenId`. The caller must own `tokenId` or be an approved operator.
      * @dev See {ERC721BurnMemoryEnumerableUpgradeable.burn}.
-     * @custom:event TokenBurned
      * @param tokenId the token id to be burned
      */
     function burn(uint256 tokenId) external whenNotPaused {
@@ -443,7 +432,6 @@ INFTCollection
     /**
      * @notice enables burning of tokens
      * @dev reverts if burning already enabled.
-     * @custom:event TokenBurningEnabled
      */
     function enableBurning() external onlyOwner {
         _enableBurning();
@@ -452,7 +440,6 @@ INFTCollection
     /**
      * @notice disables burning of tokens
      * @dev reverts if burning already disabled.
-     * @custom:event TokenBurningDisabled
      */
     function disableBurning() external onlyOwner {
         _disableBurning();
@@ -478,7 +465,6 @@ INFTCollection
 
     /**
      * @notice update the treasury address
-     * @custom:event {TreasurySet}
      * @param treasury new treasury address to be saved
      */
     function setTreasury(address treasury) external onlyOwner {
@@ -487,7 +473,6 @@ INFTCollection
 
     /**
      * @notice updates the sign address.
-     * @custom:event {SignAddressSet}
      * @param _signAddress new signer address to be set
      */
     function setSignAddress(address _signAddress) external onlyOwner {
@@ -496,7 +481,6 @@ INFTCollection
 
     /**
      * @notice updates the sign address.
-     * @custom:event {MaxSupplySet}
      * @param _maxSupply maximum amount of tokens that can be minted
      */
     function setMaxSupply(uint256 _maxSupply) external onlyOwner {
@@ -506,8 +490,6 @@ INFTCollection
     /**
      * @notice updates which address is allowed to execute the mint function.
      * @dev also resets default mint price
-     * @custom:event {AllowedExecuteMintSet}
-     * @custom:event {DefaultMintingValuesSet}
      * @param minterToken the address that will be allowed to execute the mint function
      */
     function setAllowedExecuteMint(IERC20Metadata minterToken) external onlyOwner {
@@ -516,7 +498,6 @@ INFTCollection
 
     /**
      * @notice updates the base token URI for the contract
-     * @custom:event {BaseURISet}
      * @param baseURI an URI that will be used as the base for token URI
      */
     function setBaseURI(string calldata baseURI) external onlyOwner {
@@ -851,7 +832,6 @@ INFTCollection
 
     /**
      * @notice complete the minting called from waveMint and mint
-     * @custom:event {Transfer}
      * @param waveData the data of the wave used to mint
      * @param wallet minting wallet
      * @param amount number of token to mint
@@ -945,8 +925,6 @@ INFTCollection
     /**
      * @notice actually updates the variables that store the personalization traits per token.
      * @dev no checks are done on input validations. Calling functions are expected to do them
-     * @custom:event {Personalized}
-     * @custom:event {MetadataUpdate}
      * @param tokenId the ID for the token to personalize
      * @param personalizationMask the personalization mask that will be applied
      */
@@ -971,7 +949,6 @@ INFTCollection
 
     /**
      * @notice updates the base token URI for the contract
-     * @custom:event {BaseURISet}
      * @param baseURI an URI that will be used as the base for token URI
      */
     function _setBaseURI(string calldata baseURI) internal {
@@ -985,7 +962,6 @@ INFTCollection
 
     /**
      * @notice update the treasury address
-     * @custom:event {TreasurySet}
      * @param _treasury new treasury address to be saved
      */
     function _setTreasury(address _treasury) internal {
@@ -1000,8 +976,6 @@ INFTCollection
     /**
      * @notice updates which address is allowed to execute the mint function.
      * @dev also resets default mint price
-     * @custom:event {AllowedExecuteMintSet}
-     * @custom:event {DefaultMintingValuesSet}
      * @param _minterToken the address that will be allowed to execute the mint function
      */
     function _setAllowedExecuteMint(IERC20Metadata _minterToken) internal {
@@ -1015,7 +989,6 @@ INFTCollection
 
     /**
      * @notice updates maximum supply
-     * @custom:event {MaxSupplySet}
      * @param _maxSupply maximum amount of tokens that can be minted
      */
     function _setMaxSupply(uint256 _maxSupply) internal {

diff --git a/packages/avatar/contracts/nft-collection/NFTCollectionSignature.sol b/packages/avatar/contracts/nft-collection/NFTCollectionSignature.sol
@@ -10,7 +10,8 @@ import {ECDSA} from "@openzeppelin/contracts-5.0.2/utils/cryptography/ECDSA.sol"
  * @custom:security-contact [email protected]
  * @notice Signatures accepted by the NFTCollection
  * @dev We have a set of different signatures to be backward compatible with previous collections
- * @dev We must be sure that all the signatures are different and cannot be reused so we added a string to reveal.
+ * @dev We must be sure that all the signatures are different and cannot be reused by different methods, so,
+ * @dev we added an extra constant string to reveal to distinguish it from the mint signature.
  * @dev mint:           ['address', 'uint256', 'address', 'uint256']
  * @dev reveal:         ['address', 'uint256', 'address', 'uint256', 'string']
  * @dev personalize:    ['address', 'uint256', 'address', 'uint256', 'uint256', 'uint256']
@@ -91,7 +92,6 @@ abstract contract NFTCollectionSignature {
 
     /**
      * @notice updates the sign address.
-     * @custom:event {SignAddressSet}
      * @param _signAddress new signer address to be set
      */
     function _setSignAddress(address _signAddress) internal {