Receiver Hook

The primary function is the tokensReceived hook, defined in the IERC777Recipient or IERC1155Receiver interface. When tokens are sent to a contract implementing this interface, the token contract's transfer function calls tokensReceived on the recipient, passing details of the transaction.

• Automatic Execution: Logic runs atomically within the same transaction as the transfer.
• Context Data: Receives the sender's address, recipient's address, token amount, and optional user data (data and operatorData fields).
• Atomic Composability: Ensures the recipient's intended action (e.g., minting an NFT, swapping tokens) either completes fully or the entire transfer is reverted.

Receiver Hooks solve a critical UX and security flaw in the ERC-20 standard. With ERC-20:

• Two-Step Process: A contract must first be approved to spend a user's tokens, then call transferFrom.
• Funds Locked Risk: Tokens sent directly to a non-upgraded contract are permanently lost, as the contract has no way to react.

With ERC-777/ERC-1155 Hooks:

• One-Step Process: A user can send tokens directly; the recipient contract's logic executes immediately.
• No Lost Funds: The hook can reject the transaction if the contract is not prepared to handle it, refunding the sender.

Hooks enable complex, trust-minimized interactions by making contracts reactive.

• DeFi Vaults & Yield Strategies: Automatically stake received tokens into a farming protocol.
• NFT Marketplaces: Mint an NFT automatically upon receipt of payment in a single transaction.
• Subscription Services: Grant access or extend a membership period when a periodic payment is received.
• Batch Operations (ERC-1155): Handle the receipt of multiple token types (fungible and non-fungible) in a single batch transfer, with logic for each.

While powerful, hooks introduce new security vectors that must be managed.

• Reentrancy Guard: The hook is called during the transfer; the token contract is temporarily in control of the recipient's execution. Recipient contracts must use reentrancy guards (like OpenZeppelin's) to prevent malicious token contracts from re-entering the hook.
• Hook Gas Limits: The token contract must ensure the call to tokensReceived has a sufficient gas stipend, or the transfer may fail.
• Trust in Token Contract: The recipient must trust the token contract's implementation to call the hook correctly and not maliciously.

A compliant recipient contract must implement the interface and function.

solidityCopy
interface IERC777Recipient {
    function tokensReceived(
        address operator,
        address from,
        address to,
        uint256 amount,
        bytes calldata userData,
        bytes calldata operatorData
    ) external;
}

The implementing contract overrides this function. It can:

• Revert: To reject the transfer (e.g., invalid userData).
• Execute Logic: Swap tokens, mint an asset, update internal accounting.
• Emit Events: For off-chain tracking of the automated action.

ERC-1363 is a separate standard that builds upon ERC-20 to add similar hook functionality. It defines transferAndCall and approveAndCall functions that, upon transfer, execute a function on the recipient contract.

• Key Difference: While ERC-777 hooks are called automatically on any transfer, ERC-1363 requires the sender to explicitly choose a transferAndCall method, specifying the target function.
• Backward Compatibility: ERC-1363 is designed to be more easily integrated with existing ERC-20 infrastructure, acting as an extension rather than a replacement.

Projects can implement receiver hooks to deduct and route fees automatically during transfers. This is essential for revenue-generating protocols like NFT marketplaces or cross-chain bridges.

• Example: A DEX's liquidity pool token uses a hook to take a 0.05% protocol fee on every transfer, sending it to a treasury contract.
• Mechanism: The hook logic executes after the core transfer validation but before final state settlement.

Receiver hooks can enforce transfer conditions based on the state of the receiving address or external data. This enables programmable compliance for regulated assets or membership tokens.

• Use Cases:
  • KYC/AML: Verify the recipient's credentials via an oracle before allowing the transfer to complete.
  • Vesting: Enforce lock-up schedules for team or investor tokens on transfer.
• Key Feature: Allows for reverting transfers that do not meet predefined conditions.

In cross-chain messaging protocols, a receiver hook on the destination chain is the execution endpoint for a bridged asset transfer. It mints wrapped tokens or releases native assets upon verification of the source chain proof.

• Flow: A bridge relayer calls the token contract's receiver hook with a validity proof after detecting a burn/lock on the source chain.
• Security Critical: The hook must rigorously validate the cross-chain message to prevent unauthorized minting.

For tokenized real-world assets like treasury bills or real estate, receiver hooks can trigger off-chain settlement processes and update registries upon transfer of ownership.

• Example: Transferring a tokenized bond might trigger the hook to notify a custodian's API to update the legal beneficiary record.
• Architecture: Often involves a trusted oracle or verifiable credential system to connect on-chain transfers to off-chain legal events.

The primary risk for a receiver hook is reentrancy, where a malicious contract exploits the callback to re-enter the calling function before its state is finalized. This can drain funds or corrupt logic.

• Classic Pattern: A hook makes a recursive call back to the original transfer or mint function.
• Mitigation: Use Checks-Effects-Interactions pattern or a reentrancy guard (e.g., OpenZeppelin's ReentrancyGuard) to lock the state during the hook execution.

The calling contract must provide gas for the hook's execution, which can be exploited for Denial-of-Service (DoS).

• Attack Vector: A malicious hook implements an infinite loop or complex computation, causing the original transaction to run out of gas and revert.
• Mitigation: Implement a gas limit for the hook call or use low-level call with a specified gas stipend, though this can lead to failed hooks.

Hooks execute arbitrary code, which can alter the state assumptions of the calling contract in ways the developer did not anticipate.

• Example: A hook could change the balance of a critical address, manipulate approval amounts, or call other system functions.
• Implication: Contract logic must be robust against all possible state changes during the hook, not just the intended ones. Avoid making state assumptions after a hook call.

Receiver hooks that perform on-chain actions like swaps or liquidity provision are vulnerable to Maximal Extractable Value (MEV) exploitation.

• Mechanism: A searcher can front-run the transaction containing the hook, manipulate market prices, and back-run to profit, at the expense of the hook executor.
• Impact: Results in worse execution prices (slippage) for users. This is a systemic risk for any hook that interacts with AMMs or lending markets.

Contracts implementing hooks often must trust the logic of the receiving contract. This creates a trust surface that can be compromised.

• Risk: If a popular wallet or vault contract with a hook is upgraded maliciously or hacked, all tokens that call it become vulnerable.
• Consideration: Hooks can lead to centralization risks, as protocols may whitelist only a few "trusted" hook implementations to mitigate risk.

To mitigate these risks, developers should adhere to strict security patterns:

• Use Established Standards: Implement widely-audited interfaces like ERC-777's tokensReceived or ERC-1155's onERC1155Received.
• Minimize Hook Scope: Restrict what the hook is allowed to do; avoid granting approval or transfer capabilities within the hook context.
• Thorough Testing & Auditing: Use fuzzing (e.g., with Foundry) and static analysis to test hook interactions under adversarial conditions. Always audit hook logic.

Receiver hooks introduce significant reentrancy risks if not implemented carefully. The external call to the hook function can be exploited by a malicious contract to re-enter the token contract before state updates (like balances) are finalized.

• Mitigation: Follow the Checks-Effects-Interactions pattern. Update all internal state (balances) before making the external call to the hook.
• This is a critical security consideration highlighted in audits of hook-enabled standards.

A key design decision for hooks is the behavior when a recipient is not a contract or lacks the hook function.

• ERC-777 and ERC-1155 use ERC165 for interface detection. If a contract doesn't implement the hook, the transfer proceeds normally—this is a safe fallback.
• Gas overhead: The extra STATICCALL to check for interface support and execute the hook adds gas cost. This is a trade-off for increased functionality and must be accounted for in gas estimation.

Receiver hooks are a foundational primitive for DeFi composability. They allow tokens to programmatically interact with other protocols without manual steps.

• Example: A user transfers tokens to a lending pool; the tokensReceived hook automatically deposits them into a yield-bearing vault.
• Example: A DAO treasury receives tokens; the hook automatically creates a new governance proposal. This moves logic from the user (multiple transactions) to the contract layer (one atomic transaction).