Skip to main content

Crate dig_merkle

Crate dig_merkle 

Source
Expand description

§dig-merkle — the DIG Network canonical CHIP-0035 DataLayer coin expert crate

dig-merkle is a pure, key-free, network-free SpendBundle-builder for the Chia CHIP-0035 DataLayer singleton that anchors a .dig file’s merkle root on-chain. It constructs the exact CoinSpends for every DataLayer-coin lifecycle operation and reports — via required_signatures — the exact signatures a caller must produce. It never holds a secret key, never signs, and never touches the network. The consumer signs the reported messages, assembles the SpendBundle, and broadcasts.

§The DataLayer coin

A DataLayer coin is a CHIP-0035 singleton whose launcher_id IS the DIG store_id. Its DatastoreMetadata carries the capsule’s root_hash (the anchored .dig merkle root) plus optional label/description/size_proof, the additive program_hash ("p"), and the store size as a power-of-2 size_bucket ("sz" — see SizeBucket) that REPLACES the SDK’s exact bytes/"b" field, and its DelegatedPuzzle list grants admin/writer/oracle authority. Spending the coin recreates it with a new root, transferring ownership, delegating write access, or melting it. dig-merkle builds each such spend unsigned.

§Invariants

These four invariants hold across the entire crate and are the contract every unit is built to (SPEC §1):

  • INV-1 — No network. dig-merkle performs NO network or chain I/O. Every function is a pure transform of its inputs; the caller fetches coins and broadcasts bundles.
  • INV-2 — No keys. dig-merkle never accepts, holds, derives, or logs a secret key. It computes what must be signed (required_signatures); the caller’s signer produces the signatures.
  • INV-3 — Unsigned output. Every operation returns an unsigned MerkleCoinSpend — coin spends plus the recreated child Datastore. Signatures are always the caller’s responsibility.
  • INV-4 — SDK byte-source-of-truth. Every puzzle, layer, and coin-spend byte is produced by chia-wallet-sdk (pinned to the 0.30 / chia-protocol 0.26 family, chip-0035 feature). dig-merkle adds DataLayer-workflow ergonomics on top; it never re-implements a puzzle or hand-rolls a spend bundle, and re-exports the SDK’s Datastore types verbatim.

§Consumer pattern

build an unsigned MerkleCoinSpend  ->  required_signatures(&spend.coin_spends, &constants)
  ->  caller signs each reported message  ->  assemble SpendBundle  ->  broadcast

§Operation surface

On the foundation (the type surface MerkleCoinSpend/Owner + re-exported SDK Datastore types, the error taxonomy MerkleError, the inner-spend helpers, and the signing boundary required_signatures) the crate ships the DataLayer-coin lifecycle:

delegation, oracle, and fee remain doc-only stubs, landing in their own units.

Re-exports§

pub use error::MerkleError;
pub use error::MerkleResult;
pub use hint::digstore_owner_hint;
pub use hint::from_launcher_hint;
pub use hint::launcher_hint_for;
pub use hint::StoreKind;
pub use hint::DATASTORE_LAUNCHER_HINT;
pub use hint::DID_PROFILE_LAUNCHER_HINT;
pub use hint::DIGSTORE_OWNER_HINT_DOMAIN;
pub use hydrate::hydrate;
pub use lineage::child_lineage_proof;
pub use melt::melt;
pub use metadata::DigDataStoreMetadata;
pub use mint::mint_datastore;
pub use mint::mint_datastore_launch_with_kind;
pub use mint::mint_datastore_with_kind;
pub use mint::DatastoreLaunch;
pub use read::did_ref_from_spend;
pub use read::resolve_owner_did;
pub use read::DidRef;
pub use sign::required_signatures;
pub use size::SizeBucket;
pub use types::MerkleCoinSpend;
pub use types::Owner;
pub use update::update_root;

Modules§

delegation
Grant or revoke admin/writer/oracle crate::DelegatedPuzzle authority (future unit, SPEC §3.3).
error
The dig-merkle error taxonomy (SPEC §6).
fee
Attach a reserve fee condition to any DataLayer operation (future unit, SPEC §3).
hint
The DataLayer coin owner-discovery hint (SPEC §9) — a self-contained, byte-identical contract.
hydrate
Reconstructing a spendable DataLayer coin from its parent spend (SPEC §5) — fail-closed.
lineage
DataLayer-coin lineage proofs (SPEC §5) — the proof a child singleton spend requires.
melt
The DataLayer-coin melt builder (SPEC §3.5) — terminally spend the coin, leaving no successor.
metadata
The DIG DataLayer metadata (SPEC §2) — the SDK’s DatastoreMetadata shape with the exact-byte "b" size REPLACED by a power-of-2 size_bucket ("sz"), plus the additive program_hash ("p").
mint
The DataLayer-coin mint builder (SPEC §3.1) — launch a new store singleton anchoring a root.
oracle
Spend the oracle delegated puzzle to read the coin for a fee (future unit, SPEC §3.4).
read
Reading on-chain DataLayer state without spending (SPEC §3.6/§3.7) — owner-DID discovery.
sign
The signing boundary (SPEC §4) — the load-bearing custody guarantee of dig-merkle.
size
The .dig store size as a power-of-2 bucket (SPEC §2, CLVM alist key "sz").
types
The public type surface of dig-merkle (SPEC §2).
update
The DataLayer-coin update builder (SPEC §3.2) — recreate the coin anchoring a new root.

Structs§

AggSigConstants
Coin
CoinSpend
Conditions
A grow-only list of conditions which can be used when building spend bundles.
Datastore
Everything that is required to spend a Datastore coin.
DatastoreInfo
DatastoreMetadata
IntermediateLauncher
An intermediate launcher is a coin that is created prior to the actual launcher coin. In this case, it automatically creates the launcher coin upon being spent.
Launcher
A singleton launcher is a coin that is spent within the same block to create a singleton. The first coin that is created is known as an “eve” singleton. The Launcher type allows you to get the launcher id before committing to creating the singleton.
LineageProof
SpendContext
A wrapper around Allocator that caches puzzles and keeps track of a list of CoinSpend. It’s used to construct spend bundles in an easy and efficient way.

Enums§

DelegatedPuzzle
Proof
RequiredSignature

Type Aliases§

Bytes32