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

# Token-Interoperabilität

Wie ERC-20- und SPL-Token auf Rome dasselbe zugrunde liegende Konto sind.

Rome bildet einen ERC-20-Token und seinen zugrunde liegenden SPL-Token als ein gemeinsames Konto ab. Diese Seite erklärt, wie Token auf EVM und Solana funktionieren.

## Das Shared-State-Modell

Bei einer gewöhnlichen Wallet ist ein ERC-20-Token auf Rome ein **transparenter Wrapper** über einem SPL-Tokenkonto auf Solana. Das ERC-20-Guthaben der Wallet entspricht ihrem SPL-Guthaben. Eine aus der EVM-Adresse abgeleitete Programmadresse besitzt das Tokenkonto. Dies ist die **PDA mit externer Autorität**.

<figure><img src="https://511478552-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>

* Keine Synchronisierungsverzögerung: Das ERC-20-Guthaben der Wallet entspricht ihrem SPL-Guthaben.
* Bei gewöhnlichen Wallets, einschließlich MetaMask-Wallets und synthetischen Adressen, wird die Liquidität nicht aufgeteilt. Jeder Wrapper über einer Mint zeigt dasselbe Wallet-Guthaben an. Die `balanceOf` Methode liest dieses Guthaben aus dem Tokenkonto der Wallet aus. Token, die in EVM-Verträgen gehalten werden, werden je Wrapper verwaltet (siehe [Der Wrapper-Vertrag](#the-wrapper-contract)).
* Bei den Token einer Wallet wird nichts auf der einen Seite gesperrt und auf der anderen geprägt. In Verträgen gehaltene Token liegen im eigenen Escrow-Tokenkonto des Wrappers auf Solana. Jeder Wrapper verwaltet diese Token separat.

**Warum ein zweiter Wrapper das Guthaben nicht aufteilt**

Zwei Wrapper über derselben Mint zeigen dasselbe Wallet-Guthaben an. Wrapper lesen `totalSupply` aus der Solana-Mint. Auf Hadrian (Testnet) gaben drei wUSDC-Wrapper übereinstimmende Wallet-Guthaben zurück. Alle drei wUSDC-Wrapper (9.0.0, 8.0.0 und Mai 2026) gaben die Supply der Solana-Mint zurück.

Jede Factory lässt einen Wrapper pro Mint zu. Eine neue Factory-Version kann einen weiteren Wrapper für diese Mint bereitstellen. Das Registry-Verzeichnis gibt den kanonischen Wrapper je Chain an.

Eine Solana-Wallet, die USDC direkt hält, und eine EVM-Adresse halten Token derselben Mint. Solana-Pools verwenden für beide dieselben Tresore und Reserven.

Die Inhabertabelle im [Via-Explorer](https://docs.rome.builders/de/apps-auf-rome/via.md) wird aus den `Transfer` Ereignissen jedes Wrappers erstellt. Sie kann vom Guthaben des Tokenkontos abweichen, da direkte SPL-Transfers, `ActivateAta`und Transfers über einen anderen Wrapper nicht in den Ereignissen dieses Wrappers erscheinen.

> Die folgenden Importpfade verwenden `@rome-protocol/rome-solidity`. Das Paket ist nicht auf npm verfügbar; installieren Sie es aus dem öffentlichen [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) -Repository mit `npm install github:rome-protocol/rome-solidity`oder `forge install rome-protocol/rome-solidity` mit einem Remapping. Die Wrapper- und Factory-Verträge benötigen außerdem OpenZeppelin unter Foundry (siehe [Solidity-Verträge bereitstellen](https://docs.rome.builders/de/entwicklerleitfaden/deploy-solidity.md#using-the-rome-solidity-sdk)). Die Precompile-Schnittstellen befinden sich in [`contracts/interface.sol`](https://github.com/rome-protocol/rome-solidity/blob/master/contracts/interface.sol).

## Der Wrapper-Vertrag

`SPL_ERC20` (und seine Variante mit zwischengespeichertem Track `SPL_ERC20_cached`, die die Factory für jede Mint bereitstellt, außer für eine mit aktiviertem Transfer-Hook; siehe [Token-2022-Mints](#token-2022-mints)) stellt eine vollständige ERC-20-Schnittstelle für eine SPL-Mint bereit:

* `balanceOf()` — liest das ATA-Guthaben des Nutzers aus Solana aus (bei einer Vertragsadresse wird das eigene Ledger des Wrappers ausgelesen; siehe unten)
* `transfer()` / `transferFrom()` — verschieben Token auf Solana
* `approve()` / `allowance()` — ERC-20-Freigaben pro Ausgeber, die im EVM-Speicher gehalten werden (ein SPL-Tokenkonto kennt keine EVM-ähnlichen Freigaben). Sie sind von der einmaligen Erteilung unten getrennt: Damit der Wrapper die Token eines Nutzers überhaupt bewegen kann, fungiert er als SPL-Delegate dieses Nutzers. Der Nutzer gewährt ihm dieses Recht einmal pro Wallet.
* `totalSupply()` — liest den Bestand des SPL-Mints aus

Ein Vertrag kann die einmalige Berechtigung nicht erteilen. Daher werden die Token eines Vertrags im eigenen Tokenkonto des Wrappers gehalten und im Ledger des Wrappers erfasst. `balanceOf(contract)` liest dieses Ledger aus.

## Die Factory

`ERC20SPLFactory` erstellt einen Wrapper für jeden SPL-Mint:

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

// Einen Wrapper bereitstellen; Name/Symbol aus den Token-2022-Metadaten oder von Metaplex laden
address wrapper = factory.add_spl_token_with_metadata(splMint);

// Oder Name/Symbol manuell angeben
address wrapper = factory.add_spl_token_no_metadata(splMint, "USD Coin", "USDC");
```

Live-Factory-Adresse aus den `live` Einträgen der Registry (v0.2.0): Hadrian `0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078`. Frühere Factory-Verträge sind weiterhin on-chain, aber als `deprecated` oder `retired` in der [Registry](https://github.com/rome-protocol/rome-registry/tree/main/chains)gekennzeichnet; verwenden Sie sie nicht. Die Registry ist maßgeblich. Lesen Sie daher die Live-Adresse dort aus (siehe [Verträge in der Liste auslesen](https://docs.rome.builders/de/referenz/contract-addresses.md#reading-the-contracts-list)), anstatt sie in Ihren Code zu kopieren.

## Kanonische Mints

Es gibt keinen On-Chain-Token-Registry-Vertrag. Kanonische Wrapper sowie Gas- und Bridge-Token werden in der Off-Chain-Registry [`rome-protocol/registry`](https://github.com/rome-protocol/rome-registry)gepflegt; erlaubnisfrei erstellte Wrapper über `add_spl_token_no_metadata` werden anhand des On-Chain- `TokenCreated` Ereignisses ermittelt. Die Registry nennt für jeden Mint auf jeder Chain den kanonischen Wrapper. Wallet-Guthaben werden von allen Wrappern gemeinsam genutzt. Jeder Wrapper erfasst separat die Guthaben, die von EVM-Verträgen gehalten werden.

## SPL-Operationen aus Solidity

Für benutzer-PDA-signierte SPL-Primitiven verwenden Sie das **HelperProgram-** Precompile (`0xFF…09`) – für ATA-Erstellung, SPL-Transfers und die Umrechnung zwischen Gas und Lamports:

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

IHelperProgram helper = IHelperProgram(0xFF00000000000000000000000000000000000009);

helper.create_ata(user, mint);              // ATA des Nutzers für einen Mint erstellen
helper.transfer_spl(to, tokens, mint);      // SPL-Token von der PDA des Aufrufers übertragen
```

`transfer_spl` hat mehrere Überladungen (darunter eine Delegate-Variante für `transferFrom` Abläufe); siehe `interface.sol` für exakte Signaturen. Im Cached-Track befinden sich die entsprechenden Operationen auf `ISplCached` (`0xFF…05`) und `IAssociatedSplCached` (`0xFF…06`). Ein Vertrag verwendet durchgehend denselben Track.

## Einmalige Freigabe pro Wallet

Der Wrapper bewegt die Token eines Nutzers als **SPL-Delegate** des Tokenkontos dieses Nutzers. Daher muss eine Wallet dem Wrapper dieses Recht einmal pro Wrapper einräumen, bevor der Wrapper Token für sie bewegen kann. Die Freigabe erfolgt durch einen Aufruf des Helper-Precompiles (`0xff00000000000000000000000000000000000009`):

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

`approve_spl` wird vom eigenen Konto des Nutzers signiert. Der Nutzer sendet den Aufruf, nicht der Wrapper oder Ihr Vertrag. Die Mint-Adresse ist `mint_id()` auf dem Wrapper.

* **Wer benötigt die Freigabe?** Jede EVM-Wallet und jede synthetische Adresse eines Solana-Nutzers für jeden Wrapper, dessen Token sie bewegen möchte. Ein Vertrag, der Token mit `transferFrom` abruft, funktioniert nur für Nutzer, die dem Wrapper eine Freigabe erteilt haben.
* **So prüfen Sie die Freigabe** Rufen Sie `isEnabled(user)` auf dem Wrapper auf. Die Funktion gibt `true` zurück, sobald die Freigabe erteilt wurde.
* **Was passiert, wenn die Freigabe fehlt?** Die Übertragung wird mit dem SPL-Fehler `0x4` (Eigentümer stimmt nicht überein) abgebrochen.
* **Ein Delegate pro Tokenkonto.** Ein SPL-Tokenkonto hat nur einen Delegate. Erteilt man einem anderen Programm, etwa einer Bridge oder einem Router, eine Freigabe für dasselbe Tokenkonto, ersetzt diese die Freigabe des Wrappers. Der Wrapper funktioniert für diesen Nutzer dann nicht mehr, bis er ihm erneut eine Freigabe erteilt. Prüfen Sie `isEnabled` vor einer Übertragung, statt davon auszugehen, dass eine frühere Freigabe noch gilt.

Wenn eine neue Factory-Version einen Wrapper ersetzt, erteilt jede Wallet dem neuen Wrapper mit `approve_spl`eine Berechtigung. Der alte Wrapper kann die Token dieser Wallet nur bewegen, solange er Delegate des Tokenkontos bleibt. Mit der Freigabe für den neuen Wrapper wird dieser Delegate ersetzt.

Der [Leitfaden für Dual-Lane-Apps](https://docs.rome.builders/de/entwicklerleitfaden/dual-lane-app.md#one-time-grant-the-wrapper) enthält den vollständigen Code für beide Lanes.

## Ein- und Auszahlungen

* **In die EVM** — auf der SPL-Seite wird das Guthaben der PDA-eigenen ATA des Nutzers gutgeschrieben; der ERC-20-Wrapper bildet das Guthaben unmittelbar ab. Eingehende Übertragungen von anderen Chains werden On-Chain über eine vom Nutzer signierte Autorisierung auf der Bridge abgewickelt.
* **Gas in den Gas-Token umwandeln** — rufen Sie das `Withdraw` Precompile (`0x42…16`). `withdraw_to_ata(wei)` verbrennt natives Gas und schreibt den entsprechenden Betrag in den Dezimalstellen des Gastokens dem Tokenkonto des Aufrufers gut. Der Wrapper des Gastokens (z. B. wUSDC) zeigt ihn anschließend als Guthaben an. `withdraw_to_pda(wei)` zahlt Lamports an die PDA des Aufrufers aus und funktioniert nur auf einer Chain, deren Gas SOL ist. Auf Hadrian und Rubicon, die USDC als Gas verwenden, wird der Aufruf zurückgesetzt. Verwende dort stattdessen `withdraw_to_ata` . Der Betrag wird in Gas-Einheiten mit 18 Dezimalstellen angegeben und muss einem ganzzahligen Vielfachen einer Gastoken-Einheit entsprechen: Auf einer Chain mit USDC als Gas muss er ein Vielfaches von 10^12 (einer Einheit mit 6 Dezimalstellen) sein, andernfalls wird der Aufruf zurückgesetzt. `HelperProgram.deposit_from_ata(wei)` funktioniert umgekehrt und wandelt den Gastoken im Tokenkonto des Aufrufers wieder in natives Gas um; dabei gilt dieselbe Vielfachregel. Hierbei handelt es sich um Konvertierungen von Gastoken, nicht um eine Auszahlung anderer Token.
* **Auszahlung an Solana in beliebigen anderen Token** — das Guthaben des Wrappers entspricht bereits dem SPL-Guthaben; für die Auszahlung genügt also eine SPL-Übertragung:
  * `HelperProgram.transfer_spl_to_signer(amount, mint)` sendet die Token des Aufrufers an das Tokenkonto der Solana-Wallet, die die Transaktion signiert hat. Dieser Rückweg erreicht die eigene Wallet des Nutzers nur über den von der Wallet signierten Solana-Pfad. Bei einem Aufruf über MetaMask oder das Relay ist der Signierer Rome's Proxy-Payer, sodass der Aufruf fehlschlägt oder die Token an Rome gehen. Verwende stattdessen `transfer_spl` oder `RomeBridgeWithdraw.bridgeOutToSolana` .
  * `RomeBridgeWithdraw.bridgeOutToSolana(solanaRecipient, amount, mint)` sendet sie an eine beliebige Solana-Wallet. Dafür ist die Genehmigung des Nutzers für den Bridge-Vertrag erforderlich (`approve_spl(bridge, …)`, siehe den Hinweis zu einem einzelnen Delegate oben). Außerdem muss das Tokenkonto des Empfängers vorhanden sein; `ensureRecipientAta(solanaRecipient, mint)` erstellt es.
  * `RomeBridgeWithdraw` verbrennt außerdem USDC, um es über CCTP an eine andere Chain zu senden (`burnUSDC`), und sendet andere Assets über Wormhole (`burnETH`, `burnToWormhole`).

Die aktuelle Adresse von `RomeBridgeWithdraw` finden Sie im Registry.

Informationen dazu, wie Sie andere Token zwischen Solana und Ethereum oder AggLayer-Chains übertragen, finden Sie unter [Solgate](https://docs.rome.builders/de/apps-auf-rome/solgate.md) und [13. Mit Solgate entwickeln](https://docs.rome.builders/de/rome-academy/13-build-on-solgate.md).

## Gastoken

Jede Chain hat ihren eigenen Gastoken: SOL oder einen SPL-Token. Die Preisquelle des Rome Proxy kann ein Hermes-API-Feed, ein Meteora-DAMM-v1-Pool, ein Meteora-DAMM-v2-Pool oder ein Festpreis sein. Hadrian (Testnet) und Rubicon (Mainnet) verwenden USDC. Hadrian verwendet Test-USDC. Rubicon verwendet echtes USDC. Es gibt keinen universellen Standard-Gastoken.

## Token-2022-Mints

Die Factory wrappt auch Token-2022-Mints. Sie fragt das Helper-Precompile mit `mint_info(mint)` (Selektor `0xe24bf5d4`) nach dem Mint-Typ und wählt anhand der Antwort den passenden Wrapper aus. `mint_info` gibt fünf Werte zurück:

| Wert           | Bedeutung                                                                                                   |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `tokenProgram` | das Token-Programm, dem der Mint gehört (das klassische SPL-Token-Programm oder Token-2022)                 |
| `decimals`     | die Dezimalstellen des Mints                                                                                |
| `hookProgram`  | das Transfer-Hook-Programm oder null, wenn kein Hook vorhanden oder der vorhandene Hook nicht aktiviert ist |
| `feeBps`       | die Transfergebühr in Basispunkten oder null, wenn keine Gebühr anfällt oder sie auf null gesetzt ist       |
| `extensions`   | eine Bitmap der Token-2022-Erweiterungen des Mints; Bit N steht für Erweiterungstyp N                       |

Welchen Wrapper ein Mint erhält:

| Mint                                                                                                            | Wrapper                                                                                                 | `wrapper_kind_by_mint` |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------- |
| Ein gewöhnlicher Mint, ein Token-2022-Mint ohne Hook oder ein Mint mit vorhandenem, aber nicht aktiviertem Hook | den gecachten Wrapper (`SPL_ERC20_cached`)                                                              | `1`                    |
| Ein Token-2022-Mint mit aktiviertem Transfer-Hook                                                               | den Wrapper mit Hook (`SPL_ERC20_Token2022Hooked`), bereitgestellt über den `hooked_wrapper_deployer()` | `2`                    |

Ein Mint mit Transfergebühr erhält den gecachten Wrapper, und sein `Transfer` -Ereignis meldet den nach Abzug der Gebühr eingegangenen Betrag, nicht den gesendeten Betrag. Den Wrapper-Typ eines Mints können Sie über die Factory mit `wrapper_kind_by_mint(mint)`ermitteln; bei der aktiven Hadrian-Factory geben die USDC-, ETH- und SOL-Wrapper alle `1`.

Was abgelehnt wird:

* Ein Mint mit aktiviertem Transfer-Hook kann keinen der gewöhnlichen Wrapper erhalten. Die Bereitstellung von `SPL_ERC20` oder `SPL_ERC20_cached` dafür führt direkt zu einem Revert mit `ArmedTransferHookUnsupported(mint, hookProgram)`. Über die Factory wird in diesem Fall stattdessen der Wrapper mit Hook verwendet.
* Bei einer Adresse, die kein SPL-Mint ist, führt `mint_info` zu einem Revert mit `Invalid SPL mint account: <address>`.
* Bei einem Mint, für den bereits ein Wrapper existiert, erfolgt ein Revert mit `Token exists`, und bei einem bereits verwendeten Symbol erfolgt ein Revert mit `Token with symbol exists`.
* `add_spl_token_with_metadata` liest Name und Symbol zuerst aus den Token-2022-Metadaten des Mints selbst und danach aus Metaplex. Wenn der Mint keine dieser Angaben enthält, erfolgt ein Revert mit `Mint asserts no name: use add_spl_token_no_metadata`.

Funktionsweise des Wrappers mit Hook:

* Token-2022 führt den Hook bei jeder Übertragung aus, und der Hook benötigt Konten, die von der Übertragung abhängen. Der Wrapper kann diese nicht selbst ermitteln, daher löst der Aufrufer die vollständige Kontenliste anhand der Extra-Account-Metas-Liste des Mints auf und übergibt sie. Der Wrapper prüft den festen Teil dieser Liste (das Hook-Programm und sein Validierungskonto) und leitet sie unverändert weiter.
* Die einfachen Funktionen `transfer`, `transferFrom` und `bridgeOutToSolana` mit `HookAccountPlanRequired`. Verwenden Sie `transferWithHookAccounts`, `transferFromWithHookAccounts` und `bridgeOutToSolanaWithHookAccounts`, die die Kontenliste als zusätzliches Argument entgegennehmen.
* Wenn sich das Hook-Programm des Mints ändert, nachdem der Wrapper bereitgestellt wurde, werden Transfers mit `HookConfigurationChanged`.
* Tokens werden per direktem Cross-Program-Aufruf verschoben, also über den Legacy-Pfad, nicht über den gecachten Pfad. Ein Vertrag verwendet durchgehend denselben Pfad, und Aufrufe über den Legacy-Pfad werden nur in atomarer Ausführung ausgeführt. Daher muss ein Aufruf mit dem Hook-Wrapper in eine atomare Transaktion passen.
* Für die Guthaben des Vertrags wird kein Kontobuch geführt. An einen Vertrag gesendete Tokens landen auf dessen eigenem Token-Konto. Der Vertrag kann sie erst weitersenden, nachdem er dem Wrapper die `approve_spl` Freigabe erteilt hat.
* Wie jeder andere Wrapper benötigt er dieselbe [einmalige Freigabe](#one-time-grant-per-wallet) .

## Einschränkungen

* SPL-Tokenbeträge sind `uint64` (max. 18,446,744,073,709,551,615)
* ERC-20-Freigaben (`approve` / `allowance`) werden im EVM-Speicher abgelegt. Der Wrapper verschiebt Tokens als SPL-Delegate des Nutzers, für den der Nutzer einmalig pro Wrapper eine Freigabe erteilt (siehe [Einmalige Freigabe pro Wallet](#one-time-grant-per-wallet))
* ERC-20-Wrapper-Symbole müssen innerhalb jeder Factory eindeutig sein

## Wie geht es weiter?

* [Vertragsadressen](https://docs.rome.builders/de/referenz/contract-addresses.md) — Precompiles und Adressen pro Chain
* [Solana von der EVM aus aufrufen](https://docs.rome.builders/de/entwicklerleitfaden/call-solana-from-evm.md) — CPI- und SPL-Operationen aus Solidity
* [Wie Solana und die EVM auf Rome zusammenkommen](https://docs.rome.builders/de/kernkonzepte/how-solana-and-evm-meet.md)
* [Ein Solana-Programm integrieren](https://docs.rome.builders/de/entwicklerleitfaden/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/de/kernkonzepte/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.
