アーキテクチャ

Kora は 3 つのクレートで構成される Rust ワークスペースです。

• kora-lib はコアロジックと RPC サーバーを含みます。
• kora-cli はオペレーターが実行する kora バイナリをビルドします。
• kora-deploy は専用のプログラムデプロイツールで、バージョンは個別に管理されます。 特記がない限り、以下はすべて crates/lib/src 内にあります。

リクエストのライフサイクル

以下の図は、Kora におけるトランザクションの一般的なフローを示しています。 コールパスを理解することは、Kora ノードの設定や 新機能の追加において重要です。

各ステージの所在

他に知っておくべきファイルが 2 つあります。config.rs は kora.toml のスキーマ全体を定義し、 state.rs はデシリアライズされた設定をプロセスグローバルな状態として保持します。

RPC サーバーを読む

rpc.rs は薄いディスパッチ層で、JSON-RPC エンドポイントごとに 1 つのメソッドを持ち、 API 全体を把握する最も手早い方法です。各メソッドのロジックは rpc_server/method/ 配下の 専用ファイルにあります。sign_transaction.rs を最初から最後まで読んでください。他の署名 メソッドはそのバリエーションです。

バリデーターを読む

transaction_validator.rs と transaction/instruction_util.rs には、トランザクションと instructions を 検証するロジックが含まれています。さらに、fee-payer-policy の 安全性プロパティテストは、ゲート対象のプログラムごとに 1 ファイルずつ validator/transaction_validator/fee_payer_policy_props/ 配下にあります。

知っておきたい規約

デフォルトの検証。 [validation.fee_payer_policy] 配下のすべてのフラグは デフォルトで false であり、ポリシー構造体には #[serde(default)] が付いています。 この組み合わせは意図的なものです。新たにゲートされる instruction を追加しても、 既存のオペレーターの設定が壊れてはならず、意図しない許可ではなく 拒否として扱われる必要があります。フラグを追加する際は、この両方を維持してください。

検証するのは解決済みのトランザクションであり、生のトランザクションではありません。 生の VersionedTransaction は静的なアカウントキーしか公開しないため、そこから V0 トランザクションを検証・ 料金計算すると、ルックアップテーブルのアカウントが黙ってスキップされ、 課金が不足します。VersionedTransactionResolved::from_transaction はそれらの アドレスを事前に解決します。そのため、後続のすべてのステージが解決済みの型を受け取ります。

トランザクションプラグインの追加

プラグインは plugin/mod.rs の TransactionPlugin トレイトを実装します。このトレイトには 2 つの メソッドがあります。validate は署名フロー中にトランザクションごとに実行され、 validate_config は起動時に 1 回実行され、オペレーター向けにエラーと警告を返します。 PluginExecutionContext は、4 つの署名メソッドのうちどれがプラグインを呼び出したかを伝えます。

TransactionPluginRunner::from_config は、config.rs で定義された TransactionPluginType に対して マッチングを行います。新しい組み込みプラグインを追加するには、そこに新しいバリアントを加え、 ランナーに新しい match アームを追加します。現在同梱されている 2 つのプラグインは gas_swap と deploy_authority です。

テスト

Kora は設定をプロセスグローバルな状態として保持するため、tests/ ではフェーズごとに 1 つの [[test]] ターゲットを宣言しており、各ターゲットは独自の組み込み surfnet と Kora ノードを起動し、ゼロから初期化されます。バイナリごとに設定は 1 つです。新しいフェーズには、既存のモジュール内の新モジュールではなく、 新しいターゲットが必要です。

cargo test -p tests --test <target>

それ以外はすべて justfile を通じて連携されています。コマンドを手作業で 組み立て直すのではなく、そちらを参照してください。