@artblocks/contracts 1.0.2 → 1.0.4

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

@@ -0,0 +1,348 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+import "../../../interfaces/v0.8.x/IGenArt721CoreContractV3_Base.sol";
+
+import "@openzeppelin-4.7/contracts/utils/math/Math.sol";
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title Art Blocks Max Invocations Library
+ * @notice This library manages the maximum invocation limits for Art Blocks
+ * projects. It provides functionality for synchronizing, manually limiting, and
+ * updating these limits, ensuring the integrity in relation to the core Art
+ * Blocks contract, and managing updates upon token minting.
+ * @dev Functions include `syncProjectMaxInvocationsToCore`,
+ * `manuallyLimitProjectMaxInvocations`, and `purchaseEffectsInvocations`.
+ * @author Art Blocks Inc.
+ */
+
+library MaxInvocationsLib {
+    uint256 internal constant ONE_MILLION = 1_000_000;
+
+    /**
+     * @notice Data structure that holds max invocations project configuration.
+     */
+    struct MaxInvocationsProjectConfig {
+        bool maxHasBeenInvoked;
+        uint24 maxInvocations;
+    }
+
+    /**
+     * @notice Syncs project's max invocations to core contract value.
+     * @param _projectId The id of the project.
+     * @param _coreContract The address of the core contract.
+     * @param maxInvocationsProjectConfig Data structure that holds max invocations project configuration.
+     * @return uint256 the updated max invocations.
+     */
+    function syncProjectMaxInvocationsToCore(
+        uint256 _projectId,
+        address _coreContract,
+        MaxInvocationsProjectConfig storage maxInvocationsProjectConfig
+    ) internal returns (uint256) {
+        uint256 maxInvocations;
+        uint256 invocations;
+        (invocations, maxInvocations, , , , ) = IGenArt721CoreContractV3_Base(
+            _coreContract
+        ).projectStateData(_projectId);
+        // update storage with results
+        maxInvocationsProjectConfig.maxInvocations = uint24(maxInvocations);
+
+        // We need to ensure maxHasBeenInvoked is correctly set after manually syncing the
+        // local maxInvocations value with the core contract's maxInvocations value.
+        // This synced value of maxInvocations from the core contract will always be greater
+        // than or equal to the previous value of maxInvocations stored locally.
+        maxInvocationsProjectConfig.maxHasBeenInvoked =
+            invocations == maxInvocations;
+        return maxInvocations;
+    }
+
+    /**
+     * @notice Manually limits project's max invocations.
+     * @param _projectId The id of the project.
+     * @param _coreContract The address of the core contract.
+     * @param _maxInvocations The new max invocations limit.
+     * @param maxInvocationsProjectConfig Data structure that holds max invocations project configuration.
+     */
+    function manuallyLimitProjectMaxInvocations(
+        uint256 _projectId,
+        address _coreContract,
+        uint24 _maxInvocations,
+        MaxInvocationsProjectConfig storage maxInvocationsProjectConfig
+    ) internal {
+        // CHECKS
+        (
+            uint256 coreInvocations,
+            uint256 coreMaxInvocations
+        ) = coreContractInvocationData(_projectId, _coreContract);
+        require(
+            _maxInvocations <= coreMaxInvocations,
+            "Invalid max invocations"
+        );
+        require(_maxInvocations >= coreInvocations, "Invalid max invocations");
+
+        // EFFECTS
+        // update storage with results
+        maxInvocationsProjectConfig.maxInvocations = uint24(_maxInvocations);
+        // We need to ensure maxHasBeenInvoked is correctly set after manually setting the
+        // local maxInvocations value.
+        maxInvocationsProjectConfig.maxHasBeenInvoked =
+            coreInvocations == _maxInvocations;
+    }
+
+    /**
+     * @notice Validate effects on invocations after purchase. This ensures
+     * that the token invocation is less than or equal to the local max
+     * invocations, and also updates the local maxHasBeenInvoked value.
+     * @dev This function checks that the token invocation is less than or
+     * equal to the local max invocations, and also updates the local
+     * maxHasBeenInvoked value.
+     * @param _tokenId The id of the token.
+     * @param maxInvocationsProjectConfig Data structure that holds max
+     * invocations project configuration.
+     */
+    function validatePurchaseEffectsInvocations(
+        uint256 _tokenId,
+        MaxInvocationsProjectConfig storage maxInvocationsProjectConfig
+    ) internal {
+        // invocation is token number plus one, and will never overflow due to
+        // limit of 1e6 invocations per project. block scope for gas efficiency
+        // (i.e. avoid an unnecessary var initialization to 0).
+        unchecked {
+            uint256 tokenInvocation = (_tokenId % ONE_MILLION) + 1;
+            uint256 localMaxInvocations = maxInvocationsProjectConfig
+                .maxInvocations;
+            // handle the case where the token invocation == minter local max
+            // invocations occurred on a different minter, and we have a stale
+            // local maxHasBeenInvoked value returning a false negative.
+            // @dev this is a CHECK after EFFECTS, so security was considered
+            // in detail here.
+            require(
+                tokenInvocation <= localMaxInvocations,
+                "Max invocations reached"
+            );
+            // in typical case, update the local maxHasBeenInvoked value
+            // to true if the token invocation == minter local max invocations
+            // (enables gas efficient reverts after sellout)
+            if (tokenInvocation == localMaxInvocations) {
+                maxInvocationsProjectConfig.maxHasBeenInvoked = true;
+            }
+        }
+    }
+
+    /**
+     * Helper function to check if max invocations has not been initialized.
+     * Returns true if not initialized, false if initialized.
+     * @param _maxInvocationsProjectConfig Struct that holds max invocations
+     * project configuration.
+     * @return bool
+     * @dev We know a project's max invocations have never been initialized if
+     * both max invocations and maxHasBeenInvoked are still initial values.
+     * This is because if maxInvocations were ever set to zero,
+     * maxHasBeenInvoked would be set to true.
+     */
+    function maxInvocationsIsUnconfigured(
+        MaxInvocationsProjectConfig storage _maxInvocationsProjectConfig
+    ) internal view returns (bool) {
+        return
+            _maxInvocationsProjectConfig.maxInvocations == 0 &&
+            !_maxInvocationsProjectConfig.maxHasBeenInvoked;
+    }
+
+    /**
+     * Returns if invocations remain available for a given project.
+     * This function calls the core contract to get the most up-to-date
+     * invocation data (which may be useful to avoid reverts during mint).
+     * This function considers core contract max invocations, and minter local
+     * max invocations, and returns a response based on the most limiting
+     * max invocations value.
+     * @param _maxInvocationsProjectConfig Struct that holds minter-level max
+     * invocations
+     * @param _projectId The id of the project.
+     * @param _coreContract The address of the core contract.
+     */
+    function invocationsRemain(
+        MaxInvocationsProjectConfig storage _maxInvocationsProjectConfig,
+        uint256 _projectId,
+        address _coreContract
+    ) internal view returns (bool) {
+        // get up-to-data invocation data from core contract
+        (
+            uint256 coreInvocations,
+            uint256 coreMaxInvocations
+        ) = MaxInvocationsLib.coreContractInvocationData(
+                _projectId,
+                _coreContract
+            );
+        // load minter-local max invocations into memory
+        uint256 localMaxInvocations = _maxInvocationsProjectConfig
+            .maxInvocations;
+        // invocations remain available if the core contract has not reached
+        // the most limiting max invocations, either on minter or core contract
+        uint256 limitingMaxInvocations = Math.min(
+            coreMaxInvocations,
+            localMaxInvocations
+        );
+        return coreInvocations < limitingMaxInvocations;
+    }
+
+    /**
+     * Pulls core contract invocation data for a given project.
+     * @dev This function calls the core contract to get the invocation data
+     * @param _projectId The id of the project.
+     * @param _coreContract The address of the core contract.
+     * @return coreInvocations The number of invocations for the project.
+     * @return coreMaxInvocations The max invocations for the project, as
+     * defined on the core contract.
+     */
+    function coreContractInvocationData(
+        uint256 _projectId,
+        address _coreContract
+    )
+        internal
+        view
+        returns (uint256 coreInvocations, uint256 coreMaxInvocations)
+    {
+        (
+            coreInvocations,
+            coreMaxInvocations,
+            ,
+            ,
+            ,
+
+        ) = IGenArt721CoreContractV3_Base(_coreContract).projectStateData(
+            _projectId
+        );
+    }
+
+    /**
+     * Returns the max invocations for a given MaxInvocationsProjectConfig.
+     * @param _maxInvocationsProjectConfig MaxInvocationsProjectConfig struct
+     * to be queried.
+     */
+    function getMaxInvocations(
+        MaxInvocationsProjectConfig storage _maxInvocationsProjectConfig
+    ) internal view returns (uint256) {
+        return _maxInvocationsProjectConfig.maxInvocations;
+    }
+
+    /**
+     * Returns if max has been invoked for a given MaxInvocationsProjectConfig.
+     * @param _maxInvocationsProjectConfig MaxInvocationsProjectConfig struct
+     * to be queried.
+     */
+    function getMaxHasBeenInvoked(
+        MaxInvocationsProjectConfig storage _maxInvocationsProjectConfig
+    ) internal view returns (bool) {
+        return _maxInvocationsProjectConfig.maxHasBeenInvoked;
+    }
+
+    /**
+     * Get if a project has reached its max invocations.
+     * Function is labaled as "safe" because it checks the core contract's
+     * invocations and max invocations. If the local max invocations is greater
+     * than the core contract's max invocations, it will defer to the core
+     * contract's max invocations (since those are the limiting factor).
+     * @param _projectId The id of the project.
+     * @param _coreContract The address of the core contract.
+     * @param _maxInvocationsProjectConfig MaxInvocationsProjectConfig struct
+     */
+    function projectMaxHasBeenInvokedSafe(
+        uint256 _projectId,
+        address _coreContract,
+        MaxInvocationsProjectConfig storage _maxInvocationsProjectConfig
+    ) internal view returns (bool) {
+        // get max invocations from core contract
+        uint256 coreInvocations;
+        uint256 coreMaxInvocations;
+        (coreInvocations, coreMaxInvocations) = MaxInvocationsLib
+            .coreContractInvocationData(_projectId, _coreContract);
+        uint256 localMaxInvocations = _maxInvocationsProjectConfig
+            .maxInvocations;
+        // value is locally defined, and could be out of date.
+        // only possible illogical state is if local max invocations is
+        // greater than core contract's max invocations, in which case
+        // we should use the core contract's max invocations
+        if (localMaxInvocations > coreMaxInvocations) {
+            // local max invocations is stale and illogical, defer to core
+            // contract's max invocations since it is the limiting factor
+            return (coreMaxInvocations == coreInvocations);
+        }
+        // local max invocations is limiting, so check core invocations against
+        // local max invocations
+        return (coreInvocations >= localMaxInvocations);
+    }
+
+    /**
+     * @notice Refreshes max invocations to account for core contract max
+     * invocations state, without imposing any additional restrictions on the
+     * minter's max invocations state.
+     * If minter max invocations have never been populated, this function will
+     * populate them to equal the core contract's max invocations state (which
+     * is the least restrictive state).
+     * If minter max invocations have been populated, this function will ensure
+     * the minter's max invocations are not greater than the core contract's
+     * max invocations (which would be stale and illogical), and update the
+     * minter's max invocations and maxHasBeenInvoked state to be consistent
+     * with the core contract's max invocations.
+     * If the minter max invocations have been populated and are not greater
+     * than the core contract's max invocations, this function will do nothing,
+     * since that is a valid state in which the minter has been configured to
+     * be more restrictive than the core contract.
+     * @dev assumes core contract's max invocations may only be reduced, which
+     * is the case for all V3 core contracts
+     */
+    function refreshMaxInvocations(
+        uint256 _projectId,
+        address _coreContract,
+        MaxInvocationsProjectConfig storage _maxInvocationsProjectConfig
+    ) internal returns (bool maxInvocationsUpdated) {
+        if (maxInvocationsIsUnconfigured(_maxInvocationsProjectConfig)) {
+            // populate the minter max invocation state to equal the values on
+            // the core contract (least restrictive state)
+            MaxInvocationsLib.syncProjectMaxInvocationsToCore(
+                _projectId,
+                _coreContract,
+                _maxInvocationsProjectConfig
+            );
+            // return true to indicate max invocation state update
+            maxInvocationsUpdated = true;
+        } else {
+            // if local max invocations were already populated, validate the local state
+            uint256 coreMaxInvocations;
+            uint256 coreInvocations;
+            (coreInvocations, coreMaxInvocations) = MaxInvocationsLib
+                .coreContractInvocationData(_projectId, _coreContract);
+
+            uint256 localMaxInvocations = _maxInvocationsProjectConfig
+                .maxInvocations;
+            if (localMaxInvocations > coreMaxInvocations) {
+                // if local max invocations are greater than core max invocations, make
+                // them equal since that is the least restrictive logical state
+                // @dev this is only possible if the core contract's max invocations
+                // have been reduced since the minter's max invocations were last
+                // updated
+                // set local max invocations to core contract's max invocations
+                _maxInvocationsProjectConfig.maxInvocations = uint24(
+                    coreMaxInvocations
+                );
+                // update the minter's `maxHasBeenInvoked` state
+                _maxInvocationsProjectConfig
+                    .maxHasBeenInvoked = (coreMaxInvocations ==
+                    coreInvocations);
+                // return true to indicate max invocation state update
+                maxInvocationsUpdated = true;
+            } else if (coreInvocations >= localMaxInvocations) {
+                // core invocations are greater than this minter's max
+                // invocations, indicating that minting must have occurred on
+                // another minter. update the minter's `maxHasBeenInvoked` to
+                // true to prevent any false negatives on
+                // `getMaxHasBeenInvoked'
+                _maxInvocationsProjectConfig.maxHasBeenInvoked = true;
+                // @dev do not return true, because we did not change the value
+                // of minter-local max invocations
+            }
+        }
+    }
+}

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

@@ -0,0 +1,175 @@
+// 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;
+
+/**
+ * @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[];
+
+    /// @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 => uint256) userMintInvocations;
+    }
+
+    /**
+     * @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.
+     */
+    function setProjectInvocationsPerAddress(
+        MerkleProjectConfig storage _projectConfig,
+        uint24 _maxInvocationsPerAddress
+    ) internal {
+        _projectConfig.useMaxInvocationsPerAddressOverride = true;
+        _projectConfig
+            .maxInvocationsPerAddressOverride = _maxInvocationsPerAddress;
+    }
+
+    /**
+     * @notice Updates the Merkle root of a project.
+     * @param _projectConfig Merkle project config.
+     * @param _root The new Merkle root.
+     */
+    function updateMerkleRoot(
+        MerkleProjectConfig storage _projectConfig,
+        bytes32 _root
+    ) internal {
+        require(_root != bytes32(0), "Must provide root");
+        _projectConfig.merkleRoot = _root;
+    }
+
+    /**
+     * @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 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.
+     */
+    function verifyAddress(
+        bytes32 _proofRoot,
+        bytes32[] calldata _proof,
+        address _address
+    ) internal pure returns (bool) {
+        return _proof.verifyCalldata(_proofRoot, 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 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.
+     */
+    function projectRemainingInvocationsForAddress(
+        MerkleProjectConfig storage _projectConfig,
+        address _address
+    )
+        internal
+        view
+        returns (
+            bool projectLimitsMintInvocationsPerAddress,
+            uint256 mintInvocationsRemaining
+        )
+    {
+        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
+        }
+    }
+}

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

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+import "../../../interfaces/v0.8.x/IGenArt721CoreContractV3_Base.sol";
+import "../../../interfaces/v0.8.x/IGenArt721CoreContractExposesHashSeed.sol";
+import "../../../interfaces/v0.8.x/IGenArt721CoreContractV3WithSharedRandomizer.sol";
+import "../../../interfaces/v0.8.x/ISharedRandomizerV0.sol";
+
+import "@openzeppelin-4.7/contracts/token/ERC20/IERC20.sol";
+
+pragma solidity ^0.8.0;
+
+/**
+ * @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";
+
+    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
+        // panelId => hashSeed => panelIsMinted
+        mapping(uint256 => mapping(bytes12 => bool)) polyptychPanelHashSeedIsMinted;
+    }
+
+    /**
+     * @notice Increments the minter to the next polyptych panel of a given project
+     * @param _polyptychProjectConfig Project ID to increment to its next polyptych panel
+     */
+    function incrementPolyptychProjectPanelId(
+        PolyptychProjectConfig storage _polyptychProjectConfig
+    ) internal {
+        ++_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 _polyptychProjectConfig polyptych project config
+     * @param _tokenHashSeed token hash seed
+     */
+    function validatePolyptychEffects(
+        PolyptychProjectConfig storage _polyptychProjectConfig,
+        bytes12 _tokenHashSeed
+    ) internal {
+        // 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, _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 _polyptychProjectConfig Polyptych project config struct to query
+     */
+    function getPolyptychPanelId(
+        PolyptychProjectConfig storage _polyptychProjectConfig
+    ) internal view returns (uint256) {
+        return _polyptychProjectConfig.polyptychPanelId;
+    }
+
+    /**
+     * Gets if a polyptych panel has already been minted for a given panel ID
+     * and hash seed.
+     * @param _polyptychProjectConfig Polyptych project config struct to query
+     * @param _panelId Polyptych panel ID to query
+     * @param _hashSeed Hash seed of panel to query
+     */
+    function getPolyptychPanelHashSeedIsMinted(
+        PolyptychProjectConfig storage _polyptychProjectConfig,
+        uint256 _panelId,
+        bytes12 _hashSeed
+    ) internal view returns (bool) {
+        return
+            _polyptychProjectConfig.polyptychPanelHashSeedIsMinted[_panelId][
+                _hashSeed
+            ];
+    }
+}