> 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/id/konsep-inti/token-interop.md).

# Interoperabilitas Token

Bagaimana token ERC-20 dan SPL adalah akun dasar yang sama di Rome.

Rome merepresentasikan token ERC-20 dan token SPL yang mendasarinya sebagai satu akun bersama. Halaman ini menjelaskan cara kerja token di EVM dan Solana.

## Model state bersama

Untuk dompet biasa, token ERC-20 di Rome adalah **pembungkus transparan** atas akun token SPL di Solana. Saldo ERC-20 dompet sama dengan saldo SPL-nya. Alamat turunan program untuk alamat EVM tersebut memiliki akun token itu. Ini adalah **PDA otoritas eksternal**.

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

* Tanpa jeda sinkronisasi: saldo ERC-20 dompet sama dengan saldo SPL-nya.
* Dompet biasa, termasuk dompet MetaMask dan alamat sintetis, tidak mengalami fragmentasi likuiditas. Setiap pembungkus atas suatu mint menampilkan saldo dompet yang sama. Metode `balanceOf` membaca saldo tersebut dari akun token dompet. Token yang disimpan di dalam kontrak EVM disimpan per pembungkus (lihat [Kontrak pembungkus](#the-wrapper-contract)).
* Untuk token milik dompet, tidak ada yang dikunci di satu sisi dan dicetak di sisi lain. Token yang disimpan dalam kontrak berada di akun token escrow milik pembungkus itu sendiri di Solana. Setiap pembungkus melacak token tersebut secara terpisah.

**Mengapa pembungkus kedua tidak membagi saldo**

Dua pembungkus atas mint yang sama menampilkan saldo dompet yang sama. Pembungkus membaca `totalSupply` dari mint Solana. Di Hadrian (testnet), tiga pembungkus wUSDC menghasilkan saldo dompet yang sama. Ketiga pembungkus wUSDC (9.0.0, 8.0.0, dan Mei 2026) menghasilkan suplai dari mint Solana.

Setiap factory hanya mengizinkan satu pembungkus untuk setiap mint. Versi factory baru dapat menerapkan pembungkus lain untuk mint tersebut. Registry mencantumkan pembungkus kanonis untuk setiap chain.

Dompet Solana yang menyimpan USDC secara langsung dan alamat EVM menyimpan token dari mint yang sama. Pool Solana menggunakan vault dan cadangan yang sama untuk keduanya.

Tabel pemegang di [Via explorer](https://docs.rome.builders/id/aplikasi-di-rome/via.md) dibuat dari event `Transfer` setiap pembungkus. Tabel ini dapat berbeda dari saldo akun token karena transfer SPL langsung, `ActivateAta`, dan transfer melalui pembungkus lain tidak muncul dalam event pembungkus tersebut.

> Jalur impor di bawah menggunakan `@rome-protocol/rome-solidity`. Paket ini tidak tersedia di npm; instal dari repositori publik [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) dengan `npm install github:rome-protocol/rome-solidity`, atau `forge install rome-protocol/rome-solidity` dengan remapping; kontrak pembungkus dan factory juga memerlukan OpenZeppelin di Foundry (lihat [Menerapkan Kontrak Solidity](https://docs.rome.builders/id/panduan-pengembang/deploy-solidity.md#using-the-rome-solidity-sdk)). Antarmuka precompile tersedia di [`contracts/interface.sol`](https://github.com/rome-protocol/rome-solidity/blob/master/contracts/interface.sol).

## Kontrak pembungkus

`SPL_ERC20` (dan varian cached-track-nya `SPL_ERC20_cached`, yang diterapkan factory untuk setiap mint kecuali mint yang memiliki transfer hook aktif; lihat [Mint Token-2022](#token-2022-mints)) menyediakan antarmuka ERC-20 lengkap untuk mint SPL:

* `balanceOf()` — membaca saldo ATA pengguna dari Solana (untuk alamat kontrak, fungsi ini membaca ledger milik pembungkus itu sendiri; lihat di bawah)
* `transfer()` / `transferFrom()` — memindahkan token di Solana
* `approve()` / `allowance()` — allowance ERC-20 per pembelanja yang disimpan di penyimpanan EVM (akun token SPL tidak memiliki allowance seperti EVM). Allowance ini terpisah dari pemberian izin satu kali di bawah: agar dapat memindahkan token pengguna, wrapper bertindak sebagai delegate SPL pengguna tersebut, dan pengguna memberikan hak itu sekali untuk setiap wallet
* `totalSupply()` — membaca suplai mint SPL

Kontrak tidak dapat memberikan izin satu kali tersebut, sehingga token kontrak disimpan di akun token milik wrapper sendiri dan dicatat dalam ledger wrapper. `balanceOf(contract)` membaca ledger tersebut.

## Factory

`ERC20SPLFactory` menerapkan wrapper untuk mint SPL apa pun:

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

// Terapkan wrapper, ambil nama/simbol dari metadata Token-2022 mint atau Metaplex
address wrapper = factory.add_spl_token_with_metadata(splMint);

// Atau tentukan nama/simbol secara manual
address wrapper = factory.add_spl_token_no_metadata(splMint, "USD Coin", "USDC");
```

Alamat factory aktif, dari entri `live` di registry (v0.2.0): Hadrian `0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078`. Factory terdahulu masih ada di blockchain, tetapi ditandai `deprecated` atau `retired` di [registry](https://github.com/rome-protocol/rome-registry/tree/main/chains); jangan gunakan. Registry adalah sumber acuan, jadi baca alamat aktif dari sana (lihat [Membaca daftar kontrak](https://docs.rome.builders/id/referensi/contract-addresses.md#reading-the-contracts-list)) alih-alih menyalinnya ke kode Anda.

## Mint kanonis

Tidak ada kontrak registri token di blockchain. Wrapper kanonis serta token gas/bridge dikurasi di [`rome-protocol/registry`](https://github.com/rome-protocol/rome-registry)off-chain; wrapper tanpa izin yang dibuat melalui `add_spl_token_no_metadata` ditemukan dari event `TokenCreated` di blockchain. Registry mencantumkan wrapper kanonis untuk setiap mint di setiap chain. Saldo wallet digunakan bersama oleh berbagai wrapper. Setiap wrapper mencatat secara terpisah saldo yang dimiliki kontrak EVM.

## Operasi SPL dari Solidity

Untuk primitif SPL yang ditandatangani PDA pengguna, gunakan precompile **HelperProgram** (`0xFF…09`) — pembuatan ATA, transfer SPL, dan konversi gas↔lamport:

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

IHelperProgram helper = IHelperProgram(0xFF00000000000000000000000000000000000009);

helper.create_ata(user, mint);              // buat ATA pengguna untuk suatu mint
helper.transfer_spl(to, tokens, mint);      // transfer SPL dari PDA pemanggil
```

`transfer_spl` memiliki beberapa overload (termasuk varian delegate untuk alur `transferFrom` ); lihat `interface.sol` untuk tanda tangan yang persis. Pada jalur cached, operasi yang setara tersedia di `ISplCached` (`0xFF…05`) dan `IAssociatedSplCached` (`0xFF…06`). Sebuah kontrak menggunakan satu jalur secara konsisten.

## Persetujuan satu kali per dompet

Wrapper memindahkan token pengguna sebagai **delegate SPL** untuk akun token pengguna tersebut. Karena itu, dompet harus memberikan hak tersebut sekali untuk setiap wrapper sebelum wrapper dapat memindahkan tokennya. Persetujuan ini dilakukan dengan satu pemanggilan ke precompile Helper (`0xff00000000000000000000000000000000000009`):

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

`approve_spl` ditandatangani oleh akun pengguna sendiri, jadi pengguna yang mengirimkannya, bukan wrapper atau kontrak Anda. Mint-nya adalah `mint_id()` pada wrapper.

* **Siapa yang memerlukannya.** Setiap dompet EVM dan setiap alamat sintetis pengguna Solana memerlukannya untuk setiap wrapper yang tokennya ingin dipindahkan. Kontrak yang menarik token dengan `transferFrom` hanya berfungsi untuk pengguna yang telah memberikan persetujuan kepada wrapper.
* **Cara memeriksanya.** Panggil `isEnabled(user)` pada wrapper. Fungsi ini mengembalikan `true` setelah persetujuan diberikan.
* **Tanda yang muncul jika persetujuan belum diberikan.** Transfer gagal dan dibatalkan (revert) dengan kesalahan SPL `0x4` (ketidakcocokan pemilik).
* **Satu delegate per akun token.** Akun token SPL hanya memiliki satu delegate. Memberikan persetujuan kepada program lain untuk akun token yang sama, seperti bridge atau router, akan menggantikan persetujuan wrapper. Akibatnya, wrapper tidak lagi berfungsi untuk pengguna tersebut sampai mereka memberikan persetujuan lagi. Periksa `isEnabled` sebelum transfer, alih-alih berasumsi bahwa persetujuan sebelumnya masih berlaku.

Saat versi factory baru menggantikan wrapper, setiap dompet memberikan izin kepada wrapper baru dengan `approve_spl`. Wrapper lama hanya dapat memindahkan token dompet tersebut selama masih menjadi delegate akun token. Memberikan persetujuan kepada wrapper baru akan menggantikan delegate tersebut.

Panduan aplikasi [dua jalur](https://docs.rome.builders/id/panduan-pengembang/dual-lane-app.md#one-time-grant-the-wrapper) berisi kode lengkap untuk kedua jalur.

## Deposit dan penarikan

* **Ke EVM** — sisi SPL mengkreditkan ATA milik PDA pengguna; wrapper ERC-20 langsung mencerminkan saldo tersebut. Transfer masuk dari chain lain diselesaikan secara on-chain melalui otorisasi yang ditandatangani pengguna pada bridge.
* **Mengonversi gas menjadi token gas** — panggil `Withdraw` precompile (`0x42…16`). `withdraw_to_ata(wei)` membakar gas native dan mengkreditkan jumlah ekuivalen, dalam satuan desimal token gas itu sendiri, ke akun token pemanggil, yang kemudian ditampilkan sebagai saldo oleh wrapper token gas (misalnya wUSDC). `withdraw_to_pda(wei)` membayar lamport ke PDA pemanggil dan hanya berlaku pada chain yang gas-nya SOL; pemanggilan ini akan revert di Hadrian dan Rubicon, yang menggunakan USDC sebagai gas, jadi gunakan `withdraw_to_ata` di sana. Jumlahnya dinyatakan dalam satuan gas dengan 18 desimal dan harus berupa kelipatan bulat satuan token gas: pada chain dengan gas USDC, nilainya harus kelipatan 10^12 (satu satuan dengan 6 desimal); jika tidak, pemanggilan akan revert. `HelperProgram.deposit_from_ata(wei)` melakukan kebalikannya, yaitu mengubah token gas di akun token pemanggil kembali menjadi gas native, dengan aturan kelipatan yang sama. Ini adalah konversi token gas, bukan mekanisme untuk menarik token lain.
* **Keluar ke Solana, token lain** — saldo wrapper itu sendiri sudah merupakan saldo SPL, jadi memindahkannya keluar berarti melakukan transfer SPL:
  * `HelperProgram.transfer_spl_to_signer(amount, mint)` mengirim token pemanggil ke akun token milik dompet Solana yang menandatangani transaksi. Jalur pengembalian ini hanya mencapai dompet pengguna sendiri pada jalur Solana yang ditandatangani oleh dompet tersebut. Jika dipanggil dari MetaMask atau melalui relay, penandatangan adalah proxy payer Rome, sehingga pemanggilan gagal atau token dikirim ke Rome. Gunakan `transfer_spl` atau `RomeBridgeWithdraw.bridgeOutToSolana` sebagai gantinya.
  * `RomeBridgeWithdraw.bridgeOutToSolana(solanaRecipient, amount, mint)` mengirimkannya ke dompet Solana mana pun. Fungsi ini memerlukan grant pengguna untuk kontrak bridge (`approve_spl(bridge, …)`, lihat catatan tentang satu delegate di atas), dan akun token penerima harus sudah ada; `ensureRecipientAta(solanaRecipient, mint)` membuatnya.
  * `RomeBridgeWithdraw` juga membakar USDC untuk mengirimkannya ke chain lain melalui CCTP (`burnUSDC`) dan mengirim aset lain melalui Wormhole (`burnETH`, `burnToWormhole`).

Ambil alamat `RomeBridgeWithdraw` terbaru dari registry.

Untuk memindahkan token lain antara Solana dan Ethereum atau chain AggLayer, lihat [Solgate](https://docs.rome.builders/id/aplikasi-di-rome/solgate.md) dan [13. Membangun di Solgate](https://docs.rome.builders/id/rome-academy/13-build-on-solgate.md).

## Token gas

Setiap chain memiliki token gasnya sendiri: SOL atau token SPL. Sumber harga Rome Proxy dapat berupa feed API Hermes, pool Meteora DAMM v1, pool Meteora DAMM v2, atau harga tetap. Hadrian (testnet) dan Rubicon (mainnet) menggunakan USDC. Hadrian menggunakan USDC uji coba. Rubicon menggunakan USDC asli. Tidak ada token gas default yang berlaku universal.

## Mint Token-2022

Factory juga membungkus mint Token-2022. Factory menanyakan jenis mint kepada precompile Helper menggunakan `mint_info(mint)` (selector `0xe24bf5d4`), lalu memilih wrapper berdasarkan jawabannya. `mint_info` mengembalikan lima nilai:

| Nilai          | Arti                                                                                           |
| -------------- | ---------------------------------------------------------------------------------------------- |
| `tokenProgram` | program token yang memiliki mint tersebut (program SPL Token klasik atau Token-2022)           |
| `decimals`     | jumlah desimal mint                                                                            |
| `hookProgram`  | program transfer-hook, atau nol jika tidak ada hook atau hook tersedia tetapi tidak diaktifkan |
| `feeBps`       | biaya transfer dalam basis poin, atau nol jika tidak ada biaya atau nilainya ditetapkan ke nol |
| `extensions`   | bitmap ekstensi Token-2022 yang dimiliki mint, bit N untuk jenis ekstensi N                    |

Wrapper yang diperoleh mint:

| Mint                                                                                                | Wrapper                                                                                               | `wrapper_kind_by_mint` |
| --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------- |
| Mint biasa, mint Token-2022 tanpa hook, atau mint dengan hook yang tersedia tetapi tidak diaktifkan | wrapper yang di-cache (`SPL_ERC20_cached`)                                                            | `1`                    |
| Mint Token-2022 dengan transfer hook yang diaktifkan                                                | wrapper dengan hook (`SPL_ERC20_Token2022Hooked`), yang di-deploy melalui `hooked_wrapper_deployer()` | `2`                    |

Mint dengan biaya transfer memperoleh wrapper yang di-cache, dan event `Transfer` melaporkan jumlah yang diterima setelah biaya dipotong, bukan jumlah yang dikirim. Anda dapat membaca jenis wrapper yang diperoleh mint dari factory menggunakan `wrapper_kind_by_mint(mint)`; pada factory Hadrian yang aktif, wrapper USDC, ETH, dan SOL semuanya mengembalikan `1`.

Yang ditolak:

* Mint dengan transfer hook yang diaktifkan tidak dapat memperoleh wrapper biasa. Men-deploy `SPL_ERC20` atau `SPL_ERC20_cached` secara langsung untuk mint tersebut akan gagal dengan `ArmedTransferHookUnsupported(mint, hookProgram)`. Melalui factory, kasus ini akan menggunakan wrapper dengan hook.
* Alamat yang bukan mint SPL menyebabkan `mint_info` gagal dengan `Invalid SPL mint account: <address>`.
* Mint yang sudah memiliki wrapper akan gagal dengan `Token exists`, dan simbol yang sudah digunakan akan gagal dengan `Token with symbol exists`.
* `add_spl_token_with_metadata` pertama-tama membaca nama dan simbol dari metadata Token-2022 milik mint itu sendiri, lalu dari Metaplex. Jika mint tidak memiliki keduanya, operasi akan gagal dengan `Mint asserts no name: use add_spl_token_no_metadata`.

Cara kerja wrapper dengan hook:

* Token-2022 menjalankan hook pada setiap transfer, dan hook memerlukan akun yang bergantung pada transfer tersebut. Wrapper tidak dapat menentukan akun-akun ini, jadi pemanggil mengambil daftar akun lengkap dari daftar extra-account-metas milik mint dan meneruskannya. Wrapper memeriksa bagian tetap dari daftar tersebut (program hook dan akun validasinya), lalu meneruskannya tanpa perubahan.
* transfer biasa `transfer`, `transferFrom` dan `bridgeOutToSolana` mengembalikan error dengan `HookAccountPlanRequired`. Gunakan `transferWithHookAccounts`, `transferFromWithHookAccounts` dan `bridgeOutToSolanaWithHookAccounts`, yang menerima daftar akun sebagai argumen tambahan.
* Jika program hook pada mint berubah setelah wrapper diterapkan, transfer akan mengembalikan error dengan `HookConfigurationChanged`.
* Wrapper ini memindahkan token melalui panggilan lintas program langsung, yaitu jalur lama, dan tidak menggunakan jalur cache. Kontrak menggunakan satu jalur secara konsisten, dan panggilan pada jalur lama hanya berjalan dalam eksekusi atomik. Jadi, panggilan yang menggunakan wrapper dengan hook harus muat dalam satu transaksi atomik.
* Wrapper ini tidak menyimpan ledger saldo kontrak. Token yang dikirim ke kontrak masuk ke akun token milik kontrak itu sendiri, dan kontrak hanya dapat meneruskannya setelah memberikan `approve_spl` hibah kepada wrapper itu sendiri.
* Wrapper ini memerlukan [hibah satu kali](#one-time-grant-per-wallet) yang sama seperti wrapper lainnya.

## Batasan

* Jumlah token SPL bertipe `uint64` (maks. 18,446,744,073,709,551,615)
* Allowance ERC-20 (`approve` / `allowance`) adalah penyimpanan EVM. Wrapper memindahkan token sebagai delegasi SPL pengguna, yang diberikan pengguna satu kali untuk setiap wrapper (lihat [Hibah satu kali per dompet](#one-time-grant-per-wallet))
* Simbol wrapper ERC-20 harus unik untuk setiap factory

## Langkah Selanjutnya

* [Alamat Kontrak](https://docs.rome.builders/id/referensi/contract-addresses.md) — precompile dan alamat per chain
* [Memanggil Solana dari EVM](https://docs.rome.builders/id/panduan-pengembang/call-solana-from-evm.md) — operasi CPI dan SPL dari Solidity
* [Cara Solana dan EVM terhubung di Rome](https://docs.rome.builders/id/konsep-inti/how-solana-and-evm-meet.md)
* [Mengintegrasikan program Solana](https://docs.rome.builders/id/panduan-pengembang/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/id/konsep-inti/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.
