@1inch/solidity-utils 3.8.3 → 4.1.0

package/contracts/libraries/AddressArray.sol

@@ -2,98 +2,227 @@
 
 pragma solidity ^0.8.0;
 
-/// @title Library that implements address array on mapping, stores array length at 0 index.
+/**
+ * @title AddressArray
+ * @notice Implements a dynamic array of addresses using a mapping for storage efficiency, with the array length stored at index 0.
+ * @dev This library provides basic functionalities such as push, pop, set, and retrieval of addresses in a storage-efficient manner.
+ */
 library AddressArray {
+    /**
+     * @dev Error thrown when attempting to access an index outside the bounds of the array.
+     */
     error IndexOutOfBounds();
+
+    /**
+     * @dev Error thrown when attempting to pop an element from an empty array.
+     */
     error PopFromEmptyArray();
+
+    /**
+     * @dev Error thrown when the output array provided for getting the list of addresses is too small.
+     */
     error OutputArrayTooSmall();
 
-    /// @dev Data struct containing raw mapping.
+    uint256 internal constant _ZERO_ADDRESS = 0x8000000000000000000000000000000000000000000000000000000000000000; // Next tx gas optimization
+    uint256 internal constant _LENGTH_MASK  = 0x0000000000000000ffffffff0000000000000000000000000000000000000000;
+    uint256 internal constant _ADDRESS_MASK = 0x000000000000000000000000ffffffffffffffffffffffffffffffffffffffff;
+    uint256 internal constant _ONE_LENGTH   = 0x0000000000000000000000010000000000000000000000000000000000000000;
+    uint256 internal constant _LENGTH_OFFSET = 160;
+
+    /**
+     * @dev Struct containing the raw mapping used to store the addresses and the array length.
+     */
     struct Data {
-        mapping(uint256 => uint256) _raw;
+        uint256[1 << 32] _raw;
     }
 
-    /// @dev Length of array.
+    /**
+     * @notice Returns the number of addresses stored in the array.
+     * @param self The instance of the Data struct.
+     * @return The number of addresses.
+     */
     function length(Data storage self) internal view returns (uint256) {
-        return self._raw[0] >> 160;
+        return (self._raw[0] & _LENGTH_MASK) >> _LENGTH_OFFSET;
     }
 
-    /// @dev Returns data item from `self` storage at `i`.
+    /**
+     * @notice Retrieves the address at a specified index in the array.
+     * @param self The instance of the Data struct.
+     * @param i The index to retrieve the address from.
+     * @return The address stored at the specified index.
+     */
     function at(Data storage self, uint256 i) internal view returns (address) {
-        return address(uint160(self._raw[i]));
+        if (i >= 1 << 32) revert IndexOutOfBounds();
+        return address(uint160(self._raw[i] & _ADDRESS_MASK));
     }
 
-    /// @dev Returns list of addresses from storage `self`.
-    function get(Data storage self) internal view returns (address[] memory arr) {
-        uint256 lengthAndFirst = self._raw[0];
-        arr = new address[](lengthAndFirst >> 160);
-        _get(self, arr, lengthAndFirst);
-    }
+    /**
+     * @notice Returns all addresses in the array from storage.
+     * @param self The instance of the Data struct.
+     * @return output Array containing all the addresses.
+     */
+    function get(Data storage self) internal view returns (address[] memory output) {
+        assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
+            let lengthAndFirst := sload(self.slot)
+            let len := shr(_LENGTH_OFFSET, and(lengthAndFirst, _LENGTH_MASK))
+            let fst := and(lengthAndFirst, _ADDRESS_MASK)
 
-    /// @dev Puts list of addresses from `self` storage into `output` array.
-    function get(Data storage self, address[] memory output) internal view returns (address[] memory) {
-        return _get(self, output, self._raw[0]);
+            // Allocate array
+            output := mload(0x40)
+            mstore(0x40, add(output, mul(0x20, add(1, len))))
+            mstore(output, len)
+
+            if len {
+                // Copy first element and then the rest in a loop
+                let ptr := add(output, 0x20)
+                mstore(ptr, fst)
+                for { let i := 1 } lt(i, len) { i:= add(i, 1) } {
+                    let item := and(sload(add(self.slot, i)), _ADDRESS_MASK)
+                    mstore(add(ptr, mul(0x20, i)), item)
+                }
+            }
+        }
     }
 
-    function _get(
-        Data storage self,
-        address[] memory output,
-        uint256 lengthAndFirst
-    ) private view returns (address[] memory) {
-        uint256 len = lengthAndFirst >> 160;
-        if (len > output.length) revert OutputArrayTooSmall();
-        if (len > 0) {
-            output[0] = address(uint160(lengthAndFirst));
-            unchecked {
-                for (uint256 i = 1; i < len; i++) {
-                    output[i] = address(uint160(self._raw[i]));
+    /**
+     * @notice Copies the addresses into the provided output array.
+     * @param self The instance of the Data struct.
+     * @param input The array to copy the addresses into.
+     * @return output The provided output array filled with addresses.
+     */
+    function get(Data storage self, address[] memory input) internal view returns (address[] memory output) {
+        output = input;
+        bytes4 err = OutputArrayTooSmall.selector;
+        assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
+            let lengthAndFirst := sload(self.slot)
+            let len := shr(_LENGTH_OFFSET, and(lengthAndFirst, _LENGTH_MASK))
+            let fst := and(lengthAndFirst, _ADDRESS_MASK)
+
+            if gt(len, mload(input)) {
+                mstore(0, err)
+                revert(0, 4)
+            }
+            if len {
+                // Copy first element and then the rest in a loop
+                let ptr := add(output, 0x20)
+                mstore(ptr, fst)
+                for { let i := 1 } lt(i, len) { i:= add(i, 1) } {
+                    let item := and(sload(add(self.slot, i)), _ADDRESS_MASK)
+                    mstore(add(ptr, mul(0x20, i)), item)
                 }
             }
         }
-        return output;
     }
 
-    /// @dev Array push back `account` operation on storage `self`.
-    function push(Data storage self, address account) internal returns (uint256) {
-        unchecked {
-            uint256 lengthAndFirst = self._raw[0];
-            uint256 len = lengthAndFirst >> 160;
-            if (len == 0) {
-                self._raw[0] = (1 << 160) + uint160(account);
-            } else {
-                self._raw[0] = lengthAndFirst + (1 << 160);
-                self._raw[len] = uint160(account);
+    /**
+     * @notice Adds an address to the end of the array.
+     * @param self The instance of the Data struct.
+     * @param account The address to add.
+     * @return res The new length of the array.
+     */
+    function push(Data storage self, address account) internal returns (uint256 res) {
+        assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
+            let lengthAndFirst := sload(self.slot)
+            let len := shr(_LENGTH_OFFSET, and(lengthAndFirst, _LENGTH_MASK))
+
+            switch len
+            case 0 {
+                sstore(self.slot, or(account, _ONE_LENGTH))
+            }
+            default {
+                sstore(self.slot, add(lengthAndFirst, _ONE_LENGTH))
+                sstore(add(self.slot, len), or(account, _ZERO_ADDRESS))
             }
-            return len + 1;
+            res := add(len, 1)
         }
     }
 
-    /// @dev Array pop back operation for storage `self`.
+    /**
+     * @notice Removes the last address from the array.
+     * @param self The instance of the Data struct.
+     */
     function pop(Data storage self) internal {
-        unchecked {
-            uint256 lengthAndFirst = self._raw[0];
-            uint256 len = lengthAndFirst >> 160;
-            if (len == 0) revert PopFromEmptyArray();
-            self._raw[len - 1] = 0;
-            if (len > 1) {
-                self._raw[0] = lengthAndFirst - (1 << 160);
+        bytes4 err = PopFromEmptyArray.selector;
+        assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
+            let lengthAndFirst := sload(self.slot)
+            let len := shr(_LENGTH_OFFSET, and(lengthAndFirst, _LENGTH_MASK))
+
+            switch len
+            case 0 {
+                mstore(0, err)
+                revert(0, 4)
+            }
+            case 1 {
+                sstore(self.slot, _ZERO_ADDRESS)
+            }
+            default {
+                sstore(self.slot, sub(lengthAndFirst, _ONE_LENGTH))
+            }
+        }
+    }
+
+    /**
+     * @notice Array pop back operation for storage `self` that returns popped element.
+     * @param self The instance of the Data struct.
+     * @return res The address that was removed from the array.
+     */
+    function popGet(Data storage self) internal returns(address res) {
+        bytes4 err = PopFromEmptyArray.selector;
+        assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
+            let lengthAndFirst := sload(self.slot)
+            let len := shr(_LENGTH_OFFSET, and(lengthAndFirst, _LENGTH_MASK))
+
+            switch len
+            case 0 {
+                mstore(0, err)
+                revert(0, 4)
+            }
+            case 1 {
+                res := and(lengthAndFirst, _ADDRESS_MASK)
+                sstore(self.slot, _ZERO_ADDRESS)
+            }
+            default {
+                res := and(sload(add(self.slot, sub(len, 1))), _ADDRESS_MASK)
+                sstore(self.slot, sub(lengthAndFirst, _ONE_LENGTH))
+            }
+        }
+    }
+
+    /**
+     * @notice Sets the address at a specified index in the array.
+     * @param self The instance of the Data struct.
+     * @param index The index at which to set the address.
+     * @param account The address to set at the specified index.
+     */
+    function set(Data storage self, uint256 index, address account) internal {
+        bytes4 err = IndexOutOfBounds.selector;
+        assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
+            let lengthAndFirst := sload(self.slot)
+            let len := shr(_LENGTH_OFFSET, and(lengthAndFirst, _LENGTH_MASK))
+            let fst := and(lengthAndFirst, _ADDRESS_MASK)
+
+            if iszero(lt(index, len)) {
+                mstore(0, err)
+                revert(0, 4)
+            }
+
+            switch index
+            case 0 {
+                sstore(self.slot, or(xor(lengthAndFirst, fst), account))
+            }
+            default {
+                sstore(add(self.slot, index), or(account, _ZERO_ADDRESS))
             }
         }
     }
 
-    /// @dev Set element for storage `self` at `index` to `account`.
-    function set(
-        Data storage self,
-        uint256 index,
-        address account
-    ) internal {
-        uint256 len = length(self);
-        if (index >= len) revert IndexOutOfBounds();
-
-        if (index == 0) {
-            self._raw[0] = (len << 160) | uint160(account);
-        } else {
-            self._raw[index] = uint160(account);
+    /**
+     * @notice Erase length of the array.
+     * @param self The instance of the Data struct.
+     */
+    function erase(Data storage self) internal {
+        assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
+            sstore(self.slot, _ADDRESS_MASK)
         }
     }
 }

package/contracts/libraries/AddressLib.sol

@@ -5,7 +5,8 @@ pragma solidity ^0.8.0;
 type Address is uint256;
 
 /**
-* @dev Library for working with addresses encoded as uint256 values, which can include flags in the highest bits.
+* @notice AddressLib
+* @notice Library for working with addresses encoded as uint256 values, which can include flags in the highest bits.
 */
 library AddressLib {
     uint256 private constant _LOW_160_BIT_MASK = (1 << 160) - 1;

package/contracts/libraries/AddressSet.sol

@@ -4,16 +4,18 @@ pragma solidity ^0.8.0;
 
 import "./AddressArray.sol";
 
-/** @title Library that is using AddressArray library for AddressArray.Data
- * and allows Set operations on address storage data:
- * 1. add
- * 2. remove
- * 3. contains
+/**
+ * @title AddressSet
+ * @notice Library for managing sets of addresses, allowing operations such as add, remove, and contains.
+ * Utilizes the AddressArray library for underlying data storage.
  */
 library AddressSet {
     using AddressArray for AddressArray.Data;
 
-    /** @dev Data struct from AddressArray.Data items
+    uint256 internal constant _NULL_INDEX = type(uint256).max;
+
+    /**
+     * @dev Data struct from AddressArray.Data items
      * and lookup mapping address => index in data array.
      */
     struct Data {
@@ -21,45 +23,107 @@ library AddressSet {
         mapping(address => uint256) lookup;
     }
 
-    /// @dev Length of data storage.
+    /**
+     * @notice Determines the number of addresses in the set.
+     * @param s The set of addresses.
+     * @return The number of addresses in the set.
+     */
     function length(Data storage s) internal view returns (uint256) {
         return s.items.length();
     }
 
-    /// @dev Returns data item from `s` storage at `index`.
+    /**
+     * @notice Retrieves the address at a specified index in the set.
+     * @param s The set of addresses.
+     * @param index The index of the address to retrieve.
+     * @return The address at the specified index.
+     */
     function at(Data storage s, uint256 index) internal view returns (address) {
         return s.items.at(index);
     }
 
-    /// @dev Returns true if storage `s` has `item`.
+    /**
+     * @notice Checks if the set contains the specified address.
+     * @param s The set of addresses.
+     * @param item The address to check for.
+     * @return True if the set contains the address, false otherwise.
+     */
     function contains(Data storage s, address item) internal view returns (bool) {
-        return s.lookup[item] != 0;
+        uint256 index = s.lookup[item];
+        return index != 0 && index != _NULL_INDEX;
+    }
+
+    /**
+     * @notice Returns list of addresses from storage `s`.
+     * @param s The set of addresses.
+     * @return The array of addresses stored in `s`.
+     */
+    function get(Data storage s) internal view returns (address[] memory) {
+        return s.items.get();
+    }
+
+    /**
+     * @notice Puts list of addresses from `s` storage into `output` array.
+     * @param s The set of addresses.
+     * @return The provided output array filled with addresses.
+     */
+    function get(Data storage s, address[] memory input) internal view returns (address[] memory) {
+        return s.items.get(input);
     }
 
-    /// @dev Adds `item` into storage `s` and returns true if successful.
+    /**
+     * @notice Adds an address to the set if it is not already present.
+     * @param s The set of addresses.
+     * @param item The address to add.
+     * @return True if the address was added to the set, false if it was already present.
+     */
     function add(Data storage s, address item) internal returns (bool) {
-        if (s.lookup[item] > 0) {
+        uint256 index = s.lookup[item];
+        if (index != 0 && index != _NULL_INDEX) {
             return false;
         }
         s.lookup[item] = s.items.push(item);
         return true;
     }
 
-    /// @dev Removes `item` from storage `s` and returns true if successful.
+    /**
+     * @notice Removes an address from the set if it exists.
+     * @param s The set of addresses.
+     * @param item The address to remove.
+     * @return True if the address was removed from the set, false if it was not found.
+     */
     function remove(Data storage s, address item) internal returns (bool) {
         uint256 index = s.lookup[item];
-        if (index == 0) {
+        s.lookup[item] = _NULL_INDEX;
+        if (index == 0 || index == _NULL_INDEX) {
             return false;
         }
-        if (index < s.items.length()) {
+
+        address lastItem = s.items.popGet();
+        if (lastItem != item) {
             unchecked {
-                address lastItem = s.items.at(s.items.length() - 1);
                 s.items.set(index - 1, lastItem);
                 s.lookup[lastItem] = index;
             }
         }
-        s.items.pop();
-        delete s.lookup[item];
         return true;
     }
+
+    /**
+     * @notice Erases set from storage `s`.
+     * @param s The set of addresses.
+     * @return items All removed items.
+     */
+    function erase(Data storage s) internal returns(address[] memory items) {
+        items = s.items.get();
+        uint256 len = items.length;
+        if (len > 0) {
+            s.items.erase();
+            unchecked {
+                for (uint256 i = 0; i < len; i++) {
+                    s.lookup[items[i]] = _NULL_INDEX;
+                }
+            }
+        }
+    }
 }

package/contracts/libraries/BySigTraits.sol

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+library BySigTraits {
+    error WrongNonceType();
+
+    // 2 bits for type
+    // 6 bits reserved for future use
+    // 40 bits for deadline
+    // 80 bits for relayer address lower bits
+    // 128 bits for nonce value
+    type Value is uint256;
+
+    enum NonceType {
+        Account,
+        Selector,
+        Unique
+    }
+
+    uint256 constant internal TYPE_BIT_SHIFT = 254;
+    uint256 constant internal DEADLINE_BIT_SHIFT = 208;
+    uint256 constant internal DEADLINE_BIT_MASK = (1 << 40) - 1;
+    uint256 constant internal RELAYER_BIT_SHIFT = 128;
+    uint256 constant internal RELAYER_BIT_MASK = (1 << 80) - 1;
+    uint256 constant internal NONCE_MASK = (1 << 128) - 1;
+
+    function nonceType(Value traits) internal pure returns(NonceType) {
+        uint256 _type = Value.unwrap(traits) >> TYPE_BIT_SHIFT;
+        if (_type > uint256(NonceType.Unique)) revert WrongNonceType();
+        return NonceType(_type);
+    }
+
+    function deadline(Value traits) internal pure returns(uint256) {
+        return (Value.unwrap(traits) >> DEADLINE_BIT_SHIFT) & DEADLINE_BIT_MASK;
+    }
+
+    function isRelayerAllowed(Value traits, address relayer) internal pure returns(bool) {
+        uint256 relayerBits = (Value.unwrap(traits) >> RELAYER_BIT_SHIFT) & RELAYER_BIT_MASK;
+        return relayerBits == 0 || (uint160(relayer) & RELAYER_BIT_MASK) == relayerBits;
+    }
+
+    function nonce(Value traits) internal pure returns(uint256) {
+        return Value.unwrap(traits) & NONCE_MASK;
+    }
+}

package/contracts/libraries/BytesMemory.sol

@@ -3,7 +3,8 @@
 pragma solidity ^0.8.0;
 
 /**
- * @title A library for operating on bytes memory slices without copying.
+ * @title BytesMemory
+ * @notice A library for operating on bytes memory slices without copying.
  */
 library BytesMemory {
     error OutOfBounds();

package/contracts/libraries/BytesStorage.sol

@@ -3,7 +3,8 @@
 pragma solidity ^0.8.0;
 
 /**
- * @title A library for operating on bytes storage slices.
+ * @title BytesStorage
+ * @notice A library for operating on bytes storage slices.
  */
 library BytesStorage {
     error OutOfBounds();