@artblocks/contracts 1.3.2 → 1.4.0

package/contracts/interfaces/v0.8.x/IArtblocksRoyaltyOverride.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: LGPL-3.0-only
 // Created By: Art Blocks Inc.
 
-import "@openzeppelin-4.5/contracts/utils/introspection/IERC165.sol";
+import "@openzeppelin-5.0/contracts/utils/introspection/IERC165.sol";
 
 pragma solidity ^0.8.0;
 

package/contracts/interfaces/v0.8.x/IClaimMinter.sol

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title IClaimMinter
+ * @author Art Blocks Inc.
+ * @notice Interface for the ClaimMinter contract that enables admin to pre-mint tokens
+ * for a project and allows collectors to claim tokens in an arbitrary order with
+ * configurable pricing.
+ */
+interface IClaimMinter {
+    // Events
+    event PriceConfigured(uint256 basePriceInWei, uint256 priceIncrementInWei);
+    event TimestampStartConfigured(uint256 timestampStart);
+    event TokensPreMinted(uint256 amount);
+    event TokenClaimed(
+        uint256 indexed tokenId,
+        address indexed claimant,
+        uint256 price
+    );
+    event TokenWithdrawnAfterAuction(
+        uint256 indexed tokenNumber,
+        address indexed toAddress
+    );
+
+    /**
+     * @notice Returns all claimed bitmaps
+     * @return An array of all claimed bitmaps
+     */
+    function getAllClaimedBitmaps() external view returns (string memory);
+
+    /**
+     * @notice Sets the base price in wei for token 0 and the price increment in wei.
+     * Only callable by the core contract's Admin ACL.
+     * @param basePriceInWei_ Base price in wei for token 0.
+     * @param priceIncrementInWei_ Price increment in wei.
+     */
+    function configurePricePerTokenInWei(
+        uint256 basePriceInWei_,
+        uint256 priceIncrementInWei_
+    ) external;
+
+    /**
+     * @notice Sets the timestamp when claiming can begin.
+     * Only callable by the core contract's Admin ACL.
+     * @param timestampStart_ Unix timestamp when claiming can begin.
+     */
+    function configureTimestampStart(uint256 timestampStart_) external;
+
+    /**
+     * @notice Pre-mints `amount` tokens to this contract.
+     * @param amount Number of tokens to pre-mint.
+     */
+    function preMint(uint256 amount) external;
+
+    /**
+     * @notice Claims token `tokenId` by paying the required price.
+     * @param tokenNumber Token invocation number to claim.
+     */
+    function claimToken(uint256 tokenNumber) external payable;
+
+    /**
+     * @notice Checks if a token is claimed using bitmap storage
+     * @param tokenNumber The token invocation number
+     * @return True if the token is claimed
+     */
+    function isTokenClaimed(uint256 tokenNumber) external view returns (bool);
+}

package/contracts/interfaces/v0.8.x/IDependencyRegistryV0.sol

@@ -87,6 +87,89 @@ interface IDependencyRegistryV0 {
 
     event UniversalBytecodeStorageReaderUpdated(address indexed newReader);
 
+    event DependencyCanvasTagTypeUpdated(
+        bytes32 indexed dependencyNameAndVersion,
+        CanvasTagType canvasTagType
+    );
+
+    event DependencyLoadAsModuleUpdated(
+        bytes32 indexed dependencyNameAndVersion,
+        bool loadAsModule
+    );
+
+    event DependencyProjectScriptTagTypeUpdated(
+        bytes32 indexed dependencyNameAndVersion,
+        ProjectScriptTagType projectScriptTagType,
+        string projectScriptSpecialType
+    );
+
+    /**
+     * @notice Enum representing the canvas tag requirements for a dependency.
+     * @dev Conveys whether generated HTML must include a canvas tag, and where.
+     * @dev NoCanvasTag is the default value. No canvas tag is added to the generated HTML.
+     * @dev CanvasBeforeProjectScript adds a canvas tag before the project script.
+     * @dev CanvasAfterProjectScript adds a canvas tag after the project script.
+     */
+    enum CanvasTagType {
+        NoCanvasTag, // default
+        CanvasBeforeProjectScript,
+        CanvasAfterProjectScript
+    }
+
+    /**
+     * @notice Enum representing how a project's script must be injected into generated HTML.
+     * @dev ClassicScript is the default value. The project script is wrapped in a plain
+     * `<script>` tag, which is correct for the majority of dependencies.
+     * @dev Module wraps the project script in `<script type="module">`, for dependencies whose
+     * projects are authored as ES modules (e.g. those importing a bare specifier such as "three").
+     * @dev SpecialType wraps the project script in a `<script>` tag whose `type` attribute is set
+     * to the dependency's `projectScriptSpecialType` (e.g. "application/processing").
+     * @dev RawHtml injects the project script verbatim, with no wrapping tag, for dependencies
+     * whose project scripts are themselves complete HTML documents (e.g. "custom@na"). Generated
+     * HTML also omits the default style reset in this case, because the raw document owns its
+     * own styling.
+     */
+    enum ProjectScriptTagType {
+        ClassicScript, // default
+        Module,
+        SpecialType,
+        RawHtml
+    }
+
+    /**
+     * @notice Struct holding all details describing a dependency, including the fields that
+     * fully prescribe how the generator should render projects using it.
+     */
+    struct DependencyDetails {
+        // name and version of dependency (i.e. "name@version") used to identify dependency
+        string nameAndVersion;
+        // type of license, MIT, GPL, etc.
+        string licenseType;
+        // preferred CDN URL for dependency
+        string preferredCDN;
+        // count of additional CDN URLs for dependency
+        uint24 additionalCDNCount;
+        // preferred code repository URL for dependency
+        string preferredRepository;
+        // count of additional repository URLs for dependency
+        uint24 additionalRepositoryCount;
+        // project website URL for dependency
+        string dependencyWebsite;
+        // whether the dependency is available on chain
+        bool availableOnChain;
+        // count of on-chain scripts for dependency
+        uint24 scriptCount;
+        // whether the dependency's own script is an ES module, and therefore must be exposed to
+        // project scripts via an import map rather than loaded with a plain `<script src>` tag
+        bool loadAsModule;
+        // canvas tag requirement for the dependency
+        CanvasTagType canvasTagType;
+        // how a project's script must be injected into generated HTML
+        ProjectScriptTagType projectScriptTagType;
+        // `type` attribute used when projectScriptTagType is SpecialType; empty otherwise
+        string projectScriptSpecialType;
+    }
+
     /**
      * @notice Returns the count of scripts for dependency `dependencyNameAndVersion`.
      * @param dependencyNameAndVersion Dependency type to be queried.
@@ -117,6 +200,18 @@ interface IDependencyRegistryV0 {
     /**
      * @notice Returns details for a given dependency type `dependencyNameAndVersion`.
      * @param dependencyNameAndVersion Name and version of dependency (i.e. "name@version") used to identify dependency.
+     * @return dependencyDetails Details for the given dependency.
+     */
+    function getDependencyDetailsV2(
+        bytes32 dependencyNameAndVersion
+    ) external view returns (DependencyDetails memory dependencyDetails);
+
+    /**
+     * @notice Returns details for a given dependency type `dependencyNameAndVersion`.
+     * @dev Superseded by `getDependencyDetailsV2`, which additionally returns the fields
+     * prescribing how the generator renders projects using this dependency. Retained with an
+     * unchanged signature so that existing off-chain consumers continue to decode correctly.
+     * @param dependencyNameAndVersion Name and version of dependency (i.e. "name@version") used to identify dependency.
      * @return nameAndVersion String representation of `dependencyNameAndVersion`.
      *                        (e.g. "p5js(atSymbol)1.0.0")
      * @return licenseType License type for dependency

package/contracts/interfaces/v0.8.x/IEngineFactoryV0.sol

@@ -32,6 +32,11 @@ interface IEngineFactoryV0 {
      * new Engine or Engine Flex contracts.
      */
     event Abandoned();
+    /**
+     * @notice The default base URI host was updated.
+     * @param defaultBaseURIHost new default base URI host
+     */
+    event DefaultBaseURIHostUpdated(string defaultBaseURIHost);
 
     /**
      * @notice Creates a new Engine or Engine Flex contract with the provided
@@ -69,6 +74,16 @@ interface IEngineFactoryV0 {
      */
     function drainERC20(address ERC20TokenAddress, address recipient) external;
 
+    /**
+     * @notice Updates the default base URI host used when initializing new
+     * Engine contracts.
+     * Only callable by the owner.
+     * @param _defaultBaseURIHost New default base URI host.
+     */
+    function updateDefaultBaseURIHost(
+        string memory _defaultBaseURIHost
+    ) external;
+
     /**
      * @notice Calls transferOwnership on the core registry.
      * Useful for updating the owner of the core registry contract.

package/contracts/interfaces/v0.8.x/IGenArt721CoreContractV3_Base.sol

@@ -80,7 +80,9 @@ interface IGenArt721CoreContractV3_Base is IGenArt721CoreProjectScriptV1 {
         FIELD_PROJECT_SCRIPT_TYPE, // 13
         FIELD_PROJECT_ASPECT_RATIO, // 14
         FIELD_PROJECT_BASE_URI, // 15
-        FIELD_PROJECT_PROVIDER_SECONDARY_FINANCIALS // 16
+        FIELD_PROJECT_PROVIDER_SECONDARY_FINANCIALS, // 16
+        FIELD_PROJECT_TRANSFER_HOOK, // 17
+        FIELD_PROJECT_TRANSFER_HOOK_LOCKED // 18
     }
 
     /**
@@ -126,7 +128,11 @@ interface IGenArt721CoreContractV3_Base is IGenArt721CoreProjectScriptV1 {
         AspectRatioNoNumbers, // 34
         AspectRatioImproperFormat, // 35
         OnlyNullPlatformProvider, // 36
-        ContractInitialized // 37
+        ContractInitialized, // 37
+        TransferHookLocked, // 38
+        TransferHookInvalidInterface, // 39
+        TransferHookReentrancy, // 40
+        TransferHookUnexpectedHook // 41
     }
 
     /**
@@ -143,6 +149,19 @@ interface IGenArt721CoreContractV3_Base is IGenArt721CoreProjectScriptV1 {
      */
     event Mint(address indexed _to, uint256 indexed _tokenId);
 
+    /**
+     * @notice Token ID `_tokenId` minted to `_to`, with token hash
+     * `_tokenHash`.
+     * @dev New event in v3.2.9. When `_tokenHash` is non-zero, the token
+     * hash was assigned atomically during the mint transaction. When
+     * `_tokenHash` is bytes32(0), the hash has not yet been assigned.
+     */
+    event Mint(
+        address indexed _to,
+        uint256 indexed _tokenId,
+        bytes32 _tokenHash
+    );
+
     /**
      * @notice currentMinter updated to `_currentMinter`.
      * @dev Implemented starting with V3 core

package/contracts/interfaces/v0.8.x/IGenArt721CoreContractV3_Engine.sol

@@ -147,4 +147,76 @@ interface IGenArt721CoreContractV3_Engine is IGenArt721CoreContractV3_Base {
      * @return The address of the current split provider.
      */
     function splitProvider() external view returns (ISplitProviderV0);
+
+    /**
+     * @notice Project `_projectId` transfer hook updated to `_hook`.
+     * @dev New event in v3.3. `_hook` of `address(0)` means no hook is
+     * configured (today's transfer security profile).
+     */
+    event ProjectTransferHookUpdated(
+        uint256 indexed _projectId,
+        address indexed _hook
+    );
+
+    /**
+     * @notice Project `_projectId` transfer hook configuration has been
+     * permanently locked at `_hook` (which may be `address(0)`).
+     * @dev New event in v3.3. One-way. Auto-lock at `address(0)` when the
+     * four-week project metadata lock elapses with no hook set does not emit
+     * this event (it is time-based, not a transaction).
+     */
+    event ProjectTransferHookLocked(
+        uint256 indexed _projectId,
+        address indexed _hook
+    );
+
+    /**
+     * @notice Set or clear the transfer hook for project `_projectId`.
+     * @dev New function in v3.3. Artist or Admin ACL. Reverts if locked:
+     * either `lockProjectTransferHook` was called, or the four-week project
+     * metadata lock elapsed while the hook is `address(0)`. After auto-lock,
+     * a hook that is already set remains configurable until the artist locks.
+     * A non-zero hook must ERC-165-advertise `ITransferHook`
+     * (interface ID `0x6344b0e2`). `address(0)` clears the hook.
+     * @param _projectId Project ID.
+     * @param _hook Hook contract, or `address(0)` to clear.
+     */
+    function configureProjectTransferHook(
+        uint256 _projectId,
+        address _hook
+    ) external;
+
+    /**
+     * @notice Permanently lock the transfer hook for project `_projectId` at
+     * `_expectedHook`, which may be `address(0)`.
+     * @dev New function in v3.3. Artist only. If locked at `address(0)`, a
+     * hook can never be assigned — restoring today's transfer security
+     * profile. If the four-week project metadata lock elapsed with no hook
+     * set, the configuration is already locked and this reverts.
+     * @dev `_expectedHook` must equal the project's currently configured hook.
+     * Because locking is permanent and the hook may be updated by either the
+     * artist or the Admin ACL, this guards against a `configureProjectTransferHook`
+     * call landing first and causing an unintended hook to be locked in.
+     * @dev WARNING: locking freezes the hook address, not the hook's behavior.
+     * Locking at an upgradeable proxy leaves its owner able to change what runs
+     * on every transfer, with no way for the project to move away from it.
+     * @param _projectId Project ID.
+     * @param _expectedHook Hook the caller expects to lock in. Reverts with
+     * `TransferHookUnexpectedHook` if it does not match the current hook.
+     */
+    function lockProjectTransferHook(
+        uint256 _projectId,
+        address _expectedHook
+    ) external;
+
+    /**
+     * @notice Transfer hook configuration for project `_projectId`.
+     * @return hook Hook address, or `address(0)` if none is configured.
+     * @return locked True if the artist called `lockProjectTransferHook`, or
+     * if the four-week project metadata lock elapsed while the hook is
+     * `address(0)`.
+     */
+    function projectTransferHookConfig(
+        uint256 _projectId
+    ) external view returns (address hook, bool locked);
 }

package/contracts/interfaces/v0.8.x/IOwnerHistoryTransferHook.sol

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+pragma solidity ^0.8.0;
+
+import {ITransferHook} from "./ITransferHook.sol";
+
+/**
+ * @title Interface for the on-chain owner history transfer hook.
+ * @author Art Blocks Inc.
+ * @notice Reference `ITransferHook` implementation that records every owner a
+ * token has had, on chain, for projects that opt in.
+ */
+interface IOwnerHistoryTransferHook is ITransferHook {
+    /**
+     * @notice One entry in a token's ownership chain.
+     * @dev Packed into a single storage slot: 20-byte address + 12-byte
+     * timestamp. `uint96` seconds is not a real bound.
+     */
+    struct OwnerRecord {
+        address owner;
+        uint96 timestamp;
+    }
+
+    /**
+     * @notice Token `tokenId` on `coreContract` recorded `owner` at
+     * `index` in its ownership chain.
+     * @dev Index 0 is the owner that preceded the first change this hook saw:
+     * `address(0)` when the hook was configured before the token was minted,
+     * and otherwise the owner at the moment the hook started tracking.
+     */
+    event OwnerRecorded(
+        address indexed coreContract,
+        uint256 indexed tokenId,
+        address indexed owner,
+        uint256 index,
+        uint256 timestamp
+    );
+
+    /**
+     * @notice Thrown when the calling core does not have this hook configured
+     * for the token's project.
+     */
+    error HookNotConfiguredForProject(
+        address coreContract,
+        uint256 projectId,
+        address configuredHook
+    );
+
+    /**
+     * @notice Full ownership chain recorded for a token, oldest first.
+     * @dev Unbounded; use `ownerHistorySlice` for tokens with long histories.
+     * @param coreContract Core contract the token belongs to.
+     * @param tokenId Token ID.
+     */
+    function ownerHistory(
+        address coreContract,
+        uint256 tokenId
+    ) external view returns (OwnerRecord[] memory records);
+
+    /**
+     * @notice A page of a token's ownership chain, oldest first.
+     * @param coreContract Core contract the token belongs to.
+     * @param tokenId Token ID.
+     * @param start Index to start at.
+     * @param count Maximum number of records to return. The returned array is
+     * shorter than `count` when fewer records remain.
+     */
+    function ownerHistorySlice(
+        address coreContract,
+        uint256 tokenId,
+        uint256 start,
+        uint256 count
+    ) external view returns (OwnerRecord[] memory records);
+
+    /**
+     * @notice Number of records in a token's ownership chain.
+     */
+    function ownerHistoryLength(
+        address coreContract,
+        uint256 tokenId
+    ) external view returns (uint256);
+
+    /**
+     * @notice Owners a token has had, excluding the most recently recorded one.
+     * @dev Excludes the `address(0)` anchor of a token tracked from its mint,
+     * which is not an owner; for a token first seen mid-life, the anchor is the
+     * real owner at that moment and is included. Empty until a token has
+     * changed hands at least once while tracked.
+     */
+    function previousOwners(
+        address coreContract,
+        uint256 tokenId
+    ) external view returns (address[] memory owners);
+
+    /**
+     * @notice Most recently recorded owner of a token.
+     * @dev This is the token's current owner while the hook stays configured
+     * for its project. If the project's hook is cleared, transfers stop being
+     * recorded and this becomes the owner as of the last recorded transfer, so
+     * consumers that need the live owner should call `ownerOf` on the core.
+     * @return owner Most recent recorded owner, or `address(0)` if the token
+     * has never been recorded.
+     */
+    function lastRecordedOwner(
+        address coreContract,
+        uint256 tokenId
+    ) external view returns (address owner);
+
+    /**
+     * @notice Whether a token's recorded chain begins at its mint, which is the
+     * case only if this hook was configured for the project before the token
+     * was minted.
+     */
+    function isTrackedFromMint(
+        address coreContract,
+        uint256 tokenId
+    ) external view returns (bool);
+}

package/contracts/interfaces/v0.8.x/ISRHooks.sol

@@ -0,0 +1,229 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Creatd By: Art Blocks Inc.
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title ISRHooks
+ * @author Art Blocks Inc.
+ * @notice This interface defines the custom events and functions for the SRHooks contract.
+ * It does not include any of the IPMPV0 events, which are indexed separately.
+ */
+interface ISRHooks {
+    /**
+     * @notice Emitted when the contract is initialized
+     * @param coreContractAddress The address of the core contract.
+     * @param coreProjectId The project ID of the core contract.
+     */
+    event SRHooksInitialized(
+        address coreContractAddress,
+        uint256 coreProjectId
+    );
+
+    /**
+     * @notice Emitted when the tokens sending to a token are updated
+     * @param coreContract The address of the core contract.
+     * @param tokenId The ID of the token.
+     * @param tokensSendingTo The tokens sending to the token.
+     */
+    event TokenSendingToUpdated(
+        address indexed coreContract,
+        uint256 indexed tokenId,
+        uint16[] tokensSendingTo
+    );
+
+    /**
+     * @notice Emitted when the tokens sending to a token are updated
+     * @param coreContract The address of the core contract.
+     * @param tokenId The ID of the token.
+     * @param tokensReceivingFrom The tokens receiving from the token.
+     */
+    event TokenReceivingFromUpdated(
+        address indexed coreContract,
+        uint256 indexed tokenId,
+        uint16[] tokensReceivingFrom
+    );
+
+    /**
+     * @notice Struct for the token metadata calldata.
+     * @param updateImage Whether to update the image data.
+     * @param imageDataCompressed The compressed image data.
+     * @param updateSound Whether to update the sound data.
+     * @param soundDataCompressed The compressed sound data.
+     */
+    struct TokenMetadataCalldata {
+        bool updateImage; // true if updating the image data
+        bytes imageDataCompressed; // non-empty if updating the image data
+        bool updateSound; // true if updating the sound data
+        bytes soundDataCompressed; // may be empty to clear the sound data, non-empty if setting the sound data
+    }
+
+    /**
+     * @notice Struct for the token metadata view.
+     * @param imageDataCompressed The compressed image data.
+     * @param imageVersion The version of the image data.
+     * @param soundDataCompressed The compressed sound data.
+     * @param soundVersion The version of the sound data.
+     */
+    struct TokenMetadataView {
+        bytes imageDataCompressed;
+        uint16 imageVersion;
+        bytes soundDataCompressed;
+        uint16 soundVersion;
+    }
+
+    struct TokenLiveData {
+        uint256 tokenNumber;
+        address ownerAddress;
+        bytes imageDataCompressed;
+        bytes soundDataCompressed;
+        string ownerEnsName;
+    }
+
+    // enum for the different possible states of a token's SR configuration
+    enum SendStates {
+        Neutral,
+        SendGeneral,
+        SendTo
+    }
+
+    enum ReceiveStates {
+        Neutral,
+        ReceiveGeneral,
+        ReceiveFrom,
+        ReceiveTo
+    }
+
+    /**
+     * @notice Updates the state and metadata for a given token.
+     * Reverts if the token number is invalid or the msg.sender is not owner or valid delegate.xyz V2 of token owner.
+     * Reverts if invalid configuration is provided.
+     * Includes two boolean flags to update the send and receive states and token metadata separately, in a single function call.
+     * Never allows updating to a slot that is invalid.
+     * @param tokenNumber The token number to update.
+     * @param updateSendState Whether to update the send state.
+     * @param sendState The new send state. Valid values are SendGeneral, SendTo, Neutral.
+     * @param tokensSendingTo Tokens to send this token to. Only non-empty iff updateSendState is true and sendState is SendTo.
+     * Duplicates are automatically deduplicated when calculating dilution rates.
+     * @param updateReceiveState Whether to update the receive state.
+     * @param receiveState The new receive state. Valid values are ReceiveGeneral, ReceiveFrom, Neutral.
+     * @param tokensReceivingFrom Tokens this token is open to receive from. Only non-empty iff updateReceiveState is true and receiveState is ReceiveFrom.
+     * Duplicates and self-referential entries are automatically filtered in getLiveData results.
+     * @param updateTokenMetadata Whether to update the token metadata.
+     * @param updatedActiveSlot The new active slot. If updating token metadata, this is the new active slot.
+     * @param tokenMetadataCalldata The new token metadata. If updating token metadata, this is the new token metadata at the updated active slot. Only non-empty iff updateTokenMetadata is true.
+     */
+    function updateTokenStateAndMetadata(
+        uint256 tokenNumber,
+        bool updateSendState,
+        SendStates sendState,
+        uint16[] memory tokensSendingTo,
+        bool updateReceiveState,
+        ReceiveStates receiveState,
+        uint16[] memory tokensReceivingFrom,
+        bool updateTokenMetadata,
+        uint256 updatedActiveSlot,
+        TokenMetadataCalldata memory tokenMetadataCalldata
+    ) external;
+
+    /**
+     * @notice Gets the live data for a given token.
+     * @param tokenNumber The token number to get the live data for.
+     * @param blockNumber The block number to get the live data for. Must be in latest 256 blocks.
+     * @param maxReceive The maximum number of tokens to receive, in each array of receivedTokensGeneral and receivedTokensTo.
+     * maxReceive must be less than or equal to MAX_RECEIVE_RATE_PER_BLOCK.
+     * Treats block number of 0 as latest completed block.
+     * Reverts if block number is in future - need block hash to be defined.
+     * NOTE: Each array of receivedTokensGeneral and receivedTokensTo has a maximum length of maxReceive,
+     * but their combined length may be greater than maxReceive. The art script should handle this by
+     * deterministically shuffling/sampling from the arrays if desired.
+     * WARNING: This function is designed for off-chain view calls only and may exceed block gas limits in cases where
+     * a token has many senders or is receiving from many tokens. It is not intended to be called within transactions.
+     * WARNING: Self-referential SendGeneral and SendTo tokens may be included in the results.
+     * @return sendState The send state of the token.
+     * @return receiveState The receive state of the token.
+     * @return receivedTokensGeneral The received tokens general of the token.
+     * @return receivedTokensTo The received tokens to of the token.
+     * @return numSendGeneral The number of tokens in the send general pool.
+     * @return numReceiveGeneral The number of tokens in the receive general pool.
+     * @return numSendingToMe The number of tokens sending to me.
+     * @return usedBlockNumber The block number used to generate the random numbers.
+     */
+    function getLiveData(
+        uint256 tokenNumber,
+        uint256 blockNumber,
+        uint256 maxReceive
+    )
+        external
+        view
+        returns (
+            SendStates sendState,
+            ReceiveStates receiveState,
+            TokenLiveData[] memory receivedTokensGeneral,
+            TokenLiveData[] memory receivedTokensTo,
+            uint256 numSendGeneral,
+            uint256 numReceiveGeneral,
+            uint256 numSendingToMe,
+            uint256 usedBlockNumber
+        );
+
+    /**
+     * @notice Gets the state of the general pools.
+     * @return sendGeneralTokensLength The length of the send general tokens.
+     * @return receiveGeneralTokensLength The length of the receive general tokens.
+     */
+    function getGeneralPoolState()
+        external
+        view
+        returns (
+            uint256 sendGeneralTokensLength,
+            uint256 receiveGeneralTokensLength
+        );
+
+    /**
+     * @notice Gets the state of a given token.
+     * @param tokenNumber The token number to get the state for.
+     * @return sendState The send state.
+     * @return receiveState The receive state.
+     * @return tokensSendingTo The tokens sending to the token.
+     * @return tokensReceivingFrom The tokens receiving from the token.
+     * @return activeSlot The active slot.
+     * @return activeSlotTokenMetadata The token metadata at the active slot.
+     * @return ownerAddress The address of the token owner.
+     */
+    function getTokenState(
+        uint256 tokenNumber
+    )
+        external
+        view
+        returns (
+            SendStates sendState,
+            ReceiveStates receiveState,
+            uint16[] memory tokensSendingTo,
+            uint16[] memory tokensReceivingFrom,
+            uint256 activeSlot,
+            TokenMetadataView memory activeSlotTokenMetadata,
+            address ownerAddress
+        );
+
+    /**
+     * @notice Gets the token metadata at a given slot.
+     * @param tokenNumber The token number to get the token metadata for.
+     * @param slot The slot to get the token metadata for.
+     * @return tokenMetadata The token metadata at the given slot.
+     */
+    function getTokenMetadataAtSlot(
+        uint256 tokenNumber,
+        uint256 slot
+    ) external view returns (TokenMetadataView memory tokenMetadata);
+
+    /**
+     * @notice Gets the tokens sending to a given token.
+     * WARNING: This function is unbounded in gas cost, and is designed to be used by view accessors only. Use with caution.
+     * @param tokenNumber The token number to get the tokens sending to for.
+     * @return tokensSendingTo The token numbers sending to the given token.
+     */
+    function getTokensSendingToToken(
+        uint256 tokenNumber
+    ) external view returns (uint256[] memory tokensSendingTo);
+}