Skip to main content

Receiver Hook Extension

The Receiver Hook Extension enables individual token accounts to enforce custom validation logic on incoming transfers through programmable hooks. Unlike the Transfer Hook Extension which operates at the mint level and affects all accounts of that mint, the Receiver Hook Extension operates at the account level, allowing each token account to optionally specify its own receiver-hook program.

Overview​

When the token program processes a transfer to an account with a configured receiver hook:

  1. The token program invokes the receiver-hook program
  2. The hook program validates the transfer details
  3. The hook program either approves or rejects the transfer

This provides flexible, per-account control over incoming transfer validation. While Transfer Hooks are configured by the mint and apply to all accounts, Receiver Hooks are configured individually by each account owner, allowing for customized validation logic at the account level.

Hook Program Capabilities​

Receiver-hook programs can inspect:

  • Source account details
  • Destination account details
  • Transfer amount
  • Optional transaction metadata

Based on these inputs, hooks can implement:

  • Badge verification checks
  • Jurisdictional controls
  • Fee collection logic
  • Analytics tracking
  • Multi-signature requirements
  • Custom compliance rules

Example Use Cases​

Badge Verification Hook​

A badge verification hook examines the verification status of the sender's badge before allowing any transfers. It performs a comprehensive check to ensure the sender's badge remains valid and has not expired. The hook only permits transfers to proceed when they originate from properly verified senders. The verification parameters can be customized based on both the badge type and the specific verifier being used.

Payment Escrow Hook​

The payment escrow hook implements a secure payment validation system by maintaining a comprehensive list of expected payments. It stores specific pairs of sender public keys and their corresponding expected payment amounts. When a transfer is initiated, the hook validates it against this predefined list of expected payments. Only transfers that exactly match these predetermined parameters are accepted. The hook also includes automatic tracking functionality to monitor payment completion status.

Analytics Hook​

An analytics hook serves as a comprehensive tracking system for monitoring inbound transfer activity. It maintains running counts of transaction frequency and actively monitors various transfer patterns. The hook stores all these usage metrics directly on-chain, creating a permanent record of transaction analytics. This data can be valuable for understanding usage patterns and monitoring account activity over time.

Implementation​

Each token account has a receiver_hook field that references the hook program's address. Account owners can:

  • Select existing hook programs
  • Deploy custom hook logic
  • Update hook program reference
  • Remove hook restrictions

Hook programs use SphereNet's cross-program invocation (CPI) capabilities to integrate with the token program securely and efficiently.

This extension enables sophisticated payment flows and compliance controls while maintaining the composability and security of the underlying token system.