ERC20

Reference of interfaces and utilities related to ERC20 contracts.

For an overview of ERC20, read our ERC20 guide.

Core

IERC20 

use openzeppelin::token::erc20::interface::IERC20;

Interface of the IERC20 standard as defined in EIP-20.

Functions
Events

Functions

name() → felt252 external

Returns the name of the token.

symbol() → felt252 external

Returns the ticker symbol of the token.

decimals() → u8 external

Returns the number of decimals the token uses - e.g. 8 means to divide the token amount by 100000000 to get its user-readable 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 a custom implementation is used.

This information is only used for display purposes: it in no way affects any of the arithmetic of the contract.

total_supply() → u256 external

Returns the amount of tokens in existence.

balance_of(account: ContractAddress) → u256 external

Returns the amount of tokens owned by account.

allowance(owner: ContractAddress, spender: ContractAddress) → u256 external

Returns the remaining number of tokens that spender is allowed to spend on behalf of owner through transfer_from. This is zero by default.

This value changes when approve or transfer_from are called.

transfer(recipient: ContractAddress, amount: u256) → bool external

Moves amount tokens from the caller’s token balance to to. Returns true on success, reverts otherwise.

Emits a Transfer event.

transfer_from(sender: ContractAddress, recipient: ContractAddress, amount: u256) → bool external

Moves amount tokens from sender to recipient using the allowance mechanism. amount is then deducted from the caller’s allowance. Returns true on success, reverts otherwise.

Emits a Transfer event.

approve(spender: ContractAddress, amount: u256) → bool external

Sets amount as the allowance of spender over the caller’s tokens. Returns true on success, reverts otherwise.

Emits an Approval event.

Events

Transfer(from: ContractAddress, to: ContractAddress, value: u256) event

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

Note that value may be zero.

Approval(owner: ContractAddress, spender: ContractAddress, value: u256) event

Emitted when the allowance of a spender for an owner is set. value is the new allowance.

ERC20 

use openzeppelin::token::erc20::ERC20;

Implementation of the IERC20 interface.

Constructor
External functions
ERC20Impl
Non-standard
ERC20CamelOnlyImpl
Internal functions
InternalImpl
Events

Constructor

constructor(ref self: ContractState, name: felt252, symbol: felt252, initial_supply: u256, recipient: ContractAddress) constructor

Sets both the token name and symbol and mints initial_supply to recipient. Note that the token name and symbol are immutable once set through the constructor.

External functions

name(@self: ContractState) → felt252 external

See IERC20::name.

symbol(@self: ContractState) → felt252 external

See IERC20::symbol.

decimals(@self: ContractState) → u8 external

See IERC20::decimals.

total_supply(@self: ContractState) → u256 external

See IERC20::total_supply.

balance_of(@self: ContractState, account: ContractAddress) → u256 external

See IERC20::balance_of.

allowance(@self: ContractState, owner: ContractAddress, spender: ContractAddress) → u256 external

See IERC20::allowance.

transfer(ref self: ContractState, recipient: ContractAddress, amount: u256) → bool external

See IERC20::transfer.

Requirements:

  • recipient cannot be the zero address.

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

transfer_from(ref self: ContractState, sender: ContractAddress, recipient: ContractAddress, amount: u256) → bool external

See IERC20::transfer_from.

Requirements:

  • sender cannot be the zero address.

  • sender must have a balance of at least amount.

  • recipient cannot be the zero address.

  • The caller must have allowance for sender's tokens of at least amount.

approve(ref self: ContractState, spender: ContractAddress, amount: u256) → bool external

See IERC20::approve.

Requirements:

  • spender cannot be the zero address.

increase_allowance(ref self: ContractState, spender: ContractAddress, added_value: u256) → bool external

Increases the allowance granted from the caller to spender by added_value Returns true on success, reverts otherwise.

Emits an Approval event.

Requirements:

  • spender cannot be the zero address.

decrease_allowance(ref self: ContractState, spender: ContractAddress, subtracted_value: u256) → bool external

Decreases the allowance granted from the caller to spender by subtracted_value Returns true on success.

Emits an Approval event.

Requirements:

  • spender cannot be the zero address.

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

totalSupply(self: @ContractState) → u256 external

See IERC20::total_supply.

Supports the Cairo v0 convention of writing external methods in camelCase as discussed here.

balanceOf(self: @ContractState, account: ContractAddress) → u256 external

See IERC20::balance_of.

Supports the Cairo v0 convention of writing external methods in camelCase as discussed here.

transferFrom(ref self: ContractState, sender: ContractAddress, recipient: ContractAddress) → bool external

See IERC20::transfer_from.

Supports the Cairo v0 convention of writing external methods in camelCase as discussed here.

increaseAllowance(ref self: ContractState, spender: ContractAddress, addedValue: u256) → bool external

See increase_allowance.

Supports the Cairo v0 convention of writing external methods in camelCase as discussed here.

decreaseAllowance(ref self: ContractState, spender: ContractAddress, subtractedValue: u256) → bool external

See decrease_allowance.

Supports the Cairo v0 convention of writing external methods in camelCase as discussed here.

Internal functions

initializer(ref self: ContractState, name: felt252, symbol: felt252) internal

Initializes the contract by setting the token name and symbol. This should be used inside of the contract’s constructor.

_transfer(ref self: ContractState, sender: ContractAddress, recipient: ContractAddress, amount: u256) internal

Moves amount of tokens from from to to.

This internal function does not check for access permissions but can be useful as a building block, for example to implement automatic token fees, slashing mechanisms, etc.

Emits a Transfer event.

Requirements:

  • from cannot be the zero address.

  • to cannot be the zero address.

  • from must have a balance of at least amount.

_approve(ref self: ContractState, owner: ContractAddress, spender: ContractAddress, amount: u256) internal

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

This internal function does not check for access permissions but can be useful as a building block, for example to implement automatic allowances on behalf of other addresses.

Emits an Approval event.

Requirements:

  • owner cannot be the zero address.

  • spender cannot be the zero address.

_mint(ref self: ContractState, recipient: ContractAddress, amount: u256) internal

Creates an amount number of tokens and assigns them to recipient.

Emits a Transfer event with from being the zero address.

Requirements:

  • recipient cannot be the zero address.

_burn(ref self: ContractState, account: ContractAddress, amount: u256) internal

Destroys amount number of tokens from account.

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

Requirements:

  • account cannot be the zero address.

_increase_allowance(ref self: ContractState, spender: ContractAddress, added_value: u256) internal

Increases the allowance granted from the caller to spender by added_value

Emits an Approval event.

_decrease_allowance(ref self: ContractState, spender: ContractAddress, subtracted_value: u256) internal

Decreases the allowance granted from the caller to spender by subtracted_value

Emits an Approval event.

_spend_allowance(ref self: ContractState, owner: ContractAddress, spender: ContractAddress, amount: u256) internal

Updates owner's allowance for spender based on spent amount.

This internal function does not update the allowance value in the case of infinite allowance.

Possibly emits an Approval event.

Events

Transfer(from: ContractAddress, to: ContractAddress, value: u256) event

See IERC20::Transfer.

Approval(owner: ContractAddress, spender: ContractAddress, value: u256) event

See IERC20::Approval.

← Creating Supply
Introspection →