---

title: PQ Migration — Self-Custody Demonstration Workflow

audience: substrate_operators_industry_consumers

game: WIKI-PQ-MIGRATION-SELF-CUSTODY-001

contract_version: 1.0.0

authority_kind: normative

---

PQ Migration — Self-Custody Demonstration Workflow

What this page is for. Any GaiaFTCL substrate operator can demonstrate, on their own machine and against their own wallet, that the substrate composes a post-quantum migration end-to-end with substrate-cosigned evidence at every step. No third-party keys. No live spend. Just operator proves operator controls both ends; substrate seals the receipt.

Patents: USPTO 19/460,960 · USPTO 19/096,071 — © 2026 Richard Gillespie

---

Scope discipline (locked)

The substrate refuses to compose a migration evidence chain unless the operator controls both ends:

Proof-of-ownership is the operator signing a substrate-composed challenge with each key. Both signatures verify or the V194 receipt does not seal. The substrate does not write V194 rows for third-party verifications. The substrate does not compose Bitcoin transactions in this workflow.

Why this is the right starting point

The PQ migration substrate operates honestly without ever broadcasting a transaction. The operator demonstrates:

1. The Shor reduction chain is real (existing shor break-classical ladder: RSA + secp256k1 ECDLP (P256K, Q-only) + Lean kernel seal).

2. The PQ wallet generates through a bound reference library (operator-pinned SHA-256).

3. The migrated PQ wallet is Shor-safe by the FIPS 204/205 reductions.

4. The operator controls both ends of the migration via challenge-response signatures.

Federation-cosigned evidence at each step. Append-only schemas. Replay-bit-exact. The substrate's role ends at the sealed receipt; whether the operator subsequently broadcasts a real Bitcoin spend is the operator's decision through the operator's existing wallet tooling, not the substrate's.

The five evidence rows

Row Schema What it seals
V188 substrate_shor_demonstration_history Shor reduction chain ran; secp256k1 ECDLP witness verified
V189 substrate_pq_wallet_migration_history PQ keypair generated through reference library; P2PQH address derived
V190 substrate_shor_pq_safety_demonstration_history Substrate-mathematical rationale for PQ Shor-safety sealed
V193 substrate_pq_ownership_verification_history Operator signed challenge with both source secp256k1 key and destination PQ key; both signatures verified
V194 substrate_pq_migration_demonstration Single-row receipt linking V188 → V189 → V190 → V193

Each row carries canonical_witness, witness_hash_sha256, and signature_quintet columns. Federation cosignature seals every row. Append-only DELETE + UPDATE triggers prevent rewriting history.

Workflow

Step 0 — Bind the PQ reference library

Until the operator binds, the substrate refuses to generate PQ keys. The substrate-honest scaffold at cells/xcode/Sources/VQbit/PureOO/PostQuantumReferenceLibraryPins.swift carries empty pins; the operator records:

public static let mlDSA87 = PostQuantumReferenceLibraryPin(
    schemeIdentifier: "ml-dsa-87",
    sourceURL: "https://github.com/pq-crystals/dilithium",
    pinnedSHA256: "<operator-verified-sha-256>",
    pinnedAtISO: "<operator-pin-iso>",
    federationCosigned: true)

After re-build, PureOOMLDSA87Scheme.referenceLibraryLinked returns true. PQ keypair generation operates against the bound library.

Step 1 — Shor demonstration (math chain)

gaiaftcl shor break-classical

Runs:

Exit 0 when all three legs pass. The RSA semiprime ladder plus secp256k1 ECDLP witness demonstrates the reduction chain on live curve arithmetic. Mainnet secp256k1 Shor convergence remains substrate-development beyond current substrate capability — the substrate refuses to fabricate convergence claims it has not composed.

When run with --wallet-label and --operator-confirmation, the command writes a V188 row with terminal substrate_convergence_incomplete (honest acknowledgement of the mainnet gap).

Step 2 — PQ wallet migration

gaiaftcl wallet pq migrate \
    --secp256k1-wallet-label my-wallet \
    --pq-scheme ml-dsa-87 \
    --associated-demonstration-id <v188_id>

Generates the PQ keypair through PureOOMLDSA87Scheme.generateKeypair() (refuses if reference library is not operator-bound). Derives P2PQH address via the BIP P2PQH reference implementation. Writes V189 with the one-gate-closure witness hash.

Step 3 — PQ-safety proof

gaiaftcl shor prove-pq-safe --migration-id <v189_id>

Composes the substrate-mathematical rationale: ML-DSA security reduces to MLWE/MSIS (lattice problems with no hidden subgroup structure for Shor's QFT); SLH-DSA security reduces to hash preimage resistance (Grover-shaped, not Shor-shaped). Writes V190 with terminal substrate_proven_safe.

Step 4 — Ownership verification

The operator signs a substrate-composed challenge with both keys:

gaiaftcl wallet pq verify-ownership \
    --migration-id <v189_id> \
    --source-secp256k1-public-key-hex <hex> \
    --source-secp256k1-signature-hex <hex> \
    --destination-pq-signature-hex <hex>

The substrate composes the challenge from (migration_id || source_pubkey || destination_address || v189_witness || timestamp). The operator signs this challenge with the source secp256k1 key (via their existing wallet tooling) and the destination PQ key (via their bound PQ scheme).

Both verifications must pass for verification_terminal = both_ends_verified. Single-end failures write the specific terminal (source_secp256k1_unverified or destination_pq_unverified).

Step 5 — Demonstration receipt

gaiaftcl wallet pq demonstration-receipt \
    --migration-id <v189_id> \
    --verification-id <v193_id>

Assembles a V194 single-row receipt linking V188 + V189 + V190 + V193. Substrate refuses to seal V194 unless V193 terminal is both_ends_verified. The UNIQUE constraint on (operator_identifier, wallet_label) prevents duplicate receipts for the same wallet.

V194 terminal self_custody_migration_sealed is the operator's substrate-cosigned proof that they migrated their own wallet end-to-end with both-ends control.

What this demonstrates — and what it doesn't

Demonstrates:

Does not demonstrate:

Federation participation

Operators participating in the federation mesh can publish their V188 / V189 / V190 / V193 / V194 rows to the federation bus for cross-cell verification. Federation cosignature on each row makes the receipt verifiable on any participating cell without exposing the operator's private keys.

NATS subjects:

Operators publish at their discretion. Substrate cell remains sovereign.

Files of record

---

*The operator runs the demonstration on their own machine. The substrate seals the evidence. The migration is operator-action; the substrate provides the mechanism.*

Federation cosignature: pending operator signing host (v26). Witness (sha256 of rendered body): 02e266a435938bcf99f3d28eae78b1ad5338b07d18700e327babd1f3fe0374c6. This page serves with a substrate-honest pending-signature notice until the operator's Franklin signer cosigns it.