ERC1155

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

For an overview of ERC1155, read our ERC1155 guide.

Core

IERC1155 

use openzeppelin_token::erc1155::interface::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 

use openzeppelin_token::erc1155::interface::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.

ERC1155Component 

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.
Hooks
Internal Functions
InternalImpl
Events
IERC1155

Hooks

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.

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.

Receiver

IERC1155Receiver 

use openzeppelin_token::erc1155::interface::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.

ERC1155ReceiverComponent 

use openzeppelin_token::erc1155::ERC1155ReceiverComponent;

ERC1155Receiver component implementing IERC1155Receiver.

Implementing SRC5Component is a requirement for this component to be implemented.
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.

Presets

ERC1155Upgradeable 

use openzeppelin_presets::ERC1155;

Upgradeable ERC1155 contract leveraging ERC1155Component.

Sierra class hash

0x032e3666516e3c138011121baaf898e372f9b23eaae313ad8a401c9b9620d5ae

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.

← ERC1155
Common →