HomeForumWebsiteImpact
GitHub Icon
OpenZeppelin ContractsPrevious Versionsv4API ReferenceToken

ERC1155

Smart contract ERC1155 utilities and implementations

Outdated Version

You're viewing an older version (v4.x) The latest documentation is available for the current version. Click here to visit latest version.
AnthropicOpen in Claude

This set of interfaces and contracts are all related to the ERC1155 Multi Token Standard.

The EIP consists of three interfaces which fulfill different roles, found here as IERC1155, IERC1155MetadataURI and IERC1155Receiver.

ERC1155 implements the mandatory IERC1155 interface, as well as the optional extension IERC1155MetadataURI, by relying on the substitution mechanism to use the same URI for all token types, dramatically reducing gas costs.

Additionally there are multiple custom extensions, including:

This core set of contracts is designed to be unopinionated, allowing developers to access the internal functions in ERC1155 (such as _mint) and expose them as external functions in the way they prefer. On the other hand, ERC1155 Presets (such as ERC1155PresetMinterPauser) are designed using opinionated patterns to provide developers with ready to use, deployable contracts.

Core

IERC1155

IERC1155MetadataURI

ERC1155

IERC1155Receiver

ERC1155Receiver

Extensions

ERC1155Pausable

ERC1155Burnable

ERC1155Supply

ERC1155URIStorage

Presets

These contracts are preconfigured combinations of the above features. They can be used through inheritance or as models to copy and paste their source code.

ERC1155PresetMinterPauser

Utilities

ERC1155Holder

ERC1155

import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";

Implementation of the basic standard multi-token. See https://eips.ethereum.org/EIPS/eip-1155 Originally based on code by Enjin: https://github.com/enjin/erc-1155

Available since v3.1.

Functions

IERC1155MetadataURI

IERC1155

ERC165

IERC165

Events

IERC1155MetadataURI

IERC1155

ERC165

IERC165

constructor(string uri_)

public

#

See ERC1155._setURI.

supportsInterface(bytes4 interfaceId) → bool

public

#

See IERC165.supportsInterface.

uri(uint256) → string

public

#

See IERC1155MetadataURI.uri.

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

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

balanceOf(address account, uint256 id) → uint256

public

#

See IERC1155.balanceOf.

Requirements:

  • account cannot be the zero address.

balanceOfBatch(address[] accounts, uint256[] ids) → uint256[]

public

#

See IERC1155.balanceOfBatch.

Requirements:

  • accounts and ids must have the same length.

setApprovalForAll(address operator, bool approved)

public

#

See IERC1155.setApprovalForAll.

isApprovedForAll(address account, address operator) → bool

public

#

See IERC1155.isApprovedForAll.

safeTransferFrom(address from, address to, uint256 id, uint256 amount, bytes data)

public

#

See IERC1155.safeTransferFrom.

safeBatchTransferFrom(address from, address to, uint256[] ids, uint256[] amounts, bytes data)

public

#

See IERC1155.safeBatchTransferFrom.

_safeTransferFrom(address from, address to, uint256 id, uint256 amount, bytes data)

internal

#

Transfers amount tokens of token type id from from to to.

Emits a IERC1155.TransferSingle event.

Requirements:

  • to cannot be the zero address.
  • from must have a balance of tokens of type id of at least amount.
  • If to refers to a smart contract, it must implement IERC1155Receiver.onERC1155Received and return the acceptance magic value.

_safeBatchTransferFrom(address from, address to, uint256[] ids, uint256[] amounts, bytes data)

internal

#

xref:ROOT:erc1155#batch-operations[Batched] version of ERC1155._safeTransferFrom.

Emits a IERC1155.TransferBatch event.

Requirements:

_setURI(string newuri)

internal

#

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

By this mechanism, any occurrence of the \{id\} substring in either the URI or any of the amounts 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/000000000000000000000000000000000000000000000000000000000004cce0.json for token type ID 0x4cce0.

See ERC1155.uri.

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

_mint(address to, uint256 id, uint256 amount, bytes data)

internal

#

Creates amount tokens of token type id, and assigns them to to.

Emits a IERC1155.TransferSingle event.

Requirements:

_mintBatch(address to, uint256[] ids, uint256[] amounts, bytes data)

internal

#

xref:ROOT:erc1155#batch-operations[Batched] version of ERC1155._mint.

Emits a IERC1155.TransferBatch event.

Requirements:

_burn(address from, uint256 id, uint256 amount)

internal

#

Destroys amount tokens of token type id from from

Emits a IERC1155.TransferSingle event.

Requirements:

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

_burnBatch(address from, uint256[] ids, uint256[] amounts)

internal

#

xref:ROOT:erc1155#batch-operations[Batched] version of ERC1155._burn.

Emits a IERC1155.TransferBatch event.

Requirements:

  • ids and amounts must have the same length.

_setApprovalForAll(address owner, address operator, bool approved)

internal

#

Approve operator to operate on all of owner tokens

Emits an IERC1155.ApprovalForAll event.

_beforeTokenTransfer(address operator, address from, address to, uint256[] ids, uint256[] amounts, bytes data)

internal

#

Hook that is called before any token transfer. This includes minting and burning, as well as batched variants.

The same hook is called on both single and batched variants. For single transfers, the length of the ids and amounts arrays will be 1.

Calling conditions (for each id and amount pair):

  • When from and to are both non-zero, amount of from's tokens of token type id will be transferred to to.
  • When from is zero, amount tokens of token type id will be minted for to.
  • when to is zero, amount of from's tokens of token type id will be burned.
  • from and to are never both zero.
  • ids and amounts have the same, non-zero length.

To learn more about hooks, head to xref:ROOT:extending-contracts#using-hooks[Using Hooks].

_afterTokenTransfer(address operator, address from, address to, uint256[] ids, uint256[] amounts, bytes data)

internal

#

Hook that is called after any token transfer. This includes minting and burning, as well as batched variants.

The same hook is called on both single and batched variants. For single transfers, the length of the id and amount arrays will be 1.

Calling conditions (for each id and amount pair):

  • When from and to are both non-zero, amount of from's tokens of token type id will be transferred to to.
  • When from is zero, amount tokens of token type id will be minted for to.
  • when to is zero, amount of from's tokens of token type id will be burned.
  • from and to are never both zero.
  • ids and amounts have the same, non-zero length.

To learn more about hooks, head to xref:ROOT:extending-contracts#using-hooks[Using Hooks].

IERC1155

import "@openzeppelin/contracts/token/ERC1155/IERC1155.sol";

Required interface of an ERC1155 compliant contract, as defined in the EIP.

Available since v3.1.

Functions

IERC165

Events

IERC165

balanceOf(address account, uint256 id) → uint256

external

#

Returns the amount of tokens of token type id owned by account.

Requirements:

  • account cannot be the zero address.

balanceOfBatch(address[] accounts, uint256[] ids) → uint256[]

external

#

xref:ROOT:erc1155#batch-operations[Batched] version of ERC1155.balanceOf.

Requirements:

  • accounts and ids must have the same length.

setApprovalForAll(address operator, bool approved)

external

#

Grants or revokes permission to operator to transfer the caller's tokens, according to approved,

Emits an IERC1155.ApprovalForAll event.

Requirements:

  • operator cannot be the caller.

isApprovedForAll(address account, address operator) → bool

external

#

Returns true if operator is approved to transfer account's tokens.

See ERC1155.setApprovalForAll.

safeTransferFrom(address from, address to, uint256 id, uint256 amount, bytes data)

external

#

Transfers amount tokens of token type id from from to to.

Emits a IERC1155.TransferSingle event.

Requirements:

  • to cannot be the zero address.
  • If the caller is not from, it must have been approved to spend from's tokens via ERC1155.setApprovalForAll.
  • from must have a balance of tokens of type id of at least amount.
  • If to refers to a smart contract, it must implement IERC1155Receiver.onERC1155Received and return the acceptance magic value.

safeBatchTransferFrom(address from, address to, uint256[] ids, uint256[] amounts, bytes data)

external

#

xref:ROOT:erc1155#batch-operations[Batched] version of ERC1155.safeTransferFrom.

Emits a IERC1155.TransferBatch event.

Requirements:

TransferSingle(address indexed operator, address indexed from, address indexed to, uint256 id, uint256 value)

event

#

Emitted when value tokens of token type id are transferred from from to to by operator.

TransferBatch(address indexed operator, address indexed from, address indexed to, uint256[] ids, uint256[] values)

event

#

Equivalent to multiple IERC1155.TransferSingle events, where operator, from and to are the same for all transfers.

ApprovalForAll(address indexed account, address indexed operator, bool approved)

event

#

Emitted when account grants or revokes permission to operator to transfer their tokens, according to approved.

URI(string value, uint256 indexed id)

event

#

Emitted when the URI for token type id changes to value, if it is a non-programmatic URI.

If an IERC1155.URI event was emitted for id, the standard guarantees that value will equal the value returned by IERC1155MetadataURI.uri.

IERC1155Receiver

import "@openzeppelin/contracts/token/ERC1155/IERC1155Receiver.sol";

Available since v3.1.

Functions

IERC165

onERC1155Received(address operator, address from, uint256 id, uint256 value, bytes data) → bytes4

external

#

Handles the receipt of a single ERC1155 token type. This function is called at the end of a safeTransferFrom after the balance has been updated.

NOTE: To accept the transfer, this must return bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) (i.e. 0xf23a6e61, or its own function selector).

onERC1155BatchReceived(address operator, address from, uint256[] ids, uint256[] values, bytes data) → bytes4

external

#

Handles the receipt of a multiple ERC1155 token types. This function is called at the end of a safeBatchTransferFrom after the balances have been updated.

NOTE: To accept the transfer(s), this must return bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)")) (i.e. 0xbc197c81, or its own function selector).

ERC1155Burnable

import "@openzeppelin/contracts/token/ERC1155/extensions/ERC1155Burnable.sol";

Extension of ERC1155 that allows token holders to destroy both their own tokens and those that they have been approved to use.

Available since v3.1.

Functions

ERC1155

IERC1155MetadataURI

IERC1155

ERC165

IERC165

Events

ERC1155

IERC1155MetadataURI

IERC1155

ERC165

IERC165

burn(address account, uint256 id, uint256 value)

public

#

burnBatch(address account, uint256[] ids, uint256[] values)

public

#

ERC1155Pausable

import "@openzeppelin/contracts/token/ERC1155/extensions/ERC1155Pausable.sol";

ERC1155 token with pausable token transfers, minting and burning.

Useful for scenarios such as preventing trades until the end of an evaluation period, or having an emergency switch for freezing all token transfers in the event of a large bug.

This contract does not include public pause and unpause functions. In addition to inheriting this contract, you must define both functions, invoking the Pausable._pause and Pausable._unpause internal functions, with appropriate access control, e.g. using AccessControl or Ownable. Not doing so will make the contract unpausable.

Available since v3.1.

Functions

Pausable

ERC1155

IERC1155MetadataURI

IERC1155

ERC165

IERC165

Events

Pausable

ERC1155

IERC1155MetadataURI

IERC1155

ERC165

IERC165

_beforeTokenTransfer(address operator, address from, address to, uint256[] ids, uint256[] amounts, bytes data)

internal

#

See ERC1155._beforeTokenTransfer.

Requirements:

  • the contract must not be paused.

ERC1155Supply

import "@openzeppelin/contracts/token/ERC1155/extensions/ERC1155Supply.sol";

Extension of ERC1155 that adds tracking of total supply per id.

Useful for scenarios where Fungible and Non-fungible tokens have to be clearly identified. Note: While a totalSupply of 1 might mean the corresponding is an NFT, there is no guarantees that no other token with the same id are not going to be minted.

Functions

ERC1155

IERC1155MetadataURI

IERC1155

ERC165

IERC165

Events

ERC1155

IERC1155MetadataURI

IERC1155

ERC165

IERC165

totalSupply(uint256 id) → uint256

public

#

Total amount of tokens in with a given id.

exists(uint256 id) → bool

public

#

Indicates whether any token exist with a given id, or not.

_beforeTokenTransfer(address operator, address from, address to, uint256[] ids, uint256[] amounts, bytes data)

internal

#

See ERC1155._beforeTokenTransfer.

ERC1155URIStorage

import "@openzeppelin/contracts/token/ERC1155/extensions/ERC1155URIStorage.sol";

ERC1155 token with storage based token URI management. Inspired by the ERC721URIStorage extension

Available since v4.6.

Functions

ERC1155

IERC1155MetadataURI

IERC1155

ERC165

IERC165

Events

ERC1155

IERC1155MetadataURI

IERC1155

ERC165

IERC165

uri(uint256 tokenId) → string

public

#

See IERC1155MetadataURI.uri.

This implementation returns the concatenation of the _baseURI and the token-specific uri if the latter is set

This enables the following behaviors:

  • if _tokenURIs[tokenId] is set, then the result is the concatenation of _baseURI and _tokenURIs[tokenId] (keep in mind that _baseURI is empty per default);

  • if _tokenURIs[tokenId] is NOT set then we fallback to super.uri() which in most cases will contain ERC1155._uri;

  • if _tokenURIs[tokenId] is NOT set, and if the parents do not have a uri value set, then the result is empty.

_setURI(uint256 tokenId, string tokenURI)

internal

#

Sets tokenURI as the tokenURI of tokenId.

_setBaseURI(string baseURI)

internal

#

Sets baseURI as the _baseURI for all tokens

IERC1155MetadataURI

import "@openzeppelin/contracts/token/ERC1155/extensions/IERC1155MetadataURI.sol";

Interface of the optional ERC1155MetadataExtension interface, as defined in the EIP.

Available since v3.1.

Functions

IERC1155

IERC165

Events

IERC1155

IERC165

uri(uint256 id) → string

external

#

Returns the URI for token type id.

If the \{id\} substring is present in the URI, it must be replaced by clients with the actual token type ID.

ERC1155PresetMinterPauser

import "@openzeppelin/contracts/token/ERC1155/presets/ERC1155PresetMinterPauser.sol";

ERC1155 token, including:

  • ability for holders to burn (destroy) their tokens
  • a minter role that allows for token minting (creation)
  • a pauser role that allows to stop all token transfers

This contract uses AccessControl to lock permissioned functions using the different roles - head to its documentation for details.

The account that deploys the contract will be granted the minter and pauser roles, as well as the default admin role, which will let it grant both minter and pauser roles to other accounts.

Deprecated in favor of Contracts Wizard.

Functions

ERC1155Pausable

Pausable

ERC1155Burnable

ERC1155

IERC1155MetadataURI

IERC1155

AccessControlEnumerable

AccessControl

ERC165

IERC165

IAccessControlEnumerable

IAccessControl

Events

ERC1155Pausable

Pausable

ERC1155Burnable

ERC1155

IERC1155MetadataURI

IERC1155

AccessControlEnumerable

AccessControl

ERC165

IERC165

IAccessControlEnumerable

IAccessControl

constructor(string uri)

public

#

Grants DEFAULT_ADMIN_ROLE, MINTER_ROLE, and PAUSER_ROLE to the account that deploys the contract.

mint(address to, uint256 id, uint256 amount, bytes data)

public

#

Creates amount new tokens for to, of token type id.

See ERC1155._mint.

Requirements:

  • the caller must have the MINTER_ROLE.

mintBatch(address to, uint256[] ids, uint256[] amounts, bytes data)

public

#

xref:ROOT:erc1155#batch-operations[Batched] variant of IERC4626.mint.

pause()

public

#

Pauses all token transfers.

See ERC1155Pausable and Pausable._pause.

Requirements:

  • the caller must have the PAUSER_ROLE.

unpause()

public

#

Unpauses all token transfers.

See ERC1155Pausable and Pausable._unpause.

Requirements:

  • the caller must have the PAUSER_ROLE.

supportsInterface(bytes4 interfaceId) → bool

public

#

See IERC165.supportsInterface.

_beforeTokenTransfer(address operator, address from, address to, uint256[] ids, uint256[] amounts, bytes data)

internal

#

MINTER_ROLE() → bytes32

public

#

PAUSER_ROLE() → bytes32

public

#

ERC1155Holder

import "@openzeppelin/contracts/token/ERC1155/utils/ERC1155Holder.sol";

Available since v3.1.

Functions

ERC1155Receiver

IERC1155Receiver

ERC165

IERC165

onERC1155Received(address, address, uint256, uint256, bytes) → bytes4

public

#

onERC1155BatchReceived(address, address, uint256[], uint256[], bytes) → bytes4

public

#

ERC1155Receiver

import "@openzeppelin/contracts/token/ERC1155/utils/ERC1155Receiver.sol";

Available since v3.1.

Functions

IERC1155Receiver

ERC165

IERC165

supportsInterface(bytes4 interfaceId) → bool

public

#

See IERC165.supportsInterface.

On this page

CoreExtensionsPresetsUtilitiesERC1155IERC1155MetadataURIIERC1155ERC165IERC165IERC1155MetadataURIIERC1155ERC165IERC165IERC1155IERC165IERC165IERC1155ReceiverIERC165ERC1155BurnableERC1155IERC1155MetadataURIIERC1155ERC165IERC165ERC1155IERC1155MetadataURIIERC1155ERC165IERC165ERC1155PausablePausableERC1155IERC1155MetadataURIIERC1155ERC165IERC165PausableERC1155IERC1155MetadataURIIERC1155ERC165IERC165ERC1155SupplyERC1155IERC1155MetadataURIIERC1155ERC165IERC165ERC1155IERC1155MetadataURIIERC1155ERC165IERC165ERC1155URIStorageERC1155IERC1155MetadataURIIERC1155ERC165IERC165ERC1155IERC1155MetadataURIIERC1155ERC165IERC165IERC1155MetadataURIIERC1155IERC165IERC1155IERC165ERC1155PresetMinterPauserERC1155PausablePausableERC1155BurnableERC1155IERC1155MetadataURIIERC1155AccessControlEnumerableAccessControlERC165IERC165IAccessControlEnumerableIAccessControlERC1155PausablePausableERC1155BurnableERC1155IERC1155MetadataURIIERC1155AccessControlEnumerableAccessControlERC165IERC165IAccessControlEnumerableIAccessControlERC1155HolderERC1155ReceiverIERC1155ReceiverERC165IERC165ERC1155ReceiverIERC1155ReceiverERC165IERC165