アーキテクチャ

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アームを追加します。現在提供されているプラグインはgas_swapとdeploy_authorityの2つです。

テスト

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

cargo test -p tests --test <target>

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