descriptor-codec

Efficiently encode and decode Bitcoin wallet descriptors with a 30-40% size reduction.

Features

• Compact Encoding: Tag-based and variable-length encoding and the avoidance of bech32 and base58 reduces descriptor size by 30-40%
• Complete Coverage: Supports all descriptors including those with complex miniscript and private keys
• QR Code Friendly: Smaller encodings improve QR code reliability and scanning
• NFC Compatible: Fits descriptors within NFC byte limits for hardware wallet communication

Usage

use descriptor_codec::{encode, decode};

// Encode a descriptor
let descriptor = "wsh(sortedmulti(2,\
    03a0434d9e47f3c86235477c7b1ae6ae5d3442d49b1943c2b752a68e2a47e247c7,\
    036d2b085e9e382ed10b69fc311a03f8641ccfff21574de0927513a49d9a688a00,\
    02e8445082a72f29b75ca48748a914df60622a609cacfce8ed0e35804560741d29\
))#hfj7wz7l";

let encoded = encode(descriptor).unwrap();
let decoded = decode(&encoded).unwrap();
assert_eq!(descriptor, decoded);

CLI Usage

Installation

To build the project, use the following command:

cargo build --release --features cli

The executable will be located at ./target/release/descriptor-codec.

Commands

• Encode a Descriptor

  Encodes a Bitcoin descriptor and outputs the result as hex.

  ./target/release/descriptor-codec encode <DESCRIPTOR_STRING>
  

  Arguments:

  • <DESCRIPTOR_STRING>: The Bitcoin descriptor string to encode.

• Decrypt a Descriptor

  Decodes hex-encoded descriptor data.

  ./target/release/descriptor-codec decode <DATA>
  

  Arguments:

  • <DATA>: Hex-encoded descriptor data.

Algorithm

The encoder splits the descriptor into two parts that are concatenated: a structural template and a data payload.

Template and Payload

The encoding separates the descriptor's structure from its raw data.

• Template: This part defines the logical structure of the descriptor. It is a sequence of single-byte Tags that represent script components (like wsh, pk, older) and structural information. It also contains variable-length encoded integers for derivation paths and multisig k/n parameters.
• Payload: This part contains the raw data values from the descriptor, concatenated in the order they are referenced by the template. This includes items like public keys, private keys, key fingerprints, hashes, and timelock values.

When decoding, the template is read first to understand the structure, which then dictates how to parse the subsequent payload data.

Variable-Length Encoding

To save space, unsigned integers are encoded as variable-length LEB128 integers. This is used for:

• Absolute and relative timelocks (after, older).
• The k (threshold) and n (total keys) values in multisig (multi, sortedmulti) and threshold (thresh) scripts.
• The length of derivation paths and the individual child numbers within them.
• Hardened child numbers are encoded as $2c+1$, where $c$ is the child number. Unhardened child numbers are encoded as $2c$.

Tags

Each component of a descriptor is represented by a single-byte tag.

Use Cases

• Sharing complex multisig configurations via QR codes
• NFC communication with hardware wallets
• Reducing bandwidth in wallet coordination protocols
• Storing descriptors in constrained environments

License

This project is licensed under the CC0-1.0 License.

Author

Joshua Doman joshsdoman@gmail.com