架构

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 包含 验证交易和指令的逻辑。此外还有手续费支付方策略的安全属性测试, 每个受控程序对应一个文件,位于 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 进行匹配。新增内置插件,就是在那里新增一个变体, 并在 runner 中新增一个匹配分支。目前随附的两个插件是 gas_swap 和 deploy_authority。

测试

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

cargo test -p tests --test <target>

其他一切都通过 justfile 串联起来。请直接阅读它,而不是 手动重新拼凑命令。