> 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/ru/rukovodstva-dlya-razrabotchikov/dual-lane-app.md).

# Построение приложения с двумя линиями

Пошаговый разбор двуполосного приложения — один контракт Solidity, используемый как пользователем MetaMask, так и пользователем кошелька Solana, с точным описанием того, что происходит на каждом шаге.

Приложение **приложение с двумя каналами** — это один контракт Solidity, который и **MetaMask (EVM)** пользователь, и **кошелька Solana** пользователь используют напрямую — один и тот же контракт, одно и то же состояние, каждый — со своим уже имеющимся кошельком. На этой странице пошагово разбирается *точно* что происходит на каждом шаге, с каждой стороны.

Пример представляет собой небольшой **хранилище**: вы `депозит` USDC, а позже `withdraw` его. «Stake / unstake», «supply / redeem», «tip / claim» — одна и та же схема.

## Что вы пишете — стандартное хранилище ERC-20

В Rome USDC пользователя Solana на стороне EVM отображается как обычный **токен ERC-20** — оболочка SPL для этого минта (например, `wUSDC`). Поэтому ваш контракт — обычное токенное хранилище: он забирает токены через `transferFrom` и возвращает их через `transfer`. Ничего специфичного для 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;                 // оболочка 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));
    }
}
```

> **Почему ERC-20, а не `payable` / `msg.value`?** Расходуемый баланс пользователя Solana — это их **SPL-токен-аккаунт кошелька**, отображаемый 1:1 как эта оболочка ERC-20 — *не* родной баланс EVM. Поэтому пользователь Solana всегда может пополнить `transferFrom`, но `deposit() payable` требовал бы нативную стоимость, которой у них в покое нет. Постройте решение вокруг токена — и оба канала будут работать одинаково.

Разверните его с помощью Foundry или Hardhat, указав в конструкторе адрес оболочки для вашего токена (из [реестре](https://github.com/rome-protocol/rome-registry)). В Rome газовым токеном является USDC, поэтому для развертывания нужен небольшой баланс USDC на газ.

## Два канала

| Канал      | Кошелёк                                         | Как приложение вызывает это                                                     |
| ---------- | ----------------------------------------------- | ------------------------------------------------------------------------------- |
| **EVM**    | MetaMask (ключ EVM)                             | `submitRomeTx` — стандартная запись Rome                                        |
| **Solana** | кошелек Solana, например Solflare (ключ Solana) | `submitRomeTxV1` — одна транзакция Solana v1 на каждый вызов, ключ EVM не нужен |

Канал EVM — обычный. Остальная часть этой страницы — **ветки Solana** — интересная половина.

## Ключевая идея: синтетический адрес — это прозрачный проход

EVM-идентичность пользователя Solana — это его **синтетический адрес** — `keccak256(solana_pubkey)[12:]`. Это его `msg.sender` в контракте, но **в покое он ничего не хранит.** Деньги пользователя находятся в его **кошелька Solana** (как SPL USDC), а на стороне EVM тот же баланс — это то, что `wUSDC.balanceOf(synthetic)` читает. Стоимость течет *через* через синтетический адрес:

* **Вход** (deposit): token account кошелька → token account синтетического адреса → контракт (через `transferFrom`).
* **Выход** (withdraw): контракт → token account синтетического адреса → token account кошелька.

После каждого кругового прохода синтетический адрес возвращается к нулю.

## Один раз: активировать (подготовить синтетический адрес)

Новый on-chain-аккаунт синтетического адреса не существует, пока вы его не создадите. Когда пользователь Solana впервые совершает действие, его синтетический адрес **подготавливается** с `create_pda` вызовом — после этого вызовы, переносящие стоимость (ERC-20 `transferFrom`, sweep), могут быть подписаны им.

`submitRomeTxV1` не делает это за вас, поэтому подготовьте адрес явно, один раз, до первого вызова, переносящего стоимость. Хорошее место — шаг «Активировать» или непосредственно перед первым approve:

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

const synthetic = syntheticAddress(wallet.publicKey);
const deps = { connection, proxyUrl, chainId, programId, signer }; // signer: Keypair в скриптах, LaneSigner в приложении-кошельке
if (!(await isSyntheticProvisioned(connection, programId, synthetic))) {
  await submitRomeTxV1(deps, buildCreatePdaCall(synthetic)); // один create_pda
}
```

## Разово: предоставить права обертке

Оболочка wUSDC перемещает токены пользователя как **SPL-делегат** делегация его токен-аккаунта, поэтому каждый пользователь должен один раз выдать ей это право на каждую оболочку, до первого депозита. Это относится и к пользователю MetaMask, и к синтетическому адресу пользователя Solana. Без этого разрешения каждый `transferFrom` вывод из кошелька завершается ошибкой, а депозит откатывается с ошибкой SPL `0x4` (несовпадение владельца).

Проверьте через view-метод оболочки `isEnabled(user)`. Если он возвращает `false`, отправьте `approve_spl(wrapper, 2^64-1, mint)` напрямую в helper precompile по адресу `0xff00000000000000000000000000000000000009`; mint `mint_id()` на оболочке. На канале EVM это `submitRomeTx` вызов, на канале Solana — `submitRomeTxV1` вызов:

```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) }); // клиент viem для RPC сети

// кто: адрес MetaMask или syntheticAddress(wallet.publicKey) для пользователя Solana
let grant = null; // остается null, когда isEnabled истинно
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:    if (grant) await submitRomeTx(provider, { from: who, ...grant });
// Канал Solana: if (grant) await submitRomeTxV1(deps, grant);
```

## Что нужно каждой стороне

|                                 | Нужно                                                              | Почему                                                                                                                                 |
| ------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Пользователь Solana**         | **SOL** (немного)                                                  | оплачивает комиссию за транзакцию Solana на каждом транзакционном вызове канала                                                        |
|                                 | **USDC в виде токена SPL** в их кошельке                           | стоимость, которую они вносят (на стороне EVM это видно как `wUSDC`)                                                                   |
| **Пользователь EVM (MetaMask)** | **USDC** как их баланс газа Rome                                   | газ, и стоимость, которую они вносят после обертывания; они пополняют его через **мост USDC** в Rome (фауcета нет)                     |
|                                 | один **обернуть** часть этого газа в **wUSDC** (`withdraw_to_ata`) | хранилище принимает wUSDC, оболочку ERC-20, а не нативный газ. Баланс газового USDC на MetaMask не является wUSDC, пока его не обернут |
|                                 | одноразовое **разрешение оболочке** (`approve_spl`)                | позволяет оболочке wUSDC перемещать их токены; см. [Разово: предоставить права обертке](#one-time-grant-the-wrapper)                   |
| **Вы (разработчик)**            | кошелек с **USDC** газом в Rome                                    | для развертывания контракта                                                                                                            |

## Стоимость ВХОД — депозит (пошагово)

Пользователь Solana держит SOL + USDC в своем кошельке Solana. Каждый шаг — это транзакция Solana v1, **подписываемая этим кошельком**, а приложение отправляет ее в Solana RPC. Fund-этап собирается в приложении, и кошелек подписывает его одним запросом; каждый вызов контракта составляется proxy, а кошелек подписывает его после читаемого сообщения авторизации:

1. **Fund-этап** — `buildFundLeg(...)` → `submitSolanaInstructionsV1(...)`. Создает token account USDC для синтетического адреса (если нужно) и выполняет **`ActivateAta`**, перемещая `сумму` USDC из token account кошелька **в**. Теперь `wUSDC.balanceOf(synthetic)` показывает этот баланс.
2. **Выдать разрешение оболочке** (когда `isEnabled` является false) — `submitRomeTxV1(deps, { to: HELPER, data: approve_spl(wUSDC, 2^64-1, mint) })`. См. [Разово: предоставить права обертке](#one-time-grant-the-wrapper). *(Подготовьте синтетический адрес перед этим, если это первый вызов пользователя по этому каналу.)*
3. **Разрешить** — `submitRomeTxV1(deps, { to: wUSDC, data: encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [vault, amount] }) })`. Позволяет хранилищу забрать токены.
4. **Депозит** — `submitRomeTxV1(deps, { to: vault, data: encodeFunctionData({ abi, functionName: "deposit", args: [depositAmount] }) })`. Хранилище выполняет `transferFrom(synthetic, vault, amount)` — USDC перемещается из синтетического адреса в хранилище, зачисляясь на адрес синтетического адреса.

**Итоговый эффект:** USDC переместился **кошелек Solana → (синтетический адрес) → хранилище.**

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

// 1) fund-этап — USDC кошелька → token account синтетического адреса (кошелек подписывает)
await submitSolanaInstructionsV1(
  buildFundLeg({ programId, chainId, mint: usdcMint, amount: depositAmount, wallet: wallet.publicKey, synthetic }),
  { connection, signer },
);

// 2) выдать разрешение оболочке, один раз (синтетический адрес уже подготовлен); `grant` — это вызов, сформированный в разделе «Один раз: выдать разрешение оболочке», или null, когда isEnabled истинно
if (grant) await submitRomeTxV1(deps, grant);

// 3) approve для хранилища
await submitRomeTxV1(deps, { to: wUSDC, data: encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [vault, depositAmount] }) });

// 4) депозит — хранилище забирает через transferFrom
await submitRomeTxV1(deps, { to: vault, data: encodeFunctionData({ abi, functionName: "deposit", args: [depositAmount] }) });
```

## Стоимость ВЫХОДА — вывод (пошагово)

Теперь пользователь выводит средства. Тоже с подписью кошельком, два запроса на каждый вызов:

1. **Вывод** — `submitRomeTxV1(deps, { to: vault, data: withdraw(amount) })`. `vault.withdraw` выполняет `transfer(synthetic, amount)` — USDC перемещается из хранилища обратно в **token account синтетического адреса** .
2. **Sweep-этап** — `buildSweepLeg(...)` дает вам `HelperProgram.transfer_spl` вызов + accounts; выполните его (при необходимости создайте token account кошелька с помощью `submitSolanaInstructionsV1`, затем отправьте вызов Helper через `submitRomeTxV1`; proxy находит token account'ы) для перемещения USDC из синтетического адреса **обратно в собственный кошелек Solana пользователя**. Синтетический адрес возвращается к нулю.

**Итоговый эффект:** USDC переместился **хранилище → (синтетический адрес) → кошелек Solana пользователя.** Ничего не остается без движения.

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

// 1) withdraw — хранилище возвращает USDC на token account синтетического адреса
await submitRomeTxV1(deps, { to: vault, data: encodeFunctionData({ abi, functionName: "withdraw", args: [amount] }) });

// 2) sweep-этап — token account синтетического адреса → token account собственного кошелька пользователя
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 });
```

## Измерено на Hadrian

Каждый шаг на канале Solana ниже выполнялся как одна транзакция версии 1 на Hadrian:

| Шаг                                 | Вычислительные единицы | Байты | Аккаунты |
| ----------------------------------- | ---------------------- | ----- | -------- |
| Подготовка (`create_pda`)           | 39,008                 | 703   | 9        |
| Выдача прав обертке (`approve_spl`) | 50,687                 | 899   | 13       |
| Разрешить                           | 79,335                 | 769   | 10       |
| Депозит в хранилище                 | 242,880                | 1,070 | 20       |
| Вывод из хранилища                  | 280,903                | 1,037 | 19       |
| Sweep (`transfer_spl`)              | 46,810                 | 899   | 13       |

## Подводные камни

Вот что обычно не так в транзакции, собранной вручную для канала Solana. SDK и composer proxy решают большинство из этих проблем:

* **Подготовка.** Новый аккаунт синтетического адреса должен быть создан (`create_pda`) до любого вызова, переносящего стоимость, иначе он не сможет подписать перевод. `submitRomeTxV1` не делает это за вас: проверьте `isSyntheticProvisioned` и отправьте `buildCreatePdaCall(synthetic)` один раз.
* **Выдайте разрешение оболочке один раз.** Оболочка перемещает токены как SPL-delegate пользователя. Проверьте `isEnabled` и отправьте `approve_spl` в Helper precompile перед первым депозитом, иначе депозит откатится с ошибкой SPL `0x4`.
* **Расходуйте оболочку, а не `msg.value`.** Баланс пользователя Solana — это их token account SPL, отображаемый как оболочка ERC-20 — перемещайте его через `transfer` / `transferFrom`, никогда не нативную стоимость.
* **Сформировано для вас.** ComputeBudget, казначейский кошелек и обнаружение аккаунтов выполняются composer'ом proxy, так что ничего из этого не появляется в вашем коде. До подписи кошельком SDK проверяет составленную транзакцию и отклоняет все, кроме того вызова, который авторизовал пользователь.
* **Куда это отправляется.** Кошелек подписывает транзакцию v1, и **приложение отправляет ее в Solana RPC** — а не в proxy, который ее составляет (relay-вызов — единственное исключение ниже; см. [Ретранслируемые вызовы и длинные вызовы](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/call-evm-from-solana.md#relayed-calls-and-long-calls)). On-chain программа выводит `msg.sender` из Solana signer.
* **Два запроса на каждый вызов.** Кошелек подписывает читаемое сообщение авторизации (`Авторизация Rome` и хэш транзакции EVM), а затем саму транзакцию, используя один и тот же ключ.
* **Проверьте, что ваш кошелек подписывает v1.** `signV1Wire` должен возвращать 64-байтную подпись над сообщением v1; через Wallet Standard это `solana:signTransaction` в raw wire и `signedTransaction.slice(-64)`. Не каждый кошелек пока умеет декодировать транзакции v1, поэтому протестируйте свой, прежде чем строить на нем решение. Сегодня в devnet Solflare их подписывает; Phantom пока нет.
* **Крупные вызовы идут через relay.** Вызов, который не помещается в одну транзакцию, передается proxy через relay с той же подписью авторизации, и результат имеет `route: "relay"`и результат имеет `fundSyntheticGas(deps, amountWei)`. См. [Ретранслируемые вызовы и длинные вызовы](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/call-evm-from-solana.md#relayed-calls-and-long-calls).
* **Газ — это USDC.** Фаусета нет — заведите USDC через мост (см. [Получение средств](https://docs.rome.builders/ru/resursy/faucets.md)).

Ранее `submitRomeTxSolanaLane` все еще есть в SDK: он собирает в клиенте legacy Solana-транзакцию (один запрос кошелька, при этом ComputeBudget и казначейский кошелек обрабатываются SDK).

## То же приложение из MetaMask

Пользователь EVM вызывает тот же самый контракт с `submitRomeTx` — стандартные EVM-инструменты, газ в USDC. Одно отличие от пользователя Solana: у пользователя MetaMask есть **нативный газ USDC**, а не wUSDC. Хранилище принимает оболочку wUSDC, поэтому пользователь сначала оборачивает часть своего газа, затем один раз выдает разрешение оболочке, после чего выполняет шаги ERC-20 как обычно. Fund- и sweep-этапы не нужны, потому что обернутые токены уже находятся на его EVM-адресе.

1. **Обернуть газ в wUSDC** — отправьте `withdraw_to_ata(wei)` в Withdraw precompile по адресу `0x4200000000000000000000000000000000000016`. Оно сжигает такое же количество нативного газа и зачисляет эквивалентную сумму на token account `wUSDC.balanceOf(user)` затем отображается. `wei` указано в 18-значной единице газа и должно быть кратно 10^12 (одной 6-значной единице wUSDC), иначе вызов откатится. Пропустите этот шаг, если у пользователя уже есть wUSDC.
2. **Выдать разрешение оболочке** (когда `isEnabled` является false) — тот же `approve_spl` вызов, что и выше, отправленный с помощью `submitRomeTx`. См. [Разово: предоставить права обертке](#one-time-grant-the-wrapper).
3. **Разрешить** — `approve(vault, amount)` в wUSDC.
4. **Депозит** — `deposit(amount)` в vault. Withdraw — это `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) оберните часть газового USDC в wUSDC (weiAmount указан в 18-значных единицах газа)
await submitRomeTx(provider, { from: who, to: WITHDRAW, data: encodeFunctionData({ abi: withdrawAbi, functionName: "withdraw_to_ata", args: [weiAmount] }) });

// 2) выдать разрешение оболочке, один раз: `grant` — это вызов, сформированный в разделе «Один раз: выдать разрешение оболочке», или null
if (grant) await submitRomeTx(provider, { from: who, ...grant });

// 3) approve и 4) deposit, как для любого 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] }) });
```

Оба пользователя используют одно и то же `balanceOf` состояние в vault.

## Что дальше

* [Вызов EVM из Solana](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/call-evm-from-solana.md) — механика канала Solana в деталях
* [Вызов Solana из EVM](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/call-solana-from-evm.md) — другое направление (CPI)
* [Получение средств](https://docs.rome.builders/ru/resursy/faucets.md) — USDC как газовый токен; заведите его через мост


---

# 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/ru/rukovodstva-dlya-razrabotchikov/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.
