For the complete documentation index, see llms.txt. This page is also available as Markdown.

Token Uyumluluğu

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

Rome, bir ERC-20 tokenini ve onun temel SPL tokenını tek bir paylaşılan 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üzdan için, Rome üzerindeki bir ERC-20 tokenı bir şeffaf sarmalayıcıdır Solana’daki bir SPL token hesabının üstünde bulunur. Cüzdanın ERC-20 bakiyesi onun SPL bakiyesidir. EVM adresi için programdan türetilmiş bir adres token hesabına sahiptir. Bu, onun harici yetki PDA’sıdır.

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.
  • Eşitleme gecikmesi yok: cüzdanın ERC-20 bakiyesi onun SPL bakiyesidir.

  • MetaMask cüzdanları ve sentetik adresler dahil sıradan cüzdanlarda likidite parçalanması yoktur. Bir mint üzerindeki her sarmalayıcı aynı cüzdan bakiyesini gösterir. balanceOf yöntemi bu bakiyeyi cüzdanın token hesabından okur. EVM sözleşmelerinin içinde tutulan tokenlar sarmalayıcı başına tutulur (bkz. Sarmalayıcı sözleşmesi).

  • Bir cüzdanın tokenları için bir tarafta kilitli, diğer tarafta basılmış hiçbir şey yoktur. Sözleşme tarafından tutulan tokenlar Solana’daki sarmalayıcının kendi emanet token hesabında durur. Her sarmalayıcı bu tokenları ayrı ayrı izler.

İkinci bir sarmalayıcının bakiyeyi neden bölmediği

Aynı mint üzerindeki iki sarmalayıcı aynı cüzdan bakiyesini gösterir. Sarmalayıcılar totalSupply değerini Solana mintinden okur. Hadrian’da (testnet) üç wUSDC sarmalayıcısı eşleşen cüzdan bakiyeleri döndürdü. Üç wUSDC sarmalayıcısının tamamı (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ı adlandırır.

USDC tutan bir Solana cüzdanı ve bir EVM adresi, aynı mintin tokenlarını tutar. Solana havuzları her ikisi için de aynı kasaları ve rezervleri kullanır.

İçindeki sahipler tablosu Via gezgini 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ği için token hesabı bakiyesinden farklı olabilir.

Aşağıdaki içe aktarma yolları @rome-protocol/rome-soliditykullanır. Paket npm’de değildir; onu herkese açık rome-solidity repo’sundan npm install github:rome-protocol/rome-solidity, ile kurun ya da forge install rome-protocol/rome-solidity bir yeniden eşleme ile; sarmalayıcı ve fabrika sözleşmelerinin de Foundry altında OpenZeppelin’e ihtiyacı vardır (bkz. Solidity Sözleşmeleri Dağıtma). Ön-derleme arayüzleri contracts/interface.sol.

Sarmalayıcı sözleşmesi

SPL_ERC20 adresinde bulunur SPL_ERC20_cached(ve onun önbelleğe alınmış izleme varyantı Token-2022 mintleri) tam bir ERC-20 arayüzü sağlar, bir SPL minti üzerinde:

  • balanceOf() — kullanıcının ATA bakiyesini Solana’dan okur (bir sözleşme adresi için sarmalayıcının kendi defterini okur, aşağıya bakın)

  • transfer() / transferFrom() — tokenları Solana’da taşır

  • approve() / allowance() — EVM depolamasında tutulan, her harcayıcı için ayrı ERC-20 izinleri (bir SPL token hesabının EVM tarzı izinleri yoktur). Bunlar aşağıdaki tek seferlik izinle ayrıdır: bir kullanıcının tokenlarını hiç hareket ettirmek için sarmalayıcı o kullanıcının SPL delegesi gibi davranır ve kullanıcı bu hakkı her cüzdan için bir kez verir

  • totalSupply() — SPL mint arzını okur

Bir sözleşme tek seferlik izni gönderemez, bu yüzden bir sözleşmenin 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 minti için bir sarmalayıcı dağıtır:

Kayıt defterindeki canlı kayıtlarından canlı fabrika adresi (v0.2.0): Hadrian 0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078. Daha önceki fabrikalar hâlâ zincir üzerindedir ancak kullanımdan kaldırılmış veya emekliye ayrılmış şu kısmında: kaydındaolarak işaretlenmiştir; onları kullanmayın. Kayıt defteri doğruluk kaynağıdır, bu yüzden canlı adresi ondan okuyun (bkz. Sözleşmeler listesini okuma) ve onu kodunuza kopyalamayın.

Kanonik mintler

Zincir üzerinde bir token-kayıt sözleşmesi yoktur. Kanonik sarmalayıcılar ve gaz/köprü tokenları çevrimdışı rome-protocol/registry; izin gerektirmeyen, yoluyla oluşturulan sarmalayıcılar add_spl_token_no_metadata zincir üzerindeki TokenCreated olayından keşfedilir. Kayıt defteri, her zincirde her mint için kanonik sarmalayıcıyı adlandırır. Cüzdan bakiyeleri sarmalayıcılar arasında paylaşılır. Her sarmalayıcı, EVM sözleşmelerinin tuttuğu bakiyeleri ayrı ayrı izler.

Solidity’den SPL işlemleri

Kullanıcı-PDA imzalı SPL ilkel işlevleri için HelperProgram ön-derlemeyi0xFF…09) kullanın — ATA oluşturma, SPL transferleri ve gas↔lamports dönüşümü:

transfer_spl birden çok aşırı yüklemeye sahiptir ( transferFrom akışları için interface.sol dahil); tam imzalar için bkz. Önbelleğe alınmış izde eşdeğer işlemler ISplCached (0xFF…05ve IAssociatedSplCached (0xFF…06). Bir sözleşme tek bir izi tutarlı şekilde kullanır.

Cüzdan başına tek seferlik izin

Sarmalayıcı, bir kullanıcının tokenlarını onun SPL delegesi olarak taşır; yani bir cüzdan, sarmalayıcı kendisi adına bir şey taşımadan önce bu hakkı her sarmalayıcı için bir kez vermelidir. İzin, Helper ön-derlemesine tek bir çağrıdır (0xff00000000000000000000000000000000000009):

approve_spl kullanıcının kendi hesabı tarafından imzalanır, bu yüzden bunu kullanıcı gönderir; sarmalayıcı veya sözleşmeniz değil. Mint mint_id() sarmalayıcı üzerindedir.

  • Kimlerin buna ihtiyacı var. Tokenlarını taşımak istediği her sarmalayıcı için, her EVM cüzdanı ve her Solana kullanıcısının sentetik adresi. Tokenları transferFrom ile çeken bir sözleşme yalnızca sarmalayıcıya izin vermiş kullanıcılar için çalışır.

  • Nasıl kontrol edilir. Çağırın isEnabled(user) sarmalayıcı üzerinde. Döndürür true izin yerindeyse.

  • Eksik olduğunda nasıl görünür. Aktarım SPL hatasıyla geri alınır 0x4 (sahip uyuşmazlığı).

  • Her token hesabı için bir delege. Bir SPL token hesabının tek bir delegesi vardır. Aynı token hesabı üzerinde bir başka programa, örneğin bir köprüye veya bir yönlendiriciye, izin vermek sarmalayıcının izninin yerine geçer ve kullanıcı yeniden izin verene kadar sarmalayıcı o kullanıcı için çalışmayı durdurur. Bir aktarımından önce isEnabled kontrol edin, önceki bir izin hâlâ duruyor varsaymak yerine.

Yeni bir fabrika sürümü bir sarmalayıcının yerini aldığında, her cüzdan yeni sarmalayıcıya approve_splile izin verir. Eski sarmalayıcı, token hesabının delegesi olarak kaldığı sürece o cüzdanın tokenlarını taşıyabilir. Yeni sarmalayıcıya izin vermek o delegeliği değiştirir.

Şu çift şeritli uygulama kılavuzu iki şerit için de tam kodu içerir.

Yatırma ve çekme

  • EVM'ye — SPL tarafı kullanıcının PDA’sına ait ATA’sına kredi verir; ERC-20 sarmalayıcısı bakiyeyi anında yansıtır. Diğer zincirlerden gelen giriş transferleri, köprü üzerindeki kullanıcı tarafından imzalanmış bir yetkilendirme yoluyla zincir üzerinde sonuçlanır.

  • Gazı gaz tokenına sarmalayın — Çekme ön-derlemeyi0x42…16). withdraw_to_ata(wei) yerel gazı yakar ve eşdeğer miktarı, gaz tokenının kendi ondalık basamaklarıyla, çağıranın token hesabına kredi olarak yazar; bunu gaz tokenının sarmalayıcısı (örneğin wUSDC) sonra bir bakiye olarak gösterir. withdraw_to_pda(wei) çağıranın PDA’sına lamports öder ve yalnızca gazı SOL olan bir zincir için geçerlidir; Hadrian ve Rubicon’da geri alınır, çünkü onlar gaz olarak USDC kullanır, bu yüzden orada withdraw_to_ata kullanın. Miktar 18 ondalıklı gaz birimlerindedir ve tam sayı olmalıdır: USDC-gazlı bir zincirde 10^12’nin katı (6 ondalıklı birimden biri), aksi hâlde çağrı geri alınır. HelperProgram.deposit_from_ata(wei) tersini yapar ve çağıranın token hesabındaki gaz tokenını aynı kat-kuralıyla tekrar yerel gaza dönüştürür. Bunlar gaz tokenı dönüşümleridir, diğer tokenlar için bir çıkış değildir.

  • Solana’ya çıkışta, herhangi bir diğer token — sarmalayıcının kendi bakiyesi zaten SPL bakiyesidir, bu yüzden onu dışarı taşımak bir SPL transferidir:

    • HelperProgram.transfer_spl_to_signer(amount, mint) çağıranın tokenlarını, işlemi imzalayan Solana cüzdanının token hesabına gönderir. Bu geri dönüş ayağı kullanıcının kendi cüzdanına yalnızca cüzdan-imzalı Solana şeridinde ulaşır. MetaMask’ten veya relayer üzerinden çağrıldığında imzalayan Rome’un proxy ödeyicisidir, bu yüzden çağrı başarısız olur ya da tokenlar Rome’a gider. Bunun yerine transfer_spl veya RomeBridgeWithdraw.bridgeOutToSolana kullanın.

    • RomeBridgeWithdraw.bridgeOutToSolana(solanaRecipient, amount, mint) onları herhangi bir Solana cüzdanına gönderir. Köprü sözleşmesi için kullanıcının iznine ihtiyaç duyar (approve_spl(bridge, …), yukarıdaki tek-delege notuna bakın) ve alıcının token hesabı mevcut olmalıdır; ensureRecipientAta(solanaRecipient, mint) onu oluşturur.

    • RomeBridgeWithdraw ayrıca USDC’yi CCTP üzerinden başka bir zincire yakar (burnUSDC) ve diğer varlıkları Wormhole üzerinden gönderir (burnETH, burnToWormhole).

Canlı RomeBridgeWithdraw adresini kayıt defterinden alın.

Gaz tokeni

Her zincirin kendi gaz tokenı vardır: SOL veya bir SPL tokenı. Rome Proxy’nin fiyat kaynağı bir Hermes API beslemesi, bir Meteora DAMM v1 havuzu, bir Meteora DAMM v2 havuzu veya sabit bir fiyat olabilir. Hadrian (testnet) ve Rubicon (mainnet) USDC kullanır. Hadrian test USDC kullanır. Rubicon gerçek USDC kullanır. Evrensel bir varsayılan gaz tokenı yoktur.

Token-2022 mintleri

Fabrika ayrıca Token-2022 mintlerini de sarar. Helper ön-derlemesine mintin ne olduğunu mint_info(mint) (seçici 0xe24bf5d4), ile sorar ve yanıta göre sarmalayıcıyı seçer. mint_info beş değer döndürür:

Değer
Anlamı

tokenProgram

mintin sahibi olan token programı (klasik SPL Token programı veya Token-2022)

ondalıklar

mintin ondalık basamakları

hookProgram

aktarim-kancası programı veya kanca yoksa ya da kanca mevcut ama etkin değilse sıfır

feeBps

varsa transfer ücreti, baz puan cinsinden; yoksa veya sıfır olarak ayarlanmışsa sıfır

extensions

mintin taşıdığı Token-2022 uzantılarının bir bit haritası, uzantı türü N için N. bit

Bir mint ne alır:

Mint

Sarmalayıcı

wrapper_kind_by_mint

Sıradan bir mint, kancası olmayan bir Token-2022 minti veya kancası mevcut ama etkin olmayan bir mint

önbelleğe alınmış sarmalayıcı (SPL_ERC20_cached)

1

Etkin bir aktarım kancasına sahip Token-2022 minti

kancalı sarmalayıcı (SPL_ERC20_Token2022Hooked), fabrikanın hooked_wrapper_deployer()

2

ile dağıttığı. Transfer ücreti olan bir mint önbelleğe alınmış sarmalayıcıyı alır ve onun Transfer olayı, gönderilen miktarı değil, ücret sonrası ulaşan miktarı bildirir. Bir mintin fabrikadan hangi türü aldığını wrapper_kind_by_mint(mint)ile okuyabilirsiniz; canlı Hadrian fabrikasında USDC, ETH ve SOL sarmalayıcılarının hepsi 1.

Neler reddedilir:

  • Etkin bir aktarım kancasına sahip bir mint sıradan sarmalayıcılardan birini alamaz. Onu doğrudan dağıtmak SPL_ERC20 veya SPL_ERC20_cached geri alınır ArmedTransferHookUnsupported(mint, hookProgram). Fabrika üzerinden bu durum bunun yerine kancalı sarmalayıcıya gider.

  • SPL minti olmayan bir adres mint_info geri alınmasına yol açar Geçersiz SPL mint hesabı: <address>.

  • Zaten bir sarmalayıcısı olan bir mint Token exists, ve zaten kullanımda olan bir sembol Token with symbol exists.

  • add_spl_token_with_metadata adı ve sembolü önce mintin kendi Token-2022 meta verilerinden, sonra Metaplex’ten okur. Mint bunların hiçbirine sahip değilse şu hatayla geri alınır Mint adı beyan etmiyor: add_spl_token_no_metadata kullanın.

Kancalı sarmalayıcının davranışı:

  • Token-2022 her transferde kancayı çalıştırır ve kanca transfere bağlı hesaplara ihtiyaç duyar. Sarmalayıcı bunu kendi başına çıkaramaz, bu yüzden çağıran mintin extra-account-metas listesinden tam hesap listesini çözer ve onu iletir. Sarmalayıcı o listenin sabit kısmını (kanca programı ve doğrulama hesabı) denetler ve onu değiştirmeden iletir.

  • Düz transfer, transferFrom ve bridgeOutToSolana geri alınmasına yol açar HookAccountPlanRequired. Kullanın transferWithHookAccounts, transferFromWithHookAccounts ve bridgeOutToSolanaWithHookAccounts, bunlar hesap listesini ek bir bağımsız değişken olarak alır.

  • Mintin kanca programı sarmalayıcı dağıtıldıktan sonra değişirse, transferler HookConfigurationChanged.

  • tokenları doğrudan çapraz-program çağrısıyla, eski izden hareket ettirir ve önbelleğe alınmış izi kullanmaz. Bir sözleşme tek bir izi tutarlı şekilde kullanır ve eski izdeki çağrılar yalnızca atomik yürütmede çalışır; dolayısıyla kancalı sarmalayıcıyı kullanan bir çağrı tek bir atomik işlem içine sığmak zorundadır.

  • Sözleşme bakiyeleri için hiçbir defter tutmaz. Bir sözleşmeye gönderilen tokenlar sözleşmenin kendi token hesabına iner ve sözleşme onları yalnızca approve_spl sarmalayıcının kendisine izni verdikten sonra geri gönderebilir.

  • Aynı tek seferlik izin gereklidir, diğer tüm sarmalayıcılarda olduğu gibi.

Kısıtlar

  • SPL token miktarları uint64 (en fazla 18.446.744.073.709.551.615)

  • ERC-20 izinleri (approve / allowance) EVM depolamasıdır. Sarmalayıcı, tokenları kullanıcının SPL delegesi olarak taşır; bunu kullanıcı her sarmalayıcı için bir kez verir (bkz. Cüzdan başına tek seferlik izin)

  • ERC-20 sarmalayıcı sembolleri fabrika başına benzersiz olmalıdır

Sırada Ne Var

Son güncelleme

Bu yararlı oldu mu?