Architectuur

Kora is een Rust-workspace met drie crates:

• kora-lib bevat de kernlogica en de RPC-server,
• kora-cli bouwt de kora-binary die operators uitvoeren, en
• kora-deploy is een gespecialiseerde tool voor het uitrollen van programma's, met een eigen versiebeheer. Alles hieronder staat in crates/lib/src, tenzij anders vermeld.

De levenscyclus van een verzoek

Het onderstaande diagram toont de algemene route van een transactie door Kora. Het begrijpen van het aanroeppad is belangrijk voor het configureren van een Kora-node en het toevoegen van nieuwe functionaliteit.

Waar elke fase zich bevindt

Nog twee bestanden om te kennen: config.rs definieert het volledige kora.toml-schema, en state.rs bewaart de gedeserialiseerde configuratie in een procesbrede globale state.

De RPC-server lezen

rpc.rs is een dunne dispatch-laag met één methode per JSON-RPC-endpoint en is de snelste manier om de hele API te overzien. De logica van elke methode staat in een eigen bestand onder rpc_server/method/. Lees sign_transaction.rs van begin tot eind; de andere ondertekeningsmethoden zijn variaties daarop.

De transactievalidatie lezen

transaction_validator.rs en transaction/instruction_util.rs bevatten de logica voor het valideren van transacties en instructies. Daarnaast zijn er de tests voor de veiligheidseigenschappen van het fee-payer-beleid, die per afgeschermd programma in één bestand staan onder validator/transaction_validator/fee_payer_policy_props/.

Handige conventies om te kennen

Standaardvalidatie. Elke vlag onder [validation.fee_payer_policy] staat standaard op false, en de beleidsstructs dragen #[serde(default)]. Die combinatie is bewust gekozen: het toevoegen van een nieuw afgeschermde instructie mag de bestaande configuratie van een operator niet breken, en het moet resulteren in een weigering in plaats van een onbedoelde toestemming. Behoud beide wanneer je een vlag toevoegt.

Valideer de opgeloste transactie, nooit de ruwe. De ruwe VersionedTransaction bevat alleen statische accountsleutels, dus als je een V0-transactie daarmee valideert of prijst, worden lookup-table-accounts stilzwijgend overgeslagen en wordt er te weinig in rekening gebracht. VersionedTransactionResolved::from_transaction lost die adressen vooraf op, en daarom nemen alle volgende fases het opgeloste type als invoer.

Een transactieplug-in toevoegen

Plug-ins implementeren de TransactionPlugin-trait in plugin/mod.rs. Die heeft twee methoden: validate draait per transactie tijdens de ondertekeningsflows, en validate_config draait eenmalig bij het opstarten en geeft fouten en waarschuwingen terug aan de operator. Een PluginExecutionContext vertelt de plug-in door welke van de vier ondertekeningsmethoden hij is aangeroepen.

TransactionPluginRunner::from_config matcht op TransactionPluginType, gedefinieerd in config.rs. Een nieuwe ingebouwde plug-in is een nieuwe variant daar plus een nieuwe match-arm in de runner. De twee plug-ins die nu worden meegeleverd, zijn gas_swap en deploy_authority.

Testen

Kora bewaart de configuratie in een procesbrede globale state, dus tests/ declareert één [[test]]-target per fase, en elke target start zijn eigen ingebedde surfnet plus Kora-node op, vanaf nul opgezet. Eén configuratie per binary: een nieuwe fase vraagt om een nieuwe target, niet om een nieuwe module in een bestaande.

cargo test -p tests --test <target>

Al het andere is aangesloten via de justfile. Lees die in plaats van commando's handmatig te reconstrueren.