> For the complete documentation index, see [llms.txt](https://docs.rome.builders/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/from-home.md).

# 从家中：从另一条链接入 Rome

让另一条链上的用户无需离开原链即可访问你的 Rome 应用——把资产带入、执行操作，再把资产取回。

您的用户无需迁移到 Rome。来自他们的原链——例如 Arbitrum 或 Monad 这样的 L2，或 Solana——他们可以把资产转入，使用您的 Rome 应用，再把资产转出。该桥接完全链上运行，并由用户自己的签名授权；您只需通过一个 API 将应用接入它。

## 工作原理

* **入站（原链 → Rome）：** 在通过 CCTP 的 gas 代币 USDC 路径中， `settle_inbound_bridge_v2` Rome 程序的指令会为用户入账，并在已签名的 **EIP-712** `SettleAuthorization`，因此不存在特权结算方。其他入站路径不使用该指令或签名。通过 Wormhole 传入的 Wrapper USDC、ETH，以及 SOL，都会直接作为包装代币进入用户账户。对于 Solana 上、且 gas 代币为 USDC 的链，USDC 还需要一笔由用户签名的额外交易，才能把包装代币转换为 gas。报价会告诉您某条路径需要哪些签名。
* **出站（Rome → 原链）：** `RomeBridgeWithdraw` （在 [`rome-solidity`](https://github.com/rome-protocol/rome-solidity)）
* **传输方式：** Circle **CCTP** 用于 USDC，以及 **Wormhole** ETH 的代币桥。Solana 原链使用普通的 SPL 转入，并通过 Rome 提现转出。Wormhole 仅用于 ETH 的入站通道。还存在一条通用的 Wormhole 路径，仅用于出站，且其上的每一种资产都必须先由 Rome 运维方启用。
* **编排：** 链下的 [`rome-bridge-api`](https://github.com/rome-protocol/rome-bridge-api) 为路径报价、验证源链交易，并代为支付结算费用。它不持有资金，也不持有密钥。它只能触发用户已经签名的内容。

## 开始构建

该 API 在 devnet 上公开提供，地址为 `https://bridge-api.devnet.romeprotocol.xyz`. `GET /v1/routes` 列出所有可用路径（资产、通道、方向、源链、Rome 链、速度）。下面这些调用与 SDK 封装的四个方法相同： `@rome-protocol/sdk/bridge` (`requestQuote`, `registerTransfer`, `getTransfer`, `reportStep`）。CLI 会为您完成整个流程： `rome fund` 和 `rome bridge` 用于转账，以及 `rome verify --path from-home` 用于往返流程，详情见 [Rome CLI](/zh/chan-pin/rome-cli.md) 页面。

### 将资产转入

1. **为路径报价。** 传入用户的源链、资产、金额和地址。链使用 CAIP-2 标识，例如 `eip155:84532`; `romeChainId` 是您的 Rome 链。较旧的名称 `ethereum` 和 `solana` 仍然可接受，但已弃用，API 会在这些响应中标记一个 `Sunset` 标头。完整的请求与响应结构详见 [API reference](https://github.com/rome-protocol/rome-bridge-api/blob/main/docs/API.md).

   ```bash
   curl -X POST https://bridge-api.devnet.romeprotocol.xyz/v1/quote \\
     -H 'Content-Type: application/json' \\
     -d '{
       "asset": "USDC",
       "direction": "to-rome",
       "sourceChain": "eip155:84532",
       "romeChainId": "200010",
       "amount": "1000000",
       "sender": { "ethereum": "0xUSER" },
       "recipient": "0xUSER"
     }'
   ```

   金额以字符串形式表示的基础单位整数（`"1000000"` 代表 1 USDC）。ETH 金额以 wei 表示，并且在出站时必须是 10,000,000,000 wei 的整数倍（包装代币有 8 位小数）；API 会拒绝更小的精度。响应会列出 `步骤`。 `userSigns: true`，并按步骤顺序排列：EVM 交易位于 `unsignedTxs`，Solana 指令位于 `unsignedTx`。请按返回内容原样签名。没有需要签名内容的步骤，会在 Circle 或 Wormhole 完成转移证明后由赞助方执行。出站领取是例外，详见下文：由用户自行构建。
2. **让用户签名。** 对于 CCTP 报价，这包括 USDC 授权以及源链上的销毁。如果报价在 `signatureRequests`中包含一项，用户还需要签署该 EIP-712 `SettleAuthorization` 一旦销毁哈希可用；填入销毁哈希，并将结果作为 `userSettleSig` 传入下一次调用。只有 gas 代币 CCTP 路径才有这一项。Wormhole ETH、wrapper-intent USDC 以及 Solana 路径都没有。
3. **注册转账。** `POST /v1/transfers` 携带完整报价以及 `step1TxHash`，即第一步中最后一笔交易（销毁）的哈希。API 会检查源链上的交易是否与报价一致，并返回一个转账 `ID`.
4. **轮询** `GET /v1/transfers/{id}` 每隔几秒，直到 `结果` 是 `完成`。随后用户会在 Rome 上获得资金，并可以使用您的应用。

Solana 原链遵循相同的结构，但步骤不同。用户向其 Rome 账户的代币账户发送一笔 SPL 转账。完成这一步后，SOL 会以 wrapped SOL 的形式到账。在 gas 代币为 USDC 的链上，例如 Hadrian，USDC 还需要第二步：由用户签名的一笔 Rome 交易，将到达的包装代币转换为原生 gas。任何其他 SPL 代币都通过 `spl-solana-to-rome` 路径，该路径会接收以下 mint： `splAsset`.

### 将资产转出

出站桥接并不是入站流程的反向执行。它需要多个签名，并且由用户在原链上完成。报价时使用 `direction` 设为 `from-rome`. `sourceChain` 指定非 Rome 一侧，而 `destinationChainId` 选择用户领取资产的链。两者都要传入： `destinationChainId` 这是决定领取链的字段；如果报价中没有它，则默认使用 Ethereum Sepolia， `sourceChain` 无论如何说明：

```bash
curl -X POST https://bridge-api.devnet.romeprotocol.xyz/v1/quote \\
  -H 'Content-Type: application/json' \\
  -d '{
    "asset": "USDC",
    "direction": "from-rome",
    "sourceChain": "eip155:84532",
    "destinationChainId": 84532,
    "romeChainId": "200010",
    "amount": "1000000",
    "sender": { "rome": "0xUSER" },
    "recipient": "0xUSER"
  }'
```

对于通过 CCTP 的 USDC，报价会返回两个步骤，用户需要签署两者：

1. **在 Rome 上，按顺序进行两笔交易。** 第一笔授予 `RomeBridgeWithdraw` 用户在 Solana 上的 wUSDC 代理权限（`approve_spl`）。该授权的额度正好覆盖此次销毁金额，因此报价每次都会包含它，且用户会在每次销毁前签署。第二笔通过以下方式销毁 wUSDC： `RomeBridgeWithdraw`，从而启动 CCTP 转账。使用销毁哈希注册该转账。销毁消耗的是 wUSDC，也就是报价中标记为 `burnToken`的代币，而不是原生 gas USDC。作为 gas 入账的资金不会被销毁，因此若要完成往返，请以以下方式将 USDC 转入： `意图："wrapper"`.
2. **在目标链上进行领取。** 轮询 `GET /v1/transfers/{id}` 直到第 2 步 `就绪`。然后它携带 `消息` 和 `证明`。用户调用 `receiveMessage(message, attestation)` 目标链上的 Circle 消息传输器（报价会给出传输器和 CCTP 域）。这里没有赞助，因此用户需要在该链上准备 gas。使用以下接口上报领取哈希： `POST /v1/transfers/{id}/steps/2`.

通过 Wormhole 的 ETH 具有相同的结构。用户授予相同的 wETH 代理权限，在 Rome 上销毁 wETH，并等待 Wormhole 守护者签名。随后用户使用自己的交易在 Ethereum 上兑换： `completeTransferAndUnwrapETH` 在报价指定的代币桥上（`claimTokenBridge`），使用已签名消息（`vaa`）。

提现到 Solana 地址没有领取步骤。USDC 只需一笔 Rome 交易即可提现到用户的 Solana 账户。SOL 则是一个 Rome 步骤，包含三笔交易：对 wSOL 的同样代理授权、可选创建收款方在 Solana 上的 wSOL 代币账户（如果已存在则跳过），以及通过以下方式提现： `RomeBridgeWithdraw`.

**首次出站转账需要已激活的账户。** CCTP 销毁会在 Solana 上创建一个消息账户，而用户在 Rome 上的账户必须持有足够的 lamports 来支付这笔费用。新钱包通常不满足这一条件，因此在用户完成一次激活之前，首次出站转账会失败。检查标准是账户至少持有 15,000,000 lamports。使用以下方式读取： `account_lamports(bytes32)` 在位于以下地址的 CPI 预编译合约上： `0xff00000000000000000000000000000000000008`，并传入用户在 Solana 上的 external-auth 账户（CLI 会为您执行此读取）。激活调用 `activate()` 上的 `SimpleActivator` 合约，位于 [registry](https://github.com/rome-protocol/rome-registry) 中对应您链的列表里，并且该调用会携带以该链 gas 代币支付的费用。在 Hadrian 上，这笔费用是 2 USDC。CLI 使用以下命令完成： `rome activate <chain>`，以及 `rome bridge --to` 如果账户尚未就绪，CLI 会停止并提示您运行该命令。该预留金额可覆盖一次销毁，而租金会在 Circle 证明销毁后返还，这大约需要 30 分钟。在此之前进行第二次销毁，或者账户在激活后已被耗尽，则需要 `topUpUserPda(lamports)` 在同一合约上，因为 `activate()` 该操作在账户激活后会回退。 `rome activate` 会选择正确的调用。入站转账无需激活。报价不会将激活作为步骤包含在内，因此您的应用必须先检查账户，并在首次出站报价前提供激活选项。

## 阅读代码

* [appia](https://github.com/rome-protocol/appia) —— 一个 from-home 应用：用户从原链带入 USDC，并在不离开 Rome 的情况下使用 Rome 侧 DeFi。
* [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api) —— 编排器（报价 → 验证 → 赞助）。

## 下一步

* [获得资金](/zh/zi-yuan/faucets.md) —— 同一路由可为新建的开发钱包注资。
* [部署 Solidity](/zh/kai-fa-zhe-zhi-nan/deploy-solidity.md) —— 将您的应用部署到 Rome。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/from-home.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.