# Meta-Hook Router

Meta-Hook Router 是一个 Token-2022 Transfer Hook 多路复用器。它解决了一个根本性限制：Token-2022 只允许 **一个** 每个铸币地址对应一个 transfer hook。Meta-Hook Router 占据这唯一的槽位，并将请求分发给最多 8 个子 Hook——既包括原生 Solana 程序，也包括 Rome EVM 上的 Solidity 合约。

## 问题

Token-2022 Transfer Hooks 功能强大——它们会在每一次 `transfer_checked` 调用时触发，从而支持合规、版税、分析等更多能力。但每个铸币地址只能对应一个 hook 程序。如果某稳定币发行方既需要 KYC 检查，又需要制裁筛查，还需要版税执行，就无法使用三个独立的 hook 程序。

## 解决方案

Meta-Hook Router 将自己注册为该铸币地址的单一 transfer hook，然后按优先级顺序分发到多个子 Hook：

```
SPL 转账（Jupiter、Raydium、钱包）
    ↓
Token-2022 transfer_checked
    ↓
Meta-Hook Router（单一 hook 槽位）
    ├── 子 Hook 1：KYC 合规（Rome EVM 上的 Solidity）
    ├── 子 Hook 2：制裁检查（Rome EVM 上的 Solidity）
    ├── 子 Hook 3：转账分析（原生 Solana 程序）
    └── 子 Hook 4：版税执行（Rome EVM 上的 Solidity）
    ↓
首次失败即停止全部——转账回滚
```

## 关键特性

**多 Hook 分发** — 每个铸币地址最多 8 个子 Hook，按优先级顺序依次分发。

**原生 + EVM 子 Hook** — 在一条分发链中同时混合原生 Solana 程序和 Solidity 合约。

**首次失败即停止全部** — 如果任何子 Hook 拒绝该转账，整个转账将回滚。这确保合规无法被绕过。

**ExtraAccountMetaList 聚合** — 路由器会连接所有子 Hook 的额外账户元数据，以便 Token-2022 能将正确的账户传递给每个子 Hook。

**管理员指令** — `registerSubHook`, `removeSubHook`, `reorderSubHooks`, `pauseSubHook` — 完整生命周期管理。

**仅单状态模式** — Transfer Hook 在 Solana 交易内部执行。OP-Geth 无法从该上下文中访问，因此所有 EVM 子 Hook 都必须使用单状态（代理）模式。

## 架构

### 双层合规

Meta-Hook Router 可在两个层面实现合规：

**SPL 层（Solana）** — 路由器会在每次 `transfer_checked` 调用时触发。当用户在 Jupiter 上兑换合规代币、从 Phantom 发送代币，或与任何 Solana DeFi 协议交互时，合规 hook 都会被触发。

**ERC-20 层（EVM）** — 在 Rome EVM 内，ERC-20 封装合约可以实现其自身的转账限制（兼容 ERC-3643）。所有 EVM 内部转账都会经过合规检查。

**桥接层** — 当代币进入或离开 Rome EVM 时，该 hook 会触发。桥接金库在合规合约中被列入白名单，以允许存入/提取。

**共享注册表** — 两个层级都读取同一个 `KYCRegistry.sol` 合约。一次 KYC 审批同时覆盖 Solana 和 EVM。

### 计算预算

| Hook 类型       | CU 成本      |
| ------------- | ---------- |
| 基础转账开销        | 100,000 CU |
| 每个原生子 Hook    | 50,000 CU  |
| 每个 EVM 子 Hook | 200,000 CU |
| 推荐用于 EVM 转账   | 800,000 CU |

## 子 Hook 解决方案

### P0——优先发布

**S1：KYC/制裁合规 Hook** — 作为 Transfer Hook 处理器的 Solidity 合规合约。按铸币地址命名空间隔离、协议金库白名单（Jupiter/Kamino/Orca + Rome 桥接金库）、跨链 KYC 的地址关联。

**S1b：ERC-20 合规封装器** — 面向 EVM 侧的 S1 配套组件。Rome EVM 内 ERC-20 表示上的 ERC-3643 兼容转账限制。

**S2：多 Hook 复用器（非 EVM）** — 路由器本身对任何 Token-2022 发行方都有价值，即使不使用 EVM 也是如此。为整个生态系统解决每个铸币地址只能有一个 hook 的限制。

**S3：GENIUS Act 稳定币合规** — 面向稳定币的监管 hook：制裁、司法辖区、报告。

### P1——下一步发布

**S4：转账限额与速率控制** — 单笔上限、每日/每周速率限制、冷却期。

**S5：基于司法辖区的转账规则** — 国家黑名单、合格投资者检查、按司法辖区设置持有期。

**S6：版税执行** — 对每笔 SPL 转账执行不可绕过的创作者版税。

**S7：链上转账分析** — 只读 hook，输出事件。免费层采用切入点。

### P2——市场扩展

**S8：通过 Bridge Gate 的许可型 L2** — 在桥接存入/提取边界实施合规。

**S9：动态费用路由** — 按每笔转账可编程提取费用。

**S10：积分/奖励点** — 转账触发的积分发放。

**S11：归属/锁仓执行** — 阻止违反归属计划的转账。

## 用例：端到端 RWA 合规

```
发行方（例如 Securitize）部署：
  1. 在 Rome EVM 上部署 ComplianceHook.sol（KYC 注册表、制裁、司法辖区规则）
  2. 将其注册为 Meta-Hook Router 中的 EVM 子 Hook
  3. 将 RWA 代币铸造为 Token-2022，并将 transfer_hook 设为 Meta-Hook Router

Solana 用户在 Jupiter 上交换 RWA 代币：
  Jupiter 调用 transfer_checked
    → Token-2022 调用 Meta-Hook Router
    → 路由器通过 CPI 分发到 Rome EVM
    → ComplianceHook 检查发送方/接收方的 KYC + 制裁情况
    → 通过：转账完成
    → 失败：整个转账回滚

EVM 用户将 RWA 代币桥接到 Rome EVM：
  SPL 转账到桥接金库
    → Hook 触发（入口处进行合规检查）
    → 在 EVM 内部铸造 ERC-20
    → ERC-20 具备自身的转账限制（ERC-3643）
    → 所有 EVM 转账都会在 ERC-20 层面进行合规检查
```

## 已知限制

1. **仅单状态模式** — OP-Geth 无法从 Solana 交易内部访问
2. **仅 transfer\_checked** — Hook 仅在 `transfer_checked`时触发，而不是在普通 `transfer`不会触发钩子。Rome 桥接必须使用 `transfer_checked`
3. **mint/burn 不受钩子影响** — Token-2022 hooks 不会在铸造/销毁操作时触发。由 mint authority 控制
4. **最多 8 个子 Hook** — 每个铸币地址的限制
5. **代币包装规避** — 用户可能通过包装代币来规避 hooks。可通过包装器黑名单 + PermanentDelegate 扩展进行缓解
6. **EVM 地址模型** — Hook 看到的是基于 Rome 派生的 EVM 地址，而不是 Ethereum 地址。SDK 提供派生工具

## 状态

**进行中** — 路由器核心和 KYC hook（S1）实现已启用。已记录 9 个包、13 项硬性约束、24 个边缘情况。

## 相关内容

* [Transfer Hooks](/zh/he-xin-gai-nian/transfer-hooks.md) — Token-2022 Transfer Hooks 在 Rome 中的工作方式
* [代币互操作](/zh/he-xin-gai-nian/token-interop.md) — ERC-20 ↔ SPL 代币模型
* [稳定币发行方](/zh/yong-li/stablecoin-issuers.md) — 稳定币的多 Hook 合规


---

# 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/zh/chan-pin/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.