proofbundle 2.0.0b2__tar.gz → 2.0.0b3__tar.gz

{proofbundle-2.0.0b2/src/proofbundle.egg-info → proofbundle-2.0.0b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proofbundle
-Version: 2.0.0b2
+Version: 2.0.0b3
 Summary: Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT.
 Author: Konrad Gruszka
 License: MIT
@@ -32,6 +32,7 @@ Requires-Dist: rfc3161-client>=1.0.6; extra == "anchors"
 Requires-Dist: opentimestamps>=0.4.5; extra == "anchors"
 Requires-Dist: rfc8785>=0.1.4; extra == "anchors"
 Provides-Extra: adapters
+Provides-Extra: chia
 Provides-Extra: experimental
 Provides-Extra: pq
 Requires-Dist: cryptography>=48; extra == "pq"
@@ -67,10 +68,12 @@ these exact bytes* and *that nothing changed since* — not that the number is t
 Merkle, one file, no server, no network.
 
 [![CI](https://github.com/b7n0de/proofbundle/actions/workflows/ci.yml/badge.svg)](https://github.com/b7n0de/proofbundle/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/proofbundle.svg)](https://pypi.org/project/proofbundle/)
+[![Python](https://img.shields.io/pypi/pyversions/proofbundle.svg)](https://pypi.org/project/proofbundle/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-D6248A.svg)](LICENSE)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Mutation tested](https://img.shields.io/badge/tests-mutation_gated-D6248A.svg)](scripts/mutation_check.py)
-<!-- PyPI / Downloads / SLSA / PEP 740 badges are enabled on the first PyPI release — see RELEASE.md. -->
+<!-- SLSA / PEP 740 attestation badges follow once the first attested release lands, see RELEASE.md. -->
 
 </div>
 
@@ -156,6 +159,14 @@ flowchart LR
   `PROOFBUNDLE_EMIT=1` / `--proofbundle`), plus a Hugging Face Community Evals bridge. See
   [INTEGRATIONS.md](INTEGRATIONS.md), or the end-to-end walkthrough
   [docs/INSPECT_HAPPY_PATH.md](docs/INSPECT_HAPPY_PATH.md) — run an eval, get a receipt, verify it offline.
+- **External time anchors** *(v2.0 beta, the `[anchors]` extra)* — an optional `anchors[]` layer that
+  attaches external evidence of *when* a commitment or receipt existed, from a party the producer does not
+  control. Two built-in types verify offline: **RFC 3161** TSA tokens (against a frozen cert chain) and
+  **OpenTimestamps** Bitcoin proofs (honest pending → confirmed lifecycle). A `register_anchor_type`
+  extension interface lets a third party ship its own fail-closed type; two worked examples ship — a
+  first-party **`chia-datalayer/v1`** (offline Merkle inclusion of a canonical root under a published Chia
+  DataLayer root) and a third-party **`markovian-provenance/v1`** (a wallet-attributable, Bitcoin-anchored
+  stamp). See [docs/ANCHORS.md](docs/ANCHORS.md).
 
 ## Docs
 
@@ -170,6 +181,7 @@ flowchart LR
 | Honest comparison to Rekor / in-toto / OMS / ValiChord | [INTEROP.md](INTEROP.md) |
 | Regulatory mapping (and what to never claim) | [COMPLIANCE.md](COMPLIANCE.md) |
 | Funders / role fit | [docs/PROJECT_BRIEF.md](docs/PROJECT_BRIEF.md) |
+| External time anchors + the bring-your-own-type extension interface (v2.0 beta) | [docs/ANCHORS.md](docs/ANCHORS.md) |
 | **Preview:** TEE-attestation bridge (v2.0 beta) | [docs/EXPERIMENTAL_ENCLAVE.md](docs/EXPERIMENTAL_ENCLAVE.md) |
 
 ## Install

{proofbundle-2.0.0b2 → proofbundle-2.0.0b3}/README.md

@@ -14,10 +14,12 @@ these exact bytes* and *that nothing changed since* — not that the number is t
 Merkle, one file, no server, no network.
 
 [![CI](https://github.com/b7n0de/proofbundle/actions/workflows/ci.yml/badge.svg)](https://github.com/b7n0de/proofbundle/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/proofbundle.svg)](https://pypi.org/project/proofbundle/)
+[![Python](https://img.shields.io/pypi/pyversions/proofbundle.svg)](https://pypi.org/project/proofbundle/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-D6248A.svg)](LICENSE)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Mutation tested](https://img.shields.io/badge/tests-mutation_gated-D6248A.svg)](scripts/mutation_check.py)
-<!-- PyPI / Downloads / SLSA / PEP 740 badges are enabled on the first PyPI release — see RELEASE.md. -->
+<!-- SLSA / PEP 740 attestation badges follow once the first attested release lands, see RELEASE.md. -->
 
 </div>
 
@@ -103,6 +105,14 @@ flowchart LR
   `PROOFBUNDLE_EMIT=1` / `--proofbundle`), plus a Hugging Face Community Evals bridge. See
   [INTEGRATIONS.md](INTEGRATIONS.md), or the end-to-end walkthrough
   [docs/INSPECT_HAPPY_PATH.md](docs/INSPECT_HAPPY_PATH.md) — run an eval, get a receipt, verify it offline.
+- **External time anchors** *(v2.0 beta, the `[anchors]` extra)* — an optional `anchors[]` layer that
+  attaches external evidence of *when* a commitment or receipt existed, from a party the producer does not
+  control. Two built-in types verify offline: **RFC 3161** TSA tokens (against a frozen cert chain) and
+  **OpenTimestamps** Bitcoin proofs (honest pending → confirmed lifecycle). A `register_anchor_type`
+  extension interface lets a third party ship its own fail-closed type; two worked examples ship — a
+  first-party **`chia-datalayer/v1`** (offline Merkle inclusion of a canonical root under a published Chia
+  DataLayer root) and a third-party **`markovian-provenance/v1`** (a wallet-attributable, Bitcoin-anchored
+  stamp). See [docs/ANCHORS.md](docs/ANCHORS.md).
 
 ## Docs
 
@@ -117,6 +127,7 @@ flowchart LR
 | Honest comparison to Rekor / in-toto / OMS / ValiChord | [INTEROP.md](INTEROP.md) |
 | Regulatory mapping (and what to never claim) | [COMPLIANCE.md](COMPLIANCE.md) |
 | Funders / role fit | [docs/PROJECT_BRIEF.md](docs/PROJECT_BRIEF.md) |
+| External time anchors + the bring-your-own-type extension interface (v2.0 beta) | [docs/ANCHORS.md](docs/ANCHORS.md) |
 | **Preview:** TEE-attestation bridge (v2.0 beta) | [docs/EXPERIMENTAL_ENCLAVE.md](docs/EXPERIMENTAL_ENCLAVE.md) |
 
 ## Install

{proofbundle-2.0.0b2 → proofbundle-2.0.0b3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proofbundle"
-version = "2.0.0b2"
+version = "2.0.0b3"
 description = "Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -52,6 +52,11 @@ eval = ["rfc8785>=0.1.4"]
 anchors = ["rfc3161-client>=1.0.6", "opentimestamps>=0.4.5", "rfc8785>=0.1.4"]
 # The lm-eval adapter reads exported results.json (no import) → pure stdlib.
 adapters = []
+# chia-datalayer/v1 anchor WRITER (anchors_chia_add). Needs no extra Python package — it drives the
+# stable `chia rpc data_layer|full_node` CLI of a locally installed, cert-authed Chia node (the DataLayer
+# node is the real dependency, not a wheel). Declared so `pip install proofbundle[chia]` is a documented,
+# discoverable install target. VERIFYING an anchor offline (anchors_chia) needs neither this nor a node.
+chia = []
 # EXPERIMENTAL (v2.0 preview): the TEE-attestation bridge (proofbundle.experimental.enclave).
 # Opt-in and clearly unstable — API/wire-format may change or be removed without deprecation.
 # No new runtime dependency (pure stdlib + the core `cryptography`); the extra exists to signal

{proofbundle-2.0.0b2 → proofbundle-2.0.0b3}/src/proofbundle/__init__.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-__version__ = "2.0.0b2"
+__version__ = "2.0.0b3"
 
 __all__ = [
     "__version__",

{proofbundle-2.0.0b2 → proofbundle-2.0.0b3}/src/proofbundle/anchors.py

@@ -78,6 +78,15 @@ def _ensure_builtin_types() -> None:
             _VERIFIERS["opentimestamps"] = anchors_ots.verify_opentimestamps
         except Exception:
             pass
+    # chia-datalayer/v1: the first FIRST-PARTY extension anchor. Its offline Merkle verifier (level i) is
+    # PURE SHA-256 — no Chia software, no extra — so it always registers (writing an anchor via anchor-add
+    # needs the [chia] extra + a node, but VERIFYING one offline does not).
+    if "chia-datalayer/v1" not in _VERIFIERS:
+        try:
+            from . import anchors_chia  # noqa: PLC0415
+            _VERIFIERS[anchors_chia.ANCHOR_TYPE] = anchors_chia.verify_chia_datalayer
+        except Exception:   # pragma: no cover - pure module, import should not fail
+            pass
 
 
 def _b64d(value, field: str) -> bytes:
@@ -167,9 +176,9 @@ def verify_anchors(anchors, *, target_roots: dict, require: Optional[str] = None
     if not isinstance(anchors, list):
         raise BundleFormatError("anchors must be a list")
     results = [verify_anchor(a, target_roots=target_roots, now=now) for a in anchors]
-    if require:   # a warn/pending anchor never SATISFIES a requirement — only a real verified one
+    if require:   # a warn/pending/inclusion-only anchor never SATISFIES a requirement — only a full one
         want = None if require == "any" else require
-        matched = [r for r in results if r["ok"] and (want is None or r["type"] == want)]
+        matched = [r for r in results if r["ok"] and not r["warn"] and (want is None or r["type"] == want)]
         if not matched:
             return {"status": "FAIL",
                     "detail": f"--require-anchor {require}: no verifying anchor of that type",

proofbundle-2.0.0b3/src/proofbundle/anchors_chia.py

@@ -0,0 +1,196 @@
+"""Chia DataLayer anchor (``chia-datalayer/v1``) — the first first-party extension anchor type.
+
+This is the **offline Merkle verifier** (level i of the three-level honesty documented in ``docs/ANCHORS.md``):
+it proves, with **pure SHA-256 and NO Chia software**, that a key/value pair is included under a published
+DataLayer root. It does NOT prove the chain binding (that the ``published_root`` is actually an unspent
+singleton on the heaviest chain) — that is level ii (light wallet) / level iii (own full node), which need
+Chia software and are reported separately, never conflated here.
+
+Wire facts (Chia 2.7.x / chia_rs datalayer, pinned in the adapter spec; re-check against the live version
+before trusting — Chia moves modules): a DataLayer ``get_proof`` yields, per key:
+
+    key_clvm_hash  = CLVM tree hash of the key atom   = sha256(0x01 ‖ key_atom)
+    value_clvm_hash= CLVM tree hash of the value atom = sha256(0x01 ‖ value_atom)
+    node_hash (leaf) = sha256(0x02 ‖ key_clvm_hash ‖ value_clvm_hash)
+    internal node    = sha256(0x02 ‖ left ‖ right)
+    ascent: each layer carries other_hash_side (0=LEFT sibling / 1=RIGHT sibling), other_hash, combined_hash
+    root = layers[-1].combined_hash   (or node_hash when layers == [])
+
+The anchor's ``proof`` field (base64 in the bundle, decoded to bytes by ``verify_anchor``) is the **UTF-8 JSON**
+of a proof object with those hex fields; ``canonical_root`` is the ``value_digest`` the anchor stamps.
+
+Fail-closed: any structural problem, hash mismatch, or ascent inconsistency returns ``{"ok": False, ...}``.
+Never raises for an ordinary bad proof.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Optional
+
+ANCHOR_TYPE = "chia-datalayer/v1"
+
+# CLVM tree-hash / node-hash domain-separation prefixes (Chia DataLayer Merkle set).
+_ATOM_PREFIX = b"\x01"   # sha256(0x01 ‖ atom) = CLVM tree hash of an atom
+_NODE_PREFIX = b"\x02"   # sha256(0x02 ‖ left ‖ right) = internal/leaf node hash
+
+_HASH_LEN = 32           # sha256 digest length
+_MAX_LAYERS = 256        # a DataLayer tree of 2**256 leaves is absurd; bound the ascent (DoS guard)
+_MAX_PROOF_BYTES = 131072  # real chia-datalayer proofs are ~2.5 KB; cap the input before json.loads (DoS guard)
+
+
+def _h(*parts: bytes) -> bytes:
+    m = hashlib.sha256()
+    for p in parts:
+        m.update(p)
+    return m.digest()
+
+
+def _hexatom(value, field: str) -> bytes:
+    """Decode an arbitrary-length hex string (optionally 0x-prefixed) to bytes. DataLayer keys/values are
+    atoms of any length — only the HASHES are fixed at 32 bytes (see _hexbytes)."""
+    if not isinstance(value, str):
+        raise ValueError(f"{field} must be a hex string")
+    s = value[2:] if value[:2] in ("0x", "0X") else value
+    return bytes.fromhex(s)   # raises ValueError on non-hex / odd length
+
+
+def _hexbytes(value, field: str) -> bytes:
+    """Decode a 32-byte hash hex string (optionally 0x-prefixed) to bytes, else raise ValueError."""
+    b = _hexatom(value, field)
+    if len(b) != _HASH_LEN:
+        raise ValueError(f"{field} must be {_HASH_LEN} bytes (got {len(b)})")
+    return b
+
+
+def clvm_atom_hash(atom: bytes) -> bytes:
+    """CLVM tree hash of a raw atom: sha256(0x01 ‖ atom). Public helper (Paket 1 anchor-add reuses it)."""
+    return _h(_ATOM_PREFIX, atom)
+
+
+def leaf_node_hash(key_clvm_hash: bytes, value_clvm_hash: bytes) -> bytes:
+    """DataLayer leaf hash: sha256(0x02 ‖ key_clvm_hash ‖ value_clvm_hash)."""
+    return _h(_NODE_PREFIX, key_clvm_hash, value_clvm_hash)
+
+
+def merkle_root_from_layers(node_hash: bytes, inclusion_layers: list) -> bytes:
+    """Recompute the DataLayer root by ascending ``inclusion_layers`` from ``node_hash``.
+
+    Each layer is ``{"other_hash_side": 0|1, "other_hash": hex, "combined_hash": hex}``. ``other_hash_side``
+    is the side of the SIBLING: 0 = sibling on the LEFT → sha256(0x02 ‖ other ‖ cur); 1 = sibling on the
+    RIGHT → sha256(0x02 ‖ cur ‖ other). Each layer's declared ``combined_hash`` MUST equal the recomputed
+    value (fail-closed) — this is what makes the proof self-consistent, not just plausible.
+
+    Returns the root bytes. Raises ValueError on any structural/consistency problem.
+    """
+    if not isinstance(inclusion_layers, list):
+        raise ValueError("inclusion_layers must be a list")
+    if len(inclusion_layers) > _MAX_LAYERS:
+        raise ValueError("inclusion_layers too deep")
+    cur = node_hash
+    for i, layer in enumerate(inclusion_layers):
+        if not isinstance(layer, dict):
+            raise ValueError(f"layer {i} must be an object")
+        side = layer.get("other_hash_side")
+        if side not in (0, 1):
+            raise ValueError(f"layer {i} other_hash_side must be 0 (LEFT) or 1 (RIGHT)")
+        other = _hexbytes(layer.get("other_hash"), f"layer {i} other_hash")
+        declared = _hexbytes(layer.get("combined_hash"), f"layer {i} combined_hash")
+        combined = _h(_NODE_PREFIX, other, cur) if side == 0 else _h(_NODE_PREFIX, cur, other)
+        if combined != declared:
+            raise ValueError(f"layer {i} combined_hash inconsistent with the recomputed hash")
+        cur = combined
+    return cur
+
+
+def verify_offline_merkle(proof_obj: dict, canonical_root: bytes) -> dict:
+    """Pure offline verification (level i). ``proof_obj`` is the decoded chia-datalayer proof dict.
+
+    The BINDING to the target is via the DataLayer KEY: the anchor's ``canonicalRoot`` IS the key stored in
+    the store (``key = canonicalRoot``), so the proof must carry the raw ``key``, it must EQUAL
+    ``canonical_root``, and it must be the atom that hashes (``sha256(0x01‖key)``) to ``key_clvm_hash`` — whose
+    leaf ascends through ``inclusion_layers`` to ``published_root``. This ties ``canonical_root``
+    cryptographically to the Merkle path; an unrelated (even genuine) proof for a DIFFERENT key can no longer
+    be relabelled to this target by swapping a decoupled digest field.
+
+    Checks, all fail-closed:
+      1. raw ``key`` present AND == ``canonical_root`` AND ``sha256(0x01‖key) == key_clvm_hash``
+      2. (optional) raw ``value`` → ``sha256(0x01‖value) == value_clvm_hash``
+      3. leaf ``node_hash == sha256(0x02‖key_clvm‖value_clvm)`` (when declared)
+      4. ascending ``inclusion_layers`` reproduces ``published_root`` (each layer's combined_hash self-consistent)
+
+    Proves ONLY that ``canonical_root`` is a key included under ``published_root``; NOT that ``published_root``
+    is on-chain (that is level ii/iii, needs Chia software — see docs/ANCHORS.md).
+    """
+    try:
+        key_clvm = _hexbytes(proof_obj.get("key_clvm_hash"), "key_clvm_hash")
+        value_clvm = _hexbytes(proof_obj.get("value_clvm_hash"), "value_clvm_hash")
+        published_root = _hexbytes(proof_obj.get("published_root"), "published_root")
+        layers = proof_obj.get("inclusion_layers")
+
+        # (1) BINDING — the raw DataLayer key IS the target canonicalRoot, and it is the atom under key_clvm_hash.
+        raw_key = proof_obj.get("key")
+        if not isinstance(raw_key, str) or not raw_key:
+            return {"ok": False, "detail": "proof missing the raw key (required to bind canonicalRoot to the leaf)"}
+        key_bytes = _hexatom(raw_key, "key")
+        if key_bytes != canonical_root:
+            return {"ok": False, "detail": "the anchored DataLayer key does not equal the target canonicalRoot (cross-target/tampered/forged)"}
+        if clvm_atom_hash(key_bytes) != key_clvm:
+            return {"ok": False, "detail": "key_clvm_hash does not match sha256(0x01 || key)"}
+
+        # (2) optional: raw value atom (ANY length) → value_clvm_hash
+        raw_value = proof_obj.get("value")
+        if isinstance(raw_value, str) and raw_value:
+            if clvm_atom_hash(_hexatom(raw_value, "value")) != value_clvm:
+                return {"ok": False, "detail": "value_clvm_hash does not match sha256(0x01 || value)"}
+
+        # (3) leaf hash
+        leaf = leaf_node_hash(key_clvm, value_clvm)
+        declared_node = proof_obj.get("node_hash")
+        if declared_node is not None and _hexbytes(declared_node, "node_hash") != leaf:
+            return {"ok": False, "detail": "node_hash does not match sha256(0x02 || key_clvm || value_clvm)"}
+
+        # (4) ascend to the root
+        root = merkle_root_from_layers(leaf, layers if layers is not None else [])
+        if root != published_root:
+            return {"ok": False, "detail": "inclusion_layers do not reproduce published_root (not included)"}
+
+    except ValueError as exc:
+        return {"ok": False, "detail": f"malformed chia-datalayer proof: {exc}"}
+    return {"ok": True, "detail": "chia-datalayer merkle: canonicalRoot (as DataLayer key) included under published_root (level i, offline; chain binding NOT checked here)"}
+
+
+def verify_chia_datalayer(proof: bytes, canonical_root: bytes, *, frozen: Optional[dict] = None,
+                          now: Optional[int] = None) -> dict:
+    """Registered anchor verifier for ``chia-datalayer/v1`` (see ``register_anchor_type``).
+
+    ``proof`` is the UTF-8 JSON of the proof object; ``canonical_root`` is the target's root bytes. Returns
+    ``{"ok", "warn", "status", "detail"}``, fail-closed. LEVEL i ONLY: proves the Merkle inclusion under the
+    published root offline; it deliberately does NOT assert the chain binding (an anchor that is Merkle-valid
+    but whose published_root was never on-chain would pass HERE — the honest, documented boundary; a relying
+    party who needs the chain binding runs level ii/iii with Chia software, see docs/ANCHORS.md).
+    """
+    if not isinstance(proof, (bytes, bytearray)):
+        return {"ok": False, "warn": False, "status": "fail", "detail": "chia-datalayer proof must be bytes"}
+    if len(proof) > _MAX_PROOF_BYTES:
+        return {"ok": False, "warn": False, "status": "fail", "detail": f"chia-datalayer proof too large (> {_MAX_PROOF_BYTES} bytes)"}
+    # Unconditional fail-closed backstop: a verifier must NEVER crash its caller on a hostile proof. Enumerating
+    # exception types (ValueError, ...) misses RecursionError (deeply nested JSON), MemoryError, or a TypeError
+    # from a non-bytes canonical_root — all of which a caller-controlled proof could trigger. Catch everything.
+    try:
+        proof_obj = json.loads(bytes(proof).decode("utf-8"))
+        if not isinstance(proof_obj, dict):
+            return {"ok": False, "warn": False, "status": "fail", "detail": "chia-datalayer proof JSON must be an object"}
+        res = verify_offline_merkle(proof_obj, bytes(canonical_root))
+    except Exception as exc:   # noqa: BLE001 - deliberate fail-closed backstop for ANY hostile input
+        return {"ok": False, "warn": False, "status": "fail", "detail": f"chia-datalayer proof rejected (fail-closed): {type(exc).__name__}"}
+    if not bool(res.get("ok")):
+        return {"ok": False, "warn": False, "status": "fail", "detail": res.get("detail", "")}
+    # LEVEL i is proven (offline Merkle inclusion) → ok=True. But level i is NOT external time / chain-binding
+    # evidence: a self-fabricated tree with a never-on-chain published_root passes here (the documented
+    # boundary). So this is marked warn=True (status 'warn'), exactly like an un-upgraded OpenTimestamps
+    # PENDING proof — it must NOT satisfy --require-anchor and it aggregates as WARN, never a clean PASS that
+    # would read as a full external-time anchor. A relying party who needs the chain binding runs level
+    # ii/iii with Chia software (see docs/ANCHORS.md); the require-matcher gates on ok AND NOT warn.
+    return {"ok": True, "warn": True, "status": "warn", "detail": res.get("detail", "")}

proofbundle-2.0.0b3/src/proofbundle/anchors_chia_add.py

@@ -0,0 +1,154 @@
+"""chia-datalayer/v1 anchor WRITER / EXPORTER (Paket 1) — needs the ``[chia]`` extra + a reachable Chia
+DataLayer node (this is the ONLY chia-dependent part; VERIFYING an anchor offline needs neither, see
+``anchors_chia.py``).
+
+``export_anchor`` turns an existing (store, key) into a portable ``chia-datalayer/v1`` anchor dict whose
+offline proof ``verify_chia_datalayer`` accepts. ``anchor_add`` is the full flow: insert the digest, wait
+for on-chain confirmation, then export. A NETWORK/NODE FAILURE NEVER DAMAGES ANYTHING — ``anchor_add``
+returns the new anchor or raises cleanly; it never writes a partial/half-anchor.
+
+Access is via the stable ``chia rpc data_layer|full_node <method> '<json>'`` subprocess surface (the Python
+imports move between Chia versions; the JSON-RPC wire is stable). RPC is local + cert-authed; never exposed.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import shutil
+import subprocess
+import time
+from typing import Optional
+
+from .anchors_chia import ANCHOR_TYPE, verify_offline_merkle
+
+_CHIA_BIN = os.getenv("CHIA_CLI", shutil.which("chia") or "chia")
+
+
+class ChiaRpcError(RuntimeError):
+    """A Chia RPC/CLI call failed. Fail-closed: the caller aborts, no partial anchor is written."""
+
+
+def _rpc(service: str, method: str, payload: dict, *, timeout: int = 60) -> dict:
+    """Call ``chia rpc <service> <method> '<json>'`` and return the parsed dict. Raises ChiaRpcError on
+    any failure (missing binary, timeout, non-zero exit, non-JSON, ``success:false``)."""
+    try:
+        proc = subprocess.run(
+            [_CHIA_BIN, "rpc", service, method, json.dumps(payload)],
+            capture_output=True, text=True, timeout=timeout, check=False,
+        )
+    except FileNotFoundError as exc:
+        raise ChiaRpcError(f"chia binary not found ({_CHIA_BIN}); install proofbundle[chia] + a node") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise ChiaRpcError(f"chia rpc {service} {method} timed out") from exc
+    if proc.returncode != 0:
+        raise ChiaRpcError(f"chia rpc {service} {method} exit {proc.returncode}: {(proc.stderr or proc.stdout)[:200]}")
+    try:
+        data = json.loads(proc.stdout)
+    except ValueError as exc:
+        raise ChiaRpcError(f"chia rpc {service} {method}: non-JSON response") from exc
+    if isinstance(data, dict) and data.get("success") is False:
+        raise ChiaRpcError(f"chia rpc {service} {method}: {data.get('error', 'success=false')}")
+    return data
+
+
+def _hx(b: bytes) -> str:
+    return "0x" + b.hex()
+
+
+def export_anchor(store_id: str, *, canonical_root: bytes, target: str = "receipt",
+                  network: str = "mainnet", value: Optional[str] = None) -> dict:
+    """Build a ``chia-datalayer/v1`` anchor from live ``get_proof`` + ``get_root`` (+ best-effort
+    ``get_coin_record`` for height/timestamp). The DataLayer KEY IS the target's ``canonical_root`` (that is
+    the whole binding — see anchors_chia.verify_offline_merkle), so the key is derived here, never passed in
+    independently. Returns the anchor dict (self-verifying offline before emit). Fail-closed.
+    """
+    key = _hx(bytes(canonical_root))   # key == canonicalRoot: the binding the verifier enforces
+    gp = _rpc("data_layer", "get_proof", {"store_id": store_id, "keys": [key]})
+    proofs = ((gp.get("proof") or {}).get("store_proofs") or {}).get("proofs") or []
+    if not proofs:
+        raise ChiaRpcError("get_proof returned no proof for the key (not in the store / not confirmed)")
+    pr = proofs[0]
+    root_resp = _rpc("data_layer", "get_root", {"id": store_id})
+    published_root = root_resp.get("hash")
+    if not published_root or set(published_root.replace("0x", "")) == {"0"}:
+        raise ChiaRpcError("store has no confirmed published root yet")
+
+    coin_id = (gp.get("proof") or {}).get("coin_id")
+    inner_puzzle_hash = (gp.get("proof") or {}).get("inner_puzzle_hash")
+    block_height = None
+    root_timestamp = None
+    if coin_id:                                   # best-effort: height + timestamp from the full node (Stufe iii material)
+        try:
+            cr = _rpc("full_node", "get_coin_record_by_name", {"name": coin_id}, timeout=20)
+            rec = cr.get("coin_record") or {}
+            block_height = rec.get("confirmed_block_index")
+            root_timestamp = rec.get("timestamp")
+        except ChiaRpcError:
+            pass                                  # height/timestamp are Stufe-iii extras; absence is not fatal
+
+    proof_obj = {
+        "store_id": store_id, "key": key,   # key == canonicalRoot (the binding)
+        "key_clvm_hash": pr["key_clvm_hash"], "value_clvm_hash": pr["value_clvm_hash"],
+        "node_hash": pr["node_hash"], "inclusion_layers": pr.get("layers", []),
+        "published_root": published_root,
+        "coin_id": coin_id, "inner_puzzle_hash": inner_puzzle_hash,
+        "block_height": block_height, "root_timestamp": root_timestamp, "network": network,
+    }
+    if value is not None:
+        proof_obj["value"] = value if value.startswith(("0x", "0X")) else "0x" + value
+
+    # self-check BEFORE returning: an exported anchor MUST verify offline, else we never emit it (No-Fake).
+    chk = verify_offline_merkle(proof_obj, bytes(canonical_root))
+    if not chk.get("ok"):
+        raise ChiaRpcError(f"exported anchor failed its own offline verification: {chk.get('detail')}")
+
+    return {
+        "type": ANCHOR_TYPE, "target": target,
+        "canonicalRoot": base64.b64encode(bytes(canonical_root)).decode(),
+        "proof": base64.b64encode(json.dumps(proof_obj).encode()).decode(),
+    }
+
+
+def _wait_confirmed(store_id: str, prev_root: Optional[str], *, timeout: int = 180, poll: int = 5) -> None:
+    """Block until the store's published root advances past ``prev_root`` (the batch_update confirmed).
+    Raises ChiaRpcError on timeout. ``poll`` uses monotonic sleep; no busy loop."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        root = _rpc("data_layer", "get_root", {"id": store_id}).get("hash")
+        if root and root != prev_root and set(root.replace("0x", "")) != {"0"}:
+            return
+        time.sleep(poll)
+    raise ChiaRpcError("timed out waiting for the batch_update root to confirm on-chain")
+
+
+def anchor_add(canonical_root_hex: str, *, store_id: str, value_digest_hex: Optional[str] = None,
+               target: str = "receipt", network: str = "mainnet", fee: int = 100_000_000,
+               wait: bool = True) -> dict:
+    """Full flow: insert ``key=canonicalRoot`` (value = ``value_digest`` or the canonicalRoot itself) into the
+    store, wait for on-chain confirmation, then export the anchor. Idempotent: a key already present ("Key
+    already present") is treated as "already anchored" and re-exported, not an error. Fail-closed: a network
+    failure raises ChiaRpcError and writes NOTHING partial (the caller keeps its receipt untouched)."""
+    canonical_root_hex = canonical_root_hex if canonical_root_hex.startswith(("0x", "0X")) else "0x" + canonical_root_hex
+    canonical_root = bytes.fromhex(canonical_root_hex[2:])
+    if len(canonical_root) != 32:
+        raise ValueError("canonical_root must be a 32-byte hex digest")
+    value_hex = value_digest_hex or canonical_root_hex
+    value_hex = value_hex if value_hex.startswith(("0x", "0X")) else "0x" + value_hex
+
+    prev_root = _rpc("data_layer", "get_root", {"id": store_id}).get("hash")
+    changelist = [{"action": "insert", "key": canonical_root_hex, "value": value_hex}]
+    already = False
+    try:
+        _rpc("data_layer", "batch_update",
+             {"id": store_id, "changelist": changelist, "fee": fee, "submit_on_chain": True})
+    except ChiaRpcError as exc:
+        if "already present" in str(exc).lower():
+            already = True                        # idempotent: the digest is already anchored
+        else:
+            raise                                 # any other failure → clean abort, nothing written
+    if wait and not already:
+        _wait_confirmed(store_id, prev_root)
+    return export_anchor(store_id, canonical_root=canonical_root,
+                         target=target, network=network, value=value_hex)

proofbundle-2.0.0b3/src/proofbundle/anchors_markovian.py

@@ -0,0 +1,121 @@
+"""Markovian provenance anchor (EXPERIMENTAL; third-party extension example for docs/ANCHORS.md).
+
+A worked example of a *third-party* anchor ``type`` registered through
+:func:`proofbundle.anchors.register_anchor_type`. It shows how an outside protocol plugs its own
+evidence into the generic ``anchors[]`` layer without touching proofbundle's core, and it is deliberately
+NOT wired into the built-in set (``_ensure_builtin_types``) — a third-party type is opt-in by design.
+
+**What it proves.** A ``markovian-provenance/v1`` stamp is an *issuer-attributable* commitment: it binds
+the committed data to a wallet via ``merkle_root = sha256(data_hash ":" salt ":" wallet)``, and the data
+itself is Bitcoin-anchored with OpenTimestamps. A verified anchor therefore says: *the target canonical
+root was committed by wallet W and existed by the OTS-attested Bitcoin block time.* The time is trustless
+(Bitcoin); the issuer binding is self-consistent inside the stamp envelope.
+
+**Composition, not reinvention.** The Bitcoin time proof is delegated verbatim to the built-in
+``opentimestamps`` verifier (:func:`proofbundle.anchors_ots.verify_opentimestamps`), inheriting its exact
+fail-closed lifecycle (PENDING -> WARN; upgraded-without-header -> honest not-pass; upgraded + supplied
+block header -> confirmed). This type only adds the Markovian envelope checks on top; it never
+re-implements the Bitcoin discipline.
+
+``proof`` is UTF-8 JSON: ``{schema, data_hash, salt, wallet, merkle_root, zk_commitment?, block_height?,
+stamped_at?, ots}`` where ``ots`` is base64 of the detached OpenTimestamps proof over the canonical root.
+``canonicalRoot`` is the exact bytes the stamp committed (the stamp's ``data_hash``).
+
+Register it explicitly (that it is not a core built-in is the point of a third-party type)::
+
+    from proofbundle.anchors_markovian import register
+    register()   # anchors[] entries with type "markovian-provenance/v1" now verify
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import json
+from typing import Optional
+
+ANCHOR_TYPE = "markovian-provenance/v1"
+
+
+def _fail(status: str, detail: str) -> dict:
+    return {"ok": False, "warn": False, "status": status, "detail": detail}
+
+
+def verify_markovian(proof: bytes, canonical_root: bytes, *, frozen: dict,
+                     now: Optional[int] = None) -> dict:
+    """Fail-closed verifier for a ``markovian-provenance/v1`` anchor. Returns {ok, warn, status, detail}.
+
+    Steps (any doubt -> not ok; never raises for an ordinary bad proof):
+      1. parse the JSON envelope;
+      2. schema is ``markovian-provenance/v1``;
+      3. binding: ``data_hash`` equals the target ``canonical_root`` (hex);
+      4. envelope integrity: ``merkle_root == sha256(data_hash ":" salt ":" wallet)`` (wallet bound to data);
+      5. Bitcoin time: delegate the embedded OTS proof to the built-in opentimestamps verifier.
+    The final status/warn mirror the OTS verifier (pending / upgraded_unverified / confirmed); a PASS also
+    names the committing wallet and Markovian chain height.
+    """
+    # 1. parse
+    try:
+        env = json.loads(proof.decode("utf-8"))
+        if not isinstance(env, dict):
+            raise ValueError("envelope is not a JSON object")
+    except (UnicodeDecodeError, ValueError) as exc:
+        return _fail("malformed", f"markovian proof is not valid JSON: {exc}")
+
+    # 2. schema
+    if env.get("schema") != ANCHOR_TYPE:
+        return _fail("bad_schema", f"markovian proof schema must be {ANCHOR_TYPE!r}")
+
+    data_hash = env.get("data_hash")
+    salt = env.get("salt")
+    wallet = env.get("wallet")
+    merkle_root = env.get("merkle_root")
+    ots_b64 = env.get("ots")
+    for name, val in (("data_hash", data_hash), ("salt", salt), ("wallet", wallet),
+                      ("merkle_root", merkle_root), ("ots", ots_b64)):
+        if not isinstance(val, str) or not val:
+            return _fail("bad_fields", f"markovian envelope field {name!r} missing or not a string")
+    # the loop above guarantees these are non-empty str; narrow explicitly so the type checker follows
+    assert isinstance(data_hash, str) and isinstance(ots_b64, str)
+
+    # 3. binding: the stamp must commit to EXACTLY the target canonical root
+    try:
+        if bytes.fromhex(data_hash) != canonical_root:
+            return _fail("unbound", "markovian data_hash does not match the target canonical root")
+    except ValueError:
+        return _fail("bad_fields", "markovian data_hash is not valid hex")
+
+    # 4. envelope integrity: the wallet is bound to the data inside the stamp
+    recomputed = hashlib.sha256(f"{data_hash}:{salt}:{wallet}".encode("utf-8")).hexdigest()
+    if recomputed != merkle_root:
+        return _fail("envelope_mismatch",
+                     "markovian merkle_root != sha256(data_hash:salt:wallet) — envelope inconsistent/tampered")
+
+    # 5. Bitcoin time: delegate to the built-in OpenTimestamps verifier (compose, don't reinvent)
+    try:
+        ots_proof = base64.b64decode(ots_b64, validate=True)
+    except (ValueError, binascii.Error):
+        return _fail("bad_fields", "markovian ots field is not valid base64")
+    try:
+        from .anchors_ots import verify_opentimestamps  # noqa: PLC0415
+    except ImportError:
+        return _fail("no_lib",
+                     "markovian anchor needs proofbundle[anchors] (opentimestamps) for the Bitcoin proof")
+
+    ots_res = verify_opentimestamps(ots_proof, canonical_root, frozen=frozen, now=now)
+    who = f"Markovian wallet {wallet}"
+    chain = env.get("block_height")
+    chain_part = f", Markovian chain block {chain}" if chain is not None else ""
+    if ots_res.get("ok"):
+        return {"ok": True, "warn": False, "status": "confirmed",
+                "detail": f"canonical root committed by {who}{chain_part}; {ots_res.get('detail', '')}"}
+    # not a full anchor yet — carry the OTS lifecycle status/warn verbatim, framed as Markovian
+    return {"ok": False, "warn": bool(ots_res.get("warn")), "status": ots_res.get("status", "fail"),
+            "detail": f"markovian stamp envelope valid ({who}{chain_part}) but Bitcoin proof not verified: "
+                      f"{ots_res.get('detail', '')}"}
+
+
+def register() -> None:
+    """Register this third-party type so ``anchors[]`` entries of type ``markovian-provenance/v1`` verify."""
+    from .anchors import register_anchor_type  # noqa: PLC0415
+    register_anchor_type(ANCHOR_TYPE, verify_markovian)