Struct Descriptor 

pub struct Descriptor {
    pub n: u8,
    pub path_decl: PathDecl,
    pub use_site_path: UseSitePath,
    pub tree: Node,
    pub tlv: TlvSection,
}

Top-level descriptor parsed/built from a v0.30 wire payload.

Each field corresponds to a spec section: Header (§3.2), origin PathDecl (§3.3), use-site UseSitePath (§3.4), descriptor tree (§3.5–3.6), and trailing tlv section (§3.7).

Fields

n: u8

Number of placeholders (1-indexed key universe size).

path_decl: PathDecl

Origin path declaration (single or per-@N divergent).

use_site_path: UseSitePath

Use-site (post-key) path applied to every key by default.

tree: Node

Descriptor tree root node.

tlv: TlvSection

Trailing TLV section (overrides, fingerprints, etc.).

Implementations

impl Descriptor

pub fn derive_address( &self, chain: u32, index: u32, network: Network, ) -> Result<Address<NetworkUnchecked>, Error>

Derive the address at (chain, index) for this descriptor on network.

chain selects the use-site multipath alternative (e.g. 0 = receive, 1 = change for the standard <0;1>/* form). index is the trailing wildcard child number.

Returns an Address<NetworkUnchecked>; callers can .assume_checked() (when they trust the network parameter) or .require_network(network) to lock it down.

Errors

• Error::MissingPubkey when any @N lacks an xpub.
• Error::InvalidXpubBytes when an xpub’s 33-byte pubkey field doesn’t parse as a valid secp256k1 point.
• Error::ChainIndexOutOfRange when chain is out of range for the use-site multipath.
• Error::HardenedPublicDerivation when the use-site path requires a hardened derivation step.
• Error::MissingExplicitOrigin propagated from crate::canonicalize::expand_per_at_n.
• Error::AddressDerivationFailed for any miniscript-layer failure (type check, context error, unsupported fragment).

impl Descriptor

pub fn key_index_width(&self) -> u8

Bit width for placeholder-index encoding: ⌈log₂(n)⌉ per SPEC v0.30 §7.

Index range is 0..n. The NUMS H-point is signalled by an explicit is_nums bit on Body::Tr (SPEC §7), not by a reserved sentinel. MUST stay in lockstep with decode::decode_payload’s independent computation; a stale formula would silently desync the bitstream.

pub fn is_wallet_policy(&self) -> bool

Returns true iff this descriptor is in wallet-policy mode per SPEC §3.3: the Pubkeys TLV is present and contains at least one entry. Template-only mode (no Pubkeys TLV at all, or Pubkeys = Some(vec![]) after sparse-decode) returns false.

The check is a post-TLV-decode predicate; mode dispatch never reads a header bit.

pub fn canonical_payload_bytes(&self) -> Result<(Vec<u8>, usize), Error>

Return the deterministic pre-chunking canonical packed payload of this descriptor as a bit-precise (bytes, total_bits) pair, for a downstream consumer that needs the raw, round-trippable byte payload (without the codex32/md1 string wrapper or chunk framing).

This delegates to encode_payload, which canonicalizes BIP 388 placeholder ordering internally (SPEC §6.1) before emitting bits — so the output is canonical for any valid input descriptor (two inputs that differ only in non-canonical placeholder numbering produce byte-identical payloads).

The payload is bit-aligned: the returned bytes are zero-padded to a byte boundary, and total_bits is the exact unpadded bit count. The final byte may carry up to 7 trailing zero-pad bits, so total_bits is load-bearing — a consumer MUST round-trip with this exact bit count, not bytes.len() * 8. Feed both values back to Descriptor::from_canonical_payload_bytes to recover the descriptor.

pub fn from_canonical_payload_bytes( bytes: &[u8], total_bits: usize, ) -> Result<Descriptor, Error>

Reconstruct a Descriptor from a bit-precise canonical packed payload previously produced by Descriptor::canonical_payload_bytes.

bytes may be zero-padded to a byte boundary; total_bits is the exact payload bit count (the same value returned alongside the bytes). Delegates to decode_payload.

impl Descriptor

pub fn unresolved_origin_indices(&self) -> Vec<u8>

The ascending @N indices whose origin cannot be resolved: a pure query mirroring validate_explicit_origin_required’s SEMANTICS (P0.1, pathless/dead-card partial-decode).

Returns the ascending indices where canonical_origin(&self.tree) is None AND the per-idx origin (override-or-path_decl) is empty. Returns [] when canonical_origin is Some OR every idx has a non-empty origin (i.e. exactly the set of shapes that decode cleanly today under the strict default). Does NOT call crate::canonicalize::expand_per_at_n — this is a non-erroring, side-effect-free query, not an expansion; callers needing per-@N origin/use-site/fp/xpub records still use expand_per_at_n (which stays strict and fail-closed unconditionally — see its doc comment).

Trait Implementations

impl Clone for Descriptor

fn clone(&self) -> Descriptor

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Descriptor

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

Formats the value using the given formatter.

impl Eq for Descriptor

impl PartialEq for Descriptor

fn eq(&self, other: &Descriptor) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Descriptor