# Transfer Hooks

Token-2022 转账钩子允许程序在每次代币转账时执行自定义逻辑。Rome 使 Solidity 智能合约能够充当转账钩子——将 EVM 的可编程能力带入 Solana 的代币标准。

## 转账钩子如何工作

Token-2022（Solana 的下一代代币程序）支持一种名为 Transfer Hook 的扩展。当某个铸币配置了转账钩子时：

1. 每次 `transfer_checked` 对该铸币的调用都会触发指定的钩子程序
2. 钩子接收转账详情（发送方、接收方、金额、铸币）
3. 钩子可以批准或拒绝该转账
4. 如果钩子拒绝（revert），整个转账将失败

## 由 EVM 驱动的转账钩子

在 Rome 上，Solidity 合约可以作为转账钩子处理器：

```
用户在 Jupiter（Solana）上交换代币
    ↓
Jupiter 调用 transfer_checked
    ↓
Token-2022 调用指定的钩子程序
    ↓
钩子程序 = Rome 元钩子路由器
    ↓
路由器通过 CPI → Rome EVM 分发到 Solidity 合约
    ↓
Solidity 合约执行合规逻辑
    ↓
通过：转账完成
失败：整个转账回滚
```

这意味着 **Solana 上的每一笔 SPL 代币转账** ——无论是在 Jupiter、Raydium、Phantom，还是任何钱包中——都可以触发 EVM 合规逻辑。

## 示例：KYC 合规钩子

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

contract ComplianceHook {
    mapping(address => bool) public kycApproved;
    mapping(address => bool) public sanctioned;

    // 由 Meta-Hook Router 在每次转账时调用
    function onTransfer(
        address sender,
        address recipient,
        uint256 amount,
        bytes32 mint
    ) external view {
        // 检查发送方是否已通过 KYC
        require(kycApproved[sender], "发送方未通过 KYC 审核");

        // 检查接收方是否已通过 KYC
        require(kycApproved[recipient], "接收方未通过 KYC 审核");

        // 检查任一方是否受到制裁
        require(!sanctioned[sender], "发送方受制裁");
        require(!sanctioned[recipient], "接收方受制裁");

        // 转账获批——函数返回且不发生回滚
    }
}
```

## 关键限制

**`transfer_checked` 仅。** 钩子仅在 `transfer_checked` 调用时触发，而不是普通的 `transfer`。任何使用 Rome 代币的集成都必须使用 `transfer_checked` 以确保合规执行。

**需要单状态模式。** 转账钩子在 Solana 交易内部执行。OP-Geth 在该上下文中无法访问。所有 EVM 钩子逻辑都必须在单状态（代理）模式下运行。

**CPI 深度预算。** 钩子调用会消耗 CPI 深度：

```
第 0 层：DeFi 协议 → SPL Token-2022
第 1 层：Token-2022 → Meta-Hook Router
第 2 层：Meta-Hook Router → Rome EVM（CPI 预编译）
第 3 层：Rome EVM →（Solidity 发起的任何进一步 CPI）
```

在钩子调用链之后，只剩下一个 CPI 层级。

**计算预算。** EVM 钩子会消耗大量 CU：

* 基础转账开销：100,000 CU
* 每个 EVM 子钩子：200,000 CU
* EVM 转账建议预算：800,000 CU

## DeFi 协议白名单

DeFi 协议金库（Jupiter、Kamino、Orca、Rome bridge vault）需要特殊处理。这些金库会在正常操作中接收和发送代币——如果阻止它们，会破坏 DeFi。

合规合约维护一个 `protocolWhitelist` 映射。白名单地址（金库、已知协议的 PDA）会在不进行 KYC 检查的情况下获批。这使得代币能够通过 DeFi 协议流转，同时仍对终端用户转账执行合规要求。

## 地址模型

转账钩子看到的是 **Rome 派生的 EVM 地址**，而不是以太坊地址。当 Solana 用户与带有 Rome 钩子的代币交互时，他们的 Solana 公钥会通过 PDA 派生映射为一个 EVM 地址。Rome Solidity SDK 为此映射提供了工具。

## 相关页面

* [Meta-Hook Router](/zh/chan-pin/meta-hook-router.md) ——启用每个铸币多个子钩子的钩子多路复用器
* [代币互操作](/zh/he-xin-gai-nian/token-interop.md) —— ERC-20 和 SPL 代币之间的关系
* [构建转账钩子指南](https://github.com/rome-protocol/docs/blob/main/developer-guides/build-transfer-hook.md) ——逐步钩子开发


---

# 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/he-xin-gai-nian/transfer-hooks.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.