@1inch/solidity-utils 3.8.3 → 4.1.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

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+interface IERC7597Permit {
+    function permit(
+        address owner,
+        address spender,
+        uint256 value,
+        uint256 deadline,
+        bytes memory signature
+    ) external;
+}

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