CRUMB a card from devarno-cloud

SPUH 16-byte Routing Header

grace advanced 5 min read

ELI5

SPUH is a postage stamp on every unit. Sixteen bytes that say what it is, what shape it has, what version, and the first 64 bits of its full fingerprint — enough to route or filter without opening the parcel.

Technical Deep Dive

Source: packages/schema/src/spuh.ts. Functions: encodeSpuh(fields): Uint8Array (lines 37–61), decodeSpuh(buf): SpuhFields (lines 67–108), fingerprintToPrefix(fp): bigint (lines 114–120).

Header Layout (128 bits)

packet
title SPUH header 16 bytes
0-3: "Ver(4)"
4-7: "Type(4)"
8-11: "Domain(4)"
12-15: "Status(4)"
16-23: "Major(8)"
24-31: "Minor(8)"
32-39: "Patch(8)"
40-55: "SchemaVersion(16, BE)"
56: "gate"
57: "protected"
58: "coreInjected"
59: "crdtDirty"
60-63: "unused(4)"
64-127: "Blake3 fingerprint prefix (64 bits = 16 hex chars)"

Field Reference

BytesFieldNotes
0Version (4) | Type (4)Type maps to one of 5 unit types
1Domain (4) | Status (4)Domain SPUH bit mapping in constants.ts:54-60
2–4Major | Minor | PatchSemver components, 1 byte each (0–255)
5–6SchemaVersion16-bit big-endian schema-of-schema version
7Flagsbit 0 gate, bit 1 protected, bit 2 coreInjected, bit 3 crdtDirty, bits 4–7 unused
8–15Fingerprint prefixFirst 16 hex chars of full digest, packed as 64-bit unsigned int

Why a Prefix, Not the Full Digest

  • Full digest is 32 bytes. A 64-bit prefix is plenty for routing tables and bloom filters.
  • Verification still requires the full digest (SPEC-02 verify pipeline).
  • fingerprintToPrefix("blake3:a1d94a02...") strips the prefix label, takes the first 16 hex chars, parses as BigInt.

Wire Use Cases

  • Fast filter: “give me all published dev chain units” reads byte 0 + byte 1 + byte 7 only.
  • Routing: cross-namespace bridges can route on domain bits without parsing the full unit.
  • Bloom-filter membership: crdtDirty and coreInjected flags compress per-batch state.

Key Terms

  • SPUH → STRATT Prompt Unit Header; binary header that complements the YAML body.
  • Fingerprint prefix → 64-bit truncation of the Blake3 digest; routing-grade, not security-grade.
  • crdtDirty flag → Set by L2 CRDT layer; consumed by reconciliation passes.

Q&A

Q: Can two units collide on the SPUH fingerprint prefix? A: Yes — 64 bits gives ~1.8e19 buckets, so collisions are negligible at protocol scale but mathematically possible. Verification always reads the full 256-bit digest.

Q: What happens if unused flag bits are set on read? A: decodeSpuh ignores them. Forward compatibility — they reserve space for future per-unit booleans (e.g. signed, encrypted).

Q: Is endianness specified for SchemaVersion? A: Big-endian, 16 bits. Major/Minor/Patch are single bytes so endianness doesn’t apply.

Examples

Decoded SPUH for stratt://dev/chain/sol-1-boot@0.1.0 with status published, gate present, fingerprint blake3:a1d94a025f820f161ce6...:

  • byte 0: 0x14 = (version 1, type chain=4)
  • byte 1: 0x03 = (domain dev=0, status published=3)
  • bytes 2–4: 0x00 0x01 0x00 (semver 0.1.0)
  • byte 7: 0x01 (gatePresent set)
  • bytes 8–15: 0xa1d94a025f820f16 (first 16 hex chars of digest as u64)

neighbors on the map