mk_codec/
key_card.rs

1//! `KeyCard` — the in-memory representation of a decoded MK card.
2//!
3//! Field semantics mirror the wire-format payload from
4//! `design/SPEC_mk_v0_1.md` §3.2. The bytecode-layer encode/decode
5//! lives in [`crate::bytecode`] (Phase 4); the string-layer wrapper
6//! (BCH + chunking) wires up the public `encode`/`decode` functions
7//! below in Phase 5.
8
9use bitcoin::bip32::{DerivationPath, Fingerprint, Xpub};
10
11use crate::error::Result;
12
13/// In-memory representation of one decoded MK card.
14///
15/// Per closure Q-8, `origin_fingerprint` is `Option<Fingerprint>`:
16/// a card encoded with the bytecode-header fingerprint flag unset
17/// (privacy-preserving mode) reconstructs to a `KeyCard` with
18/// `origin_fingerprint = None`.
19///
20/// `#[non_exhaustive]` so future versions can add fields without
21/// breaking external constructors.
22#[non_exhaustive]
23#[derive(Debug, Clone, PartialEq, Eq)]
24pub struct KeyCard {
25    /// Policy ID stubs declaring which MD-encoded policy template(s)
26    /// this xpub is intended to serve. Each stub is the top 4 bytes
27    /// of the policy's `SHA-256(canonical_bytecode)`. The vector is
28    /// guaranteed non-empty after a successful `decode` (the decoder
29    /// rejects `count == 0` with `Error::InvalidPolicyIdStubCount`).
30    pub policy_id_stubs: Vec<[u8; 4]>,
31
32    /// Master-key fingerprint identifying the seed from which `xpub`
33    /// was derived. Verbatim from BIP 380 origin notation `[fp/...]`.
34    /// Optional per closure Q-8: encoders MAY omit (set bytecode-header
35    /// bit 2 = 0) for the privacy-preserving mode.
36    pub origin_fingerprint: Option<Fingerprint>,
37
38    /// Derivation path from master to `xpub`. Encoded on the wire
39    /// either via a 1-byte standard-path indicator (BIP 44/49/84/86/
40    /// 48-segwit/48-nested/87 + testnet variants) or via the explicit
41    /// `0xFE` escape hatch with LEB128 components.
42    pub origin_path: DerivationPath,
43
44    /// The BIP 32 extended public key. The wire format carries a
45    /// 73-byte compact form (per closure Q-7); the in-memory `Xpub`
46    /// is reconstructed at decode time using the locked rule:
47    ///
48    /// ```text
49    /// depth        := component_count(origin_path)
50    /// child_number := last_component(origin_path)
51    /// ```
52    pub xpub: Xpub,
53}
54
55impl KeyCard {
56    /// Construct a `KeyCard` from its four owned fields.
57    ///
58    /// `KeyCard` is `#[non_exhaustive]` so that future versions can
59    /// add fields without breaking external callers; the constructor
60    /// stays stable across additions because new fields land with
61    /// `Default`-compatible values or new constructors.
62    ///
63    /// # Field invariants enforced at encode time
64    ///
65    /// `KeyCard::new` is intentionally permissive — field-level
66    /// validation lives in [`crate::encode`] / [`crate::bytecode::encode_bytecode`].
67    /// In particular:
68    ///
69    /// - `policy_id_stubs` MUST be non-empty; the encoder rejects an
70    ///   empty vector with [`crate::Error::InvalidPolicyIdStubCount`]
71    ///   (per `design/SPEC_mk_v0_1.md` §4 rule 3).
72    /// - `origin_path` MUST have at most [`crate::MAX_PATH_COMPONENTS`]
73    ///   = 10 components when an explicit-path encoding would be used;
74    ///   exceeding that yields [`crate::Error::PathTooDeep`].
75    ///
76    /// Callers that want a fail-fast constructor should validate
77    /// these invariants before calling `new`, or simply rely on the
78    /// encoder's rejection.
79    pub fn new(
80        policy_id_stubs: Vec<[u8; 4]>,
81        origin_fingerprint: Option<Fingerprint>,
82        origin_path: DerivationPath,
83        xpub: Xpub,
84    ) -> Self {
85        Self {
86            policy_id_stubs,
87            origin_fingerprint,
88            origin_path,
89            xpub,
90        }
91    }
92}
93
94/// Encode a `KeyCard` into one or more `mk1`-prefixed strings.
95///
96/// Multi-chunk encodings draw a fresh 20-bit `chunk_set_id` from the
97/// system CSPRNG. Use [`encode_with_chunk_set_id`] for byte-deterministic
98/// output (vector regeneration, conformance tests).
99pub fn encode(card: &KeyCard) -> Result<Vec<String>> {
100    crate::string_layer::encode(card)
101}
102
103/// Like [`encode`], with an explicit `chunk_set_id` override.
104///
105/// `chunk_set_id` MUST fit in 20 bits (`0..=0x000F_FFFF`); otherwise
106/// returns [`crate::Error::ChunkedHeaderMalformed`]. The override is
107/// only consulted on the chunked path; single-string encodings have no
108/// `chunk_set_id` field.
109pub fn encode_with_chunk_set_id(card: &KeyCard, chunk_set_id: u32) -> Result<Vec<String>> {
110    crate::string_layer::encode_with_chunk_set_id(card, chunk_set_id)
111}
112
113/// Decode one or more `mk1`-prefixed strings into a `KeyCard`.
114pub fn decode(strings: &[&str]) -> Result<KeyCard> {
115    crate::string_layer::decode(strings)
116}
117
118#[cfg(test)]
119mod tests {
120    use super::*;
121
122    /// Sanity check: type signatures compile and the public API
123    /// surface matches what the lib.rs re-exports expect. Real
124    /// round-trip coverage at this layer lands in Phase 6.
125    #[test]
126    fn types_compile() {
127        let _f: fn(&KeyCard) -> Result<Vec<String>> = encode;
128        let _g: fn(&[&str]) -> Result<KeyCard> = decode;
129    }
130}
mk_codec/key_card.rs

mk_codec/
key_card.rs
