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

# Eine Dual-Lane-App bauen

Eine Schritt-für-Schritt-Anleitung für eine Dual-Lane-App — ein Solidity-Vertrag, der sowohl von einem MetaMask-Nutzer als auch von einem Solana-Wallet-Nutzer verwendet wird, mit genau dem, was bei jedem Schritt passiert.

Eine **Dual-Lane-App** ist ein Solidity-Vertrag, den sowohl ein **MetaMask (EVM)** Benutzer und ein **Solana-Wallet** Benutzer direkt verwenden — derselbe Vertrag, derselbe Zustand, jeder mit der Wallet, die er bereits hat. Diese Seite führt durch *genau* was bei jedem Schritt auf jeder Seite passiert.

Das Beispiel ist ein kleiner **Vault**: du `Deposit` USDC und später `withdraw` es. „Stake / unstake“, „supply / redeem“, „tip / claim“ haben die gleiche Struktur.

## Was du schreibst — ein standardmäßiger ERC-20-Vault

Auf Rome erscheint das USDC eines Solana-Benutzers auf der EVM-Seite als ein gewöhnlicher **ERC-20-Token** — der SPL-Wrapper für diesen Mint (z. B. `wUSDC`). Daher ist dein Vertrag ein normaler Token-Vault: Er zieht Token mit `transferFrom` und gibt sie zurück mit `transfer`.

```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;                 // der wUSDC-Wrapper
    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));
    }
}
```

> **Warum ERC-20 und nicht `payable` / `msg.value`?** Das verfügbare Guthaben eines Solana-Benutzers ist sein **SPL-Token-Konto der Wallet**, 1:1 als dieser ERC-20-Wrapper dargestellt — *nicht* das native EVM-Guthaben. Daher kann ein Solana-Benutzer immer ein `transferFrom`, aber ein `deposit() payable` nativen Wert benötigen, den sie im Ruhezustand nicht halten. Baue um den Token herum, und beide Lanes funktionieren gleich.

Deploye es mit Foundry oder Hardhat und richte den Konstruktor auf die Wrapper-Adresse deines Tokens aus (aus dem [Registry](https://github.com/rome-protocol/rome-registry)). Auf Rome ist der Gas-Token USDC, daher brauchst du zum Deployen ein kleines USDC-Guthaben für Gas.

## Die beiden Lanes

| Lane       | Wallet                                                 | Wie die App es aufruft                                                                    |
| ---------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| **EVM**    | MetaMask (ein EVM-Schlüssel)                           | `submitRomeTx` — der standardmäßige Rome-Schreibvorgang                                   |
| **Solana** | eine Solana-Wallet wie Solflare (ein Solana-Schlüssel) | `submitRomeTxV1` — eine Solana-v1-Transaktion pro Aufruf, kein EVM-Schlüssel erforderlich |

Die EVM-Lane ist gewöhnlich. Der Rest dieser Seite ist der **Solana-Weg** — die interessante Hälfte.

## Die Grundidee: das Synthetic ist ein Pass-Through

Die EVM-Identität eines Solana-Benutzers ist seine **synthetische Adresse** — `keccak256(solana_pubkey)[12:]`. Es ist ihre `msg.sender` im Vertrag, aber **es hält im Ruhezustand nichts.** Das Geld des Benutzers liegt in seinem **Solana-Wallet** (als SPL-USDC), und auf der EVM-Seite ist genau dieses Guthaben das, was `wUSDC.balanceOf(synthetic)` ausliest. Der Wert fließt *durch* über das Synthetic:

* **In** (Einzahlung): Wallet-Token-Konto → Synthetic-Token-Konto → Vertrag (über `transferFrom`).
* **Aus** (Auszahlung): Vertrag → Synthetic-Token-Konto → Wallet-Token-Konto.

Das Synthetic gleicht sich nach jedem Hin- und Rückweg wieder auf null aus.

## Einmalig: Aktivieren (das Synthetic bereitstellen)

Das On-Chain-Konto eines brandneuen Synthetic existiert nicht, bis du es erstellst. Wenn ein Solana-Benutzer zum ersten Mal handelt, wird sein Synthetic **bereitgestellt** mit einem `create_pda` -Aufruf bereitgestellt — danach können wertbewegende Aufrufe (der ERC-20 `transferFrom`, der Sweep) von ihm signiert werden.

`submitRomeTxV1` tut das nicht für dich, also stelle es explizit und einmal vor dem ersten wertbewegenden Aufruf bereit. Ein guter Ort ist ein „Aktivieren“-Schritt oder direkt vor dem ersten approve:

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

const synthetic = syntheticAddress(wallet.publicKey);
const deps = { connection, proxyUrl, chainId, programId, signer }; // signer: ein Keypair in Skripten, ein LaneSigner in einer Wallet-App
if (!(await isSyntheticProvisioned(connection, programId, synthetic))) {
  await submitRomeTxV1(deps, buildCreatePdaCall(synthetic)); // one create_pda
}
```

## Einmalig: dem Wrapper gewähren

Der wUSDC-Wrapper bewegt die Token eines Benutzers als der **SPL-Delegierter** Delegierte ihres Token-Kontos, daher muss jeder Benutzer ihm dieses Recht einmal pro Wrapper vor der ersten Einzahlung gewähren. Das gilt gleichermaßen für einen MetaMask-Benutzer und für die Synthetic-Adresse eines Solana-Benutzers. Ohne die Erlaubnis schlägt jeder `transferFrom` Transfer aus der Wallet fehl und die Einzahlung wird mit dem SPL-Fehler `0x4` (Besitzer stimmt nicht überein).

Prüfe mit der View-Funktion des Wrappers `isEnabled(user)`. Wenn sie zurückgibt `false`, sende `approve_spl(wrapper, 2^64-1, mint)` direkt an das Helper-Precompile bei `0xff00000000000000000000000000000000000009`; `mint_id()` der Mint ist `submitRomeTx` am Wrapper. Auf der EVM-Lane ist das ein `submitRomeTxV1` Aufruf, auf der Solana-Lane ein

```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)"]);

// ein viem-Client auf dem RPC der Chain

// wer: die MetaMask-Adresse oder syntheticAddress(wallet.publicKey) für einen Solana-Benutzer
// bleibt null, wenn isEnabled true ist
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] }) };
}
// EVM-Lane:    if (grant) await submitRomeTx(provider, { from: who, ...grant });
// Solana-Lane: if (grant) await submitRomeTxV1(deps, grant);
```

## Was jede Seite braucht

|                             | Benötigt                                                                  | Warum                                                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Solana-Benutzer**         | **SOL** (ein wenig)                                                       | zahlt die Solana-Transaktionsgebühr für jede Lane-Transaktion                                                                                      |
|                             | **USDC als SPL-Token** in ihrer Wallet                                    | den Wert, den sie einzahlen (auf der EVM-Seite sichtbar als `wUSDC`)                                                                               |
| **EVM-Benutzer (MetaMask)** | **USDC** als ihr Rome-Gasguthaben                                         | Gas, und den Wert, den sie einzahlen, sobald er gewrappt ist; sie füllen ihn auf durch **das Bridging von USDC** nach Rome (es gibt keinen Faucet) |
|                             | ein **wrappen** eines Teils dieses Gases in **wUSDC** (`withdraw_to_ata`) | der Vault nimmt wUSDC, den ERC-20-Wrapper, nicht natives Gas. Ein MetaMask-Guthaben an Gas-USDC ist erst dann wUSDC, wenn es gewrappt wurde        |
|                             | die einmalige **Wrapper-Erlaubnis** (`approve_spl`)                       | ermöglicht es dem wUSDC-Wrapper, ihre Token zu bewegen; siehe [Einmalig: dem Wrapper gewähren](#one-time-grant-the-wrapper)                        |
| **Du (der Builder)**        | eine Wallet mit **USDC** Gas auf Rome                                     | um den Vertrag bereitzustellen                                                                                                                     |

## Wert hinein — Einzahlung (Schritt für Schritt)

Der Solana-Benutzer hat SOL + USDC in seiner Solana-Wallet. Jeder Schritt ist eine Solana-v1-Transaktion, **von dieser Wallet signiert**, und die App sendet sie an den Solana-RPC. Der Fund-Teil wird in der App erstellt und die Wallet signiert ihn mit einer Aufforderung; jeder Vertragsaufruf wird vom Proxy zusammengesetzt, und die Wallet signiert ihn nach einer lesbaren Autorisierungsnachricht:

1. **Fund-Teil** — `buildFundLeg(...)` → `submitSolanaInstructionsV1(...)`. Erstellt das USDC-Token-Konto des Synthetic (falls nötig) und führt **`ActivateAta`**, wobei `Betrag` USDC aus dem Token-Konto der Wallet **in das**. Jetzt `wUSDC.balanceOf(synthetic)` zeigt dieses Guthaben an.
2. **Gewähre dem Wrapper die Erlaubnis** (wenn `isEnabled` falsch ist) — `submitRomeTxV1(deps, { to: HELPER, data: approve_spl(wUSDC, 2^64-1, mint) })`. Siehe [Einmalig: dem Wrapper gewähren](#one-time-grant-the-wrapper). *(Stelle das Synthetic vorher bereit, wenn dies der erste Lane-Aufruf des Benutzers ist.)*
3. **Genehmigen** — `submitRomeTxV1(deps, { to: wUSDC, data: approve(vault, amount) })`. Erlaubt dem Vault, die Token abzurufen.
4. **Einzahlung** — `submitRomeTxV1(deps, { to: vault, data: deposit(amount) })`. Der Vault führt aus `transferFrom(synthetic, vault, amount)` — die USDC wandern vom Synthetic in den Vault und werden der Adresse des Synthetic gutgeschrieben.

**Nettoeffekt:** USDC ging **Solana-Wallet → (Synthetic) → der Vault.**

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

const synthetic = syntheticAddress(wallet.publicKey);
// signer: ein LaneSigner (payer, signAuthHash, signV1Wire) oder ein Keypair

// 1) Fund-Teil — Wallet-USDC → Synthetic-Token-Konto (die Wallet signiert)
await submitSolanaInstructionsV1(
  buildFundLeg({ programId, chainId, mint: usdcMint, amount: depositAmount, wallet: wallet.publicKey, synthetic }),
  { connection, signer },
);

// 2) gewähre dem Wrapper einmal die Erlaubnis (das Synthetic ist bereits bereitgestellt); `grant` ist der Aufruf, der unter „Einmalig: Gewähre dem Wrapper die Erlaubnis“ erstellt wurde, oder null, wenn isEnabled true ist
if (grant) await submitRomeTxV1(deps, grant);

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

// 4) Einzahlung — der Vault zieht per transferFrom
await submitRomeTxV1(deps, { to: vault, data: encodeFunctionData({ abi, functionName: "deposit", args: [depositAmount] }) });
```

## Wert hinaus — Auszahlung (Schritt für Schritt)

Jetzt hebt der Benutzer ab. Ebenfalls von der Wallet signiert, zwei Aufforderungen pro Aufruf:

1. **Withdraw** — `submitRomeTxV1(deps, { to: vault, data: withdraw(amount) })`. `vault.withdraw` führt aus `transfer(synthetic, amount)` — USDC wandern vom Vault zurück in das **des Synthetic** Token-Konto.
2. **Sweep-Teil** — `buildSweepLeg(...)` gibt dir den `HelperProgram.transfer_spl` Aufruf + Konten; führe ihn aus (erstelle bei Bedarf das Token-Konto der Wallet mit `submitSolanaInstructionsV1`, `submitRomeTxV1`dann sende den Helper-Aufruf über **zurück in die eigene Solana-Wallet des Benutzers**. Das Synthetic gleicht sich auf null aus.

**Nettoeffekt:** USDC ging **der Vault → (Synthetic) → die Solana-Wallet des Benutzers.** Nichts bleibt hängen.

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

// 1) Auszahlung — der Vault gibt USDC an das Token-Konto des Synthetic zurück
await submitRomeTxV1(deps, { to: vault, data: encodeFunctionData({ abi, functionName: "withdraw", args: [amount] }) });

// 2) Sweep-Teil — Synthetic-Token-Konto → Token-Konto der eigenen Wallet des Benutzers
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 });
```

## Gemessen auf Hadrian

Jeder der folgenden Solana-Lane-Schritte lief als eine Version-1-Transaktion auf Hadrian:

| Schritt                             | Compute-Units | Bytes | Accounts |
| ----------------------------------- | ------------- | ----- | -------- |
| Bereitstellung (`create_pda`)       | 39,008        | 703   | 9        |
| Wrapper-Genehmigung (`approve_spl`) | 50,687        | 899   | 13       |
| Genehmigen                          | 79,335        | 769   | 10       |
| Vault-Einzahlung                    | 242,880       | 1,070 | 20       |
| Vault-Auszahlung                    | 280,903       | 1,037 | 19       |
| Sweep (`transfer_spl`)              | 46,810        | 899   | 13       |

## Die Fallstricke

Das sind die Dinge, die eine von Hand gebaute Solana-Lane-Transaktion falsch macht. Das SDK und der Composer des Proxys erledigen die meisten davon:

* **Bereitstellung.** Das Konto eines frischen Synthetic muss erstellt werden (`create_pda`) `submitRomeTxV1` tut das nicht für dich: prüfe `isSyntheticProvisioned` und übermittle `buildCreatePdaCall(synthetic)` einmal.
* **Gewähre dem Wrapper einmal die Erlaubnis.** Der Wrapper bewegt Token als SPL-Delegierter des Benutzers. Prüfe `isEnabled` und sende `approve_spl` an das Helper-Precompile vor der ersten Einzahlung, sonst wird die Einzahlung mit dem SPL-Fehler zurückgesetzt `0x4`.
* **Verwende den Wrapper, nicht `msg.value`.** Das Guthaben eines Solana-Benutzers ist sein SPL-Token-Konto, dargestellt als der ERC-20-Wrapper — bewege es mit `transfer` / `transferFrom`, niemals nativen Wert.
* **Für dich komponiert.** ComputeBudget, die Treasure-Wallet und die Kontenermittlung werden vom Composer des Proxys erledigt, sodass sie in deinem Code nicht erscheinen. Bevor die Wallet signiert, prüft das SDK die komponierte Transaktion und lehnt alles außer dem vom Benutzer autorisierten Aufruf ab.
* **Wohin es gesendet wird.** Die Wallet signiert die v1-Transaktion und die **App sendet sie an den Solana-RPC** — nicht an den Proxy, der sie zusammensetzt (ein weitergeleiteter Aufruf ist die eine Ausnahme unten; siehe [Weitergeleitete Aufrufe und lange Aufrufe](https://docs.rome.builders/de/entwicklerleitfaden/call-evm-from-solana.md#relayed-calls-and-long-calls)). On-chain leitet das Programm `msg.sender` vom Solana-Signer ab.
* **Zwei Aufforderungen pro Aufruf.** Die Wallet signiert eine lesbare Autorisierungsnachricht (`Rome-Autorisierung` und den EVM-Transaktions-Hash), dann die Transaktion, beides mit demselben Schlüssel.
* **Prüfe, dass deine Wallet v1 signiert.** `signV1Wire` muss die 64-Byte-Signatur über die v1-Nachricht zurückgeben; über Wallet Standard ist das `solana:signTransaction` auf dem Rohdraht und `signedTransaction.slice(-64)`. Nicht jede Wallet dekodiert v1-Transaktionen schon, also teste deine, bevor du darauf aufbaust. Auf dem Devnet signiert Solflare sie heute; Phantom noch nicht.
* **Große Aufrufe werden weitergeleitet.** Ein Aufruf, der nicht in eine Transaktion passt, wird vom Proxy mit derselben Autorisierungssignatur weitergeleitet, und das Ergebnis hat `route: "relay"`. Ein weitergeleiteter Aufruf wird in dem nativen Gas der Chain bezahlt, also fülle das Synthetic mit `fundSyntheticGas(deps, amountWei)`. Siehe [Weitergeleitete Aufrufe und lange Aufrufe](https://docs.rome.builders/de/entwicklerleitfaden/call-evm-from-solana.md#relayed-calls-and-long-calls).
* **Gas ist USDC.** Kein Faucet — bridge USDC hinein (siehe [Finanzierung erhalten](https://docs.rome.builders/de/ressourcen/faucets.md)).

Die frühere `submitRomeTxSolanaLane` ist weiterhin im SDK: Es erstellt eine Legacy-Solana-Transaktion im Client (eine Wallet-Aufforderung, wobei ComputeBudget und die Treasure-Wallet vom SDK behandelt werden).

## Dieselbe App von MetaMask aus

Ein EVM-Benutzer ruft denselben Vertrag mit `submitRomeTx` — standardmäßige EVM-Tools, Gas in USDC. Ein Unterschied zum Solana-Benutzer: Ein MetaMask-Benutzer hält **natives Gas-USDC**, nicht wUSDC. Der Vault nimmt den wUSDC-Wrapper, also wrappt der Benutzer zuerst einen Teil seines Gases, gewährt dann dem Wrapper einmal die Erlaubnis und führt dann die ERC-20-Schritte wie gewohnt aus. Es gibt keine Fund- oder Sweep-Teile, weil die gewrappten Token bereits an ihrer EVM-Adresse liegen.

1. **Gas in wUSDC wrappen** — sende `withdraw_to_ata(wei)` an das Withdraw-Precompile bei `0x4200000000000000000000000000000000000016`. `wUSDC.balanceOf(user)` und dann angezeigt wird. `Wei` liegt in der 18-Dezimal-Gaseinheit und muss ein Vielfaches von 10^12 sein (eine 6-Dezimal-wUSDC-Einheit), sonst wird der Aufruf zurückgesetzt. Überspringe diesen Schritt, wenn der Benutzer bereits wUSDC hält.
2. **Gewähre dem Wrapper die Erlaubnis** (wenn `isEnabled` falsch ist) — derselbe `approve_spl` Aufruf wie oben, gesendet mit `submitRomeTx`. Siehe [Einmalig: dem Wrapper gewähren](#one-time-grant-the-wrapper).
3. **Genehmigen** — `approve(vault, amount)` auf wUSDC.
4. **Einzahlung** — `deposit(amount)` auf den Vault. Withdraw ist `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) wandle etwas Gas-USDC in wUSDC um (weiAmount ist in 18-Dezimal-Gaseinheiten)
await submitRomeTx(provider, { from: who, to: WITHDRAW, data: encodeFunctionData({ abi: withdrawAbi, functionName: "withdraw_to_ata", args: [weiAmount] }) });

// 2) gewähre dem Wrapper einmal die Erlaubnis: `grant` ist der Aufruf, der unter „Einmalig: Gewähre dem Wrapper die Erlaubnis“ erstellt wurde, oder null
if (grant) await submitRomeTx(provider, { from: who, ...grant });

// 3) approve und 4) deposit, wie bei jedem ERC-20
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] }) });
```

Beide Benutzer teilen sich denselben `balanceOf` Zustand im Vault.

## Was als Nächstes kommt

* [EVM aus Solana aufrufen](https://docs.rome.builders/de/entwicklerleitfaden/call-evm-from-solana.md) — die Mechanik der Solana-Lane im Detail
* [Solana aus EVM aufrufen](https://docs.rome.builders/de/entwicklerleitfaden/call-solana-from-evm.md) — die andere Richtung (CPI)
* [Finanzierung erhalten](https://docs.rome.builders/de/ressourcen/faucets.md) — USDC als Gas-Token; bridge es hinein


---

# 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/de/entwicklerleitfaden/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.
