diff --git a/.solhint.json b/.solhint.json index 8df942a10..928e7ae96 100644 --- a/.solhint.json +++ b/.solhint.json @@ -2,7 +2,7 @@ "extends": "default", "rules": { "indent": ["error", 4], - + "func-order": false, "bracket-align": false, "compiler-fixed": false, "no-simple-event-func-name": false, diff --git a/contracts/token/ERC20/ERC20.sol b/contracts/token/ERC20/ERC20.sol index 30039d274..b59c66279 100644 --- a/contracts/token/ERC20/ERC20.sol +++ b/contracts/token/ERC20/ERC20.sol @@ -4,16 +4,27 @@ import "./IERC20.sol"; import "../../math/SafeMath.sol"; /** - * @title Standard ERC20 token + * @dev Implementation of the `IERC20` interface. * - * @dev Implementation of the basic standard token. - * https://eips.ethereum.org/EIPS/eip-20 - * Originally based on code by FirstBlood: - * https://github.com/Firstbloodio/token/blob/master/smart_contract/FirstBloodToken.sol + * This implementation is agnostic to the way tokens are created. This means + * that a supply mechanism has to be added in a derived contract using `_mint`. + * For a generic mechanism see `ERC20Mintable`. * - * This implementation emits additional Approval events, allowing applications to reconstruct the allowance status for - * all accounts just by listening to said events. Note that this isn't required by the specification, and other - * compliant implementations may not do it. + * *For a detailed writeup see our guide [How to implement supply + * mechanisms](https://forum.zeppelin.solutions/t/how-to-implement-erc20-supply-mechanisms/226).* + * + * We have followed general OpenZeppelin guidelines: functions revert instead + * of returning `false` on failure. This behavior is nonetheless conventional + * and does not conflict with the expectations of ERC20 applications. + * + * Additionally, an `Approval` event is emitted on calls to `transferFrom`. + * This allows applications to reconstruct the allowance for all accounts just + * by listening to said events. Other implementations of the EIP may not emit + * these events, as it isn't required by the specification. + * + * Finally, the non-standard `decreaseAllowance` and `increaseAllowance` + * functions have been added to mitigate the well-known issues around setting + * allowances. See `IERC20.approve`. */ contract ERC20 is IERC20 { using SafeMath for uint256; @@ -25,21 +36,40 @@ contract ERC20 is IERC20 { uint256 private _totalSupply; /** - * @dev Total number of tokens in existence. - */ - function totalSupply() public view returns (uint256) { - return _totalSupply; - } - - /** - * @dev Gets the balance of the specified address. - * @param owner The address to query the balance of. - * @return A uint256 representing the amount owned by the passed address. + * @dev Returns the amount of tokens owned by an account (`owner`). See `IERC20.balanceOf`. */ function balanceOf(address owner) public view returns (uint256) { return _balances[owner]; } + /** + * @dev Moves tokens from the caller's account to a specified recipient + * (`to`). See `IERC20.transfer`. + * + * Requirements + * + * - `to` cannot be the zero address. + */ + function transfer(address to, uint256 value) public returns (bool) { + _transfer(msg.sender, to, value); + return true; + } + + /** + * @dev Configures the amount that a `spender` account is able to spend on + * behalf of the caller. See `IERC20.approve`. + * + * > `approve` can be abused by an untrusted spender. + * + * Requirements + * + * - `spender` cannot be the zero address. + */ + function approve(address spender, uint256 value) public returns (bool) { + _approve(msg.sender, spender, value); + return true; + } + /** * @dev Function to check the amount of tokens that an owner allowed to a spender. * @param owner address The address which owns the funds. @@ -50,30 +80,6 @@ contract ERC20 is IERC20 { return _allowances[owner][spender]; } - /** - * @dev Transfer token to a specified address. - * @param to The address to transfer to. - * @param value The amount to be transferred. - */ - function transfer(address to, uint256 value) public returns (bool) { - _transfer(msg.sender, to, value); - return true; - } - - /** - * @dev Approve the passed address to spend the specified amount of tokens on behalf of msg.sender. - * 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 - * @param spender The address which will spend the funds. - * @param value The amount of tokens to be spent. - */ - function approve(address spender, uint256 value) public returns (bool) { - _approve(msg.sender, spender, value); - return true; - } - /** * @dev Transfer tokens from one address to another. * Note that while this function emits an Approval event, this is not required as per the specification, @@ -118,6 +124,15 @@ contract ERC20 is IERC20 { return true; } + /** + * @dev Returns the amount of tokens in existence. + * + * See `IERC20.totalSupply`. + */ + function totalSupply() public view returns (uint256) { + return _totalSupply; + } + /** * @dev Transfer token for a specified addresses. * @param from The address to transfer from. diff --git a/contracts/token/ERC20/IERC20.sol b/contracts/token/ERC20/IERC20.sol index 7c3230b96..b60df95b9 100644 --- a/contracts/token/ERC20/IERC20.sol +++ b/contracts/token/ERC20/IERC20.sol @@ -1,23 +1,78 @@ pragma solidity ^0.5.0; /** - * @title ERC20 interface - * @dev see https://eips.ethereum.org/EIPS/eip-20 + * @dev Interface of the ERC20 standard as defined in the EIP. Does not include + * the optional functions; to access them see [ERC20Detailed](#erc20detailed). */ interface IERC20 { - function transfer(address to, uint256 value) external returns (bool); - - function approve(address spender, uint256 value) external returns (bool); - - function transferFrom(address from, address to, uint256 value) external returns (bool); - - function totalSupply() external view returns (uint256); - + /** + * @dev Returns the amount of tokens owned by an account (`who`). + */ function balanceOf(address who) external view returns (uint256); + /** + * @dev Moves tokens from the caller's account to a specified recipient + * (`to`). The amount is specified by `value`. + * + * Returns a boolean value indicating whether the operation succeeded. + * + * Emits a `Transfer` event. + */ + function transfer(address to, uint256 value) external returns (bool); + + /** + * @dev Configures the amount that a `spender` account is able to spend on + * behalf of the caller. The amount is specified by `value`. + * + * Returns a boolean value indicating whether the operation succeeded. + * + * See `allowance` and `transferFrom`. + * + * > 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. + */ + function approve(address spender, uint256 value) external returns (bool); + + /** + * @dev Returns the current allowance that an `owner` has set for a `spender`. + * + * This value is updated when either `approve` or `transferFrom` are called. + */ function allowance(address owner, address spender) external view returns (uint256); + /** + * @dev Moves tokens from one account (`from`) to another (`to`). The + * caller must have remaining allowance from the owner (see `approve` and + * `allowance`). If this operation succeeds, the transferred amount + * (`value`) is deducted from the caller's allowance. + * + * Returns a boolean value indicating whether the operation succeeded. + + * Emits a `Transfer` event. + */ + function transferFrom(address from, address to, uint256 value) external returns (bool); + + /** + * @dev Returns the amount of tokens in existence. + */ + function totalSupply() external view returns (uint256); + + /** + * @dev Emitted when tokens are moved from one account (`from`) to anoter (`to`). + * + * Note that `value` may be zero. + */ event Transfer(address indexed from, address indexed to, uint256 value); + /** + * @dev Emitted when the allowance of a `spender` for an `owner` is set by + * a call to `approve`. `value` is the new allowance. + */ event Approval(address indexed owner, address indexed spender, uint256 value); } diff --git a/contracts/token/ERC20/README.md b/contracts/token/ERC20/README.md index 4e0b25ba3..f43216a3a 100644 --- a/contracts/token/ERC20/README.md +++ b/contracts/token/ERC20/README.md @@ -1,18 +1,33 @@ --- sections: - - title: Interfaces + - title: Core contracts: - IERC20 - - title: Contracts - contracts: - ERC20 - ERC20Detailed + - title: Extensions + contracts: - ERC20Mintable - ERC20Burnable - - ERC20Capped - ERC20Pausable + - ERC20Capped - title: Utilities contracts: - SafeERC20 - TokenTimelock --- + +This set of interfaces, contracts, and utilities are all related to the [ERC20 token standard](https://eips.ethereum.org/EIPS/eip-20). + +*For a walkthrough on how to create an ERC20 token read our [ERC20 guide](../../learn-about-tokens.md#constructing-a-nice-erc20-token).* + +There a few core contracts that implement the behavior specified in the EIP: `IERC20`, `ERC20`, `ERC20Detailed`. + +Additionally there are multiple extensions, including: +- designation of addresses that can create token supply (`ERC20Mintable`), with an optional maximum cap (`ERC20Capped`), +- destruction of own tokens (`ERC20Burnable`), +- designation of addresses that can pause token operations for all users (`ERC20Pausable`). + +Finally, there are some utilities to interact with ERC20 contracts in various ways. +- `SafeERC20` is a wrapper around the interface that eliminates the need to handle boolean return values. +- `TokenTimelock` can hold tokens for a beneficiary until a specified time.