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

# Bangun aplikasi dua jalur

Panduan langkah demi langkah sebuah aplikasi dua jalur — satu kontrak Solidity yang digunakan oleh pengguna MetaMask dan pengguna dompet Solana, dengan penjelasan tepat tentang apa yang terjadi di setiap langkah.

Sebuah **aplikasi dua jalur** adalah satu kontrak Solidity yang digunakan oleh baik seorang **MetaMask (EVM)** pengguna dan sebuah **wallet Solana** pengguna gunakan langsung — kontrak yang sama, state yang sama, masing-masing dengan dompet yang sudah mereka miliki. Halaman ini membahas *secara tepat* apa yang terjadi pada setiap langkah, di setiap sisi.

Contohnya adalah sebuah **vault**: Anda `deposit` USDC dan nanti `withdraw` menyimpannya. "Stake / unstake", "supply / redeem", "tip / claim" memiliki bentuk yang sama.

## Yang Anda tulis — sebuah vault ERC-20 standar

Di Rome, USDC milik pengguna Solana muncul di sisi EVM sebagai sebuah **token ERC-20** — pembungkus SPL untuk mint tersebut (misalnya `wUSDC`). Jadi kontrak Anda adalah vault token biasa: kontrak ini menarik token dengan `transferFrom` dan mengembalikannya dengan `transfer`. Tidak ada yang spesifik 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;                 // pembungkus 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));
    }
}
```

> **Mengapa ERC-20, bukan `payable` / `msg.value`?** Saldo yang dapat dibelanjakan oleh pengguna Solana adalah **akun token SPL milik dompet mereka**, ditampilkan 1:1 sebagai pembungkus ERC-20 ini — *bukan* saldo native EVM. Jadi pengguna Solana selalu bisa mendanai sebuah `transferFrom`, tetapi sebuah `deposit() payable` akan membutuhkan nilai native yang tidak mereka simpan saat diam. Bangunlah di sekitar token dan kedua jalur akan bekerja dengan cara yang sama.

Deploy dengan Foundry atau Hardhat, arahkan konstruktor ke alamat pembungkus untuk token Anda (dari [registry](https://github.com/rome-protocol/rome-registry)). Di Rome, token gas adalah USDC, jadi Anda memerlukan sedikit saldo gas USDC untuk melakukan deployment.

## Dua jalur

| Jalur      | Dompet                                        | Bagaimana aplikasi memanggilnya                                                  |
| ---------- | --------------------------------------------- | -------------------------------------------------------------------------------- |
| **EVM**    | MetaMask (kunci EVM)                          | `submitRomeTx` — penulisan standar Rome                                          |
| **Solana** | dompet Solana seperti Solflare (kunci Solana) | `submitRomeTxV1` — satu transaksi Solana v1 per panggilan, tanpa perlu kunci EVM |

Jalur EVM itu biasa. Sisa halaman ini adalah **jalur Solana** — bagian yang menarik.

## Gagasan utamanya: synthetic adalah jalur penerusan

Identitas EVM milik pengguna Solana adalah **alamat sintetis** — `keccak256(solana_pubkey)[12:]`. Itu adalah `msg.sender` di kontrak, tetapi **itu tidak menyimpan apa pun saat diam.** Uang pengguna berada di **wallet Solana** (sebagai SPL USDC), dan di sisi EVM saldo yang sama itulah yang dibaca oleh `wUSDC.balanceOf(synthetic)` membaca. Nilai mengalir *melalui* melalui synthetic:

* **Masuk** (deposit): akun token dompet → akun token synthetic → kontrak (melalui `transferFrom`).
* **Keluar** (withdraw): kontrak → akun token synthetic → akun token dompet.

Synthetic kembali menjadi nol setelah setiap perjalanan bolak-balik.

## Sekali saja: Aktifkan (provision synthetic)

Akun on-chain synthetic yang baru tidak ada sampai Anda membuatnya. Saat pertama kali pengguna Solana bertindak, synthetic mereka **diprovisioning** dengan sebuah `create_pda` panggilan — setelah itu, panggilan yang memindahkan nilai (ERC-20 `transferFrom`, sweep) dapat ditandatangani olehnya.

`submitRomeTxV1` tidak melakukan ini untuk Anda, jadi lakukan provision secara eksplisit, sekali, sebelum panggilan pertama yang memindahkan nilai. Tempat yang baik adalah langkah "Activate", atau tepat sebelum approve pertama:

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

const synthetic = syntheticAddress(wallet.publicKey);
const deps = { connection, proxyUrl, chainId, programId, signer }; // signer: a Keypair in scripts, a LaneSigner in a wallet app
if (!(await isSyntheticProvisioned(connection, programId, synthetic))) {
  await submitRomeTxV1(deps, buildCreatePdaCall(synthetic)); // satu create_pda
}
```

## Sekali pakai: beri wrapper

Pembungkus wUSDC memindahkan token pengguna sebagai **delegasi SPL** delegasi dari akun token mereka, jadi setiap pengguna harus memberikan hak itu sekali per pembungkus, sebelum deposit pertama. Ini berlaku baik untuk pengguna MetaMask maupun untuk alamat synthetic pengguna Solana. Tanpa pemberian hak ini, setiap `transferFrom` transfer keluar dari dompet akan gagal dan deposit dibatalkan dengan kesalahan SPL `0x4` (ketidakcocokan pemilik).

Periksa dengan tampilan pembungkus `isEnabled(user)`. Jika mengembalikan `false`, kirim `approve_spl(wrapper, 2^64-1, mint)` langsung ke precompile Helper di `0xff00000000000000000000000000000000000009`; mint-nya adalah `mint_id()` pada pembungkus. Di jalur EVM itu adalah `submitRomeTx` panggilan, di jalur Solana sebuah `submitRomeTxV1` panggilan:

```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) }); // klien viem pada RPC chain

// siapa: alamat MetaMask, atau syntheticAddress(wallet.publicKey) untuk pengguna Solana
let grant = null; // tetap null ketika isEnabled bernilai 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] }) };
}
// Jalur EVM:    if (grant) await submitRomeTx(provider, { from: who, ...grant });
// Jalur Solana: if (grant) await submitRomeTxV1(deps, grant);
```

## Yang dibutuhkan masing-masing sisi

|                             | Membutuhkan                                                                         | Mengapa                                                                                                                           |
| --------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Pengguna Solana**         | **SOL** (sedikit)                                                                   | membayar biaya transaksi Solana pada setiap tx jalur                                                                              |
|                             | **USDC sebagai token SPL** di dompet mereka                                         | nilai yang mereka setorkan (terlihat di sisi EVM sebagai `wUSDC`)                                                                 |
| **Pengguna EVM (MetaMask)** | **USDC** sebagai saldo gas Rome mereka                                              | gas, dan nilai yang mereka setorkan setelah dibungkus; mereka menambahnya dengan **menjembatani USDC** ke Rome (tidak ada faucet) |
|                             | sebuah **pembungkusan** sebagian dari gas itu menjadi **wUSDC** (`withdraw_to_ata`) | vault menerima wUSDC, pembungkus ERC-20, bukan gas native. Saldo gas USDC di MetaMask bukan wUSDC sampai dibungkus                |
|                             | sekali saja **pemberian hak pembungkus** (`approve_spl`)                            | memungkinkan pembungkus wUSDC memindahkan token mereka; lihat [Sekali pakai: beri wrapper](#one-time-grant-the-wrapper)           |
| **Anda (pembuatnya)**       | dompet dengan **USDC** gas di Rome                                                  | untuk melakukan deployment kontrak                                                                                                |

## Nilai MASUK — deposit (langkah demi langkah)

Pengguna Solana memiliki SOL + USDC di dompet Solana mereka. Setiap langkah adalah transaksi Solana v1, **ditandatangani oleh dompet itu**, dan aplikasi mengirimnya ke RPC Solana. Bagian pendanaan dibuat di aplikasi dan dompet menandatanganinya dengan satu prompt; setiap panggilan kontrak disusun oleh proxy, dan dompet menandatanganinya setelah pesan otorisasi yang dapat dibaca:

1. **Bagian pendanaan** — `buildFundLeg(...)` → `submitSolanaInstructionsV1(...)`. Membuat akun token USDC milik synthetic (jika perlu) dan menjalankan **`ActivateAta`**, memindahkan `jumlah` USDC dari akun token dompet **ke**. Sekarang `wUSDC.balanceOf(synthetic)` menampilkan saldo itu.
2. **Berikan hak ke pembungkus** (ketika `isEnabled` bernilai false) — `submitRomeTxV1(deps, { to: HELPER, data: approve_spl(wUSDC, 2^64-1, mint) })`. Lihat [Sekali pakai: beri wrapper](#one-time-grant-the-wrapper). *(Lakukan provision synthetic sebelum ini jika ini adalah panggilan jalur pertama pengguna.)*
3. **Setujui** — `submitRomeTxV1(deps, { to: wUSDC, data: approve(vault, amount) })`. Memungkinkan vault menarik token.
4. **Setoran** — `submitRomeTxV1(deps, { to: vault, data: deposit(amount) })`. Vault menjalankan `transferFrom(synthetic, vault, amount)` — USDC berpindah dari synthetic ke vault, dikreditkan ke alamat synthetic.

**Efek bersih:** USDC berpindah **dompet Solana → (synthetic) → vault.**

```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: a LaneSigner (payer, signAuthHash, signV1Wire) or a Keypair

// 1) bagian pendanaan — USDC dompet → akun token synthetic (dompet menandatangani)
await submitSolanaInstructionsV1(
  buildFundLeg({ programId, chainId, mint: usdcMint, amount: depositAmount, wallet: wallet.publicKey, synthetic }),
  { connection, signer },
);

// 2) berikan hak ke pembungkus, sekali (synthetic sudah diprovisioning); `grant` adalah panggilan yang dibuat di bawah "Sekali saja: berikan hak ke pembungkus", atau null saat isEnabled bernilai true
if (grant) await submitRomeTxV1(deps, grant);

// 3) setujui vault
await submitRomeTxV1(deps, { to: wUSDC, data: encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [vault, depositAmount] }) });

// 4) deposit — vault menarik melalui transferFrom
await submitRomeTxV1(deps, { to: vault, data: encodeFunctionData({ abi, functionName: "deposit", args: [depositAmount] }) });
```

## Nilai KELUAR — withdraw (langkah demi langkah)

Sekarang pengguna melakukan withdraw. Juga ditandatangani dompet, dua prompt per panggilan:

1. **Withdraw** — `submitRomeTxV1(deps, { to: vault, data: withdraw(amount) })`. `vault.withdraw` menjalankan `transfer(synthetic, amount)` — USDC berpindah dari vault kembali ke **milik synthetic** akun token.
2. **Bagian sweep** — `buildSweepLeg(...)` memberi Anda `HelperProgram.transfer_spl` panggilan + akun; jalankan (buat akun token dompet jika perlu dengan `submitSolanaInstructionsV1`, lalu kirim panggilan Helper melalui `submitRomeTxV1`; proxy menemukan akun token) untuk memindahkan USDC dari synthetic **kembali ke dompet Solana milik pengguna**. Synthetic kembali menjadi nol.

**Efek bersih:** USDC berpindah **vault → (synthetic) → dompet Solana milik pengguna.** Tidak ada yang tertinggal.

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

// 1) withdraw — vault mengembalikan USDC ke akun token synthetic
await submitRomeTxV1(deps, { to: vault, data: encodeFunctionData({ abi, functionName: "withdraw", args: [amount] }) });

// 2) bagian sweep — akun token synthetic → akun token dompet milik pengguna sendiri
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 });
```

## Diukur di Hadrian

Setiap langkah jalur Solana di bawah ini dijalankan sebagai satu transaksi versi-1 di Hadrian:

| Langkah                           | Unit komputasi | Byte  | Akun |
| --------------------------------- | -------------- | ----- | ---- |
| Provision (`create_pda`)          | 39,008         | 703   | 9    |
| Pemberian wrapper (`approve_spl`) | 50,687         | 899   | 13   |
| Setujui                           | 79,335         | 769   | 10   |
| Deposit vault                     | 242,880        | 1,070 | 20   |
| Withdraw vault                    | 280,903        | 1,037 | 19   |
| Sweep (`transfer_spl`)            | 46,810         | 899   | 13   |

## Hal-hal yang perlu diperhatikan

Inilah hal-hal yang sering salah dalam transaksi jalur Solana yang dibuat manual. SDK dan komposer proxy menangani sebagian besar di antaranya:

* **Provisioning.** Akun synthetic baru harus dibuat (`create_pda`) sebelum panggilan yang memindahkan nilai apa pun, kalau tidak ia tidak `submitRomeTxV1` tidak melakukannya untuk Anda: periksa `isSyntheticProvisioned` dan kirim `buildCreatePdaCall(synthetic)` sekali.
* **Berikan hak ke pembungkus sekali.** Pembungkus memindahkan token sebagai delegasi SPL pengguna. Periksa `isEnabled` dan kirim `approve_spl` ke precompile Helper sebelum deposit pertama, atau deposit dibatalkan dengan kesalahan SPL `0x4`.
* **Gunakan pembungkus, bukan `msg.value`.** Saldo pengguna Solana adalah akun token SPL mereka, ditampilkan sebagai pembungkus ERC-20 — pindahkan dengan `transfer` / `transferFrom`, bukan nilai native.
* **Disusun untuk Anda.** ComputeBudget, dompet treasury, dan penemuan akun dilakukan oleh komposer proxy, jadi tidak satu pun muncul di kode Anda. Sebelum dompet menandatangani, SDK memeriksa transaksi yang disusun dan menolak apa pun selain panggilan yang diotorisasi pengguna.
* **Ke mana dikirim.** Dompet menandatangani transaksi v1 dan **aplikasi mengirimnya ke RPC Solana** — bukan ke proxy, yang menyusunnya (panggilan yang direlay adalah satu pengecualian, di bawah; lihat [Panggilan yang direlay dan panggilan panjang](https://docs.rome.builders/id/panduan-pengembang/call-evm-from-solana.md#relayed-calls-and-long-calls)). Di on-chain, program menurunkan `msg.sender` dari penandatangan Solana.
* **Dua prompt per panggilan.** Dompet menandatangani pesan otorisasi yang dapat dibaca (`Otorisasi Rome` dan hash transaksi EVM), lalu transaksi, keduanya dengan kunci yang sama.
* **Periksa bahwa dompet Anda menandatangani v1.** `signV1Wire` harus mengembalikan tanda tangan 64-byte atas pesan v1; melalui Wallet Standard itu adalah `solana:signTransaction` pada wire mentah dan `signedTransaction.slice(-64)`. Belum semua dompet dapat mendekode transaksi v1, jadi uji dompet Anda sebelum membangunnya. Di devnet saat ini, Solflare menandatanganinya; Phantom belum.
* **Panggilan besar direlay.** Panggilan yang tidak muat dalam satu transaksi direlay oleh proxy dengan tanda tangan otorisasi yang sama, dan hasilnya memiliki `route: "relay"`. Panggilan yang direlay dibayar dalam gas native chain, jadi isi ulang synthetic dengan `fundSyntheticGas(deps, amountWei)`. Lihat [Panggilan yang direlay dan panggilan panjang](https://docs.rome.builders/id/panduan-pengembang/call-evm-from-solana.md#relayed-calls-and-long-calls).
* **Gas adalah USDC.** Tidak ada faucet — jembatani USDC masuk (lihat [Mendapatkan pendanaan](https://docs.rome.builders/id/sumber-daya/faucets.md)).

Yang sebelumnya `submitRomeTxSolanaLane` masih ada di SDK: ini membangun transaksi Solana legasi di klien (satu prompt dompet, dengan ComputeBudget dan dompet treasury ditangani oleh SDK).

## Aplikasi yang sama dari MetaMask

Pengguna EVM memanggil kontrak yang identik dengan `submitRomeTx` — tooling EVM standar, gas dalam USDC. Satu perbedaan dari pengguna Solana: pengguna MetaMask memegang **gas native USDC**, bukan wUSDC. Vault menerima pembungkus wUSDC, jadi pengguna membungkus sebagian gas mereka terlebih dahulu, lalu memberikan hak ke pembungkus sekali, lalu melakukan langkah ERC-20 seperti biasa. Tidak ada bagian pendanaan atau sweep, karena token yang dibungkus sudah berada di alamat EVM mereka.

1. **Bungkus gas menjadi wUSDC** — kirim `withdraw_to_ata(wei)` ke precompile Withdraw di `0x4200000000000000000000000000000000000016`. Ini membakar gas native sebanyak itu dan mengkreditkan jumlah ekuivalen ke akun token pengguna dalam gas token, yang `wUSDC.balanceOf(user)` lalu muncul. `wei` berada dalam unit gas 18 desimal dan harus kelipatan 10^12 (satu unit wUSDC 6 desimal), atau panggilan dibatalkan. Lewati langkah ini jika pengguna sudah memegang wUSDC.
2. **Berikan hak ke pembungkus** (ketika `isEnabled` bernilai false) — panggilan yang sama `approve_spl` seperti di atas, dikirim dengan `submitRomeTx`. Lihat [Sekali pakai: beri wrapper](#one-time-grant-the-wrapper).
3. **Setujui** — `approve(vault, amount)` pada wUSDC.
4. **Setoran** — `deposit(amount)` pada vault. Withdraw adalah `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) bungkus sebagian gas USDC menjadi wUSDC (weiAmount dalam unit gas 18 desimal)
await submitRomeTx(provider, { from: who, to: WITHDRAW, data: encodeFunctionData({ abi: withdrawAbi, functionName: "withdraw_to_ata", args: [weiAmount] }) });

// 2) berikan hak ke pembungkus, sekali: `grant` adalah panggilan yang dibuat di bawah "Sekali saja: berikan hak ke pembungkus", atau null
if (grant) await submitRomeTx(provider, { from: who, ...grant });

// 3) setujui dan 4) deposit, seperti ERC-20 apa pun
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] }) });
```

Kedua pengguna berbagi `balanceOf` state di vault.

## Langkah berikutnya

* [Panggil EVM dari Solana](https://docs.rome.builders/id/panduan-pengembang/call-evm-from-solana.md) — mekanisme jalur Solana secara rinci
* [Panggil Solana dari EVM](https://docs.rome.builders/id/panduan-pengembang/call-solana-from-evm.md) — arah lainnya (CPI)
* [Mendapatkan pendanaan](https://docs.rome.builders/id/sumber-daya/faucets.md) — USDC sebagai token gas; jembatani masuk


---

# 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/id/panduan-pengembang/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.
