> 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/vi/huong-dan-cho-nha-phat-trien/from-home.md).

# Từ home: đến Rome từ một chuỗi khác

Cho phép người dùng trên chuỗi khác tiếp cận ứng dụng Rome của bạn mà không cần rời chỗ — đưa tài sản vào, thực hiện hành động, rồi mang chúng ra lại.

Người dùng của bạn không phải chuyển sang Rome. Từ chuỗi gốc của họ — một L2 như Arbitrum hoặc Monad, hay Solana — họ đưa tài sản vào, dùng ứng dụng Rome của bạn, rồi rút tài sản ra. Cầu nối nằm trên chuỗi và được ủy quyền bằng chính chữ ký của người dùng; bạn kết nối ứng dụng của mình với nó qua một API.

## Cách hoạt động

* **Vào (gốc → Rome):** trên tuyến USDC token gas qua CCTP, `settle_inbound_bridge_v2` lệnh của chương trình Rome ghi có cho người dùng, dưới một **EIP-712** `SettleAuthorization`, nên không có bộ thanh toán đặc quyền nào. Các tuyến vào khác không dùng lệnh hay chữ ký đó. Wrapper USDC, ETH qua Wormhole và SOL sẽ vào trực tiếp dưới dạng token wrapper trong tài khoản của người dùng. Solana USDC trên một chain có token gas là USDC cần thêm một giao dịch nữa, do người dùng ký, để đổi wrapper thành gas. Báo giá sẽ cho bạn biết tuyến nào cần những chữ ký nào.
* **Ra (Rome → gốc):** `RomeBridgeWithdraw` (trong [`rome-solidity`](https://github.com/rome-protocol/rome-solidity)) đốt tài sản trên Rome. Sau đó người dùng tự nhận nó trên chuỗi gốc bằng giao dịch của chính họ.
* **Vận chuyển:** Circle **CCTP** cho USDC và cầu token **Wormhole** cho ETH. Các chuỗi gốc Solana dùng chuyển SPL thông thường để vào và lệnh rút Rome để ra. Wormhole là tuyến vào chỉ dành cho ETH. Có một tuyến Wormhole chung chỉ cho đầu ra, và mỗi tài sản trên đó trước tiên phải được các operator của Rome bật lên.
* **Điều phối:** bộ điều phối ngoài chuỗi [`rome-bridge-api`](https://github.com/rome-protocol/rome-bridge-api) báo giá một tuyến, xác minh giao dịch trên chuỗi nguồn, và tài trợ phí thanh toán. Nó không giữ tiền và cũng không giữ khóa nào. Nó chỉ có thể kích hoạt những gì người dùng đã ký trước đó.

## Xây dựng nó

API công khai trên devnet tại `https://bridge-api.devnet.romeprotocol.xyz`. `GET /v1/routes` liệt kê mọi tuyến đang hoạt động (tài sản, rail, chiều, chain nguồn, chain Rome, tốc độ). Các lệnh gọi dưới đây chính là bốn lệnh mà SDK bọc trong `@rome-protocol/sdk/bridge` (`requestQuote`, `registerTransfer`, `getTransfer`, `reportStep`). CLI chạy toàn bộ luồng cho bạn: `rome fund` và `rome bridge` cho các lần chuyển và `rome verify --path from-home` cho một chuyến đi khứ hồi, như được mô tả trên trang [Rome CLI](https://docs.rome.builders/vi/san-pham/rome-cli.md) .

### Đưa tài sản vào

1. **Báo giá tuyến.** Gửi chain nguồn của người dùng, tài sản, số lượng và địa chỉ. Chain được nhập dưới dạng id CAIP-2 như `eip155:84532`; `romeChainId` là chain Rome của bạn. Các tên cũ `ethereum` và `solana` vẫn được chấp nhận nhưng đã lỗi thời, và API đánh dấu các phản hồi đó bằng header `Sunset` . Cấu trúc đầy đủ của request và response có trong [tài liệu tham chiếu 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"
     }'
   ```

   Số lượng là số nguyên đơn vị cơ sở dưới dạng chuỗi (`"1000000"` là 1 USDC). Số lượng ETH được tính bằng wei và, khi đi ra, phải là bội số của 10.000.000.000 wei (wrapper có 8 chữ số thập phân); API sẽ từ chối bất kỳ giá trị nào nhỏ hơn mức đó. Phản hồi liệt kê `các bước`. Người dùng ký các giao dịch của mọi bước được đánh dấu `userSigns: true`, theo thứ tự bước: giao dịch EVM nằm trong `unsignedTxs`, chỉ thị Solana nằm trong `unsignedTx`. Ký chúng đúng như được trả về. Các bước không cần ký sẽ do sponsor thực hiện sau khi Circle hoặc Wormhole xác nhận chuyển khoản. Yêu cầu nhận ở đầu ra là ngoại lệ, được mô tả bên dưới: người dùng tự tạo nó.
2. **Yêu cầu người dùng ký.** Với một quote CCTP thì đó là phê duyệt USDC và đốt trên chain nguồn. Nếu quote có mục trong `signatureRequests`, người dùng cũng ký EIP-712 đó `SettleAuthorization` sau khi biết hash của lệnh đốt; điền hash của lệnh đốt và truyền kết quả dưới dạng `userSettleSig` ở lệnh gọi tiếp theo. Chỉ tuyến CCTP dùng token gas mới có mục này. Wormhole ETH, USDC theo intent wrapper và các tuyến Solana thì không có.
3. **Đăng ký chuyển khoản.** `POST /v1/transfers` với `quoteId` và `step1TxHash`, là hash của giao dịch cuối cùng ở bước đầu tiên (lệnh đốt), trong vòng 15 phút kể từ quote. Trên tuyến gas, thêm chữ ký thanh toán dưới dạng `userSettleSig`. API từ chối một đối tượng quote đầy đủ. Nó kiểm tra rằng giao dịch trên chain nguồn khớp với quote đã lưu và trả về một `id`.
4. **Thăm dò** `GET /v1/transfers/{id}` mỗi vài giây cho đến khi `kết quả` là `hoàn tất`, và xử lý `thất bại` và `hết hạn`. Khi đó người dùng đã được cấp vốn trên Rome và có thể dùng ứng dụng của bạn. Một lần chuyển hoàn tất có thể mang một ghi chú `suy giảm` với một `degradationReason`, vì vậy hãy kiểm tra chúng trước khi bạn báo cho người dùng rằng số dư gas hoặc wrapper đã về.

Các chuỗi gốc Solana đi theo cùng một cấu trúc nhưng với các bước khác nhau. Người dùng gửi một chuyển SPL đến tài khoản token của tài khoản Rome của họ. SOL sẽ đến dưới dạng wrapped SOL sau một lần chuyển đó. Trên một chain có token gas là USDC, như Hadrian, USDC cần bước thứ hai: một giao dịch Rome do người dùng ký để đổi wrapper đã đến thành gas gốc. Bất kỳ token SPL nào khác đều đi qua tuyến `spl-solana-to-rome` , tuyến này nhận mint trong `splAsset`.

### Đưa tài sản ra ngoài

Bridging ra ngoài không phải là luồng vào chạy ngược lại. Nó có hơn một chữ ký, và người dùng hoàn tất nó trên chain gốc. Báo giá nó với `direction` đặt thành `from-rome`. `sourceChain` chỉ phía không phải Rome bằng một id CAIP-2, và lệnh đốt đi tới chain đó. `destinationChainId` là tùy chọn và phải khớp với nó khi bạn gửi. Tên cũ `ethereum` vẫn có nghĩa là 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"
  }'
```

Với USDC qua CCTP, quote trả về hai bước và người dùng ký cả hai:

1. **Trên Rome, hai giao dịch theo thứ tự.** Lệnh đầu tiên cấp `RomeBridgeWithdraw` quyền đại diện trên wUSDC của người dùng trên Solana (`approve_spl`). Quyền cấp bao trùm chính xác số lượng của lệnh đốt này, nên quote luôn bao gồm nó và người dùng ký nó trước mỗi lần đốt. Lệnh thứ hai đốt wUSDC thông qua `RomeBridgeWithdraw`, lệnh này bắt đầu chuyển CCTP. Đăng ký chuyển khoản bằng hash của lệnh đốt. Lệnh đốt dùng wUSDC, token mà quote đặt tên là `burnToken`, chứ không phải USDC gas gốc. Quỹ đi vào dưới dạng gas không phải thứ được đốt, vì vậy để đi khứ hồi hãy đưa USDC vào với `intent: "wrapper"`.
2. **Trên chain đích, là claim.** Thăm dò `GET /v1/transfers/{id}` cho đến khi bước 2 `sẵn sàng`. Sau đó nó mang `thông điệp` và `xác nhận`. Người dùng gọi `receiveMessage(message, attestation)` trên message transmitter của Circle ở chain đích (quote nêu tên transmitter và miền CCTP). Không có gì được tài trợ ở đây, nên người dùng cần gas trên chain đó. Báo hash của claim với `POST /v1/transfers/{id}/steps/2`.

Rút ETH khỏi Rome qua Wormhole hiện không được cung cấp trên Hadrian hoặc Rubicon. Hadrian chỉ liệt kê ETH qua Wormhole theo hướng vào Rome. Rubicon không liệt kê tuyến ETH nào.

Rút về địa chỉ Solana thì không có bước claim. USDC là một giao dịch Rome duy nhất rút về tài khoản Solana của người dùng. SOL là một bước Rome với ba giao dịch: lệnh cấp đại diện wSOL giống như trên, một thao tác tạo tài khoản token wSOL của người nhận trên Solana nếu cần (bỏ qua khi nó đã tồn tại), và lệnh rút qua `RomeBridgeWithdraw`.

**Các lần chuyển ra ngoài không cần bước kích hoạt.** Một lệnh đốt CCTP tạo ra một tài khoản message trên Solana, và tài khoản đó cần tiền thuê. Tài khoản Solana của chính hợp đồng bridge sẽ trả khoản tiền thuê đó. Ngay trước lệnh gọi CPI của nó, hợp đồng gọi `swap_gas_to_lamports`: người trả phí Solana của giao dịch sẽ ứng trước lamports, và người dùng sẽ bị tính chúng bằng gas ngay trong cùng giao dịch đốt đó. Một ví mới có thể thực hiện lần chuyển ra ngoài đầu tiên mà không cần thiết lập trước. `RomeBridgeWithdraw` đang ở phiên bản 13.0.0 trên Hadrian và Rubicon hiện nay. Các quote đầu ra không có bước kích hoạt hay nạp thêm, nên ứng dụng của bạn không cần kiểm tra tài khoản của người dùng trước quote đầu tiên. Các lần chuyển vào cũng không cần kích hoạt. CLI `rome` (0.11.0) vẫn có kiểm tra riêng. `rome bridge --to` (không có `--dry-run`) sẽ đọc lamport của tài khoản ngoài quyền hạn của người dùng trên Solana. Nếu nó giữ ít hơn 15.000.000, lệnh sẽ dừng và bảo bạn chạy `rome activate <chain>`, lệnh này trả 2 USDC trên Hadrian thông qua hợp đồng `SimpleActivator` . `rome verify --path from-home` thực hiện cùng một kiểm tra trước khi bắt đầu. Hợp đồng không cần kích hoạt đó.

## Đọc mã

* [appia](https://github.com/rome-protocol/appia) — một ứng dụng từ home: người dùng đưa USDC từ chuỗi gốc của họ và sử dụng DeFi phía Rome mà không rời khỏi nó.
* [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api) — bộ điều phối (quote → xác minh → tài trợ).

## Tiếp theo là gì

* [Được cấp vốn](https://docs.rome.builders/vi/tai-nguyen/faucets.md) — cùng một đường cầu nối cấp vốn cho một ví dev mới tinh.
* [Triển khai Solidity](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/deploy-solidity.md) — đưa ứng dụng của bạn lên 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/vi/huong-dan-cho-nha-phat-trien/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.
