ERC6909

This module provides interfaces and components for ERC6909 contracts.

For an overview of ERC6909, read the ERC6909 guide.

Interfaces

The interfaces documented here are provided by the openzeppelin_interfaces package version 2.2.0.

`IERC6909`

use openzeppelin_interfaces::erc6909::IERC6909;

Interface of the minimal multi-token standard defined in EIP-6909.

SRC5 ID

0xd5aa138060489fd9c4592f77a16011cc5615ce4d292ee1f7873ae65c43b6bb

Functions

balance_of(owner, id)
allowance(owner, spender, id)
is_operator(owner, spender)
transfer(receiver, id, amount)
transfer_from(sender, receiver, id, amount)
approve(spender, id, amount)
set_operator(spender, approved)

Events

Transfer(caller, sender, receiver, id, amount)
Approval(owner, spender, id, amount)
OperatorSet(owner, spender, approved)

Functions

balance_of(owner: ContractAddress, id: u256) → u256

external

Returns the amount of id tokens owned by owner.

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

external

Returns the number of id tokens that spender can transfer on behalf of owner.

is_operator(owner: ContractAddress, spender: ContractAddress) → bool

external

Returns whether spender is approved as an operator for every token ID owned by owner.

transfer(receiver: ContractAddress, id: u256, amount: u256) → bool

external

Transfers amount of token id from the caller to receiver.

Emits a Transfer event.

transfer_from(sender: ContractAddress, receiver: ContractAddress, id: u256, amount: u256) → bool

external

Transfers amount of token id from sender to receiver, using the caller's allowance when the caller is neither sender nor an operator for sender.

Emits a Transfer event.

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

external

Sets amount as spender's allowance for the caller's token id.

Emits an Approval event.

set_operator(spender: ContractAddress, approved: bool) → bool

external

Grants or revokes spender's permission to transfer every token ID owned by the caller.

Emits an OperatorSet event.

Events

Transfer(caller: ContractAddress, sender: ContractAddress, receiver: ContractAddress, id: u256, amount: u256)

event

Emitted when caller moves amount of token id from sender to receiver.

Approval(owner: ContractAddress, spender: ContractAddress, id: u256, amount: u256)

event

Emitted when owner sets spender's allowance for token id to amount.

OperatorSet(owner: ContractAddress, spender: ContractAddress, approved: bool)

event

Emitted when owner grants or revokes spender's operator approval.

Core

`ERC6909Component`

use openzeppelin_token::erc6909::ERC6909Component;

ERC6909 component implementing IERC6909.

Implementing SRC5Component is required by this component.

See Hooks for the extension points invoked by token updates.

Hooks

ERC6909HooksTrait

before_update(self, from, recipient, id, amount)
after_update(self, from, recipient, id, amount)

Embeddable Implementations

ERC6909Impl

balance_of(self, owner, id)
allowance(self, owner, spender, id)
is_operator(self, owner, spender)
transfer(self, receiver, id, amount)
transfer_from(self, sender, receiver, id, amount)
approve(self, spender, id, amount)
set_operator(self, spender, approved)

Internal functions

InternalImpl

initializer(self)
mint(self, receiver, id, amount)
burn(self, account, id, amount)
update(self, sender, receiver, id, amount)
_set_operator(self, owner, spender, approved)
_spend_allowance(self, owner, spender, id, amount)
_approve(self, owner, spender, id, amount)
_transfer(self, sender, receiver, id, amount)

Events

Transfer(caller, sender, receiver, id, amount)
Approval(owner, spender, id, amount)
OperatorSet(owner, spender, approved)

Hooks

Every contract using ERC6909Component must implement ERC6909HooksTrait. Import openzeppelin_token::erc6909::ERC6909HooksEmptyImpl when the contract does not need custom hook logic.

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

hook

Runs at the beginning of update, before balances change.

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

hook

Runs at the end of update, after balances change and the Transfer event is emitted.

Embeddable functions

balance_of(self: @ContractState, owner: ContractAddress, id: u256) → u256

external

Returns the amount of id tokens owned by owner.

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

external

Returns the number of id tokens that spender can transfer on behalf of owner.

is_operator(self: @ContractState, owner: ContractAddress, spender: ContractAddress) → bool

external

Returns whether spender is approved as an operator for every token ID owned by owner.

transfer(ref self: ContractState, receiver: ContractAddress, id: u256, amount: u256) → bool

external

Transfers amount of token id from the caller to receiver.

Requirements:

receiver is not the zero address.
The caller has a balance of at least amount for token id.

Emits a Transfer event.

transfer_from(ref self: ContractState, sender: ContractAddress, receiver: ContractAddress, id: u256, amount: u256) → bool

external

Transfers amount of token id from sender to receiver. The caller's per-token allowance is spent unless the caller is sender or an operator for sender.

Requirements:

sender and receiver are not the zero address.
sender has a balance of at least amount for token id.
The caller is sender, is an operator for sender, or has an allowance of at least amount.

Emits a Transfer event.

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

external

Sets amount as spender's allowance for the caller's token id.

Requirements:

spender is not the zero address.

Emits an Approval event.

set_operator(ref self: ContractState, spender: ContractAddress, approved: bool) → bool

external

Grants or revokes spender's permission to transfer every token ID owned by the caller.

Requirements:

spender is not the zero address.

Emits an OperatorSet event.

Internal functions

initializer(ref self: ContractState)

internal

Registers the IERC6909 interface ID through SRC5. Call this function from the contract's constructor.

mint(ref self: ContractState, receiver: ContractAddress, id: u256, amount: u256)

internal

Mints amount of token id to receiver.

Requirements:

receiver is not the zero address.

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

burn(ref self: ContractState, account: ContractAddress, id: u256, amount: u256)

internal

Burns amount of token id from account.

Requirements:

account is not the zero address.
account has a balance of at least amount for token id.

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

update(ref self: ContractState, sender: ContractAddress, receiver: ContractAddress, id: u256, amount: u256)

internal

Moves amount of token id from sender to receiver. A zero sender represents a mint, and a zero receiver represents a burn.

Invokes before_update before balances change and after_update after the Transfer event is emitted. Total supply tracking is provided by ERC6909TokenSupplyComponent.

Emits a Transfer event.

_set_operator(ref self: ContractState, owner: ContractAddress, spender: ContractAddress, approved: bool)

internal

Grants or revokes spender's operator approval for owner.

Requirements:

owner and spender are not the zero address.

Emits an OperatorSet event.

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

internal

Reduces spender's allowance for owner and token id by amount.

An allowance equal to the maximum u256 value is treated as infinite and is not reduced. This function does not emit an Approval event.

Requirements:

A finite allowance is at least amount.

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

internal

Sets amount as spender's allowance for owner and token id.

Requirements:

owner and spender are not the zero address.

Emits an Approval event.

_transfer(ref self: ContractState, sender: ContractAddress, receiver: ContractAddress, id: u256, amount: u256)

internal

Moves amount of token id from sender to receiver through update.

Requirements:

sender and receiver are not the zero address.
sender has a balance of at least amount for token id.

Emits a Transfer event.

Events

Transfer(caller: ContractAddress, sender: ContractAddress, receiver: ContractAddress, id: u256, amount: u256)

event

See IERC6909::Transfer.

Approval(owner: ContractAddress, spender: ContractAddress, id: u256, amount: u256)

event

See IERC6909::Approval.

OperatorSet(owner: ContractAddress, spender: ContractAddress, approved: bool)

event

See IERC6909::OperatorSet.

Extension interfaces

`IERC6909ContentUri`

use openzeppelin_interfaces::erc6909::IERC6909ContentUri;

Interface for contract-level and token-level content URIs.

SRC5 ID

0x356efd8b40a01c1525c7d0ecafbe3b82a47df564fdd496727effe6336526f05

Functions

contract_uri()
token_uri(id)

Functions

contract_uri() → ByteArray

external

Returns the contract-level URI.

token_uri(id: u256) → ByteArray

external

Returns the URI associated with token id.

`IERC6909ContentUriAdmin`

use openzeppelin_interfaces::erc6909::IERC6909ContentUriAdmin;

Interface for managing ERC6909 content URIs. Implementations restrict these functions through Ownable, AccessControl, or AccessControlDefaultAdminRules.

Functions

set_contract_uri(contract_uri)
set_token_uri(id, token_uri)

Functions

set_contract_uri(contract_uri: ByteArray)

external

Sets the contract-level URI.

set_token_uri(id: u256, token_uri: ByteArray)

external

Sets the URI associated with token id.

`IERC6909Metadata`

use openzeppelin_interfaces::erc6909::IERC6909Metadata;

Interface for per-token metadata.

SRC5 ID

0x19aa0b778d120d5294054319458ee8886514766411c50dceddd9463712d6011

Functions

name(id)
symbol(id)
decimals(id)

Functions

name(id: u256) → ByteArray

external

Returns the name of token id.

symbol(id: u256) → ByteArray

external

Returns the symbol of token id.

decimals(id: u256) → u8

external

Returns the number of decimals used to display token id.

`IERC6909MetadataAdmin`

use openzeppelin_interfaces::erc6909::IERC6909MetadataAdmin;

Interface for managing ERC6909 token metadata. Implementations restrict these functions through Ownable, AccessControl, or AccessControlDefaultAdminRules.

Functions

set_token_name(id, name)
set_token_symbol(id, symbol)
set_token_decimals(id, decimals)

Functions

set_token_name(id: u256, name: ByteArray)

external

Sets the name of token id.

set_token_symbol(id: u256, symbol: ByteArray)

external

Sets the symbol of token id.

set_token_decimals(id: u256, decimals: u8)

external

Sets the number of decimals used to display token id.

`IERC6909TokenSupply`

use openzeppelin_interfaces::erc6909::IERC6909TokenSupply;

Interface for querying per-token total supply.

SRC5 ID

0x3a632c15cb93b574eb9166de70521abbeab5c2eb4fdab9930729bba8658c41

Functions

total_supply(id)

Functions

total_supply(id: u256) → u256

external

Returns the total supply of token id.

Extensions

`ERC6909ContentURIComponent`

use openzeppelin_token::erc6909::extensions::ERC6909ContentURIComponent;

Component implementing IERC6909ContentUri and the access-controlled variants of IERC6909ContentUriAdmin.

Implementing ERC6909Component and SRC5Component is required by this component.

Constants

CONTENT_URI_ADMIN_ROLE

Embeddable Implementations

ERC6909ContentURIImpl

contract_uri(self)
token_uri(self, id)

ERC6909ContentURIAdminOwnableImpl

set_contract_uri(self, contract_uri)
set_token_uri(self, id, token_uri)

ERC6909ContentURIAdminAccessControlImpl

set_contract_uri(self, contract_uri)
set_token_uri(self, id, token_uri)

ERC6909ContentURIAdminAccessControlDefaultAdminRulesImpl

set_contract_uri(self, contract_uri)
set_token_uri(self, id, token_uri)

Internal functions

InternalImpl

initializer(self)
_set_contract_uri(self, contract_uri)
_set_token_uri(self, id, token_uri)

Events

ContractURIUpdated()
URI(value, id)

Constants

CONTENT_URI_ADMIN_ROLE: felt252

constant

Role required by the AccessControl and AccessControlDefaultAdminRules implementations to manage contract and token URIs.

Embeddable functions

contract_uri(self: @ContractState) → ByteArray

external

Returns the contract-level URI.

token_uri(self: @ContractState, id: u256) → ByteArray

external

Returns the URI associated with token id. Returns an empty ByteArray when no URI has been set for that token.

ERC6909ContentURIAdminOwnableImpl

Provides content URI management restricted to the contract owner. Requires OwnableComponent.

set_contract_uri(ref self: ContractState, contract_uri: ByteArray)

external

Sets the contract-level URI.

Requirements:

The caller is the contract owner.

Emits a ContractURIUpdated event.

set_token_uri(ref self: ContractState, id: u256, token_uri: ByteArray)

external

Sets the URI associated with token id.

Requirements:

The caller is the contract owner.

Emits a URI event.

ERC6909ContentURIAdminAccessControlImpl

Provides content URI management restricted by CONTENT_URI_ADMIN_ROLE. Requires AccessControlComponent.

set_contract_uri(ref self: ContractState, contract_uri: ByteArray)

external

Sets the contract-level URI.

Requirements:

The caller has CONTENT_URI_ADMIN_ROLE.

Emits a ContractURIUpdated event.

set_token_uri(ref self: ContractState, id: u256, token_uri: ByteArray)

external

Sets the URI associated with token id.

Requirements:

The caller has CONTENT_URI_ADMIN_ROLE.

Emits a URI event.

ERC6909ContentURIAdminAccessControlDefaultAdminRulesImpl

Provides content URI management restricted by CONTENT_URI_ADMIN_ROLE. Requires AccessControlDefaultAdminRulesComponent.

set_contract_uri(ref self: ContractState, contract_uri: ByteArray)

external

Sets the contract-level URI.

Requirements:

The caller has CONTENT_URI_ADMIN_ROLE.

Emits a ContractURIUpdated event.

set_token_uri(ref self: ContractState, id: u256, token_uri: ByteArray)

external

Sets the URI associated with token id.

Requirements:

The caller has CONTENT_URI_ADMIN_ROLE.

Emits a URI event.

Internal functions

initializer(ref self: ContractState)

internal

Registers the IERC6909ContentUri interface ID through SRC5. Call this function from the contract's constructor.

_set_contract_uri(ref self: ContractState, contract_uri: ByteArray)

internal

Sets the contract-level URI.

Emits a ContractURIUpdated event.

_set_token_uri(ref self: ContractState, id: u256, token_uri: ByteArray)

internal

Sets the URI associated with token id.

Emits a URI event.

Events

ContractURIUpdated()

event

Emitted when the contract-level URI changes. See ERC-7572.

URI(value: ByteArray, id: u256)

event

Emitted when the URI associated with token id changes to value.

`ERC6909MetadataComponent`

use openzeppelin_token::erc6909::extensions::ERC6909MetadataComponent;

Component implementing IERC6909Metadata and the access-controlled variants of IERC6909MetadataAdmin.

Implementing ERC6909Component and SRC5Component is required by this component.

Constants

METADATA_ADMIN_ROLE

Embeddable Implementations

ERC6909MetadataImpl

name(self, id)
symbol(self, id)
decimals(self, id)

ERC6909MetadataAdminOwnableImpl

set_token_name(self, id, name)
set_token_symbol(self, id, symbol)
set_token_decimals(self, id, decimals)

ERC6909MetadataAdminAccessControlImpl

set_token_name(self, id, name)
set_token_symbol(self, id, symbol)
set_token_decimals(self, id, decimals)

ERC6909MetadataAdminAccessControlDefaultAdminRulesImpl

set_token_name(self, id, name)
set_token_symbol(self, id, symbol)
set_token_decimals(self, id, decimals)

Internal functions

InternalImpl

initializer(self)
_set_token_name(self, id, name)
_set_token_symbol(self, id, symbol)
_set_token_decimals(self, id, decimals)

Events

ERC6909NameUpdated(id, new_name)
ERC6909SymbolUpdated(id, new_symbol)
ERC6909DecimalsUpdated(id, new_decimals)

Constants

METADATA_ADMIN_ROLE: felt252

constant

Role required by the AccessControl and AccessControlDefaultAdminRules implementations to manage token metadata.

Embeddable functions

name(self: @ContractState, id: u256) → ByteArray

external

Returns the name of token id.

symbol(self: @ContractState, id: u256) → ByteArray

external

Returns the symbol of token id.

decimals(self: @ContractState, id: u256) → u8

external

Returns the number of decimals used to display token id.

ERC6909MetadataAdminOwnableImpl

Provides metadata management restricted to the contract owner. Requires OwnableComponent.

set_token_name(ref self: ContractState, id: u256, name: ByteArray)

external

Sets the name of token id.

Requirements:

The caller is the contract owner.

Emits an ERC6909NameUpdated event.

set_token_symbol(ref self: ContractState, id: u256, symbol: ByteArray)

external

Sets the symbol of token id.

Requirements:

The caller is the contract owner.

Emits an ERC6909SymbolUpdated event.

set_token_decimals(ref self: ContractState, id: u256, decimals: u8)

external

Sets the number of decimals used to display token id.

Requirements:

The caller is the contract owner.

Emits an ERC6909DecimalsUpdated event.

ERC6909MetadataAdminAccessControlImpl

Provides metadata management restricted by METADATA_ADMIN_ROLE. Requires AccessControlComponent.

set_token_name(ref self: ContractState, id: u256, name: ByteArray)

external

Sets the name of token id.

Requirements:

The caller has METADATA_ADMIN_ROLE.

Emits an ERC6909NameUpdated event.

set_token_symbol(ref self: ContractState, id: u256, symbol: ByteArray)

external

Sets the symbol of token id.

Requirements:

The caller has METADATA_ADMIN_ROLE.

Emits an ERC6909SymbolUpdated event.

set_token_decimals(ref self: ContractState, id: u256, decimals: u8)

external

Sets the number of decimals used to display token id.

Requirements:

The caller has METADATA_ADMIN_ROLE.

Emits an ERC6909DecimalsUpdated event.

ERC6909MetadataAdminAccessControlDefaultAdminRulesImpl

Provides metadata management restricted by METADATA_ADMIN_ROLE. Requires AccessControlDefaultAdminRulesComponent.

set_token_name(ref self: ContractState, id: u256, name: ByteArray)

external

Sets the name of token id.

Requirements:

The caller has METADATA_ADMIN_ROLE.

Emits an ERC6909NameUpdated event.

set_token_symbol(ref self: ContractState, id: u256, symbol: ByteArray)

external

Sets the symbol of token id.

Requirements:

The caller has METADATA_ADMIN_ROLE.

Emits an ERC6909SymbolUpdated event.

set_token_decimals(ref self: ContractState, id: u256, decimals: u8)

external

Sets the number of decimals used to display token id.

Requirements:

The caller has METADATA_ADMIN_ROLE.

Emits an ERC6909DecimalsUpdated event.

Internal functions

initializer(ref self: ContractState)

internal

Registers the IERC6909Metadata interface ID through SRC5. Call this parameterless function from the contract's constructor.

_set_token_name(ref self: ContractState, id: u256, name: ByteArray)

internal

Sets the name of token id.

Emits an ERC6909NameUpdated event.

_set_token_symbol(ref self: ContractState, id: u256, symbol: ByteArray)

internal

Sets the symbol of token id.

Emits an ERC6909SymbolUpdated event.

_set_token_decimals(ref self: ContractState, id: u256, decimals: u8)

internal

Sets the number of decimals used to display token id.

Emits an ERC6909DecimalsUpdated event.

Events

ERC6909NameUpdated(id: u256, new_name: ByteArray)

event

Emitted when the name of token id changes to new_name.

ERC6909SymbolUpdated(id: u256, new_symbol: ByteArray)

event

Emitted when the symbol of token id changes to new_symbol.

ERC6909DecimalsUpdated(id: u256, new_decimals: u8)

event

Emitted when the display decimals of token id changes to new_decimals.

`ERC6909TokenSupplyComponent`

use openzeppelin_token::erc6909::extensions::ERC6909TokenSupplyComponent;

Component implementing IERC6909TokenSupply and tracking total supply separately for each token ID.

Implementing ERC6909Component, its hooks trait, and SRC5Component is required by this component. Call update_token_supply from before_update to keep supply synchronized with mints and burns.

Embeddable Implementations

ERC6909TokenSupplyImpl

total_supply(self, id)

Internal functions

InternalImpl

initializer(self)
update_token_supply(self, sender, receiver, id, amount)

Embeddable functions

total_supply(self: @ContractState, id: u256) → u256

external

Returns the total supply of token id.

Internal functions

initializer(ref self: ContractState)

internal

Registers the IERC6909TokenSupply interface ID through SRC5. Call this function from the contract's constructor.

update_token_supply(ref self: ContractState, sender: ContractAddress, receiver: ContractAddress, id: u256, amount: u256)

internal

Updates the total supply of token id. A zero sender increases supply by amount, and a zero receiver decreases supply by amount. Ordinary transfers do not change supply.

Call this function from before_update so supply changes are applied before core balances change.

ERC6909

On this page