> 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/dual-lane-app.md).

# Xây dựng một ứng dụng hai làn

Hướng dẫn từng bước cho một ứng dụng hai làn — một hợp đồng Solidity được cả người dùng MetaMask và người dùng ví Solana sử dụng, với chính xác những gì xảy ra ở mỗi bước.

Một **ứng dụng hai luồng** là một hợp đồng Solidity duy nhất mà cả một **MetaMask (EVM)** người dùng và một **ví Solana** người dùng sử dụng trực tiếp — cùng hợp đồng, cùng trạng thái, mỗi bên với ví họ vốn đã có. Trang này sẽ đi qua *chính xác* điều gì xảy ra ở từng bước, ở mỗi phía.

Ví dụ là một **két**: bạn `nạp` USDC rồi sau đó `withdraw` nó. "Stake / unstake", "supply / redeem", "tip / claim" có cùng dạng.

## Bạn viết gì — một két ERC-20 tiêu chuẩn

Trên Rome, USDC của người dùng Solana xuất hiện ở phía EVM như một **token ERC-20** thông thường — wrapper SPL cho mint đó (ví dụ `wUSDC`). Vì vậy, hợp đồng của bạn là một két token bình thường: nó rút token bằng `transferFrom` và trả lại chúng bằng `transfer`. Không có gì đặc thù Rome:

```solidity
interface IERC20 {
    function transfer(address to, uint256 amount) external returns (bool);
    function transferFrom(address from, address to, uint256 amount) external returns (bool);
}

contract Vault {
    IERC20 public immutable token;                 // wrapper wUSDC
    mapping(address => uint256) public balanceOf;
    constructor(IERC20 _token) { token = _token; }

    function deposit(uint256 amount) external {
        require(token.transferFrom(msg.sender, address(this), amount));
        balanceOf[msg.sender] += amount;
    }
    function withdraw(uint256 amount) external {
        balanceOf[msg.sender] -= amount;
        require(token.transfer(msg.sender, amount));
    }
}
```

> **Tại sao là ERC-20, không phải `payable` / `msg.value`?** Số dư có thể chi tiêu của người dùng Solana là **tài khoản token SPL của ví**, được hiển thị 1:1 như wrapper ERC-20 này — *không phải* số dư gas gốc EVM. Vì vậy, một người dùng Solana luôn có thể nạp cho một `transferFrom`, nhưng một `deposit() payable` sẽ cần giá trị gốc mà họ không nắm giữ sẵn. Hãy xây dựng quanh token và cả hai luồng sẽ hoạt động như nhau.

Triển khai nó bằng Foundry hoặc Hardhat, trỏ constructor tới địa chỉ wrapper cho token của bạn (từ [registry](https://github.com/rome-protocol/rome-registry)). Trên Rome, gas token là USDC, nên bạn cần một ít số dư gas USDC để triển khai.

## Hai luồng

| Luồng      | Ví                                           | Ứng dụng gọi nó như thế nào                                                    |
| ---------- | -------------------------------------------- | ------------------------------------------------------------------------------ |
| **EVM**    | MetaMask (một khóa EVM)                      | `submitRomeTx` — thao tác ghi chuẩn của Rome                                   |
| **Solana** | một ví Solana như Solflare (một khóa Solana) | `submitRomeTxV1` — một giao dịch Solana v1 cho mỗi lần gọi, không cần khóa EVM |

Luồng EVM là bình thường. Phần còn lại của trang này là **luồng Solana** — nửa thú vị.

## Ý tưởng chính: tài sản tổng hợp là một đường chuyển tiếp

Danh tính EVM của một người dùng Solana là **địa chỉ tổng hợp** — `keccak256(solana_pubkey)[12:]`. Nó là `msg.sender` trong hợp đồng, nhưng **nó không nắm giữ gì khi ở trạng thái nghỉ.** Tiền của người dùng nằm trong **ví Solana** (dưới dạng SPL USDC), và ở phía EVM, số dư đó chính là thứ `wUSDC.balanceOf(synthetic)` đọc được. Giá trị chảy *qua* qua tài khoản tổng hợp:

* **Trong** (nạp): tài khoản token của ví → tài khoản token của tài khoản tổng hợp → hợp đồng (thông qua `transferFrom`).
* **Ra** (rút): hợp đồng → tài khoản token của tài khoản tổng hợp → tài khoản token của ví.

Tài khoản tổng hợp được triệt tiêu về 0 sau mỗi lượt đi-về.

## Một lần: Kích hoạt (cấp phát tài khoản tổng hợp)

Một tài khoản mới tinh của tài khoản tổng hợp trên chuỗi chưa tồn tại cho đến khi bạn tạo nó. Lần đầu tiên người dùng Solana hành động, tài khoản tổng hợp của họ được **cấp phát** bằng một `create_pda` gọi — sau đó, các lệnh di chuyển giá trị (lệnh ERC-20 `transferFrom`, sweep) có thể được nó ký.

`submitRomeTxV1` không làm điều này cho bạn, vì vậy hãy cấp phát rõ ràng, một lần, trước lần gọi di chuyển giá trị đầu tiên. Một nơi tốt là bước "Kích hoạt", hoặc ngay trước lần approve đầu tiên:

```javascript
import { submitRomeTxV1, isSyntheticProvisioned, buildCreatePdaCall, syntheticAddress } from "@rome-protocol/sdk";

const synthetic = syntheticAddress(wallet.publicKey);
const deps = { connection, proxyUrl, chainId, programId, signer }; // signer: một Keypair trong script, một LaneSigner trong ứng dụng ví
if (!(await isSyntheticProvisioned(connection, programId, synthetic))) {
  await submitRomeTxV1(deps, buildCreatePdaCall(synthetic)); // một create_pda
}
```

## Một lần: cấp quyền cho wrapper

Wrapper wUSDC di chuyển token của người dùng như là **delegate SPL** của tài khoản token của họ, vì vậy mỗi người dùng phải cấp cho nó quyền đó một lần cho mỗi wrapper, trước lần nạp đầu tiên. Điều này áp dụng cho cả người dùng MetaMask lẫn địa chỉ tổng hợp của người dùng Solana. Nếu không cấp quyền, mọi `transferFrom` lệnh ra khỏi ví đều thất bại và việc nạp sẽ hoàn nguyên với lỗi SPL `0x4` (không khớp chủ sở hữu).

Kiểm tra bằng hàm view của wrapper `isEnabled(user)`. Nếu nó trả về `false`, hãy gửi `approve_spl(wrapper, 2^64-1, mint)` trực tiếp tới precompile Helper tại `0xff00000000000000000000000000000000000009`; mint là `mint_id()` trên wrapper. Ở luồng EVM đó là một `submitRomeTx` gọi, ở luồng Solana là một `submitRomeTxV1` gọi:

```javascript
import { submitRomeTx, submitRomeTxV1, syntheticAddress } from "@rome-protocol/sdk";
import { createPublicClient, encodeFunctionData, http, parseAbi } from "viem";

const HELPER = "0xff00000000000000000000000000000000000009";
const wrapperAbi = parseAbi(["function isEnabled(address user) view returns (bool)", "function mint_id() view returns (bytes32)"]);
const grantAbi = parseAbi(["function approve_spl(address spender, uint64 amount, bytes32 mint)"]);

const publicClient = createPublicClient({ transport: http(rpcUrl) }); // một client viem trên RPC của chuỗi

// ai: địa chỉ MetaMask, hoặc syntheticAddress(wallet.publicKey) cho người dùng Solana
let grant = null; // giữ null khi isEnabled là true
if (!(await publicClient.readContract({ address: wUSDC, abi: wrapperAbi, functionName: "isEnabled", args: [who] }))) {
  const mint = await publicClient.readContract({ address: wUSDC, abi: wrapperAbi, functionName: "mint_id" });
  grant = { to: HELPER, data: encodeFunctionData({ abi: grantAbi, functionName: "approve_spl", args: [wUSDC, 2n ** 64n - 1n, mint] }) };
}
// Luồng EVM:    nếu có grant thì await submitRomeTx(provider, { from: who, ...grant });
// Luồng Solana: nếu có grant thì await submitRomeTxV1(deps, grant);
```

## Mỗi bên cần gì

|                               | Cần                                                                       | Tại sao                                                                                                                    |
| ----------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Người dùng Solana**         | **SOL** (một ít)                                                          | trả phí giao dịch Solana cho mỗi tx trên luồng                                                                             |
|                               | **USDC dưới dạng token SPL** trong ví của họ                              | giá trị họ nạp (được thấy ở phía EVM như `wUSDC`)                                                                          |
| **Người dùng EVM (MetaMask)** | **USDC** như số dư gas Rome của họ                                        | gas, và giá trị họ nạp sau khi được wrap; họ nạp thêm bằng cách **bridge USDC** vào Rome (không có faucet)                 |
|                               | một **wrap** một phần trong số gas đó thành **wUSDC** (`withdraw_to_ata`) | két nhận wUSDC, wrapper ERC-20, chứ không phải gas gốc. Số dư USDC gas của MetaMask không phải wUSDC cho đến khi được wrap |
|                               | quyền wrapper **một lần** (`approve_spl`)                                 | cho phép wrapper wUSDC di chuyển token của họ; xem [Một lần: cấp quyền cho wrapper](#one-time-grant-the-wrapper)           |
| **Bạn (người xây dựng)**      | một ví với **USDC** gas trên Rome                                         | để triển khai hợp đồng                                                                                                     |

## Giá trị VÀO — nạp (từng bước)

Người dùng Solana có SOL + USDC trong ví Solana của họ. Mỗi bước là một giao dịch Solana v1, **được ký bởi ví đó**, và ứng dụng gửi nó tới Solana RPC. Chặng fund được dựng trong ứng dụng và ví ký nó chỉ với một lời nhắc; mỗi lệnh hợp đồng được proxy ghép lại, và ví ký nó sau một thông điệp ủy quyền có thể đọc được:

1. **Chặng nạp** — `buildFundLeg(...)` → `submitSolanaInstructionsV1(...)`. Tạo tài khoản token USDC của tài khoản tổng hợp (nếu cần) và chạy **`ActivateAta`**, chuyển `amount` USDC từ tài khoản token của ví **vào**. Bây giờ `wUSDC.balanceOf(synthetic)` hiển thị số dư đó.
2. **Cấp quyền cho wrapper** (khi `isEnabled` là sai) — `submitRomeTxV1(deps, { to: HELPER, data: approve_spl(wUSDC, 2^64-1, mint) })`. Xem [Một lần: cấp quyền cho wrapper](#one-time-grant-the-wrapper). *(Cấp phát tài khoản tổng hợp trước bước này nếu đây là lần gọi luồng đầu tiên của người dùng.)*
3. **Phê duyệt** — `submitRomeTxV1(deps, { to: wUSDC, data: approve(vault, amount) })`. Cho phép két kéo token.
4. **Nạp** — `submitRomeTxV1(deps, { to: vault, data: deposit(amount) })`. Két chạy `transferFrom(synthetic, vault, amount)` — USDC chuyển từ tài khoản tổng hợp vào két, được ghi có cho địa chỉ của tài khoản tổng hợp.

**Tác động ròng:** USDC đi **ví Solana → (tổng hợp) → két.**

```javascript
import { syntheticAddress, buildFundLeg, submitSolanaInstructionsV1, submitRomeTxV1 } from "@rome-protocol/sdk";
import { encodeFunctionData, erc20Abi } from "viem";

const synthetic = syntheticAddress(wallet.publicKey);
const deps = { connection, proxyUrl, chainId, programId, signer }; // signer: một LaneSigner (payer, signAuthHash, signV1Wire) hoặc một Keypair

// 1) chặng nạp — USDC từ ví → tài khoản token của tài khoản tổng hợp (ví ký)
await submitSolanaInstructionsV1(
  buildFundLeg({ programId, chainId, mint: usdcMint, amount: depositAmount, wallet: wallet.publicKey, synthetic }),
  { connection, signer },
);

// 2) cấp quyền cho wrapper, một lần (tài khoản tổng hợp đã được cấp phát rồi); `grant` là lệnh được dựng dưới mục "Một lần: Cấp quyền cho wrapper", hoặc null khi isEnabled là true
if (grant) await submitRomeTxV1(deps, grant);

// 3) phê duyệt két
await submitRomeTxV1(deps, { to: wUSDC, data: encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [vault, depositAmount] }) });

// 4) nạp — két kéo qua transferFrom
await submitRomeTxV1(deps, { to: vault, data: encodeFunctionData({ abi, functionName: "deposit", args: [depositAmount] }) });
```

## Giá trị RA — rút (từng bước)

Bây giờ người dùng rút. Cũng do ví ký, hai lời nhắc cho mỗi lần gọi:

1. **Withdraw** — `submitRomeTxV1(deps, { to: vault, data: withdraw(amount) })`. `vault.withdraw` chạy `transfer(synthetic, amount)` — USDC chuyển từ két trở lại **tài khoản token của** tổng hợp.
2. **Chặng sweep** — `buildSweepLeg(...)` cho bạn `HelperProgram.transfer_spl` lệnh + các tài khoản; chạy nó (tạo tài khoản token của ví nếu cần bằng `submitSolanaInstructionsV1`, rồi gửi lệnh Helper qua `submitRomeTxV1`; proxy sẽ tìm các tài khoản token) để chuyển USDC từ tài khoản tổng hợp **trở lại ví Solana riêng của người dùng**. Tài khoản tổng hợp được triệt tiêu về 0.

**Tác động ròng:** USDC đi **két → (tổng hợp) → ví Solana của người dùng.** Không có gì bị mắc kẹt.

```javascript
import { buildSweepLeg } from "@rome-protocol/sdk";

// 1) rút — két trả USDC về tài khoản token của tài khoản tổng hợp
await submitRomeTxV1(deps, { to: vault, data: encodeFunctionData({ abi, functionName: "withdraw", args: [amount] }) });

// 2) chặng sweep — tài khoản token của tài khoản tổng hợp → tài khoản token của chính ví người dùng
const sweep = buildSweepLeg({ programId, mint: usdcMint, amount, wallet: wallet.publicKey, synthetic });
await submitSolanaInstructionsV1([sweep.ensureWalletAtaIx], { connection, signer });
await submitRomeTxV1(deps, { to: sweep.helperTo, data: sweep.calldata });
```

## Đo trên Hadrian

Mỗi bước ở luồng Solana bên dưới đã chạy như một giao dịch phiên bản 1 trên Hadrian:

| Bước                                  | Đơn vị tính toán | Byte  | Tài khoản |
| ------------------------------------- | ---------------- | ----- | --------- |
| Cấp phát (`create_pda`)               | 39,008           | 703   | 9         |
| Cấp quyền của wrapper (`approve_spl`) | 50,687           | 899   | 13        |
| Phê duyệt                             | 79,335           | 769   | 10        |
| Nạp vào két                           | 242,880          | 1,070 | 20        |
| Rút khỏi két                          | 280,903          | 1,037 | 19        |
| Sweep (`transfer_spl`)                | 46,810           | 899   | 13        |

## Những bẫy thường gặp

Đây là những thứ một giao dịch luồng Solana tự viết tay rất dễ làm sai. SDK và bộ ghép của proxy xử lý phần lớn trong số đó:

* **Cấp phát.** Tài khoản của một tài khoản tổng hợp mới phải được tạo (`create_pda`) trước bất kỳ lệnh di chuyển giá trị nào, nếu không nó không thể ký chuyển tiền. `submitRomeTxV1` không làm điều đó cho bạn: hãy kiểm tra `isSyntheticProvisioned` và gửi `buildCreatePdaCall(synthetic)` một lần.
* **Cấp quyền cho wrapper một lần.** Wrapper di chuyển token như một đại diện SPL của người dùng. Kiểm tra `isEnabled` và gửi `approve_spl` tới precompile Helper trước lần nạp đầu tiên, nếu không lệnh nạp sẽ hoàn nguyên với lỗi SPL `0x4`.
* **Chi tiêu wrapper, không phải `msg.value`.** Số dư của một người dùng Solana là tài khoản token SPL của họ, được hiển thị dưới dạng wrapper ERC-20 — hãy di chuyển nó bằng `transfer` / `transferFrom`, tuyệt đối không dùng giá trị gốc.
* **Đã được ghép cho bạn.** ComputeBudget, treasure wallet và việc dò tìm tài khoản đều do bộ ghép của proxy đảm nhiệm, nên không cái nào xuất hiện trong mã của bạn. Trước khi ví ký, SDK kiểm tra giao dịch đã ghép và từ chối mọi thứ ngoài lệnh mà người dùng đã ủy quyền.
* **Nó được gửi đi đâu.** Ví ký giao dịch v1 và **ứng dụng gửi nó tới Solana RPC** — không phải tới proxy, vốn là nơi ghép nó lại (một lệnh được relay là ngoại lệ duy nhất, bên dưới; xem [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)). Trên chuỗi, chương trình suy ra `msg.sender` từ người ký Solana.
* **Hai lời nhắc cho mỗi lần gọi.** Ví ký một thông điệp ủy quyền có thể đọc được (`Rome authorization` và mã băm giao dịch EVM), rồi ký chính giao dịch đó, cả hai bằng cùng một khóa.
* **Kiểm tra ví của bạn có ký v1.** `signV1Wire` phải trả về chữ ký 64 byte trên thông điệp v1; qua Wallet Standard thì đó là `solana:signTransaction` trên wire thô và `signedTransaction.slice(-64)`. Không phải ví nào cũng đã giải mã được giao dịch v1, vì vậy hãy thử ví của bạn trước khi xây dựng trên đó. Hiện nay trên devnet, Solflare ký được; Phantom thì chưa.
* **Các lệnh lớn sẽ được relay.** Một lệnh không vừa trong một giao dịch sẽ được proxy relay với cùng chữ ký ủy quyền, và kết quả có `route: "relay"`. Một lệnh được relay được thanh toán bằng gas gốc của chuỗi, vì vậy hãy nạp thêm cho tài khoản tổng hợp bằng `fundSyntheticGas(deps, amountWei)`. Xem [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).
* **Gas là USDC.** Không có faucet — hãy bridge USDC vào (xem [Được cấp vốn](https://docs.rome.builders/vi/tai-nguyen/faucets.md)).

Lệnh `submitRomeTxSolanaLane` vẫn còn trong SDK: nó dựng một giao dịch Solana kiểu cũ ở client (một lời nhắc ví, với ComputeBudget và treasure wallet do SDK xử lý).

## Ứng dụng tương tự từ MetaMask

Một người dùng EVM gọi cùng hợp đồng với `submitRomeTx` — công cụ EVM tiêu chuẩn, gas bằng USDC. Có một khác biệt so với người dùng Solana: một người dùng MetaMask nắm giữ **USDC gas gốc**, chứ không phải wUSDC. Két nhận wrapper wUSDC, vì vậy người dùng trước tiên wrap một phần gas của họ, sau đó cấp quyền wrapper một lần, rồi làm các bước ERC-20 như thường lệ. Không có chặng fund hay sweep, vì các token đã wrap vốn đã nằm tại địa chỉ EVM của họ.

1. **Wrap gas thành wUSDC** — gửi `withdraw_to_ata(wei)` tới precompile Withdraw tại `0x4200000000000000000000000000000000000016`. Nó đốt lượng gas gốc đó và ghi có số lượng tương đương vào tài khoản token của người dùng bằng token gas, mà `wUSDC.balanceOf(user)` rồi hiển thị. `wei` nằm trong đơn vị gas 18 chữ số và phải là bội số của 10^12 (một đơn vị wUSDC 6 chữ số), nếu không lệnh sẽ hoàn nguyên. Bỏ qua bước này nếu người dùng đã nắm giữ wUSDC.
2. **Cấp quyền cho wrapper** (khi `isEnabled` là sai) — cùng `approve_spl` lệnh như trên, được gửi với `submitRomeTx`. Xem [Một lần: cấp quyền cho wrapper](#one-time-grant-the-wrapper).
3. **Phê duyệt** — `approve(vault, amount)` trên wUSDC.
4. **Nạp** — `deposit(amount)` trên két. Rút là `withdraw(amount)`.

```javascript
import { submitRomeTx } from "@rome-protocol/sdk";
import { encodeFunctionData, erc20Abi, parseAbi } from "viem";

const WITHDRAW = "0x4200000000000000000000000000000000000016";
const withdrawAbi = parseAbi(["function withdraw_to_ata(uint256 wei_)"]);

// 1) wrap một phần USDC gas thành wUSDC (weiAmount tính theo đơn vị gas 18 chữ số)
await submitRomeTx(provider, { from: who, to: WITHDRAW, data: encodeFunctionData({ abi: withdrawAbi, functionName: "withdraw_to_ata", args: [weiAmount] }) });

// 2) cấp quyền cho wrapper, một lần: `grant` là lệnh được dựng dưới mục "Một lần: Cấp quyền cho wrapper", hoặc null
if (grant) await submitRomeTx(provider, { from: who, ...grant });

// 3) phê duyệt và 4) nạp, như với bất kỳ ERC-20 nào
await submitRomeTx(provider, { from: who, to: wUSDC, data: encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [vault, depositAmount] }) });
await submitRomeTx(provider, { from: who, to: vault, data: encodeFunctionData({ abi, functionName: "deposit", args: [depositAmount] }) });
```

Cả hai người dùng chia sẻ cùng `balanceOf` trạng thái trong két.

## Tiếp theo là gì

* [Gọi EVM từ Solana](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/call-evm-from-solana.md) — cơ chế luồng Solana chi tiết
* [Gọi Solana từ EVM](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/call-solana-from-evm.md) — hướng còn lại (CPI)
* [Được cấp vốn](https://docs.rome.builders/vi/tai-nguyen/faucets.md) — USDC là gas token; bridge nó vào


---

# 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/dual-lane-app.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.
