驗證帳本
自行實現驗證器
規範寫到讓第三方能實現獨立驗證器——一致性向量、本格式專為抓住的實現錯誤,以及重新實現真正會栽的地方。
運營方的驗證器驗運營方的簽名,證明不了任何可實現性。要那個證明,就自己實現一個——這是被鼓勵的,規範正為此而寫:精確到無需閱讀運營方代碼即可實現,且實現者有辦法確認自己寫對了。
一個有用的參照:一個簽名驗證器用約一百行 Python 就寫得下。 linkex.ai 實例的一次內部審計正是用這種規模的獨立重新實現完成的——並藉此暴露了兩處只有真去獨立實現才會現形的文檔缺口,隨後修進了規範。那正是這條反饋迴路按設計運轉的樣子。
一致性向量
每條「看起來對的實現也會栽」的規則都有向量:確切的輸入字節、確切的期望輸出字節與其 SHA-256。實現合規,當且僅當:
- 每個 accept 向量產出與聲明完全一致的規範化字節與哈希;
- 每個 reject 向量被拒絕而非修復——這正是基於
JSON.parse的驗證器過不了的一條,因為主流解析器會靜默修復本格式恰恰要拒絕的那些輸入; - 每份公布的分段載荷哈希到其信封內的承諾,且信封自身的摘要相符。
套件包含一段帶密鑰輪換歷史的連鎖回執,以及它蘊含的密鑰解析結果——並且刻意公布了一個固定私鑰種子:沒有它,實現者只能驗證參考簽名,無法檢驗自己簽出的字節是否一致——而簽名恰是域標籤錯誤會靜默藏身的那一半(標籤寫錯仍能得到一個看起來合法的簽名,只在別人的驗證器上才失敗)。
參考實現本身也在每個 accept 向量上與第二個獨立實現交叉核對。
重新實現真正會栽的地方
以下是被點名的陷阱——每一處都是「兩個看起來都對的實現」產生分歧的地方:
規範化
- 對象鍵按 UTF-16 碼元排序,不是碼點、也不是 UTF-8 字節。emoji(代理對)排在許多更低碼點之前;Go 的原生字串比較與 Rust 的
Ord都是碼點序,在這裡都是錯的。 - 字串轉義遵循 ECMAScript
JSON.stringify:七個短轉義,其他 C0 控制字符用小寫\u00xx——且不轉義<、>、&、U+2028/U+2029。Go 的encoding/json默認做 HTML 轉義且必然轉義 U+2028/U+2029;復用標準編碼器的 Go 實現在此失敗——參考實現為此自寫了字串輸出器。 - 四條規則必須在原始輸入字節上、在任何解析器運行之前檢查:重複鍵、未配對代理項轉義、畸形 UTF-8、尾部多餘數據。解析器把四者全部靜默解決,校驗解析後取值等於放行了本格式專門要拒絕的一切。
哈希與簽名
- 哈希域與簽名域是兩回事。 承諾用自己的域標籤做哈希,卻沿用回執的簽名標籤——被簽的永遠是一個哈希域已使其無歧義的 32 字節哈希。
hash與signature字段不屬於被哈希的字節。 它們隨對象傳輸——與回執的self_hash不在自己信封之內同理。- 拒絕非規範 base64。 多數解碼器忽略末位字符的無用比特,於是一個 64 字節簽名有 16 種解碼結果相同且全部驗簽通過的寫法(32 字節公鑰有 4 種)。把解出的字節重新編碼、與輸入比對——那就是全部檢查。一旦簽名字串本身被哈希(Merkle 葉子的回執行裡正是如此),這就不再是潔癖:十六種寫法就是一張回執的十六個不同葉子。
Merkle
- 奇數節點晉升、絕不複製。向量把三葉樹的正確根與 CVE-2012-2459 形狀的錯誤根都公布了,因為錯誤的根單看完全合理。
- 節點哈希不可交換;證明記錄兄弟節點的方位。
抽樣
抽籤的四處細節,散文描述無法反推、全部具規範性:
seq編碼為八字節大端——不是十進制文本,也不是 JSON;- HMAC 密鑰是種子的裸 32 字節(去掉
sha256:前綴後十六進制解碼)——用顯示字串作密鑰是另一個函數,會產出另一份自洽的樣本,這是最糟的分歧,因為雙方都以為自己對; - 只比較 HMAC 的前 8 字節,按大端讀作無符號整數;
- 閾值以 IEEE-754 binary64 計算、乘數與截斷方式均有明文規定——不是因為浮點優雅,而是因為「兩個都正確的實現可以給出不同答案」的規則不成其為規則,所以必須點名一種算術。
你需要什麼
| 輸入 | 在哪裡 |
|---|---|
| 回執規範 | 交付對手方;將發布於 opentallyprotocol |
一致性向量(canonical_vectors.json) | 隨規範交付 |
| 錨定規範 | 實時提供:/api/anchor/spec——對確切字節取哈希即可復現上鏈的 spec_hash |
| 用於實測的真實數據 | 公開帳本端點,無需帳號 |
從對照向量做規範化開始,然後對實時密鑰歷史與一份真實證據包做簽名驗證。當你的實現在每個向量上復現參考哈希、又驗過真實生產回執時,你擁有的就比對任何人二進制的信任更好:一份用你自己讀過的代碼寫成的、對帳本的獨立檢查。