Skip to content

ms-codec v0.1.0 — initial release (entr-only)

Choose a tag to compare

View all tags
@bg002h bg002h released this 04 May 04:45
ms-codec-v0.1.0
ab374ed

Initial release. Reference implementation of the ms1 backup format (HRP ms) for BIP-39 entropy. Sibling to md1 (wallet descriptors) and mk1 (xpubs). Designed for steel-plate engraving with strong BCH error correction.

What's new

  • Wire format: BIP-93 codex32 used directly via Andrew Poelstra's rust-codex32 = "=0.1.0" (CC0). No fork.
  • v0.1 payload kind: entr (BIP-39 entropy, 16/20/24/28/32 B = BIP-39 word counts {12, 15, 18, 21, 24}).
  • v0.1 emitted strings: 50/56/62/69/75 chars (short codex32 checksum only).
  • Public API: encode(Tag, &Payload) -> Result<String>, decode(&str) -> Result<(Tag, Payload)>, inspect(&str) -> Result<InspectReport>.
  • Tag::ENTR const; Payload::Entr(Vec<u8>); InspectReport for debugging.
  • Decoder applies the full SPEC §4 validity rule set (10 rules); encoder mirrors the reserved-not-emitted-tag rejection (SPEC §3.5.1).
  • v0.2 K-of-N share-encoding migration designed up-front via the 0x00 reserved-prefix byte; v0.1 strings remain forward-readable by v0.2 decoders. See MIGRATION.md.
  • Payload, PayloadKind, Error, InspectReport are #[non_exhaustive] from day 1.

Scope notes

  • In: BIP-39 entropy. Tag: entr.
  • Out (deferred to v0.2+): Direct BIP-32 master seed (64 B) and serialized xpriv (78 B). They overflow BIP-93 codex32's length brackets when prepended with the v0.2-migration prefix byte. The master-seed backup use case is preserved at the application layer via BIP-39 phrase → entropy → ms1 entr → engrave → recover entropy → BIP-39 mnemonic → PBKDF2 → master seed. See design/SPEC_ms_v0_1.md §1.3 for full discussion of the design tradeoff.

Engraving caveat: BIP-39 wordlist language

ms1 v0.1 does not carry the BIP-39 wordlist language on the wire. Users with non-English wallets MUST record their wordlist language alongside the engraved card. A future v0.2+ payload kind mnem (reserved tag) is allocated to address this on the wire. See SPEC §6.3.

Tests

50 tests across all targets: 28 unit + 1 doc-test + 10 negative + 5 round-trip proptests + 2 forward-compat + 3 BIP-39 integration + 1 vector-corpus replay. cargo build, cargo clippy --all-targets -D warnings, cargo fmt --check all clean.

Wire-format SHA pin

The canonical test vectors at crates/ms-codec/tests/vectors/v0.1.json are SHA-256-pinned at this release. Subsequent corpus changes that alter the SHA require a SemVer minor bump.

sha256(crates/ms-codec/tests/vectors/v0.1.json) = f8d671f543101a4b90fd028126aef66958ff4050e38a32baa48ff298cdf2901a

Documentation

Assets 2
Loading