> 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/tr/temel-kavramlar/token-interop.md).

# Token Uyumluluğu

ERC-20 ve SPL token'ların Rome üzerinde nasıl aynı temel hesap olduğu.

Rome, bir ERC-20 tokenı ve onun temelindeki SPL tokenını tek bir ortak hesap olarak temsil eder. Bu sayfa, tokenların EVM ve Solana genelinde nasıl çalıştığını açıklar.

## Paylaşılan durum modeli

Sıradan bir cüzdanda Rome üzerindeki ERC-20 tokenı, Solana'daki bir SPL token hesabının **şeffaf bir sarmalayıcısıdır**  . Cüzdanın ERC-20 bakiyesi, SPL bakiyesidir. EVM adresi için türetilmiş bir program adresi, token hesabının sahibidir. Bu adres, **harici yetkili PDA'sıdır**.

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

* Eşitleme gecikmesi yoktur: Cüzdanın ERC-20 bakiyesi, SPL bakiyesidir.
* MetaMask cüzdanları ve sentetik adresler de dahil olmak üzere sıradan cüzdanlarda likidite parçalanması olmaz. Bir mint üzerindeki tüm sarmalayıcılar aynı cüzdan bakiyesini gösterir. balanceOf `balanceOf` yöntemi, bu bakiyeyi cüzdanın token hesabından okur. EVM sözleşmelerinde tutulan tokenlar, her sarmalayıcı için ayrı tutulur (bkz. [Sarmalayıcı sözleşmesi](#the-wrapper-contract)).
* Cüzdanın tokenları için tokenlar bir tarafta kilitlenip diğer tarafta basılmaz. Sözleşmede tutulan tokenlar, Solana'da sarmalayıcının kendi emanet token hesabında bulunur. Her sarmalayıcı bu tokenları ayrı ayrı izler.

**İkinci bir sarmalayıcı bakiyeyi neden bölmez?**

Aynı mint üzerindeki iki sarmalayıcı da aynı cüzdan bakiyesini gösterir. Sarmalayıcılar `totalSupply` değerini Solana mintinden okur. Hadrian'da (test ağı) üç wUSDC sarmalayıcısı aynı cüzdan bakiyelerini döndürdü. Üç wUSDC sarmalayıcısının tümü (9.0.0, 8.0.0 ve Mayıs 2026) Solana mintinin arzını döndürdü.

Her fabrika, mint başına bir sarmalayıcıya izin verir. Yeni bir fabrika sürümü, o mint için başka bir sarmalayıcı dağıtabilir. Kayıt defteri, her zincir için kanonik sarmalayıcıyı belirtir.

USDC'yi doğrudan elinde tutan bir Solana cüzdanı ile bir EVM adresi, aynı minte ait tokenları tutar. Solana havuzları her ikisi için de aynı kasaları ve rezervleri kullanır.

Via explorer'daki [Via explorer](https://docs.rome.builders/tr/rome-uzerindeki-uygulamalar/via.md) sahipler tablosu, her sarmalayıcının `Transfer` olaylarından oluşturulur. Doğrudan SPL transferleri, `ActivateAta`ve başka bir sarmalayıcı üzerinden yapılan transferler o sarmalayıcının olaylarında görünmediğinden bu tablo, token hesabı bakiyesinden farklı olabilir.

> Aşağıdaki içe aktarma yollarında `@rome-protocol/rome-solidity`kullanılır. Paket npm'de bulunmaz; paketi herkese açık [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) deposundan şu komutla yükleyin: `npm install github:rome-protocol/rome-solidity`veya bir eşleme kullanarak `forge install rome-protocol/rome-solidity` komutuyla yükleyin. Sarmalayıcı ve fabrika sözleşmeleri için Foundry altında OpenZeppelin de gerekir (bkz. [Solidity Sözleşmelerini Dağıtma](https://docs.rome.builders/tr/gelistirici-kilavuzlari/deploy-solidity.md#using-the-rome-solidity-sdk)). Ön derleme arayüzleri şu konumdadır: [`contracts/interface.sol`](https://github.com/rome-protocol/rome-solidity/blob/master/contracts/interface.sol).

## Sarmalayıcı sözleşmesi

`SPL_ERC20` (ve önbellekli izleme varyantı `SPL_ERC20_cached`, fabrika bunu etkin bir transfer kancasına sahip olanlar dışındaki tüm mintler için dağıtır; bkz. [Token-2022 mintleri](#token-2022-mints)) bir SPL minti üzerinde eksiksiz bir ERC-20 arayüzü sunar:

* `balanceOf()` — kullanıcının ATA bakiyesini Solana'dan okur (bir sözleşme adresi için, aşağıda açıklandığı gibi sarmalayıcının kendi defterini okur)
* `transfer()` / `transferFrom()` — tokenları Solana'da taşır
* `approve()` / `allowance()` — EVM depolamasında tutulan, harcayıcı başına ERC-20 harcama izinleri (SPL token hesabında EVM tarzı harcama izinleri bulunmaz). Bunlar aşağıdaki tek seferlik yetkiden ayrıdır: sarmalayıcının bir kullanıcının tokenlarını taşıyabilmesi için kullanıcının SPL delegesi olarak hareket etmesi gerekir ve kullanıcı bu yetkiyi her cüzdan için bir kez verir.
* `totalSupply()` — SPL mint arzını okur

Bir sözleşme tek seferlik yetkiyi veremez; bu nedenle sözleşmeye ait tokenlar sarmalayıcının kendi token hesabında tutulur ve sarmalayıcının defterinde izlenir. `balanceOf(contract)` bu defteri okur.

## Fabrika

`ERC20SPLFactory` herhangi bir SPL mint için bir sarmalayıcı dağıtır:

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

// Mint'in Token-2022 meta verilerinden veya Metaplex'ten ad/sembol bilgilerini yükleyerek bir sarmalayıcı dağıtın
address wrapper = factory.add_spl_token_with_metadata(splMint);

// Ya da ad/sembol bilgisini elle belirtin
address wrapper = factory.add_spl_token_no_metadata(splMint, "USD Coin", "USDC");
```

Kayıt defterinin `live` girdilerinden alınan canlı fabrika adresi (v0.2.0): Hadrian `0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078`. Önceki fabrikalar hâlâ zincir üzerinde bulunur ancak `deprecated` veya `retired` olarak [kayıt defterinde](https://github.com/rome-protocol/rome-registry/tree/main/chains)işaretlenmiştir; bunları kullanmayın. Kayıt defteri tek doğruluk kaynağıdır; bu nedenle adresi kodunuza kopyalamak yerine buradan okuyun (bkz. [Sözleşme listesini okuma](https://docs.rome.builders/tr/referans/contract-addresses.md#reading-the-contracts-list)).

## Kanonik mint'ler

Zincir üzerinde bir token kayıt defteri sözleşmesi yoktur. Kanonik sarmalayıcılar ile gas/köprü tokenları, zincir dışındaki [`rome-protocol/registry`](https://github.com/rome-protocol/rome-registry)içinde düzenlenir; `add_spl_token_no_metadata` aracılığıyla oluşturulan izinsiz sarmalayıcılar, zincir üzerindeki `TokenCreated` olayından keşfedilir. Kayıt defteri, her zincirde her mint için kanonik sarmalayıcıyı belirtir. Cüzdan bakiyeleri sarmalayıcılar arasında ortaktır. Her sarmalayıcı, EVM sözleşmelerinin elinde bulunan bakiyeleri ayrı olarak izler.

## Solidity'den SPL işlemleri

Kullanıcı PDA'sı tarafından imzalanan SPL temel işlemleri için **HelperProgram** ön derlemesini (`0xFF…09`) kullanın — ATA oluşturma, SPL transferleri ve gas↔lamports dönüşümü:

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

IHelperProgram helper = IHelperProgram(0xFF00000000000000000000000000000000000009);

helper.create_ata(user, mint);              // kullanıcının mint için ATA'sını oluştur
helper.transfer_spl(to, tokens, mint);      // çağıranın PDA'sından SPL transfer et
```

`transfer_spl` birden fazla aşırı yüklemeye sahiptir (transferFrom `transferFrom` akışları için bir delege çeşidi dahil); bkz. `interface.sol` dosyasına bakın. Önbellekli yolda eşdeğer işlemler şu arayüzlerde bulunur: `ISplCached` (`0xFF…05`) ve `IAssociatedSplCached` (`0xFF…06`). Bir sözleşme, tutarlı biçimde tek bir yol kullanır.

## Her cüzdan için tek seferlik yetkilendirme

Sarmalayıcı, kullanıcının token hesapları üzerinde **SPL temsilcisi** olarak kullanıcının tokenlarını taşır. Bu nedenle bir cüzdanın, sarmalayıcı kendi adına herhangi bir token taşıyabilmeden önce, her sarmalayıcı için bir kez bu yetkiyi vermesi gerekir. Yetkilendirme, Helper ön derlemesine yapılan tek bir çağrıdır (`0xff00000000000000000000000000000000000009`):

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

`approve_spl` kullanıcının kendi hesabı tarafından imzalanır; dolayısıyla çağrıyı sarmalayıcı veya sözleşmeniz değil, kullanıcı gönderir. Mint, sarmalayıcıdaki `mint_id()` değeridir.

* **Kimlerin buna ihtiyacı var?** Her EVM cüzdanının ve her Solana kullanıcısının sentetik adresinin, tokenlarını taşımak istediği her sarmalayıcı için bu yetkilendirmeye ihtiyacı vardır. `transferFrom` ile token çeken bir sözleşme, yalnızca sarmalayıcıyı yetkilendirmiş kullanıcılar için çalışır.
* **Nasıl kontrol edilir?** Sarmalayıcı üzerinde `isEnabled(user)` çağrısını yapın. Yetkilendirme yapıldıktan sonra `true` döndürür.
* **Yetkilendirme eksik olduğunda ne olur?** Transfer, `0x4` SPL hatasıyla (sahip uyuşmazlığı) geri alınır.
* **Token hesabı başına bir temsilci.** Bir SPL token hesabının tek bir temsilcisi vardır. Aynı token hesabı üzerinde köprü veya yönlendirici gibi başka bir programa yetki verilmesi, sarmalayıcının yetkisinin yerini alır. Kullanıcı sarmalayıcıyı yeniden yetkilendirene kadar sarmalayıcı o kullanıcı için çalışmayı durdurur. Önceki bir yetkilendirmenin hâlâ geçerli olduğunu varsaymak yerine, transferden önce `isEnabled` ile kontrol edin.

Yeni bir fabrika sürümü bir sarmalayıcının yerini aldığında, her cüzdan yeni sarmalayıcıya `approve_spl`ile izin verir. Eski sarmalayıcı, o cüzdanın tokenlarını yalnızca token hesabının temsilcisi olarak kaldığı sürece taşıyabilir. Yeni sarmalayıcının yetkilendirilmesi, mevcut temsilcinin yerini alır.

Her iki yolun kodunun tamamı [çift yollu uygulama kılavuzunda](https://docs.rome.builders/tr/gelistirici-kilavuzlari/dual-lane-app.md#one-time-grant-the-wrapper) yer alır.

## Yatırma ve çekme

* **EVM'ye** — SPL tarafı, kullanıcının PDA'sına ait ATA'ya tutarı alacak kaydeder; ERC-20 sarmalayıcısı bakiyeyi hemen yansıtır. Diğer zincirlerden gelen transferler, köprü üzerinde kullanıcı tarafından imzalanmış bir yetkilendirme aracılığıyla zincir üzerinde sonuçlandırılır.
* **Gas'ı gas tokenına dönüştürme** — şu ön derlemeyi çağırın: `Withdraw` (`0x42…16`). `withdraw_to_ata(wei)` yerel gas'ı yakar ve eşdeğer tutarı, gas token'ının kendi ondalık basamak sayısına göre hesaplayarak çağıranın token hesabına aktarır; gas token'ının sarmalayıcısı (ör. wUSDC) bunu daha sonra bakiye olarak gösterir. `withdraw_to_pda(wei)` çağıranın PDA'sına lamport gönderir ve yalnızca gas'ın SOL olduğu zincirlerde geçerlidir; gas olarak USDC kullanan Hadrian ve Rubicon'da işlem geri alınır. Bu nedenle orada `withdraw_to_ata` kullanın. Tutar 18 ondalık basamaklı gas birimleri cinsindendir ve gas token'ı birimlerinin tam sayı katı olmalıdır: USDC gas'lı bir zincirde 10^12'nin katı (6 ondalık basamaklı bir birim), aksi takdirde çağrı geri alınır. `HelperProgram.deposit_from_ata(wei)` ters yönde çalışır ve çağıranın token hesabındaki gas token'ını yeniden yerel gas'a dönüştürür; aynı kat kuralı geçerlidir. Bunlar gas token'ı dönüştürme işlemleridir; diğer token'lar için çıkış yöntemi değildir.
* **Solana'ya, diğer token'lar** — sarmalayıcının kendi bakiyesi zaten SPL bakiyesidir; dolayısıyla bunu dışarı aktarmak bir SPL transferidir:
  * `HelperProgram.transfer_spl_to_signer(amount, mint)` çağıranın token'larını, işlemi imzalayan Solana cüzdanının token hesabına gönderir. Bu dönüş yolu, kullanıcının kendi cüzdanına yalnızca cüzdan imzalı Solana hattında ulaşır. MetaMask'ten veya aktarıcı üzerinden çağrılırsa imzalayan Rome'un vekil ödeyicisidir; bu nedenle çağrı başarısız olur ya da token'lar Rome'a gider. Bunun yerine `transfer_spl` veya `RomeBridgeWithdraw.bridgeOutToSolana` kullanın.
  * `RomeBridgeWithdraw.bridgeOutToSolana(solanaRecipient, amount, mint)` token'ları herhangi bir Solana cüzdanına gönderir. Kullanıcının köprü sözleşmesine yetki vermesi gerekir (`approve_spl(bridge, …)`, yukarıdaki tek temsilci notuna bakın); ayrıca alıcının token hesabı mevcut olmalıdır. `ensureRecipientAta(solanaRecipient, mint)` hesabı oluşturur.
  * `RomeBridgeWithdraw` ayrıca CCTP üzerinden USDC'yi başka bir zincire yakar (`burnUSDC`) ve diğer varlıkları Wormhole üzerinden gönderir (`burnETH`, `burnToWormhole`).

Güncel `RomeBridgeWithdraw` adresini kayıt defterinden alın.

Solana ile Ethereum veya AggLayer zincirleri arasında başka token'lar taşımak için bkz. [Solgate](https://docs.rome.builders/tr/rome-uzerindeki-uygulamalar/solgate.md) ve [13. Solgate üzerinde geliştirme](https://docs.rome.builders/tr/rome-akademi/13-build-on-solgate.md).

## Gas token'ı

Her zincirin kendine ait bir gas token'ı vardır: SOL veya bir SPL token'ı. Rome Proxy'nin fiyat kaynağı bir Hermes API akışı, Meteora DAMM v1 havuzu, Meteora DAMM v2 havuzu veya sabit bir fiyat olabilir. Hadrian (test ağı) ve Rubicon (ana ağ) USDC kullanır. Hadrian test USDC'si kullanır. Rubicon gerçek USDC kullanır. Tüm zincirler için geçerli tek bir varsayılan gas token'ı yoktur.

## Token-2022 mint'leri

Fabrika, Token-2022 mint'lerini de sarmalar. Mint'in türünü öğrenmek için Helper ön derlemesine `mint_info(mint)` (seçici `0xe24bf5d4`) sorar ve yanıta göre sarmalayıcıyı seçer. `mint_info` beş değer döndürür:

| Değer          | Anlamı                                                                            |
| -------------- | --------------------------------------------------------------------------------- |
| `tokenProgram` | mint'in sahibi olan token programı (klasik SPL Token programı veya Token-2022)    |
| `decimals`     | mint'in ondalık basamak sayısı                                                    |
| `hookProgram`  | transfer-hook programı; hook yoksa veya mevcut olup etkinleştirilmemişse sıfır    |
| `feeBps`       | baz puan cinsinden transfer ücreti; ücret yoksa veya sıfıra ayarlanmışsa sıfır    |
| `extensions`   | mint'in taşıdığı Token-2022 uzantılarının bit haritası; uzantı türü N için N. bit |

Bir mint'in aldığı:

| Mint                                                                                                       | Sarmalayıcı                                                                                | `wrapper_kind_by_mint` |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------- |
| Sıradan bir mint, hook içermeyen bir Token-2022 mint'i veya hook'u mevcut olup etkinleştirilmemiş bir mint | önbelleğe alınmış sarmalayıcı (`SPL_ERC20_cached`)                                         | `1`                    |
| Etkinleştirilmiş transfer hook'u olan bir Token-2022 mint'i                                                | hook'lu sarmalayıcı (`SPL_ERC20_Token2022Hooked`), factory'nin `hooked_wrapper_deployer()` | `2`                    |

Transfer ücreti olan bir mint, önbelleğe alınmış sarmalayıcıyı alır ve mint'in `Transfer` olayı, gönderilen miktarı değil, ücret kesildikten sonra ulaşan miktarı bildirir. Bir mint'in aldığı türü factory'den şu yöntemle okuyabilirsiniz: `wrapper_kind_by_mint(mint)`; canlı Hadrian factory'sinde USDC, ETH ve SOL sarmalayıcılarının tümü şu değeri döndürür: `1`.

Reddedilenler:

* Etkinleştirilmiş transfer hook'u olan bir mint, sıradan sarmalayıcılardan birini alamaz. Üzerinde doğrudan `SPL_ERC20` veya `SPL_ERC20_cached` dağıtmak, `ArmedTransferHookUnsupported(mint, hookProgram)`hatasıyla işlemin geri alınmasına neden olur. Factory üzerinden bu mint türü bunun yerine hook'lu sarmalayıcıya yönlendirilir.
* SPL mint'i olmayan bir adres, `mint_info` çağrısının şu hatayla geri alınmasına neden olur: `Invalid SPL mint account: <address>`.
* Zaten bir sarmalayıcısı olan bir mint, `Token exists`hatasıyla; zaten kullanımda olan bir sembol ise `Token with symbol exists`.
* `add_spl_token_with_metadata` önce adı ve sembolü mint'in kendi Token-2022 meta verilerinden, ardından Metaplex'ten okur. Mint'in ikisi de yoksa şu hatayla işlemi geri alır: `Mint asserts no name: use add_spl_token_no_metadata`.

Hook'lu sarmalayıcının çalışma şekli:

* Token-2022, her transferde hook'u çalıştırır ve hook, transfere bağlı hesaplara ihtiyaç duyar. Sarmalayıcı bu hesapları belirleyemez; bu nedenle çağıran, mint'in ek hesap meta verileri listesinden hesapların tamamını çözümler ve listeyi sarmalayıcıya iletir. Sarmalayıcı, listenin sabit bölümünü (hook programı ve doğrulama hesabı) denetler ve listeyi değiştirmeden iletir.
* Düz `transfer`, `transferFrom` ve `bridgeOutToSolana` şu hatayla geri döner: `HookAccountPlanRequired`. Şunları kullanın: `transferWithHookAccounts`, `transferFromWithHookAccounts` ve `bridgeOutToSolanaWithHookAccounts`; bu işlevler hesap listesini ek bir bağımsız değişken olarak alır.
* Wrapper dağıtıldıktan sonra mint'in hook programı değişirse transferler şu hatayla geri döner: `HookConfigurationChanged`.
* Tokenları doğrudan programlar arası çağrı (CPI) ile taşır; bu, eski yöntemdir ve önbelleğe alınmış yöntemi kullanmaz. Bir sözleşme tek bir yöntemi tutarlı biçimde kullanır. Eski yöntemdeki çağrılar yalnızca atomik yürütmede çalıştığından, hook'lu wrapper kullanan bir çağrının tek bir atomik işleme sığması gerekir.
* Sözleşme bakiyeleri için bir kayıt tutmaz. Sözleşmeye gönderilen tokenlar sözleşmenin kendi token hesabına ulaşır ve sözleşme bunları ancak şu işlemi yaptıktan sonra aktarabilir: `approve_spl` wrapper'ın kendisine yetki verme.
* Diğer wrapper'lar gibi aynı [tek seferlik yetki verme](#one-time-grant-per-wallet) işlemini gerektirir.

## Kısıtlamalar

* SPL token miktarları `uint64` (en fazla 18,446,744,073,709,551,615)
* ERC-20 harcama izinleri (`approve` / `allowance`) EVM depolamasında tutulur. Wrapper, tokenları kullanıcının SPL vekili olarak taşır; kullanıcı bu yetkiyi her wrapper için bir kez verir (bkz. [Cüzdan başına tek seferlik yetki verme](#one-time-grant-per-wallet))
* ERC-20 wrapper sembolleri her fabrika için benzersiz olmalıdır

## Sırada Ne Var?

* [Sözleşme Adresleri](https://docs.rome.builders/tr/referans/contract-addresses.md) — ön derlemeler ve zincir bazında adresler
* [EVM'den Solana'yı çağırma](https://docs.rome.builders/tr/gelistirici-kilavuzlari/call-solana-from-evm.md) — Solidity'den CPI ve SPL işlemleri
* [Solana ve EVM, Rome'da nasıl buluşuyor?](https://docs.rome.builders/tr/temel-kavramlar/how-solana-and-evm-meet.md)
* [Bir Solana programını entegre etme](https://docs.rome.builders/tr/gelistirici-kilavuzlari/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/tr/temel-kavramlar/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.
