Repository navigation
Releases
v0.1.3 — MerkleNode frozen; directory trees
MerkleNode joins the frozen 0.1.x surface, and directory trees arrive as
experimental, default-off features. Every existing golden vector is
byte-identical, and every identifier minted under earlier 0.1.x releases
remains valid. The dir_tree breaking notes below apply only to the new,
non-frozen features.
Added
-
MerkleNodebytes are frozen (#112): cross-language vectors in
tests/merkle_vectors.json, checked in Rust and Python.MerkleNodeis in the
default surface;unstable-merkleis now a deprecated no-op alias. -
dir_treesingle-file roots (#109):Linkis nowContentAddressable, and
snapshot/snapshot_withreturn the rootLink(also stored), so a
regular file is a root:resolve(store, &link.content_id()?, "")proves it
andverify_filechecks it, extra digests included. A file root and a
directory root over the same bytes have different ids;DirNodebytes are
unchanged. Breaking (experimental, non-frozen):snapshotreturnsLink
notContentId;resolve/Proof::verifytake aLinkid;Proof.nodes[0]
is the root link's bytes, sonodes.len()is depth + 1. -
structures::dir_treebehind the new default-offdir-treefeature
(#105):DirNode/Link,snapshot,resolveandProof. One root
ContentIdnames a directory of files, and a path resolves to a file's id
with an O(depth) proof that verifies against only the root. Bytes are
NON-FROZEN until conformance vectors land (#33). -
dir_treemulti-digest file links behind the new default-offmulti-digest
feature (#107):Link::Filegainsalso, extra SHA-256 / MD5 digests of
the same bytes thatProof::verify_filechecks ALL of, alongside BLAKE3 and
size. NewDigestAlg,file_link,snapshot_with, and the typed errors
InvalidDigest/UnsupportedDigest. A link with noalsokeeps its
previous bytes and root.Linkis no longerCopy.
v0.1.2 — the decode side of the contract
[0.1.2] — 2026-08-27 — the decode side of the contract
This release closes the hole on the other side of the codec — decoding (#90).
Every golden vector is byte-identical and identifiers minted under 0.1.0 /
0.1.1 remain valid. It is not purely additive, and says so: it makes one
deliberate, narrow exception to the otherwise frozen 0.1.x Rust API, recorded
under Stability exception below.
The defect. canonical::from_canonical_dagcbor was a bare
serde_ipld_dagcbor::from_slice. It never compared the bytes it was handed
against the canonical encoding of the value it returned, so a decoded value could
re-encode to different bytes and therefore carry a different ContentId
than its own source — silently. Two independent causes: the bytes may not have
been canonical (reordered map keys, non-minimal integers — all of which decode
fine), or the target type may have dropped a field it does not name (serde
ignores unknown map keys by default; for a protocol record that field may have
been a required demand). ContentId::from_canonical_bytes_checked catches the
first but structurally cannot catch the second: it re-encodes as generic IPLD,
which keeps every key. Only a typed round trip sees it.
Added
-
canonical::from_canonical_dagcbor_checked<T: DeserializeOwned + Serialize>
— decode, then prove the round trip. Three stages, each naming a different
party: the bytes are canonical (NonCanonicalblames the bytes), they
decode as aT(DecodingError), and re-encoding the value reproduces them
byte-for-byte (LossyDecodeblames the bytes/type pairing — these bytes
are not that type's canonical representation of what it decoded). Exact byte
equality is stronger than comparing the two ids — it assumes no collision
resistance. -
ContentAddressable::from_canonical_form— the same guarantee as a
defaulted trait method, so the ergonomic path is the safe one. It re-encodes
through the type's owncanonical_form(the function that defines its
identity), not throughto_canonical_dagcbor, which is why its bound is
DeserializeOwned + Sizedand not alsoSerialize. It carries
where Self: Sized, so the trait stays dyn-compatible.The enforced guarantee is byte equality, and the method never calls
content_id:let value = T::from_canonical_form(b)?; assert_eq!(value.canonical_form()?, b);
value.content_id()? == ContentId::from_canonical_bytes(b)follows only as a
corollary for a lawful implementation — one whosecontent_id()obeys the
trait law.content_idis overridable and nothing here calls it, so the crate
cannot enforce the corollary; useensure_content_idwhen it must be held
rather than assumed. The returned value has the same canonical representation
and identity as the input bytes, but is not necessarily equal to a previously
encoded in-memory value — a#[serde(skip)]field is absent from the encoding,
so two values differing only in it share identical canonical bytes and the
decode returns the default. (A plain#[serde(default)]field is not such a
case: it is written back on re-encode, so it produces aLossyDecodemismatch
unless it is also omitted when serializing.)This is the one addition covered by the Stability exception below.
-
ContentError::LossyDecode— added under the enum's#[non_exhaustive]
contract, which the0.1.0error policy kept for exactly this. It carries no
source, likeNonCanonical: nothing failed underneath, a comparison simply
came out unequal. Theerrormodule's operation → variant map gains a row
(rows may be added per its own freeze note). -
Python:
from_canonical_dagcbor_checked— delegating to the same core
function the Rust face calls, so the two languages cannot disagree about what is
canonical. Python had no canonicality gate of any kind before this. The
LossyDecodehalf has no Python analogue and cannot: Python decodes into the
generic model, which keeps every key, so no field can be dropped. The test
suite pins that as a property rather than leaving it assumed.
Stability exception
Version 0.1.2 makes one deliberate, narrow exception to the otherwise
frozen 0.1.x Rust API: it adds the defaulted associated function
ContentAddressable::from_canonical_form.
Adding a defaulted associated function to a public trait is RFC 1105's minor /
possibly breaking category. A downstream type that implements
ContentAddressable and receives an associated function of the same name
from another trait in scope can now fail with error[E0034]: multiple applicable items in scope. Disambiguate with fully qualified trait syntax:
<T as OtherTrait>::from_canonical_form(bytes)The method's where Self: DeserializeOwned clause does not remove it from
resolution for such an implementor, so the exposure is not limited to types that
implement Deserialize. A ^0.1 dependency picks this up without an opt-in,
which is why it is recorded rather than left to be discovered.
No wire bytes, CID profile, canonical encoding, identifier, existing method
signature, or existing runtime behavior is removed or changed. The remainder of
the 0.1.x stability contract stays in force, and this exception does not
license further ones. See docs/STABILITY.md.
Deprecated
canonical::from_canonical_dagcbor— it verifies neither canonical form
nor the typed round trip, and its name says otherwise. Behavior is
unchanged for0.1.x; removal is a major-version event. Successors:
from_canonical_dagcbor_checked, orContentAddressable::from_canonical_form
when the type isContentAddressable. Deprecation rather than a silent fix so
that a consumer under a zero-warnings policy is told, at the call site, that
they are on the unverified path. The Pythonfrom_canonical_dagcborkeeps its
behavior as the deliberate mirror of that door.
Fixed
-
A
tag-42link cannot be re-encoded from Python. The Python codec has been
asymmetric about links since it shipped: decoding maps one to aContentId
object, whileto_canonical_dagcborhas no case for aContentIdand raises
TypeError. The asymmetry itself is unchanged (fixing it means rewriting the
Python encode path, which is not this release's business), but it is now
documented and pinned by tests in the README, the new door's docstring, and
the Python suite: a link-bearing document decodes fine and
ContentId.from_canonical_bytes(b)is still its correct id, but you must mint
from the bytes, never from the decoded value. Rust has no such gap. -
tests/test_profile_validation.py's foreign-link fixture was malformed — 44
bytes for a CBOR item declaring 41, so every decode of it failed in the codec
withTrailingDatabefore the profile check, and the only Python test
guarding that path had never once exercised it. Corrected, parametrized over
both decode doors, the error message asserted, and a structural guard added so
the fixture cannot silently go malformed again. -
The Python
from_canonical_dagcbordocstring claimed a check that never
ran — "Raises ValueError if the bytes are not valid canonical dag-cbor". It
did not verify canonicality. The docstring now states what the function does
and points at the checked door. -
One canonicality implementation, not two. The gate
ContentId::from_canonical_bytes_checkedapplies is now a single shared
function, andNodeStoreExt::get_node— which had open-coded exactly the three
stagesContentAddressable::from_canonical_formperforms — shares that body.
Behavior is unchanged in both; they can no longer drift apart.get_noderuns the shared body, not the trait method:from_canonical_form
is defaulted on an unsealed trait, so aTthat overrode it could otherwise
have switched the seam's whole check off. Stages 1 and 2 (canonicality, then the
typed decode) stay type-independent and out ofT's reach; stage 3 necessarily
consultsT::canonical_form, which is what identity means for a
ContentAddressable. The lossy verdict travels as a value rather than an error,
so aLossyDecoderaised inside a caller's owncanonical_formis still
propagated verbatim instead of being relabelledRepresentationMismatch.
Notes
- No wire bytes changed.
tests/vectors.json,tests/raw_vectors.jsonand
tests/legacy_vectors.jsonare untouched, and every vector in the DAG-CBOR set
is now additionally asserted to survive the checked decoder and come back naming
the pinned id — a gate that refuses bad bytes is only worth having if it accepts
everything the crate itself calls canonical. - The raw and legacy vector sets are deliberately not run through it: they pin
the identities of opaque byte strings and of legacy identifier text, neither of
which is a DAG-CBOR document. The profile law is that the codec is part of the
identity.
v0.1.1 — the identity/classification layer
[0.1.1] — the identity/classification layer
Additive: the frozen 0.1.0 core contract is untouched, every golden vector
is byte-identical, and identifiers minted under 0.1.0 remain valid. This
release makes foreign content identity representable without ever minting it
(#84, ADR 0003).
Added — frozen for 0.1.x
RawContentId— CIDv1 ·raw(0x55) · BLAKE3-256 (0x1e) · 32 bytes:
the identity of an opaque byte string, sibling toContentId(the DAG-CBOR
profile). Same four presentation forms, same accessor names. Its bytes are
fixed by the CID specification, not by this crate, and pinned cross-language
bytests/raw_vectors.json. Rust and Python.ClassifiedCid { Content | Raw | Foreign(ForeignCid) }— classification of
any well-formed CID. The three variants are pairwise disjoint and jointly
total:ForeignCid's every constructor rejects a recognized profile, so each
CID has exactly one representation, andDeserializederives the variant
from the wire bytes rather than trusting it.- The profile law. Codec + multihash algorithm + digest jointly constitute
identity.RawContentId(x)never equalsContentId(x)even when the digest
bytes coincide — no cross-typePartialEq, noFromeither way, and each
ingress rejects the other's codec. Compare identities as typed CID bytes,
never asdigest_hex()(identical across profiles for the same digest). ContentId::from_dag_cbor_digest— the honest no-rehash door for a digest
the caller knows is over canonical DAG-CBOR.
Deprecated
ContentId::from_blake3_content_digest(Rust and Python) — it stamped the
DAG-CBOR codec on a digest it could not know came from DAG-CBOR. Behavior is
unchanged for0.1.x; removal is a major-version event. Successors:
RawContentId::from_blake3_digestfor opaque bytes,
ContentId::from_dag_cbor_digestfor known-DAG-CBOR digests.
Added — experimental (NOT frozen), opt-in, default-off
unstable-legacy— parse-only edge adapters for the dialects still in the
wild (legacy::kylnenvelope-hex,legacy::nessie<algo>:<hex>,
legacy::bare_blake3), pinned bytests/legacy_vectors.json. Rust-only by
design. CanonicalFromStrnever learns a legacy dialect, so enabling
this cannot change how canonical text parses.unstable-migration—IdentityMigration/MigrationKind, a
content-addressed record stating that one identity superseded another.
Construction and both serde ingresses validate (non-mintabletoand
self-migration are refused;deny_unknown_fieldson a private wire shape).
Its API and its bytes are both unfrozen until golden migration vectors
land — its field names are load-bearing for its own id. Do not persist these
records as long-lived identity claims yet.
Notes
ClassifiedCidis named Classified, not Verified: it proves structural
validity and profile membership, never that content matches a digest. Content
verification remainsverify/ensure_content_id(andVerifiedStore,
which does check bytes on read).- Canonical emitted text is still base32-lower only.
content-addressable 0.1.0
[0.1.0] — first stable-contract release
The first release to freeze the core content-addressing contract for the
whole 0.1.x line. Downstream systems can persist identifiers and link against
the byte/wire and API surface below; changing any frozen item is a breaking
release outside 0.1.x.
Frozen for 0.1.x (the stable contract)
- IPLD-native CIDv1 identifiers. A
ContentIdis a CID version 1 with the
fixed profile: dag-cbor codec (0x71), BLAKE3 multihash (0x1e), and
a 32-byte digest. Canonical string form is multibase base32-lower
(bafyr4i…). - Canonical dag-cbor.
to_canonical_dagcbor/from_canonical_dagcbor
produce and parse the one canonical DAG-CBOR encoding (deterministic map key
ordering, definite lengths), so equal values always yield equal bytes and
equal ids regardless of input field order. - Frozen presentation forms, Rust and Python. The CID string form, the full
binary CID envelope (to_bytes/from_bytes), and the bare-digest accessors
(digest_bytes= 32 bytes,digest_hex= 64 hex chars) are identical across
both languages. - Golden cross-language vectors.
tests/vectors.jsonpins the byte-exact
Rust↔Python parity; both test suites verify against the same vectors. - Fail-closed CID profile validation at every ingress.
FromStr,
TryFrom<Cid>,from_bytes(CID binary), and serde (human-readable and
binary) all reject any CID outside the frozen profile with
ContentError::InvalidCidProfile. The Pythonparse/from_bytesroute
through the same checks. An off-profileContentIdcannot be constructed. - Checked and unchecked canonical-byte constructors.
from_canonical_bytes
hashes canonical bytes into the fixed profile (always on-profile);
from_canonical_bytes_checkedadditionally re-derives and compares;
from_blake3_content_digestis the documented unchecked no-rehash door
(the caller asserts the digest is BLAKE3 over canonical DAG-CBOR) and still
emits the fixed profile envelope. - Verification. The
ContentAddressabletrait exposescontent_id,
verify(recompute and compare), andensure_content_id;verifysurfaces
the underlying encoding error rather than a bare boolean. - MSRV Rust
1.85(Rust 2024-edition baseline), enforced by a dedicated CI
job so a transitive dependency cannot silently raise the floor. - Python
3.9+, abi3. Oneabi3-py39wheel per platform (Linux x86_64 /
aarch64, macOS universal2, Windows x64) plus an sdist; forward-compatible with
newer CPython without a per-version rebuild.
Experimental (NOT frozen) — opt-in, default-off
-
unstable-merkle—MerkleNode<T>content-addressed DAG nodes. The
serialized node bytes are not frozen and may change within0.1.xuntil
Merkle conformance vectors land. -
unstable-store— the CID-addressed node-store seam (NodeStore,
NodeStoreExt,VerifiedStore,MemoryStore,AddressedBytes,
StoreError,StoreOperation). The trait/API surface is not frozen and
defines no new wire bytes of its own.These are not production-ready and are named to say so. See
docs/STABILITY.md.
Migration from 0.1.0-alpha.1
- Feature rename (breaking for feature users): the experimental cargo
features were renamed to carry their stability at the call site —
merkle→unstable-merkle,store→unstable-store. There are
no compatibility aliases. If you enabledfeatures = ["merkle"]/
["store"], switch to["unstable-merkle"]/["unstable-store"]. The Rust
module paths (content_addressable::merkle,::store) and type names are
unchanged — only the feature flags moved. Users of the default (frozen core)
feature set are unaffected. - The frozen core byte/wire contract is unchanged from
0.1.0-alpha.1:
every golden vector is byte-identical, so identifiers minted under the alpha
remain valid.
Compatibility
- The abandoned SHA3-256 /
picklePython sibling is incompatible. An
earlier, unrelated Python implementation that hashed with SHA3-256 over a
pickleserialization produces different, non-interoperable identifiers.
It is not this package; do not mix identifiers between the two.
Known limitations
- The Merkle catalog is incomplete and experimental (
unstable-*); its bytes
and API may change within0.1.x. from_blake3_content_digestis unchecked by design — it trusts the caller's
digest provenance.- Non-integer floats are outside the canonical vector set (DAG-CBOR float rules
are handled per-language, not in the shared cross-language gate).
Install
# Rust (crates.io)
content-addressable = "0.1.0"# Python (PyPI) — distribution `content-addressable`, import `content_addressable`
pip install content-addressable==0.1.0Verification
Published from the protected release workflow on the merged, signed commit
534d96d34da41c9f50afdcc03d6dc42c69fdc022 (tag v0.1.0). Every PyPI file's
SHA-256 was verified identical to the CI-built, gate-validated artifacts.
See the attached SHA256SUMS.txt.