架构

Kora 是一个包含三个 crate 的 Rust 工作区:

• kora-lib 包含核心逻辑和 RPC 服务器,
• kora-cli 用于构建运维人员运行的 kora 二进制文件,以及
• kora-deploy 是一个专用的程序部署工具,独立进行版本管理。 除非另有说明,以下内容均位于 crates/lib/src 中。

请求生命周期

下图展示了交易在 Kora 中流转的总体流程。 了解调用路径对于配置 Kora 节点和添加 新功能至关重要。

各阶段所在位置

还有两个需要了解的文件:config.rs 定义了完整的 kora.toml 模式, state.rs 则将反序列化后的配置保存在进程全局状态中。

阅读 RPC 服务器

rpc.rs 是一个轻量的分发层,每个 JSON-RPC 端点对应一个方法, 也是了解整套 API 的最快途径。每个方法的逻辑都位于 rpc_server/method/ 下各自的文件中。请从头到尾通读 sign_transaction.rs;其他签名 方法都是它的变体。

阅读验证器

transaction_validator.rs 和 transaction/instruction_util.rs 包含 验证交易和指令的逻辑。此外还有 fee-payer-policy 安全属性测试,每个受控程序对应一个文件,位于 validator/transaction_validator/fee_payer_policy_props/ 下。

值得了解的约定

默认验证。 [validation.fee_payer_policy] 下的每个标志 默认均为 false,且策略结构体带有 #[serde(default)]。这种 搭配是有意为之:新增受控指令不得破坏 现有运维人员的配置,并且它必须表现为拒绝,而不是 意外放行。添加标志时请同时保留这两点。

验证解析后的交易,而不是原始交易。 原始的 VersionedTransaction 仅暴露静态账户密钥,因此据此验证或 计价 V0 交易时,会悄悄跳过查找表账户, 导致少收费用。VersionedTransactionResolved::from_transaction 会提前解析这些 地址,这就是为什么所有下游阶段都使用解析后的类型。

添加交易插件

插件需要实现 plugin/mod.rs 中的 TransactionPlugin trait。它有两个 方法:validate 在签名流程中针对每笔交易运行, validate_config 在启动时运行一次,并向 运维人员返回错误和警告。PluginExecutionContext 会告知插件是四种签名 方法中的哪一种调用了它。

TransactionPluginRunner::from_config 会对 config.rs 中定义的 TransactionPluginType 进行匹配。新增内置插件需要在其中添加一个新变体, 并在运行器中添加一个新的匹配分支。目前随附的两个插件是 gas_swap 和 deploy_authority。

测试

Kora 将配置保存在进程全局状态中,因此 tests/ 为每个阶段声明一个 [[test]] 目标,每个目标都会启动各自内嵌的 surfnet 以及 Kora 节点,并从零开始初始化。每个二进制文件对应一份配置:新增阶段需要新增 目标,而不是在现有目标中新增模块。

cargo test -p tests --test <target>

其他所有内容都通过 justfile 串联起来。请直接阅读该文件,而不是 手动重建命令。