onERC1155Received

A marketplace contract uses onERC1155Received to safely accept tokens from users for listing. The function performs checks before allowing the deposit.

• Key Logic: Validates the _operator (the marketplace) and _from address.
• State Update: Stores the token ID, amount, and seller in an internal escrow mapping.
• Security: Returns the magic value 0xf23a6e61 only after all checks pass, preventing accidental lock-up.

In-game smart contracts act as player inventories, receiving ERC-1155 items like weapons, potions, and crafting materials.

• Batch Support: Uses onERC1155BatchReceived for equipping multiple items in one transaction.
• Game Logic Hook: The function can trigger in-game events (e.g., "item equipped") upon successful receipt.
• Access Control: Often restricts _operator to approved game logic contracts to prevent unauthorized transfers.

Lending protocols accept ERC-1155 tokens (e.g., semi-fungible LP positions) as collateral. The vault contract must implement the receiver hook.

• Collateralization: The function records the received token IDs/amounts, linking them to a user's debt position.
• Reentrancy Guard: Critical to place the external call (safeTransferFrom) before vault state updates, following Checks-Effects-Interactions pattern.
• Data Field: The _data parameter can encode loan-specific metadata for the vault.

Staking pools and yield farms accept ERC-1155 tokens to represent staked positions, enabling complex DeFi Lego.

• Receipt Token: The pool mints a new ERC-1155 or ERC-20 receipt token to the user upon receiving their assets.
• Inter-Contract Flow: Enables seamless movement of assets between compliant contracts without manual approval steps.
• Standardization: This hook is why ERC-1155 tokens work across thousands of dApps without custom integrations.

Incorrect implementation can lead to locked funds. Key mistakes to avoid:

• Missing Return Value: Failing to return 0xf23a6e61 (or 0xbc197c81 for batches) will cause transfers to revert.
• Ignoring the _data Field: This parameter is often used by sending contracts; ignoring it can break expected functionality.
• Insufficient Access Control: Not validating the _operator can allow unauthorized contracts to deposit tokens.

The most critical risk is reentrancy. The onERC1155Received hook is called during the token transfer. A malicious contract can re-enter your contract's logic before the initial transfer state is finalized.

• Classic Example: A staking contract that updates user balances after the hook call can be drained if the hook calls back into the stake function.
• Mitigation: Follow the Checks-Effects-Interactions pattern. Update all internal state (balances, totals) before making any external calls, including the token transfer that triggers the hook.

The ERC-1155 standard mandates that onERC1155Received must return a specific magic value: bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")). Failure to return this exact value will cause the entire transfer to revert.

• Common Pitfall: Forgetting the returns statement or returning an incorrect selector.
• Best Practice: Use the provided interface and the IERC1155Receiver abstract contract from OpenZeppelin, which includes the correct function signatures and return values.

The onERC1155BatchReceived hook introduces additional complexity. It must handle multiple token IDs and values in a single transaction, which amplifies risks.

• Atomicity Risk: The entire batch operation must be treated as atomic. If logic fails for one token type, the entire batch should revert to avoid partial state corruption.
• Gas & Validation: Processing arrays requires careful gas management and validation of array lengths to prevent out-of-gas errors or malformed input exploits.

The hook must validate the caller (msg.sender) is a trusted token contract. It receives an operator argument, which is the address that initiated the transfer (not necessarily the token holder).

• Spoofing Risk: Do not trust the operator or from arguments for authorization; use msg.sender to verify the calling token contract.
• Context Separation: The hook may be called outside of a user-initiated action (e.g., during a marketplace settlement). Ensure business logic accounts for this and does not make unsafe assumptions about the from address.

If your receiving contract uses a proxy pattern (e.g., UUPS or Transparent Proxy), special care is needed.

• Selector Clash: Ensure the hook function selector does not clash with the proxy's own functions (like upgradeTo).
• Storage Layout: State variables updated in the hook must remain consistent across upgrades. Changing storage layout can corrupt data when the hook is called.
• Initialization: The hook must not be callable before the contract is fully initialized, to prevent initialization exploits.

A safe transfer is a token transfer that calls the recipient's onERC1155Received or onERC1155BatchReceived hook to ensure the contract is aware and capable of handling the tokens. This prevents tokens from being permanently locked in contracts that cannot manage them. The safeTransferFrom and safeBatchTransferFrom functions enforce this check, unlike the basic transferFrom.

To confirm successful receipt, the onERC1155Received function must return a specific magic value: bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")). This 4-byte selector (0xf23a6e61) acts as a cryptographic signature, proving the contract intentionally implements the ERC-1155 token receiver interface. Returning any other value will cause the transfer to be reverted.

The onERC1155BatchReceived function is the counterpart for batch transfers. It is called by safeBatchTransferFrom and receives arrays of token IDs and amounts. It must return the magic value bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)")) (0xbc197c81). This allows contracts to efficiently process multiple asset transfers in one transaction.

IERC1155Receiver is the Solidity interface that defines the two mandatory functions a contract must implement to safely accept ERC-1155 tokens:

• onERC1155Received(address operator, address from, uint256 id, uint256 value, bytes data)
• onERC1155BatchReceived(address operator, address from, uint256[] ids, uint256[] values, bytes data) Contracts that do not implement this interface cannot receive tokens via safe transfer functions.