Ekosistem & repo

Setiap repo publik Rome, apa isinya, dan bagaimana semuanya tersusun — peta untuk menavigasi permukaan.

Permukaan publik Rome adalah seperangkat repositori: beberapa fondasi paket yang Anda bangun di atasnya, scaffolder, aplikasi referensi untuk dipelajari, dan dua layanan yang dipanggil aplikasi Anda. Halaman ini adalah peta — apa itu setiap repo dan bagaimana mereka saling terhubung.

Dua tetangga menjawab pertanyaan yang berbeda, dan halaman ini menautkan keduanya alih-alih mengulanginya:

• Arsitektur menjelaskan protokol — bagaimana EVM berjalan di dalam program Solana.

• Setiap repo menyertakan sebuah AGENTS.md (mis. rome-sdk-ts/AGENTS.md) yang mengarahkan berdasarkan dari apa Anda memulai (kontrak Solidity, program Solana, greenfield, from-home) ke satu contoh yang paling dekat dengan kasus Anda.

Halaman ini adalah tingkat di antaranya: seluruh permukaan dan bagaimana bagian-bagiannya terhubung.

Permukaan sekilas

Fondasi — bangun di atas ini

Repo	Apa itu	Gunakan saat
rome-registry	@rome-protocol/registry — proyeksi fakta rantai langsung yang hanya-baca, dihasilkan (id, RPC, alamat, mint token, id program, feed oracle, ALT).	Anda membutuhkan fakta rantai yang nyata — jangan pernah hardcode.
rome-sdk-ts	@rome-protocol/sdk — jalur penulisan TypeScript: submitRomeTx + pengukuran biaya, kedua jalur, encoder PDA/ATA + CPI, binding precompile, sebuah /bridge klien.	Anda menulis kode aplikasi atau frontend.
rome-solidity	Antarmuka precompile Solidity, pembungkus SPL/ERC-20, dan adapter oracle — perangkat di sisi kontrak.	Anda menulis kontrak.

Aplikasi referensi — belajar lewat contoh

Repo	Apa itu	Gunakan saat
rome-dex	AMM dua jalur — pool Solana native dengan router EVM tipis.	Membuka jalur lainnya; sebuah native-core contoh.
aerarium	Peminjaman dua jalur — inti Comet Solidity yang dijangkau pengguna Solana melalui pengirim sintetis.	Membuka jalur lainnya; sebuah Inti Solidity contoh.
cardo	Pengguna EVM yang menjalankan dApp Solana (swap/stake/lend/perps) melalui CPI.	Sebuah aplikasi CPI-ke-Solana yang sudah dikerjakan untuk dipelajari.
appia	DeFi lintas-VM yang berpusat pada posisi; pengguna menjangkaunya dari chain asal mereka.	Sebuah from-home aplikasi.
rome-aave-v3-demo	Supply/borrow/repay Aave v3, dideploy tanpa perubahan.	Aplikasi EVM penuh yang berjalan apa adanya.

Fork kontrak — protokol yang dikenal, dideploy di Rome

Repo	Apa itu	Gunakan saat
compound-on-rome-comet	Pasar uang Compound III (Comet).	Mem-fork protokol EVM yang dikenal.
rome-aave-v3	Fork kontrak Aave v3.	Mem-fork protokol EVM yang dikenal.

Layanan — aplikasi Anda memanggil ini

Repo	Apa itu	Gunakan saat
rome-bridge-api	Orkestrator off-chain + sponsor biaya untuk bridge on-chain. Tidak menyimpan kunci.	Mengisi dana dompet, atau alur from-home.
rome-oracle-gateway	Feed harga Solana (Pyth, Switchboard) diekspos ke EVM melalui Chainlink AggregatorV3Interface.	Anda membutuhkan feed harga.

Scaffold — mulai di sini

Repo	Apa itu	Gunakan saat
create-rome-app	npx github:rome-protocol/create-rome-app — membuat scaffold aplikasi dua jalur yang sudah terhubung ke registry + SDK, dengan pemeriksaan kedua jalur yang didanai.	Memulai aplikasi baru.

Cara mereka tersusun

Tulang punggungnya adalah tiga fondasi dan satu scaffolder:

• rome-registry adalah satu-satunya sumber fakta langsung. rome-sdk-ts adalah jalur penulisan — dan /bridge subjalurnya adalah klien yang digunakan aplikasi Anda untuk berbicara dengan rome-bridge-api. rome-solidity adalah apa yang diimpor oleh kontrak Anda (dan fork); adapter oracle yang rome-oracle-gateway deploy juga berada di sana. Ketiganya independen satu sama lain — pilih yang dibutuhkan aplikasi Anda.

• create-rome-app menghubungkan dua yang pertama untuk aplikasi baru, sehingga proyek baru langsung mulai membaca registry dan menulis melalui SDK.

Aplikasi referensi adalah pengecualian yang patut diketahui: mereka lebih dulu ada daripada paket-paket yang diekstrak. cardo menggunakan paket registry; appia memproyeksikan registry ke JSON statis saat build time; dan keduanya mem-vendor jalur penulisan mereka alih-alih mengimpor SDK. Baca untuk mempelajari polanya — tetapi sebuah baru aplikasi harus mulai dari create-rome-app + paket-paketnya, bukan dengan mengkloning aplikasi.

Navigasikan berdasarkan apa yang Anda butuhkan

• Fakta rantai langsung (id, alamat, mint, id program) → rome-registry. Jangan pernah hardcode.

• Menulis kode aplikasi (sebuah penulisan, panggilan CPI, bridge) → rome-sdk-ts; referensi di Rome SDK.

• Menulis kontrak → rome-solidity; lihat Deploy Kontrak Solidity.

• Memanggil program Solana dari kontrak Solidity → precompile CPI di rome-solidity (interface.sol); cardo adalah contoh yang sudah dikerjakan.

• Contoh yang bekerja dari aplikasi AMM, lending, CPI, atau from-home → aplikasi referensi di atas; milik setiap repo AGENTS.md mengarah berdasarkan titik awal.

• Membuat scaffold aplikasi baru → create-rome-app.

• Feed harga → rome-oracle-gateway (lihat portal Oracle Gateway).

• Pengguna di chain lain → Dari home + rome-bridge-api.

• Memutuskan sisi mana yang menyimpan logika Anda → Pilih inti Anda.

Lapisan fondasi, secara dekat

rome-registry — fakta langsung, publik secara desain

Registry adalah dihasilkan dari sumber internal Rome: allowlist hanya menghasilkan apa yang memang dimaksudkan untuk publik, mengganti endpoint internal dengan padanan publiknya, dan menolak secara default semuanya yang lain — jadi aman untuk publik secara desain. Ini menerbitkan, per chain, chain.json / tokens.json / contracts.json / oracle.json / bridge.json / alts.jsonplus Solana program dan deployment aplikasi per-protokol.

Anda membacanya melalui getter — getChain, getTokens, getContracts, getOracle, getBridge, getAlts, dan getPrograms(network) (id program dikunci berdasarkan network, bukan chain id). Paket ini ESM biasa (belum ada tipe TypeScript bawaan saat ini).

Dua hal yang perlu diketahui sebelum Anda menggunakannya:

• getTokens() tidak mengembalikan assetRef. Untuk menemukan pembungkus token, cocokkan berdasarkan mint (mintId) — misalnya, pembungkus token gas adalah entri yang berbagi mint-nya.

• Ini membaca JSON dari disk (node:fs) — ini tidak aman untuk browser. Dalam web app, proyeksikan nilai yang Anda butuhkan ke file JSON statis saat build time dan impor itu di client. (Itu persis yang create-rome-app dan appia lakukan.)

Fakta yang tidak dibaca langsung oleh aplikasi Anda juga muncul di Alamat Kontrak referensi.

rome-sdk-ts — jalur penulisan, kedua jalur

@rome-protocol/sdk (v0.2.1) membungkus semua yang dibutuhkan penulisan Rome agar Anda tidak perlu membuat calldata atau biaya secara manual:

• submitRomeTx — jalur penulisan jalur EVM: menentukan ukuran gas berdasarkan eth_estimateGas (dipadding, dengan batas maksimum cadangan saat estimasi revert) dan menyediakan biaya EIP-1559.

• submitRomeTxSolanaLane — hal yang sama, untuk sebuah Phantom/Solana dompet Phantom/Solana yang menjalankan aplikasi EVM Anda. Pengirim sintetis tidak menyimpan apa pun saat diam; buildFundLeg/buildSweepLeg memindahkan nilai masuk dan keluar sebagai ERC-20 (wUSDC), bukan native msg.value , dan sintetis baru disediakan otomatis (create_pda) saat pertama kali digunakan.

• derivasi PDA/ATA, CPI invoke/invoke_signed encoder, binding precompile, dan sebuah /bridge subjalur (@rome-protocol/sdk/bridge) — klien bridge quote-first.

API lengkap + contoh: Rome SDK, dan panduan Memanggil Solana dari EVM, Memanggil EVM dari Solana, dan Membangun aplikasi dua jalur.

rome-solidity — perangkat di sisi kontrak

Apa yang diimpor oleh kontrak Anda:

• contracts/interface.sol — antarmuka precompile yang terikat ke alamatnya: CPI ICrossProgramInvocation (0xFF…08), Helper IHelperProgram (0xFF…09, pembuatan ATA/PDA, transfer SPL, gas↔lamports), Withdraw IWithdraw (0x42…16), dan System (0xFF…07). Sebuah gas-optimised cached keluarga yang dioptimalkan untuk gas juga ada di sini; sebuah kontrak menggunakan satu jalur secara konsisten. Tabel alamat lengkap: Alamat Kontrak.

• Pembungkus SPL/ERC-20 — SPL_ERC20 (berbasis CPI) dan SPL_ERC20_cached (jalur cached, digunakan di devnet); setiap mint SPL sudah menjadi ERC-20 melalui ini.

• Adapter oracle (contracts/oracle/) — adapter Pyth/Switchboard rome-oracle-gateway yang dideploy, dibaca melalui IAggregatorV3Interface.

• Contoh yang dikerjakan di contracts/examples/.

Bagian Solidity SDK dari Rome SDK menunjukkan pola impor dan binding precompile dalam kode.

Langkah selanjutnya

• Pilih inti Anda — sisi mana yang menyimpan logika Anda.

• Quickstart — deploy kontrak pertama Anda.

• create-rome-app — buat scaffold aplikasi dua jalur.

• Masing-masing repo AGENTS.md — rute berdasarkan titik awal ke contoh terdekat.