ERC20
This module provides interfaces, presets, 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.
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.
IERC20Metadata
use openzeppelin::token::erc20::interface::IERC20Metadata;
Interface for the optional metadata functions in EIP-20.
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
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.
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
Requirements:
-
sender
cannot be the zero address. -
sender
must have a balance of at leastamount
. -
recipient
cannot be the zero address. -
The caller must have allowance for
sender
's tokens of at leastamount
.
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.
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
Supports the Cairo v0 convention of writing external methods in camelCase as discussed here.
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 leastamount
.
_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.
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.
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 implementSRC6::is_valid_signature
. -
signature
should be valid for the message hash.
Emits a DelegateChanged event.
May emit one or two DelegateVotesChanged events.
_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
.
Presets
ERC20Upgradeable
use openzeppelin::presets::ERC20Upgradeable;
Upgradeable ERC20 contract leveraging ERC20Component with a fixed-supply mechanism for token distribution.
0x073d71c37e20c569186445d2c497d2195b4c0be9a255d72dbad86662fcc63ae6