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

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.

IERC20Metadata 

use openzeppelin::token::erc20::interface::IERC20Metadata;

Interface for the optional metadata functions in EIP-20.

Functions

Functions

name() → ByteArray external

Returns the name of the token.

symbol() → ByteArray 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. To create a custom decimals implementation, see Customizing decimals.

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

ERC20Component 

use openzeppelin::token::erc20::ERC20Component;

ERC20 component extending IERC20 and IERC20Metadata.

See Hooks to understand how are hooks used.
Hooks
Internal implementations
InternalImpl
Events

Hooks

Hooks are functions which implementations can extend the functionality of the component source code. Every contract using ERC20Component is expected to provide an implementation of the ERC20HooksTrait. For basic token contracts, an empty implementation with no logic must be provided.

You can use openzeppelin::token::erc20::ERC20HooksEmptyImpl which is already available as part of the library for this purpose.

before_update(ref self: ContractState, from: ContractAddress, recipient: ContractAddress, amount: u256) hook

Function executed at the beginning of the update function prior to any other logic.

after_update(ref self: ContractState, from: ContractAddress, recipient: ContractAddress, amount: u256) hook

Function executed at the end of the update function.

Embeddable functions

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.

name() → ByteArray external

See IERC20Metadata::name.

symbol() → ByteArray external

See IERC20Metadata::symbol.

decimals() → u8 external

See IERC20Metadata::decimals.

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.

Internal functions

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

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

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.

update(ref self: ContractState, from: ContractAddress, to: ContractAddress, amount: u256) internal

Transfers an amount of tokens from from to to, or alternatively mints (or burns) if from (or to) is the zero address.

This function can be extended using the ERC20HooksTrait, to add functionality before and/or after the transfer, mint, or burn.

Emits a Transfer event.

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

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

Extensions

ERC20VotesComponent 

use openzeppelin::token::extensions::ERC20VotesComponent;

Extension of ERC20 to support voting and delegation.

Implementing ERC20Component is a requirement for this component to be implemented.
To track voting units, this extension requires that the transfer_voting_units function is called after every transfer, mint, or burn operation. For this, the ERC20HooksTrait must be used.

This extension keeps a history (checkpoints) of each account’s vote power. Vote power can be delegated either by calling the delegate function directly, or by providing a signature to be used with delegate_by_sig. Voting power can be queried through the public accessors get_votes and get_past_votes.

By default, token balance does not account for voting power. This makes transfers cheaper. The downside is that it requires users to delegate to themselves in order to activate checkpoints and have their voting power tracked.

Internal implementations
InternalImpl
Events

Embeddable functions

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

Returns the current amount of votes that account has.

get_past_votes(self: @ContractState, account: ContractAddress, timepoint: u64) → u256 external

Returns the amount of votes that account had at a specific moment in the past.

Requirements:

  • timepoint must be in the past.

get_past_total_supply(self: @ContractState, timepoint: u64) → u256 external

Returns the total supply of votes available at a specific moment in the past.

This value is the sum of all available votes, which is not necessarily the sum of all delegated votes. Votes that have not been delegated are still part of total supply, even though they would not participate in a vote.

delegates(self: @ContractState, account: ContractAddress) → ContractAddress external

Returns the delegate that account has chosen.

delegate(ref self: ContractState, delegatee: ContractAddress) external

Delegates votes from the caller to delegatee.

Emits a DelegateChanged event.

May emit one or two DelegateVotesChanged events.

delegate_by_sig(ref self: ContractState, delegator: ContractAddress, delegatee: ContractAddress, nonce: felt252, expiry: u64, signature: Array<felt252>) external

Delegates votes from delegator to delegatee through a SNIP12 message signature validation.

Requirements:

  • expiry must not be in the past.

  • nonce must match the account’s current nonce.

  • delegator must implement SRC6::is_valid_signature.

  • signature should be valid for the message hash.

Emits a DelegateChanged event.

May emit one or two DelegateVotesChanged events.

Internal functions

get_total_supply(self: @ContractState) → u256 internal

Returns the current total supply of votes.

_delegate(ref self: ContractState, account: ContractAddress, delegatee: ContractAddress) internal

Delegates all of account's voting units to delegatee.

Emits a DelegateChanged event.

May emit one or two DelegateVotesChanged events.

move_delegate_votes(ref self: ContractState, from: ContractAddress, to: ContractAddress, amount: u256) internal

Moves amount of delegated votes from from to to.

May emit one or two DelegateVotesChanged events.

transfer_voting_units(ref self: ContractState, from: ContractAddress, to: ContractAddress, amount: u256) internal

Transfers, mints, or burns voting units.

To register a mint, from should be zero. To register a burn, to should be zero. Total supply of voting units will be adjusted with mints and burns.

May emit one or two DelegateVotesChanged events.

num_checkpoints(self: @ContractState, account: ContractAddress) → u32 internal

Returns the number of checkpoints for account.

checkpoints(self: @ContractState, account: ContractAddress, pos: u32) → Checkpoint internal

Returns the pos-th checkpoint for account.

get_voting_units(self: @ContractState, account: ContractAddress) → u256 internal

Returns the voting units of an account.

Events

DelegateChanged(delegator: ContractAddress, from_delegate: ContractAddress, to_delegate: ContractAddress) event

Emitted when delegator delegates their votes from from_delegate to to_delegate.

DelegateVotesChanged(delegate: ContractAddress, previous_votes: u256, new_votes: u256) event

Emitted when delegate votes are updated from previous_votes to new_votes.

Presets

ERC20Upgradeable 

use openzeppelin::presets::ERC20Upgradeable;

Upgradeable ERC20 contract leveraging ERC20Component with a fixed-supply mechanism for token distribution.

Sierra class hash

0x041f57a27f2fba3477c38e6559a09bf5b7bb3244ec1ca3cbea4ca5918d253137

Constructor
Embedded Implementations
ERC20MixinImpl
OwnableMixinImpl
External Functions

Constructor

constructor(ref self: ContractState, name: ByteArray, symbol: ByteArray, fixed_supply: u256, recipient: ContractAddress, owner: ContractAddress) constructor

Sets the name and symbol and mints fixed_supply tokens to recipient. Assigns owner as the contract owner with permissions to upgrade.

External functions

upgrade(ref self: ContractState, new_class_hash: ClassHash) external

Upgrades the contract to a new implementation given by new_class_hash.

Requirements:

  • The caller is the contract owner.

  • new_class_hash cannot be zero.

← Creating Supply
ERC721 →