@artblocks/contracts 1.3.2 → 1.4.0

package/contracts/libs/v0.8.x/FeistelWalkLib.sol

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/**
+ * @title FeistelWalkLib
+ * @author Art Blocks Inc.
+ * @notice Uniform once-over traversal of [0..N) via a seeded Feistel permutation.
+ * @dev Designed for off-chain eth_call sampling (e.g., pick K=100 from N≈10k).
+ *      - No duplicates, full coverage if you iterate k=0..N-1
+ *      - O(1) per index; O(K) to sample K items
+ *      - Works for any N (uses cycle-walking from next power-of-two domain)
+ *      - Not cryptographic; optimized for gas efficiency with good mixing
+ *  Uses 2 Feistel rounds with 64-bit round keys (k0, k1) derived from the seed.
+ *  Additional keys (k2, k3) reserved for potential future use.
+ *
+ *  The Feistel domain is exactly 2^logM = M (the next power of two >= N) for both
+ *  even and odd logM, achieved with an UNBALANCED split in `_feistelOnPow2Domain`
+ *  (`a = logM/2`, `b = logM - a`, `a + b = logM`). This keeps M <= 2N, so the
+ *  cycle-walk in-range probability is >= ~0.5 and a full traversal (k = 0..N-1) is
+ *  a true permutation of [0..N) with no duplicates or drops.
+ */
+library FeistelWalkLib {
+    uint256 private constant MAX_CYCLE_WALKS = 32;
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+
+    /// @notice Immutable traversal plan (deterministic from (seed, N)).
+    /// @dev Build once per call, then stream with `index(plan, k)` or batch via `sample(plan, K)`.
+    struct Plan {
+        uint256 N; // pool size (>= 1)
+        uint256 M; // next power-of-two >= N (<= 2N)
+        uint256 logM; // log2(M) - precomputed to avoid repeated calculation
+        uint256 rounds; // Feistel rounds (2 for gas-efficient mixing)
+        uint64 k0; // Round key 0
+        uint64 k1; // Round key 1
+    }
+
+    /// @notice Build a Feistel permutation plan over [0..N).
+    /// @param seed Arbitrary seed (domain-separate upstream if you like).
+    /// @param N    Domain size; must be > 0.
+    function makePlan(
+        bytes32 seed,
+        uint256 N
+    ) internal pure returns (Plan memory p) {
+        require(N > 0, "FeistelWalkLib:N=0");
+        p.N = N;
+        p.M = _nextPow2(N); // <= 2N
+        p.logM = _log2ceil(p.M); // precompute to avoid repeated calculation
+        p.rounds = 2; // 2 rounds provides good mixing with lower gas cost
+
+        // Derive round keys for 2-round Feistel
+        p.k0 = uint64(
+            uint256(keccak256(abi.encodePacked(seed, "feistel.k0", N)))
+        );
+        p.k1 = uint64(
+            uint256(keccak256(abi.encodePacked(seed, "feistel.k1", N)))
+        );
+    }
+
+    /// @notice Stream the k-th index in the seeded permutation.
+    /// @dev Requires 0 <= k < N. O(1) arithmetic; bounded cycle-walk if N not power of two.
+    function index(
+        Plan memory p,
+        uint256 k
+    ) internal pure returns (uint256 idx) {
+        require(k < p.N, "FeistelWalkLib:k>=N");
+        if (p.N == 1) return 0; // trivial domain
+
+        // Permute k into [0..N) using Feistel over [0..M) + cycle-walking
+        return _feistelPermuteRange(k, p.N, p.M, p.logM, p.rounds, p.k0, p.k1);
+    }
+
+    /// @notice Return up to K indices from the permutation (k = 0..K-1).
+    /// @dev If K > N, it clamps to N. Allocates an array of size K'.
+    function sample(
+        Plan memory p,
+        uint256 K
+    ) internal pure returns (uint256[] memory out) {
+        if (K > p.N) K = p.N;
+        out = new uint256[](K);
+        unchecked {
+            for (uint256 i = 0; i < K; ++i) {
+                out[i] = index(p, i);
+            }
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Internal: Feistel on arbitrary N via power-of-two domain + cycle-walk
+    // -------------------------------------------------------------------------
+
+    /// @dev Permute x∈[0..N) by embedding into [0..M) (M power of two), running Feistel,
+    ///      then cycle-walking until result < N. With M < 2N, p = N/M ≥ ~0.5 in worst case.
+    ///      Hard-cap at MAX_CYCLE_WALKS to guarantee bounded work; on overflow, return `x`.
+    function _feistelPermuteRange(
+        uint256 x,
+        uint256 N,
+        uint256 M,
+        uint256 logM,
+        uint256 rounds,
+        uint64 k0,
+        uint64 k1
+    ) private pure returns (uint256) {
+        if (N == 1) return 0; // trivial domain
+        uint256 y = x;
+        unchecked {
+            for (uint256 i = 0; i < MAX_CYCLE_WALKS; ++i) {
+                uint256 z = _feistelOnPow2Domain(y, M, logM, rounds, k0, k1);
+                if (z < N) return z; // landed inside domain
+                y = z; // cycle-walk and try again
+            }
+        }
+        // Ultra-rare guard: deterministic in-domain fallback (keeps progress).
+        return x;
+    }
+
+    /// @dev Feistel permutation over [0..M) where M is a power of two.
+    ///      Split into a low half (a bits) and a high half (b bits) with
+    ///      a + b = logM, and apply the round function twice for good mixing.
+    ///      Using an UNBALANCED split (a = logM/2, b = logM - a) keeps the domain
+    ///      exactly 2^logM = M for both even and odd logM. A balanced split
+    ///      (half = (logM + 1) / 2) would span 2*half = logM + 1 bits for odd logM
+    ///      and therefore permute [0, 2M) instead of [0, M); the wider domain pushes
+    ///      the cycle-walk past its cap for N just above a power of two and triggers
+    ///      the identity `return x` fallback, breaking the bijection (duplicate /
+    ///      missing elements). Each round masks its output to the width of the half
+    ///      it writes, so every round is invertible and the whole map is a bijection
+    ///      over [0, M). For even logM, a == b and this is identical to a balanced
+    ///      split.
+    function _feistelOnPow2Domain(
+        uint256 x,
+        uint256 M,
+        uint256 logM,
+        uint256 /* rounds */,
+        uint64 k0,
+        uint64 k1
+    ) private pure returns (uint256) {
+        if (M == 1) return 0; // degenerate
+        if (M == 2) {
+            // Special case: 2-element domain, use key to determine permutation
+            return ((k0 & 1) == 0) ? x : (1 - x);
+        }
+
+        // Full assembly for maximum gas efficiency
+        uint256 result;
+        assembly {
+            // Unbalanced Feistel: low half is `a` bits, high half is `b` bits,
+            // with a + b = logM (so the domain is exactly 2^logM = M).
+            let a := div(logM, 2)
+            let b := sub(logM, a)
+            let maskA := sub(shl(a, 1), 1)
+            let maskB := sub(shl(b, 1), 1)
+
+            // Split into L (low, a bits) and R (high, b bits)
+            let L := and(x, maskA)
+            let R := and(shr(a, x), maskB)
+
+            // Round 0: R (b bits) -> a-bit register
+            let F := and(R, 0xFFFFFFFFFFFFFFFF)
+            F := xor(F, k0)
+            F := xor(F, shl(13, F))
+            F := xor(F, shr(7, F))
+            F := xor(F, shl(17, F))
+            F := xor(F, shr(5, F))
+
+            let newR := and(xor(L, F), maskA) // a bits
+            L := R // b bits
+            R := newR // a bits
+
+            // Round 1: R (a bits) -> b-bit register
+            F := and(R, 0xFFFFFFFFFFFFFFFF)
+            F := xor(F, xor(k1, 1))
+            F := xor(F, shl(13, F))
+            F := xor(F, shr(7, F))
+            F := xor(F, shl(17, F))
+            F := xor(F, shr(5, F))
+
+            newR := and(xor(L, F), maskB) // b bits
+            L := R // a bits
+            R := newR // b bits
+
+            // Recombine: R (b bits) high, L (a bits) low => a + b = logM bits
+            result := or(shl(a, R), L)
+        }
+        return result;
+    }
+
+    // -------------------------------------------------------------------------
+    // Internal: Bit helpers
+    // -------------------------------------------------------------------------
+
+    /// @dev Next power of two ≥ x. For x==0, returns 1.
+    function _nextPow2(uint256 x) private pure returns (uint256) {
+        if (x <= 1) return 1;
+        unchecked {
+            x -= 1;
+            x |= x >> 1;
+            x |= x >> 2;
+            x |= x >> 4;
+            x |= x >> 8;
+            x |= x >> 16;
+            x |= x >> 32;
+            x |= x >> 64;
+            x |= x >> 128;
+            return x + 1;
+        }
+    }
+
+    /// @dev ceil(log2(x)) for x≥1. (Number of bits to represent x-1.)
+    function _log2ceil(uint256 x) private pure returns (uint256 n) {
+        require(x > 0, "log2ceil(0)");
+        unchecked {
+            x -= 1;
+            while (x > 0) {
+                x >>= 1;
+                ++n;
+            }
+        }
+    }
+}

package/contracts/libs/v0.8.x/ImmutableUint16Array.sol

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+pragma solidity ^0.8.0;
+
+import {SSTORE2} from "./SSTORE2.sol"; // Import SSTORE2 library
+
+/**
+ * @title ImmutableUint16Array
+ * @author Art Blocks Inc.
+ * @notice This library is optimized to store immutable arrays of uint16 values much more efficiently than using native Solidity storage arrays.
+ * It uses a single SSTORE2 contract to store the length + packed uint16 values
+ * Allows overwriting the pointer to point to a new immutable array.
+ */
+library ImmutableUint16Array {
+    /**
+     * @notice Struct to store the SSTORE2 pointer to the packed uint16 array.
+     * @dev dataPointer is the SSTORE2 pointer to the packed uint16 array. Assigned to address(0) if the array is empty.
+     */
+    struct Uint16Array {
+        address dataPointer; // SSTORE2 pointer storing length + packed uint16 values
+    }
+
+    /**
+     * @notice Stores a packed immutable uint16 array using a single SSTORE2 contract.
+     * Allows overwriting the pointer to point to a new immutable array.
+     * @dev Optimized for the case where the array is empty by assigning the dataPointer to address(0).
+     * @param storageArray The storage reference to store the packed array.
+     * @param values The array of strings to pack.
+     */
+    function store(
+        Uint16Array storage storageArray,
+        uint16[] memory values
+    ) internal {
+        uint256 arrayLength = values.length;
+        // edge case - empty array
+        if (arrayLength == 0) {
+            storageArray.dataPointer = address(0);
+            return;
+        }
+        // realistically will not overflow uint16, but check for security guarantees
+        // @dev no coverage on else (difficulty of triggering)
+        require(
+            arrayLength <= type(uint16).max,
+            "Total bytes length exceeds uint16 limit"
+        );
+
+        // compute total bytes length
+        // @dev this is deterministic and can be pre-computed since it is a fixed size array
+        uint256 totalBytesLength = arrayLength * 2; // 2 bytes per uint16
+
+        // prepare the combined storage structure (length + packed uint16 values)
+        // @dev 8 bytes for length, totalBytesLength bytes for uint16 values
+        // over-allocate 32 bytes for memory safety
+        // note: shorten length by 32 bytes at end of function before returning
+        uint256 packedDataLength = 8 + totalBytesLength;
+        bytes memory packedData = new bytes(packedDataLength + 0x20);
+        uint256 ptr;
+
+        // store the length of the values array in the first 8 bytes of the packedData
+        assembly ("memory-safe") {
+            ptr := add(packedData, 0x20) // pointer to first byte of packedData
+            mstore(ptr, shl(192, arrayLength)) // left-align only 8 bytes in the 32-byte slot
+            ptr := add(ptr, 8) // move pointer forward by 8 bytes
+        }
+
+        // pack the values efficiently, using assembly to compile 32 bytes at a time
+        for (uint i = 0; i < arrayLength; i += 16) {
+            // 16 indices per loop, 2 bytes per index, 32 bytes per loop
+            // build the 32 bytes of the current value, 16 uint16 values per loop, left to right
+            // handle end of array case
+            uint256 maxIndex = i + 16 < arrayLength ? i + 16 : arrayLength;
+            bytes32 chunk;
+            for (uint j = 0; j < (maxIndex - i); j++) {
+                chunk |= bytes32(uint256(values[i + j])) << (240 - (j * 16));
+            }
+            // store the 32 bytes into the result
+            assembly ("memory-safe") {
+                // safe to write past end of final array - 32 bytes of buffer at end of array
+                mstore(ptr, chunk) // store the 32 bytes into the result
+                ptr := add(ptr, 0x20) // move the result pointer forward by 32 bytes
+            }
+        }
+
+        // remove the buffer from the packedData bytes array length
+        assembly ("memory-safe") {
+            ptr := packedData
+            mstore(ptr, packedDataLength)
+        }
+
+        // store the packed data in the SSTORE2 contract
+        storageArray.dataPointer = SSTORE2.write(packedData);
+    }
+
+    /**
+     * @notice Clears the storage array by setting the dataPointer to address(0).
+     * @param storageArray The storage reference to clear.
+     */
+    function clear(Uint16Array storage storageArray) internal {
+        storageArray.dataPointer = address(0);
+    }
+
+    function isEmpty(
+        Uint16Array storage storageArray
+    ) internal view returns (bool) {
+        return storageArray.dataPointer == address(0);
+    }
+
+    /**
+     * @notice Retrieves the total number of stored uint16 values from SSTORE2.
+     * @param storageArray The storage reference containing packed values.
+     * @return count The count of stored values.
+     */
+    function length(
+        Uint16Array storage storageArray
+    ) internal view returns (uint256 count) {
+        // edge case - unassigned dataPointer or empty array
+        if (storageArray.dataPointer == address(0)) {
+            return 0;
+        }
+
+        // load the packed data from the SSTORE2 contract
+        bytes memory allData = SSTORE2.read(storageArray.dataPointer);
+        // load the total length of the values array from the first 8 bytes of the SSTORE2 contract
+        assembly ("memory-safe") {
+            count := shr(192, mload(add(allData, 32))) // skip first 8 bytes (length of the actual bytes array we stored)
+        }
+    }
+
+    /**
+     * @notice Retrieves a single uint16 value from storage by index.
+     * @param storageArray The storage reference containing packed values.
+     * @param index The index of the value to retrieve.
+     * @return result The retrieved value.
+     */
+    function get(
+        Uint16Array storage storageArray,
+        uint256 index
+    ) internal view returns (uint16 result) {
+        // edge case - unassigned dataPointer or empty array
+        if (storageArray.dataPointer == address(0)) {
+            revert("Index out of bounds");
+        }
+        // load the packed data from the SSTORE2 contract
+        bytes memory allData = SSTORE2.read(storageArray.dataPointer);
+        // load the total length of the values array from the first 8 bytes of the SSTORE2 contract
+        uint256 arrayLength;
+        assembly ("memory-safe") {
+            arrayLength := shr(192, mload(add(allData, 32))) // skip first 8 bytes (length of the actual bytes array we stored)
+        }
+        require(index < arrayLength, "Index out of bounds");
+
+        // the location is deterministic and can be pre-computed since it is a fixed size array
+        uint256 location = 32 + 8 + (index * 2); // 32 bytes for bytes array length, 8 bytes for overall array length, 2 bytes per index
+        // load the value from the packed data
+        assembly ("memory-safe") {
+            result := shr(240, mload(add(allData, location))) // load the 2 bytes of the value from the packed data
+        }
+    }
+
+    /**
+     * @notice Retrieves all stored uint16 values in a single batch call.
+     * @param storageArray The storage reference containing packed values.
+     * @return results An array of all stored values.
+     */
+    function getAll(
+        Uint16Array storage storageArray
+    ) internal view returns (uint16[] memory results) {
+        // edge case - unassigned dataPointer or empty array
+        if (storageArray.dataPointer == address(0)) {
+            return new uint16[](0);
+        }
+        // load the packed data from the SSTORE2 contract
+        bytes memory allData = SSTORE2.read(storageArray.dataPointer);
+        // load the total length of the values array from the first 8 bytes of the SSTORE2 contract
+        uint256 arrayLength;
+        assembly ("memory-safe") {
+            arrayLength := shr(192, mload(add(allData, 32))) // skip first 8 bytes (length of the actual bytes array we stored)
+        }
+
+        // for each value in the array, populate results
+        results = new uint16[](arrayLength);
+
+        // loop in assembly to access the packed data directly
+        assembly ("memory-safe") {
+            let ptr := add(allData, 40) // skip first 8 bytes + 32 bytes for bytes array length (length of the actual bytes array we stored)
+            for {
+                let i := 0
+            } lt(i, arrayLength) {
+                i := add(i, 1)
+            } {
+                // @dev in memory, uint16 values are not packed, but are abi-encoded, so we add mul i * 0x20 to get the offset of the value in the results array
+                mstore(
+                    add(results, add(mul(i, 0x20), 0x20)),
+                    shr(240, mload(ptr))
+                ) // store the 2 bytes of the value from the packed data into the results array
+                ptr := add(ptr, 2) // move the pointer forward by 2 bytes for next iteration
+            }
+        }
+    }
+}