@artblocks/contracts 1.0.3 → 1.1.0

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

@@ -0,0 +1,384 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+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.
+ * It provides functionalities such as updating the merkle root of project, verifying an address against a proof,
+ * and setting the maximum number of invocations per address for a project.
+ * @author Art Blocks Inc.
+ */
+
+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";
+    bytes32 internal constant CONFIG_USE_MAX_INVOCATIONS_PER_ADDRESS_OVERRIDE =
+        "useMaxMintsPerAddrOverride"; // shortened to fit in 32 bytes
+    bytes32 internal constant CONFIG_MAX_INVOCATIONS_OVERRIDE =
+        "maxMintsPerAddrOverride"; // shortened to match format of previous key
+
+    struct MerkleProjectConfig {
+        // If true, the maxInvocationsPerAddressOverride will be used.
+        // If false, the default max invocations per address will be used.
+        bool useMaxInvocationsPerAddressOverride;
+        // Maximum invocations allowed per address.
+        // This will be used if useMaxInvocationsPerAddressOverride is true.
+        // A value of 0 means no limit.
+        // @dev Safe to use uint24 because maxInvocationsPerAddressOverride <= 1_000_000
+        // and 1_000_000 << max uint24
+        uint24 maxInvocationsPerAddressOverride;
+        // 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 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 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(
+        uint256 projectId,
+        address coreContract,
+        uint24 maxInvocationsPerAddress
+    ) internal {
+        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 projectId The ID of the project to update.
+     * @param coreContract The address of the core contract.
+     * @param root The new Merkle root.
+     */
+    function updateMerkleRoot(
+        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.
+     * 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 {
+        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.
+     * @return The hash of the 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.
+     * @return The resulting hash from processing the proof.
+     */
+    function processProofForAddress(
+        bytes32[] calldata proof,
+        address address_
+    ) internal pure returns (bytes32) {
+        return proof.processProofCalldata(hashAddress(address_));
+    }
+
+    /**
+     * @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 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 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(
+        uint256 projectId,
+        address coreContract
+    ) internal view returns (uint256) {
+        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];
+    }
+
+    /**
+     * @notice Returns remaining invocations for a given address.
+     * If `projectLimitsMintInvocationsPerAddress` is false, individual
+     * 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
+     * `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(
+        uint256 projectId,
+        address coreContract,
+        address address_
+    )
+        internal
+        view
+        returns (
+            bool projectLimitsMintInvocationsPerAddress,
+            uint256 mintInvocationsRemaining
+        )
+    {
+        MerkleProjectConfig storage projectConfig = getMerkleProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        uint256 maxInvocationsPerAddress = projectMaxInvocationsPerAddress(
+            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 {
+            projectLimitsMintInvocationsPerAddress = true;
+            uint256 userMintInvocations = projectConfig.userMintInvocations[
+                address_
+            ];
+            // if user has not reached max invocations per address, return
+            // remaining invocations
+            if (maxInvocationsPerAddress > userMintInvocations) {
+                unchecked {
+                    // will never underflow due to the check above
+                    mintInvocationsRemaining =
+                        maxInvocationsPerAddress -
+                        userMintInvocations;
+                }
+            }
+            // else user has reached their maximum invocations, so leave
+            // `mintInvocationsRemaining` at solidity initial value of zero
+        }
+    }
+
+    /**
+     * 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(proofRoot, hashAddress(address_));
+    }
+}

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

@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+pragma solidity ^0.8.0;
+
+import {IGenArt721CoreContractV3_Base} from "../../../interfaces/v0.8.x/IGenArt721CoreContractV3_Base.sol";
+import {IGenArt721CoreContractExposesHashSeed} from "../../../interfaces/v0.8.x/IGenArt721CoreContractExposesHashSeed.sol";
+import {IGenArt721CoreContractV3WithSharedRandomizer} from "../../../interfaces/v0.8.x/IGenArt721CoreContractV3WithSharedRandomizer.sol";
+import {ISharedRandomizerV0} from "../../../interfaces/v0.8.x/ISharedRandomizerV0.sol";
+
+import {GenericMinterEventsLib} from "./GenericMinterEventsLib.sol";
+
+import {IERC20} from "@openzeppelin-4.7/contracts/token/ERC20/IERC20.sol";
+
+/**
+ * @title Art Blocks Polyptych Minter Library
+ * @notice This library is designed for the Art Blocks platform. It includes
+ * structs and functions to help configure Polyptych minters.
+ * @author Art Blocks Inc.
+ */
+
+library PolyptychLib {
+    bytes32 constant POLYPTYCH_PANEL_ID = "polyptychPanelId";
+
+    // position of Polyptych Lib storage, using a diamond storage pattern
+    // for this library
+    bytes32 constant POLYPTYCH_LIB_STORAGE_POSITION =
+        keccak256("polyptychlib.storage");
+
+    struct PolyptychProjectConfig {
+        // @dev uint24 provides sufficient qty of panels, and could be packed
+        // in the future if other values are added to this struct.
+        uint24 polyptychPanelId;
+        // Stores whether a panel with an ID has been minted for a given token hash seed
+        mapping(uint256 panelId => mapping(bytes12 hashSeed => bool panelIsMinted)) polyptychPanelHashSeedIsMinted;
+    }
+
+    // Diamond storage pattern is used in this library
+    struct PolyptychLibStorage {
+        mapping(address coreContract => mapping(uint256 projectId => PolyptychProjectConfig)) polyptychProjectConfigs;
+    }
+
+    /**
+     * @notice Increments the minter to the next polyptych panel of a given project
+     * @param projectId Project ID to increment panel ID for
+     * @param coreContract Core contract address that _projectId is on
+     */
+    function incrementPolyptychProjectPanelId(
+        uint256 projectId,
+        address coreContract
+    ) internal {
+        PolyptychProjectConfig
+            storage polyptychProjectConfig = getPolyptychProjectConfig({
+                projectId: projectId,
+                coreContract: coreContract
+            });
+        // increment panel ID
+        ++polyptychProjectConfig.polyptychPanelId;
+
+        // index the update
+        emit GenericMinterEventsLib.ConfigValueSet({
+            projectId: projectId,
+            coreContract: coreContract,
+            key: PolyptychLib.POLYPTYCH_PANEL_ID,
+            value: polyptychProjectConfig.polyptychPanelId
+        });
+    }
+
+    /**
+     * Validate the polyptych-related effects after a purchase on a polyptych
+     * minter.
+     * Verifies that the token hash seed is non-zero, and also enforces that
+     * the hash seed can only be used up to one time per panel.
+     * @param projectId Project ID to validate
+     * @param coreContract Core contract address to validate
+     * @param tokenHashSeed token hash seed
+     */
+    function validatePolyptychEffects(
+        uint256 projectId,
+        address coreContract,
+        bytes12 tokenHashSeed
+    ) internal {
+        PolyptychProjectConfig
+            storage polyptychProjectConfig = getPolyptychProjectConfig({
+                projectId: projectId,
+                coreContract: coreContract
+            });
+        // ensure non-zero hash seed
+        require(tokenHashSeed != bytes12(0), "Only non-zero hash seeds");
+        // verify that the hash seed has not been used on the current panel
+        uint256 panelId = polyptychProjectConfig.polyptychPanelId;
+        require(
+            !polyptychProjectConfig.polyptychPanelHashSeedIsMinted[panelId][
+                tokenHashSeed
+            ],
+            "Panel already minted"
+        );
+        // mark hash seed as used for the current panel
+        polyptychProjectConfig.polyptychPanelHashSeedIsMinted[panelId][
+            tokenHashSeed
+        ] = true;
+    }
+
+    /**
+     * @notice Sets the polyptych token hash seed on shared randomizer for a
+     * token ID on a core contract.
+     * @dev This function assumes the core contract is configured to use a
+     * shared randomizer that supports polyptych minting.
+     * @param coreContract Core contract address
+     * @param tokenId Token ID to set hash seed for
+     * @param hashSeed Hash seed to set
+     */
+    function setPolyptychHashSeed(
+        address coreContract,
+        uint256 tokenId,
+        bytes12 hashSeed
+    ) internal {
+        IGenArt721CoreContractV3WithSharedRandomizer(coreContract)
+            .randomizerContract()
+            .preSetHashSeed({
+                coreContract: coreContract,
+                tokenId: tokenId,
+                hashSeed: hashSeed
+            });
+    }
+
+    /**
+     * Validates that token hash seed is assigned to the token ID `tokenId` on
+     * the core contract `coreContract`.
+     * Reverts if hash seed is not assigned to the token ID.
+     * @param coreContract Core contract address
+     * @param tokenId Token ID to validate
+     * @param targetHashSeed target hash seed of `tokenId` on `coreContract`
+     */
+    function validateAssignedHashSeed(
+        address coreContract,
+        uint256 tokenId,
+        bytes12 targetHashSeed
+    ) internal view {
+        bytes12 assignedHashSeed = getTokenHashSeed({
+            coreContract: coreContract,
+            tokenId: tokenId
+        });
+        require(
+            assignedHashSeed == targetHashSeed,
+            "Unexpected token hash seed"
+        );
+    }
+
+    /**
+     * Gets token hash seed from core contract.
+     * Note that this function assumes the core contract conforms to
+     * `IGenArt721CoreContractExposesHashSeed`, which early versions of V3
+     * core contracts do not. If a contract does not conform to this interface,
+     * this function will revert.
+     * @param coreContract Core contract address
+     * @param tokenId Token ID to query hash seed for
+     */
+    function getTokenHashSeed(
+        address coreContract,
+        uint256 tokenId
+    ) internal view returns (bytes12) {
+        return
+            IGenArt721CoreContractExposesHashSeed(coreContract)
+                .tokenIdToHashSeed(tokenId);
+    }
+
+    /**
+     * Gets the current polyptych panel ID from polyptych project config.
+     * Polyptych panel ID is an incremented value that is used to track the
+     * current panel of a polyptych project.
+     * @param projectId Project ID to query
+     * @param coreContract Core contract address to query
+     */
+    function getPolyptychPanelId(
+        uint256 projectId,
+        address coreContract
+    ) internal view returns (uint256) {
+        PolyptychProjectConfig
+            storage polyptychProjectConfig = getPolyptychProjectConfig({
+                projectId: projectId,
+                coreContract: coreContract
+            });
+        return polyptychProjectConfig.polyptychPanelId;
+    }
+
+    /**
+     * Gets if a polyptych panel has already been minted for a given panel ID
+     * and hash seed.
+     * @param projectId Project ID to query
+     * @param coreContract Core contract address to query
+     * @param panelId Polyptych panel ID to query
+     * @param hashSeed Hash seed of panel to query
+     */
+    function getPolyptychPanelHashSeedIsMinted(
+        uint256 projectId,
+        address coreContract,
+        uint256 panelId,
+        bytes12 hashSeed
+    ) internal view returns (bool) {
+        PolyptychProjectConfig
+            storage polyptychProjectConfig = getPolyptychProjectConfig({
+                projectId: projectId,
+                coreContract: coreContract
+            });
+        return
+            polyptychProjectConfig.polyptychPanelHashSeedIsMinted[panelId][
+                hashSeed
+            ];
+    }
+
+    /**
+     * Loads the PolyptychProjectConfig 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 getPolyptychProjectConfig(
+        uint256 projectId,
+        address coreContract
+    ) internal view returns (PolyptychProjectConfig storage) {
+        return s().polyptychProjectConfigs[coreContract][projectId];
+    }
+
+    /**
+     * @notice Return the storage struct for reading and writing. This library
+     * uses a diamond storage pattern when managing storage.
+     * @return storageStruct The PolyptychLibStorage struct.
+     */
+    function s()
+        internal
+        pure
+        returns (PolyptychLibStorage storage storageStruct)
+    {
+        bytes32 position = POLYPTYCH_LIB_STORAGE_POSITION;
+        assembly ("memory-safe") {
+            storageStruct.slot := position
+        }
+    }
+}