PQHD Integration
Tidecoin wallet integration uses the Bitcoin Core descriptor-wallet model, but post-quantum keys are derived through PQHD instead of BIP32. PQHD has no xpub equivalent and no public child derivation. Integrations should treat PQHD seed material like signing key material, not like watch-only metadata.
This page is the integration guide for wallet builders and custodial systems. It is not the PQHD cryptographic specification; see PQHD Wallet for derivation rules and PSBT and Offline Signing for PSBT byte layout.
Descriptor form
PQHD key expressions use a 32-byte seed ID, encoded as 64 hex characters, and a six-element hardened path:
pqhd(<seedid32>)/10007h/6868h/<scheme>h/<account>h/<change>h/<index>hRanged receive and change descriptors use a hardened wildcard in the final position:
wpkh(pqhd(<seedid32>)/10007h/6868h/7h/0h/0h/*h)
wpkh(pqhd(<seedid32>)/10007h/6868h/7h/0h/1h/*h)Descriptor parsing rules:
| Rule | Requirement |
|---|---|
| Seed ID | 32 bytes, displayed as 64 hex characters. |
| Path length | Exactly six elements after pqhd(...). |
| Hardened-only | Every element must be hardened. |
| Purpose | 10007h. |
| Coin type | 6868h. |
| Change | 0h for receive, 1h for change. |
| Wildcard | If present, must be the final *h element. |
| BIP32 | xpub and xprv descriptors are not PQHD substitutes. |
Scheme policy
The path’s scheme element is the same numeric scheme prefix used by serialized PQ public keys:
| Path element | Scheme | Mainnet policy |
|---|---|---|
7h | Falcon-512 | Live. |
8h | Falcon-1024 | Gated by AuxPoW activation. |
9h | ML-DSA-44 | Gated by AuxPoW activation. |
10h | ML-DSA-65 | Gated by AuxPoW activation. |
11h | ML-DSA-87 | Gated by AuxPoW activation. |
Mainnet integrations should default to Falcon-512 until the active chain rules allow other schemes. Testnet and regtest are useful for exercising the post-AuxPoW schemes before mainnet activation.
Seed management RPC
Tidecoin Core exposes wallet RPCs for PQHD seed inventory and policy:
| Command | Purpose |
|---|---|
listpqhdseeds | List seed IDs tracked by the loaded wallet. |
importpqhdseed | Import a 32-byte PQHD master seed. |
setpqhdseed | Select default receive and change seed IDs. |
removepqhdseed | Remove a non-default seed not referenced by wallet descriptors. |
setpqhdpolicy | Select default receive and change signature schemes. |
Use wallet-scoped RPC:
tidecoin-cli -rpcwallet="hot" listpqhdseeds
tidecoin-cli -rpcwallet="hot" setpqhdpolicy "falcon-512" "falcon-512"Do not log master seed material. Seed IDs are identifiers, not secrets, but they still reveal wallet structure and should be treated as operational metadata.
Watch-only and offline signing boundary
An online watch-only wallet can know descriptors, scripts, addresses, UTXOs, and PQHD origin metadata. It should not know PQHD master seeds. An offline signer needs the seed material plus enough PSBT metadata to reconstruct the derivation path for each signing key.
Typical split:
| Component | Holds seeds | Holds descriptors | Role |
|---|---|---|---|
| Online watch wallet | No | Yes | Tracks UTXOs and creates PSBTs. |
| Offline signer | Yes | Yes or imported metadata | Signs PSBTs. |
| Broadcaster | No | Optional | Runs testmempoolaccept and broadcasts final hex. |
When a PSBT must cross this boundary, request PQHD origin metadata with the
wallet RPC option include_pqhd_origins where the command supports it.
Integration workflow
For an application-controlled wallet:
- Create or load a descriptor wallet.
- Import or generate PQHD seed material.
- Set receive and change seed defaults.
- Set receive and change scheme policy.
- Generate receive descriptors and addresses.
- Create transactions through wallet RPC or PSBT.
- Verify fee sizing with Tidecoin PQ signature sizes.
- Test final transactions with
testmempoolaccept.
For a watch-only or cold-signing setup:
- Keep seed material offline.
- Import descriptors or watch-only address data online.
- Create an unsigned funded PSBT online.
- Include PQHD origin records when offline signing requires them.
- Transfer the PSBT to the offline signer.
- Sign and finalize offline.
- Return final hex or finalized PSBT to the online broadcaster.
- Broadcast and monitor confirmation status.
Failure cases to handle
| Failure | Integration response |
|---|---|
Descriptor rejects pqhd(...) | Check seed ID length, six hardened path elements, purpose, coin type, scheme, and change branch. |
| Scheme rejected before AuxPoW | Fall back to an allowed scheme for that network and height. |
| Missing PQHD seed | Import or select the seed before signing. |
removepqhdseed fails | The seed is default or still referenced by descriptors. Do not force removal. |
| Offline signer cannot locate derivation | Include PQHD origin metadata in the PSBT or import matching descriptors. |
| Fee too low or transaction too large | Recompute vbytes using PQ signature sizes. |
Source of truth
| Topic | Source |
|---|---|
| PQHD derivation and path rules | PQHD Wallet |
| Descriptor parser | ../tidecoin/src/script/descriptor.cpp |
| Wallet seed and policy RPCs | ../tidecoin/src/wallet/rpc/wallet.cpp |
| PQHD wallet descriptors | ../tidecoin/src/wallet/walletutil.cpp |
| PSBT origin records | PSBT and Offline Signing |
See also: Wallets / PQHD Wallets, Transaction Size & Fees, RPC Reference.