@artblocks/contracts 1.3.1 → 1.4.0

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

@@ -0,0 +1,429 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title EnumerableSetUint16
+ * @author Art Blocks Inc.
+ * @notice Gas-optimized enumerable set library for uint16 values with assembly optimizations.
+ * @dev This library efficiently packs uint16 values into shared uint256 storage slots,
+ * storing up to 16 uint16 values per slot. This significantly reduces gas costs compared
+ * to OpenZeppelin's EnumerableSet.UintSet which stores each value in its own slot.
+ *
+ * The library maintains:
+ * - A packed array where each uint256 slot contains up to 16 uint16 values (stored as value+1)
+ * - An index mapping for O(1) lookups (maps value -> packed position)
+ *
+ * Values are stored as (value + 1) to distinguish empty slots (0) from actual values.
+ * This means the maximum storable value is 65534 (not 65535).
+ *
+ * Count is derived on-demand by examining the last slot to find the highest populated position.
+ * This eliminates an SSTORE operation on every add/remove, significantly reducing gas costs.
+ *
+ * Assembly is used extensively for:
+ * - Efficient bit manipulation operations
+ * - Optimized storage access patterns
+ * - Reduced memory operations
+ * - Binary search for finding highest offset
+ *
+ * Interface is compatible with OpenZeppelin's EnumerableSet.UintSet, but specifically
+ * for uint16 values.
+ */
+library EnumerableSetUint16 {
+    /**
+     * @dev Structure to hold the set data.
+     *
+     * Storage layout:
+     * - _values: Array of uint256 where each element packs 16 uint16 values (stored as value+1)
+     * - _indexesPacked: Packed mapping where each uint256 contains 16 positions (16 bits each)
+     *
+     * Position encoding: 16 bits per position = (slotIndex << 4) | offsetInSlot + 1
+     * - Bits 0-11: slotIndex (supports up to 4096 slots = 65,536 values)
+     * - Bits 12-15: offsetInSlot (0-15)
+     * - +1 makes it 1-indexed so 0 means "not present"
+     *
+     * Packing in _indexesPacked:
+     * - Key: value >> 4 (bucket index - groups of 16 values)
+     * - Value: uint256 containing 16 packed 16-bit positions
+     * - Position in bucket: value & 0xF (determines which 16-bit segment)
+     */
+    struct Uint16Set {
+        // Array of packed uint256 slots, each containing up to 16 uint16 values (as value+1)
+        uint256[] _values;
+        // Packed mapping: each uint256 holds 16 positions (16 bits each) for 16 consecutive values
+        // Bucket (value>>4) maps to uint256 with 16 positions at (value&0xF)*16 bits
+        mapping(uint16 => uint256) _indexesPacked;
+    }
+
+    /**
+     * @dev Add a value to a set. O(1).
+     * Returns true if the value was added to the set, that is if it was not
+     * already present.
+     * @param value The uint16 value to add. Must be < 65535 (max uint16 - 1).
+     */
+    function add(Uint16Set storage set, uint16 value) internal returns (bool) {
+        require(
+            value < type(uint16).max,
+            "EnumerableSetUint16: value too large"
+        );
+
+        if (contains(set, value)) {
+            return false;
+        }
+
+        uint256 count = length(set);
+        uint256 slotIndex;
+        uint256 offsetInSlot;
+
+        assembly {
+            // slotIndex = count >> 4 (count / 16)
+            slotIndex := shr(4, count)
+            // offsetInSlot = count & 0xF (count % 16)
+            offsetInSlot := and(count, 0xF)
+        }
+
+        // Ensure the slot exists
+        if (slotIndex >= set._values.length) {
+            set._values.push(0);
+        }
+
+        // Pack the value+1 into the slot using assembly
+        assembly {
+            // Calculate storage slot for _values[slotIndex]
+            mstore(0x00, set.slot)
+            let valuesSlot := keccak256(0x00, 0x20)
+            let targetSlot := add(valuesSlot, slotIndex)
+
+            // Load current slot value
+            let slot := sload(targetSlot)
+
+            // Calculate shift amount: offsetInSlot * 16
+            let shiftAmount := shl(4, offsetInSlot)
+
+            // Create mask: 0xFFFF << shiftAmount
+            let mask := shl(shiftAmount, 0xFFFF)
+
+            // Clear the target position and insert value+1
+            // slot = (slot & ~mask) | ((value + 1) << shiftAmount)
+            slot := or(and(slot, not(mask)), shl(shiftAmount, add(value, 1)))
+
+            // Store back
+            sstore(targetSlot, slot)
+        }
+
+        // Store the position (1-indexed) in packed format
+        // Position encodes: ((slotIndex << 4) | offsetInSlot) + 1
+        uint256 position;
+        assembly {
+            position := add(or(shl(4, slotIndex), offsetInSlot), 1)
+        }
+        _setPackedIndex(set._indexesPacked, value, position);
+
+        return true;
+    }
+
+    /**
+     * @dev Removes a value from a set. O(1).
+     * Returns true if the value was removed from the set, that is if it was
+     * present.
+     */
+    function remove(
+        Uint16Set storage set,
+        uint16 value
+    ) internal returns (bool) {
+        uint256 valueIndex = _getPackedIndex(set._indexesPacked, value);
+
+        if (valueIndex == 0) {
+            return false; // Value not in set
+        }
+
+        uint256 lastIndex = length(set) - 1;
+        uint256 valuePosition = valueIndex - 1;
+
+        // Calculate last slot position (used in both branches)
+        uint256 lastSlotIndex;
+        uint256 lastOffsetInSlot;
+        assembly {
+            lastSlotIndex := shr(4, lastIndex)
+            lastOffsetInSlot := and(lastIndex, 0xF)
+        }
+
+        if (lastIndex != valuePosition) {
+            uint256 lastValuePlusOne;
+
+            assembly {
+                // Load last value
+                mstore(0x00, set.slot)
+                let valuesSlot := keccak256(0x00, 0x20)
+                let lastSlot := sload(add(valuesSlot, lastSlotIndex))
+
+                // Extract last value: (lastSlot >> (lastOffsetInSlot * 16)) & 0xFFFF
+                lastValuePlusOne := and(
+                    shr(shl(4, lastOffsetInSlot), lastSlot),
+                    0xFFFF
+                )
+            }
+
+            // Move last value to the removed value's position
+            uint256 valueSlotIndex;
+            uint256 valueOffsetInSlot;
+
+            assembly {
+                valueSlotIndex := shr(4, valuePosition)
+                valueOffsetInSlot := and(valuePosition, 0xF)
+
+                // Calculate storage slot
+                mstore(0x00, set.slot)
+                let valuesSlot := keccak256(0x00, 0x20)
+                let targetSlot := add(valuesSlot, valueSlotIndex)
+
+                // Load current slot
+                let slot := sload(targetSlot)
+
+                // Calculate shift and mask
+                let shiftAmount := shl(4, valueOffsetInSlot)
+                let mask := shl(shiftAmount, 0xFFFF)
+
+                // Update slot: (slot & ~mask) | (lastValuePlusOne << shiftAmount)
+                slot := or(
+                    and(slot, not(mask)),
+                    shl(shiftAmount, lastValuePlusOne)
+                )
+
+                // Store back
+                sstore(targetSlot, slot)
+            }
+
+            // Update the moved value's index
+            _setPackedIndex(
+                set._indexesPacked,
+                uint16(lastValuePlusOne - 1),
+                valueIndex
+            );
+        }
+
+        // Clear the last position
+        bool shouldPop;
+
+        assembly {
+            // Calculate storage slot
+            mstore(0x00, set.slot)
+            let valuesSlot := keccak256(0x00, 0x20)
+            let targetSlot := add(valuesSlot, lastSlotIndex)
+
+            // Load current slot
+            let slot := sload(targetSlot)
+
+            // Clear the position: slot & ~(0xFFFF << (lastOffsetInSlot * 16))
+            let shiftAmount := shl(4, lastOffsetInSlot)
+            let mask := shl(shiftAmount, 0xFFFF)
+            slot := and(slot, not(mask))
+
+            // Store back
+            sstore(targetSlot, slot)
+
+            // Check if we should pop: slot is zero
+            shouldPop := iszero(slot)
+        }
+
+        // Pop the array if the last slot is now empty
+        if (shouldPop && lastSlotIndex == set._values.length - 1) {
+            set._values.pop();
+        }
+
+        // Delete the removed value's packed index
+        _setPackedIndex(set._indexesPacked, value, 0);
+
+        return true;
+    }
+
+    /**
+     * @dev Returns true if the value is in the set. O(1).
+     */
+    function contains(
+        Uint16Set storage set,
+        uint16 value
+    ) internal view returns (bool) {
+        return _getPackedIndex(set._indexesPacked, value) != 0;
+    }
+
+    /**
+     * @dev Returns the number of values in the set. O(1) amortized.
+     * Uses binary search to find the highest populated position in the last slot.
+     */
+    function length(
+        Uint16Set storage set
+    ) internal view returns (uint256 result) {
+        uint256 valuesLength = set._values.length;
+
+        if (valuesLength == 0) {
+            return 0;
+        }
+
+        uint256 lastSlot = set._values[valuesLength - 1];
+
+        // Use binary search to find highest non-zero 16-bit segment
+        uint256 highestOffset;
+        assembly {
+            let slot := lastSlot
+            highestOffset := 0
+
+            // Binary search for highest non-zero segment
+            // Check upper half (bits 128-255)
+            let upper := shr(128, slot)
+            if gt(upper, 0) {
+                highestOffset := 8
+                slot := upper
+            }
+
+            // Check upper 4 positions of current 8-position range
+            upper := shr(64, slot)
+            if gt(upper, 0) {
+                highestOffset := add(highestOffset, 4)
+                slot := upper
+            }
+
+            // Check upper 2 positions of current 4-position range
+            upper := shr(32, slot)
+            if gt(upper, 0) {
+                highestOffset := add(highestOffset, 2)
+                slot := upper
+            }
+
+            // Check upper 1 position of current 2-position range
+            upper := shr(16, slot)
+            if gt(upper, 0) {
+                highestOffset := add(highestOffset, 1)
+            }
+        }
+
+        // Calculate total length: ((valuesLength - 1) * 16) + highestOffset + 1
+        return ((valuesLength - 1) << 4) + highestOffset + 1;
+    }
+
+    /**
+     * @dev Returns the value stored at position `index` in the set. O(1).
+     *
+     * Note that there are no guarantees on the ordering of values inside the
+     * array, and it may change when more values are added or removed.
+     *
+     * Requirements:
+     * - `index` must be strictly less than {length}.
+     */
+    function at(
+        Uint16Set storage set,
+        uint256 index
+    ) internal view returns (uint16) {
+        require(
+            index < length(set),
+            "EnumerableSetUint16: index out of bounds"
+        );
+
+        uint256 result;
+        assembly {
+            // slotIndex = index >> 4
+            let slotIndex := shr(4, index)
+            // offsetInSlot = index & 0xF
+            let offsetInSlot := and(index, 0xF)
+
+            // Load slot value
+            mstore(0x00, set.slot)
+            let valuesSlot := keccak256(0x00, 0x20)
+            let slot := sload(add(valuesSlot, slotIndex))
+
+            // Extract value: (slot >> (offsetInSlot * 16)) & 0xFFFF - 1
+            result := sub(and(shr(shl(4, offsetInSlot), slot), 0xFFFF), 1)
+        }
+
+        return uint16(result);
+    }
+
+    /**
+     * @dev Returns an array containing all values in the set. O(N).
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive.
+     * This is designed to mostly be used by view accessors that are queried without any gas fees.
+     * Developers should keep in mind that this function has an unbounded cost, and using it as part
+     * of a state-changing function may render the function uncallable if the set grows to a point
+     * where copying to memory consumes too much gas to fit in a block.
+     */
+    function values(
+        Uint16Set storage set
+    ) internal view returns (uint256[] memory) {
+        uint256 count = length(set);
+        uint256[] memory result = new uint256[](count);
+
+        for (uint256 i = 0; i < count; i++) {
+            result[i] = at(set, i);
+        }
+
+        return result;
+    }
+
+    /**
+     * @dev Internal helper to get a packed index for a value.
+     * @param packed The packed index mapping.
+     * @param value The uint16 value to look up.
+     * @return position The position (1-indexed, 0 means not present).
+     */
+    function _getPackedIndex(
+        mapping(uint16 => uint256) storage packed,
+        uint16 value
+    ) private view returns (uint256 position) {
+        assembly {
+            // bucketIndex = value >> 4
+            let bucketIndex := shr(4, value)
+            // posInBucket = value & 0xF
+            let posInBucket := and(value, 0xF)
+
+            // Calculate storage slot for packed[bucketIndex]
+            mstore(0x00, bucketIndex)
+            mstore(0x20, packed.slot)
+            let bucketSlot := keccak256(0x00, 0x40)
+
+            // Load bucket
+            let bucket := sload(bucketSlot)
+
+            // Extract position: (bucket >> (posInBucket * 16)) & 0xFFFF
+            position := and(shr(shl(4, posInBucket), bucket), 0xFFFF)
+        }
+    }
+
+    /**
+     * @dev Internal helper to set a packed index for a value.
+     * @param packed The packed index mapping.
+     * @param value The uint16 value to set.
+     * @param position The position to store (1-indexed, 0 means remove).
+     */
+    function _setPackedIndex(
+        mapping(uint16 => uint256) storage packed,
+        uint16 value,
+        uint256 position
+    ) private {
+        assembly {
+            // bucketIndex = value >> 4
+            let bucketIndex := shr(4, value)
+            // posInBucket = value & 0xF
+            let posInBucket := and(value, 0xF)
+
+            // Calculate storage slot for packed[bucketIndex]
+            mstore(0x00, bucketIndex)
+            mstore(0x20, packed.slot)
+            let bucketSlot := keccak256(0x00, 0x40)
+
+            // Load current bucket
+            let bucket := sload(bucketSlot)
+
+            // Calculate shift and mask
+            let shiftAmount := shl(4, posInBucket)
+            let mask := shl(shiftAmount, 0xFFFF)
+
+            // Update bucket: (bucket & ~mask) | (position << shiftAmount)
+            bucket := or(and(bucket, not(mask)), shl(shiftAmount, position))
+
+            // Store back
+            sstore(bucketSlot, bucket)
+        }
+    }
+}

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;
+            }
+        }
+    }
+}