onERC1155BatchReceived

The onERC1155BatchReceived function is a mandatory callback defined by the ERC-1155 Multi Token Standard (EIP-1155). Its primary purpose is to notify a recipient contract that it has received a batch of one or more token types and amounts via a safe transfer. This function must return a magic value (0xbc197c81) to confirm the transaction was accepted, preventing tokens from being permanently locked in non-compliant contracts.

The function has a specific signature that includes all data necessary to process a complex batch transfer:

• operator: The address initiating the transfer (msg.sender).
• from: The address sending the tokens.
• ids: An array of token IDs being transferred.
• values: An array of corresponding token amounts.
• data: Additional calldata passed without modification. This structured data allows the receiving contract to atomically update its internal state for multiple asset types in a single transaction.

This function is part of the safe transfer family (safeBatchTransferFrom). If a transfer is made to a contract address, the ERC-1155 standard requires the caller to check that the recipient implements this function. The recipient must return the predefined 4-byte magic value bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)")) (which is 0xbc197c81). Failure to return this value causes the entire transfer to be reverted, ensuring tokens are not sent to contracts that cannot handle them.

A key advantage over ERC-721 and ERC-20 is enabling atomic batch transfers. A single call to safeBatchTransferFrom can move dozens of different token IDs and amounts. The corresponding onERC1155BatchReceived callback receives the entire batch data at once, allowing the receiving contract's logic to succeed or fail as a single unit. This is critical for complex operations like bundling NFTs with fungible resources in gaming or executing multi-asset trades in DeFi.

To be a compliant receiver, a smart contract must implement the IERC1155Receiver interface, which defines both onERC1155Received and onERC1155BatchReceived. Contracts typically inherit from helper libraries like OpenZeppelin's ERC1155Holder, which provides a default implementation that accepts all tokens. For custom logic (e.g., validating specific token IDs), developers override this function to add their business rules before returning the magic value.

This callback enables sophisticated on-chain applications:

• Gaming Inventories: A game contract receives a batch of weapons, armor, and currency from a player's wallet in one transaction.
• NFT Marketplaces: A marketplace escrow contract accepts a bundle of NFTs and payment tokens as part of a batch listing or trade.
• DeFi Vaults: A yield vault receives multiple LP position tokens (ERC-1155) representing shares in different pools simultaneously. The batch nature significantly reduces gas costs and complexity compared to multiple individual transfers.

The function must return the 4-byte magic value 0xbc197c81. This return value is the safety check that signals to the calling contract the batch was accepted. A missing or incorrect return value will cause the entire transfer transaction to revert, protecting the sender from losing tokens to a non-receiver contract.

• Example: return bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"));

Because onERC1155BatchReceived is an external call triggered during a transfer, it is a prime vector for reentrancy attacks. The function should be protected using a reentrancy guard modifier (e.g., OpenZeppelin's nonReentrant) or the Checks-Effects-Interactions pattern before performing any subsequent calls or state changes.

• Critical: Apply the guard even if logic seems simple, as the callback context is inherently untrusted.

The function parameters provide context for the transfer. The operator is the address that initiated the batch transfer (which could be the token owner or an approved operator). The from address is the sender (address(0) for mints). The data field contains optional extra information from the sender.

• Best Practice: Validate that the operator is a trusted contract or the expected ERC1155 token contract to prevent spoofed callbacks.
• Data Handling: Securely decode and validate any data payload to avoid unexpected behavior.

The function receives arrays of ids and values. Your logic must handle the entire batch atomically—either all tokens are accepted, or the function should revert. Design state updates to be idempotent where possible, ensuring that being called twice with the same batch data does not double-count or duplicate state changes, which is a common flaw in airdrop or staking mechanics.

Your contract must explicitly implement the IERC1155Receiver interface via the supportsInterface function. This is checked by compliant ERC1155 contracts before transfer via ERC1155Holder or ERC1155Receiver. Failure to properly declare support will cause safe transfers to be rejected.

• Implementation: function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) { return interfaceId == type(IERC1155Receiver).interfaceId || super.supportsInterface(interfaceId); }

Rigorously test onERC1155BatchReceived with edge cases: empty arrays, extremely large batches, reentrant calls, and malformed data. Use fuzzing tests (e.g., with Foundry) to discover unexpected state combinations. Employ static analysis tools like Slither or MythX to automatically detect common vulnerabilities such as missing return values or reentrancy in the callback logic.

The onERC1155BatchReceived function is a mandatory callback invoked on a recipient contract when it receives a batch of ERC-1155 tokens via safeBatchTransferFrom. Its signature is: function onERC1155BatchReceived(address operator, address from, uint256[] calldata ids, uint256[] calldata values, bytes calldata data) external returns (bytes4).

• Purpose: It allows the receiving contract to react to the transfer, such as updating internal balances or logic.
• Return Value: Must return the function's selector 0xbc197c81 to confirm successful handling.

NFT marketplaces use this function to enable batch purchases and bundle listings.

• Example: A user buys 5 different NFTs in a single transaction. The marketplace contract receives the batch, and onERC1155BatchReceived triggers internal logic to list each item for sale or credit the user's account.
• Gas Efficiency: This is significantly more gas-efficient than processing 5 separate safeTransferFrom calls, as it consolidates state updates and event emissions.

Game contracts implement this function to manage player inventories that contain multiple item types (ERC-1155 tokens).

• Mechanism: When a player opens a loot box or completes a quest rewarding multiple items, the game's reward contract calls safeBatchTransferFrom to the player's inventory contract.
• Inventory Update: The player's contract uses onERC1155BatchReceived to automatically add all the new weapon, armor, and currency tokens to their in-game balance in a single, atomic operation.

DeFi protocols use this for batch staking of multiple LP (Liquidity Provider) position NFTs or reward tokens.

• Process: A user can stake 10 different LP position NFTs (each an ERC-1155) into a farm in one transaction.
• Callback Action: The farm's staking contract, upon receiving the batch, uses onERC1155BatchReceived to validate and record the stake for each token ID, then starts accruing rewards for the user.

Improper implementation can lead to locked funds or reentrancy attacks.

• Magic Value: Failing to return 0xbc197c81 will cause the entire batch transfer to be reverted.
• Reentrancy: The function is called during the transfer. Calling back (reentering) into the sending contract before updating internal state is dangerous.
• Best Practice: Follow the checks-effects-interactions pattern within the callback, or use reentrancy guards if calling external contracts.

The IERC1155Receiver interface is the contract interface that must be implemented by any contract that wishes to accept safe transfers of ERC-1155 tokens. It defines two required functions:

• onERC1155Received: For single token transfers.
• onERC1155BatchReceived: For batch token transfers. A successful call must return the function's predefined magic value (0xbc197c81 for batch) to confirm the contract is prepared to hold the tokens.

ERC-1155 has two transfer methods:

• safeTransferFrom / safeBatchTransferFrom: These functions check if the recipient is a contract. If it is, they call onERC1155Received or onERC1155BatchReceived. This prevents tokens from being permanently locked in a contract that doesn't know how to handle them.
• transferFrom: A 'regular' transfer that does not perform this check. It is generally unsafe to use when sending to unknown contract addresses.

onERC721Received is the analogous function in the ERC-721 (Non-Fungible Token) standard. It serves the same purpose—allowing a contract to signal it can accept an NFT—but is designed for single, non-fungible assets. Comparing it to onERC1155BatchReceived highlights the efficiency of ERC-1155's batch design for managing collections or game item inventories.

Implementing receiver hooks like onERC1155BatchReceived introduces reentrancy risks. A malicious contract could call back into the sending function before the initial transfer is finalized. Using a reentrancy guard (e.g., OpenZeppelin's ReentrancyGuard modifier) is a critical security practice to prevent such attacks during the execution of these callback functions.

A magic return value is a predefined 4-byte function selector used to confirm successful execution of a hook. For onERC1155BatchReceived, the required return value is bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)")), which is 0xbc197c81. Returning this value is a mandatory check that proves the receiving contract is aware of the ERC-1155 standard.