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.

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.

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 to owner account.

  • signature must use the current nonce of the owner.

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:

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

IERC20Permit 

use openzeppelin_token::erc20::interface::IERC20Permit;

Interface of the ERC20Permit standard to support gasless token approvals as defined in EIP-2612.

Functions

Functions

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.

Sierra class hash

0x041385cd42de9877180b006fc01d613c70e2429fc2e660df6a791b4cc0e747de

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.

← ERC20Permit
ERC721 →