A specification for backing up bitcoin extended public keys (xpubs) on durable media (paper, steel) in a form that is compact, hand-transcribable, and strongly error-correcting. Designed to engrave alongside a Mnemonic Descriptor (MD) policy card for foreign-xpub multisig recovery.
Status: v0.1 reference implementation shipped. The wire format is locked per the closure design at
docs/superpowers/specs/2026-04-29-mk1-open-questions-closure-design.md;crates/mk-codecprovides a workingKeyCard↔Vec<String>round-trip with BCH error correction and a canonical 39-vector conformance corpus (17 clean + 22 negative, one negative perErrorvariant). Pre-BIP-submission audit items remain — seedesign/FOLLOWUPS.md.
MK is the third format in a triad of codex32-derived bitcoin backup formats:
| Format | HRP | Purpose | Spec |
|---|---|---|---|
| Mnemonic Seed share | ms1 |
Seed shares | BIP 93 (Andrew Poelstra) |
| Mnemonic Descriptor | md1 |
Wallet-policy template | bg002h/descriptor-mnemonic |
| Mnemonic Key | mk1 |
Extended public keys | this repo |
All three reuse BIP 93's BCH plumbing (same generator polynomials, same alphabet) with HRP-mixing and per-format target residues providing domain separation.
MD encodes the BIP 388 wallet-policy template (the @N-placeholder shape), but not the xpubs that map placeholders to keys. For wallets where the user holds every seed, MD's omission is fine — the seeds reconstruct the xpubs. For foreign-xpub multisig (the user is one of N cosigners and doesn't hold all seeds), MD alone is insufficient: the missing xpubs must come from somewhere at recovery time.
MK fills that gap with separate per-cosigner cards. Each cosigner backs up their own xpub on its own card, atomically, and may stamp one or more "Policy ID" stubs declaring which MD-encoded wallets the xpub serves. Cosigners can hand their MK card to a wallet creator without revealing other cosigners' xpubs.
.
├── bip/
│ └── bip-mnemonic-key.mediawiki ← BIP draft (content-complete; pre-submission audit)
├── crates/
│ └── mk-codec/ ← Rust reference implementation (v0.1)
├── design/
│ ├── DECISIONS.md ← rolling design-decisions log (D-1..D-15, Q-1..Q-10 closed)
│ ├── FOLLOWUPS.md ← deferred items + pre-bip-submission audit gates
│ └── SPEC_mk_v0_1.md ← wire-format spec (post-closure)
├── CHANGELOG.md
├── LICENSE
└── README.md
- For format users / implementers:
bip/bip-mnemonic-key.mediawikiis the canonical (draft) spec. - For the reference implementation:
crates/mk-codec/— Rust crate, v0.1.1 working encode/decode round-trip + 39-vector conformance corpus (17 clean + 22 negative) atcrates/mk-codec/src/test_vectors/v0.1.json. - For why the design is the way it is:
design/DECISIONS.mdwalks through D-1..D-15 (the 2026-04-29 design discussion plus closures of Q-1..Q-10).design/SPEC_mk_v0_1.mdis the post-closure wire-format spec. - For deferred work:
design/FOLLOWUPS.md— pre-BIP-submission audit gates and cross-repo coordination items.
mk ships man pages generated from its own clap definition — the same source as --help — so they cannot drift from the binary. Three ways to install them:
-
Automatic (default). The constellation installer installs them alongside the binary into
~/.local/share/man/man1— no sudo, no system files:sh -c "$(curl -fsSL https://raw.githubusercontent.com/bg002h/mnemonic-toolkit/master/scripts/install.sh)"Then
man mkworks (andman mk-<subcommand>for each subcommand). Pass--no-manto skip, or--man-dir <dir>to relocate. -
By hand. If you installed the binary directly (
cargo install), emit them yourself:mk gen-man --out ~/.local/share/man/man1 -
Download. Each release attaches a
mk-man.tar.gzasset — extract it into your manpath.
If man mk can't find them (older man-db, or macOS/BSD man that doesn't auto-read ~/.local/share/man): man -M ~/.local/share/man mk.
- Foreign-xpub multisig recovery: each cosigner backs up their xpub on its own MK card. Recovery: assemble policy card (MD) + cosigner key cards (MK) → reconstruct full descriptor → verify Wallet Instance ID matches.
- Per-card metadata: optional BIP 32 origin fingerprint (closure Q-8 privacy-preserving mode), derivation path (standard-table indicator OR explicit-path escape hatch with a 10-component cap), 73-byte compact xpub (closure Q-7), ≥1 Policy ID stubs identifying which MD-encoded wallets the xpub serves.
- Privacy framing: an MK card alone enables full transaction-history reconstruction; physical security parity with seed backups is recommended (MUST NOT be photographed).
- Extended private keys (xprv): backing up secret material is BIP 93's job.
- MuSig2 aggregate keys (BIP 327): future milestone, possibly its own format.
- Embedded wallet-policy fragments: the policy lives on the MD card; MK is key-only.
The release mk-<version>-x86_64-linux-musl.tar.gz and …-aarch64-linux-musl.tar.gz
binaries are reproducible — bit-for-bit rebuildable from source. Each release
attaches SHA256SUMS.x86_64, SHA256SUMS.aarch64, and PROVENANCE.<arch>.txt.
Integrity (did my download arrive intact?):
sha256sum -c SHA256SUMS.x86_64 # or SHA256SUMS.aarch64Provenance (was it really built from this source — no hidden changes?):
independently rebuild and confirm you get the same hash. See
docs/verify-reproducibility.md for the exact
steps — in brief: git checkout the release commit (from PROVENANCE.<arch>.txt),
docker pull ghcr.io/bg002h/repro-musl-mnemonic-key@sha256:<digest> (the pinned,
public build image), rebuild offline, and compare to SHA256SUMS.<arch>. A match
proves the published binary came from this source.
Scope: the static-musl Linux x86_64 and aarch64 mk binaries.
(gnu, macOS/Windows, and the GUI are not yet reproducible.) Note: a local
cargo install / install.sh build is not bit-for-bit reproducible — the
guarantee is for the published container-built release tarballs.
The specification text in this repository and the reference implementation in crates/mk-codec/ are dual-licensed, at your option, under either the MIT License or the Unlicense public-domain dedication — SPDX MIT OR Unlicense.
bg002h · bcg@pm.me
- Mnemonic Descriptor (MD) — sibling repo for the wallet-policy-template format.
- BIP 93 — codex32 — Andrew Poelstra. Provides the BCH plumbing MK reuses.
- BIP 32 — Hierarchical Deterministic Wallets — defines the xpub serialization MK encodes.
- BIP 380 — Output Descriptors — origin notation
[fp/path]xpub. - BIP 388 — Wallet Policies — the placeholder-template framing MD encodes.