{"id":49414044,"url":"https://github.com/bg002h/descriptor-mnemonic","last_synced_at":"2026-05-16T06:13:10.707Z","repository":{"id":354078061,"uuid":"1222000641","full_name":"bg002h/descriptor-mnemonic","owner":"bg002h","description":"Wallet Descriptor Mnemonic — a steel-engravable backup format for Bitcoin wallet policies","archived":false,"fork":false,"pushed_at":"2026-04-27T04:05:55.000Z","size":131,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T04:06:23.125Z","etag":null,"topics":["bip","bip388","bitcoin","codex32","descriptors","miniscript","self-custody","wallet-backup"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bg002h.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T00:14:34.000Z","updated_at":"2026-04-27T04:05:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bg002h/descriptor-mnemonic","commit_stats":null,"previous_names":["bg002h/descriptor-mnemonic"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/bg002h/descriptor-mnemonic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bg002h%2Fdescriptor-mnemonic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bg002h%2Fdescriptor-mnemonic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bg002h%2Fdescriptor-mnemonic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bg002h%2Fdescriptor-mnemonic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bg002h","download_url":"https://codeload.github.com/bg002h/descriptor-mnemonic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bg002h%2Fdescriptor-mnemonic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32407231,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"online","status_checked_at":"2026-04-29T02:00:06.602Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bip","bip388","bitcoin","codex32","descriptors","miniscript","self-custody","wallet-backup"],"created_at":"2026-04-29T02:12:05.792Z","updated_at":"2026-05-16T06:13:10.692Z","avatar_url":"https://github.com/bg002h.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mnemonic Descriptor (MD)\n\n\u003e **Note**: This crate was renamed from `wdm-codec` (HRP `wdm`) to `md-codec` (HRP `md`) in v0.3.0. See [`MIGRATION.md`](./MIGRATION.md#v02x--v030) for upgrade guidance and [`CHANGELOG.md`](./CHANGELOG.md) for the v0.3.0 entry. The repository URL is unchanged.\n\n\u003e **Status: Pre-Draft, AI + reference implementation, awaiting human review.**\n\u003e This specification was produced by an AI assistant in collaboration with\n\u003e the author, and is shipped alongside a working reference implementation\n\u003e split across two Rust crates (MIT): the codec library at\n\u003e [`crates/md-codec/`](crates/md-codec/) and the `md` CLI at\n\u003e [`crates/md-cli/`](crates/md-cli/), locking the v0.1 wire format with\n\u003e committed test vectors. The spec and impl have\n\u003e not yet been reviewed end-to-end by a human or by the broader bitcoin\n\u003e community. Tag values, header layout, HRP, and structural decisions\n\u003e remain subject to change pending that review. Treat as a working sketch\n\u003e with concrete artifacts, not a finalized spec.\n\nA specification for backing up bitcoin wallet policies on durable media\n(paper, steel) in a form that is compact, hand-transcribable, and\nstrongly error-correcting.\n\nMD is to **wallet structure** what BIP 39 is to **seed entropy**: a\ncanonical engravable backup format. Where a 24-word BIP 39 phrase\nrestores a wallet's keys, an MD string restores a wallet's spending\npolicy — the miniscript template, derivation paths, and (in future\nversions) cosigners' extended public keys.\n\n\u003e **Scope note (v0.6+):** MD is *neutral* on hardware-signer compatibility.\n\u003e An MD-encoded backup is structurally well-formed if and only if the\n\u003e policy parses under BIP 388 + BIP 379; whether the policy is signable\n\u003e on a particular hardware signer is a separate concern handled by\n\u003e wallet software (above MD) and by signer firmware (below MD). The\n\u003e responsibility chain is: wallet software constructs a signer-compatible\n\u003e policy → MD encodes it losslessly → user recovers → recovery wallet\n\u003e pairs with matching signer to spend. **You are responsible for\n\u003e ensuring your policy is signable on your target signer.** See the\n\u003e BIP draft §\"Signer compatibility (informational)\" for the full\n\u003e framing.\n\n## What this repository contains\n\n```\n.\n├── bip/\n│   ├── README.md                                  ← BIP draft index\n│   └── bip-mnemonic-descriptor.mediawiki          ← the formal BIP draft\n├── crates/\n│   ├── md-codec/                                  ← Rust reference codec library (v0.16+: library-only)\n│   ├── md-cli/                                    ← `md` CLI binary (v0.1+; ships the binary extracted from md-codec 0.15.x)\n│   └── md-signer-compat/                          ← layered named-signer-subset validator (v0.7+)\n├── design/\n│   ├── POLICY_BACKUP.md   ← design rationale, decisions log, open items\n│   ├── PRIOR_ART.md       ← survey of related encoding schemes\n│   ├── CORPUS.md          ← reference miniscript test corpus\n│   ├── FOLLOWUPS.md       ← deferred items + closure log\n│   └── agent-reports/     ← per-phase Opus review reports\n├── LICENSE\n└── README.md\n```\n\n## Where to start reading\n\n- **For format users / implementers:** `bip/bip-mnemonic-descriptor.mediawiki` is the canonical spec.\n- **For the codec library:** [`crates/md-codec/README.md`](crates/md-codec/README.md) — quickstart and library API.\n- **For the `md` CLI:** [`crates/md-cli/README.md`](crates/md-cli/README.md) — install instructions, subcommand reference, network selection.\n- **For why the spec is the way it is:** `design/POLICY_BACKUP.md` documents the design decisions and tradeoffs in detail.\n- **For comparison with existing formats:** `design/PRIOR_ART.md`.\n- **For what real miniscripts look like under MD encoding:** `design/CORPUS.md` and the locked test vectors at `crates/md-codec/tests/vectors/` (per-shape `{template, phrase.txt, bytes.hex, descriptor.json}` quadruples; manifest at `manifest.rs`).\n\n## What MD is for\n\nBitcoin wallets that use arbitrary miniscript spending policies — multisig, timelocks, decaying conditions, inheritance schemes — must back up the policy structure separately from the seed. The seed alone is insufficient to recover funds because the wallet doesn't know what spending conditions to enforce.\n\nExisting approaches (JSON exports, Liana `.bed` files, Coldcard multisig configs, Bytewords/UR) all have shortcomings for the durable-storage case: they're too verbose for engraving, lack strong error correction, depend on digital infrastructure, or don't cover arbitrary miniscript.\n\nMD addresses this with:\n\n- **Codex32-derived encoding** (BIP 93 BCH error correction; bech32 alphabet)\n- **Compact bytecode** for BIP 380 descriptors and BIP 388 wallet policies (extending `descriptor-codec`)\n- **Multi-string chunking** for arbitrary-length policies\n- **Mandatory guided recovery** combining BCH ECC with structural knowledge\n\n## What's covered in v0\n\nThe v0 specification scope targets the most common self-custody case:\n\n- A single user holding all seeds referenced by the policy (no foreign xpubs)\n- Shared paths (all `@i` placeholders on one derivation path) **and per-`@N` divergent paths** (one path per placeholder, in placeholder-index order) — v0.10+\n- `wsh()` segwit v0 or `tr()` taproot script types\n\nThis covers single-key wallets, all common multisig configurations (including those where each cosigner derives from a distinct BIP 48 account), decaying multisig, simple inheritance, and timelock-based recovery — every Liana wallet template plus typical Coldcard self-custody setups.\n\nForeign xpubs (multi-party multisig where you don't hold all seeds) are deferred to v1+. Per-`@N` divergent paths shipped in v0.10 (`Tag::OriginPaths`); the current wire format is **v0.30** (a clean break from v0.x — see `design/SPEC_v0_30_wire_format.md`, [`CHANGELOG.md`](CHANGELOG.md), and [`MIGRATION.md`](MIGRATION.md)). v0.32 (2026-05-11) replaced the v0.14-era 5-shape address-derivation allow-list with a generic AST → `miniscript::Descriptor` converter, covering every BIP-388-parseable shape.\n\n## Status\n\nThis specification is in **Pre-Draft, AI + reference implementation, awaiting human review** status. The structure of the spec is in place and a reference implementation ships at [`crates/md-codec/`](crates/md-codec/) with 444 tests passing across the workspace (395 without default features). Independent human review of both the spec and the impl is the remaining gate. Open spec questions are tracked in `design/POLICY_BACKUP.md` §8; deferred work is tracked in [`design/FOLLOWUPS.md`](design/FOLLOWUPS.md).\n\nThe Rust reference implementation implements the current scope:\n\n- Full encode → bytecode → chunking → codex32 → BCH-checksummed string round-trip.\n- Decode pipeline with per-stage diagnostics (`DecodeReport` + `Confidence`).\n- 444 unit + integration tests across the workspace (395 without default features), including corpus round-trips, negative conformance vectors, hand-AST defensive coverage, and BCH known-vectors cross-checked against an independent Python implementation.\n- v0.30 wire-format test vectors locked in `crates/md-codec/tests/vectors/` (per-shape quadruples; manifest at `tests/vectors/manifest.rs`).\n- `Descriptor::derive_address` (v0.32+, feature `derive`, default-on) covers every BIP-388-parseable shape via the generic AST → `miniscript::Descriptor` converter at `crates/md-codec/src/to_miniscript.rs`.\n- An `md` CLI (in [`crates/md-cli/`](crates/md-cli/)) for ad-hoc encode/decode/verify/inspect/bytecode/vectors operations, plus a `from-policy` mode (behind opt-in `cli-compiler` feature) wrapping rust-miniscript's policy compiler.\n- A sibling [`md-signer-compat`](crates/md-signer-compat/) crate (v0.7.0+) shipping named hardware-signer subsets (`COLDCARD_TAP`, `LEDGER_TAP`) with a `validate_tap_tree` walker, plus a `md-signer-compat validate --signer \u003cname\u003e ...` CLI binary.\n\nThe `Draft` status (the first formal BIP 2 status) will be claimed only after the spec has been reviewed by at least one human contributor end-to-end.\n\nThe next development steps are tracked in `design/POLICY_BACKUP.md` §10:\n\n1. ~~Reference implementation (Rust)~~ — done; see `crates/md-codec/`.\n2. ~~Concrete test vectors for the corpus~~ — done; locked in `tests/vectors/v0.1.json`.\n3. Implementation experience to refine the spec\n4. Submission to bitcoin-dev for community review\n5. Formal BIP submission\n\n## License\n\nThe specification text in this repository and the reference implementation\nin `crates/md-codec/` and `crates/md-cli/` are released under the\n[MIT License](LICENSE).\n\n## Contact\n\nbg002h · `bcg@pm.me`\n\n## Related work\n\n- [BIP 388 — Wallet Policies for Descriptor Wallets](https://github.com/bitcoin/bips/blob/master/bip-0388.mediawiki)\n- [BIP 93 — codex32](https://github.com/bitcoin/bips/blob/master/bip-0093.mediawiki)\n- [BIP 380 — Output Descriptors](https://github.com/bitcoin/bips/blob/master/bip-0380.mediawiki)\n- [Pieter Wuille's miniscript reference](https://bitcoin.sipa.be/miniscript/)\n- [`descriptor-codec` (Josh Doman)](https://github.com/joshdoman/descriptor-codec)\n- [Liana wallet (Wizardsardine)](https://github.com/wizardsardine/liana)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbg002h%2Fdescriptor-mnemonic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbg002h%2Fdescriptor-mnemonic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbg002h%2Fdescriptor-mnemonic/lists"}