arr00-testing-oz-contracts 0.0.0 → 5.8.0

package/utils/math/SignedMath.sol

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.1.0) (utils/math/SignedMath.sol)
+
+pragma solidity ^0.8.20;
+
+import {SafeCast} from "./SafeCast.sol";
+
+/**
+ * @dev Standard signed math utilities missing in the Solidity language.
+ */
+library SignedMath {
+    /**
+     * @dev Branchless ternary evaluation for `a ? b : c`. Gas costs are constant.
+     *
+     * IMPORTANT: This function may reduce bytecode size and consume less gas when used standalone.
+     * However, the compiler may optimize Solidity ternary operations (i.e. `a ? b : c`) to only compute
+     * one branch when needed, making this function more expensive.
+     */
+    function ternary(bool condition, int256 a, int256 b) internal pure returns (int256) {
+        unchecked {
+            // branchless ternary works because:
+            // b ^ (a ^ b) == a
+            // b ^ 0 == b
+            return b ^ ((a ^ b) * int256(SafeCast.toUint(condition)));
+        }
+    }
+
+    /**
+     * @dev Returns the largest of two signed numbers.
+     */
+    function max(int256 a, int256 b) internal pure returns (int256) {
+        return ternary(a > b, a, b);
+    }
+
+    /**
+     * @dev Returns the smallest of two signed numbers.
+     */
+    function min(int256 a, int256 b) internal pure returns (int256) {
+        return ternary(a < b, a, b);
+    }
+
+    /**
+     * @dev Returns the average of two signed numbers without overflow.
+     * The result is rounded towards zero.
+     */
+    function average(int256 a, int256 b) internal pure returns (int256) {
+        // Formula from the book "Hacker's Delight"
+        int256 x = (a & b) + ((a ^ b) >> 1);
+        return x + (int256(uint256(x) >> 255) & (a ^ b));
+    }
+
+    /**
+     * @dev Returns the absolute unsigned value of a signed value.
+     */
+    function abs(int256 n) internal pure returns (uint256) {
+        unchecked {
+            // Formula from the "Bit Twiddling Hacks" by Sean Eron Anderson.
+            // Since `n` is a signed integer, the generated bytecode will use the SAR opcode to perform the right shift,
+            // taking advantage of the most significant (or "sign" bit) in two's complement representation.
+            // This opcode adds new most significant bits set to the value of the previous most significant bit. As a result,
+            // the mask will either be `bytes32(0)` (if n is positive) or `~bytes32(0)` (if n is negative).
+            int256 mask = n >> 255;
+
+            // A `bytes32(0)` mask leaves the input unchanged, while a `~bytes32(0)` mask complements it.
+            return uint256((n + mask) ^ mask);
+        }
+    }
+}

package/utils/structs/Accumulators.sol

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.6.0) (utils/structs/Accumulators.sol)
+
+pragma solidity ^0.8.24;
+
+import {Memory} from "../Memory.sol";
+import {Panic} from "../Panic.sol";
+
+/**
+ * @dev Structure concatenating an arbitrary number of bytes buffers with limited memory allocation.
+ *
+ * The Accumulators library provides a memory-efficient alternative to repeated concatenation of bytes.
+ * Instead of copying data on each concatenation (O(n**2) complexity), it builds a linked list of references
+ * to existing data and performs a single memory allocation during flattening (O(n) complexity).
+ *
+ * Uses 0x00 as sentinel value for empty state (i.e. null pointers)
+ *
+ * ==== How it works
+ *
+ * 1. Create an empty accumulator with null head/tail pointers
+ * 2. Add data using {push} (append) or {shift} (prepend). It creates linked list nodes
+ * 3. Each node stores a reference to existing data (no copying)
+ * 4. Call {flatten} to materialize the final concatenated result in a single operation
+ *
+ * ==== Performance
+ *
+ * * Addition: O(1) per operation (just pointer manipulation)
+ * * Flattening: O(n) single pass with one memory allocation
+ * * Memory: Minimal overhead until flattening (only stores references)
+ */
+library Accumulators {
+    using Memory for *;
+
+    /**
+     * @dev Bytes accumulator: a linked list of `bytes`.
+     *
+     * NOTE: This is a memory structure that SHOULD NOT be put in storage.
+     */
+    struct Accumulator {
+        Memory.Pointer head;
+        Memory.Pointer tail;
+    }
+
+    /// @dev Item (list node) in a bytes accumulator
+    struct AccumulatorEntry {
+        Memory.Pointer next;
+        Memory.Slice data;
+    }
+
+    /// @dev Create a new (empty) accumulator
+    function accumulator() internal pure returns (Accumulator memory self) {
+        self.head = _nullPtr();
+        self.tail = _nullPtr();
+    }
+
+    /// @dev Add a bytes buffer to (the end of) an Accumulator
+    function push(Accumulator memory self, bytes memory data) internal pure returns (Accumulator memory) {
+        return push(self, data.asSlice());
+    }
+
+    /// @dev Add a memory slice to (the end of) an Accumulator
+    function push(Accumulator memory self, Memory.Slice data) internal pure returns (Accumulator memory) {
+        if (!data.isReserved()) Panic.panic(Panic.RESOURCE_ERROR);
+
+        Memory.Pointer ptr = _asPtr(AccumulatorEntry({next: _nullPtr(), data: data}));
+
+        if (_nullPtr().equal(self.head)) {
+            self.head = ptr;
+            self.tail = ptr;
+        } else {
+            _asAccumulatorEntry(self.tail).next = ptr;
+            self.tail = ptr;
+        }
+
+        return self;
+    }
+
+    /// @dev Add a bytes buffer to (the beginning of) an Accumulator
+    function shift(Accumulator memory self, bytes memory data) internal pure returns (Accumulator memory) {
+        return shift(self, data.asSlice());
+    }
+
+    /// @dev Add a memory slice to (the beginning of) an Accumulator
+    function shift(Accumulator memory self, Memory.Slice data) internal pure returns (Accumulator memory) {
+        if (!data.isReserved()) Panic.panic(Panic.RESOURCE_ERROR);
+
+        Memory.Pointer ptr = _asPtr(AccumulatorEntry({next: self.head, data: data}));
+
+        if (_nullPtr().equal(self.head)) {
+            self.head = ptr;
+            self.tail = ptr;
+        } else {
+            self.head = ptr;
+        }
+
+        return self;
+    }
+
+    /// @dev Flatten all the bytes entries in an Accumulator into a single buffer
+    function flatten(Accumulator memory self) internal pure returns (bytes memory result) {
+        assembly ("memory-safe") {
+            result := mload(0x40)
+            let ptr := add(result, 0x20)
+            for {
+                let it := mload(self)
+            } iszero(iszero(it)) {
+                it := mload(it)
+            } {
+                let slice := mload(add(it, 0x20))
+                let offset := and(slice, shr(128, not(0)))
+                let length := shr(128, slice)
+                mcopy(ptr, offset, length)
+                ptr := add(ptr, length)
+            }
+            mstore(result, sub(ptr, add(result, 0x20)))
+            mstore(0x40, ptr)
+        }
+    }
+
+    function _asPtr(AccumulatorEntry memory item) private pure returns (Memory.Pointer ptr) {
+        assembly ("memory-safe") {
+            ptr := item
+        }
+    }
+
+    function _asAccumulatorEntry(Memory.Pointer ptr) private pure returns (AccumulatorEntry memory item) {
+        assembly ("memory-safe") {
+            item := ptr
+        }
+    }
+
+    function _nullPtr() private pure returns (Memory.Pointer) {
+        return Memory.Pointer.wrap(0);
+    }
+}

package/utils/structs/BitMaps.sol

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.7.0) (utils/structs/BitMaps.sol)
+
+pragma solidity ^0.8.20;
+
+/**
+ * @dev Library for managing uint256 to bool mapping in a compact and efficient way, provided the keys are sequential.
+ * Largely inspired by Uniswap's https://github.com/Uniswap/merkle-distributor/blob/master/contracts/MerkleDistributor.sol[merkle-distributor].
+ *
+ * BitMaps pack 256 booleans across each bit of a single 256-bit slot of `uint256` type.
+ * Hence booleans corresponding to 256 _sequential_ indices would only consume a single slot,
+ * unlike the regular `bool` which would consume an entire slot for a single value.
+ *
+ * This results in gas savings in two ways:
+ *
+ * - Setting a zero value to non-zero only once every 256 times
+ * - Accessing the same warm slot for every 256 _sequential_ indices
+ */
+library BitMaps {
+    struct BitMap {
+        mapping(uint256 bucket => uint256) _data;
+    }
+
+    /**
+     * @dev Returns whether the bit at `index` is set.
+     */
+    function get(BitMap storage bitmap, uint256 index) internal view returns (bool) {
+        uint256 bucket = index >> 8;
+        uint256 mask = 1 << (index & 0xff);
+        return bitmap._data[bucket] & mask != 0;
+    }
+
+    /**
+     * @dev Sets the bit at `index` to the boolean `value`.
+     */
+    function setTo(BitMap storage bitmap, uint256 index, bool value) internal {
+        if (value) {
+            set(bitmap, index);
+        } else {
+            unset(bitmap, index);
+        }
+    }
+
+    /**
+     * @dev Sets the bit at `index`.
+     */
+    function set(BitMap storage bitmap, uint256 index) internal {
+        uint256 bucket = index >> 8;
+        uint256 mask = 1 << (index & 0xff);
+        bitmap._data[bucket] |= mask;
+    }
+
+    /**
+     * @dev Unsets the bit at `index`.
+     */
+    function unset(BitMap storage bitmap, uint256 index) internal {
+        uint256 bucket = index >> 8;
+        uint256 mask = 1 << (index & 0xff);
+        bitmap._data[bucket] &= ~mask;
+    }
+}