Enum DidError 

#[non_exhaustive]
pub enum DidError {
    Driver(DriverError),
    Signer(String),
    Parse(String),
    NotDid,
    NotTheOwner,
    InvalidDidString(String),
    UnsupportedOwner(&'static str),
    EvenSingletonAmount(u64),
    OddAmountCreateCoin,
    AggSigUnsafeInConditions,
    NonCanonicalCreateCoinAmount(String),
    DisallowedCondition(String),
    InvalidRecovery(String),
    MissingLineage,
    MissingHint,
    Chain(String),
    NoIdentitySingleton,
    NotASingleton,
    NotDidRooted,
    LauncherMismatch,
    LineageTooDeep,
}

Everything that can go wrong while building or parsing a DID spend.

The variants split into two families: errors delegated to the chia-wallet-sdk driver/signer (wrapped verbatim so the underlying cause is never lost), and DID-domain errors this crate raises itself (parse/hydration/codec guards, all fail-closed per SPEC §5).

Marked #[non_exhaustive]: this taxonomy grows whenever a new fail-closed guard is added, and every such addition would otherwise be a breaking change for any downstream exhaustive match. Downstream code must carry a _ arm. dig-account’s AccountError is #[non_exhaustive] for the same reason; the two now agree.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Driver(DriverError)

A chia-wallet-sdk driver operation failed (puzzle currying, spend construction, CLVM evaluation). The wrapped DriverError carries the precise cause.

Signer(String)

The signing calculator failed to derive the required signatures from the coin spends (invalid puzzle/solution, an infinity public key in an AGG_SIG condition). The message is the underlying signer error rendered as a string, so this crate does not leak the signer’s error type into its public surface.

Parse(String)

A coin/puzzle/solution could not be parsed as the expected shape.

NotDid

The supplied puzzle parsed successfully but is not a DID singleton.

NotTheOwner

The caller could not prove it controls the DID: the supplied crate::Owner key does not curry to the DID’s current p2_puzzle_hash.

Raised by irreversible operations — [crate::melt] — before any spend is built. Such a spend could never confirm (the caller cannot produce its AGG_SIG_ME), but a melt is unrecoverable, so authority is refused up front rather than discovered at signing time (SPEC §5, fail-closed).

InvalidDidString(String)

A did:chia:1… string was malformed or failed bech32m decoding.

UnsupportedOwner(&'static str)

The operation cannot honour the crate::Owner variant it was given, because it must add conditions of its own and a caller-supplied pre-built inner spend emits one fixed condition set. Rather than silently dropping those conditions — which yields a well-formed bundle that creates none of the coins it reports — the operation refuses. The message names the alternative the caller should use instead (SPEC §5, fail-closed).

EvenSingletonAmount(u64)

A funding coin with an EVEN amount was supplied to a DID launch. The u64 is that amount.

Chia’s singleton top layer recognises only the launcher’s ODD-amount output as the singleton, and this crate’s launch gives the singleton the funding coin’s entire amount. An even-amount funding coin therefore produces a bundle that spends the money and creates no DID at all — a total, silent loss of the funding coin, not a rejected spend. Arbitrary wallet coins are even about half the time.

Split the funding coin down to exactly the odd amount the singleton should carry first (dig-account splits to 1 mojo) and pass that coin (SPEC §3, fail-closed).

OddAmountCreateCoin

A caller supplied an odd-amount CREATE_COIN to a DID-preserving spend. A singleton’s inner puzzle may emit exactly ONE odd-amount CREATE_COIN, and the DID’s own recreation occupies it, so a caller’s odd-amount CREATE_COIN can never be valid here — most often an attempt to parent a foreign singleton launcher (an amount-1 coin) to the DID coin.

Refused at build time because the alternative is opaque: the bundle would assemble and report a child DID, then be rejected at mempool admission. It never enters a block, so no fee is paid — but the caller pays a wasted round-trip and gets no explanation. Parent the launcher to an ordinary coin instead and bind it to the DID by an announcement this spend asserts, or by the launched singleton’s owner puzzle hash (SPEC §5, fail-closed).

AggSigUnsafeInConditions

A caller supplied an AGG_SIG_UNSAFE requirement in the conditions of a DID spend.

Unlike every other AGG_SIG_* condition, AGG_SIG_UNSAFE is signed with no coin binding and no domain separation — the signed message is the caller’s bytes verbatim. A DID owner induced to sign one produces a permanent, replayable assertion under their identity key, reusable in any spend or challenge-response the attacker later constructs. Since this crate’s contract is that the caller signs every message required_signatures reports, such a requirement is never legitimate in a DID spend and is refused (SPEC §5, fail-closed).

This refusal removes the UNBOUNDED shape, not every shape whose damage outlives the bundle. A permitted AGG_SIG_PARENT also outlives it: that signature is bound to the DID coin’s PARENT id, so it stays satisfiable by any future spend of any coin sharing that parent — the other outputs of the DID’s PREVIOUS spend, not anything this spend creates. That set was fixed before this spend was built and MAY include a coin an earlier caller paid to a third party, under a puzzle that third party chose. What the refusal buys is a BOUND, not an end to persistence: unlike AGG_SIG_UNSAFE, a permitted signature can never reach a later generation of the DID and can never become an off-domain assertion.

Nor does it make a hostile condition set safe. The permitted shapes still move the caller’s own bundled funds to caller-chosen puzzle hashes and still emit announcements under the DID’s authority. A caller composing conditions from an untrusted source MUST review the bundle before signing — and, where an AGG_SIG_PARENT is present, MUST also account for what the DID’s PREVIOUS spend created, which this bundle does not show.

NonCanonicalCreateCoinAmount(String)

A caller supplied a CREATE_COIN whose amount atom is not chia’s canonical integer encoding.

CLVM integers are SIGNED and chia additionally requires a canonical encoding, but the typed CreateCoin::amount this crate’s allowlist reads is a u64 decoded from the atom UNSIGNED. The two disagree on exactly the encodings chia refuses: a leading byte with the sign bit set (0x80 reads as 128, chain says CoinAmountNegative), a redundant leading zero (0x000002 reads as 2, chain says InvalidCoinAmount), and an atom with more bytes than the value needs (chain says the amount overflows). Such a spend assembles here, reports a child DID, and is then dropped at mempool admission telling the caller nothing — the opaque failure this guard exists to prevent.

The rule mirrors chia’s sanitize_uint exactly, so it can refuse nothing the chain would accept (SPEC §5, fail-closed).

DisallowedCondition(String)

A caller supplied a condition that is not on the allowlist of shapes a DID-preserving spend may carry. The string renders the offending condition.

The guard is an allowlist rather than a list of refusals for a structural reason: chia_sdk_types::Condition is #[non_exhaustive] and carries a catch-all Other variant that serializes to CLVM verbatim, so any caller can hand a refused condition over under a name a denylist does not recognise while the chain still sees the condition itself. Only a guard that refuses everything it does not explicitly permit can fail closed — and it stays closed when a future SDK release adds a variant nobody here has considered (SPEC §5).

InvalidRecovery(String)

A recovery operation supplied an inconsistent recovery configuration (list hash / required verifications mismatch).

MissingLineage

Hydration could not establish the lineage proof required to spend the DID (SPEC §5, fail-closed).

MissingHint

A parsed DID coin was missing the owner hint memo required to recreate its child (SPEC §5, fail-closed).

Chain(String)

A chain-level precondition was violated (e.g. a supplied coin does not match the expected launcher). The string states the specific violation. Also carries a crate::resolve::ChainSource read error verbatim — a failed read NEVER degrades to “assume owned” (SPEC §5, fail-closed).

NoIdentitySingleton

The DID’s identity singleton has no current on-chain coin — it was never launched, or has been melted, so there is no lineage to root a coin against (SPEC §5, fail-closed).

NotASingleton

The coin under proof could not be authenticated as a genuine singleton: its parent-spend chain does not resolve to a singleton launcher (an ordinary payment/change coin, or a pay-to coin that merely wears a singleton puzzle hash without a genuine recreation parent spend). SPEC §5.

NotDidRooted

The coin authenticates as a genuine singleton, but neither IS the DID singleton nor was launched from a coin in the DID singleton’s lineage — it is not rooted in the DID’s identity (SPEC §5).

LauncherMismatch

The DID’s current tip authenticated as a genuine singleton, but its GENUINE launcher (walked from the parent-spend chain) is not the launcher that was requested. This is the money-critical guard for crate::resolve_xch_address: a dishonest crate::ChainSource can echo an attacker DID’s tip for a victim launcher, and the curried launcher_id on that tip is attacker-chosen, so only the parent-walk-authenticated launcher may be trusted. Resolving an address from a mismatched launcher would pay the wrong recipient, so this fails closed (SPEC §5).

LineageTooDeep

The parent-spend walk exceeded crate::resolve::MAX_LINEAGE_DEPTH — a DoS guard against an unbounded (possibly adversarial) lineage. The proof fails closed rather than walk forever.

Trait Implementations

impl Debug for DidError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for DidError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for DidError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<DriverError> for DidError

fn from(source: DriverError) -> Self

Converts to this type from the input type.