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.
permit(ref self: ContractState, owner: ContractAddress, spender: ContractAddress, amount: u256, deadline: u64, signature: Span<felt252>) → bool
external
Sets amount
as the allowance of spender
over owner
's tokens after validating the
signature.
Requirements:
-
owner
is a deployed account contract. -
spender
is not the zero address. -
deadline
is not a timestamp in the past. -
signature
is a valid signature that can be validated with a call toowner
account. -
signature
must use the current nonce of theowner
.
Emits an Approval event. Every successful call increases `owner’s nonce by one.
nonces(self: @ContractState, owner: ContractAddress) → felt252
external
Returns the current nonce of owner
. A nonce value must be included
whenever a signature for permit
call is generated.
DOMAIN_SEPARATOR(self: @ContractState) → felt252
external
Returns the domain separator used in generating a message hash for permit
signature.
The domain hashing logic follows the SNIP12 standard.
snip12_metadata(self: @ContractState) → (felt252, felt252)
external
Returns the domain name and version used to generate the message hash for permit signature.
The returned tuple contains:
-
t.0
: The name used in the SNIP12Metadata implementation. -
t.1
: The version used in the SNIP12Metadata implementation.
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
IERC20Permit
use openzeppelin_token::erc20::interface::IERC20Permit;
Interface of the ERC20Permit standard to support gasless token approvals as defined in EIP-2612.
permit(owner: ContractAddress, spender: ContractAddress, amount: u256, deadline: u64, signature: Span<felt252>)
external
Sets amount
as the allowance of spender
over owner
's tokens after validating the signature.
nonces(owner: ContractAddress) → felt252
external
Returns the current nonce of owner
. A nonce value must be included
whenever a signature for permit
call is generated.
DOMAIN_SEPARATOR() → felt252
external
Returns the domain separator used in generating a message hash for permit
signature.
The domain hashing logic follows the SNIP12 standard.
Presets
ERC20Upgradeable
use openzeppelin_presets::ERC20Upgradeable;
Upgradeable ERC20 contract leveraging ERC20Component with a fixed-supply mechanism for token distribution.
0x044491e887497a0dec63a0f3e02bab88abb8cc7594eb9317baa6b847c8c79233