dig-did

The DIG Network canonical Chia DID expert crate — a pure, key-free, network-free SpendBundle-builder for Chia Decentralized Identifiers (DIDs).

dig-did constructs the exact CoinSpends for every DID lifecycle operation and reports the exact signatures a caller must produce. It never holds a secret key, never signs, and never touches the network. You build an unsigned spend, ask dig-did what must be signed, sign it with your own signer, assemble the SpendBundle, and broadcast.

This crate is built to a normative spec — see SPEC.md for the full contract an independent reimplementation could be built against.

[dependencies]
dig-did = "0.2"

Invariants

• INV-1 — No network. No network or chain I/O. Every function is a pure transform; you fetch coins and broadcast bundles.
• INV-2 — No keys. dig-did never accepts, holds, derives, or logs a secret key. No function takes a SecretKey.
• INV-3 — Unsigned output. Every operation returns an unsigned DidSpend. Signing is always yours.
• INV-4 — SDK byte-source-of-truth. Every puzzle/spend byte comes from chia-wallet-sdk (pinned to the 0.34 / chia-protocol 0.36 family). dig-did adds DID-workflow ergonomics; it never re-implements a puzzle or hand-rolls a spend bundle.

The consumer pattern

build an unsigned DidSpend
   -> required_signatures(&spend.coin_spends, &constants)
   -> your signer signs each reported message
   -> assemble a SpendBundle (coin_spends + aggregated signature)
   -> broadcast

DidSpend { coin_spends: Vec<CoinSpend>, child: Option<Did> } is the output of every operation: the unsigned coin spends plus the DID as it will exist after they confirm (child is None for a terminal operation such as a melt).

Owner says who is authorized to spend a DID:

• Owner::Standard(PublicKey) — the standard single-key p2 puzzle; dig-did builds the layer for you.
• Owner::Custom(Spend) — you supply an already-built inner spend for any custom p2 puzzle. Note: operations that compute conditions of their own (create, settle, spend-with-conditions) refuse Custom with DidError::UnsupportedOwner; see SPEC §2.4 and spend_did_with_conditions.

Creating a DID

use dig_did::{create_simple_did, did_string_from_launcher_id, Owner};
use chia_wallet_sdk::driver::SpendContext;

let ctx = &mut SpendContext::new();

// `funding_coin` must be owned by the same key/spend as `owner` (fetched from your own coin store).
let spend = create_simple_did(ctx, funding_coin, Owner::Standard(owner_public_key))?;

let did = spend.child.expect("create always returns a child DID");
println!("minted {}", did_string_from_launcher_id(did.info.launcher_id));

// spend.coin_spends now holds the funding + launcher + settle spends, unsigned (INV-3).

Owner::Custom cannot be used with create_did, create_simple_did, or create_eve_did_only. Those functions compute launcher conditions internally; a pre-built inner spend emits one fixed condition set and cannot carry them. Passing Owner::Custom to any of these returns DidError::UnsupportedOwner. Use Owner::Standard(public_key) for all create paths. If you need a custom p2 puzzle on an already-launched DID, use spend_did_with_conditions (which also refuses Custom — supply the spend directly) or Launcher::create_eve_did from chia-wallet-sdk.

The signing boundary

use dig_did::{required_signatures, AggSigConstants, RequiredSignature};
use chia_wallet_sdk::prelude::MAINNET_CONSTANTS;

// `coin_spends` came from a dig-did operation (e.g. create/update/transfer).
let constants = AggSigConstants::from(&*MAINNET_CONSTANTS);
let required: Vec<RequiredSignature> = required_signatures(&coin_spends, &constants)?;

for sig in &required {
    match sig {
        RequiredSignature::Bls(bls) => {
            let message = bls.message();     // the exact bytes to sign
            let public_key = &bls.public_key; // the key to sign them under
            // your signer produces the BLS signature here — dig-did never does
        }
        RequiredSignature::Secp(_) => { /* handle secp requirements if your p2 uses them */ }
    }
}

required_signatures runs each coin spend to collect its AGG_SIG_* conditions and returns the precise set — public key, raw message, appended coin/domain info. It is pure and key-free; it never takes a secret key. Owner operations require AGG_SIG_ME (bound to the specific coin), never an AGG_SIG_UNSAFE over caller bytes.

Operation surface

The full DID lifecycle (see SPEC.md §3 for field-level detail). Each operation returns Result<DidSpend, DidError>; a standard-owner operation requires one AGG_SIG_ME over the owner key unless noted.

Status: 0.4 adds the DID→XCH address resolver (resolve_xch_address + resolve_xch_address_from_did_string, SPEC.md §3/§6) and migrates the ChainSource seam onto the canonical dig-chainsource-interface crate (the one non-drifting trait, re-exported so the public paths are unchanged). 0.3 added the lineage-proof spine — the ChainSource seam, prove_lineage + AncestryProof, and walk_did_lineage_to_tip (SPEC.md §5.1/§10) — on top of 0.2 (creation + hydration + did:chia: codec) and the 0.1 foundation (type surface, error taxonomy, signing boundary). The remaining operation modules above are declared and specified; each lands in its own release against this foundation. The table documents the complete designed interface.

Types

• Did, DidInfo — the DID singleton and its info (re-exported from chia-wallet-sdk).
• DidSpend — { coin_spends, child }, the unsigned output of every operation.
• Owner — Standard(PublicKey) | Custom(Spend). Operations that compute conditions internally (create, settle, spend-with-conditions) require Standard and return DidError::UnsupportedOwner for Custom (SPEC §2.4).
• DidError / DidResult<T> — the error taxonomy (SPEC.md §6).
• AggSigConstants, RequiredSignature — re-exported so you can call and consume required_signatures without a direct chia-wallet-sdk dependency.
• ChainSource / SingletonLineage — re-exported from the canonical dig-chainsource-interface crate: the caller-supplied honest chain reader (see SPEC.md §10) + a singleton's lineage (membership + tip).
• Address — re-exported bech32m address codec (chia-sdk-utils), for rendering/decoding a resolved XCH payment address.
• AncestryProof / LineageModel — the unforgeable output of prove_lineage (Direct | LaunchedFrom).
• DidTip — a DID singleton's reconstructed current tip.
• Coin, CoinSpend, Bytes32, Proof, LineageProof — re-exported Chia wire types.

Module map

Security

dig-did holds no key and signs nothing (INV-2). Its whole job is to build correct unsigned spends and tell you exactly what to sign. AGG_SIG_ME binds each owner signature to its coin (no replay); hydration is fail-closed (ambiguous chain data is an error, never a guess). See SPEC.md §7.

License

Licensed under either of Apache-2.0 or MIT at your option.