Expand description
CIDv1 + multihash encoder for content-addressed model references (#395).
Produces deterministic CIDv1 strings for git OIDs and XET chunk/shard hashes,
giving every model artifact a single canonical identifier that survives moves
between the local registry, the atproto federated record store, and XET-backed
CAS shards. The wire representation stays modelRef :Text in the capnp schema
(#395 is a Rust-only grammar change); the CID is the canonical text payload
federated peers resolve.
§Layout
CIDv1 ::= multibase("b") || base32( <0x01> || multicodec || multihash )
multihash ::= uvarint(algo) || uvarint(len) || digest- Multibase
bis lowercase RFC4648 base32 without padding — the IPFS/atproto canonical CIDv1 encoding. (Thezbase58btc prefix used by DID-doc Multikeys is rejected here: CIDs are base32.) See https://github.com/multiformats/multibase. - CID version is always
0x01(CIDv1). CIDv0 (sha1+git implicit) is not emitted; git OIDs get an explicit CIDv1 instead. - Multicodec identifies the content type:
git-raw(0x78) for a raw git object addressed by OID, the local XET codes below for XET hashes, and the localat9p-capsulecode for capsule commitments. - Multihash carries the hash algorithm + digest, so a CID is self-describing and can address sha1 git blobs, sha2-256 git-tree hashes, and blake3 XET chunks uniformly.
§Hash codes (multiformats/multicodec registry)
| algo | code | used for |
|---|---|---|
| sha1 | 0x11 | legacy git blob/tree/commit OIDs |
| sha2-256 | 0x12 | git OIDs (sha256 repos), XET tags |
| blake3 | 0x1e | XET hashes; at9p BLAKE3-512 CIDs |
§Multicodec codes
| codec | code | status |
|---|---|---|
| git-raw | 0x78 | registered (multicodec table) |
| xet-xorb | 0x71 | LOCAL convention, unregistered (#395) |
| xet-shard | 0x72 | LOCAL convention, unregistered (#395) |
| at9p-capsule | 0x73 | LOCAL convention, unregistered (#881) |
The XET and at9p-capsule codes live in the multicodec reserved (0x70–0x7f)
private-use range and MUST be replaced with official codes once registered
with multiformats. They are tagged LOCAL_CONVENTION so a grep finds them
when the migration lands.
§Determinism
Encoding is a pure function of (codec, algo, digest): the same input always
yields the same CID string (no randomness, no timestamps, no canonicalization
ambiguity). Round-tripping decode(encode(x)) == x holds for all valid CIDs.
Structs§
- Cid
- A decoded CIDv1: the content-type codec and the multihash.
- Multihash
- A decoded multihash: the algorithm tag and the raw digest bytes.
Enums§
- Codec
- Content-type codec identifying what a CID addresses.
- Hash
Algo - Hash-algorithm codes from the multihash table (https://github.com/multiformats/multicodec/blob/master/table.md).
Functions§
- decode_
cid - Decode a canonical CIDv1 base32 string produced by
encode_cid. - decode_
multihash - Decode a multihash produced by
encode_multihash. - encode_
cid - Encode raw
(codec, algo, digest)as a canonical CIDv1 base32 string. - encode_
git_ oid - Encode a git OID (hex string) as a
git-rawCIDv1. The algorithm is inferred from the hex length: 40 chars → sha1, 64 chars → sha2-256. - encode_
multihash - Encode a digest as a multihash:
uvarint(algo) || uvarint(len) || digest.