> 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/ja/ji-ben-gai-nian/token-interop.md).

# Token Interop

RomeではERC-20トークンとSPLトークンが同じ基盤アカウントである仕組み。

Romeでは、ERC-20トークンとその基盤となるSPLトークンを1つの共有アカウントとして扱います。このページでは、EVMとSolana間でトークンがどのように機能するかを説明します。

## 共有状態モデル

通常のウォレットでは、Rome上のERC-20トークンは、Solana上の **透過的なラッパー** です。ウォレットのERC-20残高はSPL残高そのものです。EVMアドレスに対応するプログラム派生アドレスがトークンアカウントを所有します。これが **外部権限PDA**.

<figure><img src="https://3990464069-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ウォレットや合成アドレスを含む通常のウォレットでは、流動性は分断されません。あるミントを包むすべてのラッパーで、同じウォレット残高が表示されます。 `balanceOf` メソッドは、ウォレットのトークンアカウントからその残高を読み取ります。EVMコントラクト内に保有されるトークンは、ラッパーごとに保有されます（詳細は [ラッパーコントラクト](#the-wrapper-contract)).
* を参照）。ウォレットのトークンについては、一方でロックされ、もう一方でミントされることはありません。コントラクトが保有するトークンは、Solana上のラッパー専用のエスクロー用トークンアカウントに置かれます。各ラッパーは、これらのトークンを個別に追跡します。

**2つ目のラッパーを作っても残高が分割されない理由**

同じミントを包む2つのラッパーには、同じウォレット残高が表示されます。ラッパーは、Solanaのミントから `totalSupply` を読み取ります。Hadrian（テストネット）では、3つのwUSDCラッパーが一致するウォレット残高を返しました。3つすべてのwUSDCラッパー（9.0.0、8.0.0、2026年5月版）が、Solanaミントの供給量を返しました。

各ファクトリーは、1つのミントにつき1つのラッパーを作成できます。新しいファクトリーバージョンを使えば、そのミント用に別のラッパーをデプロイできます。レジストリには、チェーンごとの正規ラッパーが登録されています。

USDCを直接保有するSolanaウォレットとEVMアドレスは、同じミントのトークンを保有します。Solana上のプールは、どちらに対しても同じボールトと準備金を使用します。

「 [Via explorer](https://docs.rome.builders/ja/romenoapuri/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` をリマッピング付きで実行します。Foundryでは、ラッパーコントラクトとファクトリーコントラクトにOpenZeppelinも必要です（ [Solidityコントラクトのデプロイ](https://docs.rome.builders/ja/gaido/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`。ファクトリーは、転送フックが有効になっている1つのミントを除くすべてのミントに対してこちらをデプロイします。詳細は [Token-2022のミント](#token-2022-mints)を参照）は、SPLミントに対して完全なERC-20インターフェースを提供します。

* `balanceOf()` — SolanaからユーザーのATA残高を読み取ります（コントラクトアドレスの場合は、下記のとおりラッパー独自の台帳を読み取ります）
* `transfer()` / `transferFrom()` — Solana上でトークンを移動します
* `approve()` / `allowance()` — EVMストレージに保持される、支出者ごとのERC-20使用許可（SPLトークンアカウントにはEVM形式の使用許可はありません）。これは後述する一度限りの権限付与とは別のものです。ユーザーのトークンを移動するには、ラッパーがそのユーザーのSPLデリゲートとして動作する必要があり、ユーザーはウォレットごとに一度だけ、その権限を付与します。
* `totalSupply()` — SPLミントの供給量を読み取ります

コントラクトは一度限りの権限付与を行えないため、コントラクトが保有するトークンはラッパー自身のトークンアカウントに保管され、ラッパーの台帳で管理されます。 `balanceOf(contract)` はその台帳を読み取ります。

## ファクトリーの

`ERC20SPLFactory` は、任意のSPLミント用のラッパーをデプロイします。

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

// Deploy a wrapper, loading name/symbol from the mint's Token-2022 metadata or Metaplex
address wrapper = factory.add_spl_token_with_metadata(splMint);

// Or specify name/symbol manually
address wrapper = factory.add_spl_token_no_metadata(splMint, "USD Coin", "USDC");
```

Hadrianのライブファクトリーアドレスは、レジストリの `live` エントリー（v0.2.0）に記載されています。 `0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078`。以前のファクトリーもオンチェーン上に残っていますが、 `deprecated` または `retired` として [レジストリ](https://github.com/rome-protocol/rome-registry/tree/main/chains)に記載されています。これらは使用しないでください。レジストリが正しい情報源なので、アドレスをコードにコピーするのではなく、レジストリからライブアドレスを読み取ってください（ [コントラクト一覧の読み取り](https://docs.rome.builders/ja/rifarensu/contract-addresses.md#reading-the-contracts-list)を参照）。

## 正規ミント

オンチェーンのトークンレジストリコントラクトはありません。正規ラッパーとガス／ブリッジトークンは、オフチェーンの [`rome-protocol/registry`](https://github.com/rome-protocol/rome-registry)で管理されています。 `add_spl_token_no_metadata` を使ってパーミッションレスに作成されたラッパーは、オンチェーンの `TokenCreated` イベントから検出されます。レジストリには、各チェーンで各ミントに対応する正規ラッパーが記載されています。ウォレット残高はラッパー間で共有されます。EVMコントラクトが保有する残高は、各ラッパーが個別に管理します。

## SolidityからのSPL操作

ユーザーPDAの署名を使うSPLプリミティブには、 **HelperProgram** プリコンパイル（`0xFF…09`）を使用します。ATAの作成、SPLの転送、ガスとlamportsの変換を実行できます。

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

IHelperProgram helper = IHelperProgram(0xFF00000000000000000000000000000000000009);

helper.create_ata(user, mint);              // create the user's ATA for a mint
helper.transfer_spl(to, tokens, mint);      // transfer SPL from the caller's PDA
```

`transfer_spl` には複数のオーバーロードがあり（ `transferFrom` のフロー向けのデリゲート版を含む）、詳細は `interface.sol` 厳密なシグネチャについては、キャッシュ済みトラックでは、対応する操作は `ISplCached` (`0xFF…05`）および `IAssociatedSplCached` (`0xFF…06`）にあります。コントラクトはどちらか一方のトラックを一貫して使用します。

## ウォレットごとに一度だけ許可

ラッパーは、ユーザーのトークンをそのユーザーのトークンアカウントの **SPLデリゲート** として移動します。そのため、ラッパーがユーザーに代わってトークンを移動するには、ウォレットがラッパーごとに一度、事前にその権限を付与する必要があります。許可は Helper プリコンパイルへの1回の呼び出しで行います（`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` （所有者不一致）でリバートします。
* **トークンアカウントごとにデリゲートは1つ** SPL トークンアカウントに設定できるデリゲートは1つだけです。同じトークンアカウントに対して、ブリッジやルーターなど別のプログラムに許可を与えると、ラッパーへの許可は置き換えられます。そのユーザーが再び許可を与えるまで、ラッパーは機能しなくなります。以前の許可がまだ有効だと決めつけず、転送前に `isEnabled` を確認してください。

新しいファクトリーバージョンによってラッパーが置き換えられると、各ウォレットは `approve_spl`で新しいラッパーに権限を付与します。古いラッパーがそのウォレットのトークンを移動できるのは、トークンアカウントのデリゲートであり続ける間だけです。新しいラッパーに許可を与えると、そのデリゲートは置き換えられます。

両方のレーンの完全なコードは、 [デュアルレーンアプリガイド](https://docs.rome.builders/ja/gaido/dual-lane-app.md#one-time-grant-the-wrapper) に記載されています。

## 入金と出金

* **EVM への入金** — SPL 側ではユーザーの PDA が所有する ATA に残高が加算され、ERC-20 ラッパーの残高にも直ちに反映されます。他のチェーンからの入金は、ブリッジ上でユーザー署名の認可を通じてオンチェーンで精算されます。
* **ガスをガストークンにラップする** — `Withdraw` プリコンパイル（`0x42…16`). `withdraw_to_ata(wei)` ネイティブガスを消費し、同等の数量をガストークン固有の小数桁数で呼び出し元のトークンアカウントに加算します。その残高はガストークンのラッパー（例: wUSDC）に表示されます。 `withdraw_to_pda(wei)` 呼び出し元のPDAにランポートを送金します。ガスがSOLのチェーンにのみ適用されます。ガスにUSDCを使用するHadrianとRubiconではリバートするため、代わりに `withdraw_to_ata` を使用してください。数量は18桁小数のガス単位で指定し、ガストークン単位の整数でなければなりません。USDCガスのチェーンでは10^12の倍数（小数桁数6桁の1単位）である必要があり、それ以外の場合は呼び出しがリバートします。 `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, …)`。上記の「1つのデリゲート」に関する注意を参照）と、受取人のトークンアカウントが必要です。 `ensureRecipientAta(solanaRecipient, mint)` でアカウントを作成できます。
  * `RomeBridgeWithdraw` は、CCTP経由でUSDCを別のチェーンに送ることもできます（`burnUSDC`）。その他の資産はWormhole経由で送信します（`burnETH`, `burnToWormhole`).

レジストリから最新の `RomeBridgeWithdraw` アドレスを取得してください。

SolanaとEthereumまたはAggLayerチェーン間でその他のトークンを移動する方法については、 [Solgate](https://docs.rome.builders/ja/romenoapuri/solgate.md) および [13. Solgate上で構築する](https://docs.rome.builders/ja/rome-academy/13-build-on-solgate.md).

## ガストークン

各チェーンには、SOLまたはSPLトークンのいずれかの独自のガストークンがあります。Rome Proxyの価格ソースには、Hermes APIフィード、Meteora DAMM v1プール、Meteora DAMM v2プール、または固定価格を指定できます。テストネットのHadrianとメインネットのRubiconではUSDCを使用します。Hadrianではテスト用USDC、Rubiconでは実際のUSDCを使用します。全チェーン共通のデフォルトのガストークンはありません。

## Token-2022のミント

ファクトリーはToken-2022のミントもラップします。mint\_info(mint)（セレクター `mint_info(mint)` （セレクター `0xe24bf5d4`）を使ってHelperプリコンパイルにミントの種類を問い合わせ、その応答に基づいてラッパーを選択します。 `mint_info` は5つの値を返します。

| 値              | 意味                                                |
| -------------- | ------------------------------------------------- |
| `tokenProgram` | ミントを所有するトークンプログラム（従来のSPL TokenプログラムまたはToken-2022） |
| `decimals`     | ミントの小数桁数                                          |
| `hookProgram`  | 転送フックプログラム。フックがない場合、またはフックが存在していても有効化されていない場合はゼロ  |
| `feeBps`       | ベーシスポイント単位の転送手数料。手数料がない場合、またはゼロに設定されている場合はゼロ      |
| `extensions`   | ミントが持つToken-2022拡張機能のビットマップ。拡張機能タイプNにはビットNを使用     |

ミントに割り当てられるもの:

| ミント                                                   | ラッパー                                                                       | `wrapper_kind_by_mint` |
| ----------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------- |
| 通常のミント、フックのないToken-2022ミント、またはフックが存在していても有効化されていないミント | キャッシュ済みラッパー（`SPL_ERC20_cached`)                                            | `1`                    |
| 転送フックが有効化されているToken-2022ミント                           | フック付きラッパー（`SPL_ERC20_Token2022Hooked`）。ファクトリーの `hooked_wrapper_deployer()` | `2`                    |

転送手数料のあるミントにはキャッシュ済みラッパーが割り当てられ、その `Transfer` イベントには、送信額ではなく、手数料差し引き後の受取額が記録されます。ミントに割り当てられた種類は、ファクトリーの `wrapper_kind_by_mint(mint)`で確認できます。稼働中のHadrianファクトリーでは、USDC、ETH、SOLの各ラッパーはすべて `1`.

拒否されるもの:

* 転送フックが有効化されているミントには、通常のラッパーを割り当てられません。そのミントに対して `SPL_ERC20` または `SPL_ERC20_cached` を直接デプロイすると、 `ArmedTransferHookUnsupported(mint, hookProgram)`でリバートします。ファクトリー経由の場合は、代わりにフック付きラッパーが割り当てられます。
* SPLミントではないアドレスを指定すると、 `mint_info` は `Invalid SPL mint account: <address>`.
* でリバートします。すでにラッパーが割り当てられているミントは、 `Token exists`でリバートし、すでに使用されているシンボルは、 `Token with symbol exists`.
* `add_spl_token_with_metadata` は、まずミント自体のToken-2022メタデータから名前とシンボルを読み取り、次にMetaplexから読み取ります。どちらのメタデータもない場合は、 `Mint asserts no name: use add_spl_token_no_metadata`.

フック付きラッパーの動作:

* Token-2022は転送のたびにフックを実行し、フックは転送に応じたアカウントを必要とします。ラッパーはそれらを特定できないため、呼び出し元がミントのextra-account-metasリストから必要なアカウント一式を解決して渡します。ラッパーはそのリストの固定部分（フックプログラムとその検証アカウント）を確認し、変更せずに転送します。
* 通常の `transfer`, `transferFrom` および `bridgeOutToSolana` 次のエラーでリバートします。 `HookAccountPlanRequired`。次を使用してください。 `transferWithHookAccounts`, `transferFromWithHookAccounts` および `bridgeOutToSolanaWithHookAccounts`これらの関数は、追加引数としてアカウントリストを受け取ります。
* ラッパーのデプロイ後にミントのフックプログラムが変更されると、転送は次のエラーでリバートします。 `HookConfigurationChanged`.
* トークンはプログラム間の直接呼び出し（レガシートラック）で移動し、キャッシュ済みトラックは使用しません。コントラクトはどちらか一方のトラックを一貫して使用します。また、レガシートラックの呼び出しはアトミック実行中にのみ行われるため、フック対応ラッパーを使用する呼び出しは、1つのアトミックトランザクションに収める必要があります。
* コントラクト残高を記録する台帳は保持しません。コントラクトに送られたトークンはコントラクト自身のトークンアカウントに入り、コントラクトは次の操作を実行した後にのみ、そのトークンを送金できます。 `approve_spl` ラッパー自体への権限付与。
* 他のラッパーと同じ [一度限りの権限付与](#one-time-grant-per-wallet) が必要です。

## 制約

* SPLトークンの数量は `uint64` （最大 18,446,744,073,709,551,615）
* ERC-20 の allowance（`approve` / `allowance`）は EVM のストレージに保存されます。ラッパーはユーザーの SPL デリゲートとしてトークンを移動します。この権限はラッパーごとに一度、ユーザーが付与します（「 [ウォレットごとの一度限りの権限付与](#one-time-grant-per-wallet))
* ERC-20 ラッパーのシンボルはファクトリーごとに一意である必要があります

## 次のステップ

* [コントラクトアドレス](https://docs.rome.builders/ja/rifarensu/contract-addresses.md) — プリコンパイルとチェーンごとのアドレス
* [EVM から Solana を呼び出す](https://docs.rome.builders/ja/gaido/call-solana-from-evm.md) — Solidity からの CPI と SPL 操作
* [Rome で Solana と EVM が連携する仕組み](https://docs.rome.builders/ja/ji-ben-gai-nian/how-solana-and-evm-meet.md)
* [Solana プログラムを統合する](https://docs.rome.builders/ja/gaido/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/ja/ji-ben-gai-nian/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.
