Skip to main content

Module dag_cbor

Module dag_cbor 

Source
Expand description

Hyprstream’s existing deterministic CBOR encoding/decoding.

Compatibility note: this codec uses lexical text-key ordering. Public AT Protocol DAG-CBOR instead orders encoded keys (length first). Use crate::atproto_cbor for that explicit boundary. Existing native signed artifacts retain this codec; do not silently change their bytes or verifier.

DAG-CBOR is a restricted subset of CBOR (RFC 7049) with additional constraints so that a given value always produces the exact same bytes — and therefore the same CID. This determinism is load-bearing for the MST (whose internal CIDs are computed over DAG-CBOR node bytes) and for the commit signature (which signs DAG-CBOR bytes).

§Constraints enforced here

  1. Map keys are sorted in pure lexicographic text-byte order, preserving the existing native format. This differs from public DAG-CBOR ordering.
  2. Integers use minimal encoding: u8 < 24 → one byte (major 0/1); otherwise the smallest power-of-two width (1/2/4/8 bytes).
  3. No duplicate keys: decoding rejects them.
  4. Map keys are text strings: DAG-CBOR does not allow non-string keys.
  5. Recursion is bounded: decoding rejects containers nested deeper than [MAX_RECURSION_DEPTH] instead of risking stack overflow.
  6. CIDs are CBOR tag 42 byte strings carrying the DAG-CBOR link payload (leading 0x00 identity marker + raw CID bytes), per the DAG-CBOR spec.
  7. Tag 42 byte strings are reserved: any non-CID byte string is decoded as DagCbor::Bytes, never confused with a link.

§Why a custom enum rather than serde + ciborium directly

serde-driven CBOR cannot (a) guarantee map key ordering for arbitrary structs without a manual sorted-map type, nor (b) round-trip CBOR tag 42 links as first-class values. By going through a small typed DagCbor enum we make both invariants explicit and verifiable in tests (same record → same bytes → same CID).

Enums§

DagCbor
A typed DAG-CBOR value.