21 NAND 文档 EN

TapeBoot 规范

TapeBoot 规定设备怎么从 tape 容器取回固件:链上路径、频道指针、manifest 字段、签名和校验顺序。草案 v0.3。

链上路径

全部放在设备持有人的 tape 容器里,是 SiteRegistry 的普通文件。

路径内容
tapeboot/<board>/channel/<channel>.json频道指针
tapeboot/<board>/<seq>/manifest.jsonmanifest,签过名
tapeboot/<board>/<seq>/<file>文件;超过 8,400,000 字节的拆成 <file>.p0、<file>.p1 …
tapeboot/<board>/rollback/<seq>.json回滚指令,可选,签过名
名字规则
<board>[a-z0-9][a-z0-9-]{0,31},如 mm-gw2a18
<seq>十进制正整数,无前导零
<channel>[a-z][a-z0-9-]{0,15}
所有路径≤ 200 字符,不以 / 开头,不含 \ ? # :,没有空段、.、..

单个链上文件最多 350 块 × 24,000 字节 = 8,400,000 字节。更大的文件拆成分段,除最后一段外每段长度是 24,000 的倍数。

频道指针

{"tapeboot":1,"board":"mm-gw2a18","channel":"stable","seq":7,"manifest":"tapeboot/mm-gw2a18/7/manifest.json","manifest_sha256":"0x…"}
字段说明
tapeboot1
board板子名
channel频道名,如 stable、beta
seq指向的版本
manifestmanifest 路径
manifest_sha256manifest 文件的 sha256,0x + 64 位小写十六进制

manifest

tapeboot 成员

字段类型规则
v整数必须是 1
board字符串等于设备固化的 board
seq整数≥ 1,单调递增,等于路径里的 <seq>
version字符串semver,只给人看;新旧只看 seq
created字符串RFC 3339 UTC,如 2026-10-22T08:00:00Z;只给人看
prev字符串上一版 manifest 的 sha256;seq = 1 时为 64 个 0
min_loader字符串引导固件最低 semver,低于它就拒绝
owner对象{chain_id, registry, container, holder}
files数组1–16 项
sig字符串签名,见下

owner 里的地址是 0x + 40 位十六进制,比较时不分大小写。设备拿它和固化的信任根逐项比,任何一项不同整份拒绝。

files[] 每一项

字段类型规则
name字符串[A-Za-z0-9._-]{1,64},同一份 manifest 里不重复
role字符串bitstream / runtime / os / model / config
size整数文件总字节数,≥ 1
sha256字符串整个文件(各段按顺序拼起来)的 sha256
chunk整数必须是 24000
chunk_sha256数组块数 ≤ 256 时用:第 i 项是第 i 块的 sha256,共 ceil(size/24000) 项
chunk_list对象块数 > 256 时用;和 chunk_sha256 恰好给一个
parts数组按顺序的链上分段 {path, size, sha256},size 之和等于文件 size
load字符串fpga、sd,或 ddr:0x 加 8 位十六进制(如 ddr:0x81000000)
compress字符串v1 只有 none,别的值整份拒绝

chunk_list(大文件)

"chunk_list": {"path":"tapeboot/<board>/<seq>/<name>.chunks","size":<32 × 块数>,"sha256":"0x…","chunk_sha256":["0x…", …]}
字段说明
path列表文件路径,也要列进 tapeout.files
size32 × ceil(文件 size / 24000),≤ 8,400,000
sha256整个列表文件的 sha256
chunk_sha256列表文件本身每 24,000 字节一块的哈希;一块装 750 个块哈希

签名

规范化(把对象写成字节串 C)的规则:

步骤:

  1. 删掉 tapeboot.sig,按上面的规则规范化,得到 C。
  2. 摘要 D = sha256(C),32 字节。
  3. sig 是持有人对 D 做 EIP-191 personal_sign:消息是 "\x19Ethereum Signed Message:\n32" 接 D,再 keccak256。
  4. sig 写成 0x + 130 位十六进制:r、s、v 依次拼接,v 是 27 或 28。
  5. 验证:从 sig 恢复出地址,等于固化的 holder(不分大小写)。s 必须在曲线阶的下半部分,否则拒绝。

链上存的已经是规范化形式,所以板端不用建解析树:把原文里 ,"sig":"0x…" 这一段去掉再算 sha256,结果和上面相同。

校验顺序

设备全部做完才算这份 manifest 可用:

步核什么
1频道指针的 manifest_sha256 = 取到的 manifest 的 sha256
2能解析;v = 1;board、seq 和路径一致;compress 都是 none;min_loader ≤ 本机版本
3owner 四项 = 固化的信任根
4签名恢复出的地址 = 固化的 holder
5seq ≥ min_seq(microSD 上记的最近一次成功启动的 seq)
6本地有上一版 manifest 时,prev = 它的 sha256;没有(新装、跳版本)时只做 1–5
7每一块按 chunk_sha256 核,每个分段、每个文件按 sha256 核

两种读法

读法谁用规则
完整方式主机、网页、打包工具钉在已终局块,验 eth_chainId,至少 2 个独立运营方完全一致,只发只读方法;另外用链上登记的 fileInfo.sha256Hash 和 parts[].sha256 对账
设备方式板子可以只连一个节点、不钉块、不投票。签名加逐块哈希使节点只能造成失败或受控降级。应配 2 个以上节点

取字节:先 fileInfo(container, path) 拿大小,再 readRange(container, path, offset, len)。offset 和 len 是 24,000 的倍数(最后一块除外)。兜底走 https://<tape 名>.tapekit.org/<path> 网关,只能用在设备方式下。

槽和回滚

项规则
块缓存microSD 上 cache/<chunk_sha256 去掉 0x>;同一块跨文件、跨版本复用
槽slot/a/、slot/b/,各存一份完整的 manifest 和文件
状态state.json:{active, pending, min_seq}
提交新版装进不在用的槽、标 pending、试运行;60 秒内有心跳就 active = 新槽,min_seq = 新 seq
回滚没心跳就回旧槽,新 seq 记为坏版本,不再自动尝试
主动回滚频道指针可以指更旧的 seq,但不能低于 min_seq
回滚指令退到 min_seq 以下要持有人另签 rollback/<seq>.json,见下
{"tapeboot":1,"board":"…","kind":"rollback","to_seq":5,"new_min_seq":5,"nonce":<seq 的下一个值>,"sig":"0x…"}

签法同 manifest。验签通过、nonce 大于见过的最大 seq,就把 min_seq 降到 new_min_seq。v1 的板端客户端可以不实现这一条。

客户端 API

函数做什么
tb_init(cfg)固化信任根、节点列表、网关、缓存目录
tb_resolve(channel)读频道 → 取 manifest → 校验第 1–6 步
tb_plan(manifest)对照缓存列出缺的块
tb_fetch(manifest, file, sink, progress_cb)按块取回、核哈希、写缓存;整个文件通过后才按顺序交给写入目标
tb_stage(manifest)全部文件取完后写进待装槽、标 pending
tb_commit(manifest)启动成功后提交
tb_rollback()回到旧槽
tb_status(){seq, slot, pending, min_seq, last_error}

错误种类:transport、not-found、bad-manifest、wrong-owner、bad-sig、old-seq、bad-prev、loader-too-old、chunk-mismatch、file-mismatch、no-space。

已知限制

  1. 设备方式下,一个节点能把设备指向更旧、签过名、且不低于 min_seq 的版本。
  2. 持有人私钥丢了或容器转手,设备不再认新版本,要重新烧引导固件。
  3. 单份 manifest 的块哈希最多管约 48 MB。
  4. created、version 只给人看,不参与新旧判断。
  5. v1 不压缩。
怎么一步步用,见从链上取固件。