如何把 Anoma 节点事件序列化为 JSON 并正确编码执行结果?
如何把 Anoma 节点事件序列化为 JSON 并正确编码执行结果?
对 anoma_node(Anoma 协议的参考实现,Elixir/OTP 项目)做二次开发时,一个常见任务是把它的事务子系统事件——ResultEvent、CompleteEvent、TxEvent 等——序列化为 JSON。普通字段用 Jason 即可处理,但执行结果是 Nock noun,不能直接编码:项目内置了统一的编码规则,即先用 Noun.Jam.jam/1 压缩成字节、再用 Base.encode64/1 转成字符串。本文按“事件结构 → 编码规则 → REPL 实操 → 断言验证 → 跑测试套件”的顺序,带你把这件事做完整。适用前提是 mix.exs 声明的 Elixir 环境(elixir: "~> 1.17"),并能在项目目录用 USAGE.md 给出的方式进入 REPL:
iex -S mix
先弄清事件结构:谁负责序列化
节点事件都包在一层统一结构里。Anoma.Node.Event 是一个 TypedStruct,带 @derive Jason.Encoder,只有两个字段:
:node_id— 发送事件的节点 ID,非 Anoma 事件时为nil;:body— 事件本体,也就是真正承载业务内容的内层 struct。
所以“把节点事件序列化为 JSON”实际分两层:外层 Anoma.Node.Event 自动按字段名编码,内层 struct 决定执行结果字段怎么写。内层事件分布在两个模块:
- Anoma.Node.Transaction.Backends.Events:
ResultEvent、CompleteEvent、SRMEvent、TRMEvent、ROEvent; - Anoma.Node.Transaction.Mempool.Events:
TxEvent、ConsensusEvent、BlockEvent,这三个直接@derive Jason.Encoder,按字段名原样输出(如order就是字符串列表)。
执行结果的编码规则
执行结果字段的类型定义在 Mempool 模块:
@type vm_result :: {:ok, Noun.t()} | :vm_error | :in_progress
@type tx_result :: {:ok, Noun.t()} | :error | :in_progress
JSON 编码实现集中在 Backends.Events 模块的 “Json Encoding” 小节,规则如下:
| 字段值 | JSON 输出 |
|---|---|
:error |
字符串 "error" |
:vm_error(仅 ResultEvent 的 vm_result) |
字符串 "vm_error" |
{:ok, %Anoma.RM.Transparent.Transaction{} = tx} |
直接透传该 struct |
{:ok, noun} |
`noun |
其他几处相关实现:
- Mempool.Tx 的 Jason.Encoder 采用同样的
encode_maybe_noun逻辑处理tx_result/vm_result/code:原子(如默认的:in_progress)原样输出为字符串,noun 走 jam + Base64;注意它编码出的 JSON 中backend恒为nil。 - MapSet 的 Jason.Encoder 把
MapSet编码为列表,所以SRMEvent/TRMEvent的commitments/nullifiers会输出成数组。 - ROEvent 的 Jason.Encoder 与
Mempool.Tx相同,但结果字段名是read_result,且文档明确它“不应由事务子系统注册”。
在 REPL 中手动序列化事件
进入 iex -S mix 后,可直接构造内层事件并用 Jason.encode!/1 序列化。以下代码块中的值全部取自 lib/examples/serializing/events/backends.ex 的示例(这些函数本身公开,也可直接调用,如 Anoma.Node.Examples.Serializing.Events.Backends.result_event())。
ResultEvent(后端 → Mempool 的执行结果事件):
alias Anoma.Node.Transaction.Backends.Events
result_event = %Events.ResultEvent{
tx_id: "foo",
vm_result: {:ok, [1 | 2]}
}
Jason.encode!(result_event)
解码后结构应为 %{tx_id: "foo", vm_result: <base64 字符串>},其中 base64 字符串等于 [1 | 2] |> Noun.Jam.jam() |> Base.encode64()。失败分支则直接把原子换成 :vm_error,输出为 "vm_error"。
CompleteEvent(后端 → Executor 的执行完成事件):
complete_event = %Events.CompleteEvent{
tx_id: "foo",
tx_result: {:ok, [1 | 2]}
}
Jason.encode!(complete_event)
规则与 ResultEvent 一致,只是字段名为 tx_result。tx_result: :error 时输出 "error"。
SRMEvent / TRMEvent(资源机事件,携带 commitments 与 nullifiers):
srm = %Events.SRMEvent{
commitments: MapSet.new(["foo"]),
nullifiers: MapSet.new(["bar"])
}
Jason.encode!(srm)
解码后应为 %{commitments: ["foo"], nullifiers: ["bar"]};空 %Events.SRMEvent{} 则为 %{nullifiers: [], commitments: []}。
Mempool 事件(取自 lib/examples/serializing/events/mempool.ex):
alias Anoma.Node.Transaction.Mempool.Events
Jason.encode!(%Events.TxEvent{}) # 解码后为 %{id: nil, tx: nil}
Jason.encode!(%Events.ConsensusEvent{}) # 解码后为 %{order: []}
block = %Events.BlockEvent{}
Jason.encode!(%{block | round: 123, order: ["foo", "bar"]})
# 解码后为 %{order: ["foo", "bar"], round: 123}
如果想带一个真实交易,示例里用 Anoma.Node.Examples.ETransaction.simple_transaction() 生成交易后填入 TxEvent:
transaction = Anoma.Node.Examples.ETransaction.simple_transaction()
tx_event = %{
%Mempool.Events.TxEvent{}
| id: transaction.id,
tx: %Mempool.Tx{
tx_result: transaction.result,
vm_result: transaction.result,
backend: transaction.backend
}
}
Jason.encode!(tx_event)
其中 Mempool.Tx 的 vm_result/tx_result/code 都会按上面的规则编码。一个可核对的示例(来自 lib/examples/serializing/structs/mempool.ex,注意这是文档示例值,不是固定预期):vm_result = {:ok, [[["key"] | 0] | 0]} 时,JSON 中对应字段为 "FfDWyvIq"。
用断言验证编码结果
示例模块的验证方式是“编码后解码,再与预期 map 编码后解码做比较”。以 ResultEvent 为例,这套断言可直接放进你的 REPL 或自定义测试:
json = Jason.encode!(result_event)
expected_result =
{:ok, [1 | 2]} |> elem(1) |> Noun.Jam.jam() |> Base.encode64()
Jason.decode(json) ==
%{tx_id: "foo", vm_result: expected_result}
|> Jason.encode!()
|> Jason.decode()
断言为 true 说明 noun 已按项目规则编码;Jason.encode! 本身不抛异常也说明字段没有落入无法编码的形态。Mempool.Tx 的示例(structs/mempool.ex)用的是直接比较字符串:
tx = %Mempool.Tx{}
vm_result = {:ok, [[["key"] | 0] | 0]}
tx = tx |> Map.put(:vm_result, vm_result)
Jason.encode(tx) ==
Jason.encode(%{
code: nil,
vm_result: "FfDWyvIq", # 文档示例值
tx_result: :in_progress,
backend: nil
})
跑项目自带的序列化测试套件
序列化相关的可执行验证入口是 test/serialize_test.exs。它用 TestHelper.GenerateExampleTests 宏分别对四个示例模块生成测试:
use TestHelper.GenerateExampleTests,
for: Anoma.Node.Examples.Serializing.Structs.Mempool
use TestHelper.GenerateExampleTests,
for: Anoma.Node.Examples.Serializing.Events.Mempool
use TestHelper.GenerateExampleTests,
for: Anoma.Node.Examples.Serializing.Events.Backends
use TestHelper.GenerateExampleTests,
for: Anoma.Node.Examples.Serializing.Events.Ordering
在仓库根目录运行:
mix test test/serialize_test.exs
测试全部通过,即表示这些事件的 JSON 编码行为与示例断言一致。示例模块的 moduledoc 自述“I am merely a test suite, rather than examples”,也就是说这些 lib/examples/serializing 下的函数同时承担“可运行的序列化参考”和“回归测试”两个角色:改动任何 Jason.Encoder 实现后,跑一遍该文件即可发现回归。
边界与限制
- lib/examples/serializing/events/ordering.ex 目前是空模块:Ordering 事件在仓库中没有可参照的序列化示例,本文不覆盖它的编码细节。
Mempool.Tx编码出的 JSON 中backend恒为nil(编码器里写死),不是从 struct 透传的字段值。ROEvent的结果字段是read_result,不能与ResultEvent的vm_result混用;且文档注明它不应注册进事务子系统。- 示例代码中的
"foo"、["foo", "bar"]、round: 123、"FfDWyvIq"等均为文档示例值,用于说明结构与编码形式,不是节点运行时必然出现的固定输出。
完成一次 mix test test/serialize_test.exs 通过、并在 REPL 中对至少一个 {:ok, noun} 结果复现 jam + Base64 断言后,这条序列化路径就可以直接用于你的事件消费端。