@1inch/solidity-utils 4.0.0 → 4.2.0

package/README.md

@@ -3,223 +3,24 @@
     <img src="https://github.com/1inch/solidity-utils/blob/master/.github/1inch_github_b.svg#gh-dark-mode-only">
 </div>
 
-# Utils library for contracts and tests
+# Utility Library for Smart Contracts and Testing
 
 [![Build Status](https://github.com/1inch/solidity-utils/workflows/CI/badge.svg)](https://github.com/1inch/solidity-utils/actions)
 [![Coverage Status](https://codecov.io/gh/1inch/solidity-utils/branch/master/graph/badge.svg?token=HJWBIVXQQA)](https://codecov.io/gh/1inch/solidity-utils)
 [![NPM Package](https://img.shields.io/npm/v/@1inch/solidity-utils.svg)](https://www.npmjs.org/package/@1inch/solidity-utils)
 
-### About
+This repository is a comprehensive toolkit designed to streamline and optimize the development, tests and management of smart contracts. This repository serves as a one-stop resource for developers working on Ethereum and EVM-compatible blockchain projects, offering a blend of Solidity contracts with various utilities and optimizations, alongside JavaScript tools for testing, documentation, and project management.
 
-This repository contains frequently used smart contracts, libraries and interfaces. Also it contains utils which are used in tests.
+## Features
 
-### Solidity
+- **[Development and Testing](https://github.com/1inch/solidity-utils/blob/master/docs/js/modules/src.md)**: The tools and utilities provided in this section are designed to aid in the development and testing of smart contracts. They help avoid the duplication of helper methods across different repositories by centralizing commonly used functions and scripts. This not only streamlines the development process but also ensures that the latest versions of these helpers are readily available and consistently used throughout your projects. Leveraging these utilities can significantly enhance efficiency and maintainability of your smart contract code.
 
-|directory|.sol|description|
-|--|--|--|
-|contracts|`EthReceiver`||
-|contracts|`Permitable`||
-|contracts|`GasChecker`||
-|contracts/interfaces|`IDaiLikePermit`|Interface of token which has `permit` method like DAI token|
-|contracts/interfaces|`IWETH`|WETH token interface|
-|contracts/libraries|`AddressArray`|library for work with array of addresses|
-|contracts/libraries|`AddressSet`|library for work with set of addresses|
-|contracts/libraries|`RevertReasonParser`|library parse the message from reverted method to readble format|
-|contracts/libraries|`StringUtil`|optimized methods to convert data to hex|
-|contracts/libraries|`UniERC20`||
+- **[Documentation and Utilities](https://github.com/1inch/solidity-utils/blob/master/utils/README.md)**: A suite of functionalities for generating documentation and additional utilities to enhance development workflow.
 
-### JS
+- **[Configuration and Management](https://github.com/1inch/solidity-utils/blob/master/docs/js/modules/hardhat_setup.md)**: Tools for setting up Hardhat network configurations and managing project settings efficiently.
 
-|module|function|descrption|
-|--|--|--|
-|asserts|`assertThrowsAsync(action, msg)`|checks the async function `action()` thrown with message `msg`|
-|asserts|`assertRoughlyEqualValues(expected, actual, relativeDiff)`|checks the `expected` value is equal to `actual` value with `relativeDiff` precision|
-|utils|`timeIncreaseTo(seconds)`|increases blockchain time to `seconds` sec|
-|utils|`trackReceivedToken(token, wallet, txPromise, ...args)`|returns amount of `token` which recieved the `wallet` in async method `txPromise` with arguments `args`|
-|utils|`trackReceivedTokenAndTx(token, wallet, txPromise, ...args)`|returns transaction info and amount of `token` which recieved the `wallet` in async method `txPromise` with arguments `args`|
-|utils|`fixSignature(signature)`|patchs ganache's signature to geth's version|
-|utils|`signMessage(signer, messageHex) `|signs `messageHex` with `signer` and patchs ganache's signature to geth's version|
-|utils|`countInstructions(txHash, instruction)`|counts amount of `instruction` in transaction with `txHash` hash|
-|utils|`deployAndGetContract(contractName, constructorArgs, deployments, deployer, deploymentName, skipVerify, skipIfAlreadyDeployed, gasPrice, maxPriorityFeePerGas, maxFeePerGas, log, waitConfirmations)`|deploys contract `contractName` as `deploymentName` if not `skipIfAlreadyDeployed` with `constructorArgs` from `deployer` using `hardhat-deploy` `deployments` with additional gas options `gasPrice`, `maxPriorityFeePerGas` and `maxFeePerGas` and outputs results to the console if `log`. Tries to verify it after `waitConfirmations` on Etherscan if not `skipVerify`.|
-|profileEVM|`profileEVM(txHash, instruction, optionalTraceFile)`|the same as the `countInstructions()` with option of writing all trace to `optionalTraceFile`|
-|profileEVM|`gasspectEVM(txHash, options, optionalTraceFile)`|returns all used operations in `txHash` transaction with `options` and their costs with option of writing all trace to `optionalTraceFile`|
+- **[Solidity Contracts and Libraries](https://github.com/1inch/solidity-utils/blob/master/docs/contracts/SUMMARY.md)**: Frequently used smart contracts, libraries, and interfaces aimed at providing reusable code for common use cases, alongside optimizations to improve contract efficiency.
 
-### UTILS
+## Contributing
 
-#### Docify
-
-Generates documentation in markdown format from natspec docs
-
-##### Usage
-Add to `package.json` file solidity compiler version and shortcut to run command
-
-`devDependencies` section
-
-```
-"solc": "0.8.12",
-```
-
-`scripts` section
-```
-"docify": "npx solidity-utils-docify"
-```
-
-You can set output directory with ENV variable:
-```
-"docify": "DOCGEN_OUTPUT_DIR=./docs npx solidity-utils-docify"
-```
-
-...
-
-#### Dependencies list (imports-list)
-
-Lists all imports recursively for the given solidity contract file. 
-
-##### Usage
-```
-npx imports-list -i <solidity file> [-a <alias list>]
-```
-
-Available parameters
-```
-Options:
-  -i, --input <input>     file to get dependencies for
-  -a, --alias [alias...]  projects alias list
-  -h, --help              display help for command
-```
-Aliases are used to provide source code for third-party projects. 
-For example, your contract uses imports from your other project and import is defined as
-```
-import "@1inch/otherproject/contracts/dependency.sol";
-```
-and you've got source code for `@1inch/otherproject` locally. Then you provide local path for the project to rip dependencies from `dependency.sol` as well.
-If there are several dependencies they should be provided using space as separator. 
-
-##### Example
-File imports
-```Solidity
-#rootFile.sol
-import '@1inch/otherproject/contracts/dependency.sol'
-
-#@1inch/otherproject/contracts/dependency.sol
-import 'helpers/helper.sol'
-```
-File and folder structure
-```
-rootFolder/
-
--- mainProject/
----- contracts/
------- rootFile.sol
-
--- dependencyProject/
----- helpers/
------- helper.sol
----- dependency.sol
-```
-Command
-```
-rootFolder/mainProject % npx imports-list -i './contracts/rootFile.sol' -a '@1inch/otherproject' '../dependencyProject'
-```
-Output
-```
-Project => root
-not set
-
-Project => @1inch/otherproject
-../otherproject/contracts/dependency.sol
-../otherproject/contracts/helpers/helper.sol
-```
-
-#### Test documentation generator (test-docgen)
-Script generates documentation for tests in markdown format.
-Give descriptions for `describe` and `it` sections and build documentation using these descriptions.
-
-##### Example
-Test described as shown below
-
-```JavaScript
-// Test suite
-describe('My feature', function() {
-    // Nested test suite
-    describe("My subfeature", function() {
-        /*
-            **Test case 1**
-            Test case should work
-         */
-        it("My case", function() {
-        // code here
-        })
-    })
-})
-```
-will generated the following output
-```Markdown
-
-# My feature
-
-Test suite
-
-## My subfeature
-
-Nested test suite
-
-### My case
-
-**Test case 1**
-Test case should work
-```
-
-##### Installation
-- Before use install documentation parser
-```
-yarn add acquit --dev
-```
-- Optionally configure script for default usage. Add to `script` section in `package.json`
-```
-"test:docs": "npx test-docgen"
-```
-- Optionally configure script for generating test list only. Add to `script` section in `package.json`
-```
-"test:docs": "npx test-docgen -l"
-```
-
-##### Usage
-If script configured
-```
-yarn test:docs
-```
-or
-```
-npx test-docgen
-```
-
-Available parameters
-```
-Options:
-  -i, --input <input>      tests directory (default: "test")
-  -x, --exclude [exclude]  exclude directories and files. omit argument to exclude all subdirectories (default: false)
-  -o, --output <output>    file to write output (default: "TESTS.md")
-  -c, --code               include code (default: false)
-  -l, --list               list tests only, do not include description (default: false)
-  -d, --debug              debug mode (default: false)
-  -h, --help               display help for command
-```
-##### Examples
-Generate docs with default input and output
-```
-npx test-docgen
-```
-
-Generate docs for files in folders `tests/mocks` and `tests/utils`
-```
-npx test-docgen -i "tests/mocks;tests/utils"
-```
-Exclude from docs file `test/mock-exclude.js` and `test/utils folder`
-```
-npx test-docgen -x "tests/mock-exclude.js;tests/utils"
-```
-Generate list of tests only
-```
-npx test-docgen -l
-```
+Contributions are welcome! If you have a suggestion that would make this repository better, or if you have any questions, please feel free to fork the repo and create a pull request. You can also simply open an issue with your suggestion or question.

package/contracts/interfaces/ICreate3Deployer.sol

@@ -2,7 +2,23 @@
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title ICreate3Deployer
+ * @dev Interface for deploying contracts with deterministic addresses via CREATE3.
+ */
 interface ICreate3Deployer {
+    /**
+     * @notice Deploys a contract using CREATE3 with a given salt and bytecode.
+     * @param salt Unique value to create deterministic address.
+     * @param code Contract bytecode to deploy.
+     * @return Address of the deployed contract.
+     */
     function deploy(bytes32 salt, bytes calldata code) external returns (address);
+
+    /**
+     * @notice Computes the address of a contract deployed with the given salt.
+     * @param salt Unique value used during deployment.
+     * @return Address of the contract.
+     */
     function addressOf(bytes32 salt) external view returns (address);
 }

package/contracts/interfaces/IDaiLikePermit.sol

@@ -2,7 +2,20 @@
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title IDaiLikePermit
+ * @dev Interface for Dai-like permit function allowing token spending via signatures.
+ */
 interface IDaiLikePermit {
+    /**
+     * @notice Approves spending of tokens via off-chain signatures.
+     * @param holder Token holder's address.
+     * @param spender Spender's address.
+     * @param nonce Current nonce of the holder.
+     * @param expiry Time when the permit expires.
+     * @param allowed True to allow, false to disallow spending.
+     * @param v, r, s Signature components.
+     */
     function permit(
         address holder,
         address spender,

package/contracts/interfaces/IERC20MetadataUppercase.sol

@@ -2,8 +2,20 @@
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title IERC20MetadataUppercase
+ * @dev Interface for ERC20 token metadata with uppercase naming convention.
+ */
 interface IERC20MetadataUppercase {
+    /**
+     * @notice Gets the token name.
+     * @return Token name.
+     */
     function NAME() external view returns (string memory); // solhint-disable-line func-name-mixedcase
 
+    /**
+     * @notice Gets the token symbol.
+     * @return Token symbol.
+     */
     function SYMBOL() external view returns (string memory); // solhint-disable-line func-name-mixedcase
 }

package/contracts/interfaces/IERC7597Permit.sol

@@ -2,7 +2,20 @@
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title IERC7597Permit
+ * @dev A new extension for ERC-2612 permit, which has already been added to USDC v2.2.
+ */
 interface IERC7597Permit {
+    /**
+     * @notice Update allowance with a signed permit.
+     * @dev Signature bytes can be used for both EOA wallets and contract wallets.
+     * @param owner Token owner's address (Authorizer).
+     * @param spender Spender's address.
+     * @param value Amount of allowance.
+     * @param deadline The time at which the signature expires (unixtime).
+     * @param signature Unstructured bytes signature signed by an EOA wallet or a contract wallet.
+     */
     function permit(
         address owner,
         address spender,

package/contracts/interfaces/IPermit2.sol

@@ -2,39 +2,72 @@
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title IPermit2
+ * @dev Interface for a flexible permit system that extends ERC20 tokens to support permits in tokens lacking native permit functionality.
+ */
 interface IPermit2 {
+    /**
+     * @dev Struct for holding permit details.
+     * @param token ERC20 token address for which the permit is issued.
+     * @param amount The maximum amount allowed to spend.
+     * @param expiration Timestamp until which the permit is valid.
+     * @param nonce An incrementing value for each signature, unique per owner, token, and spender.
+     */
     struct PermitDetails {
-        // ERC20 token address
         address token;
-        // the maximum amount allowed to spend
         uint160 amount;
-        // timestamp at which a spender's token allowances become invalid
         uint48 expiration;
-        // an incrementing value indexed per owner,token,and spender for each signature
         uint48 nonce;
     }
-    /// @notice The permit message signed for a single token allownce
+
+    /**
+     * @dev Struct for a single token allowance permit.
+     * @param details Permit details including token, amount, expiration, and nonce.
+     * @param spender Address authorized to spend the tokens.
+     * @param sigDeadline Deadline for the permit signature, ensuring timeliness of the permit.
+     */
     struct PermitSingle {
-        // the permit data for a single token alownce
         PermitDetails details;
-        // address permissioned on the allowed tokens
         address spender;
-        // deadline on the permit signature
         uint256 sigDeadline;
     }
-    /// @notice Packed allowance
+
+    /**
+     * @dev Struct for packed allowance data to optimize storage.
+     * @param amount Amount allowed.
+     * @param expiration Permission expiry timestamp.
+     * @param nonce Unique incrementing value for tracking allowances.
+     */
     struct PackedAllowance {
-        // amount allowed
         uint160 amount;
-        // permission expiry
         uint48 expiration;
-        // an incrementing value indexed per owner,token,and spender for each signature
         uint48 nonce;
     }
 
+    /**
+     * @notice Executes a token transfer from one address to another.
+     * @param user The token owner's address.
+     * @param spender The address authorized to spend the tokens.
+     * @param amount The amount of tokens to transfer.
+     * @param token The address of the token being transferred.
+     */
     function transferFrom(address user, address spender, uint160 amount, address token) external;
 
+    /**
+     * @notice Issues a permit for spending tokens via a signed authorization.
+     * @param owner The token owner's address.
+     * @param permitSingle Struct containing the permit details.
+     * @param signature The signature proving the owner authorized the permit.
+     */
     function permit(address owner, PermitSingle memory permitSingle, bytes calldata signature) external;
 
+    /**
+     * @notice Retrieves the allowance details between a token owner and spender.
+     * @param user The token owner's address.
+     * @param token The token address.
+     * @param spender The spender's address.
+     * @return The packed allowance details.
+     */
     function allowance(address user, address token, address spender) external view returns (PackedAllowance memory);
 }

package/contracts/interfaces/IWETH.sol

@@ -4,12 +4,29 @@ pragma solidity ^0.8.0;
 
 import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 
+/**
+ * @title IWETH
+ * @dev Interface for wrapper as WETH-like token.
+ */
 interface IWETH is IERC20 {
+    /**
+     * @notice Emitted when Ether is deposited to get wrapper tokens.
+     */
     event Deposit(address indexed dst, uint256 wad);
 
+    /**
+     * @notice Emitted when wrapper tokens is withdrawn as Ether.
+     */
     event Withdrawal(address indexed src, uint256 wad);
 
+    /**
+     * @notice Deposit Ether to get wrapper tokens.
+     */
     function deposit() external payable;
 
+    /**
+     * @notice Withdraw wrapped tokens as Ether.
+     * @param amount Amount of wrapped tokens to withdraw.
+     */
     function withdraw(uint256 amount) external;
 }

package/contracts/libraries/AddressArray.sol

@@ -2,10 +2,25 @@
 
 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();
 
     uint256 internal constant _ZERO_ADDRESS = 0x8000000000000000000000000000000000000000000000000000000000000000; // Next tx gas optimization
@@ -14,26 +29,40 @@ library AddressArray {
     uint256 internal constant _ONE_LENGTH   = 0x0000000000000000000000010000000000000000000000000000000000000000;
     uint256 internal constant _LENGTH_OFFSET = 160;
 
-    /// @dev Data struct containing raw mapping.
+    /**
+     * @dev Struct containing the raw mapping used to store the addresses and the array length.
+     */
     struct Data {
         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] & _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) {
         if (i >= 1 << 32) revert IndexOutOfBounds();
         return address(uint160(self._raw[i] & _ADDRESS_MASK));
     }
 
-    /// @dev Returns list of addresses from storage `self`.
+    /**
+     * @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) {
-        /// @solidity memory-safe-assembly
-        assembly { // solhint-disable-line no-inline-assembly
+        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)
@@ -55,12 +84,16 @@ library AddressArray {
         }
     }
 
-    /// @dev Puts list of addresses from `self` storage into `output` array.
+    /**
+     * @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;
-        /// @solidity memory-safe-assembly
-        assembly { // solhint-disable-line no-inline-assembly
+        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)
@@ -81,10 +114,14 @@ library AddressArray {
         }
     }
 
-    /// @dev Array push back `account` operation on storage `self`.
+    /**
+     * @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) {
-        /// @solidity memory-safe-assembly
-        assembly { // solhint-disable-line no-inline-assembly
+        assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
             let lengthAndFirst := sload(self.slot)
             let len := shr(_LENGTH_OFFSET, and(lengthAndFirst, _LENGTH_MASK))
 
@@ -100,11 +137,13 @@ library AddressArray {
         }
     }
 
-    /// @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 {
         bytes4 err = PopFromEmptyArray.selector;
-        /// @solidity memory-safe-assembly
-        assembly { // solhint-disable-line no-inline-assembly
+        assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
             let lengthAndFirst := sload(self.slot)
             let len := shr(_LENGTH_OFFSET, and(lengthAndFirst, _LENGTH_MASK))
 
@@ -122,11 +161,14 @@ library AddressArray {
         }
     }
 
-    /// @dev Array pop back operation for storage `self` that returns popped element.
+    /**
+     * @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;
-        /// @solidity memory-safe-assembly
-        assembly { // solhint-disable-line no-inline-assembly
+        assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
             let lengthAndFirst := sload(self.slot)
             let len := shr(_LENGTH_OFFSET, and(lengthAndFirst, _LENGTH_MASK))
 
@@ -146,11 +188,15 @@ library AddressArray {
         }
     }
 
-    /// @dev Set element for storage `self` at `index` to `account`.
+    /**
+     * @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;
-        /// @solidity memory-safe-assembly
-        assembly { // solhint-disable-line no-inline-assembly
+        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)
@@ -170,10 +216,12 @@ library AddressArray {
         }
     }
 
-    /// @dev Erase length of the array
+    /**
+     * @notice Erase length of the array.
+     * @param self The instance of the Data struct.
+     */
     function erase(Data storage self) internal {
-        /// @solidity memory-safe-assembly
-        assembly { // solhint-disable-line no-inline-assembly
+        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;