Struct KeyCard 

#[non_exhaustive]
pub struct KeyCard {
    pub policy_id_stubs: Vec<[u8; 4]>,
    pub origin_fingerprint: Option<Fingerprint>,
    pub origin_path: DerivationPath,
    pub xpub: Xpub,
}

In-memory representation of one decoded MK card.

Per closure Q-8, origin_fingerprint is Option<Fingerprint>: a card encoded with the bytecode-header fingerprint flag unset (privacy-preserving mode) reconstructs to a KeyCard with origin_fingerprint = None.

#[non_exhaustive] so future versions can add fields without breaking external constructors.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

policy_id_stubs: Vec<[u8; 4]>

Policy ID stubs declaring which MD-encoded policy template(s) this xpub is intended to serve. Each stub is the top 4 bytes of a canonical, encoder-divergence-free md1 identity, FORM-AWARE: the WalletPolicyId for a keyed wallet-policy md1, or the key-stable WalletDescriptorTemplateId for a keyless template md1 (matching the toolkit’s bundle_binding_stub / mk-cli’s derive_stub_from_md1, toolkit #28). The vector is guaranteed non-empty after a successful decode (the decoder rejects count == 0 with Error::InvalidPolicyIdStubCount).

origin_fingerprint: Option<Fingerprint>

Master-key fingerprint identifying the seed from which xpub was derived. Verbatim from BIP 380 origin notation [fp/...]. Optional per closure Q-8: encoders MAY omit (set bytecode-header bit 2 = 0) for the privacy-preserving mode.

origin_path: DerivationPath

Derivation path from master to xpub. Encoded on the wire either via a 1-byte standard-path indicator (BIP 44/49/84/86/ 48-segwit/48-nested/87 + testnet variants) or via the explicit 0xFE escape hatch with LEB128 components.

xpub: Xpub

The BIP 32 extended public key. The wire format carries a 73-byte compact form (per closure Q-7); the in-memory Xpub is reconstructed at decode time using the locked rule:

depth        := component_count(origin_path)
child_number := last_component(origin_path),
                or Normal{0} when origin_path is empty (depth-0 / no-path key)

Implementations

impl KeyCard

pub fn new( policy_id_stubs: Vec<[u8; 4]>, origin_fingerprint: Option<Fingerprint>, origin_path: DerivationPath, xpub: Xpub, ) -> Self

Construct a KeyCard from its four owned fields.

KeyCard is #[non_exhaustive] so that future versions can add fields without breaking external callers; the constructor stays stable across additions because new fields land with Default-compatible values or new constructors.

Field invariants enforced at encode time

KeyCard::new is intentionally permissive — field-level validation lives in crate::encode / crate::bytecode::encode_bytecode. In particular:

• policy_id_stubs MUST be non-empty; the encoder rejects an empty vector with crate::Error::InvalidPolicyIdStubCount (per design/SPEC_mk_v0_1.md §4 rule 3).
• origin_path MUST have at most crate::MAX_PATH_COMPONENTS = 10 components when an explicit-path encoding would be used; exceeding that yields crate::Error::PathTooDeep.

Callers that want a fail-fast constructor should validate these invariants before calling new, or simply rely on the encoder’s rejection.

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

Serialize this card to its canonical pre-chunking bytecode.

Deterministic pre-chunking bytecode; independent of the per-encode random chunk_set_id (which lives in the string layer). This is the same byte payload that crate::bytecode::encode_bytecode produces and that the conformance corpus pins as canonical_bytecode_hex; it is exposed here so a downstream consumer can obtain a stable, round-trippable identity for the card without reaching into the bytecode module or the random string framing.

Reverse with KeyCard::from_canonical_payload_bytes.

Errors

Surfaces the encoder-side invariants of crate::bytecode::encode_bytecode (e.g. crate::Error::InvalidPolicyIdStubCount, crate::Error::XpubOriginPathMismatch).

pub fn from_canonical_payload_bytes(bytes: &[u8]) -> Result<KeyCard>

Reconstruct a KeyCard from its canonical pre-chunking bytecode.

Inverse of KeyCard::canonical_payload_bytes; accepts exactly the byte payload that method emits (and that crate::bytecode::decode_bytecode consumes). Empty or malformed input is rejected cleanly with an crate::Error — never a panic.

Errors

Surfaces the bytecode-layer validity rules of crate::bytecode::decode_bytecode (e.g. crate::Error::UnexpectedEnd, crate::Error::TrailingBytes, crate::Error::UnsupportedVersion).

Trait Implementations

impl Clone for KeyCard

fn clone(&self) -> KeyCard

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for KeyCard

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

Formats the value using the given formatter.

impl Eq for KeyCard

impl PartialEq for KeyCard

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for KeyCard