> 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/open-to-solana-users.md).

# Mở hợp đồng của bạn cho người dùng Solana

Triển khai một hợp đồng Solidity trên Rome (testnet Hadrian, mainnet Rubicon) và mở nó cho các ví Solana — hợp đồng cần gì, người dùng ví Solana gọi nó như thế nào, địa chỉ theo từng mạng, và một chiến dịch ra mắt ch

Một lần triển khai, hai kiểu người dùng. Một hợp đồng trên Rome được người dùng MetaMask đạt tới bằng khóa EVM của họ và người dùng ví Solana (ví dụ Solflare) bằng khóa Solana của họ — cùng địa chỉ, cùng trạng thái. Trang này là lộ trình đầu-cuối: triển khai, làm cho hợp đồng sẵn sàng cho Solana, nối lane Solana vào ứng dụng của bạn, và phát hành lên mainnet.

## 1. Triển khai trên mạng bạn muốn

Các chain Rome là các đích EVM tiêu chuẩn: Hardhat, Foundry, viem và ethers hoạt động nguyên trạng (hướng dẫn đầy đủ trong [Triển khai Hợp đồng Solidity](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/deploy-solidity.md)).

| Mạng                                                                   | ID chuỗi | RPC                                         | Trình khám phá                                                                        | Token gas | Cách lấy gas                                                                                                                                                                                      |
| ---------------------------------------------------------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Rubicon**](https://docs.rome.builders/vi/mang/rubicon.md) (mainnet) | `7531`   | `https://rubicon.mainnet.romeprotocol.xyz/` | [via-rubicon.mainnet.romeprotocol.xyz](https://via-rubicon.mainnet.romeprotocol.xyz/) | USDC      | Bridge USDC từ Ethereum, Base, Arbitrum, Polygon, Avalanche, Monad hoặc OP (CCTP) hoặc từ Solana với [Cầu Rome](https://bridge-api.mainnet.romeprotocol.xyz/); nó sẽ đến dưới dạng gas            |
| **Hadrian** (testnet)                                                  | `200010` | `https://hadrian.testnet.romeprotocol.xyz/` | [via-hadrian.testnet.romeprotocol.xyz](https://via-hadrian.testnet.romeprotocol.xyz/) | test USDC | Bridge test USDC từ một testnet ([Vòi cấp tiền](https://docs.rome.builders/vi/tai-nguyen/faucets.md)) hoặc bọc từ một ví Solana devnet trong [Ứng dụng Rome](https://app.devnet.romeprotocol.xyz) |

Gas là USDC với 18 chữ số thập phân ở phía EVM; không có faucet Rome trên Rubicon hoặc Hadrian. Các thao tác ghi tốn gas nhiều hơn trực giác về Ethereum cho thấy, vì phần lớn chi phí là tạo các tài khoản Solana: một người nhận chưa từng dùng, một tài khoản token mới, một hợp đồng đã được triển khai. Hãy dùng `eth_estimateGas`mà các công cụ chuẩn đều làm, và đừng bao giờ hardcode 21.000. Đo trên Hadrian, triển khai một hợp đồng 10 byte ước tính và dùng 1.147.921 gas, và một chuyển khoản native tới một địa chỉ chưa từng dùng là 1.086.961, so với 21.000 cho một chuyển khoản tới một địa chỉ đã tồn tại. Rome tính gas thực tế đã dùng, và trong các phép đo này thì chưa bao giờ vượt quá ước tính. Hãy nạp vài USDC trước lần triển khai đầu tiên. Sau đó xác minh nguồn trên explorer ([Xác minh hợp đồng](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/verify-contracts.md); trình xác minh mainnet là `https://verify.mainnet.romeprotocol.xyz`).

Phát triển trên Hadrian, rồi triển khai lại cùng các artifact đó lên Rubicon với chain id và các địa chỉ wrapper mainnet được thay đổi; không có gì trong hợp đồng thay đổi giữa các mạng. Rubicon có trong registry công khai từ v0.3.0, nhưng `create-rome-app` và `rome-cli` vẫn ghim registry v0.2.0, vốn không có mục Rubicon, nên chúng không thể nhắm tới nó; với các công cụ đó, hãy điền các giá trị bằng tay từ [Rubicon](https://docs.rome.builders/vi/mang/rubicon.md). Gas trên Rubicon là USDC thật với mức giá gas xấp xỉ gấp mười lần Hadrian, nên việc triển khai ở đó tốn tiền thật.

## 2. Điều gì làm cho một hợp đồng sẵn sàng cho Solana

Danh tính EVM của một người dùng Solana là **địa chỉ tổng hợp**, `keccak256(solana_pubkey)[12:]`: một `msg.sender`bình thường, với nonce bình thường. Phần lớn hợp đồng không cần thay đổi gì cả. Có ba điều quan trọng:

* **Nhận giá trị dưới dạng ERC-20, không phải `msg.value`.** Tiền của người dùng Solana là các token SPL trong ví của họ, được nhìn ở phía EVM như wrapper của token (`wUSDC`, `wETH`, `wSOL`). Synthetic không giữ gì khi ở trạng thái nghỉ và tài sản của người dùng đi vào dưới dạng wrapper, vì vậy hãy kéo bằng `transferFrom` sau một lần `approve` và trả lại bằng `transfer`. Mỗi người dùng cấp quyền delegate SPL cho wrapper một lần trước lần kéo đầu tiên ([Một lần: cấp quyền cho wrapper](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/dual-lane-app.md#one-time-grant-the-wrapper)). Một `payable` điểm vào chỉ hoạt động sau khi synthetic đã được cấp gas native ( `rome_composeExternalDepositV1`của đường relay), điều mà mô hình nạp rồi quét không làm. Một vault ERC-20, AMM hoặc thị trường cho vay hiện có đã có đúng hình dạng.
* **Hãy dùng các wrapper chuẩn tắc.** Mỗi chain có một wrapper cho mỗi mint; các địa chỉ nằm trong [Địa chỉ hợp đồng](https://docs.rome.builders/vi/tai-lieu-tham-khao/contract-addresses.md) (Hadrian cũng có trong [registry](https://github.com/rome-protocol/rome-registry)công khai). Hãy trỏ constructor tới các địa chỉ đó; đừng tự triển khai của riêng bạn.
* **Phù hợp với ngân sách nguyên tử nơi một ví ký.** Một ví Solana ký một giao dịch Solana duy nhất, vì vậy một lời gọi trên Solana-lane phải vừa với nó: khoảng 1,4 triệu compute units, 64 tài khoản, 4 KB ([Ràng buộc](https://docs.rome.builders/vi/cac-khai-niem-cot-loi/constraints.md)). Đo trên Hadrian: một lệnh chuyển, một lệnh approve và một lệnh cung cấp Aave đều vừa; một swap Uniswap V3 vừa với rất ít dư địa (khoảng 1,24M CU); một lệnh vay Aave thì không và đi theo đường relay ở phần tiếp theo. Đo bằng `computeUnitsConsumed`của biên nhận Solana, yêu cầu giao dịch với `maxSupportedTransactionVersion: 1` (các chặng Rome là giao dịch v1; nếu không có nó RPC sẽ từ chối yêu cầu).

Những gì bạn không cần: một chương trình Solana, một bridge, một lần triển khai thứ hai, hay bất kỳ Solidity đặc thù nào của Rome. Nếu hợp đồng cũng gọi các chương trình Solana thông qua các precompile, hãy xem [Gọi Solana từ EVM](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/call-solana-from-evm.md).

## 3. Để một ví Solana gọi nó

Đường EVM của ứng dụng bạn không đổi (MetaMask + `submitRomeTx`, hoặc viem/ethers thuần). Với đường Solana có hai dạng.

**Lane SDK — một giao dịch Solana v1 cho mỗi lời gọi.** [`@rome-protocol/sdk`](https://github.com/rome-protocol/rome-sdk-ts) (`submitRomeTxV1`) để proxy tạo một giao dịch Solana v1 cho lời gọi EVM của bạn (tối đa 64 tài khoản và 4 KB, không có address lookup table; trong code của bạn không có instruction ComputeBudget, ví kho báu hay khám phá tài khoản). Ví ký hai lần bằng cùng một khóa: trước tiên là một thông điệp ủy quyền dễ đọc (`Rome authorization` trên một dòng, `0x` và hash giao dịch EVM ở dòng kế tiếp), mà chain kiểm tra thông qua chương trình Ed25519, rồi sau đó là giao dịch. Ứng dụng gửi giao dịch đã ký tới Solana RPC; lời gọi trả về hash giao dịch EVM và biên nhận của nó. Trước khi ví ký giao dịch, SDK sẽ kiểm tra nó: payer là signer duy nhất, chỉ chương trình Rome và trình xác minh Ed25519 chạy, instruction Rome chứa đúng lời gọi mà người dùng đã ủy quyền, và không có priority fee. Bất kỳ thứ gì khác đều bị từ chối.

Nếu một lời gọi không vừa trong một giao dịch, composer sẽ từ chối nó và SDK chuyển nó cho proxy để relay, với cùng chữ ký ủy quyền, nên người dùng vẫn chỉ thấy một lời nhắc ủy quyền. Kết quả sau đó có `route: "relay"`. Các quy tắc cho các lời gọi được relay và các lời gọi dài nằm trong [Các lệnh được chuyển tiếp và các lệnh dài](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/call-evm-from-solana.md#relayed-calls-and-long-calls). Một lời gọi được relay được thanh toán bằng gas native của chain, vì vậy synthetic cần một số dư gas: `fundSyntheticGas(deps, amountWei)` di chuyển token gas của chain (USDC trên Hadrian và Rubicon) từ tài khoản token của ví vào trong đó, trong một giao dịch v1 do ví ký.

Chặng nạp (`buildFundLeg`) và việc tạo tài khoản token của ví trước khi quét là các instruction Solana thuần; `submitSolanaInstructionsV1` cũng gửi chúng dưới dạng giao dịch v1, được ký bởi cùng signer của ví, không có proxy tham gia. Lời gọi riêng của chặng quét (`buildSweepLeg`, `HelperProgram.transfer_spl`) đi qua `submitRomeTxV1` như mọi lời gọi khác, và proxy tìm các tài khoản token. `submitRomeTxV1` không tự tạo tài khoản của synthetic mới: trước lời gọi đầu tiên có di chuyển giá trị, hãy kiểm tra `isSyntheticProvisioned(...)` và, nếu là false, hãy gửi `buildCreatePdaCall(synthetic)` qua `submitRomeTxV1` một lần. Hướng dẫn đầy đủ về nạp và rút với code nằm trong [Xây dựng một ứng dụng hai làn](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/dual-lane-app.md); cơ chế nằm trong [Gọi EVM từ Solana](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/call-evm-from-solana.md). Phần `submitRomeTxSolanaLane`, phần xây dựng một giao dịch Solana legacy ở client, vẫn còn trong SDK như là đường cũ.

**Mỗi `deps` giá trị đến từ đâu.** Đối tượng `deps` của SDK có năm trường bắt buộc (các phần còn lại, như `fetchImpl` và các timeout, là tùy chọn). Bốn trường đến từ chain và một từ ví:

| `deps` trường | Nguồn gốc                                                                                                        | getter của Registry (`@rome-protocol/registry` v0.2.0)                                                            |
| ------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `proxyUrl`    | URL RPC của chain                                                                                                | `getChain(chainId).rpcUrl`                                                                                        |
| `chainId`     | chain ID của chain                                                                                               | `getChain(chainId).chainId`                                                                                       |
| `programId`   | program ID của Rome mà chain chạy trên đó                                                                        | `getChain(chainId).romeEvmProgramId`                                                                              |
| `kết nối`     | một Solana RPC cho cluster của chain, nơi giao dịch đã ký được gửi đến (devnet cho Hadrian, mainnet cho Rubicon) | `getChain(chainId).solana.rpc` (một URL devnet công khai cho Hadrian); với mainnet hãy dùng một RPC của riêng bạn |
| `signer`      | của ví `LaneSigner`, hoặc một `Keypair` trong script                                                             | không có                                                                                                          |

Các trình tạo chặng nhận các giá trị không có trong `deps`. Trường `mint` (gọi là `usdcMint` trong hướng dẫn) là mint Solana của token gas, lấy từ `getTokens(chainId)` (mục có `kind: "gas"`, trường `mintId`). Địa chỉ wrapper wUSDC không phải là input của trình tạo chặng; bạn dùng nó cho các lời gọi ERC-20, và đó là mục có `kind: "spl_wrapper"` và symbol `wUSDC` (trường `address`). Registry bao phủ Hadrian và, từ v0.3.0, Rubicon. Để điền các giá trị Rubicon bằng tay thì: `proxyUrl` `https://rubicon.mainnet.romeprotocol.xyz/`, `chainId` `7531`, `programId` `RomePq9X3iAoTr813HR7uRarafFDUJty6GdiEceYpzX`, `mint` `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`, wrapper từ bảng ở phần tiếp theo, và một Solana mainnet RPC cho `kết nối`. [Rubicon](https://docs.rome.builders/vi/mang/rubicon.md) có danh sách đầy đủ.

**Các endpoint external-V1 của proxy — cùng lane đó nhưng không dùng SDK.** SDK bọc compose nguyên tử, relay và nạp gas (`fundSyntheticGas`). Các phương thức RPC thô vẫn còn cho các client không dùng SDK, và chúng bao gồm compose lặp, mà SDK không bọc. Ví ký một thông điệp Ed25519 cho lời gọi (dạng dễ đọc `Rome authorization\n0x<hash>` hoặc hash thô), và proxy hoặc là tạo(s) giao dịch Solana để ví ký (`rome_composeUnsignedAtomicV1`, `rome_composeUnsignedIterativeV1` + `rome_submitSignedV1Plan`) hoặc tự thực thi toàn bộ bằng một chữ ký của ví (`rome_relayUnsignedV1`, sau một `rome_composeExternalDepositV1` (của SDK `fundSyntheticGas`) dùng để nạp số dư gas của synthetic; các lời gọi được relay sẽ chi từ đó, vì vậy hãy nạp thêm khi nó sắp cạn). Dạng phương thức trong [Hỗ trợ JSON-RPC](https://docs.rome.builders/vi/tai-lieu-tham-khao/json-rpc.md); các quy tắc ủy quyền trong [Gọi EVM từ Solana](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/call-evm-from-solana.md#the-external-v1-endpoints). Hãy dùng relay cho mọi thứ mang tính lặp, và lane SDK cho mọi thứ vừa khít.

Dù theo cách nào, hợp đồng vẫn thấy một giao dịch bình thường từ địa chỉ synthetic và người dùng không bao giờ giữ khóa EVM.

## 4. Các địa chỉ wrapper theo từng mạng

| Mạng             | `wUSDC` wrapper                              | Các wrapper khác                                                                                         |
| ---------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Rubicon (7531)   | `0x0952d233b0c254cd375f3bfb3e5869c1a906f9b3` | `wETH` `0x01e8b3573da1d4b7b4b1ce0932cf07c8af0c92e9`, `wSOL` `0xc4e29e0f726a906e93277cbbc37bf27a9848a113` |
| Hadrian (200010) | `0xbce339ba4c3a8de3bb8af1c5539e6ac11da3112d` | `wETH` `0x02aeace038269f9961c93d04dcacd6fb3adfa55f`, `wSOL` `0x39f36444fcb79b3e691544aee2a832ebef54ca9f` |

Token gas native xuất hiện dưới dạng `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` trong danh sách token; nó không phải là một hợp đồng ERC-20. Wrapper mang số chữ số thập phân của mint SPL, không phải 18: wUSDC 6, wETH 8, wSOL 9.

## 5. Danh sách kiểm tra trước khi ra mắt

1. Đã triển khai trên Hadrian; đường EVM hoạt động từ MetaMask.
2. Mọi điểm vào có di chuyển giá trị đều dựa trên ERC-20 và trỏ tới wrapper chuẩn tắc của chain.
3. Một ví Solana ký được giao dịch v1 (Solflare hiện làm được trên devnet; Phantom thì chưa) hoàn tất toàn bộ vòng đi-về trên Hadrian: provision synthetic (`create_pda`, một lần) → chặng nạp → cấp quyền → approve → gọi → chặng quét, dùng lane SDK; hoặc đường relay nếu lời gọi mang tính lặp.
4. của mỗi lời gọi trên Solana-lane `computeUnitsConsumed` được đọc từ biên nhận Solana và nằm dưới ngân sách nguyên tử, hoặc lời gọi sẽ được chuyển qua relay.
5. Việc cấp quyền wrapper nằm trong luồng nạp đầu tiên của ứng dụng bạn cho cả hai lane: `isEnabled(user)` được kiểm tra và `approve_spl` được gửi một lần khi nó là false ([Một lần: cấp quyền cho wrapper](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/dual-lane-app.md#one-time-grant-the-wrapper)).
6. Mã nguồn đã được xác minh trên trình khám phá.
7. Được triển khai lại trên Rubicon với các địa chỉ wrapper mainnet. Các `deps` giá trị lấy từ registry (v0.3.0 trở lên) hoặc điền bằng tay từ [Rubicon](https://docs.rome.builders/vi/mang/rubicon.md). Cùng một vòng đi-về được chạy một lần với tiền thật, bằng một ví mà bạn đã kiểm tra là ký được giao dịch v1 trên mainnet.

## Tiếp theo là gì

* [Xây dựng một ứng dụng hai làn](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/dual-lane-app.md) — ví dụ vault, từng bước, cả hai ví
* [Gọi EVM từ Solana](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/call-evm-from-solana.md) — địa chỉ synthetic, khám phá tài khoản, các endpoint external-V1
* [Triển khai Hợp đồng Solidity](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/deploy-solidity.md) · [Xác minh hợp đồng](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/verify-contracts.md) · [Địa chỉ hợp đồng](https://docs.rome.builders/vi/tai-lieu-tham-khao/contract-addresses.md)


---

# 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/open-to-solana-users.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.
