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.

totalSupply() → uint256

Returns the amount of tokens in existence.

balanceOf(address account) → uint256

Returns the amount of tokens owned by account.

transfer(address recipient, uint256 amount) → bool

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

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

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

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)

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)

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.

totalSupply() → uint256

balanceOf(address account) → uint256

transfer(address recipient, uint256 amount) → bool

Requirements:

  • recipient cannot be the zero address.

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

allowance(address owner, address spender) → uint256

approve(address spender, uint256 value) → bool

Requirements:

  • spender cannot be the zero address.

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

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 value. - the caller must have allowance for sender’s tokens of at least `amount.

increaseAllowance(address spender, uint256 addedValue) → 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 Approval event indicating the updated allowance.

Requirements:

  • spender cannot be the zero address.

decreaseAllowance(address spender, uint256 subtractedValue) → 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.

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)

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)

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 value)

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 value)

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)

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.

constructor(string name, string symbol, uint8 decimals)

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

Returns the name of the token.

symbol() → string

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

decimals() → 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 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

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.

transfer(address to, uint256 value) → bool

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

approve(address spender, uint256 value) → bool

increaseAllowance(address spender, uint256 addedValue) → bool

decreaseAllowance(address spender, uint256 subtractedValue) → bool

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.

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

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

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

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

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

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.

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

token() → contract IERC20

beneficiary() → address

releaseTime() → uint256

release()