Skip to content

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:

  • Source secp256k1 key — the wallet the operator is migrating away from.
  • Destination PQ key — the new UUM-8D-safed PQ wallet generated through Franklin's PostQuantumSchemeRegistry.

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 + ECDLP toy curve + 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; toy curve fixture 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: - RSA verify_shor ladder against three sealed semiprimes - ECDLP verify_shor_ecdlp toy curve fixture (canonical k mod n) - Lean kernel gate on FirstRoars/ShorFactorLarge.lean

Exit 0 when all three legs pass. The toy-curve ladder demonstrates the reduction chain mathematically. 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: - The PQ migration substrate composes through Franklin's surface. - The PQ reference library binding produces real keypairs. - The substrate-mathematical rationale for PQ Shor-safety is sealed against the cryptographic literature. - The operator can prove control of both ends through challenge-response. - The full chain is replay-bit-exact and append-only.

Does not demonstrate: - Live Shor against mainnet secp256k1 keys (substrate-development beyond current capability; deferred). - Bitcoin transaction composition or broadcast (out of scope by design). - Third-party wallet recovery (not what the substrate is for).

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: - gaiaftcl.substrate.shor_demonstration.sealed - gaiaftcl.substrate.pq_wallet_migration.sealed - gaiaftcl.substrate.shor_pq_safety_demonstration.sealed - gaiaftcl.substrate.pq_ownership_verification.sealed - gaiaftcl.substrate.pq_migration_demonstration.sealed

Operators publish at their discretion. Substrate cell remains sovereign.

Files of record

  • cells/xcode/Sources/VQbit/PureOO/PostQuantumReferenceLibraryPins.swift — operator-edited pin registry
  • cells/xcode/Sources/VQbit/PureOO/PostQuantumSignatureScheme.swift — protocol + ML-DSA-87/65 + SLH-DSA-128s conforming types
  • cells/xcode/Sources/VQbit/PureOO/PostQuantumSchemeRegistry.swift — singleton registry
  • cells/xcode/Sources/VQbit/PureOO/P2PQHScript.swift — P2PQH script composition
  • cells/xcode/Sources/GaiaFTCLCore/NarratorSchemaV193.swift — ownership verification schema
  • cells/xcode/Sources/GaiaFTCLCore/NarratorSchemaV194.swift — demonstration receipt schema
  • cells/xcode/Sources/GaiaFTCLCLI/Commands/WalletPQVerifyOwnershipCommand.swift — verify-ownership CLI
  • cells/xcode/Sources/GaiaFTCLCLI/Commands/WalletPQDemonstrationReceiptCommand.swift — receipt CLI
  • wiki/Lion-PQ-Wallet-Standard.md — parent standard (five-layer floor + HALT-1 + HALT-2)
  • cells/xcode/docs/bips/bip-p2pqh.md — BIP-shape spec for P2PQH

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-cosigned

This page's source is sealed in the GaiaFTCL federation manifest — page SHA-256 078b1c53977fa77a…, manifest witness a090592e0609adc8…, signed 2026-06-02T18:58:22Z by cell gaiaftcl-mac-cell. Verify with gaiaftcl wiki sign --all and compare wiki-all-signatures.json.