> 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` 指令会在用户已签名的 **EIP-712** `SettleAuthorization`下将资金记入用户账户，因此不存在特权结算者。其他入站路径不会使用该指令或签名。Wormhole 上的封装版 USDC、ETH 和 SOL 会作为封装代币直接入账到用户账户。对于原生 Gas 代币为 USDC 的链上的 Solana USDC，还需要再由用户签署一笔交易，把封装资产转换为 Gas。报价会告诉您某条路径需要哪些签名。
* **出站（Rome → 原链）：** `RomeBridgeWithdraw` （在 [`rome-solidity`](https://github.com/rome-protocol/rome-solidity)）会在 Rome 上销毁该资产。随后用户通过自己的交易在原链上领取。
* **传输：** 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](https://docs.rome.builders/zh/chan-pin/rome-cli.md) 页面。

### 转入资产

1. **获取路径报价。** 提交用户的源链、资产、金额和地址。链名使用 CAIP-2 标识，例如 `eip155:84532`; `romeChainId` 是您的 Rome 链。旧名称 `ethereum` 和 `solana` 仍然可接受，但已弃用，API 会在这些响应上标记 `Sunset` 头。完整的请求和响应结构请参见 [API 参考](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、封装意图型 USDC 以及 Solana 路径都不需要。
3. **登记转账。** `POST /v1/transfers` 以及报价的 `quoteId` 和 `step1TxHash`，即报价后 15 分钟内第一步中最后一笔交易（销毁）的哈希。在 Gas 路径上，请将结算签名作为 `userSettleSig`传入。API 不接受完整的 quote 对象。它会检查源链上的交易是否与已存储的报价匹配，并返回一个转账 `id`.
4. **轮询** `GET /v1/transfers/{id}` 每隔几秒查询一次，直到 `结果` 为 `complete`，并处理 `failed` 和 `expired`。随后用户在 Rome 上获得资金，即可使用您的应用。一个完整的转账可能包含一个 `degradation` 说明以及 `degradationReason`，因此在告知用户 Gas 或封装余额已到账之前，请先检查这些信息。

Solana 原链也遵循相同的结构，只是步骤不同。用户向其 Rome 账户的代币账户发起一笔 SPL 转账。SOL 会在这一步之后以封装 SOL 形式到账。在 Gas 代币为 USDC 的链上，例如 Hadrian，USDC 还需要第二步：由用户签署的一笔 Rome 交易，将到账的封装资产转换为原生 Gas。任何其他 SPL 代币都会通过 `spl-solana-to-rome` 路径，路径会将铸币地址传入 `splAsset`.

### 将资产转出

出站并不是把入站流程反向执行。它需要不止一个签名，并由用户在原链上完成。请使用以下参数进行报价： `direction` 设置为 `from-rome`. `sourceChain` 以 CAIP-2 标识指定非 Rome 一侧，销毁会转到该链。 `destinationChainId` 是可选项，且在提供时必须与其一致。旧名称 `ethereum` 仍表示 Ethereum Sepolia：

```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`）。该授权恰好覆盖此次销毁的金额，因此报价每次都会包含它，并且用户会在每次销毁前签署。第二笔通过 `RomeBridgeWithdraw`销毁 wUSDC，从而启动 CCTP 转账。请使用销毁哈希登记该转账。被销毁的是 wUSDC，而不是报价中标明为 `burnToken`的原生 Gas USDC。以 Gas 形式入账的资金不会被销毁，因此如果要做往返，请使用 `intent: "wrapper"`.
2. **在目标链上进行领取。** 轮询 `GET /v1/transfers/{id}` 直到步骤 2 `就绪`。随后它会携带 `消息` 和 `证明`。用户在目标链上的 Circle 消息传输合约上调用 `receiveMessage(message, attestation)` （报价会标明传输合约和 CCTP 域）。这里没有任何赞助，因此用户需要该链上的 Gas。请通过以下方式上报领取哈希： `POST /v1/transfers/{id}/steps/2`.

目前 Hadrian 和 Rubicon 不提供从 Rome 通过 Wormhole 转出 ETH。Hadrian 仅列出朝向 Rome 的 ETH Wormhole 路径。Rubicon 不提供任何 ETH 路径。

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

**出站转账不需要激活步骤。** CCTP 销毁会在 Solana 上创建一个消息账户，该账户需要租金。桥合约自己的 Solana 账户会支付这笔租金。在其 CPI 调用之前，合约会调用 `swap_gas_to_lamports`：交易的 Solana 费用支付者会先垫付这些 lamports，而用户会在同一笔销毁交易中以 Gas 形式为其付费。新钱包可以在没有任何先前设置的情况下完成首次出站转账。 `RomeBridgeWithdraw` 在 Hadrian 和 Rubicon 上当前版本为 13.0.0。出站报价不包含激活或补足步骤，因此您的应用在首次报价前无需检查用户账户。入站转账也不需要激活。 `rome` CLI（0.11.0）仍然会进行自己的检查。 `rome bridge --to` （不带 `--dry-run`）会读取 Solana 上用户外部授权账户的 lamports 数量。如果少于 15,000,000，该命令会停止并提示您运行 `rome activate <chain>`，它会通过 `SimpleActivator` 合约在 Hadrian 上支付 2 USDC。 `rome verify --path from-home` 在启动前会进行相同的检查。该合约不需要这种激活。

## 阅读代码

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

## 下一步

* [获得资金](https://docs.rome.builders/zh/zi-yuan/faucets.md) —— 同一条桥接路径也可为一个新的开发钱包提供资金。
* [部署 Solidity](https://docs.rome.builders/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.
