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