Skip to main content

Module cid

Module cid 

Source
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 b is lowercase RFC4648 base32 without padding — the IPFS/atproto canonical CIDv1 encoding. (The z base58btc 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 local at9p-capsule code 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)

algocodeused for
sha10x11legacy git blob/tree/commit OIDs
sha2-2560x12git OIDs (sha256 repos), XET tags
blake30x1eXET hashes; at9p BLAKE3-512 CIDs

§Multicodec codes

codeccodestatus
git-raw0x78registered (multicodec table)
xet-xorb0x71LOCAL convention, unregistered (#395)
xet-shard0x72LOCAL convention, unregistered (#395)
at9p-capsule0x73LOCAL 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.
HashAlgo
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-raw CIDv1. 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.