ERC1155 Receiver

Any contract that receives ERC-1155 tokens via safeTransferFrom or safeBatchTransferFrom must implement the IERC1155Receiver interface. This is enforced by the ERC-1155 standard. The interface requires two functions:

• onERC1155Received: Called for single transfers.
• onERC1155BatchReceived: Called for batch transfers. Both must return the function selector bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) to confirm the contract can safely handle the tokens. Failure to implement this correctly will cause transfers to revert.

A primary security risk is token lockup, where tokens are sent to a contract that cannot interact with them. The receiver functions act as a callback, allowing the receiving contract to validate the transfer, update its internal accounting (e.g., mint a wrapped version), or reject it. Without this mechanism, tokens sent via safeTransfer become permanently stuck, as the sending contract has no confirmation of successful receipt. Always use safeTransferFrom when sending to unknown addresses.

The onERC1155Received callback is an external call that can be exploited for reentrancy attacks. An attacker's malicious contract could re-enter your function before your state updates are complete. Best practice is to apply reentrancy guards (e.g., OpenZeppelin's ReentrancyGuard) to any function that calls safeTransferFrom and to the receiver functions themselves. Ensure all state changes (like balance updates) occur before making the external transfer call.

Batch operations (safeBatchTransferFrom) introduce unique risks. The onERC1155BatchReceived function must handle an array of token IDs and values atomically. Security considerations include:

• Gas limits: Large batches may exceed the block gas limit, causing the entire transfer to fail.
• Partial execution: Ensure your contract logic either fully processes the entire batch or fully reverts. Inconsistent state mid-batch can be exploited.
• Validation: Rigorously check the lengths of the ids and values arrays match and that the caller is authorized.

The receiver functions should include access control checks. While the ERC-1155 standard specifies that only the token contract itself can call these functions, it is a defensive practice to verify the caller (msg.sender) is a trusted ERC-1155 contract. You can maintain a whitelist of approved token contracts or, at minimum, validate that the caller's code size is greater than zero to prevent EOA calls. This prevents spoofed callback attacks.

In-game smart contracts acting as player inventories or vaults must be ERC1155 receivers. This allows them to:

• Securely accept a player's diverse assets (weapons, skins, potions) which are each distinct ERC-1155 token IDs.
• Enable composability, where a game contract can programmatically receive and combine items to craft new ones.
• Implement rental systems where items are temporarily transferred to a player's in-game avatar contract.

Advanced DeFi protocols use ERC1155Receiver to create synthetic positions or represent staked LP tokens. For example:

• A vault accepts a user's LP token (as an ERC-1155) and mints a new, yield-bearing vault share token back to the user.
• This enables tracking of complex, multi-asset positions with a single token ID, improving capital efficiency and enabling new financial primitives like NFT-collateralized loans.

The interface defines two mandatory callback functions that enforce secure transfers:

• onERC1155Received: Called when a single token type is transferred. Must return the function selector 0xf23a6e61.
• onERC1155BatchReceived: Called for batch transfers. Must return 0xbc197c81. These callbacks prevent tokens from being permanently locked in a contract that doesn't know how to handle them, a critical security feature of the ERC-1155 standard.

The IERC1155Receiver interface is the technical standard a contract must implement to accept ERC1155 tokens. It defines two critical functions:

• onERC1155Received: Called for single token transfers.
• onERC1155BatchReceived: Called for batch transfers of multiple token types. These functions must return a predefined magic value (0xf23a6e61 or 0xbc197c81) to confirm the contract is prepared to handle the tokens, preventing them from being locked forever.

ERC1155 defines two transfer methods. safeTransferFrom and safeBatchTransferFrom check if the recipient is a contract. If it is, they call the corresponding onERC1155Received function to ensure safe acceptance. In contrast, transferFrom does not perform this check, which can lead to tokens being permanently lost if sent to an unprepared contract. Best practice is to always use the 'safe' variants.

ERC-165 is a prerequisite for ERC1155 Receivers. Before calling the receiver functions, the transferring contract uses ERC-165's supportsInterface to check if the recipient contract actually implements the IERC1155Receiver interface. This prevents calls to non-existent functions, which would cause the transaction to revert. It's a foundational standard for secure, interoperable contract interactions.

A core feature of ERC1155 is batch operations, allowing transfers and balance checks for multiple token IDs and amounts in a single transaction. The receiver's onERC1155BatchReceived function receives arrays of token IDs and corresponding amounts. This is highly gas-efficient for applications like gaming (transferring a full set of items) or marketplaces (completing multi-item trades).

ERC1155 Receivers are essential for blockchain games. A game's smart contract acts as the receiver, implementing logic in onERC1155Received to:

• Credit a player's in-game inventory.
• Trigger gameplay events upon receiving a specific item.
• Validate that received tokens are allowed game assets. This enables seamless player-to-contract and contract-to-contract item transfers.

Decentralized marketplaces use ERC1155 Receiver contracts as escrow agents. When a user lists an ERC1155 item for sale, they transfer it to the marketplace's receiver contract via safeTransferFrom. The contract holds the item in escrow until a buyer fulfills the order, at which point the receiver contract transfers it to the new owner, completing the atomic swap.