@artblocks/contracts 1.3.1 → 1.4.0

package/contracts/web3call/augment-hooks/SRHooks.sol

@@ -0,0 +1,1722 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+pragma solidity 0.8.22;
+
+import {AbstractPMPAugmentHook} from "../augment-hooks/AbstractPMPAugmentHook.sol";
+
+import {IWeb3Call} from "../../interfaces/v0.8.x/IWeb3Call.sol";
+import {IPMPV0} from "../../interfaces/v0.8.x/IPMPV0.sol";
+import {ISRHooks} from "../../interfaces/v0.8.x/ISRHooks.sol";
+import {Strings} from "@openzeppelin-5.0/contracts/utils/Strings.sol";
+import {IERC721} from "@openzeppelin-5.0/contracts/interfaces/IERC721.sol";
+import {IDelegationRegistry as IDelegationRegistryV1} from "../../interfaces/v0.8.x/IDelegationRegistry.sol";
+import {IDelegateRegistry as IDelegationRegistryV2} from "../../interfaces/v0.8.x/IDelegateRegistry.sol";
+import {IPMPConfigureHook} from "../../interfaces/v0.8.x/IPMPConfigureHook.sol";
+import {IPMPAugmentHook} from "../../interfaces/v0.8.x/IPMPAugmentHook.sol";
+
+import {SafeCast} from "@openzeppelin-5.0/contracts/utils/math/SafeCast.sol";
+import {Initializable} from "@openzeppelin-5.0/contracts-upgradeable/proxy/utils/Initializable.sol";
+import {UUPSUpgradeable} from "@openzeppelin-5.0/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
+import {OwnableUpgradeable} from "@openzeppelin-5.0/contracts-upgradeable/access/OwnableUpgradeable.sol";
+
+import {ImmutableUint16Array} from "../../libs/v0.8.x/ImmutableUint16Array.sol";
+import {SSTORE2} from "../../libs/v0.8.x/SSTORE2.sol";
+import {ABHelpers} from "../../libs/v0.8.x/ABHelpers.sol";
+import {FeistelWalkLib} from "../../libs/v0.8.x/FeistelWalkLib.sol";
+import {ENSLib} from "../../libs/v0.8.x/ENSLib.sol";
+import {EnumerableSetUint16} from "../../libs/v0.8.x/EnumerableSetUint16.sol";
+
+/**
+ * @title SRHooks
+ * @author Art Blocks Inc.
+ * @notice This hook tracks the send and receive states of a token, and the metadata for a token.
+ * It implements the primary functionality of the SR project, and accepts most calls directly.
+ * It acts as a PMPV0 hook, and therefore derives from AbstractPMPAugmentHook.
+ * For clear off-chain provenance indexing and efficiency purposes, it emits events as if it were a
+ * PMPV0 contract, so it may be indexed directly by off-chain tools, including the Art Blocks subgraph.
+ * Some state emit events that may be custom, or may not be directly related to PMPV0, but may still be useful
+ * for off-chain indexing and analysis and frontend development.
+ * Implements a Feistel walk for efficient pseudo-random sampling at each block over large sets and arrays. This
+ * sampling is considered efficient and effective enough for our use case of streaming pseudorandom live data at each block.
+ * @dev Operationally, this contract assumes that the PMPV0 contract will be configured with at least the following PMP values,
+ * and that those values will be configured in a way where they are never able to be updated (e.g. auth option is dead address):
+ * - SendState
+ * - ReceiveState
+ * - ActiveSlot
+ * - ImageVersionSlot0
+ * - SoundVersionSlot0
+ * - ImageVersionSlot1
+ * - SoundVersionSlot1
+ * - ImageVersionSlot2
+ * - SoundVersionSlot2
+ * - ImageVersionSlot3
+ * - SoundVersionSlot3
+ * - ImageVersionSlot4
+ * - SoundVersionSlot4
+ * @dev This contract follows the UUPS (Universal Upgradeable Proxy Standard) pattern.
+ * It uses OpenZeppelin's upgradeable contracts and must be deployed behind a proxy.
+ * Only the owner can authorize upgrades via the _authorizeUpgrade function, which may
+ * be eventually disabled in future versions after to lock project functionality.
+ */
+contract SRHooks is
+    Initializable,
+    AbstractPMPAugmentHook,
+    OwnableUpgradeable,
+    UUPSUpgradeable,
+    ISRHooks
+{
+    using EnumerableSetUint16 for EnumerableSetUint16.Uint16Set;
+    using ImmutableUint16Array for ImmutableUint16Array.Uint16Array;
+    using SafeCast for uint256;
+
+    address public CORE_CONTRACT_ADDRESS;
+
+    uint256 public CORE_PROJECT_ID;
+
+    uint256 public constant MAX_IMAGE_DATA_LENGTH = 1024 * 15; // 15 KB, beyond which is unlikely to represent a 64x64 image
+    uint256 public constant MAX_SOUND_DATA_LENGTH = 1024 * 10; // 10 KB, beyond which is unlikely to represent a sound
+
+    uint256 internal constant MAX_RECEIVE_RATE_PER_BLOCK = 36; // 36 tokens per 12s block, to limit payload size for art script
+
+    uint256 internal constant MAX_SENDING_TO_LENGTH = 25; // 25 tokens, beyond which gas costs are high, you are over-represented, and if dilution is considered in the future, it would greatly inflate live data iteration time
+    uint256 internal constant MAX_RECEIVING_FROM_ARRAY_LENGTH = 1_000; // max receiving from array length is 1k to bound worst case iteration time when getting live data
+
+    // constant delegation registry pointers and rights
+    IDelegationRegistryV2 public constant DELEGATE_V2 =
+        IDelegationRegistryV2(0x00000000000000447e69651d841bD8D104Bed493);
+    bytes32 public constant DELEGATION_REGISTRY_TOKEN_OWNER_RIGHTS =
+        bytes32("postmintparameters");
+
+    // ------ TOKEN METADATA STATE VARIABLES ------
+
+    uint256 public constant NUM_METADATA_SLOTS = 5;
+
+    // struct for the token metadata in storage
+    struct TokenMetadata {
+        address imageDataAddress; // 20 bytes
+        uint16 imageVersion; // 2 bytes - max 65,535 updates per slot
+        address soundDataAddress; // 20 bytes
+        uint16 soundVersion; // 2 bytes - max 65,535 updates per slot
+    }
+
+    /// @notice mapping of token numbers to slot to metadata
+    mapping(uint256 tokenNumber => mapping(uint256 slot => TokenMetadata slotMetadata))
+        private _tokensMetadata;
+
+    struct TokenAuxStateData {
+        uint8 activeSlot;
+        bool isReceivingTo; // true if the token is only receiving tokens sending to it, false if in any other receive state
+    }
+
+    /// @notice mapping of token numbers to aux state data
+    mapping(uint256 tokenNumber => TokenAuxStateData auxStateData)
+        private _tokenAuxStateData;
+
+    // ------ SEND/RECEIVE STATE (GLOBAL) ------
+
+    /// @notice Set of token numbers that are currently in state SendGeneral
+    // @dev Uses custom packed EnumerableSetUint16 to efficiently pack uint16 values into shared storage slots
+    // @dev need O(1) access and O(1) insertion/removal for both sending and receiving tokens, so use an EnumerableSet
+    EnumerableSetUint16.Uint16Set private _sendGeneralTokens;
+
+    /// @notice Set of token numbers that are currently in state ReceiveGeneral
+    // @dev Uses custom packed EnumerableSetUint16 to efficiently pack uint16 values into shared storage slots
+    // @dev need O(1) access and O(1) insertion/removal for both sending and receiving tokens, so use an EnumerableSet
+    EnumerableSetUint16.Uint16Set private _receiveGeneralTokens;
+
+    // ------ SEND/RECEIVE STATE (PER TOKEN) ------
+
+    /// @notice Set of token numbers that are sending to a specific token
+    // @dev Uses custom packed EnumerableSetUint16 to efficiently pack uint16 values into shared storage slots
+    // @dev need O(1) access and O(1) insertion/removal for both sending and receiving tokens, so use an EnumerableSet
+    mapping(uint256 receivingTokenNumber => EnumerableSetUint16.Uint16Set tokensSendingToMe)
+        private _tokensSendingToMe;
+
+    /// @notice Array of token numbers that a given token is sending to (when in state SendTo)
+    // @dev need only O(1) access (not insertion/removal) for sending tokens, so use an ImmutableUint16Array
+    mapping(uint256 sendingTokenNumber => ImmutableUint16Array.Uint16Array tokensSendingTo)
+        private _tokensSendingTo;
+
+    /// @notice Array of token numbers that a token is open to receiving from (when in state ReceiveFrom)
+    // @dev need only O(1) access (not insertion/removal) for receiving tokens, so use an ImmutableUint16Array
+    mapping(uint256 receivingTokenNumber => ImmutableUint16Array.Uint16Array tokensReceivingFrom)
+        private _tokensReceivingFrom;
+
+    /**
+     * @notice modifier-like internal function to check if an address is the owner or a valid delegate.xyz V2 of the token owner.
+     * @param tokenNumber The token number to check.
+     * @param addressToCheck The address to check.
+     * @return isOwnerOrDelegate True if the address is the owner or a valid delegate.xyz V2 of the token owner, false otherwise.
+     * @return ownerAddress The address of the token owner.
+     * @dev This function is used to check if an address is the owner or a valid delegate.xyz V2 of the token owner,
+     * and to get the address of the token owner.
+     */
+    function _isOwnerOrDelegate(
+        uint256 tokenNumber,
+        address addressToCheck
+    ) internal view returns (bool isOwnerOrDelegate, address ownerAddress) {
+        uint256 tokenId = ABHelpers.tokenIdFromProjectIdAndTokenNumber({
+            projectId: CORE_PROJECT_ID,
+            tokenNumber: tokenNumber
+        });
+        ownerAddress = IERC721(CORE_CONTRACT_ADDRESS).ownerOf(tokenId);
+        isOwnerOrDelegate =
+            addressToCheck == ownerAddress ||
+            DELEGATE_V2.checkDelegateForERC721({
+                to: addressToCheck,
+                from: ownerAddress,
+                contract_: CORE_CONTRACT_ADDRESS,
+                tokenId: tokenId,
+                rights: DELEGATION_REGISTRY_TOKEN_OWNER_RIGHTS
+            });
+    }
+
+    /// disable initialization in deployed implementation contract for clarity
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    constructor() {
+        _disableInitializers();
+    }
+
+    /**
+     * @notice Initializes the contract with the PMPV0 address and sets the owner.
+     * @dev This function replaces the constructor for upgradeable contracts.
+     * Can only be called once due to the initializer modifier.
+     * @param _owner The address that will own this contract and authorize upgrades.
+     * @param _coreContractAddress The address of the core contract.
+     * @param _coreProjectId The project ID of the core contract.
+     */
+    function initialize(
+        address _owner,
+        address _coreContractAddress,
+        uint256 _coreProjectId
+    ) public initializer {
+        __Ownable_init(_owner);
+        __UUPSUpgradeable_init();
+
+        CORE_CONTRACT_ADDRESS = _coreContractAddress;
+        CORE_PROJECT_ID = _coreProjectId;
+
+        emit SRHooksInitialized({
+            coreContractAddress: _coreContractAddress,
+            coreProjectId: _coreProjectId
+        });
+        // @dev this contract does not emit PMPV0 project configuration events.
+        // This decouples indexing of PMP Configure events from the indexing of the project configuration information.
+        // Operationally, this contract requires configuration of the PMP project configuration as described in the contract-
+        // level documentation.
+    }
+
+    /**
+     * @notice Augment the token parameters for a given token.
+     * Augments the token parameters by appending the token's active slot's metadata and send/receive states.
+     * The following fields are appended:
+     * - imageData: the hex string of the compressed image data of the token's active slot
+     * - soundData: the hex string of the compressed sound data of the token's active slot
+     * - sendState: the string of the send state of the token (SendGeneral, SendTo, Neutral)
+     * - receiveState: the string of the receive state of the token (ReceiveGeneral, ReceiveFrom, Neutral)
+     * @dev This hook is called when a token's PMPs are read.
+     * @dev This must return all desired tokenParams, not just additional data.
+     * @param tokenParams The token parameters for the queried token.
+     * @return augmentedTokenParams The augmented token parameters.
+     */
+    function onTokenPMPReadAugmentation(
+        address /* coreContract */,
+        uint256 tokenId,
+        IWeb3Call.TokenParam[] calldata tokenParams
+    )
+        external
+        view
+        override
+        returns (IWeb3Call.TokenParam[] memory augmentedTokenParams)
+    {
+        // create a new augmentedTokenParams array with maximum length of
+        // input tokenParams + 1 extra element for the squiggle's token hash
+        uint256 originalLength = tokenParams.length;
+        uint256 augmentedMaxLength = originalLength + 4; // 4 extra elements for the token metadata fields
+        augmentedTokenParams = new IWeb3Call.TokenParam[](augmentedMaxLength);
+
+        // copy original tokenParams to augmentedTokenParams
+        for (uint256 i = 0; i < originalLength; i++) {
+            augmentedTokenParams[i] = tokenParams[i];
+        }
+
+        // append each token metadata fields (image and sound data addresses) to the augmentedTokenParams array
+        // @dev load active slot from storage
+        uint256 tokenNumber = ABHelpers.tokenIdToTokenNumber(tokenId);
+        uint256 activeSlot = _tokenAuxStateData[tokenNumber].activeSlot;
+        TokenMetadata storage tokenMetadataStorage = _tokensMetadata[
+            tokenNumber
+        ][activeSlot];
+        // return the image and sound data as hex strings
+        augmentedTokenParams[originalLength] = IWeb3Call.TokenParam({
+            key: "imageData",
+            value: _getHexStringFromSSTORE2(
+                tokenMetadataStorage.imageDataAddress
+            )
+        });
+        augmentedTokenParams[originalLength + 1] = IWeb3Call.TokenParam({
+            key: "soundData",
+            value: _getHexStringFromSSTORE2(
+                tokenMetadataStorage.soundDataAddress
+            )
+        });
+
+        // include send and receive states
+        augmentedTokenParams[originalLength + 2] = IWeb3Call.TokenParam({
+            key: "sendState",
+            value: _sendStateToString(_getSendState(tokenNumber))
+        });
+        augmentedTokenParams[originalLength + 3] = IWeb3Call.TokenParam({
+            key: "receiveState",
+            value: _receiveStateToString(_getReceiveState(tokenNumber))
+        });
+
+        // return the augmented tokenParams
+        return augmentedTokenParams;
+    }
+
+    /**
+     * @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.
+     * @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.
+     * @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.
+     * @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 {
+        // CHECKS
+        // require token number is valid uint16
+        require(tokenNumber < type(uint16).max, "Invalid token number");
+        // msg.sender must be owner or valid delegate.xyz V2 of token owner
+        // @dev this also checks that the token number is valid (exists and has valid owner)
+        (bool isOwnerOrDelegate, address ownerAddress) = _isOwnerOrDelegate(
+            tokenNumber,
+            msg.sender
+        );
+        require(
+            isOwnerOrDelegate,
+            "Only owner or valid delegate.xyz V2 of token owner allowed"
+        );
+        require(
+            updateSendState || updateReceiveState || updateTokenMetadata,
+            "At least one update must be provided"
+        );
+
+        // CHECKS-AND-EFFECTS (BRANCHED LOGIC)
+        // update token metadata first, prior to any S/R state updates (since you need artwork before you can send/receive)
+        if (updateTokenMetadata) {
+            // EFFECTS
+            // update the token metadata
+            _updateTokenMetadata({
+                tokenNumber: tokenNumber,
+                updatedActiveSlot: updatedActiveSlot,
+                tokenMetadataCalldata: tokenMetadataCalldata,
+                ownerAddress: ownerAddress
+            });
+        }
+
+        // update send/receive states second, after any metadata updates (since you need artwork before you can send/receive)
+        if (updateSendState) {
+            _updateSendState({
+                tokenNumber: tokenNumber,
+                sendState: sendState,
+                tokensSendingTo: tokensSendingTo,
+                ownerAddress: ownerAddress
+            });
+        }
+        if (updateReceiveState) {
+            _updateReceiveState({
+                tokenNumber: tokenNumber,
+                receiveState: receiveState,
+                tokensReceivingFrom: tokensReceivingFrom,
+                ownerAddress: ownerAddress
+            });
+        }
+    }
+
+    /**
+     * @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
+        )
+    {
+        // CHECKS
+        // require token number is valid uint16 using SafeCast
+        tokenNumber.toUint16(); // will revert if tokenNumber > type(uint16).max
+        // require maxReceive is not too large
+        require(
+            maxReceive <= MAX_RECEIVE_RATE_PER_BLOCK,
+            "maxReceive is too large"
+        );
+
+        // treat block number of 0 as latest completed block
+        usedBlockNumber = blockNumber == 0 ? block.number - 1 : blockNumber;
+        if (usedBlockNumber > block.number - 1) {
+            revert("Block number in future - need block hash to be defined");
+        }
+        // ensure we get a valid block hash (must be in latest 256 blocks)
+        bytes32 blockhash_ = blockhash(usedBlockNumber); // returns zero if not in latest 256 blocks
+        require(
+            blockhash_ != bytes32(0),
+            "block hash not available - must be in lastest 256 blocks"
+        );
+
+        // populate send and receive states
+        sendState = _getSendState(tokenNumber);
+        receiveState = _getReceiveState(tokenNumber);
+
+        // populate the returned state variables
+        numSendGeneral = _sendGeneralTokens.length();
+        numReceiveGeneral = _receiveGeneralTokens.length();
+        numSendingToMe = _tokensSendingToMe[tokenNumber].length();
+        // used block number already populated
+
+        // case: neutral receiving state - no tokens received
+        if (receiveState == ReceiveStates.Neutral) {
+            return (
+                sendState,
+                receiveState,
+                new TokenLiveData[](0),
+                new TokenLiveData[](0),
+                numSendGeneral,
+                numReceiveGeneral,
+                numSendingToMe,
+                usedBlockNumber
+            );
+        }
+
+        // case: receiveGeneral state - all tokens received - sample from general pool
+        if (receiveState == ReceiveStates.ReceiveGeneral) {
+            receivedTokensGeneral = _sampleReceivedTokensGeneral({
+                tokenNumber: tokenNumber,
+                blockhash_: blockhash_,
+                maxReceive: maxReceive
+            });
+            receivedTokensTo = _sampleReceivedTokensTo({
+                tokenNumber: tokenNumber,
+                blockhash_: blockhash_,
+                maxReceive: maxReceive
+            });
+            return (
+                sendState,
+                receiveState,
+                receivedTokensGeneral,
+                receivedTokensTo,
+                numSendGeneral,
+                numReceiveGeneral,
+                numSendingToMe,
+                usedBlockNumber
+            );
+        }
+
+        // case: receiveFrom state - only tokens received from specific tokens
+        if (receiveState == ReceiveStates.ReceiveFrom) {
+            (
+                receivedTokensGeneral,
+                receivedTokensTo
+            ) = _sampleTokensReceivedFrom({
+                tokenNumber: tokenNumber,
+                blockhash_: blockhash_,
+                maxReceive: maxReceive
+            });
+            return (
+                sendState,
+                receiveState,
+                receivedTokensGeneral,
+                receivedTokensTo,
+                numSendGeneral,
+                numReceiveGeneral,
+                numSendingToMe,
+                usedBlockNumber
+            );
+        }
+
+        // case: receiveTo state - only tokens received to specific tokens
+        if (receiveState == ReceiveStates.ReceiveTo) {
+            receivedTokensTo = _sampleReceivedTokensTo({
+                tokenNumber: tokenNumber,
+                blockhash_: blockhash_,
+                maxReceive: maxReceive
+            });
+            return (
+                sendState,
+                receiveState,
+                new TokenLiveData[](0), // no tokens received from general pool
+                receivedTokensTo,
+                numSendGeneral,
+                numReceiveGeneral,
+                numSendingToMe,
+                usedBlockNumber
+            );
+        }
+    }
+
+    /**
+     * @notice Samples the received tokens general for a given token.
+     * Assumes token is receiving generally.
+     * @param tokenNumber The token number to get the received tokens general for.
+     * @param blockhash_ The block hash to get the received tokens general for.
+     * @param maxReceive The maximum number of tokens to receive.
+     * @return receivedTokensGeneral The received tokens general.
+     */
+    function _sampleReceivedTokensGeneral(
+        uint256 tokenNumber,
+        bytes32 blockhash_,
+        uint256 maxReceive
+    ) internal view returns (TokenLiveData[] memory) {
+        // calculate the general send pool size (tokens available to receive from)
+        uint256 sendGeneralLength = _sendGeneralTokens.length();
+        uint256 sampleQuantity = sendGeneralLength > maxReceive
+            ? maxReceive
+            : sendGeneralLength;
+
+        // sample from general pool, quantity sampleQuantity
+        bytes32 seed = keccak256(abi.encodePacked(blockhash_, tokenNumber));
+        return
+            _sampleFromSendGeneralPool({seed: seed, quantity: sampleQuantity});
+    }
+
+    /**
+     * @notice Samples tokens from the general sending pool using an Feistel walk.
+     * @dev Uses FeistelWalkLib for efficient pseudo-random sampling over the EnumerableSet.
+     * @param seed The seed for pseudo-randomness.
+     * @param quantity The number of tokens to sample.
+     * @return result Array of TokenLiveData for sampled tokens.
+     */
+    function _sampleFromSendGeneralPool(
+        bytes32 seed,
+        uint256 quantity
+    ) internal view returns (TokenLiveData[] memory) {
+        // edge case: quantity is 0, return empty array
+        // @dev no coverage - this is a weird case
+        if (quantity == 0) {
+            return new TokenLiveData[](0);
+        }
+        // calculate the send general pool length to support making a plan
+        uint256 sendGeneralLength = _sendGeneralTokens.length();
+        // perform Feistel walk to sample token numbers from the set
+        FeistelWalkLib.Plan memory plan = FeistelWalkLib.makePlan({
+            seed: seed,
+            N: sendGeneralLength
+        });
+        uint256[] memory sampledTokenIndices = FeistelWalkLib.sample({
+            p: plan,
+            K: quantity
+        });
+        // populate TokenLiveData for each sampled token
+        uint256 sampledCount = sampledTokenIndices.length;
+        TokenLiveData[] memory result = new TokenLiveData[](sampledCount);
+        // @dev pull project id and core contract address into memory for efficient sload minimization
+        uint256 _projectId = CORE_PROJECT_ID;
+        address _coreContractAddress = CORE_CONTRACT_ADDRESS;
+        for (uint256 i = 0; i < sampledCount; i++) {
+            uint256 tokenNumber = _sendGeneralTokens.at(sampledTokenIndices[i]);
+            uint256 tokenId = ABHelpers.tokenIdFromProjectIdAndTokenNumber({
+                projectId: _projectId,
+                tokenNumber: tokenNumber
+            });
+            result[i] = _getLiveDataForToken({
+                tokenNumber: tokenNumber,
+                tokenId: tokenId,
+                coreContractAddress: _coreContractAddress
+            });
+        }
+        return result;
+    }
+
+    /**
+     * @notice Samples the received tokens to for a given token, via a Feistel walk over the tokens sending to me.
+     * Assumes token is receiving generally.
+     * @param tokenNumber The token number to get the received tokens to for.
+     * @param blockhash_ The block hash to get the received tokens to for.
+     * @param maxReceive The maximum number of tokens to receive.
+     * @return receivedTokensTo The received tokens to.
+     */
+    function _sampleReceivedTokensTo(
+        uint256 tokenNumber,
+        bytes32 blockhash_,
+        uint256 maxReceive
+    ) internal view returns (TokenLiveData[] memory) {
+        // we perform a Feistel walk to sample token numbers from the set, and then get the live data for each token.
+        uint256 sendingToMeLength = _tokensSendingToMe[tokenNumber].length();
+        if (sendingToMeLength == 0) {
+            return new TokenLiveData[](0); // no tokens sending to me, return empty array
+        }
+        // return length will be lower of sendingToMeLength and maxReceive
+        uint256 sampleQuantity = sendingToMeLength > maxReceive
+            ? maxReceive
+            : sendingToMeLength;
+        // iterate over the tokens sending to me; perform Feistel walk to sample token numbers from the set
+        bytes32 seed = keccak256(abi.encodePacked(blockhash_, tokenNumber));
+        FeistelWalkLib.Plan memory plan = FeistelWalkLib.makePlan({
+            seed: seed,
+            N: sendingToMeLength
+        });
+        // sample token numbers from the set
+        uint256[] memory sampledTokenIndices = FeistelWalkLib.sample({
+            p: plan,
+            K: sampleQuantity
+        });
+        // allocate array of TokenLiveData for the selected token numbers
+        TokenLiveData[] memory result = new TokenLiveData[](sampleQuantity);
+        // @dev pull project id and core contract address into memory for efficient sload minimization
+        uint256 _projectId = CORE_PROJECT_ID;
+        address _coreContractAddress = CORE_CONTRACT_ADDRESS;
+        EnumerableSetUint16.Uint16Set
+            storage tokensSendingToMe_ = _tokensSendingToMe[tokenNumber];
+        // for each selected token number, get the live data
+        for (uint256 i = 0; i < sampleQuantity; i++) {
+            uint256 selectedTokenNumber = tokensSendingToMe_.at(
+                sampledTokenIndices[i]
+            );
+            uint256 selectedTokenId = ABHelpers
+                .tokenIdFromProjectIdAndTokenNumber({
+                    projectId: _projectId,
+                    tokenNumber: selectedTokenNumber
+                });
+            result[i] = _getLiveDataForToken({
+                tokenNumber: selectedTokenNumber,
+                tokenId: selectedTokenId,
+                coreContractAddress: _coreContractAddress
+            });
+        }
+        return result;
+    }
+
+    /**
+     * @notice Samples the tokens received from a given token, via a Feistel walk over the tokens receiving from me.
+     * @dev This function automatically deduplicates tokens if the tokensReceivingFrom array contains duplicates,
+     * ensuring each token appears at most once in the results. Self-referential tokens are also filtered out.
+     * @param tokenNumber The token number to get the tokens received from.
+     * @param blockhash_ The blockhash to use for pseudo-randomness.
+     * @param maxReceive The maximum number of tokens to receive.
+     * @return tokensReceivedFromGeneral The tokens received from the general pool.
+     * @return tokensReceivedFromTo The tokens received to the specific tokens.
+     */
+    function _sampleTokensReceivedFrom(
+        uint256 tokenNumber,
+        bytes32 blockhash_,
+        uint256 maxReceive
+    )
+        internal
+        view
+        returns (
+            TokenLiveData[] memory tokensReceivedFromGeneral,
+            TokenLiveData[] memory tokensReceivedFromTo
+        )
+    {
+        // load the tokens receiving from into memory for efficient SSTORE2 load minimization
+        uint16[] memory tokensReceivingFrom = _tokensReceivingFrom[tokenNumber]
+            .getAll();
+        uint256 receivingFromMeLength = tokensReceivingFrom.length;
+        // we will iterate continuously over the tokens receiving from me, and include it if from the general pool,
+        // or if sending to me.
+        // if the token is not sending to me, or not sending generally, we skip it.
+        // we perform a Feistel walk to sample token numbers from the set, and then get the live data for each token.
+        // @dev no coverage - we never allow zero-length receiveFrom arrays, but check for redundancy.
+        if (receivingFromMeLength == 0) {
+            return (new TokenLiveData[](0), new TokenLiveData[](0)); // no tokens receiving from me, return empty arrays
+        }
+        // iterate over the tokens receiving from me; perform Feistel walk to sample token numbers from the set
+        bytes32 seed = keccak256(abi.encodePacked(blockhash_, tokenNumber));
+        FeistelWalkLib.Plan memory plan = FeistelWalkLib.makePlan({
+            seed: seed,
+            N: receivingFromMeLength
+        });
+
+        // SEND TO TOKEN ITERATION
+        // sample tokens from SendTo states (in separate function to avoid stack too deep)
+        uint256[]
+            memory selectedTokenNumbersTo = _sampleTokensReceivedFromSendToPool({
+                tokenNumber: tokenNumber,
+                tokensReceivingFrom: tokensReceivingFrom,
+                receivingFromMeLength: receivingFromMeLength,
+                plan: plan,
+                maxReceive: maxReceive
+            });
+        uint256 selectedTokenNumbersToLength = selectedTokenNumbersTo.length;
+
+        // SEND GENERAL TOKEN ITERATION
+        // sample tokens from general send pool (in separate function to avoid stack too deep)
+        uint256[]
+            memory selectedTokenNumbersGeneral = _sampleTokensReceivedFromGeneralPool({
+                tokenNumber: tokenNumber,
+                tokensReceivingFrom: tokensReceivingFrom,
+                receivingFromMeLength: receivingFromMeLength,
+                plan: plan,
+                maxReceive: maxReceive
+            });
+        uint256 selectedTokenNumbersGeneralLength = selectedTokenNumbersGeneral
+            .length;
+
+        // allocate array of TokenLiveData for the selected general token numbers
+        tokensReceivedFromGeneral = new TokenLiveData[](
+            selectedTokenNumbersGeneralLength
+        );
+        // @dev pull project id and core contract address into memory for efficient sload minimization
+        uint256 _projectId = CORE_PROJECT_ID;
+        address _coreContractAddress = CORE_CONTRACT_ADDRESS;
+        // for each selected general token number, get the live data
+        for (uint256 i = 0; i < selectedTokenNumbersGeneralLength; i++) {
+            uint256 selectedTokenNumber = selectedTokenNumbersGeneral[i];
+            tokensReceivedFromGeneral[i] = _getLiveDataForToken({
+                tokenNumber: selectedTokenNumber,
+                tokenId: ABHelpers.tokenIdFromProjectIdAndTokenNumber({
+                    projectId: _projectId,
+                    tokenNumber: selectedTokenNumber
+                }),
+                coreContractAddress: _coreContractAddress
+            });
+        }
+        // allocate array of TokenLiveData for the selected to token numbers
+        tokensReceivedFromTo = new TokenLiveData[](
+            selectedTokenNumbersToLength
+        );
+        // for each selected to token number, get the live data
+        for (uint256 i = 0; i < selectedTokenNumbersToLength; i++) {
+            uint256 selectedTokenNumber = selectedTokenNumbersTo[i];
+            tokensReceivedFromTo[i] = _getLiveDataForToken({
+                tokenNumber: selectedTokenNumber,
+                tokenId: ABHelpers.tokenIdFromProjectIdAndTokenNumber({
+                    projectId: _projectId,
+                    tokenNumber: selectedTokenNumber
+                }),
+                coreContractAddress: _coreContractAddress
+            });
+        }
+        return (tokensReceivedFromGeneral, tokensReceivedFromTo);
+    }
+
+    /**
+     * @notice Helper function to sample tokens from the SendTo pool that are in the tokensReceivingFrom array.
+     * @dev This function automatically deduplicates tokens if the tokensReceivingFrom array contains duplicates.
+     * Self-referential tokens are also filtered out.
+     * @param tokenNumber The token number we're checking receives from.
+     * @param tokensReceivingFrom The array of tokens that might be sending to this token.
+     * @param receivingFromMeLength The length of the tokensReceivingFrom array.
+     * @param plan The Feistel walk plan for sampling.
+     * @param maxReceive The maximum number of tokens to receive.
+     * @return selectedTokenNumbersTo Array of token numbers from SendTo states.
+     */
+    function _sampleTokensReceivedFromSendToPool(
+        uint256 tokenNumber,
+        uint16[] memory tokensReceivingFrom,
+        uint256 receivingFromMeLength,
+        FeistelWalkLib.Plan memory plan,
+        uint256 maxReceive
+    ) internal view returns (uint256[] memory selectedTokenNumbersTo) {
+        // allocate array for selected token numbers
+        selectedTokenNumbersTo = new uint256[](maxReceive);
+        uint256 selectedTokenNumbersToLength = 0;
+
+        // deduplication tracking array for tokensReceivingFrom (handles duplicates in user-provided array)
+        uint256[] memory seenTokens = new uint256[](maxReceive);
+        uint256 seenCount = 0;
+
+        for (uint256 i = 0; i < receivingFromMeLength; i++) {
+            uint256 sampledTokenNumber;
+            {
+                uint256 sampledTokenIndex = FeistelWalkLib.index(plan, i);
+                sampledTokenNumber = tokensReceivingFrom[sampledTokenIndex];
+            }
+            // skip self-referential (token receiving from itself)
+            if (sampledTokenNumber == tokenNumber) {
+                continue;
+            }
+            // check for duplicates in tokensReceivingFrom array
+            bool alreadySeen = false;
+            for (uint256 j = 0; j < seenCount; j++) {
+                if (seenTokens[j] == sampledTokenNumber) {
+                    alreadySeen = true;
+                    break;
+                }
+            }
+            if (alreadySeen) {
+                continue;
+            }
+            // if sending to me, include it
+            if (
+                _tokensSendingToMe[tokenNumber].contains(
+                    uint16(sampledTokenNumber)
+                )
+            ) {
+                selectedTokenNumbersTo[
+                    selectedTokenNumbersToLength
+                ] = sampledTokenNumber;
+                selectedTokenNumbersToLength++;
+                // mark as seen to prevent duplicate processing
+                seenTokens[seenCount++] = sampledTokenNumber;
+            }
+            // if we have selected the maximum number of tokens, break
+            if (selectedTokenNumbersToLength >= maxReceive) {
+                break;
+            }
+        }
+
+        // resize array to actual length
+        assembly {
+            mstore(selectedTokenNumbersTo, selectedTokenNumbersToLength)
+        }
+    }
+
+    /**
+     * @notice Helper function to sample tokens from the general send pool that are in the tokensReceivingFrom array.
+     * @dev This function automatically deduplicates tokens if the tokensReceivingFrom array contains duplicates.
+     * Self-referential tokens are also filtered out.
+     * @param tokenNumber The token number we're checking receives from.
+     * @param tokensReceivingFrom The array of tokens that might be sending to this token.
+     * @param receivingFromMeLength The length of the tokensReceivingFrom array.
+     * @param plan The Feistel walk plan for sampling.
+     * @param maxReceive The maximum number of tokens to receive.
+     * @return selectedTokenNumbersGeneral Array of token numbers from the general pool.
+     */
+    function _sampleTokensReceivedFromGeneralPool(
+        uint256 tokenNumber,
+        uint16[] memory tokensReceivingFrom,
+        uint256 receivingFromMeLength,
+        FeistelWalkLib.Plan memory plan,
+        uint256 maxReceive
+    ) internal view returns (uint256[] memory selectedTokenNumbersGeneral) {
+        // allocate array for selected token numbers
+        selectedTokenNumbersGeneral = new uint256[](maxReceive);
+        uint256 selectedTokenNumbersGeneralLength = 0;
+
+        // deduplication tracking array for tokensReceivingFrom (handles duplicates in user-provided array)
+        uint256[] memory seenTokens = new uint256[](maxReceive);
+        uint256 seenCount = 0;
+
+        for (uint256 i = 0; i < receivingFromMeLength; i++) {
+            uint256 sampledTokenNumber;
+            {
+                uint256 sampledTokenIndex = FeistelWalkLib.index(plan, i);
+                sampledTokenNumber = tokensReceivingFrom[sampledTokenIndex];
+            }
+            // skip self-referential (token receiving from itself)
+            if (sampledTokenNumber == tokenNumber) {
+                continue;
+            }
+            // check for duplicates in tokensReceivingFrom array
+            bool alreadySeen = false;
+            for (uint256 j = 0; j < seenCount; j++) {
+                if (seenTokens[j] == sampledTokenNumber) {
+                    alreadySeen = true;
+                    break;
+                }
+            }
+            if (alreadySeen) {
+                continue;
+            }
+            // if sending generally, include it for sure
+            if (_sendGeneralTokens.contains(uint16(sampledTokenNumber))) {
+                selectedTokenNumbersGeneral[
+                    selectedTokenNumbersGeneralLength
+                ] = sampledTokenNumber;
+                selectedTokenNumbersGeneralLength++;
+                // mark as seen to prevent duplicate processing
+                seenTokens[seenCount++] = sampledTokenNumber;
+                // if we have selected the maximum number of tokens, break
+                if (selectedTokenNumbersGeneralLength >= maxReceive) {
+                    break;
+                }
+            }
+        }
+
+        // resize array to actual length
+        assembly {
+            mstore(
+                selectedTokenNumbersGeneral,
+                selectedTokenNumbersGeneralLength
+            )
+        }
+    }
+
+    /**
+     * @notice Gets the live data for a specific token.
+     * @dev Fetches token owner and metadata from storage.
+     * @param tokenNumber The token number to get live data for.
+     * @return liveData The TokenLiveData struct for the token.
+     */
+    function _getLiveDataForToken(
+        uint256 tokenNumber,
+        uint256 tokenId,
+        address coreContractAddress
+    ) internal view returns (TokenLiveData memory liveData) {
+        // get owner address
+        address ownerAddress = IERC721(coreContractAddress).ownerOf(tokenId);
+
+        // get active slot and metadata
+        uint256 activeSlot = _tokenAuxStateData[tokenNumber].activeSlot;
+        TokenMetadata storage metadata = _tokensMetadata[tokenNumber][
+            activeSlot
+        ];
+
+        // populate live data
+        liveData.tokenNumber = tokenNumber;
+        liveData.ownerAddress = ownerAddress;
+
+        // get image and sound data
+        if (metadata.imageDataAddress != address(0)) {
+            liveData.imageDataCompressed = SSTORE2.read(
+                metadata.imageDataAddress
+            );
+        }
+        if (metadata.soundDataAddress != address(0)) {
+            liveData.soundDataCompressed = SSTORE2.read(
+                metadata.soundDataAddress
+            );
+        }
+
+        // get owner ENS name using ENS Universal Resolver
+        // @dev try/catch pattern, avoids reverts, returns empty string if reverse lookup not configured
+        liveData.ownerEnsName = ENSLib.getEnsName(ownerAddress);
+
+        return liveData;
+    }
+
+    /**
+     * @notice Updates the token metadata for a given token.
+     * Internal function - assumes token is valid
+     * @param tokenNumber The token number to update.
+     * @param updatedActiveSlot The new active slot.
+     * @param tokenMetadataCalldata The new token metadata.
+     * @param ownerAddress The address of the token owner.
+     */
+    function _updateTokenMetadata(
+        uint256 tokenNumber,
+        uint256 updatedActiveSlot,
+        TokenMetadataCalldata memory tokenMetadataCalldata,
+        address ownerAddress
+    ) internal {
+        // CHECKS
+        // updatedActiveSlot must be valid
+        require(updatedActiveSlot < NUM_METADATA_SLOTS, "Invalid active slot");
+        bool isUpdatingActiveSlot = _tokenAuxStateData[tokenNumber]
+            .activeSlot != updatedActiveSlot;
+        TokenMetadata storage tokenMetadataStorage = _tokensMetadata[
+            tokenNumber
+        ][updatedActiveSlot];
+        // require that the new active slot has/will have image metadata if updating the active slot
+        // @dev this is to prevent participation in the pools without artwork
+        if (isUpdatingActiveSlot) {
+            require(
+                tokenMetadataCalldata.updateImage ||
+                    tokenMetadataStorage.imageDataAddress != address(0),
+                "New active slot must have image metadata when updating active slot"
+            );
+        }
+
+        // CHECKS-AND-EFFECTS (BRANCHED LOGIC)
+        uint256 tokenId = ABHelpers.tokenIdFromProjectIdAndTokenNumber({
+            projectId: CORE_PROJECT_ID,
+            tokenNumber: tokenNumber
+        });
+        // update the token metadata
+        // image data
+        if (tokenMetadataCalldata.updateImage) {
+            require(
+                tokenMetadataCalldata.imageDataCompressed.length > 0,
+                "Image data must be provided when updating"
+            );
+            require(
+                tokenMetadataCalldata.imageDataCompressed.length <=
+                    MAX_IMAGE_DATA_LENGTH,
+                "Image data must be less than or equal to MAX_IMAGE_DATA_LENGTH"
+            );
+            // @dev image data, compressed + use sstore2 for efficient
+            tokenMetadataStorage.imageDataAddress = SSTORE2.write(
+                tokenMetadataCalldata.imageDataCompressed
+            );
+            tokenMetadataStorage.imageVersion += 1;
+            // emit PMPV0-indexable event for image data update
+            emit IPMPV0.TokenParamsConfigured({
+                coreContract: CORE_CONTRACT_ADDRESS,
+                tokenId: tokenId,
+                pmpInputs: _getPmpInputsForImageDataUpdate({
+                    slot: updatedActiveSlot,
+                    imageVersion: tokenMetadataStorage.imageVersion
+                }),
+                authAddresses: _getSingleElementAddressArray(ownerAddress)
+            });
+        } else {
+            require(
+                tokenMetadataCalldata.imageDataCompressed.length == 0,
+                "Image data must be empty when not updating"
+            );
+        }
+        // sound data
+        if (tokenMetadataCalldata.updateSound) {
+            // allow "clearing" the sound data by providing an empty bytes array
+            if (tokenMetadataCalldata.soundDataCompressed.length == 0) {
+                tokenMetadataStorage.soundDataAddress = address(0);
+                tokenMetadataStorage.soundVersion += 1;
+                // emit PMPV0-indexable event for sound data update
+                emit IPMPV0.TokenParamsConfigured({
+                    coreContract: CORE_CONTRACT_ADDRESS,
+                    tokenId: tokenId,
+                    pmpInputs: _getPmpInputsForSoundDataUpdate({
+                        slot: updatedActiveSlot,
+                        soundVersion: tokenMetadataStorage.soundVersion
+                    }),
+                    authAddresses: _getSingleElementAddressArray(ownerAddress)
+                });
+            } else {
+                require(
+                    tokenMetadataCalldata.soundDataCompressed.length <=
+                        MAX_SOUND_DATA_LENGTH,
+                    "Sound data must be less than or equal to MAX_SOUND_DATA_LENGTH"
+                );
+                // @dev sound data, compressed + use sstore2 for efficient
+                tokenMetadataStorage.soundDataAddress = SSTORE2.write(
+                    tokenMetadataCalldata.soundDataCompressed
+                );
+                tokenMetadataStorage.soundVersion += 1;
+                // emit PMPV0-indexable event for sound data update
+                emit IPMPV0.TokenParamsConfigured({
+                    coreContract: CORE_CONTRACT_ADDRESS,
+                    tokenId: tokenId,
+                    pmpInputs: _getPmpInputsForSoundDataUpdate({
+                        slot: updatedActiveSlot,
+                        soundVersion: tokenMetadataStorage.soundVersion
+                    }),
+                    authAddresses: _getSingleElementAddressArray(ownerAddress)
+                });
+            }
+        } else {
+            require(
+                tokenMetadataCalldata.soundDataCompressed.length == 0,
+                "Sound data must be empty when not updating"
+            );
+        }
+        // update the token's active slot if it has changed
+        if (_tokenAuxStateData[tokenNumber].activeSlot != updatedActiveSlot) {
+            // @dev we already checked that the new active slot has/will have image metadata if updating the active slot
+            // update value and emit PMPV0-indexable event for active slot update
+            _tokenAuxStateData[tokenNumber].activeSlot = updatedActiveSlot
+                .toUint8();
+            emit IPMPV0.TokenParamsConfigured({
+                coreContract: CORE_CONTRACT_ADDRESS,
+                tokenId: tokenId,
+                pmpInputs: _getPmpInputsForActiveSlotUpdate(updatedActiveSlot),
+                authAddresses: _getSingleElementAddressArray(ownerAddress)
+            });
+        }
+    }
+
+    /**
+     * @notice Updates the send state for a given token.
+     * Internal function - assumes token is valid
+     * Assumes any interactions with send state and receive state are handled by the parent function.
+     * @param tokenNumber The token number to update.
+     * @param sendState The new send state. Valid values are SendGeneral, SendTo, Neutral.
+     * @param tokensSendingTo Tokens to send this token to. Only non-empty iff sendState is SendTo.
+     * @param ownerAddress The address of the token owner.
+     */
+    function _updateSendState(
+        uint256 tokenNumber,
+        SendStates sendState,
+        uint16[] memory tokensSendingTo,
+        address ownerAddress
+    ) internal {
+        // CHECKS
+        // require that the token has image metadata at the active slot
+        require(
+            _tokensMetadata[tokenNumber][
+                _tokenAuxStateData[tokenNumber].activeSlot
+            ].imageDataAddress != address(0),
+            "Token must have image metadata at active slot when particpating"
+        );
+        // enforce SendTo arrays length
+        (sendState == SendStates.SendTo)
+            ? require(
+                tokensSendingTo.length > 0,
+                "tokensSendingTo must be non-empty"
+            )
+            : require(
+                tokensSendingTo.length == 0,
+                "tokensSendingTo must be empty"
+            );
+        // enforce tokensSendingTo length is not too long
+        require(
+            tokensSendingTo.length <= MAX_SENDING_TO_LENGTH,
+            "tokensSendingTo must be less than or equal to MAX_SENDING_TO_LENGTH"
+        );
+
+        // EFFECTS
+        uint256 tokenId = ABHelpers.tokenIdFromProjectIdAndTokenNumber({
+            projectId: CORE_PROJECT_ID,
+            tokenNumber: tokenNumber
+        });
+
+        // Step 1. clear previous send state, based on storage's send state
+        SendStates previousSendState = _getSendState(tokenNumber);
+        if (previousSendState == SendStates.SendGeneral) {
+            // simply remove the token from the send general set
+            _sendGeneralTokens.remove(uint16(tokenNumber));
+        } else if (previousSendState == SendStates.SendTo) {
+            // pop from every previous token's "sending to me" set, which is a O(n) operation for n tokens previously sent to
+            // @dev pull into memory for efficient sload minimization
+            uint16[] memory previousTokensSendingTo = _tokensSendingTo[
+                tokenNumber
+            ].getAll();
+            uint256 previousTokensSendingToLength = previousTokensSendingTo
+                .length;
+            for (uint256 i = 0; i < previousTokensSendingToLength; i++) {
+                uint256 sendingToTokenNumber = previousTokensSendingTo[i];
+                _tokensSendingToMe[sendingToTokenNumber].remove(
+                    uint16(tokenNumber)
+                );
+            }
+            // clear my previous send to array
+            _tokensSendingTo[tokenNumber].clear();
+            // emit custom event for indexing of send-to if applicable
+            // @dev acknowledge that this may cost gas for large arrays, but prefer strong indexing behavior, and
+            // still minor relative to the cost of the SSTORE operations when storing the send-to array
+            emit ISRHooks.TokenSendingToUpdated({
+                coreContract: CORE_CONTRACT_ADDRESS,
+                tokenId: tokenId,
+                tokensSendingTo: new uint16[](0)
+            });
+        }
+        // case: neutral state - no-op
+
+        // Step 2. populate the new send state
+        if (sendState == SendStates.SendGeneral) {
+            _sendGeneralTokens.add(uint16(tokenNumber));
+        } else if (sendState == SendStates.SendTo) {
+            // push the tokens to my send to array
+            _tokensSendingTo[tokenNumber].store(tokensSendingTo);
+            // push me into every token's "sending to me" set
+            // @dev no validation of target tokens needed - if they don't exist or aren't participating,
+            // they simply won't appear in getLiveData results due to state set membership checks
+            uint256 tokensSendingToLength = tokensSendingTo.length;
+            for (uint256 i = 0; i < tokensSendingToLength; i++) {
+                uint256 sendingToTokenNumber = tokensSendingTo[i];
+                // add the token to the "sending to me" Set
+                _tokensSendingToMe[sendingToTokenNumber].add(
+                    uint16(tokenNumber)
+                );
+            }
+        }
+        // case: neutral state - no-op
+
+        // emit PMPV0-indexable event for send state update
+        emit IPMPV0.TokenParamsConfigured({
+            coreContract: CORE_CONTRACT_ADDRESS,
+            tokenId: tokenId,
+            pmpInputs: _getPmpInputsForSendStateUpdate(sendState),
+            authAddresses: _getSingleElementAddressArray(ownerAddress)
+        });
+
+        // emit custom event for indexing of send-to if applicable
+        // @dev acknowledge that this may cost gas for large arrays, but prefer strong indexing behavior, and
+        // still minor relative to the cost of the SSTORE operations when storing the send-to array
+        if (sendState == SendStates.SendTo) {
+            emit ISRHooks.TokenSendingToUpdated({
+                coreContract: CORE_CONTRACT_ADDRESS,
+                tokenId: tokenId,
+                tokensSendingTo: tokensSendingTo
+            });
+        }
+    }
+
+    /**
+     * @notice Updates the receive state for a given token.
+     * Internal function - assumes token is valid
+     * Assumes any interactions with send state and receive state are handled by the parent function.
+     * @param tokenNumber The token number to update.
+     * @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 receiveState is ReceiveFrom.
+     * @param ownerAddress The address of the token owner.
+     */
+    function _updateReceiveState(
+        uint256 tokenNumber,
+        ReceiveStates receiveState,
+        uint16[] memory tokensReceivingFrom,
+        address ownerAddress
+    ) internal {
+        // CHECKS
+        // require that the token has image metadata at the active slot
+        require(
+            _tokensMetadata[tokenNumber][
+                _tokenAuxStateData[tokenNumber].activeSlot
+            ].imageDataAddress != address(0),
+            "Token must have image metadata at active slot when particpating"
+        );
+        // enforce ReceiveFrom arrays length
+        (receiveState == ReceiveStates.ReceiveFrom)
+            ? require(
+                tokensReceivingFrom.length > 0,
+                "tokensReceivingFrom must be non-empty"
+            )
+            : require(
+                tokensReceivingFrom.length == 0,
+                "tokensReceivingFrom must be empty"
+            );
+        // enforce tokensReceivingFrom length is not too long
+        require(
+            tokensReceivingFrom.length <= MAX_RECEIVING_FROM_ARRAY_LENGTH,
+            "tokensReceivingFrom must be less than or equal to MAX_RECEIVING_FROM_ARRAY_LENGTH"
+        );
+
+        // EFFECTS
+        uint256 tokenId = ABHelpers.tokenIdFromProjectIdAndTokenNumber({
+            projectId: CORE_PROJECT_ID,
+            tokenNumber: tokenNumber
+        });
+
+        // Step 1. clear previous receive state, based on storage's receive state
+        ReceiveStates previousReceiveState = _getReceiveState(tokenNumber);
+        if (previousReceiveState == ReceiveStates.ReceiveGeneral) {
+            // simply remove the token from the receive general set
+            _receiveGeneralTokens.remove(uint16(tokenNumber));
+        } else if (previousReceiveState == ReceiveStates.ReceiveFrom) {
+            // simple removal of my receive from array - we don't have a reverse mapping of the array across other tokens
+            _tokensReceivingFrom[tokenNumber].clear();
+
+            // emit custom event for indexing of receive-from if applicable
+            // @dev acknowledge that this may cost gas for large arrays, but prefer strong indexing behavior, and
+            // still minor relative to the cost of the SSTORE operations when storing the receive-from array
+            emit ISRHooks.TokenReceivingFromUpdated({
+                coreContract: CORE_CONTRACT_ADDRESS,
+                tokenId: tokenId,
+                tokensReceivingFrom: new uint16[](0)
+            });
+        } else if (previousReceiveState == ReceiveStates.ReceiveTo) {
+            // set isReceivingTo to false
+            _tokenAuxStateData[tokenNumber].isReceivingTo = false;
+        }
+        // case: neutral state - no-op
+
+        // Step 2. populate the new receive state
+        if (receiveState == ReceiveStates.ReceiveGeneral) {
+            _receiveGeneralTokens.add(uint16(tokenNumber));
+        } else if (receiveState == ReceiveStates.ReceiveFrom) {
+            // @dev no validation of target tokens needed - if they don't exist or aren't participating,
+            // they simply won't appear in getLiveData results due to state set membership checks
+            // (tokens must be in _sendGeneralTokens or _tokensSendingToMe to be included)
+            _tokensReceivingFrom[tokenNumber].store(tokensReceivingFrom);
+        } else if (receiveState == ReceiveStates.ReceiveTo) {
+            // set isReceivingTo to true
+            _tokenAuxStateData[tokenNumber].isReceivingTo = true;
+        }
+        // case: neutral state - no-op
+
+        // emit PMPV0-indexable event for receive state update
+        emit IPMPV0.TokenParamsConfigured({
+            coreContract: CORE_CONTRACT_ADDRESS,
+            tokenId: tokenId,
+            pmpInputs: _getPmpInputsForReceiveStateUpdate(receiveState),
+            authAddresses: _getSingleElementAddressArray(ownerAddress)
+        });
+
+        // emit custom event for indexing of receive-from if applicable
+        // @dev acknowledge that this may cost gas for large arrays, but prefer strong indexing behavior, and
+        // still minor relative to the cost of the SSTORE operations when storing the receive-from array
+        if (receiveState == ReceiveStates.ReceiveFrom) {
+            emit ISRHooks.TokenReceivingFromUpdated({
+                coreContract: CORE_CONTRACT_ADDRESS,
+                tokenId: tokenId,
+                tokensReceivingFrom: tokensReceivingFrom
+            });
+        }
+    }
+
+    /**
+     * @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
+        )
+    {
+        return (_sendGeneralTokens.length(), _receiveGeneralTokens.length());
+    }
+
+    /**
+     * @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
+        )
+    {
+        // require token number is valid uint16 using SafeCast
+        tokenNumber.toUint16(); // will revert if tokenNumber > type(uint16).max
+
+        sendState = _getSendState(tokenNumber);
+        receiveState = _getReceiveState(tokenNumber);
+        tokensSendingTo = ImmutableUint16Array.getAll({
+            storageArray: _tokensSendingTo[tokenNumber]
+        });
+        tokensReceivingFrom = ImmutableUint16Array.getAll({
+            storageArray: _tokensReceivingFrom[tokenNumber]
+        });
+        activeSlot = _tokenAuxStateData[tokenNumber].activeSlot;
+        TokenMetadata storage tokenMetadataStorage = _tokensMetadata[
+            tokenNumber
+        ][activeSlot];
+        activeSlotTokenMetadata.imageDataCompressed = tokenMetadataStorage
+            .imageDataAddress != address(0)
+            ? SSTORE2.read(tokenMetadataStorage.imageDataAddress)
+            : bytes("");
+        activeSlotTokenMetadata.imageVersion = tokenMetadataStorage
+            .imageVersion;
+        activeSlotTokenMetadata.soundDataCompressed = tokenMetadataStorage
+            .soundDataAddress != address(0)
+            ? SSTORE2.read(tokenMetadataStorage.soundDataAddress)
+            : bytes("");
+        activeSlotTokenMetadata.soundVersion = tokenMetadataStorage
+            .soundVersion;
+        uint256 tokenId = ABHelpers.tokenIdFromProjectIdAndTokenNumber({
+            projectId: CORE_PROJECT_ID,
+            tokenNumber: tokenNumber
+        });
+        ownerAddress = IERC721(CORE_CONTRACT_ADDRESS).ownerOf(tokenId);
+        return (
+            sendState,
+            receiveState,
+            tokensSendingTo,
+            tokensReceivingFrom,
+            activeSlot,
+            activeSlotTokenMetadata,
+            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) {
+        // require token number is valid uint16 using SafeCast
+        tokenNumber.toUint16(); // will revert if tokenNumber > type(uint16).max
+        // require slot is valid
+        require(slot < NUM_METADATA_SLOTS, "Invalid slot");
+
+        TokenMetadata storage tokenMetadataStorage = _tokensMetadata[
+            tokenNumber
+        ][slot];
+        tokenMetadata.imageDataCompressed = tokenMetadataStorage
+            .imageDataAddress != address(0)
+            ? SSTORE2.read(tokenMetadataStorage.imageDataAddress)
+            : bytes("");
+        tokenMetadata.imageVersion = tokenMetadataStorage.imageVersion;
+        tokenMetadata.soundDataCompressed = tokenMetadataStorage
+            .soundDataAddress != address(0)
+            ? SSTORE2.read(tokenMetadataStorage.soundDataAddress)
+            : bytes("");
+        tokenMetadata.soundVersion = tokenMetadataStorage.soundVersion;
+    }
+
+    /**
+     * @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) {
+        // require token number is valid uint16 using SafeCast
+        tokenNumber.toUint16(); // will revert if tokenNumber > type(uint16).max
+
+        return _tokensSendingToMe[tokenNumber].values();
+    }
+
+    /**
+     * @notice Gets the send state for a given token.
+     * Internal function - assumes token is valid
+     * @dev uses derived state to prefer SLOAD over SSTORE for efficiency
+     * @param tokenNumber The token number to get the send state for.
+     * @return sendState The send state.
+     */
+    function _getSendState(
+        uint256 tokenNumber
+    ) internal view returns (SendStates) {
+        // check for existence in send general set
+        if (_sendGeneralTokens.contains(uint16(tokenNumber))) {
+            return SendStates.SendGeneral;
+        }
+        // check for non-empty send to array
+        if (!ImmutableUint16Array.isEmpty(_tokensSendingTo[tokenNumber])) {
+            return SendStates.SendTo;
+        }
+        // must be in neutral state
+        return SendStates.Neutral;
+    }
+
+    /**
+     * @notice Converts a send state to a string.
+     * Internal function - assumes send state is valid
+     * @param sendState The send state to convert to a string.
+     * @return string The string representation of the send state.
+     */
+    function _sendStateToString(
+        SendStates sendState
+    ) internal pure returns (string memory) {
+        return
+            sendState == SendStates.SendGeneral
+                ? "SendGeneral"
+                : sendState == SendStates.SendTo
+                    ? "SendTo"
+                    : "Neutral";
+    }
+
+    /**
+     * @notice Gets the receive state for a given token.
+     * Internal function - assumes token is valid
+     * @dev uses derived state to prefer SLOAD over SSTORE for efficiency
+     * @param tokenNumber The token number to get the receive state for.
+     * @return receiveState The receive state.
+     */
+    function _getReceiveState(
+        uint256 tokenNumber
+    ) internal view returns (ReceiveStates) {
+        // check for existence in receive general set
+        if (_receiveGeneralTokens.contains(uint16(tokenNumber))) {
+            return ReceiveStates.ReceiveGeneral;
+        }
+        // check for non-empty receive from array
+        if (!ImmutableUint16Array.isEmpty(_tokensReceivingFrom[tokenNumber])) {
+            return ReceiveStates.ReceiveFrom;
+        }
+        // check for isReceivingTo
+        if (_tokenAuxStateData[tokenNumber].isReceivingTo) {
+            return ReceiveStates.ReceiveTo;
+        }
+        // must be in neutral state
+        return ReceiveStates.Neutral;
+    }
+
+    /**
+     * @notice Converts a receive state to a string.
+     * Internal function - assumes receive state is valid
+     * @param receiveState The receive state to convert to a string.
+     * @return string The string representation of the receive state.
+     */
+    function _receiveStateToString(
+        ReceiveStates receiveState
+    ) internal pure returns (string memory) {
+        if (receiveState == ReceiveStates.Neutral) {
+            return "Neutral";
+        }
+        if (receiveState == ReceiveStates.ReceiveGeneral) {
+            return "ReceiveGeneral";
+        }
+        if (receiveState == ReceiveStates.ReceiveFrom) {
+            return "ReceiveFrom";
+        }
+        if (receiveState == ReceiveStates.ReceiveTo) {
+            return "ReceiveTo";
+        }
+        // case: invalid receive state (no coverage)
+        revert("Invalid receive state");
+    }
+
+    function _getHexStringFromSSTORE2(
+        address sstore2Address
+    ) internal view returns (string memory) {
+        // case: empty sstore2 address
+        if (sstore2Address == address(0)) {
+            return "";
+        }
+        // case: non-empty sstore2 address
+        return toHexString(SSTORE2.read(sstore2Address));
+    }
+
+    /**
+     * @notice Checks if the contract supports an interface.
+     * @dev This function is required by the ERC165 interface detection pattern.
+     * @param interfaceId The interface identifier to check.
+     * @return bool True if the contract supports the interface, false otherwise.
+     */
+    function supportsInterface(
+        bytes4 interfaceId
+    ) public view override(AbstractPMPAugmentHook) returns (bool) {
+        return
+            interfaceId == type(IPMPAugmentHook).interfaceId ||
+            super.supportsInterface(interfaceId);
+    }
+
+    /**
+     * @notice Gets the PMP inputs for the receive state update.
+     * @param receiveState The receive state to update.
+     * @return pmpInputs The PMP inputs for the receive state update.
+     * @dev This function is used to get the PMP inputs for the receive state update, based on what this hook uses.
+     */
+    function _getPmpInputsForReceiveStateUpdate(
+        ReceiveStates receiveState
+    ) internal pure returns (IPMPV0.PMPInput[] memory) {
+        // build PMPInputs for the receive state update, based on what this hook uses
+        IPMPV0.PMPInput[] memory pmpInputs = new IPMPV0.PMPInput[](1);
+        pmpInputs[0] = IPMPV0.PMPInput({
+            key: "ReceiveState",
+            configuredParamType: IPMPV0.ParamType.Select,
+            configuredValue: bytes32(uint256(receiveState)), // @dev enums are aligned with select options
+            configuringArtistString: false,
+            configuredValueString: ""
+        });
+        return pmpInputs;
+    }
+
+    /**
+     * @notice Gets the PMP inputs for the send state update.
+     * @param sendState The send state to update.
+     * @return pmpInputs The PMP inputs for the send state update.
+     * @dev This function is used to get the PMP inputs for the send state update, based on what this hook uses.
+     */
+    function _getPmpInputsForSendStateUpdate(
+        SendStates sendState
+    ) internal pure returns (IPMPV0.PMPInput[] memory) {
+        // build PMPInputs for the send state update, based on what this hook uses
+        IPMPV0.PMPInput[] memory pmpInputs = new IPMPV0.PMPInput[](1);
+        pmpInputs[0] = IPMPV0.PMPInput({
+            key: "SendState",
+            configuredParamType: IPMPV0.ParamType.Select,
+            configuredValue: bytes32(uint256(sendState)), // @dev enums are aligned with select options
+            configuringArtistString: false,
+            configuredValueString: ""
+        });
+        return pmpInputs;
+    }
+
+    /**
+     * @notice Gets the PMP inputs for the active slot update.
+     * @param activeSlot The active slot to update.
+     * @return pmpInputs The PMP inputs for the active slot update.
+     * @dev This function is used to get the PMP inputs for the active slot update, based on what this hook uses.
+     */
+    function _getPmpInputsForActiveSlotUpdate(
+        uint256 activeSlot
+    ) internal pure returns (IPMPV0.PMPInput[] memory) {
+        IPMPV0.PMPInput[] memory pmpInputs = new IPMPV0.PMPInput[](1);
+        pmpInputs[0] = IPMPV0.PMPInput({
+            key: "ActiveSlot",
+            configuredParamType: IPMPV0.ParamType.Uint256Range,
+            configuredValue: bytes32(uint256(activeSlot)),
+            configuringArtistString: false,
+            configuredValueString: ""
+        });
+        return pmpInputs;
+    }
+
+    /**
+     * @notice Gets the PMP inputs for the image data update.
+     * @param slot The slot to update.
+     * @param imageVersion The image version to update.
+     * @return pmpInputs The PMP inputs for the image data update.
+     * @dev This function is used to get the PMP inputs for the image data update, based on what this hook uses.
+     */
+    function _getPmpInputsForImageDataUpdate(
+        uint256 slot,
+        uint16 imageVersion
+    ) internal pure returns (IPMPV0.PMPInput[] memory) {
+        string memory key = string(
+            bytes.concat(
+                bytes("ImageVersionSlot"),
+                bytes(Strings.toString(slot))
+            )
+        );
+        // build PMPInputs for the image data update, based on what this hook uses
+        IPMPV0.PMPInput[] memory pmpInputs = new IPMPV0.PMPInput[](1);
+        pmpInputs[0] = IPMPV0.PMPInput({
+            key: key,
+            configuredParamType: IPMPV0.ParamType.Uint256Range,
+            configuredValue: bytes32(uint256(imageVersion)),
+            configuringArtistString: false,
+            configuredValueString: ""
+        });
+        return pmpInputs;
+    }
+
+    /**
+     * @notice Gets the PMP inputs for the sound data update.
+     * @param slot The slot to update.
+     * @param soundVersion The sound version to update.
+     * @return pmpInputs The PMP inputs for the sound data update.
+     * @dev This function is used to get the PMP inputs for the sound data update, based on what this hook uses.
+     */
+    function _getPmpInputsForSoundDataUpdate(
+        uint256 slot,
+        uint16 soundVersion
+    ) internal pure returns (IPMPV0.PMPInput[] memory) {
+        string memory key = string(
+            bytes.concat(
+                bytes("SoundVersionSlot"),
+                bytes(Strings.toString(slot))
+            )
+        );
+        // build PMPInputs for the sound data update, based on what this hook uses
+        IPMPV0.PMPInput[] memory pmpInputs = new IPMPV0.PMPInput[](1);
+        pmpInputs[0] = IPMPV0.PMPInput({
+            key: key,
+            configuredParamType: IPMPV0.ParamType.Uint256Range,
+            configuredValue: bytes32(uint256(soundVersion)),
+            configuringArtistString: false,
+            configuredValueString: ""
+        });
+        return pmpInputs;
+    }
+
+    /**
+     * @notice Gets a single element address array.
+     * @param address_ The address to include in the array.
+     * @return addressArray The single element address array containing the address.
+     */
+    function _getSingleElementAddressArray(
+        address address_
+    ) internal pure returns (address[] memory) {
+        address[] memory addressArray = new address[](1);
+        addressArray[0] = address_;
+        return addressArray;
+    }
+
+    /**
+     * @notice Authorizes an upgrade to a new implementation.
+     * @dev This function is required by the UUPS pattern and can only be called by the owner.
+     *
+     * UPGRADE SAFETY REQUIREMENTS:
+     * - All existing state variables MUST remain in their current storage slots
+     * - New state variables MUST be appended to the end (never inserted between existing variables)
+     * - Never modify the type or order of existing state variables
+     * - Never remove existing state variables (they can be deprecated but must remain)
+     * - The storage layout must be append-only to maintain compatibility
+     *
+     * @param newImplementation The address of the new implementation contract.
+     */
+    function _authorizeUpgrade(
+        address newImplementation
+    ) internal override onlyOwner {
+        // this version allows the owner to upgrade the contract to a new implementation
+        // in future versions, we may choose to disable this functionality and lock project functionality permanently
+    }
+
+    // --- HELPER FUNCTIONS FROM SOLADY https://github.com/Vectorized/solady/blob/main/src/utils/LibString.sol ---
+
+    /// @dev Returns the hex encoded string from the raw bytes.
+    /// The output is encoded using 2 hexadecimal digits per byte.
+    function toHexString(
+        bytes memory raw
+    ) internal pure returns (string memory result) {
+        result = toHexStringNoPrefix(raw);
+        /// @solidity memory-safe-assembly
+        assembly {
+            let n := add(mload(result), 2) // Compute the length.
+            mstore(result, 0x3078) // Store the "0x" prefix.
+            result := sub(result, 2) // Move the pointer.
+            mstore(result, n) // Store the length.
+        }
+    }
+
+    /// @dev Returns the hex encoded string from the raw bytes.
+    /// The output is encoded using 2 hexadecimal digits per byte.
+    function toHexStringNoPrefix(
+        bytes memory raw
+    ) internal pure returns (string memory result) {
+        /// @solidity memory-safe-assembly
+        assembly {
+            let n := mload(raw)
+            result := add(mload(0x40), 2) // Skip 2 bytes for the optional prefix.
+            mstore(result, add(n, n)) // Store the length of the output.
+
+            mstore(0x0f, 0x30313233343536373839616263646566) // Store the "0123456789abcdef" lookup.
+            let o := add(result, 0x20)
+            let end := add(raw, n)
+            for {
+
+            } iszero(eq(raw, end)) {
+
+            } {
+                raw := add(raw, 1)
+                mstore8(add(o, 1), mload(and(mload(raw), 15)))
+                mstore8(o, mload(and(shr(4, mload(raw)), 15)))
+                o := add(o, 2)
+            }
+            mstore(o, 0) // Zeroize the slot after the string.
+            mstore(0x40, add(o, 0x20)) // Allocate memory.
+        }
+    }
+}