DEVELOPER REFERENCE / BITCOIN

PQ Shield
integration.

Build a defensive Bitcoin vault from public inputs, prepare unsigned spends, and verify a post-quantum anchor against a key your application already trusts.

Explore the routes ↓Read source and README ↗

Reference implementation in source. No hosted PQ Shield API or production readiness is claimed.

Implementation status

The Rust HTTP service exists and can be run locally. Its Bitcoin vault and Bloch anchor components are foundational and unaudited for production use. This page describes an API contract, not a live hosted endpoint.

01 / SYSTEM MODEL

A recovery window,
under your control.

PQ Shield builds a P2WSH deposit and delayed trigger output on unmodified Bitcoin. A client or watchtower can prepare a recovery spend while the normal branch waits for its relative timelock.

01 / PREPARE

Derive locally

Generate hot and recovery keys, a unique preimage r and its hash H(r) in your signer. Send public keys and the hash only.

02 / CONSTRUCT

Build artifacts

The API returns P2WSH scripts, addresses, unsigned Bitcoin transactions and BIP-143 sighashes.

03 / SIGN

Keep control

Your signer assembles witnesses. Your PQ key signs the anchor commitment on your device.

04 / MONITOR

Defend the window

Your node or watchtower watches the trigger and submits a clawback to a fresh safe address when required.

Bitcoin script enforces its hashlock and branch delay. Without a Bitcoin covenant, the deposit-to-trigger policy also depends on pre-signed transaction handling and secure deletion of any bypass key.

02 / HTTP CONTRACT

Six precise routes.
No secret fields.

Run the separate native service locally. JSON fields named like a mnemonic, seed, private key, WIF or preimage are rejected with HTTP 400. Bitcoin public keys must be 33-byte compressed secp256k1 keys.

Machine-readable OpenAPI 3.1

Exact route paths, public request fields, unsigned response artifacts and error shape. The only server listed is your local process; importing this file does not connect to a hosted API.

Download API contract ↓

LOCAL SERVICE / DEFAULT BIND127.0.0.1:8787

cd services/pq-shield-api
cargo run
curl http://127.0.0.1:8787/health

POST/vault/address

Build deposit and trigger P2WSH addresses and witness scripts from public keys, H(r) and a CSV delay.

PUBLIC INPUTS

POST/vault/unvault-tx

Return an unsigned deposit → trigger transaction, hot-key sighash and trigger output details.

UNSIGNED TX

POST/vault/branch-a-tx

Prepare the delayed trigger → destination spend and its hot-key sighash.

CSV-DELAYED

POST/vault/clawback-tx

Prepare the immediate recovery-key spend to a fresh, anchored safe destination.

UNSIGNED TX

POST/anchor/commitment

Return canonical anchor bytes for client-side PQ signing and Bloch guard hashes.

SIGN LOCALLY

POST/anchor/verify

Verify a signature against a required trusted_pq_pubkey obtained outside the supplied anchor.

TRUST ROOT REQUIRED

RUN LOCALLY / REGTEST

Build a vault address

This contains only public test inputs. The recovery hash is a demonstration value; derive a unique real H(r) in your own signer for each vault.

Download Node.js client ↓Download offline tests ↓Download client workflow ↓Download route check ↓Download address example ↓Download local contract check ↓Full API reference ↗

Save the client and offline test beside each other, then run node --test pq-shield-client.test.mjs without a service. For the live regtest examples, start the Rust API on loopback and run node client-workflow.mjs or node client-routes-check.mjs. The client validates response shapes and rejects secret-shaped request fields; these checks do not independently verify Bitcoin transaction bytes or PQ signatures. The scripts use dummy outpoints and never sign or broadcast. A valid signature requires a separately enrolled client-side PQ signer. The older single-route example and contract check remain available.

REGTEST / PUBLIC DATA ONLY

curl -sS http://127.0.0.1:8787/vault/address \
  -H 'Content-Type: application/json' \
  -d '{
    "network": "regtest",
    "hot_pubkey": "0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
    "recovery_pubkey": "02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5",
    "recovery_hash": "5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a",
    "csv_delay": 144
  }'

PUBLIC-INPUT CONTRACT

Map each request to its signer boundary.

The API returns construction artifacts. A local signer must validate every address, amount, outpoint and sighash before signing. None of these routes broadcasts a transaction.

01 / ADDRESS

`/vault/address`

network is bitcoin, testnet, signet or regtest. Supply compressed hot_pubkey and recovery_pubkey, a 32-byte SHA-256 recovery_hash, and csv_delay as a 16-bit integer. Keep its preimage private.

02 / UNSIGNED SPENDS

`/vault/*-tx`

Repeat public vault parameters under vault. Provide the relevant deposit_outpoint or trigger_outpoint (txid and vout), input amount in satoshis, destination and fee_sat. The response includes unsigned_tx_hex and a signer-specific sighash_hex.

03 / ANCHOR

`/anchor/commitment`

Supply target chain, deposit address, recovery hash, PQ public key, designated safe destination, delay and policy. Sign only the returned commitment_bytes_hex in your own signer. A target-chain label is metadata; it does not deploy an adapter or change that chain's rules.

04 / VERIFY

`/anchor/verify`

Supply a signed anchor and trusted_pq_pubkey obtained independently through an authenticated registration. Compare the returned valid and reason; never treat the key carried inside the anchor as its own trust root.

For machine-readable payloads and response fields, download the OpenAPI contract; the service README explains the flow. The example deliberately stops before funding, signing or broadcasting.

03 / SECURITY BOUNDARY

Trust is explicit.

A valid anchor signature matters only when your application already knows which PQ public key belongs to the owner. The anchor's own key cannot authenticate itself.

01 / CLIENT

Keys remain local

Keep Bitcoin hot and recovery private keys, the PQ secret key and preimage r in your signer. Use a dedicated hardened derivation branch for new vault keys.

02 / VERIFIER

Bring the trust root

/anchor/verify requires trusted_pq_pubkey from registration or another authenticated channel.

03 / WATCHTOWER

Stay online during Δ

Recovery relies on detection and a successful transaction race before the delayed branch matures.

04 / BITCOIN

Know consensus limits

Bitcoin still validates classical signatures. An external PQ anchor does not make native Bitcoin assets unconditionally quantum secure.

Not qualified for production custody.

The crate and service have no independent production security qualification. Bloch-side PQ enforcement is not consensus-wired. Bitcoin covenant limits, exposed or reused keys, offline monitoring and preimage fee races remain material risks.

04 / INTEGRATION PATH

From reference
to partner pilots.

Only the Bitcoin construction and anchor verification API described above are implemented here. Chain names accepted by the anchor format do not mean vaults or adapters exist on those chains.

AVAILABLE IN SOURCE

Bitcoin reference

Local Rust service with public-input construction, unsigned transaction preparation and anchor verification.

BEFORE VALUE

Security qualification

Independent review, adversarial tests, watchtower operations, signer integration and a deployment contract.

PROPOSED

Partner APIs

Managed access, versioned policies, authenticated calls and operational reporting after qualification.

RESEARCH

Other chains

Separate threat models and chain-specific spend enforcement. No cross-chain vault deployment is represented here.

BUILD FROM THE IMPLEMENTATION

Start with source.
Keep your keys.

Review the route contract and honest limits, then run the reference service in an isolated environment.

Open implementation ↗