HomeForumWebsiteImpact
GitHub Icon
API Reference

ERC1155

AnthropicOpen in Claude

This module provides interfaces, presets, and utilities related to ERC1155 contracts.

For an overview of ERC1155, read our ERC1155 guide.

Interfaces

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

IERC1155

GitHub icon
use openzeppelin_interfaces::erc1155::IERC1155;

Interface of the IERC1155 standard as defined in EIP1155.

SRC5 ID

0x6114a8f75559e1b39fcba08ce02961a1aa082d9256a158dd3e64964e4b1b52

Functions

Events

Functions

balance_of(account: ContractAddress, token_id: u256) → u256

external

#

Returns the amount of token_id tokens owned by account.

balance_of_batch(accounts: Span<ContractAddress>, token_ids: Span<u256>) → Span<u256>

external

#

Returns a list of balances derived from the accounts and token_ids pairs.

safe_transfer_from(from: ContractAddress, to: ContractAddress, token_id: u256, value: u256, data: Span<felt252>)

external

#

Transfers ownership of value amount of token_id from from if to is either IERC1155Receiver or an account.

data is additional data, it has no specified format and it is passed to to.

Emits a TransferSingle event.

safe_batch_transfer_from(from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data: Span<felt252>)

external

#

Transfers ownership of token_ids and values pairs from from if to is either IERC1155Receiver or an account.

data is additional data, it has no specified format and it is passed to to.

Emits a TransferBatch event.

set_approval_for_all(operator: ContractAddress, approved: bool)

external

#

Enables or disables approval for operator to manage all of the caller's assets.

Emits an ApprovalForAll event.

is_approved_for_all(owner: ContractAddress, operator: ContractAddress) -> bool

external

#

Queries if operator is an authorized operator for owner.

Events

TransferSingle(operator: ContractAddress, from: ContractAddress, to: ContractAddress, id: u256, value: u256)

event

#

Emitted when value amount of id token is transferred from from to to through operator.

TransferBatch(operator: ContractAddress, from: ContractAddress, to: ContractAddress, ids: Span<u256>, values: Span<u256>)

event

#

Emitted when a batch of values amount of ids tokens are transferred from from to to through operator.

ApprovalForAll(owner: ContractAddress, operator: ContractAddress, approved: bool)

event

#

Emitted when owner enables or disables operator to manage all of the owner's assets.

URI(value: ByteArray, id: u256)

event

#

Emitted when the token URI is updated to value for the id token.

IERC1155MetadataURI

GitHub icon
use openzeppelin_interfaces::erc1155::IERC1155MetadataURI;

Interface for the optional metadata function in EIP1155.

SRC5 ID

0xcabe2400d5fe509e1735ba9bad205ba5f3ca6e062da406f72f113feb889ef7

Functions

Functions

uri(token_id: u256) -> ByteArray

external

#

Returns the Uniform Resource Identifier (URI) for the token_id token.

IERC1155Receiver

GitHub icon
use openzeppelin_interfaces::erc1155::IERC1155Receiver;

Interface for contracts that support receiving token transfers from ERC1155 contracts.

SRC5 ID

0x15e8665b5af20040c3af1670509df02eb916375cdf7d8cbaf7bd553a257515e

Functions

Functions

on_erc1155_received(operator: ContractAddress, from: ContractAddress, token_id: u256, value: u256, data Span<felt252>) -> felt252

external

#

This function is called whenever an ERC1155 token_id token is transferred to this IERC1155Receiver implementer via IERC1155::safe_transfer_from by operator from from.

on_erc1155_batch_received(operator: ContractAddress, from: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data Span<felt252>) -> felt252

external

#

This function is called whenever multiple ERC1155 token_ids tokens are transferred to this IERC1155Receiver implementer via IERC1155::safe_batch_transfer_from by operator from from.

IERC1155Supply

GitHub icon
use openzeppelin_interfaces::erc1155::IERC1155Supply;

Interface for tracking the supply of ERC1155 token types.

Functions

Functions

total_supply(token_id: u256) → u256

external

#

Returns the total supply of token_id.

total_supply_all() → u256

external

#

Returns the aggregate supply across all token IDs.

exists(token_id: u256) → bool

external

#

Returns whether the total supply of token_id is greater than zero.

Core

ERC1155Component

GitHub icon
use openzeppelin_token::erc1155::ERC1155Component;

ERC1155 component implementing IERC1155 and IERC1155MetadataURI.

Implementing SRC5Component is a requirement for this component to be implemented.

See Hooks to understand how are hooks used.

Token URI

The metadata implementation delegates URI resolution to ERC1155TokenURITrait. Contracts can use the default implementation or provide an extension-specific implementation such as ERC1155URIStorageImpl.

ERC1155TokenURITrait trait

trait

#
use openzeppelin_token::erc1155::ERC1155Component::ERC1155TokenURITrait;

Defines uri(self: @ComponentState, token_id: u256) → ByteArray, which is used by ERC1155MetadataURIImpl.

ERC1155TokenURIDefaultImpl impl

impl

#
use openzeppelin_token::erc1155::ERC1155TokenURIDefaultImpl;

Returns the component's common base URI for every token type. Clients replace the \{id\} substring according to the ERC1155 metadata substitution rules.

Hooks

ERC1155HooksTrait

Embeddable Mixin Implementations

ERC1155MixinImpl

Embeddable Implementations

ERC1155Impl

ERC1155MetadataURIImpl

ERC1155CamelImpl

Internal Functions

InternalImpl

Events

IERC1155

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

You can use openzeppelin_token::erc1155::ERC1155HooksEmptyImpl which is already available as part of the library for this purpose.

before_update(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>)

hook

#

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

after_update(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>)

hook

#

Function executed at the end of the update function.

Embeddable functions

balance_of(self: @ContractState, account: ContractAddress, token_id: u256) → u256

external

#

Returns the amount of token_id tokens owned by account.

balance_of_batch(self: @ContractState, accounts: Span<ContractAddress>, token_ids: Span<u256>) → Span<u256>

external

#

Returns a list of balances derived from the accounts and token_ids pairs.

Requirements:

  • token_ids and accounts must have the same length.

safe_transfer_from(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_id: u256, value: u256, data: Span<felt252>)

external

#

Transfers ownership of value amount of token_id from from if to is either an account or IERC1155Receiver.

data is additional data, it has no specified format and it is passed to to.

This function can potentially allow a reentrancy attack when transferring tokens to an untrusted contract, when invoking on_ERC1155_received on the receiver. Ensure to follow the checks-effects-interactions pattern and consider employing reentrancy guards when interacting with untrusted contracts.

Requirements:

  • Caller is either approved or the token_id owner.
  • from is not the zero address.
  • to is not the zero address.
  • If to refers to a non-account contract, it must implement IERC1155Receiver::on_ERC1155_received and return the required magic value.

Emits a TransferSingle event.

safe_batch_transfer_from(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data: Span<felt252>)

external

#

Transfers ownership of values and token_ids pairs from from if to is either an account or IERC1155Receiver.

data is additional data, it has no specified format and it is passed to to.

This function can potentially allow a reentrancy attack when transferring tokens to an untrusted contract, when invoking on_ERC1155_batch_received on the receiver. Ensure to follow the checks-effects-interactions pattern and consider employing reentrancy guards when interacting with untrusted contracts.

Requirements:

  • Caller is either approved or the token_id owner.
  • from is not the zero address.
  • to is not the zero address.
  • token_ids and values must have the same length.
  • If to refers to a non-account contract, it must implement IERC1155Receiver::on_ERC1155_batch_received and return the acceptance magic value.

Emits a TransferSingle event if the arrays contain one element, and TransferBatch otherwise.

set_approval_for_all(ref self: ContractState, operator: ContractAddress, approved: bool)

external

#

Enables or disables approval for operator to manage all of the callers assets.

Requirements:

  • operator cannot be the caller.

Emits an ApprovalForAll event.

is_approved_for_all(self: @ContractState, owner: ContractAddress, operator: ContractAddress) -> bool

external

#

Queries if operator is an authorized operator for owner.

uri(self: @ContractState, token_id: u256) -> ByteArray

external

#

This implementation returns the same URI for all token types. It relies on the token type ID substitution mechanism specified in the EIP.

Clients calling this function must replace the id substring with the actual token type ID.

balanceOf(self: @ContractState, account: ContractAddress, tokenId: u256) → u256

external

#

See ERC1155Component::balance_of.

balanceOfBatch(self: @ContractState, accounts: Span<ContractAddress>, tokenIds: Span<u256>) → Span<u256>

external

#

See ERC1155Component::balance_of_batch.

safeTransferFrom(ref self: ContractState, from: ContractAddress, to: ContractAddress, tokenId: u256, value: u256, data: Span<felt252>)

external

#

See ERC1155Component::safe_transfer_from.

safeBatchTransferFrom(ref self: ContractState, from: ContractAddress, to: ContractAddress, tokenIds: Span<u256>, values: Span<u256>, data: Span<felt252>)

external

#

See ERC1155Component::safe_batch_transfer_from.

setApprovalForAll(ref self: ContractState, operator: ContractAddress, approved: bool)

external

#

See ERC1155Component::set_approval_for_all.

isApprovedForAll(self: @ContractState, owner: ContractAddress, operator: ContractAddress) -> bool

external

#

See ERC1155Component::is_approved_for_all.

Internal functions

initializer(ref self: ContractState, base_uri: ByteArray)

internal

#

Initializes the contract by setting the token's base URI as base_uri, and registering the supported interfaces. This should only be used inside the contract's constructor.

Most ERC1155 contracts expose the IERC1155MetadataURI interface which is what this initializer is meant to support. If the contract DOES NOT expose the IERC1155MetadataURI interface, meaning tokens do not have a URI, the contract must instead use initializer_no_metadata in the constructor. Failure to abide by these instructions can lead to unexpected issues especially with UIs.

initializer_no_metadata(ref self: ContractState)

internal

#

Initializes the contract with no metadata by registering only the IERC1155 interface.

This initializer should ONLY be used during construction in the very specific instance when the contract does NOT expose the IERC1155MetadataURI interface. Initializing a contract with this initializer means that tokens will not have a URI.

mint_with_acceptance_check(ref self: ContractState, to: ContractAddress, token_id: u256, value: u256, data: Span<felt252>)

internal

#

Creates a value amount of tokens of type token_id, and assigns them to to.

Requirements:

  • to cannot be the zero address.
  • If to refers to a smart contract, it must implement IERC1155Receiver::on_ERC1155_received and return the acceptance magic value.

Emits a TransferSingle event.

batch_mint_with_acceptance_check(ref self: ContractState, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data: Span<felt252>)

internal

#

Batched version of mint_with_acceptance_check.

Requirements:

  • to cannot be the zero address.
  • token_ids and values must have the same length.
  • If to refers to a smart contract, it must implement IERC1155Receiver::on_ERC1155_batch_received and return the acceptance magic value.

Emits a TransferBatch event.

burn(ref self: ContractState, from: ContractAddress, token_id: u256, value: u256)

internal

#

Destroys a value amount of tokens of type token_id from from.

Requirements:

  • from cannot be the zero address.
  • from must have at least value amount of tokens of type token_id.

Emits a TransferSingle event.

batch_burn(ref self: ContractState, from: ContractAddress, token_ids: Span<u256>, values: Span<u256>)

internal

#

Batched version of burn.

Requirements:

  • from cannot be the zero address.
  • from must have at least value amount of tokens of type token_id.
  • token_ids and values must have the same length.

Emits a TransferBatch event.

update_with_acceptance_check(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data: Span<felt252>)

internal

#

Version of update that performs the token acceptance check by calling onERC1155Received or onERC1155BatchReceived in the receiver if it implements IERC1155Receiver, otherwise by checking if it is an account.

Requirements:

  • to is either an account contract or supports the IERC1155Receiver interface.
  • token_ids and values must have the same length.

Emits a TransferSingle event if the arrays contain one element, and TransferBatch otherwise.

update(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>)

internal

#

Transfers a value amount of tokens of type id from from to to. Will mint (or burn) if from (or to) is the zero address.

Requirements:

  • token_ids and values must have the same length.

Emits a TransferSingle event if the arrays contain one element, and TransferBatch otherwise.

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

The ERC1155 acceptance check is not performed in this function. See update_with_acceptance_check instead.

_set_base_uri(ref self: ContractState, base_uri: ByteArray)

internal

#

Sets a new URI for all token types, by relying on the token type ID substitution mechanism specified in the EIP.

By this mechanism, any occurrence of the id substring in either the URI or any of the values in the JSON file at said URI will be replaced by clients with the token type ID.

For example, the https://token-cdn-domain/\id\.json URI would be interpreted by clients as https://token-cdn-domain/000000000000...000000000000004cce0.json for token type ID 0x4cce0.

Because these URIs cannot be meaningfully represented by the URI event, this function emits no events.

Events

TransferSingle(operator: ContractAddress, from: ContractAddress, to: ContractAddress, id: u256, value: u256)

event

#

See IERC1155::TransferSingle.

TransferBatch(operator: ContractAddress, from: ContractAddress, to: ContractAddress, ids: Span<u256>, values: Span<u256>)

event

#

See IERC1155::TransferBatch.

ApprovalForAll(owner: ContractAddress, operator: ContractAddress, approved: bool)

event

#

See IERC1155::ApprovalForAll.

URI(value: ByteArray, id: u256)

event

#

See IERC1155::URI.

ERC1155ReceiverComponent

GitHub icon
use openzeppelin_token::erc1155::ERC1155ReceiverComponent;

ERC1155Receiver component implementing IERC1155Receiver.

Implementing SRC5Component is a requirement for this component to be implemented.

Embeddable Mixin Implementations

ERC1155MixinImpl

Embeddable Implementations

ERC1155ReceiverImpl

ERC1155ReceiverCamelImpl

Internal Functions

InternalImpl

Embeddable functions

on_erc1155_received(self: @ContractState, operator: ContractAddress, from: ContractAddress, token_id: u256, value: u256, data Span<felt252>) -> felt252

external

#

Returns the IERC1155Receiver interface ID.

on_erc1155_batch_received(self: @ContractState, operator: ContractAddress, from: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data Span<felt252>) -> felt252

external

#

Returns the IERC1155Receiver interface ID.

onERC1155Received(self: @ContractState, operator: ContractAddress, from: ContractAddress, tokenId: u256, value: u256, data Span<felt252>) -> felt252

external

#

See ERC1155ReceiverComponent::on_erc1155_received.

onERC1155BatchReceived(self: @ContractState, operator: ContractAddress, from: ContractAddress, tokenIds: Span<u256>, values: Span<u256>, data Span<felt252>) -> felt252

external

#

See ERC1155ReceiverComponent::on_erc1155_batch_received.

Internal functions

initializer(ref self: ContractState)

internal

#

Registers the IERC1155Receiver interface ID as supported through introspection.

Extensions

ERC1155SupplyComponent

GitHub icon
use openzeppelin_token::erc1155::ERC1155SupplyComponent;

Extension that tracks total supply per token ID and across all token IDs.

The implementing contract must forward every ERC1155HooksTrait::after_update call to ERC1155SupplyComponent::after_update. Adding this component in an upgrade to a contract with an existing token supply leaves the new counters inconsistent and is not supported.

Embeddable Implementations

Internal Implementations

Storage

ERC1155Supply_total_supply: Map<u256, u256>

storage

#

Supply tracked for each token ID.

ERC1155Supply_total_supply_all: u256

storage

#

Aggregate supply across all token IDs.

ERC1155SupplyImpl

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

external

#

Returns the total supply of token_id.

total_supply_all(self: @ContractState) → u256

external

#

Returns the aggregate supply across all token IDs.

exists(self: @ContractState, token_id: u256) → bool

external

#

Returns whether the total supply of token_id is greater than zero.

InternalImpl

after_update(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>)

internal

#

Updates per-ID and aggregate counters after an ERC1155 operation. A zero from address increases supply for every token_ids/values pair; a zero to address decreases it.

Call this function from the implementing contract's ERC1155HooksTrait::after_update hook after every transfer, mint, or burn.

ERC1155URIStorageComponent

GitHub icon
use openzeppelin_token::erc1155::ERC1155URIStorageComponent;

Extension that supports token-specific URI suffixes. Use its ERC1155URIStorageImpl as the contract's ERC1155TokenURITrait implementation instead of ERC1155TokenURIDefaultImpl.

Implementations

Internal Implementations

Storage

ERC1155URIStorage_base_uri: ByteArray

storage

#

Base URI prepended to token-specific URI suffixes.

ERC1155URIStorage_token_uris: Map<u256, ByteArray>

storage

#

Token-specific URI suffixes keyed by token ID.

ERC1155URIStorageImpl

uri(self: @ERC1155Component::ComponentState, token_id: u256) → ByteArray

impl

#

Returns the URI for token_id. When a token-specific suffix is set, the result is the extension's base URI concatenated with that suffix. Otherwise, it returns the base URI stored by ERC1155Component.

InternalImpl

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

internal

#

Stores token_uri as the token-specific suffix for token_id and emits the core URI event with the resolved URI.

set_base_uri(ref self: ContractState, base_uri: ByteArray)

internal

#

Sets the base URI used when a token-specific suffix is present. This function emits no event.

Presets

ERC1155Upgradeable

GitHub icon
use openzeppelin_presets::ERC1155;

Upgradeable ERC1155 contract leveraging ERC1155Component.

Sierra class hash

0x075829cba5eea49a998988967e6a97de68824830118f7f008f3ac07d407cb99a

Constructor

Embedded Implementations

ERC1155Component

OwnableMixinImpl

External Functions

Constructor

constructor(ref self: ContractState, base_uri: ByteArray, recipient: ContractAddress, token_ids: Span<u256>, values: Span<u256>, owner: ContractAddress)

constructor

#

Sets the base_uri for all tokens and registers the supported interfaces. Mints the values for token_ids tokens to recipient. Assigns owner as the contract owner with permissions to upgrade.

Requirements:

  • to is either an account contract (supporting ISRC6) or supports the IERC1155Receiver interface.
  • token_ids and values must have the same length.

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.

On this page

InterfacesIERC1155IERC1155MetadataURIIERC1155ReceiverIERC1155SupplyCoreERC1155ComponentERC1155ReceiverComponentExtensionsERC1155SupplyComponentERC1155URIStorageComponentPresetsERC1155Upgradeable