# Meta-Hook Router

The Meta-Hook Router is a Token-2022 Transfer Hook multiplexer. It solves a fundamental limitation: Token-2022 allows only **one** transfer hook per mint. The Meta-Hook Router sits in that single slot and dispatches to up to 8 sub-hooks — both native Solana programs and Solidity contracts on Rome EVM.

## The Problem

Token-2022 Transfer Hooks are powerful — they fire on every `transfer_checked` call, enabling compliance, royalties, analytics, and more. But each mint gets exactly one hook program. If a stablecoin issuer needs KYC checks AND sanctions screening AND royalty enforcement, they can't use three separate hook programs.

## The Solution

The Meta-Hook Router registers as the mint's single transfer hook, then dispatches to multiple sub-hooks in priority order:

```
SPL Transfer (Jupiter, Raydium, wallet)
    ↓
Token-2022 transfer_checked
    ↓
Meta-Hook Router (single hook slot)
    ├── Sub-Hook 1: KYC Compliance (Solidity on Rome EVM)
    ├── Sub-Hook 2: Sanctions Check (Solidity on Rome EVM)
    ├── Sub-Hook 3: Transfer Analytics (Native Solana program)
    └── Sub-Hook 4: Royalty Enforcement (Solidity on Rome EVM)
    ↓
First failure stops all — transfer reverts
```

## Key Properties

**Multi-Hook Dispatch** — Up to 8 sub-hooks per mint, dispatched sequentially in priority order.

**Native + EVM Sub-Hooks** — Mix native Solana programs and Solidity contracts in one dispatch chain.

**First-Failure-Stops-All** — If any sub-hook rejects the transfer, the entire transfer reverts. This ensures compliance can't be bypassed.

**ExtraAccountMetaList Aggregation** — The router concatenates extra account metadata from all sub-hooks so Token-2022 can pass the right accounts to each.

**Admin Instructions** — `registerSubHook`, `removeSubHook`, `reorderSubHooks`, `pauseSubHook` — full lifecycle management.

**Single-State Mode Only** — Transfer hooks execute inside Solana transactions. OP-Geth is unreachable from that context, so all EVM sub-hooks must use the single-state (proxy) mode.

## Architecture

### Two-Layer Compliance

The Meta-Hook Router enables compliance at two layers:

**SPL Layer (Solana)** — The router fires on every `transfer_checked` call. When someone swaps a compliant token on Jupiter, sends it from Phantom, or interacts with any Solana DeFi protocol, the compliance hook fires.

**ERC-20 Layer (EVM)** — Inside Rome EVM, the ERC-20 wrapper contract can implement its own transfer restrictions (ERC-3643 compatible). All EVM-internal transfers are compliance-checked.

**Bridge Layer** — The hook fires when tokens enter or exit Rome EVM. The bridge vault is whitelisted in the compliance contract to allow deposit/withdrawal.

**Shared Registry** — Both layers read from the same `KYCRegistry.sol` contract. One KYC approval covers both Solana and EVM.

### Compute Budget

| Hook Type                    | CU Cost    |
| ---------------------------- | ---------- |
| Base transfer overhead       | 100,000 CU |
| Per native sub-hook          | 50,000 CU  |
| Per EVM sub-hook             | 200,000 CU |
| Recommended for EVM transfer | 800,000 CU |

## Sub-Hook Solutions

### P0 — Ship First

**S1: KYC/Sanctions Compliance Hook** — Solidity compliance contracts as Transfer Hook handlers. Per-mint namespacing, protocol vault whitelisting (Jupiter/Kamino/Orca + Rome bridge vault), address linking for cross-chain KYC.

**S1b: ERC-20 Compliance Wrapper** — Companion to S1 for EVM-side. ERC-3643 compatible transfer restrictions on the ERC-20 representation inside Rome EVM.

**S2: Multi-Hook Multiplexer (non-EVM)** — The router itself, valuable to any Token-2022 issuer even without EVM. Solves single-hook-per-mint for the entire ecosystem.

**S3: GENIUS Act Stablecoin Compliance** — Regulatory hooks for stablecoins: sanctions, jurisdictions, reporting.

### P1 — Ship Next

**S4: Transfer Limits & Velocity Controls** — Per-transfer max, daily/weekly velocity limits, cooldown periods.

**S5: Jurisdiction-Based Transfer Rules** — Country blocklists, accredited investor checks, holding periods per jurisdiction.

**S6: Royalty Enforcement** — Non-bypassable creator royalties on every SPL transfer.

**S7: On-Chain Transfer Analytics** — Read-only hook emitting events. Free tier adoption wedge.

### P2 — Market Expansion

**S8: Permissioned L2 via Bridge Gate** — Compliance at bridge deposit/withdrawal boundaries.

**S9: Dynamic Fee Routing** — Programmable fee extraction per transfer.

**S10: Loyalty/Reward Points** — Transfer-triggered point awards.

**S11: Vesting/Lockup Enforcement** — Prevent transfers violating vesting schedules.

## Use Case: End-to-End RWA Compliance

```
Issuer (e.g., Securitize) deploys:
  1. ComplianceHook.sol on Rome EVM (KYC registry, sanctions, jurisdiction rules)
  2. Registers it as EVM sub-hook in Meta-Hook Router
  3. Mints RWA token as Token-2022 with transfer_hook = Meta-Hook Router

Solana user swaps RWA token on Jupiter:
  Jupiter calls transfer_checked
    → Token-2022 invokes Meta-Hook Router
    → Router dispatches to Rome EVM via CPI
    → ComplianceHook checks sender/recipient KYC + sanctions
    → Pass: transfer completes
    → Fail: entire transfer reverts

EVM user bridges RWA token into Rome EVM:
  SPL transfer to bridge vault
    → Hook fires (compliance check at entry)
    → ERC-20 minted inside EVM
    → ERC-20 has its own transfer restrictions (ERC-3643)
    → All EVM transfers compliance-checked at ERC-20 level
```

## Known Constraints

1. **Single-state mode only** — OP-Geth is unreachable from inside a Solana transaction
2. **transfer\_checked only** — Hooks only fire on `transfer_checked`, not plain `transfer`. Rome bridge MUST use `transfer_checked`
3. **Mint/burn not hooked** — Token-2022 hooks don't fire on mint/burn operations. Controlled via mint authority
4. **Max 8 sub-hooks** — Per-mint limit
5. **Token wrapping escape** — Users could wrap tokens to avoid hooks. Mitigated by wrapper blacklist + PermanentDelegate extension
6. **EVM address model** — Hooks see Rome-derived EVM addresses, not Ethereum addresses. SDK provides derivation utility

## Status

**In Progress** — Router core and KYC hook (S1) implementation active. 9 packages, 13 hard constraints, 24 edge cases documented.

## Related

* [Transfer Hooks](/core-concepts/transfer-hooks.md) — how Token-2022 Transfer Hooks work in Rome
* [Token Interop](/core-concepts/token-interop.md) — ERC-20 ↔ SPL token model
* [Stablecoin Issuers](/use-cases/stablecoin-issuers.md) — multi-hook compliance for stablecoins


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rome.builders/products/meta-hook-router.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.