ERC-1155 Transfer Module

Manages ERC-1155 token transfers within a diamond

Key Features

• Implements safeTransferFrom and safeBatchTransferFrom adhering to EIP-1155.
• Uses diamond storage for persistent token balance management.
• Emits TransferSingle and TransferBatch events upon successful transfers.
• Includes robust error checking for invalid inputs and state conditions.

Module Usage

This module provides internal functions for use in your custom facets. Import it to access shared logic and storage.

Overview

This module implements core ERC-1155 transfer logic, enabling facets to move multiple token types between addresses. It leverages diamond storage for token balances, ensuring consistency across all facets. By adhering to EIP-1155 safe transfer requirements, it provides a secure foundation for complex token interactions within a diamond.

Storage

ERC1155Storage

ERC-8042 compliant storage struct for ERC-1155 token data. storage-location: erc8042:erc1155

Definition

struct ERC1155Storage {
  mapping(uint256 id => mapping(address account => uint256 balance)) balanceOf;
  mapping(address account => mapping(address operator => bool)) isApprovedForAll;
}

State Variables

Property	Type	Description
STORAGE_POSITION	bytes32	Diamond storage slot position for this module (Value: keccak256("erc1155"))

Functions

getStorage

Returns the ERC-1155 storage struct from the predefined diamond storage slot. Uses inline assembly to set the storage slot reference.

function getStorage() pure returns (ERC1155Storage storage s);

Returns:

Property	Type	Description
s	ERC1155Storage	The ERC-1155 storage struct reference.

---

safeBatchTransferFrom

Safely transfers multiple token types from one address to another in a single transaction. Validates ownership, approval, and receiver address before updating balances for each token type. Performs ERC1155Receiver validation if recipient is a contract (safe transfer). Complies with EIP-1155 safe transfer requirements.

function safeBatchTransferFrom(
address _from,
address _to,
uint256[] memory _ids,
uint256[] memory _values,
address _operator
) ;

Parameters:

Property	Type	Description
_from	address	The address to transfer from.
_to	address	The address to transfer to.
_ids	uint256[]	The token types to transfer.
_values	uint256[]	The amounts of tokens to transfer for each type.
_operator	address	The address initiating the transfer (may be owner or approved operator).

---

safeTransferFrom

Safely transfers a single token type from one address to another. Validates ownership, approval, and receiver address before updating balances. Performs ERC1155Receiver validation if recipient is a contract (safe transfer). Complies with EIP-1155 safe transfer requirements.

function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, address _operator) ;

Parameters:

Property	Type	Description
_from	address	The address to transfer from.
_to	address	The address to transfer to.
_id	uint256	The token type to transfer.
_value	uint256	The amount of tokens to transfer.
_operator	address	The address initiating the transfer (may be owner or approved operator).

Events

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

Signature:

event TransferBatch(
address indexed _operator, address indexed _from, address indexed _to, uint256[] _ids, uint256[] _values
);

Parameters:

Property	Type	Description
_operator	address	The address which initiated the batch transfer.
_from	address	The address which previously owned the tokens.
_to	address	The address which now owns the tokens.
_ids	uint256[]	The token types being transferred.
_values	uint256[]	The amounts of tokens transferred.

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

Signature:

event TransferSingle(
address indexed _operator, address indexed _from, address indexed _to, uint256 _id, uint256 _value
);

Parameters:

Property	Type	Description
_operator	address	The address which initiated the transfer.
_from	address	The address which previously owned the token.
_to	address	The address which now owns the token.
_id	uint256	The token type being transferred.
_value	uint256	The amount of tokens transferred.

Errors

Title: ERC-1155 Transfer Module Provides internal transfer functionality for ERC-1155 tokens. Error indicating insufficient balance for a transfer.

Signature:

error ERC1155InsufficientBalance(address _sender, uint256 _balance, uint256 _needed, uint256 _tokenId);

Error indicating array length mismatch in batch operations.

Signature:

error ERC1155InvalidArrayLength(uint256 _idsLength, uint256 _valuesLength);

Error indicating the receiver address is invalid.

Signature:

error ERC1155InvalidReceiver(address _receiver);

Error indicating the sender address is invalid.

Signature:

error ERC1155InvalidSender(address _sender);

Error indicating missing approval for an operator.

Signature:

error ERC1155MissingApprovalForAll(address _operator, address _owner);

Best Practices

Best Practice

• Ensure necessary approvals are granted using ERC1155ApproveMod before calling transfer functions.
• Verify that the _to address is a valid receiver, especially if it's a contract, to prevent unexpected behavior.
• Handle the ERC1155InsufficientBalance, ERC1155InvalidArrayLength, ERC1155InvalidReceiver, ERC1155InvalidSender, and ERC1155MissingApprovalForAll errors appropriately.

Integration Notes

Shared Storage

This module interacts with diamond storage at the slot identified by keccak256(\"erc1155\"). The getStorage() function provides direct access to the ERC1155Storage struct, which holds all token balance information. Any modifications to balances made by safeTransferFrom or safeBatchTransferFrom are immediately reflected in this shared storage, visible to all facets accessing the same storage slot.

Was this helpful?

Last updated:March 13, 2026