Arsitektur

Kora adalah workspace Rust dengan tiga crate:

kora-lib berisi logika inti dan server RPC,
kora-cli membangun biner kora yang dijalankan operator, dan
kora-deploy adalah alat deployment program khusus yang versinya dikelola secara terpisah. Semua yang dibahas di bawah ini berada di crates/lib/src kecuali dinyatakan lain.

Siklus hidup permintaan

Diagram di bawah ini menunjukkan alur umum sebuah transaksi melalui Kora. Memahami jalur pemanggilan sangat penting untuk mengonfigurasi node Kora dan menambahkan fitur baru.

Lokasi setiap tahap

Tahap dalam diagram	Sumber	Titik masuk
Gateway	`rpc_server/server.rs`	`run_rpc_server`
Dispatch	`rpc_server/rpc.rs`	`KoraRpc`
Logika per metode	`rpc_server/method/`	satu file per metode JSON-RPC
Validasi	`validator/transaction_validator.rs`	`TransactionValidator`
Plugin	`plugin/mod.rs`	`TransactionPluginRunner`
Penandatanganan	`signer/`	didukung oleh crate `solana-keychain`

Dua file lain yang perlu diketahui: config.rs mendefinisikan seluruh skema kora.toml, dan state.rs menyimpan konfigurasi yang sudah dideserialisasi dalam state global proses.

rpc.rs adalah lapisan dispatch tipis, satu metode untuk setiap endpoint JSON-RPC, dan cara tercepat untuk melihat seluruh API. Logika setiap metode berada di file tersendiri di bawah rpc_server/method/. Bacalah sign_transaction.rs dari awal sampai akhir; metode penandatanganan lainnya merupakan variasi darinya.

Membaca validator

transaction_validator.rs dan transaction/instruction_util.rs berisi logika untuk validasi transaksi dan instruksi. Selain itu, ada pengujian properti keamanan fee-payer-policy, yang disimpan satu file per program yang dibatasi di validator/transaction_validator/fee_payer_policy_props/.

Konvensi yang perlu diketahui

Validasi default. Setiap flag di bawah [validation.fee_payer_policy] secara default bernilai false, dan struct kebijakan membawa #[serde(default)]. Pasangan ini disengaja: menambahkan instruksi baru yang dibatasi tidak boleh merusak konfigurasi operator yang sudah ada, dan hasilnya harus berupa penolakan, bukan izin yang tidak disengaja. Pertahankan keduanya saat Anda menambahkan flag.

Validasi transaksi yang sudah di-resolve, jangan pernah yang mentah. VersionedTransaction mentah hanya mengekspos kunci akun statis, sehingga memvalidasi atau menghitung biaya transaksi V0 darinya akan melewatkan akun lookup-table secara diam-diam dan membebankan biaya terlalu rendah. VersionedTransactionResolved::from_transaction me-resolve alamat-alamat tersebut sejak awal, itulah sebabnya setiap tahap berikutnya menerima tipe yang sudah di-resolve.

Menambahkan plugin transaksi

Plugin mengimplementasikan trait TransactionPlugin di plugin/mod.rs. Trait ini memiliki dua metode: validate berjalan untuk setiap transaksi selama alur penandatanganan, dan validate_config berjalan sekali saat startup dan mengembalikan error serta peringatan untuk operator. PluginExecutionContext memberi tahu plugin metode penandatanganan mana dari keempat metode yang memanggilnya.

TransactionPluginRunner::from_config melakukan pencocokan pada TransactionPluginType, yang didefinisikan di config.rs. Plugin bawaan baru berarti varian baru di sana ditambah cabang match baru di runner. Dua plugin yang tersedia saat ini adalah gas_swap dan deploy_authority.

Pengujian

Kora menyimpan konfigurasi dalam state global proses, jadi tests/ mendeklarasikan satu target [[test]] per fase, dan setiap target menjalankan surfnet tertanam miliknya sendiri beserta node Kora, yang diinisialisasi dari awal. Satu konfigurasi per biner: fase baru membutuhkan target baru, bukan modul baru di dalam target yang sudah ada.

cargo test -p tests --test <target>

Semua hal lainnya terhubung melalui justfile. Bacalah file itu daripada menyusun perintah secara manual.