@artblocks/contracts 1.0.4 → 1.2.0

package/contracts/libs/v0.8.x/minter-libs/MerkleLib.sol

@@ -1,10 +1,12 @@
 // SPDX-License-Identifier: LGPL-3.0-only
 // Created By: Art Blocks Inc.
 
-import "@openzeppelin-4.7/contracts/utils/cryptography/MerkleProof.sol";
-
 pragma solidity ^0.8.0;
 
+import {GenericMinterEventsLib} from "./GenericMinterEventsLib.sol";
+
+import {MerkleProof} from "@openzeppelin-4.7/contracts/utils/cryptography/MerkleProof.sol";
+
 /**
  * @title Art Blocks Merkle Library
  * @notice This library is designed to manage and verify merkle based gating for Art Blocks projects.
@@ -16,6 +18,27 @@ pragma solidity ^0.8.0;
 library MerkleLib {
     using MerkleProof for bytes32[];
 
+    /// Events specific to this library ///
+    /**
+     * @notice Notifies of the contract's default maximum mints allowed per
+     * user for a given project, on this minter. This value can be overridden
+     * by the artist of any project at any time.
+     * @param defaultMaxInvocationsPerAddress The default maximum mints allowed
+     */
+    event DefaultMaxInvocationsPerAddress(
+        uint256 defaultMaxInvocationsPerAddress
+    );
+    /**
+     * @notice Notifies of the contracts' current delegation registry address.
+     * @param delegationRegistry The address of the delegation registry
+     */
+    event DelegationRegistryUpdated(address delegationRegistry);
+
+    // position of Merkle Lib storage, using a diamond storage pattern for this
+    // library
+    bytes32 constant MERKLE_LIB_STORAGE_POSITION =
+        keccak256("merklelib.storage");
+
     /// @notice Default maximum invocations per address
     uint256 internal constant DEFAULT_MAX_INVOCATIONS_PER_ADDRESS = 1;
     bytes32 internal constant CONFIG_MERKLE_ROOT = "merkleRoot";
@@ -37,86 +60,215 @@ library MerkleLib {
         // The root of the Merkle tree for this project.
         bytes32 merkleRoot;
         // The number of current invocations for this project from a given user address.
-        mapping(address => uint256) userMintInvocations;
+        mapping(address user => uint256 mintInvocations) userMintInvocations;
+    }
+
+    // Diamond storage pattern is used in this library
+    struct MerkleLibStorage {
+        mapping(address coreContract => mapping(uint256 projectId => MerkleProjectConfig)) merkleProjectConfigs;
     }
 
     /**
      * @notice Sets the maximum number of invocations per address for a project.
-     * @param _projectConfig Merkle project config.
-     * @param _maxInvocationsPerAddress The maximum number of invocations per address.
+     * @param projectId The ID of the project to set the maximum invocations for.
+     * @param coreContract The address of the core contract.
+     * @param maxInvocationsPerAddress The maximum number of invocations per address.
      */
     function setProjectInvocationsPerAddress(
-        MerkleProjectConfig storage _projectConfig,
-        uint24 _maxInvocationsPerAddress
+        uint256 projectId,
+        address coreContract,
+        uint24 maxInvocationsPerAddress
     ) internal {
-        _projectConfig.useMaxInvocationsPerAddressOverride = true;
-        _projectConfig
-            .maxInvocationsPerAddressOverride = _maxInvocationsPerAddress;
+        MerkleProjectConfig
+            storage merkleProjectConfig = getMerkleProjectConfig({
+                projectId: projectId,
+                coreContract: coreContract
+            });
+        merkleProjectConfig.useMaxInvocationsPerAddressOverride = true;
+        merkleProjectConfig
+            .maxInvocationsPerAddressOverride = maxInvocationsPerAddress;
+        emit GenericMinterEventsLib.ConfigValueSet({
+            projectId: projectId,
+            coreContract: coreContract,
+            key: CONFIG_USE_MAX_INVOCATIONS_PER_ADDRESS_OVERRIDE,
+            value: true
+        });
+        emit GenericMinterEventsLib.ConfigValueSet({
+            projectId: projectId,
+            coreContract: coreContract,
+            key: CONFIG_MAX_INVOCATIONS_OVERRIDE,
+            value: uint256(maxInvocationsPerAddress)
+        });
     }
 
     /**
      * @notice Updates the Merkle root of a project.
-     * @param _projectConfig Merkle project config.
-     * @param _root The new Merkle root.
+     * @param projectId The ID of the project to update.
+     * @param coreContract The address of the core contract.
+     * @param root The new Merkle root.
      */
     function updateMerkleRoot(
-        MerkleProjectConfig storage _projectConfig,
-        bytes32 _root
+        uint256 projectId,
+        address coreContract,
+        bytes32 root
+    ) internal {
+        require(root != bytes32(0), "Root must be provided");
+        MerkleProjectConfig
+            storage merkleProjectConfig = getMerkleProjectConfig({
+                projectId: projectId,
+                coreContract: coreContract
+            });
+        merkleProjectConfig.merkleRoot = root;
+        emit GenericMinterEventsLib.ConfigValueSet({
+            projectId: projectId,
+            coreContract: coreContract,
+            key: CONFIG_MERKLE_ROOT,
+            value: root
+        });
+    }
+
+    /**
+     * @notice Checks that a given proof is valid for the vault address, and
+     * also checks that the vault address has not exceeded the maximum number
+     * of invocations per address for the project.
+     * @dev Reverts if the proof is invalid or if the vault address has
+     * exceeded the maximum number of invocations per address for the project.
+     * @param projectId project id to check
+     * @param coreContract core contract address to check
+     * @param proof Merkle proof to check
+     * @param vault address to check proof against
+     */
+    function preMintChecks(
+        uint256 projectId,
+        address coreContract,
+        bytes32[] calldata proof,
+        address vault
+    ) internal view {
+        MerkleProjectConfig
+            storage merkleProjectConfig = getMerkleProjectConfig({
+                projectId: projectId,
+                coreContract: coreContract
+            });
+        // require valid Merkle proof
+        require(
+            _verifyAddress({
+                proofRoot: merkleProjectConfig.merkleRoot,
+                proof: proof,
+                address_: vault
+            }),
+            "Invalid Merkle proof"
+        );
+
+        // limit mints per address by project
+        uint256 maxProjectInvocationsPerAddress = projectMaxInvocationsPerAddress(
+                merkleProjectConfig
+            );
+
+        // note that mint limits index off of the `vault` (when applicable)
+        require(
+            merkleProjectConfig.userMintInvocations[vault] <
+                maxProjectInvocationsPerAddress ||
+                maxProjectInvocationsPerAddress == 0,
+            "Max invocations reached"
+        );
+    }
+
+    /**
+     * @notice Updates the number of invocations for the `vault` address on the
+     * given project.
+     * @param projectId Project Id to mint on
+     * @param coreContract Core contract address to mint on
+     * @param vault Address being used to mint (the allowlisted address)
+     */
+    function mintEffects(
+        uint256 projectId,
+        address coreContract,
+        address vault
     ) internal {
-        require(_root != bytes32(0), "Must provide root");
-        _projectConfig.merkleRoot = _root;
+        MerkleProjectConfig
+            storage merkleProjectConfig = getMerkleProjectConfig({
+                projectId: projectId,
+                coreContract: coreContract
+            });
+        // increment mint invocations for vault address
+        unchecked {
+            // this will never overflow since user's invocations on a project
+            // are limited by the project's max invocations
+            merkleProjectConfig.userMintInvocations[vault]++;
+        }
     }
 
     /**
      * @notice Hashes an address.
-     * @param _address The address to hash.
+     * @param address_ The address to hash.
      * @return The hash of the address.
      */
-    function hashAddress(address _address) internal pure returns (bytes32) {
-        return keccak256(abi.encodePacked(_address));
+    function hashAddress(address address_) internal pure returns (bytes32) {
+        return keccak256(abi.encodePacked(address_));
     }
 
     /**
      * @notice Processes a proof for an address.
-     * @param _proof The proof to process.
-     * @param _address The address to process the proof for.
+     * @param proof The proof to process.
+     * @param address_ The address to process the proof for.
      * @return The resulting hash from processing the proof.
      */
     function processProofForAddress(
-        bytes32[] calldata _proof,
-        address _address
+        bytes32[] calldata proof,
+        address address_
     ) internal pure returns (bytes32) {
-        return _proof.processProofCalldata(hashAddress(_address));
+        return proof.processProofCalldata(hashAddress(address_));
     }
 
     /**
-     * @notice Verifies an address against a proof.
-     * @param _proofRoot The root of the proof to verify against.
-     * @param _proof The proof to verify.
-     * @param _address The address to verify.
-     * @return True if the address is verified, false otherwise.
+     * @notice Returns the maximum number of invocations per address for a project.
+     * @param projectConfig The merkle project config to check.
+     * @return The maximum number of invocations per address.
      */
-    function verifyAddress(
-        bytes32 _proofRoot,
-        bytes32[] calldata _proof,
-        address _address
-    ) internal pure returns (bool) {
-        return _proof.verifyCalldata(_proofRoot, hashAddress(_address));
+    function projectMaxInvocationsPerAddress(
+        MerkleProjectConfig storage projectConfig
+    ) internal view returns (uint256) {
+        if (projectConfig.useMaxInvocationsPerAddressOverride) {
+            return uint256(projectConfig.maxInvocationsPerAddressOverride);
+        } else {
+            return DEFAULT_MAX_INVOCATIONS_PER_ADDRESS;
+        }
     }
 
     /**
      * @notice Returns the maximum number of invocations per address for a project.
-     * @param _projectConfig The merkle project config to check.
+     * @param projectId Project Id to get config for
+     * @param coreContract Core contract address to get config for
      * @return The maximum number of invocations per address.
      */
     function projectMaxInvocationsPerAddress(
-        MerkleProjectConfig storage _projectConfig
+        uint256 projectId,
+        address coreContract
     ) internal view returns (uint256) {
-        if (_projectConfig.useMaxInvocationsPerAddressOverride) {
-            return uint256(_projectConfig.maxInvocationsPerAddressOverride);
-        } else {
-            return DEFAULT_MAX_INVOCATIONS_PER_ADDRESS;
-        }
+        MerkleProjectConfig storage projectConfig = getMerkleProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        return projectMaxInvocationsPerAddress(projectConfig);
+    }
+
+    /**
+     * @notice Returns the number of invocations for a given address on a given
+     * project.
+     * @param projectId Project Id to query
+     * @param coreContract Core contract address to query
+     * @param purchaser Address to query
+     */
+    function projectUserMintInvocations(
+        uint256 projectId,
+        address coreContract,
+        address purchaser
+    ) internal view returns (uint256) {
+        MerkleProjectConfig storage projectConfig = getMerkleProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        return projectConfig.userMintInvocations[purchaser];
     }
 
     /**
@@ -125,17 +277,27 @@ library MerkleLib {
      * addresses are only limited by the project's maximum invocations, and a
      * dummy value of zero is returned for `mintInvocationsRemaining`.
      * If `projectLimitsMintInvocationsPerAddress` is true, the quantity of
-     * remaining mint invocations for address `_address` is returned as
+     * remaining mint invocations for address `address` is returned as
      * `mintInvocationsRemaining`.
      * Note that mint invocations per address can be changed at any time by the
      * artist of a project.
      * Also note that all mint invocations are limited by a project's maximum
      * invocations as defined on the core contract. This function may return
      * a value greater than the project's remaining invocations.
+     * @param projectId Project Id to get remaining invocations on
+     * @param coreContract Core contract address of project
+     * @param address_ Address to get remaining invocations for
+     * @return projectLimitsMintInvocationsPerAddress If true, the project
+     * limits mint invocations per address. If false, the project does not
+     * limit mint invocations per address.
+     * @return mintInvocationsRemaining The number of remaining mint invocations
+     * for address `address_`. If `projectLimitsMintInvocationsPerAddress` is
+     * false, this value is always dummy zero.
      */
     function projectRemainingInvocationsForAddress(
-        MerkleProjectConfig storage _projectConfig,
-        address _address
+        uint256 projectId,
+        address coreContract,
+        address address_
     )
         internal
         view
@@ -144,19 +306,17 @@ library MerkleLib {
             uint256 mintInvocationsRemaining
         )
     {
+        MerkleProjectConfig storage projectConfig = getMerkleProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
         uint256 maxInvocationsPerAddress = projectMaxInvocationsPerAddress(
-            _projectConfig
+            projectConfig
         );
-        if (maxInvocationsPerAddress == 0) {
-            // project does not limit mint invocations per address, so leave
-            // `projectLimitsMintInvocationsPerAddress` at solidity initial
-            // value of false. Also leave `mintInvocationsRemaining` at
-            // solidity initial value of zero, as indicated in this function's
-            // documentation.
-        } else {
+        if (maxInvocationsPerAddress != 0) {
             projectLimitsMintInvocationsPerAddress = true;
-            uint256 userMintInvocations = _projectConfig.userMintInvocations[
-                _address
+            uint256 userMintInvocations = projectConfig.userMintInvocations[
+                address_
             ];
             // if user has not reached max invocations per address, return
             // remaining invocations
@@ -171,5 +331,58 @@ library MerkleLib {
             // else user has reached their maximum invocations, so leave
             // `mintInvocationsRemaining` at solidity initial value of zero
         }
+        // else maxInvocationsPerAddress is zero, then the project does not
+        // limit mint invocations per address, so do nothing. Leave
+        // `projectLimitsMintInvocationsPerAddress` at solidity initial
+        // value of false. Also leave `mintInvocationsRemaining` at
+        // solidity initial value of zero, as indicated in this function's
+        // documentation.
+    }
+
+    /**
+     * Loads the MerkleProjectConfig for a given project and core contract.
+     * @param projectId Project Id to get config for
+     * @param coreContract Core contract address to get config for
+     */
+    function getMerkleProjectConfig(
+        uint256 projectId,
+        address coreContract
+    ) internal view returns (MerkleProjectConfig storage) {
+        return s().merkleProjectConfigs[coreContract][projectId];
+    }
+
+    /**
+     * @notice Return the storage struct for reading and writing. This library
+     * uses a diamond storage pattern when managing storage.
+     * @return storageStruct The MerkleLibStorage struct.
+     */
+    function s()
+        internal
+        pure
+        returns (MerkleLibStorage storage storageStruct)
+    {
+        bytes32 position = MERKLE_LIB_STORAGE_POSITION;
+        assembly ("memory-safe") {
+            storageStruct.slot := position
+        }
+    }
+
+    /**
+     * @notice Verifies an address against a proof.
+     * @param proofRoot The root of the proof to verify agaisnst.
+     * @param proof The proof to verify.
+     * @param address_ The address to verify.
+     * @return True if the address is verified, false otherwise.
+     */
+    function _verifyAddress(
+        bytes32 proofRoot,
+        bytes32[] calldata proof,
+        address address_
+    ) private pure returns (bool) {
+        return
+            proof.verifyCalldata({
+                root: proofRoot,
+                leaf: hashAddress(address_)
+            });
     }
 }