ERC 1155

This document is better viewed at https://docs.openzeppelin.com/contracts/api/token/erc1155

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:

designation of addresses that can pause token transfers for all users (ERC1155Pausable).
destruction of own tokens (ERC1155Burnable).

This core set of contracts is designed to be unopinionated, allowing developers to access the internal functions in ERC1155 (such as [_mint](#_mint(address-account,-uint256-id,-uint256-amount,-bytes-data) *internal*)) 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`

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

Available since v3.1.

Functions

balanceOf(account, id)
balanceOfBatch(accounts, ids)
setApprovalForAll(operator, approved)
isApprovedForAll(account, operator)
safeTransferFrom(from, to, id, amount, data)
safeBatchTransferFrom(from, to, ids, amounts, data)

IERC165

supportsInterface(interfaceId)

Events

TransferSingle(operator, from, to, id, value)
TransferBatch(operator, from, to, ids, values)
ApprovalForAll(account, operator, approved)
URI(value, id)

`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

Batched version of balanceOf.

Requirements:

* accountsandids` 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 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 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 TransferSingle event.

Requirements:

to cannot be the zero address.
If the caller is not from, it must be have been approved to spend ``from`’s tokens via 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

Batched version of safeTransferFrom.

Emits a TransferBatch event.

Requirements:

* idsandamounts` must have the same length.

If to refers to a smart contract, it must implement IERC1155Receiver-onERC1155BatchReceived and return the acceptance magic value.

`TransferSingle(address operator, address from, address to, uint256 id, uint256 value) event`

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

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

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

`ApprovalForAll(address account, address operator, bool approved) event`

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

`URI(string value, uint256 id) event`

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

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

`IERC1155MetadataURI`

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

Available since v3.1.

Functions

uri(id)

IERC1155

balanceOf(account, id)
balanceOfBatch(accounts, ids)
setApprovalForAll(operator, approved)
isApprovedForAll(account, operator)
safeTransferFrom(from, to, id, amount, data)
safeBatchTransferFrom(from, to, ids, amounts, data)

IERC165

supportsInterface(interfaceId)

Events

IERC1155

TransferSingle(operator, from, to, id, value)
TransferBatch(operator, from, to, ids, values)
ApprovalForAll(account, operator, approved)
URI(value, id)

`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.

`ERC1155`

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

constructor(uri_)
uri(_)
balanceOf(account, id)
balanceOfBatch(accounts, ids)
setApprovalForAll(operator, approved)
isApprovedForAll(account, operator)
safeTransferFrom(from, to, id, amount, data)
safeBatchTransferFrom(from, to, ids, amounts, data)
_setURI(newuri)
_mint(account, id, amount, data)
_mintBatch(to, ids, amounts, data)
_burn(account, id, amount)
_burnBatch(account, ids, amounts)
_beforeTokenTransfer(operator, from, to, ids, amounts, data)

ERC165

supportsInterface(interfaceId)
_registerInterface(interfaceId)

Events

IERC1155

TransferSingle(operator, from, to, id, value)
TransferBatch(operator, from, to, ids, values)
ApprovalForAll(account, operator, approved)
URI(value, id)

`constructor(string uri_) public`

See _setURI.

`uri(uint256) → string external

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:

* accountsandids` 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.

`_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 uri.

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

`_mint(address account, uint256 id, uint256 amount, bytes data) internal`

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

Emits a TransferSingle event.

Requirements:

account cannot be the zero address.
If account refers to a smart contract, it must implement IERC1155Receiver-onERC1155Received and return the acceptance magic value.

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

Batched version of _mint.

Requirements:

* idsandamounts` must have the same length.

If to refers to a smart contract, it must implement IERC1155Receiver-onERC1155BatchReceived and return the acceptance magic value.

`_burn(address account, uint256 id, uint256 amount) internal`

Destroys amount tokens of token type id from account

Requirements:

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

`_burnBatch(address account, uint256[] ids, uint256[] amounts) internal

Batched version of _burn.

Requirements:

* idsandamounts` must have the same length.

`_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 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 idwill be transferred toto`.
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 Using Hooks.

`IERC1155Receiver`

Functions

onERC1155Received(operator, from, id, value, data)
onERC1155BatchReceived(operator, from, ids, values, data)

IERC165

supportsInterface(interfaceId)

`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. To accept the transfer, this must return bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) (i.e. 0xf23a6e61, or its own function selector). @param operator The address which initiated the transfer (i.e. msg.sender) @param from The address which previously owned the token @param id The ID of the token being transferred @param value The amount of tokens being transferred @param data Additional data with no specified format @return bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) if transfer is allowed

`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. To accept the transfer(s), this must return bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)")) (i.e. 0xbc197c81, or its own function selector). @param operator The address which initiated the batch transfer (i.e. msg.sender) @param from The address which previously owned the token @param ids An array containing ids of each token being transferred (order and length must match values array) @param values An array containing amounts of each token being transferred (order and length must match ids array) @param data Additional data with no specified format @return bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)")) if transfer is allowed

Extensions

`ERC1155Pausable`

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.

Available since v3.1.

Functions