Architektur

Kora ist ein Rust-Workspace mit drei Crates:

• kora-lib enthält die Kernlogik und den RPC-Server,
• kora-cli baut das kora-Binary, das Operatoren ausführen, und
• kora-deploy ist ein spezialisiertes Tool für das Deployment von Programmen und wird separat versioniert. Alles Folgende befindet sich in crates/lib/src, sofern nicht anders angegeben.

Der Lebenszyklus einer Anfrage

Das folgende Diagramm zeigt den allgemeinen Ablauf einer Transaktion durch Kora. Das Verständnis des Aufrufpfads ist wichtig, um einen Kora-Node zu konfigurieren und neue Funktionen hinzuzufügen.

Wo sich die einzelnen Stufen befinden

Zwei weitere Dateien, die du kennen solltest: config.rs definiert das gesamte kora.toml-Schema, und state.rs hält die deserialisierte Konfiguration im prozessglobalen Zustand.

Den RPC-Server lesen

rpc.rs ist eine dünne Dispatch-Schicht mit einer Methode pro JSON-RPC-Endpunkt und der schnellste Weg, die gesamte API zu überblicken. Die Logik jeder Methode liegt in einer eigenen Datei unter rpc_server/method/. Lies sign_transaction.rs von Anfang bis Ende; die anderen Signiermethoden sind Variationen davon.

Den Validator lesen

transaction_validator.rs und transaction/instruction_util.rs enthalten die Logik zur Validierung von Transaktionen und Anweisungen. Hinzu kommen die Safety-Property-Tests der Fee-Payer-Policy, die pro gesperrtem Programm in jeweils einer Datei unter validator/transaction_validator/fee_payer_policy_props/ liegen.

Wissenswerte Konventionen

Standardmäßige Validierung. Jedes Flag unter [validation.fee_payer_policy] ist standardmäßig false, und die Policy-Structs tragen #[serde(default)]. Diese Kombination ist beabsichtigt: Das Hinzufügen einer neu gesperrten Anweisung darf die Konfiguration eines bestehenden Operators nicht brechen, und sie muss als Ablehnung statt als versehentliche Erlaubnis wirken. Behalte beides bei, wenn du ein Flag hinzufügst.

Validiere die aufgelöste Transaktion, niemals die rohe. Die rohe VersionedTransaction stellt nur die Schlüssel der statischen Konten bereit. Daher werden beim Validieren oder Bepreisen einer V0-Transaktion auf dieser Basis Konten aus Lookup-Tables stillschweigend übersprungen und zu wenig berechnet. VersionedTransactionResolved::from_transaction löst diese Adressen im Voraus auf, weshalb jede nachgelagerte Stufe den aufgelösten Typ erwartet.

Ein Transaktions-Plugin hinzufügen

Plugins implementieren den Trait TransactionPlugin in plugin/mod.rs. Er hat zwei Methoden: validate läuft pro Transaktion während der Signierabläufe, und validate_config läuft einmal beim Start und gibt Fehler und Warnungen für den Operator zurück. Ein PluginExecutionContext teilt dem Plugin mit, welche der vier Signiermethoden es aufgerufen hat.

TransactionPluginRunner::from_config matcht auf TransactionPluginType, das in config.rs definiert ist. Ein neues integriertes Plugin besteht aus einer neuen Variante dort plus einem neuen Match-Arm im Runner. Die beiden Plugins, die derzeit mitgeliefert werden, sind gas_swap und deploy_authority.

Testen

Kora hält die Konfiguration im prozessglobalen Zustand, daher deklariert tests/ pro Phase ein [[test]]-Target, und jedes Target startet sein eigenes eingebettetes Surfnet plus Kora-Node, von Grund auf neu befüllt. Eine Konfiguration pro Binary: Eine neue Phase braucht ein neues Target, kein neues Modul in einem bestehenden.

cargo test -p tests --test <target>

Alles Weitere ist über das justfile verdrahtet. Lies dieses, statt Befehle von Hand zusammenzubauen.