法文与一致性套件
规则写成两部法文,每部配一个冻结的核。一份实现是否合规,运行一遍即可确认。
两部法
- zikaron/1
- 账本的法:条目的字节格式、签名、条目间的链接、审计报告、两种上链形式。文本见
base/zikaron-v1.md。 - zikaron.kit/1
- 客户端文书的法:指纹清单与回执、凭证载荷、记录包、读数、授权六项核验,建立在 zikaron/1 之上。文本见
base/zikaron-kit-v1.md。
法中每条规则都是对全部输入有定义的机器判断。条文分三类:凭单个条目即可判定的;凭一组条目加审计输入可判定的;须对照链上数据判定的。前两类可离线判定,冻结覆盖的正是这两类。
冻结核
每部法有一份纯 Python、仅依赖标准库的参照实现:zikaron/1 的核是 impl-py/ 下的五个文件,zikaron.kit/1 的核是 kit-py/ 下的四个文件。把这些文件各自的 SHA-256 连同文件名排成若干行,再取一次 SHA-256,即法文中写明的发布摘要。
摘要写入法文之后,核即为判据,法文是对它的阐述。两者所述相同;理解有分歧时,以核在该输入上的输出为准。
冻结的条件
冻结一个核,须先有一份仅凭法文独立写成的实现,与之在生成的语料上逐字节一致;再经过至少十万次模糊测试,零崩溃、零挂起、零误收,同一输入始终得到同一答案。可离线判定的两类条文中,每一条封闭边界在每个种子的语料里都须两侧各覆盖一次。条件全部达成后,摘要写入法文,冻结完成。
测试一份实现
你的实现须提供约定的命令行接口:zikaron/1 为 zk1,zikaron.kit/1 为 zkk。每个命令读取约定的输入(多为一个文件),向标准输出写一个规范 JSON 值。约定全文见 HARNESS.md 与 HARNESS-KIT.md。
语料生成器会改写目录中的文件,请先把 base/zikaron-conformance 复制到仓库之外,在副本中操作。
cp -R base/zikaron-conformance /tmp/conformance
cd /tmp/conformance
# 生成语料(种子任选,各种子的结果都应一致)
python3 corpus/gen.py --seed 1
# 在语料上逐份比对你的 zk1 与核
ZK1_CANDIDATE=/path/to/zk1 python3 compare.py
# kit 同理
python3 kit-corpus/gen.py --seed 1
ZKK_CANDIDATE=/path/to/zkk python3 compare-kit.py比对器列出每一处分歧。零分歧是合规的证据;合规的定义是在全部输入上一致,因此在语料之外发现分歧,请提交议题,那是语料应当补充之处。
链面参照
须对照链上数据判定的条文,参照是 base/zikaron-core/fixtures/ 中的录制:每份录下一段链上数据,并附标准扫描结果。扫描器回放每份录制,应逐字节复现标准结果。scan-py/ 是一份独立编写的 Python 扫描器,与全部录制一致。
修改法
已冻结的核保持原样。修改规则须另立 zikaron/2:新的规格名、新的签名域字面量、新的核与新的摘要。在 zikaron/1 下写成的账本永久有效。
法文的散文是核的教科书,可以修订得更清楚;核的摘要不变,就仍是 zikaron/1。
法之外
法明确留给读者、裁决者与条款的事项:钱款、授权的含义、证据的分量、记录是否必须上链。实现这些功能的代码属于工具层,见法 §11。