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 Betreiber ausführen, und
• kora-deploy ist ein spezialisiertes Tool für das Deployment von Programmen, das separat versioniert wird. 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 man kennen sollte: 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 schlanke Dispatch-Schicht mit einer Methode pro JSON-RPC-Endpunkt und der schnellste Weg, die gesamte API zu überblicken. Die Logik jeder Methode steht in einer eigenen Datei unter rpc_server/method/. Lesen Sie sign_transaction.rs von Anfang bis Ende; die übrigen Signiermethoden sind Variationen davon.

Die Validatoren lesen

transaction_validator.rs und transaction/instruction_util.rs enthalten die Logik für die Validierung von Transaktionen und Anweisungen. Hinzu kommen die Property-Tests zu den Sicherheitseigenschaften der Fee-Payer-Policy, die in je einer Datei pro geschütztem Programm unter validator/transaction_validator/fee_payer_policy_props/ liegen.

Wissenswerte Konventionen

Standardvalidierung. Jedes Flag unter [validation.fee_payer_policy] hat standardmäßig den Wert false, und die Policy-Structs tragen #[serde(default)]. Diese Kombination ist beabsichtigt: Das Hinzufügen einer neu geschützten Anweisung darf die Konfiguration eines bestehenden Betreibers nicht brechen, und sie muss als Ablehnung statt als versehentliche Erlaubnis wirken. Behalten Sie beides bei, wenn Sie ein Flag hinzufügen.

Validieren Sie die aufgelöste Transaktion, niemals die rohe. Die rohe VersionedTransaction stellt nur statische Konten-Schlüssel bereit. Wird eine V0-Transaktion daraus validiert oder bepreist, werden Lookup-Table-Konten stillschweigend übersprungen und es wird zu wenig berechnet. VersionedTransactionResolved::from_transaction löst diese Adressen vorab 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 Signatur-Abläufe, und validate_config läuft einmal beim Start und gibt Fehler und Warnungen für den Betreiber zurück. Ein PluginExecutionContext teilt dem Plugin mit, welche der vier Signiermethoden es aufgerufen hat.

TransactionPluginRunner::from_config verzweigt per Match auf TransactionPluginType, das in config.rs definiert ist. Ein neues integriertes Plugin besteht aus einer neuen Variante dort plus einem neuen Match-Zweig 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 sowie seinen eigenen Kora-Node, jeweils von Grund auf initialisiert. 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 eingebunden. Lesen Sie dieses, anstatt Befehle von Hand zu rekonstruieren.