ERC 20

This set of interfaces, contracts, and utilities are all related to the ERC20 Token Standard.

For an overview of ERC20 tokens and a walkthrough on how to create a token contract read our ERC20 guide.

There a few core contracts that implement the behavior specified in the EIP:

  • IERC20: the interface all ERC20 implementations should conform to

  • ERC20: the base implementation of the ERC20 interface

  • ERC20Detailed: includes the name, symbol and decimals optional standard extension to the base interface

Additionally there are multiple custom extensions, including:

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.

This page is incomplete. We’re working to improve it for the next release. Stay tuned!

Core

IERC20

Interface of the ERC20 standard as defined in the EIP. Does not include the optional functions; to access them see ERC20Detailed.

Functions
Events

totalSupply() → uint256 external

Returns the amount of tokens in existence.

balanceOf(address account) → uint256 external

Returns the amount of tokens owned by account.

transfer(address recipient, uint256 amount) → bool external

Moves amount tokens from the caller’s account to recipient.

Returns a boolean value indicating whether the operation succeeded.

Emits a Transfer event.

allowance(address owner, address spender) → uint256 external

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.

approve(address spender, uint256 amount) → bool external

Sets amount as the allowance of spender over the caller’s tokens.

Returns a boolean value indicating whether the operation succeeded.

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.

transferFrom(address sender, address recipient, uint256 amount) → bool external

Moves amount tokens from sender to recipient using the allowance mechanism. amount is then deducted from the caller’s allowance.

Returns a boolean value indicating whether the operation succeeded.

Emits a Transfer event.

Transfer(address from, address to, uint256 value) event

Emitted when value tokens are moved from one account (from) to another (to).

Note that value may be zero.

Approval(address owner, address spender, uint256 value) event

Emitted when the allowance of a spender for an owner is set by a call to approve. value is the new allowance.

ERC20

Implementation of the IERC20 interface.

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.

For a detailed writeup see our guide How to implement supply mechanisms.

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.

Functions
Context
Events
IERC20

totalSupply() → uint256 public

See IERC20.totalSupply.

balanceOf(address account) → uint256 public

See IERC20.balanceOf.

transfer(address recipient, uint256 amount) → bool public

See IERC20.Transfer.

Requirements:

  • recipient cannot be the zero address.

  • the caller must have a balance of at least amount.

allowance(address owner, address spender) → uint256 public

See IERC20.allowance.

approve(address spender, uint256 amount) → bool public

See IERC20.approve.

Requirements:

  • spender cannot be the zero address.

transferFrom(address sender, address recipient, uint256 amount) → bool public

See IERC20.transferFrom.

Emits an Approval event indicating the updated allowance. This is not required by the EIP. See the note at the beginning of ERC20;

Requirements: - sender and recipient cannot be the zero address. - sender must have a balance of at least amount. - the caller must have allowance for sender’s tokens of at least `amount.

increaseAllowance(address spender, uint256 addedValue) → bool public

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 Approval event indicating the updated allowance.

Requirements:

  • spender cannot be the zero address.

decreaseAllowance(address spender, uint256 subtractedValue) → bool public

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.

Requirements:

  • spender cannot be the zero address.

  • spender must have allowance for the caller of at least subtractedValue.

_transfer(address sender, address recipient, uint256 amount) internal

Moves tokens amount from sender to recipient.

This is internal function is equivalent to transfer, and can be used to e.g. implement automatic token fees, slashing mechanisms, etc.

Emits a transfer event.

Requirements:

  • sender cannot be the zero address.

  • recipient cannot be the zero address.

  • sender must have a balance of at least amount.

_mint(address account, uint256 amount) internal

Creates amount tokens and assigns them to account, increasing the total supply.

Emits a transfer event with from set to the zero address.

Requirements

  • to cannot be the zero address.

_burn(address account, uint256 amount) internal

Destroys amount tokens from account, reducing the total supply.

Emits a transfer event with to set to the zero address.

Requirements

  • account cannot be the zero address.

  • account must have at least amount tokens.

_approve(address owner, address spender, uint256 amount) internal

Sets amount as the allowance of spender over the `owner`s tokens.

This is internal function is equivalent to approve, and can be used to e.g. set automatic allowances for certain subsystems, etc.

Emits an Approval event.

Requirements:

  • owner cannot be the zero address.

  • spender cannot be the zero address.

_burnFrom(address account, uint256 amount) internal

Destroys amount tokens from account.amount is then deducted from the caller’s allowance.

See _burn and _approve.

ERC20Detailed

Optional functions from the ERC20 standard.

Functions
IERC20
Events
IERC20

constructor(string name, string symbol, uint8 decimals) public

Sets the values for name, symbol, and decimals. All three of these values are immutable: they can only be set once during construction.

name() → string public

Returns the name of the token.

symbol() → string public

Returns the symbol of the token, usually a shorter version of the name.

decimals() → uint8 public

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 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.

Extensions

ERC20Mintable

Extension of ERC20 that adds a set of accounts with the MinterRole, which have permission to mint (create) new tokens as they see fit.

At construction, the deployer of the contract is the only minter.

Modifiers
MinterRole
Functions
MinterRole
ERC20
Context
Events
MinterRole
IERC20

mint(address account, uint256 amount) → bool public

See ERC20._mint.

Requirements:

ERC20Burnable

Extension of ERC20 that allows token holders to destroy both their own tokens and those that they have an allowance for, in a way that can be recognized off-chain (via event analysis).

Functions
ERC20
Context
Events
IERC20

burn(uint256 amount) public

Destroys amount tokens from the caller.

See ERC20._burn.

burnFrom(address account, uint256 amount) public

See ERC20._burnFrom.

ERC20Pausable

ERC20 with pausable transfers and allowances.

Useful if you want to stop trades until the end of a crowdsale, or have an emergency switch for freezing all token transfers in the event of a large bug.

Modifiers
Pausable
PauserRole
Functions
Pausable
PauserRole
ERC20
Context
Events
Pausable
PauserRole
IERC20

transfer(address to, uint256 value) → bool public

transferFrom(address from, address to, uint256 value) → bool public

approve(address spender, uint256 value) → bool public

increaseAllowance(address spender, uint256 addedValue) → bool public

decreaseAllowance(address spender, uint256 subtractedValue) → bool public

ERC20Capped

Extension of ERC20Mintable that adds a cap to the supply of tokens.

Modifiers
MinterRole
Functions
ERC20Mintable
MinterRole
ERC20
Context
Events
MinterRole
IERC20

constructor(uint256 cap) public

Sets the value of the cap. This value is immutable, it can only be set once during construction.

cap() → uint256 public

Returns the cap on the token’s total supply.

_mint(address account, uint256 value) internal

See ERC20Mintable.mint.

Requirements:

  • value must not cause the total supply to go over the cap.

Utilities

SafeERC20

Wrappers around ERC20 operations that throw on failure (when the token contract returns false). Tokens that return no value (and instead revert or throw on failure) are also supported, non-reverting calls are assumed to be successful. To use this library you can add a using SafeERC20 for ERC20; statement to your contract, which allows you to call the safe operations as token.safeTransfer(…​), etc.

Functions

safeTransfer(contract IERC20 token, address to, uint256 value) internal

safeTransferFrom(contract IERC20 token, address from, address to, uint256 value) internal

safeApprove(contract IERC20 token, address spender, uint256 value) internal

safeIncreaseAllowance(contract IERC20 token, address spender, uint256 value) internal

safeDecreaseAllowance(contract IERC20 token, address spender, uint256 value) internal

TokenTimelock

A token holder contract that will allow a beneficiary to extract the tokens after a given release time.

Useful for simple vesting schedules like "advisors get all of their tokens after 1 year".

For a more complete vesting schedule, see TokenVesting.

Functions

constructor(contract IERC20 token, address beneficiary, uint256 releaseTime) public

token() → contract IERC20 public

beneficiary() → address public

releaseTime() → uint256 public

release() public

← ERC 721
Ownership →