如何把 Anoma 节点事件序列化为 JSON 并正确编码执行结果?

原创2026-09-11 20:08:511,950 阅读
文章标签:区块链后端隐私计算

如何把 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 决定执行结果字段怎么写。内层事件分布在两个模块:

执行结果的编码规则

执行结果字段的类型定义在 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 断言后,这条序列化路径就可以直接用于你的事件消费端。

登录后查看全文
anoma-archive