> 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/klyuchevye-ponyatiya/token-interop.md).

# Совместимость токенов

Как токены ERC-20 и SPL представляют один и тот же базовый аккаунт в Rome.

Rome представляет токен ERC-20 и соответствующий ему токен SPL как единый общий аккаунт. На этой странице объясняется, как работают токены в EVM и Solana.

## Модель общего состояния

Для обычного кошелька токен ERC-20 в Rome — это **прозрачная оболочка** над аккаунтом токена SPL в Solana. Баланс ERC-20 кошелька равен его балансу SPL. Аккаунтом токена владеет адрес, производный от EVM-адреса. Это **PDA с внешним полномочием**.

<figure><img src="https://1351373662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-552c639322c2d0e90b312def5db39d06c1871d18%2Ftoken-interop.svg?alt=media" alt="An EVM address and its Solana token account, owned by its external-authority PDA. Multiple wrappers read the same token account. The wrapper escrow account and Solana pool vaults hold tokens of the same Solana mint."><figcaption></figcaption></figure>

* Без задержки синхронизации: баланс ERC-20 кошелька равен его балансу SPL.
* У обычных кошельков, включая кошельки MetaMask и синтетические адреса, ликвидность не фрагментируется. Все оболочки для одного mint показывают одинаковый баланс кошелька. Метод `balanceOf` читает этот баланс из аккаунта токена кошелька. Токены в EVM-контрактах хранятся отдельно для каждой оболочки (см. [Контракт оболочки](#the-wrapper-contract)).
* Токены кошелька не блокируются в одной системе и не выпускаются в другой. Токены, хранящиеся в контракте, находятся в собственном эскроу-аккаунте токена этой оболочки в Solana. Каждая оболочка учитывает такие токены отдельно.

**Почему вторая оболочка не разделяет баланс**

Две оболочки для одного mint показывают одинаковый баланс кошелька. Оболочки считывают `totalSupply` из mint Solana. В Hadrian (тестовая сеть) три оболочки wUSDC показывали одинаковые балансы кошельков. Все три оболочки wUSDC (9.0.0, 8.0.0 и May 2026) возвращали значение эмиссии mint Solana.

Каждая фабрика допускает только одну оболочку для каждого mint. Новая версия фабрики может развернуть ещё одну оболочку для этого mint. В реестре указана каноническая оболочка для каждой сети.

Токены одного mint могут храниться как непосредственно в кошельке Solana с USDC, так и по EVM-адресу. Пулы Solana используют для обоих вариантов одни и те же хранилища и резервы.

Таблица держателей в [обозревателе Via](https://docs.rome.builders/ru/prilozheniya-v-rome/via.md) составляется на основе событий `Transfer` . Она может отличаться от баланса аккаунта токена, поскольку прямые переводы SPL, `ActivateAta`и переводы через другую оболочку не отражаются в событиях этой оболочки.

> В путях импорта ниже используется `@rome-protocol/rome-solidity`. Пакет недоступен в npm: установите его из общедоступного репозитория [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) с помощью команды `npm install github:rome-protocol/rome-solidity`или `forge install rome-protocol/rome-solidity` с настройкой remapping; для контрактов оболочки и фабрики в Foundry также требуется OpenZeppelin (см. [Развёртывание контрактов Solidity](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/deploy-solidity.md#using-the-rome-solidity-sdk)). Интерфейсы предкомпиляции находятся в [`contracts/interface.sol`](https://github.com/rome-protocol/rome-solidity/blob/master/contracts/interface.sol).

## Контракт оболочки

`SPL_ERC20` (а также его вариант с кешированием трека `SPL_ERC20_cached`, который фабрика разворачивает для каждого mint, кроме mint с активированным хуком перевода; см. [Mint токенов Token-2022](#token-2022-mints)) предоставляет полноценный интерфейс ERC-20 поверх mint SPL:

* `balanceOf()` — считывает баланс ATA пользователя из Solana (для адреса контракта считывает собственный реестр оболочки; см. ниже)
* `transfer()` / `transferFrom()` — перемещают токены в Solana
* `approve()` / `allowance()` — лимиты ERC-20 для каждого расходующего адреса хранятся в EVM. У SPL-аккаунта токена нет лимитов в стиле EVM. Они не связаны с одноразовым разрешением, описанным ниже: чтобы вообще перемещать токены пользователя, обёртка действует как SPL-делегат этого пользователя, который один раз для каждого кошелька предоставляет ей такое право
* `totalSupply()` — считывает объём выпуска из SPL mint

Контракт не может предоставить одноразовое разрешение, поэтому токены контракта хранятся на собственном токен-аккаунте обёртки и учитываются в её реестре. `balanceOf(contract)` считывает данные из этого реестра.

## Фабрика

`ERC20SPLFactory` развёртывает обёртку для любого SPL mint:

```solidity
import {ERC20SPLFactory} from "@rome-protocol/rome-solidity/contracts/erc20spl/erc20spl_factory.sol";

// Развёртывание обёртки с загрузкой имени и символа из метаданных Token-2022 или Metaplex mint
address wrapper = factory.add_spl_token_with_metadata(splMint);

// Или укажите имя и символ вручную
address wrapper = factory.add_spl_token_no_metadata(splMint, "USD Coin", "USDC");
```

Актуальный адрес фабрики из записей со статусом `live` в реестре (v0.2.0): Hadrian `0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078`. Более ранние фабрики по-прежнему находятся в блокчейне, но помечены как `deprecated` или `retired` в [реестре](https://github.com/rome-protocol/rome-registry/tree/main/chains); не используйте их. Реестр — источник достоверной информации, поэтому считывайте актуальный адрес из него (см. раздел [Чтение списка контрактов](https://docs.rome.builders/ru/spravochnik/contract-addresses.md#reading-the-contracts-list)), а не копируйте его в свой код.

## Канонические mint

В блокчейне нет контракта реестра токенов. Канонические обёртки, а также токены для оплаты газа и мостов выбираются и публикуются во внешнем реестре [`rome-protocol/registry`](https://github.com/rome-protocol/rome-registry); обёртки без разрешений, созданные с помощью `add_spl_token_no_metadata` обнаруживаются по событию `TokenCreated` . В реестре указана каноническая обёртка для каждого mint в каждой сети. Балансы кошелька общие для всех обёрток. Каждая обёртка отдельно учитывает балансы, хранящиеся у EVM-контрактов.

## Операции SPL из Solidity

Для базовых операций SPL с подписью пользовательского PDA используйте прекомпилятор **HelperProgram** (`0xFF…09`) — создание ATA, переводы SPL и преобразование gas↔lamports:

```solidity
import {IHelperProgram} from "@rome-protocol/rome-solidity/contracts/interface.sol";

IHelperProgram helper = IHelperProgram(0xFF00000000000000000000000000000000000009);

helper.create_ata(user, mint);              // создать ATA пользователя для mint
helper.transfer_spl(to, tokens, mint);      // перевести SPL от PDA вызывающей стороны
```

`transfer_spl` имеет несколько перегрузок (в том числе вариант с делегатом для сценариев `transferFrom` ); см. `interface.sol` для точного соответствия сигнатурам. В кешируемом варианте эквивалентные операции доступны в `ISplCached` (`0xFF…05`) и `IAssociatedSplCached` (`0xFF…06`). Контракт последовательно использует один вариант.

## Однократное разрешение для каждого кошелька

Обёртка перемещает токены пользователя как **делегат SPL** учётной записи токенов этого пользователя. Поэтому кошелёк должен один раз предоставить ей это право для каждой обёртки, прежде чем она сможет перемещать его токены. Разрешение предоставляется одним вызовом прекомпилятора Helper (`0xff00000000000000000000000000000000000009`):

```solidity
helper.approve_spl(wrapper, type(uint64).max, mint);   // approve_spl(wrapper, 2^64-1, mint)
```

`approve_spl` подписывает сам пользователь, поэтому вызов отправляет он, а не обёртка и не ваш контракт. Идентификатор токена — это `mint_id()` обёртки.

* **Кому это нужно.** Каждому EVM-кошельку и синтетическому адресу каждого пользователя Solana — для каждой обёртки, которая должна перемещать его токены. Контракт, который забирает токены с помощью `transferFrom` работает только для пользователей, предоставивших разрешение обёртке.
* **Как проверить.** Вызовите `isEnabled(user)` у обёртки. После предоставления разрешения функция возвращает `true` .
* **Что происходит, если разрешения нет.** Транзакция перевода откатывается с ошибкой SPL `0x4` (несовпадение владельца).
* **Для каждой учётной записи токенов предусмотрен один делегат.** У учётной записи токенов SPL может быть только один делегат. Если предоставить другому приложению разрешение для той же учётной записи токенов — например, мосту или маршрутизатору, — оно заменит разрешение обёртки, и обёртка перестанет работать для этого пользователя, пока он не предоставит его заново. Перед переводом проверяйте `isEnabled` и не рассчитывайте, что ранее выданное разрешение всё ещё действует.

При замене обёртки новой версией фабрики каждый кошелёк предоставляет новой обёртке разрешение с помощью `approve_spl`. Старая обёртка может перемещать токены кошелька, только пока она остаётся делегатом учётной записи токенов. Предоставление разрешения новой обёртке заменяет делегата.

Полный код для обоих вариантов приведён в [руководстве по приложению с двумя вариантами взаимодействия](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/dual-lane-app.md#one-time-grant-the-wrapper) .

## Внесение и вывод средств

* **В EVM** — на стороне SPL баланс зачисляется на ATA, принадлежащую PDA пользователя; обёртка ERC-20 сразу отражает этот баланс. Входящие переводы из других сетей подтверждаются ончейн на основании авторизации, подписанной пользователем на мосту.
* **Обёртывание газа в газовый токен** — вызовите `Withdraw` прекомпилятора (`0x42…16`). `withdraw_to_ata(wei)` сжигает нативный газ и зачисляет эквивалентную сумму с учетом числа десятичных знаков газового токена на токенный счет вызывающей стороны; баланс отображается оберткой этого токена (например, wUSDC). `withdraw_to_pda(wei)` переводит лампорты на PDA вызывающей стороны и подходит только для сети, где газ оплачивается в SOL. В Hadrian и Rubicon, где газом служит USDC, вызов завершается откатом, поэтому используйте `withdraw_to_ata` в этих сетях. Сумма задается в единицах газа с 18 десятичными знаками и должна быть целым числом единиц газового токена: в сети с оплатой газа в USDC сумма должна быть кратна 10^12 (одна единица с 6 десятичными знаками), иначе вызов завершится откатом. `HelperProgram.deposit_from_ata(wei)` выполняет обратную операцию: преобразует газовый токен на токенном счете вызывающей стороны обратно в нативный газ с тем же требованием кратности. Эти операции преобразуют газовый токен, а не выводят другие токены.
* **Вывод в Solana: любые другие токены** — поскольку собственный баланс обертки уже является балансом SPL, для вывода достаточно выполнить SPL-перевод:
  * `HelperProgram.transfer_spl_to_signer(amount, mint)` отправляет токены вызывающей стороны на токенный счет кошелька Solana, подписавшего транзакцию. Этот способ возврата средств переводит их непосредственно в кошелек пользователя только при подписании транзакции в Solana самим кошельком. При вызове из MetaMask или через ретранслятор подписантом будет прокси-плательщик Rome, поэтому вызов завершится ошибкой или токены поступят Rome. Вместо этого используйте `transfer_spl` или `RomeBridgeWithdraw.bridgeOutToSolana` в этих случаях.
  * `RomeBridgeWithdraw.bridgeOutToSolana(solanaRecipient, amount, mint)` отправляет токены на любой кошелек Solana. Для этого требуется разрешение пользователя для контракта моста (`approve_spl(bridge, …)`, см. примечание выше об одном делегате), а токенный счет получателя должен существовать; `ensureRecipientAta(solanaRecipient, mint)` создает его.
  * `RomeBridgeWithdraw` также сжигает USDC для перевода в другую сеть через CCTP (`burnUSDC`) и отправляет другие активы через Wormhole (`burnETH`, `burnToWormhole`).

Получите актуальный адрес `RomeBridgeWithdraw` из реестра.

Чтобы перемещать другие токены между Solana и Ethereum или сетями AggLayer, см. [Solgate](https://docs.rome.builders/ru/prilozheniya-v-rome/solgate.md) и раздел [13. Разработка на Solgate](https://docs.rome.builders/ru/rome-academy/13-build-on-solgate.md).

## Газовый токен

В каждой сети используется собственный газовый токен: SOL или SPL-токен. Источником цены для Rome Proxy может быть API-канал Hermes, пул Meteora DAMM v1, пул Meteora DAMM v2 или фиксированная цена. В Hadrian (тестовая сеть) и Rubicon (основная сеть) используется USDC. В Hadrian используется тестовый USDC, а в Rubicon — настоящий USDC. Универсального газового токена по умолчанию нет.

## Минты Token-2022

Фабрика также создает обертки для минтов Token-2022. Она запрашивает у прекомпиляции Helper информацию о минте с помощью `mint_info(mint)` (селектор `0xe24bf5d4`) и по полученному ответу выбирает обертку. `mint_info` возвращает пять значений:

| Значение       | Описание                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------- |
| `tokenProgram` | токенная программа, которой принадлежит минт (классическая программа SPL Token или Token-2022)    |
| `decimals`     | количество десятичных знаков mint                                                                 |
| `hookProgram`  | программа-хук перевода или нулевое значение, если хука нет либо он есть, но не активирован        |
| `feeBps`       | комиссия за перевод в базисных пунктах или нулевое значение, если комиссии нет или она равна нулю |
| `extensions`   | битовая маска расширений Token-2022, имеющихся у mint: бит N соответствует типу расширения N      |

Что получает mint:

| Mint                                                                                    | Обёртка                                                                                          | `wrapper_kind_by_mint` |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------- |
| Обычный mint, mint Token-2022 без хука или mint с имеющимся, но не активированным хуком | кэшированную обёртку (`SPL_ERC20_cached`)                                                        | `1`                    |
| Mint Token-2022 с активированным хуком перевода                                         | обёртку с хуком (`SPL_ERC20_Token2022Hooked`), развёрнутую с помощью `hooked_wrapper_deployer()` | `2`                    |

Mint с комиссией за перевод получает кэшированную обёртку, а его событие `Transfer` указывает сумму, поступившую после вычета комиссии, а не отправленную сумму. Тип обёртки, полученной mint, можно узнать у фабрики с помощью `wrapper_kind_by_mint(mint)`; в работающей фабрике Hadrian для обёрток USDC, ETH и SOL возвращается `1`.

В каких случаях следует отказ:

* Mint с активированным хуком перевода не может получить одну из обычных обёрток. Прямой вызов `SPL_ERC20` или `SPL_ERC20_cached` для такого mint завершается откатом с ошибкой `ArmedTransferHookUnsupported(mint, hookProgram)`. При вызове через фабрику в этом случае используется обёртка с хуком.
* Если адрес не принадлежит mint SPL, вызов `mint_info` завершается откатом с ошибкой `Invalid SPL mint account: <address>`.
* Если для mint уже существует обёртка, вызов завершается откатом с ошибкой `Token exists`, а если символ уже используется — с ошибкой `Token with symbol exists`.
* `add_spl_token_with_metadata` сначала считывает название и символ из метаданных самого mint Token-2022, а затем — из Metaplex. Если у mint нет ни тех, ни других метаданных, вызов завершается откатом с ошибкой `Mint asserts no name: use add_spl_token_no_metadata`.

Как работает обёртка с хуком:

* Token-2022 запускает хук при каждом переводе, а хуку нужны аккаунты, зависящие от перевода. Обёртка не может определить их самостоятельно, поэтому вызывающая сторона формирует полный список аккаунтов на основе списка extra-account-metas mint и передаёт его. Обёртка проверяет фиксированную часть этого списка (программу хука и её аккаунт валидации) и передаёт список без изменений.
* Обычные `transfer`, `transferFrom` и `bridgeOutToSolana` откатывается с помощью `HookAccountPlanRequired`. Используйте `transferWithHookAccounts`, `transferFromWithHookAccounts` и `bridgeOutToSolanaWithHookAccounts`, которым список аккаунтов передаётся как дополнительный аргумент.
* Если программа хука минта меняется после развёртывания обёртки, переводы откатываются с ошибкой `HookConfigurationChanged`.
* Токены перемещаются посредством прямого межпрограммного вызова — по устаревшему пути; кэшированный путь не используется. Контракт всегда использует один и тот же путь, а вызовы по устаревшему пути выполняются только атомарно. Поэтому вызов с обёрткой, использующей хук, должен укладываться в одну атомарную транзакцию.
* В обёртке не ведётся реестр балансов контрактов. Токены, отправленные контракту, поступают на его собственный токен-аккаунт, и контракт может отправить их дальше только после того, как выдаст `approve_spl` разрешение самой обёртке.
* Для неё требуется такое же [однократное разрешение](#one-time-grant-per-wallet) , как и для любой другой обёртки.

## Ограничения

* Суммы токенов SPL имеют тип `uint64` (максимум — 18 446 744 073 709 551 615)
* Лимиты ERC-20 (`approve` / `allowance`) хранятся в EVM. Обёртка перемещает токены от имени пользователя как его делегат SPL; пользователь выдаёт разрешение один раз для каждой обёртки (см. [Однократное разрешение для каждого кошелька](#one-time-grant-per-wallet))
* Символы ERC-20-обёрток должны быть уникальны в пределах каждой фабрики

## Что дальше

* [Адреса контрактов](https://docs.rome.builders/ru/spravochnik/contract-addresses.md) — прекомпиляты и адреса в разных сетях
* [Вызов Solana из EVM](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/call-solana-from-evm.md) — CPI и операции SPL из Solidity
* [Как Solana и EVM взаимодействуют в Rome](https://docs.rome.builders/ru/klyuchevye-ponyatiya/how-solana-and-evm-meet.md)
* [Интеграция программы Solana](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/integrate-solana-program.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/ru/klyuchevye-ponyatiya/token-interop.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.
