DAG-CBOR Implementation Notes#

DAG-CBOR is the canonical data serialization format for the AT Protocol. It is a strict subset of CBOR (RFC 8949) with specific rules for determinism and linking.

1. Canonicalization Rules#

To ensure consistent Content IDs (CIDs) for the same data, specific canonicalization rules must be followed during encoding.

Map Key Sorting#

Maps must be sorted by keys. The sorting order is NOT standard lexicographical order.

1. Length: Shorter keys come first.
2. Bytes: keys of the same length are sorted lexicographically by their UTF-8 byte representation.

Example:

• "a" (len 1) comes before "aa" (len 2).
• "b" (len 1) comes before "aa" (len 2).
• "a" comes before "b".

Integer Encoding#

Integers must be encoded using the smallest possible representation.

System.Formats.Cbor (in Strict mode) generally handles this, but care must be taken to treat int, int64, and uint64 consistently.

2. Content Addressing (CIDs)#

Links to other nodes (CIDs) are encoded using CBOR Tag 42.

Format#

1. Tag: 42 (Major type 6, value 42).
2. Payload: A byte string containing:
   • The 0x00 byte (Multibase identity prefix, required by IPLD specs for binary CID inclusion).
   • The raw bytes of the CID.

3. Known Gotchas#

• Float vs Int: AT Protocol generally discourages floats where integers suffice. F# types must be matched carefully to avoid encoding 2.0 instead of 2.
• String Encoding: Must be UTF-8. Indefinite length strings are prohibited in DAG-CBOR.