From 763c51b79617f13366c7fe845752b65766770cb4 Mon Sep 17 00:00:00 2001 From: 0xneves Date: Fri, 15 Dec 2023 03:05:51 -0300 Subject: [PATCH] docs: review of the entire NatSpec - Fixed NatSpec problems - Manually edited some solidity-docgen output If the following issues get resolved, we'll be able to correctly run solidity-docgen. - [Uderscores are incorrectly placed](https://github.com/OpenZeppelin/solidity-docgen/issues/432) - [Structs are not documented](https://github.com/OpenZeppelin/solidity-docgen/issues/432) --- contracts/SwapFactory.sol | 4 +- contracts/Swaplace.sol | 11 +- contracts/interfaces/ISwapFactory.sol | 2 +- contracts/mock/ERC20/ERC20.sol | 7 +- docs/SwapFactory.md | 25 ++- docs/Swaplace.md | 26 +-- docs/echidna/TestSwapFactory.md | 34 ++++ docs/echidna/TestSwaplace.md | 34 ++++ docs/interfaces/IERC165.md | 9 +- docs/interfaces/IErrors.md | 11 +- docs/interfaces/ISwap.md | 22 ++- docs/interfaces/ISwapFactory.md | 13 +- docs/interfaces/ISwaplace.md | 43 +++-- docs/interfaces/ITransfer.md | 7 +- docs/mock/ERC20/ERC20.md | 205 +++++++++++++++++++++ docs/mock/ERC20/interfaces/IERC20.md | 154 ++++++++++++++++ docs/mock/ERC20/interfaces/IERC20Errors.md | 98 ++++++++++ docs/mock/ERC20/interfaces/IERC20Permit.md | 69 +++++++ 18 files changed, 686 insertions(+), 88 deletions(-) create mode 100644 docs/echidna/TestSwapFactory.md create mode 100644 docs/echidna/TestSwaplace.md create mode 100644 docs/mock/ERC20/ERC20.md create mode 100644 docs/mock/ERC20/interfaces/IERC20.md create mode 100644 docs/mock/ERC20/interfaces/IERC20Errors.md create mode 100644 docs/mock/ERC20/interfaces/IERC20Permit.md diff --git a/contracts/SwapFactory.sol b/contracts/SwapFactory.sol index 2eac3f7..e577888 100644 --- a/contracts/SwapFactory.sol +++ b/contracts/SwapFactory.sol @@ -6,7 +6,7 @@ import {ISwap} from "./interfaces/ISwap.sol"; import {ISwapFactory} from "./interfaces/ISwapFactory.sol"; /** - * @dev - SwapFactory is a helper for creating Swaps and making asset structs. + * @dev SwapFactory is a helper for creating Swaps and making asset structs. * * This helper can be used on and off-chain to easily create a Swap struct to be * used in the {Swaplace-createSwap} function. @@ -44,7 +44,7 @@ abstract contract SwapFactory is ISwapFactory, ISwap, IErrors { } /** - * @dev See {ISwapFactory-makeSwap}. + * @dev See {ISwapFactory-makeSwap}. */ function makeSwap( address owner, diff --git a/contracts/Swaplace.sol b/contracts/Swaplace.sol index 6132b50..ae5bc0c 100644 --- a/contracts/Swaplace.sol +++ b/contracts/Swaplace.sol @@ -6,15 +6,12 @@ import {ISwaplace} from "./interfaces/ISwaplace.sol"; import {ITransfer} from "./interfaces/ITransfer.sol"; import {SwapFactory} from "./SwapFactory.sol"; -/** ___ _ ___ ___ _ _____ _ _ _ - * | _ ) | / _ \ / __| |/ / __| | | | | - * | _ \ |_| (_) | (__| ' <| _|| |_| | |__ - * |___/____\___/ \___|_|\_\_| \___/|____| +/** * @author @0xneves | @blockful_io - * @dev - Swaplace is a Decentralized Feeless DEX. It has no owners, it cannot be stoped. - * Its core idea is to facilitate swaps between virtual assets following the ERC standard. + * @dev Swaplace is a Decentralized Feeless DEX. It has no owners, it cannot be stoped. + * Its cern is to facilitate swaps between virtual assets following the ERC standard. * Users can propose or accept swaps by allowing Swaplace to move their assets using the - * `approve` function of the Token standard or `permit` if available. + * `approve` function or `permit` if available. */ contract Swaplace is SwapFactory, ISwaplace, IERC165 { /// @dev Swap Identifier counter. diff --git a/contracts/interfaces/ISwapFactory.sol b/contracts/interfaces/ISwapFactory.sol index 0227026..51d1cf7 100644 --- a/contracts/interfaces/ISwapFactory.sol +++ b/contracts/interfaces/ISwapFactory.sol @@ -17,7 +17,7 @@ interface ISwapFactory { ) external pure returns (ISwap.Asset memory); /** - * @dev Build a swap struct to use in the {Swaplace-createSwap} function. + * @dev Build a swap struct to use in the {Swaplace-createSwap} function. * * Requirements: * diff --git a/contracts/mock/ERC20/ERC20.sol b/contracts/mock/ERC20/ERC20.sol index edb145a..0ca5b2e 100644 --- a/contracts/mock/ERC20/ERC20.sol +++ b/contracts/mock/ERC20/ERC20.sol @@ -19,7 +19,7 @@ abstract contract ERC20 is IERC20, IERC20Permit, IERC20Errors { ); /** - * @dev See {IERC20Permit-DOMAIN_SEPARATOR}. + * @dev See {IERC20Permit-DOMAIN_SEPARATOR}. */ bytes32 private immutable _domainSeparator; @@ -41,13 +41,12 @@ abstract contract ERC20 is IERC20, IERC20Permit, IERC20Errors { /** * @dev Map accounts to spender to the allowed transfereable value. */ - mapping(address => mapping(address => uint256)) - private _allowance; + mapping(address => mapping(address => uint256)) private _allowance; /** * @dev Map accounts to balance of Tokens. */ - mapping(address => uint256 ) private _balances; + mapping(address => uint256) private _balances; /** * @dev Map accounts to its current nonce. diff --git a/docs/SwapFactory.md b/docs/SwapFactory.md index a608b2c..b693a4c 100644 --- a/docs/SwapFactory.md +++ b/docs/SwapFactory.md @@ -2,7 +2,7 @@ ## SwapFactory -_- SwapFactory is a helper for creating Swaps and making asset structs. +SwapFactory is a helper for creating Swaps and making asset structs. This helper can be used on and off-chain to easily create a Swap struct to be used in the {Swaplace-createSwap} function. @@ -10,23 +10,23 @@ used in the {Swaplace-createSwap} function. Swaplace uses a {ISwap-Swap} struct to represent a Swap. This struct is composed of: -- The `owner` of the Swap is the address that created the Swap. -- The `allowed` address is the address that can accept the Swap. If the allowed - address is the zero address, then anyone can accept the Swap. -- The `expiry` date is the timestamp that the Swap will be available to accept. -- The `biding` are the assets that the owner is offering. -- The `asking` are the assets that the owner wants in exchange. +- The `owner` of the Swap is the address that created the Swap. +- The `allowed` address is the address that can accept the Swap. If the allowed + address is the zero address, then anyone can accept the Swap. +- The `expiry` date is the timestamp that the Swap will be available to accept. +- The `biding` are the assets that the owner is offering. +- The `asking` are the assets that the owner wants in exchange. The Swap struct uses an {Asset} struct to represent the asset. This struct is composed of: -- The `address` of the asset. This address can be from an ERC20 or ERC721 contract. -- The `amount` or `id` of the asset. This amount can be the amount of ERC20 tokens - or the id of an ERC721 token. +- The `address` of the asset. This address can be from an ERC20 or ERC721 contract. +- The `amount` or `id` of the asset. This amount can be the amount of ERC20 tokens + or the id of an ERC721 token. To use other standards, like ERC1155, you can wrap the ownership of the asset in an a trusted contract and Swap as an ERC721. This way, you can tokenize any -on-chain execution and trade on Swaplace._ +on-chain execution and trade on Swaplace. ### makeAsset @@ -42,5 +42,4 @@ _See {ISwapFactory-makeAsset}._ function makeSwap(address owner, address allowed, uint256 expiry, struct ISwap.Asset[] biding, struct ISwap.Asset[] asking) public view virtual returns (struct ISwap.Swap) ``` -@dev See {ISwapFactory-makeSwap}. - +_See {ISwapFactory-makeSwap}._ diff --git a/docs/Swaplace.md b/docs/Swaplace.md index e8119cb..eae345e 100644 --- a/docs/Swaplace.md +++ b/docs/Swaplace.md @@ -2,23 +2,10 @@ ## Swaplace -___ _ ___ ___ _ _____ _ _ _ - | _ ) | / _ \ / __| |/ / __| | | | | - | _ \ |_| (_) | (__| ' <| _|| |_| | |__ - |___/____\___/ \___|_|\_\_| \___/|____| - -_- Swaplace is a Decentralized Feeless DEX. It has no owners, it cannot be stoped. -Its core idea is to facilitate swaps between virtual assets following the ERC standard. +Swaplace is a Decentralized Feeless DEX. It has no owners, it cannot be stoped. +Its cern is to facilitate swaps between virtual assets following the ERC standard. Users can propose or accept swaps by allowing Swaplace to move their assets using the -`approve` function of the Token standard or `permit` if available._ - -### swapId - -```solidity -uint256 swapId -``` - -_Swap Identifier counter._ +`approve` function or `permit` if available. ### createSwap @@ -60,3 +47,10 @@ function supportsInterface(bytes4 interfaceID) external pure returns (bool) _See {IERC165-supportsInterface}._ +### totalSwaps + +```solidity +function totalSwaps() public view returns (uint256) +``` + +_Getter function for \_totalSwaps._ diff --git a/docs/echidna/TestSwapFactory.md b/docs/echidna/TestSwapFactory.md new file mode 100644 index 0000000..19a47e6 --- /dev/null +++ b/docs/echidna/TestSwapFactory.md @@ -0,0 +1,34 @@ +# Solidity API + +## TestFactory + +### has_values + +```solidity +function has_values() public +``` + +### make_asset_array + +```solidity +function make_asset_array(address addr, uint256 amountOrId) public pure returns (struct ISwap.Asset[]) +``` + +### make_valid_swap + +```solidity +function make_valid_swap(address owner, address addr, uint256 amountOrId) public view returns (struct ISwap.Swap) +``` + +### echidna_revert_invalid_expiry + +```solidity +function echidna_revert_invalid_expiry() public view +``` + +### echidna_revert_invalid_length + +```solidity +function echidna_revert_invalid_length() public view +``` + diff --git a/docs/echidna/TestSwaplace.md b/docs/echidna/TestSwaplace.md new file mode 100644 index 0000000..322734e --- /dev/null +++ b/docs/echidna/TestSwaplace.md @@ -0,0 +1,34 @@ +# Solidity API + +## TestSwaplace + +### constructor + +```solidity +constructor() public +``` + +### echidna_create_swap + +```solidity +function echidna_create_swap() public returns (bool) +``` + +### echidna_accept_swap + +```solidity +function echidna_accept_swap() public returns (bool) +``` + +### echidna_id_overflow + +```solidity +function echidna_id_overflow() public view returns (bool) +``` + +### echidna_id_never_zero_after_init + +```solidity +function echidna_id_never_zero_after_init() public view returns (bool) +``` + diff --git a/docs/interfaces/IERC165.md b/docs/interfaces/IERC165.md index eb67eeb..b251fdd 100644 --- a/docs/interfaces/IERC165.md +++ b/docs/interfaces/IERC165.md @@ -2,13 +2,13 @@ ## IERC165 -_Interface of the ERC165 standard, as defined in the +Interface of the ERC165 standard, as defined in the https://eips.ethereum.org/EIPS/eip-165[EIP]. Implementers can declare support of contract interfaces, which can then be queried by others ({ERC165Checker}). -For an implementation, see {ERC165}._ +For an implementation, see {ERC165}. ### supportsInterface @@ -16,10 +16,9 @@ For an implementation, see {ERC165}._ function supportsInterface(bytes4 interfaceId) external view returns (bool) ``` -_Returns true if this contract implements the interface defined by +Returns true if this contract implements the interface defined by `interfaceId`. See the corresponding https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section] to learn more about how these ids are created. -This function call must use less than 30 000 gas._ - +This function call must use less than 30 000 gas. diff --git a/docs/interfaces/IErrors.md b/docs/interfaces/IErrors.md index b30555a..23ee2bb 100644 --- a/docs/interfaces/IErrors.md +++ b/docs/interfaces/IErrors.md @@ -2,7 +2,7 @@ ## IErrors -_Errors only interface for the {Swaplace} implementations._ +Errors only interface for the {Swaplace} implementations. ### InvalidAddress @@ -10,7 +10,7 @@ _Errors only interface for the {Swaplace} implementations._ error InvalidAddress(address caller) ``` -_Displayed when the caller is not the owner of the swap._ +Displayed when the caller is not the owner of the swap. ### InvalidAssetsLength @@ -18,12 +18,12 @@ _Displayed when the caller is not the owner of the swap._ error InvalidAssetsLength() ``` -_Displayed when the amount of {ISwap-Asset} has a length of zero. +Displayed when the amount of {ISwap-Asset} has a length of zero. NOTE: The `biding` or `asking` array must not be empty to avoid mistakes when creating a swap. Assuming one side of the swap is empty, the correct approach should be the usage of {transferFrom} and we reinforce -this behavior by requiring the length of the array to be bigger than zero._ +this behavior by requiring the length of the array to be bigger than zero. ### InvalidExpiry @@ -31,5 +31,4 @@ this behavior by requiring the length of the array to be bigger than zero._ error InvalidExpiry(uint256 timestamp) ``` -_Displayed when the `expiry` date is in the past._ - +Displayed when the `expiry` date is in the past. diff --git a/docs/interfaces/ISwap.md b/docs/interfaces/ISwap.md index 618632a..a3096c0 100644 --- a/docs/interfaces/ISwap.md +++ b/docs/interfaces/ISwap.md @@ -2,7 +2,7 @@ ## ISwap -_Interface for the Swap Struct, used in the {Swaplace} implementation._ +Interface for the Swap Struct, used in the {Swaplace} implementation. ### Asset @@ -13,6 +13,15 @@ struct Asset { } ``` +Assets can be ERC20 or ERC721. + +It is composed of: + +- `addr` of the asset. +- `amountOrId` of the asset based on the standard. + +NOTE: `amountOrId` is the `amount` of ERC20 or the `tokenId` of ERC721. + ### Swap ```solidity @@ -25,3 +34,14 @@ struct Swap { } ``` +The Swap struct is the heart of Swaplace. + +It is composed of: + +- `owner` of the Swap. +- `allowed` address to accept the Swap. +- `expiry` date of the Swap. +- `biding` assets that are being bided by the owner. +- `asking` assets that are being asked by the owner. + +NOTE: When `allowed` address is the zero address, anyone can accept the Swap. diff --git a/docs/interfaces/ISwapFactory.md b/docs/interfaces/ISwapFactory.md index 63befc0..fd004ed 100644 --- a/docs/interfaces/ISwapFactory.md +++ b/docs/interfaces/ISwapFactory.md @@ -2,7 +2,7 @@ ## ISwapFactory -_Interface of the {SwapFactory} implementation._ +Interface of the {SwapFactory} implementation. ### makeAsset @@ -10,8 +10,8 @@ _Interface of the {SwapFactory} implementation._ function makeAsset(address addr, uint256 amountOrId) external pure returns (struct ISwap.Asset) ``` -_Constructs an asset struct that works for ERC20 or ERC721. -This function is a utility to easily create an `Asset` struct on-chain or off-chain._ +Constructs an asset struct that works for ERC20 or ERC721. +This function is a utility to easily create an `Asset` struct on-chain or off-chain. ### makeSwap @@ -19,10 +19,9 @@ This function is a utility to easily create an `Asset` struct on-chain or off-ch function makeSwap(address owner, address allowed, uint256 expiry, struct ISwap.Asset[] assets, struct ISwap.Asset[] asking) external view returns (struct ISwap.Swap) ``` -@dev Build a swap struct to use in the {Swaplace-createSwap} function. +Build a swap struct to use in the {Swaplace-createSwap} function. Requirements: -- `expiry` cannot be in the past timestamp. -- `biding` and `asking` cannot be empty. - +- `expiry` cannot be in the past timestamp. +- `biding` and `asking` cannot be empty. diff --git a/docs/interfaces/ISwaplace.md b/docs/interfaces/ISwaplace.md index 133a7fb..c9fc51f 100644 --- a/docs/interfaces/ISwaplace.md +++ b/docs/interfaces/ISwaplace.md @@ -2,7 +2,7 @@ ## ISwaplace -_Interface of the {Swaplace} implementation._ +Interface of the {Swaplace} implementation. ### SwapCreated @@ -10,7 +10,7 @@ _Interface of the {Swaplace} implementation._ event SwapCreated(uint256 id, address owner, uint256 expiry) ``` -_Emitted when a new Swap is created._ +Emitted when a new Swap is created. ### SwapAccepted @@ -18,7 +18,7 @@ _Emitted when a new Swap is created._ event SwapAccepted(uint256 id, address acceptee) ``` -_Emitted when a Swap is accepted._ +Emitted when a Swap is accepted. ### SwapCanceled @@ -26,7 +26,7 @@ _Emitted when a Swap is accepted._ event SwapCanceled(uint256 id, address owner) ``` -_Emitted when a Swap is canceled._ +Emitted when a Swap is canceled. ### createSwap @@ -34,15 +34,15 @@ _Emitted when a Swap is canceled._ function createSwap(struct ISwap.Swap Swap) external returns (uint256) ``` -_Allow users to create a Swap. Each new Swap self-increments its id by one. +Allow users to create a Swap. Each new Swap self-increments its id by one. Requirements: -- `owner` must be the caller address. -- `expiry` should be bigger than timestamp. -- `biding` and `asking` must not be empty. +- `owner` must be the caller address. +- `expiry` should be bigger than timestamp. +- `biding` and `asking` must not be empty. -Emits a {SwapCreated} event._ +Emits a {SwapCreated} event. ### acceptSwap @@ -50,20 +50,20 @@ Emits a {SwapCreated} event._ function acceptSwap(uint256 id) external returns (bool) ``` -_Accepts a Swap. Once the Swap is accepted, the expiry is set +Accepts a Swap. Once the Swap is accepted, the expiry is set to zero to avoid reutilization. Requirements: -- `allowed` must be the zero address or match the caller address. -- `expiry` must be bigger than timestamp. -- `biding` assets must be allowed to transfer. -- `asking` assets must be allowed to transfer. +- `allowed` must be the zero address or match the caller address. +- `expiry` must be bigger than timestamp. +- `biding` assets must be allowed to transfer. +- `asking` assets must be allowed to transfer. Emits a {SwapAccepted} event. NOTE: The expiry is set to 0, because if the Swap is expired it -will revert, preventing reentrancy attacks._ +will revert, preventing reentrancy attacks. ### cancelSwap @@ -71,17 +71,17 @@ will revert, preventing reentrancy attacks._ function cancelSwap(uint256 id) external ``` -_Cancels an active Swap by setting the expiry to zero. +Cancels an active Swap by setting the expiry to zero. Expiry with 0 seconds means that the Swap doesn't exist or is already canceled. Requirements: -- `owner` must be the caller adress. -- `expiry` must be bigger than timestamp. +- `owner` must be the caller adress. +- `expiry` must be bigger than timestamp. -Emits a {SwapCanceled} event._ +Emits a {SwapCanceled} event. ### getSwap @@ -89,9 +89,8 @@ Emits a {SwapCanceled} event._ function getSwap(uint256 id) external view returns (struct ISwap.Swap) ``` -_Retrieves the details of a Swap based on the `swapId` provided. +Retrieves the details of a Swap based on the `swapId` provided. NOTE: If the Swaps doesn't exist, the values will be defaulted to 0. You can check if a Swap exists by checking if the `owner` is the zero address. -If the `owner` is the zero address, then the Swap doesn't exist._ - +If the `owner` is the zero address, then the Swap doesn't exist. diff --git a/docs/interfaces/ITransfer.md b/docs/interfaces/ITransfer.md index b9e50de..f035078 100644 --- a/docs/interfaces/ITransfer.md +++ b/docs/interfaces/ITransfer.md @@ -2,7 +2,7 @@ ## ITransfer -_Generalized Interface for {IERC20} and {IERC721} `transferFrom` functions._ +Generalized Interface for {IERC20} and {IERC721} `transferFrom` functions. ### transferFrom @@ -10,9 +10,8 @@ _Generalized Interface for {IERC20} and {IERC721} `transferFrom` functions._ function transferFrom(address from, address to, uint256 amountOrId) external ``` -_See {IERC20-transferFrom} or {IERC721-transferFrom}. +_See {IERC20-transferFrom} or {IERC721-transferFrom}._ Moves an `amount` for ERC20 or `tokenId` for ERC721 from `from` to `to`. -Emits a {Transfer} event._ - +Emits a {Transfer} event. diff --git a/docs/mock/ERC20/ERC20.md b/docs/mock/ERC20/ERC20.md new file mode 100644 index 0000000..1075c96 --- /dev/null +++ b/docs/mock/ERC20/ERC20.md @@ -0,0 +1,205 @@ +# Solidity API + +## ERC20 + +_Lightweight ERC20 with Permit extension._ + +### constructor + +```solidity +constructor(string name_, string symbol_) internal +``` + +_Sets the values for {name} and {symbol}._ + +### name + +```solidity +function name() public view virtual returns (string) +``` + +_Returns the name of the token._ + +### symbol + +```solidity +function symbol() public view virtual returns (string) +``` + +_Returns the symbol of the token, usually a shorter version of the +name._ + +### decimals + +```solidity +function decimals() public view virtual returns (uint8) +``` + +_Returns the number of decimals used to get its user representation. +For example, if `decimals` equals `2`, a balance of `505` tokens should +be displayed to a user as `5.05` (`505 / 10 ** 2`). + +Tokens usually opt for a value of 18, imitating the relationship between +Ether and Wei. This is the default value returned by this function, unless +it's overridden. + +NOTE: This information is only used for _display_ purposes: it in +no way affects any of the arithmetic of the contract, including +{IERC20-balanceOf} and {IERC20-transfer}._ + +### totalSupply + +```solidity +function totalSupply() public view virtual returns (uint256) +``` + +_See {IERC20-totalSupply}._ + +### balanceOf + +```solidity +function balanceOf(address account) public view virtual returns (uint256) +``` + +_See {IERC20-balanceOf}._ + +### allowance + +```solidity +function allowance(address owner, address spender) public view virtual returns (uint256) +``` + +_See {IERC20-allowance}._ + +### nonces + +```solidity +function nonces(address owner) public view virtual returns (uint256) +``` + +_Returns the current nonce of an address._ + +### DOMAIN_SEPARATOR + +```solidity +function DOMAIN_SEPARATOR() public view virtual returns (bytes32) +``` + +_See {IERC20Permit-DOMAIN_SEPARATOR}._ + +### approve + +```solidity +function approve(address spender, uint256 value) public virtual returns (bool) +``` + +_See {IERC20-approve}. + +NOTE: If `value` is the maximum `uint256`, the allowance is not updated on +`transferFrom`. This is semantically equivalent to an infinite approval._ + +### increaseAllowance + +```solidity +function increaseAllowance(address spender, uint256 addedValue) public virtual returns (bool) +``` + +_See {IERC20-increaseAllowance}._ + +### decreaseAllowance + +```solidity +function decreaseAllowance(address spender, uint256 requestedDecrease) public virtual returns (bool) +``` + +_See {IERC20-decreaseAllowance}. + +Requirements: + +- `spender` must have allowance for the caller of at least +`requestedDecrease`._ + +### permit + +```solidity +function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) public virtual returns (bool) +``` + +_See {IERC20Permit-permit}. + +Requirements: + +- `spender` cannot be the zero address. +- `deadline` must be a timestamp in the future. +- `v`, `r` and `s` must be a valid `secp256k1` signature from `owner` +over the EIP712-formatted function arguments. +- the signature must use ``owner``'s current nonce (see {IERC20Permit-nonces})._ + +### _mint + +```solidity +function _mint(address to, uint256 value) internal +``` + +_Creates an `value` of tokens and assigns them to `to` by creating supply. + +Emits a {Transfer} event with `from` set to the zero address._ + +### _burn + +```solidity +function _burn(address from, uint256 value) internal +``` + +_Destroys an `value` of tokens from `from` by lowering the total supply. + +Requirements: + +- `from` must have a balance of at least `value`. + +Emits a {Transfer} event with `to` set to the zero address._ + +### transfer + +```solidity +function transfer(address to, uint256 value) public virtual returns (bool) +``` + +_See {IERC20-transfer}. + +Requirements: + +- the caller must have a balance of at least `value`._ + +### transferFrom + +```solidity +function transferFrom(address from, address to, uint256 value) public virtual returns (bool) +``` + +_See {IERC20-transferFrom}. + +Requirements: + +- `from` must have a balance of at least `value`. +- the caller must have allowance for `from`'s tokens of at least +`value`. + +NOTE: Does not update the allowance if the current allowance +is the maximum `uint256`._ + +### permitTransfer + +```solidity +function permitTransfer(address from, address to, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) public virtual returns (bool) +``` + +_See {IERC20Permit-permitTransfer}. + +Requirements: + +- `deadline` must be a timestamp in the future. +- `v`, `r` and `s` must be a valid `secp256k1` signature from `from` +over the EIP712-formatted function arguments. +- the signature must use `from`'s current nonce (see {IERC20Permit-nonces})._ + diff --git a/docs/mock/ERC20/interfaces/IERC20.md b/docs/mock/ERC20/interfaces/IERC20.md new file mode 100644 index 0000000..d5bf51b --- /dev/null +++ b/docs/mock/ERC20/interfaces/IERC20.md @@ -0,0 +1,154 @@ +# Solidity API + +## IERC20 + +_Interface of the ERC20 standard as defined in the EIP._ + +### Approval + +```solidity +event Approval(address owner, address spender, uint256 value) +``` + +_Emitted when the allowance of a `spender` for an `owner` is set by +a call to {approve}. `value` is the new allowance._ + +### Transfer + +```solidity +event Transfer(address from, address to, uint256 value) +``` + +_Emitted when `value` tokens are moved from `from` to `to`. + +NOTE: `value` can be zero._ + +### name + +```solidity +function name() external view returns (string) +``` + +_Returns the name of the token._ + +### symbol + +```solidity +function symbol() external view returns (string) +``` + +_Returns the symbol of the token._ + +### decimals + +```solidity +function decimals() external view returns (uint8) +``` + +_Returns the decimals places of the token._ + +### totalSupply + +```solidity +function totalSupply() external view returns (uint256) +``` + +_Returns the value of tokens in existence._ + +### balanceOf + +```solidity +function balanceOf(address account) external view returns (uint256) +``` + +_Returns the value of tokens owned by `account`._ + +### allowance + +```solidity +function allowance(address owner, address spender) external view returns (uint256) +``` + +_Returns the remaining number of tokens that `spender` will be +allowed to spend on behalf of `owner` through {transferFrom}. This is +zero by default. + +This value changes when {approve} or {transferFrom} are called. + +NOTE: If `value` is the maximum `uint256`, the allowance is not updated on +`transferFrom`. This is semantically equivalent to an infinite approval._ + +### approve + +```solidity +function approve(address spender, uint256 value) external returns (bool) +``` + +_Sets a `value` amount of tokens as the allowance of `spender` over the +caller's tokens. + +Returns a boolean value indicating whether the operation succeeded. + +IMPORTANT: Beware that changing an allowance with this method brings the risk +that someone may use both the old and the new allowance by unfortunate +transaction ordering. One possible solution to mitigate this race +condition is to first reduce the spender's allowance to 0 and set the +desired value afterwards: +https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729 + +Emits an {Approval} event._ + +### increaseAllowance + +```solidity +function increaseAllowance(address spender, uint256 addedValue) external returns (bool) +``` + +_Atomically increases the allowance granted to `spender` by the caller. + +This is an alternative to {approve} that can be used as a mitigation for +problems described in {IERC20-approve}. + +Emits an {IERC20-Approval} event indicating the updated allowance._ + +### decreaseAllowance + +```solidity +function decreaseAllowance(address spender, uint256 requestedDecrease) external returns (bool) +``` + +_Atomically decreases the allowance granted to `spender` by the caller. + +This is an alternative to {approve} that can be used as a mitigation for +problems described in {IERC20-approve}. + +Emits an {Approval} event indicating the updated allowance. + +NOTE: Although this function is designed to avoid double spending with {approval}, +it can still be frontrunned, preventing any attempt of allowance reduction._ + +### transfer + +```solidity +function transfer(address to, uint256 value) external returns (bool) +``` + +_Moves a `value` amount of tokens from the caller's account to `to`. +Returns a boolean value indicating whether the operation succeeded. + +Emits a {Transfer} event._ + +### transferFrom + +```solidity +function transferFrom(address from, address to, uint256 value) external returns (bool) +``` + +_Moves a `value` amount of tokens from `from` to `to` using the +allowance mechanism. `value` is then deducted from the caller's +allowance. + +Returns a boolean value indicating whether the operation succeeded. + +Emits a {Transfer} event._ + diff --git a/docs/mock/ERC20/interfaces/IERC20Errors.md b/docs/mock/ERC20/interfaces/IERC20Errors.md new file mode 100644 index 0000000..b0f5ae6 --- /dev/null +++ b/docs/mock/ERC20/interfaces/IERC20Errors.md @@ -0,0 +1,98 @@ +# Solidity API + +## IERC20Errors + +_Standard ERC20 Errors_ + +### ERC20InsufficientBalance + +```solidity +error ERC20InsufficientBalance(address sender, uint256 balance, uint256 needed) +``` + +_Indicates an error related to the current `balance` of a `sender`. Used in transfers._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| sender | address | Address whose tokens are being transferred. | +| balance | uint256 | Current balance for the interacting account. | +| needed | uint256 | Minimum amount required to perform a transfer. | + +### ERC20InsufficientAllowance + +```solidity +error ERC20InsufficientAllowance(address spender, uint256 allowance, uint256 needed) +``` + +_Indicates a failure with the `spender`’s `allowance`. Used in transfers._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| spender | address | Address that may be allowed to operate on tokens without being their owner. | +| allowance | uint256 | Amount of tokens a `spender` is allowed to operate with. | +| needed | uint256 | Minimum amount required to perform a transfer. | + +### ERC20FailedDecreaseAllowance + +```solidity +error ERC20FailedDecreaseAllowance(address spender, uint256 allowance, uint256 needed) +``` + +_Indicates a failed `decreaseAllowance` request._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| spender | address | Address that may be allowed to operate on tokens without being their owner. | +| allowance | uint256 | Amount of tokens a `spender` want to operate with. | +| needed | uint256 | Amount required to decrease the allowance. | + +### ERC20PermitInvalidNonce + +```solidity +error ERC20PermitInvalidNonce(address account, uint256 nonce) +``` + +_Indicates the nonce used for an `account` is not the expected current nonce._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| account | address | Address whose nonce is being checked. | +| nonce | uint256 | Expected nonce for the given `account`. | + +### ERC2612ExpiredSignature + +```solidity +error ERC2612ExpiredSignature(uint256 deadline) +``` + +_Indicates the expiration of a permit to be used._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| deadline | uint256 | Expiration time limit in seconds. | + +### ERC2612InvalidSigner + +```solidity +error ERC2612InvalidSigner(address signer, address owner) +``` + +_Indicates the mismatched owner when validating the signature._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| signer | address | Address of the signer recovered. | +| owner | address | Address of the owner expected to match `signer`. | + diff --git a/docs/mock/ERC20/interfaces/IERC20Permit.md b/docs/mock/ERC20/interfaces/IERC20Permit.md new file mode 100644 index 0000000..bf13c88 --- /dev/null +++ b/docs/mock/ERC20/interfaces/IERC20Permit.md @@ -0,0 +1,69 @@ +# Solidity API + +## IERC20Permit + +_Interface of the ERC20 Permit extension allowing approvals to be made via signatures, as defined in +https://eips.ethereum.org/EIPS/eip-2612[EIP-2612]. + +Adds the {permit} method, which can be used to change an account's ERC20 allowance (see {IERC20-allowance}) by +presenting a message signed by the account. By not relying on {IERC20-approve}, the token holder account doesn't +need to send a transaction, and thus is not required to hold Ether at all._ + +### nonces + +```solidity +function nonces(address owner) external view returns (uint256) +``` + +_Returns the current nonce for `owner`. This value must be +included whenever a signature is generated for {permit}. + +Every successful call to {permit} increases `owner`'s nonce by one. +This prevents a signature from being used multiple times._ + +### DOMAIN_SEPARATOR + +```solidity +function DOMAIN_SEPARATOR() external view returns (bytes32) +``` + +_Returns the domain separator used in the encoding of the signature for {permit}, as defined by {EIP712}._ + +### permit + +```solidity +function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external returns (bool) +``` + +_Sets `value` as the allowance of `spender` over `owner`'s tokens, +given `owner`'s signed approval. + +IMPORTANT: The same issues {IERC20-approve} has related to transaction +ordering also apply here. + +Emits an {IERC20-Approval} event. + +NOTE: `spender` can be the zero address. Checking this on-chain is a bad +usage of gas. For more information on the signature format, see the +https://eips.ethereum.org/EIPS/eip-2612#specification[relevant EIPsection]._ + +### permitTransfer + +```solidity +function permitTransfer(address from, address to, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external returns (bool) +``` + +_Allows {IERC20-transferFrom} to be used with the `owner`'s signature. +Similar to permit but changing the scope to handle the balance instead of +allowance. + +Requires less gas than regular {permit} and {IERC20-transferFrom}. + +IMPORTANT: `owner` works as `from` and `spender` as `to` (see {IERC20Permit-permit}). + +Emits an {IERC20-Transfer} event. + +NOTE: Realize that {PERMIT_TYPEHASH} is different from the one in {permit}. +This is because the arguments name differ. But won't result in a different +output as long as it is encoded following the EIP712 and ERC20Permit specs._ +