21 NAND Docs 中文

TapeBoot spec

TapeBoot defines how a device fetches firmware from a tape container: on-chain paths, channel pointers, manifest fields, signatures and the check order. Draft v0.3.

On-chain paths

Everything lives in the device holder's tape container, as ordinary SiteRegistry files.

PathContent
tapeboot/<board>/channel/<channel>.jsonChannel pointer
tapeboot/<board>/<seq>/manifest.jsonManifest, signed
tapeboot/<board>/<seq>/<file>File; anything over 8,400,000 bytes is split into <file>.p0, <file>.p1 ...
tapeboot/<board>/rollback/<seq>.jsonRollback instruction, optional, signed
NameRule
<board>[a-z0-9][a-z0-9-]{0,31}, for example mm-gw2a18
<seq>Positive decimal integer, no leading zeros
<channel>[a-z][a-z0-9-]{0,15}
All paths≤ 200 characters, do not start with /, contain none of \ ? # :, and have no empty segments, . or ..

A single on-chain file holds at most 350 chunks × 24,000 bytes = 8,400,000 bytes. Larger files are split into parts. Every part except the last is a multiple of 24,000 bytes long.

Channel pointer

{"tapeboot":1,"board":"mm-gw2a18","channel":"stable","seq":7,"manifest":"tapeboot/mm-gw2a18/7/manifest.json","manifest_sha256":"0x…"}
FieldMeaning
tapeboot1
boardBoard name
channelChannel name, such as stable or beta
seqThe version it points to
manifestManifest path
manifest_sha256sha256 of the manifest file, 0x + 64 lower-case hex digits

manifest

The tapeboot member

FieldTypeRule
vintegerMust be 1
boardstringEquals the board built into the device
seqinteger≥ 1, strictly increasing, equals <seq> in the path
versionstringsemver, for people only; which version is newer depends only on seq
createdstringRFC 3339 UTC, such as 2026-10-22T08:00:00Z; for people only
prevstringsha256 of the previous manifest; 64 zeros when seq = 1
min_loaderstringLowest semver of the boot firmware; anything lower is rejected
ownerobject{chain_id, registry, container, holder}
filesarray1–16 entries
sigstringSignature, see below

Addresses in owner are 0x + 40 hex digits, compared case-insensitively. The device compares each one with its built-in root of trust. If any one differs, the whole manifest is rejected.

Each entry in files[]

FieldTypeRule
namestring[A-Za-z0-9._-]{1,64}, unique within one manifest
rolestringbitstream / runtime / os / model / config
sizeintegerTotal file size in bytes, ≥ 1
sha256stringsha256 of the whole file (all parts joined in order)
chunkintegerMust be 24000
chunk_sha256arrayUsed when there are ≤ 256 chunks: entry i is the sha256 of chunk i, ceil(size/24000) entries in total
chunk_listobjectUsed when there are > 256 chunks; give exactly one of this and chunk_sha256
partsarrayThe on-chain parts in order, {path, size, sha256}; the size values add up to the file's size
loadstringfpga, sd, or ddr:0x plus 8 hex digits (such as ddr:0x81000000)
compressstringv1 only has none; any other value rejects the whole manifest

chunk_list (large files)

"chunk_list": {"path":"tapeboot/<board>/<seq>/<name>.chunks","size":<32 × number of chunks>,"sha256":"0x…","chunk_sha256":["0x…", …]}
FieldMeaning
pathPath of the list file; it must also be listed in tapeout.files
size32 × ceil(file size / 24000), ≤ 8,400,000
sha256sha256 of the whole list file
chunk_sha256Hashes of the list file itself, one per 24,000-byte chunk; one chunk holds 750 chunk hashes

Signature

Rules for canonical form (writing an object as the byte string C):

Steps:

  1. Remove tapeboot.sig and write the rest in canonical form, giving C.
  2. Digest D = sha256(C), 32 bytes.
  3. sig is the holder's EIP-191 personal_sign over D: the message is "\x19Ethereum Signed Message:\n32" followed by D, then keccak256.
  4. Write sig as 0x + 130 hex digits: r, s and v joined in that order, where v is 27 or 28.
  5. Verify: the address recovered from sig equals the built-in holder (case-insensitive). s must be in the lower half of the curve order, or it is rejected.

What is stored on chain is already in canonical form, so the board does not need to build a parse tree: cut the ,"sig":"0x…" segment out of the raw text and compute sha256. The result is the same as above.

Check order

A manifest is usable only after the device has done all of these:

StepWhat it checks
1The channel pointer's manifest_sha256 = the sha256 of the fetched manifest
2It parses; v = 1; board and seq match the path; every compress is none; min_loader ≤ the local version
3The four owner fields = the built-in root of trust
4The address recovered from the signature = the built-in holder
5seq ≥ min_seq (the seq of the last successful boot, kept on the microSD)
6If the previous manifest is stored locally, prev = its sha256; if not (fresh install, skipped versions), do only 1–5
7Check every chunk against chunk_sha256, and every part and every file against sha256

Two ways to read

WayWho uses itRule
Full wayHosts, web pages, packaging toolsPin to a finalized block, check eth_chainId, require at least 2 independent operators to agree exactly, send only read-only methods; also reconcile against fileInfo.sha256Hash recorded on chain and parts[].sha256
Device wayBoardsCan connect to just one node, without pinning a block or voting. With signatures and per-chunk hashes, a node can only cause a failure or a controlled downgrade. Configure 2 or more nodes

Fetching bytes: first get the size with fileInfo(container, path), then call readRange(container, path, offset, len). offset and len are multiples of 24,000 (except for the last chunk). As a fallback, use the https://<tape name>.tapekit.org/<path> gateway, in the device way only.

Slots and rollback

ItemRule
Chunk cachecache/<chunk_sha256 without 0x> on the microSD; the same chunk is reused across files and versions
Slotsslot/a/ and slot/b/, each holding a complete manifest and its files
Statestate.json: {active, pending, min_seq}
CommitInstall the new version into the slot not in use, mark it pending and do a trial run; if a heartbeat arrives within 60 seconds, set active = the new slot and min_seq = the new seq
RollbackWith no heartbeat, go back to the old slot, mark the new seq as a bad version, and do not try it again automatically
Manual rollbackThe channel pointer can point to an older seq, but not below min_seq
Rollback instructionGoing below min_seq needs a separate rollback/<seq>.json signed by the holder, see below
{"tapeboot":1,"board":"…","kind":"rollback","to_seq":5,"new_min_seq":5,"nonce":<next value of seq>,"sig":"0x…"}

It is signed the same way as the manifest. If the signature checks out and nonce is greater than the largest seq seen, lower min_seq to new_min_seq. A v1 board client may leave this out.

Client API

FunctionWhat it does
tb_init(cfg)Built-in root of trust, node list, gateway, cache directory
tb_resolve(channel)Read the channel → fetch the manifest → run check steps 1–6
tb_plan(manifest)List the chunks missing from the cache
tb_fetch(manifest, file, sink, progress_cb)Fetch chunk by chunk, check hashes, write the cache; hand the file to the write target in order only after the whole file passes
tb_stage(manifest)Once every file is fetched, write them into the standby slot and mark it pending
tb_commit(manifest)Commit after a successful boot
tb_rollback()Go back to the old slot
tb_status(){seq, slot, pending, min_seq, last_error}

Error kinds: transport, not-found, bad-manifest, wrong-owner, bad-sig, old-seq, bad-prev, loader-too-old, chunk-mismatch, file-mismatch, no-space.

Known limits

  1. In the device way, a node can point the device to an older signed version, as long as it is not below min_seq.
  2. If the holder loses the private key or the container changes hands, the device stops accepting new versions, and you have to flash the boot firmware again.
  3. The chunk hashes in a single manifest cover about 48 MB at most.
  4. created and version are for people only and play no part in deciding which version is newer.
  5. v1 has no compression.
For a step-by-step guide, see Fetch firmware from the chain.