Lattice HD Wallets

This repository is a proof-of-concept implementation that accompanies the paper Lattice HD Wallets: Post-Quantum BIP32 Hierarchical Deterministic Wallets from Lattice Assumptions. It implements a Post-Quantum Hierarchical Deterministic Wallet (PQ-HD-Wallet) with two signature schemes:

• ML-DSA – hardened-only derivation (NIST Module-Lattice Digital Signature Algorithm)
• Raccoon-G – hardened and non-hardened derivation (lattice-based, enables watch-only wallets)

It reproduces the structure of Bitcoin's BIP-32 HD wallets but uses post-quantum key derivation and signing instead of elliptic curves.

WARNING: Not for production use. This is an experimental proof-of-concept. Do not use for production keys, real funds, or security-critical systems. It has not been audited.

Overview

The project implements a post-quantum-secure key hierarchy where keys are derived deterministically from a single master seed.

Each node in the tree stores:

• a 32-byte deterministic seed (or tweak seed for Raccoon-G non-hardened children) used for key generation
• a 32-byte chain code; derivation uses BIP-32 style HMAC: HMAC-SHA512(Key = chain_code, Data = serialized_key || ser32(index)), with serialized_key = 0x00||private_key (hardened) or public_key (non-hardened)

ML-DSA supports only hardened derivation; Raccoon-G supports both hardened and non-hardened derivation, so child public keys can be derived from the parent public key alone.

The wallet supports:

• Master key generation from a 256-bit seed
• Deterministic hardened child derivation (both schemes)
• Non-hardened child derivation (Raccoon-G only)
• Path derivation syntax (e.g. m/44'/0'/0' or m/44'/0'/0'/0/1)
• Address generation as the BLAKE3 hash of the public key (ML-DSA); Raccoon-G uses the serialized public key

Motivation

Existing HD wallets rely on elliptic-curve schemes such as secp256k1. These are not quantum-resistant: a sufficiently powerful quantum computer could recover private keys from public keys using Shor's algorithm.

ML-DSA (Module-Lattice-based Digital Signature Algorithm), standardized by NIST, provides quantum-resistant digital signatures. This implementation demonstrates how HD-wallet structures can be built securely using lattice-based signatures instead of elliptic curves.

How It Works

The wallet starts from a 256-bit seed (e.g. from a BIP-39 mnemonic). This seed is hashed using an HMAC function to produce two 32-byte outputs:

• one becomes the entropy used for the master keypair
• the other becomes the master chain code.

When a new hardened child key is needed, HMAC-SHA512 is computed BIP-32 style: Key = parent chain code, Data = 0x00 || serialized_private_key || ser32(index). The 512-bit output is split: the left 256 bits become the child's key-generation seed, the right 256 bits the new chain code. For non-hardened derivation, Key = chain code and Data = serialized_public_key || ser32(index).

Raccoon-G additionally supports non-hardened derivation: the child key is derived from the parent public key and a tweak (parent_public_key + tweak_public_key), so watch-only wallets can derive child public keys without the signing key.

Hierarchical paths (e.g. m/44'/0'/0' for hardened, or m/44'/0'/0'/0/1 with non-hardened steps) are repeated applications of derivation.

For ML-DSA, each public key is hashed with BLAKE3 to produce an address; this can be extended as per protocol requirements.

Running the Code

The default build includes the Raccoon-G module (Python bridge). To run the full demo (ML-DSA + Raccoon-G), you need the Python environment.

Quick run (recommended)

From the repo root, use the wrapper script (it creates the Python venv if needed and sets the environment):

• Windows: .\run-with-raccoon.ps1 run
• Mac/Linux: ./run-with-raccoon.sh run

If Windows blocks the script ("running scripts is disabled"):

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
.\run-with-raccoon.ps1 run

or: powershell -ExecutionPolicy Bypass -File .\run-with-raccoon.ps1 run

Prerequisites: Rust and UV.

Manual setup

If you prefer to set up the Python environment yourself:

1. Install UV: See UV installation.
2. Create the venv:

   cd src/raccoon/thrc-py
   uv sync

3. Set PYO3_PYTHON (one-time) so the Rust build finds the venv:
   • Windows: setx PYO3_PYTHON "C:\path\to\project\src\raccoon\thrc-py\.venv\Scripts\python.exe"
   • Mac/Linux: export PYO3_PYTHON="/path/to/project/src/raccoon/thrc-py/.venv/bin/python" (add to shell profile for persistence)
4. From repo root:

   cargo build
   cargo run

The demo uses a fixed seed (for reproducibility) and:

• ML-DSA: Derives hardened paths (m/44', m/44'/0'/0', m/44'/0'/0'/1'), signs and verifies.
• Raccoon-G: Derives hardened (m/44', m/44'/0', m/44'/0'/0') and non-hardened (m/44'/0, m/44'/0'/0'/0, m/44'/0'/0'/0/1) paths, demonstrates watch-only derivation, and signs/verifies on multiple paths.

ML-DSA only (no Python)

cargo run --no-default-features

Running Tests

With the default features, tests include Raccoon-G, which requires the Python venv. Use the wrapper script (recommended):

• Windows: .\run-with-raccoon.ps1 test
• Mac/Linux: ./run-with-raccoon.sh test

Or set PYO3_PYTHON to the thrc-py venv Python, then from repo root:

cargo test

To run ML-DSA tests only (no Python):

cargo test --no-default-features

Raccoon-G module (Experimental)

The raccoon module provides the Raccoon-G post-quantum signature scheme and supports non-hardened derivation - a key feature missing from ML-DSA. This enables watch-only wallets that can derive child public keys without access to private keys.

Raccoon-G setup (Python interop)

The Raccoon-G implementation uses a Python bridge to the thrc reference implementation. To run the demo or tests, use the wrapper script or manual setup in Running the Code and Running Tests above.

Sage parameters script

The Raccoon-G lattice parameters (ring dimension N, modulus q, module dimensions k/ell, tail bounds nu_t/nu_w, etc.) can be derived and explored using the SageMath script in the repo:

• Script: scripts/sigparams.sage
• Purpose: Derives and prints parameters for the HD-wallet variant; outputs map to src/raccoon/thrc-py/polyr.py (RACC_N, RACC_Q) and thrc_core.py (k, ell, nu_t, nu_w, lg_st, lg_swt, omega, max_derivation_depth).
• Run: From the repo root, sage scripts/sigparams.sage (requires SageMath and optionally sage-estimate for the lattice estimator).

You do not need to run this script to build or test the project; the codebase uses fixed parameters. It is provided for transparency and for experimenting with different parameter sets. If you have SageMath installed, run it once to confirm it completes and prints parameter tables.

Why Raccoon-G?

Raccoon-G is a lattice-based signature scheme that supports linear key operations:

• child_pk = parent_pk + tweak_pk
• child_sk = parent_sk + tweak_sk

This property enables BIP-32-style non-hardened derivation, where child public keys can be computed from the parent public key alone - essential for watch-only wallets and hierarchical key management.

Comparison of byte sizes

Below is a comparison of BIP-32, PQ-HD-ML-DSA, and PQ-HD-Raccoon-G in bytes for privated key, public key, and signature.

Key and signature sizes (bytes)

Scheme	Private key	Public key	Signature
BIP32 (classical, secp256k1)	32	33	64
ML-DSA-44 (MlDsa44)	2,560	1,312	2,420
Raccoon-G	16,128	16,144	20,768

Parameters used

Raccoon-G (depth-1000) parameters

Parameter	Value	Description
N	256	Polynomial ring degree (X^N + 1)
q	50-bit prime	Coefficient modulus, q ≡ 1 (mod 512); see polyr.py
k	9	Public key vector length (mod dim)
ℓ	9	Secret key vector length (sec dim)
τ	23	Challenge space ℓ₁-norm
ν_t	35	Rounding bits for public key (q_t = q >> ν_t)
ν_w	38	Rounding bits for hint (q_w = q >> ν_w)
σ_t	2^7	Gaussian width for t (verification key)
σ_w	2^40	Gaussian width for signing randomness
κ	128	Security level (bits)
max derivation depth	1000	Supported HD derivation depth for B₂ bound