ms_codec/lib.rs
1//! `ms-codec` — reference implementation of the **ms1** backup format (HRP `ms`).
2//!
3//! ms1 is a Bitcoin self-custody backup format for BIP-39 entropy, layered atop
4//! BIP-93 codex32 via Andrew Poelstra's `rust-codex32` crate (CC0). Designed for
5//! steel-plate engraving alongside sibling formats `mk1` (xpubs) and `md1`
6//! (descriptors). Every wire-format decision is judged against "does this make
7//! a steel-plate backup more correct, or less?"
8//!
9//! See [`SPEC_ms_v0_1.md`](../../design/SPEC_ms_v0_1.md) for the full wire-format
10//! specification and [`MIGRATION.md`](../../MIGRATION.md) for the v0.1 → v0.2
11//! K-of-N share-encoding migration contract.
12//!
13//! # Quickstart
14//!
15//! ```
16//! use ms_codec::{encode, decode, Payload, Tag};
17//!
18//! let entropy = vec![0xAAu8; 16]; // 12-word BIP-39 entropy
19//! let s = encode(Tag::ENTR, &Payload::Entr(entropy.clone())).unwrap();
20//! assert_eq!(s.len(), 50); // 12-word entr = 50-char ms1 string
21//!
22//! let (tag, payload) = decode(&s).unwrap();
23//! assert_eq!(tag, Tag::ENTR);
24//! assert_eq!(payload, Payload::Entr(entropy));
25//! ```
26//!
27//! # v0.1 scope
28//!
29//! - **In:** BIP-39 entropy (16/20/24/28/32 B). Tag: `entr`.
30//! - **Out:** Direct BIP-32 master seed (64 B) and serialized xpriv (78 B) —
31//! reserved-not-emitted in v0.1; deferred to v0.2+ with separate framing
32//! (they overflow BIP-93 codex32's length brackets when prepended with
33//! the v0.2-migration prefix byte). The master-seed backup use case is
34//! preserved via the application-layer routing
35//! `BIP-39 phrase → entropy → ms1 entr → engrave → recover → BIP-39 mnemonic
36//! → PBKDF2 → master seed`. See SPEC §1.2.
37
38#![cfg_attr(not(test), deny(missing_docs))]
39
40pub mod consts;
41pub mod decode;
42pub mod encode;
43pub mod error;
44pub mod inspect;
45pub mod payload;
46pub mod tag;
47
48mod envelope; // crate-private; v0.2-migration seam
49
50pub use decode::decode;
51pub use encode::encode;
52pub use error::{Error, Result};
53pub use inspect::{inspect, InspectReport};
54pub use payload::{Payload, PayloadKind};
55pub use tag::Tag;