Architecture

Kora est un workspace Rust composé de trois crates :

• kora-lib contient la logique centrale et le serveur RPC,
• kora-cli construit le binaire kora que les opérateurs exécutent, et
• kora-deploy est un outil spécialisé de déploiement de programmes, versionné séparément. Tout ce qui suit se trouve dans crates/lib/src, sauf indication contraire.

Le cycle de vie d'une requête

Le schéma ci-dessous présente le flux général d'une transaction au sein de Kora. Comprendre le chemin d'appel est essentiel pour configurer un nœud Kora et ajouter de nouvelles fonctionnalités.

Où se trouve chaque étape

Deux autres fichiers à connaître : config.rs définit l'intégralité du schéma de kora.toml, et state.rs conserve la configuration désérialisée dans un état global au processus.

Lire le serveur RPC

rpc.rs est une fine couche de répartition, avec une méthode par endpoint JSON-RPC, et le moyen le plus rapide de voir l'ensemble de l'API. La logique de chaque méthode se trouve dans son propre fichier sous rpc_server/method/. Lisez sign_transaction.rs de bout en bout ; les autres méthodes de signature en sont des variantes.

Lire le validateur

transaction_validator.rs et transaction/instruction_util.rs contiennent la logique de validation des transactions et des instructions. S'y ajoutent les tests de propriétés de sécurité de la politique du fee payer, qui se trouvent dans un fichier par programme contrôlé sous validator/transaction_validator/fee_payer_policy_props/.

Conventions à connaître

Validation par défaut. Chaque indicateur sous [validation.fee_payer_policy] est à false par défaut, et les structs de politique portent #[serde(default)]. Cet appariement est délibéré : l'ajout d'une instruction nouvellement contrôlée ne doit pas casser la configuration d'un opérateur existant, et doit se traduire par un refus plutôt que par une autorisation accidentelle. Conservez les deux lorsque vous ajoutez un indicateur.

Validez la transaction résolue, jamais la transaction brute. La VersionedTransaction brute n'expose que les clés de compte statiques ; valider ou tarifer une transaction V0 à partir d'elle ignore donc silencieusement les comptes des tables de consultation et facture trop peu. VersionedTransactionResolved::from_transaction résout ces adresses en amont, c'est pourquoi chaque étape en aval prend le type résolu.

Ajouter un plugin de transaction

Les plugins implémentent le trait TransactionPlugin dans plugin/mod.rs. Il comporte deux méthodes : validate s'exécute pour chaque transaction pendant les flux de signature, et validate_config s'exécute une fois au démarrage et renvoie des erreurs et des avertissements à l'intention de l'opérateur. Un PluginExecutionContext indique au plugin laquelle des quatre méthodes de signature l'a invoqué.

TransactionPluginRunner::from_config effectue un match sur TransactionPluginType, défini dans config.rs. Un nouveau plugin intégré correspond à une nouvelle variante à cet endroit, plus une nouvelle branche de match dans le runner. Les deux plugins fournis aujourd'hui sont gas_swap et deploy_authority.

Tests

Kora conserve la configuration dans un état global au processus, donc tests/ déclare une cible [[test]] par phase, et chaque cible démarre son propre surfnet embarqué ainsi qu'un nœud Kora, initialisés de zéro. Une configuration par binaire : une nouvelle phase nécessite une nouvelle cible, et non un nouveau module dans une cible existante.

cargo test -p tests --test <target>

Tout le reste est câblé via le justfile. Lisez-le plutôt que de reconstituer les commandes à la main.