refactor(pq): unify quantum signing with the local-key path; alias algosdk to the PQ fork [PERA-4653]

[fmsouza]

Description

Addresses the PQ-023 review feedback: quantum (post-quantum / Falcon-1024) accounts had an entirely separate signing route, when "falcon is just another key type". This collapses that route into the ordinary local-key path, models the PQ signature generically, installs Joe's fork under the official package name, and removes the remaining mocks.

⚠️ This closes a live signing bug. Quantum transactions were being Falcon-signed over txn.bytesToSign() un-digested, when the protocol requires the SHA-512/256 digest. The old adapter hid it behind a signer callback that ignored the bytes algosdk handed it, and because no algod verifies pqsig yet, nothing could catch it. Signing now goes through pqSigningDigest(txn) = sha512_256(txn.bytesToSign()), pinned byte-for-byte against algosdk's own PQ signer by a differential test.

Signing is unified — quantum is a localKey signer

ResolvedSignerType is back to 'localKey' | 'hardware' | 'multisig'. Deleted: the machine's quantum state, quantumSignerActor, createQuantumStrategy, useQuantumTransactionSigner, the signQuantumTransactions dependency, and the quantum branches in determineSignerType / getSigningStrategy (including the ordering hazard that forced quantum to be tested before hasSigningKeys).

What remains is one branch, in useLocalKeyTransactionSigner — same altitude as the existing algo25-vs-HD difference: which bytes to sign, and whether the signature lands in sig or pqsig.

Generic PQ signature model

PQSignature { schemeId, publicKey, signature } plus a scheme registry, replacing the Falcon-specific falconSignature field. The opaque QuantumSignedTransaction { txn, pqSignedBytes } byte carrier is gone — a PQ transaction is now a real SignedTransaction with a pqsig, so isQuantumSignedTransaction, PeraSignedTxnResult, the encodeSignedTransaction carrier branch and the compactSignedResults narrowing seam all disappear. SignerInfo.signatures carries real values instead of null.

Joe's fork, installed under the official name

algosdk resolves to npm:@joe-p/algosdk@3.7.0-beta.1 via catalog alias + global override, so application code imports only algosdk. The fork is version 3.7.0-beta.1 — a future official release — so swap-back is a specifier change. Falcon itself has no official counterpart package (falcon-1024 and @joe-p/react-native-falcon are both Joe's), so it got build-time provider selection instead: getPQProvider.ts (WASM) / getPQProvider.native.ts (Nitro), replacing an if (navigator.product === 'ReactNative') runtime check.

Bugs fixed alongside

• ARC-60 was an unreachable success path for quantum — the strategy routed quantum's arc60 case into a hook that then threw unsupported account type quantum. It can only ever have failed.
• Multisig participation disagreed with itself across three code paths. canSignViaParticipants excluded quantum; getLocalParticipants and getLocalUnsignedSigners (wired to the real Sign button) admitted it — so a Falcon signature could be produced for an Ed25519 slot. All three now agree, per algosdk's own FALCON-1024 does not support multisig signing.
• Stale webview gate — quantum reported as 'Unsignable', deferring to PQ-006 which shipped. It now reports a new Quantum type rather than being aliased onto 'Algo25', since a dApp told "Ed25519" would be handed a ~1.2 KB Falcon signature it cannot verify.
• Swap guard retargeted onto its real cause. Quantum swap is blocked server-side: swap groups interleave backend pre-signed transactions with the user's, quantum needs a raised fee, and raising it forces a grp recomputation that invalidates the backend's signatures. The guard now says so, resolves the effective signer (so rekeyed-to-quantum can't slip past), and covers the previously-unguarded propose path.

Mocks removed

Dead FALCON_PUBLIC_KEY_LENGTH / FALCON_SIGNATURE_LENGTH (one contradicted the documented ≤1232 B bound), the web shim's FALCON_DET1024_PUBKEY_SIZE = 0 silent-zero placeholder (now throws), and a batch of stale comments and docs.

One "mock" is deliberately kept: commitQuantumChildKey still writes via the keystore's low-level commit(), because @algorandfoundation/keystore@1.0.0-canary.17 ships generators for seed / ed25519 / XHD-root / secret-key only — there is no Falcon generator to call. It isn't really a mock (it stores a real Falcon public key in the same encrypted namespace); the misleading MOCK label is gone and replaced with the upstream gap and its removal condition.

Related Issues

• Closes https://algorandfoundation.atlassian.net/browse/PERA-4653
• Epic: https://algorandfoundation.atlassian.net/browse/PERA-4481
• Follow-up dependency: quantum swap needs backend support (PQ fee at prepare-transactions, or isolating the user's txn in its own partition) — PERA-4705 / PQ-024

Checklist

• Have you tested your changes locally?
• Have you reviewed the code for any potential issues?
• Have you documented any necessary changes in the project's documentation?
• Have you added any necessary tests for your changes?
• Have you updated any relevant dependencies?

Additional Notes

Reviewer note: no algod accepts pqsig yet

Verified directly — LocalNet (algod 4.7.4-stable) rejects it, and so does algorand/algod:nightly build 2680, with the same error it gives an unknown field. So pnpm localnet:quantum-check reporting PENDING at exit 0 is the designed outcome, not a failure. It asserts everything up to submission (derivation, funding, the signing preimage, byte-equality vs algosdk's signer) and flips to a real end-to-end PASS unedited the day a pqsig node ships. Please don't "fix" its tier logic — the narrow PQSIG_UNSUPPORTED match is what makes it meaningful.

pnpm check:single-algosdk exists for a reason

Two algosdk copies break cross-boundary instanceof Transaction / instanceof Address and msgpack schema identity. This branch's alias silently drifted mid-development — four importers reverted to stock algosdk@3.6.0 via pnpm's peer auto-install, and only a full-tree build failure caught it. Every algokit-utils dependent now pins algosdk directly, and a pre-push guard fails loudly (and fail-closed on an unparseable lockfile) if a second resolution ever appears.

Known limitations, documented not fixed

• Rekeying to a quantum account strands funds until a pqsig algod ships — the rekey-back transaction also needs a pqsig. Gated behind enable_quantum_accounts (default off). The warning in packages/accounts/src/utils.ts is deliberately blunt about this.
• Scheme-genericity is real for the signing path, not everywhere. Transaction assembly and signing are scheme-agnostic; the fee-multiplier shape (one pqMultiplier) and quantumSignKeyId's one-child-per-seed id are genuine second-scheme blockers, now named in schemes.ts and the integration doc rather than glossed.
• Quantum ARC-60 produces a signature no Ed25519-expecting verifier can check. Intentional — consistent with quantum being just another key type, and ARC-60 needs a PQ story regardless.
• Pre-existing, untouched: useProgramSigner admits quantum for logicsig with the wrong PQ preimage (not reachable — card funding excludes quantum); fee delegation has no PQ fee adjustment; tools/ sits outside lint and the PQ import firewall.

Verification

Full suite green on a forced, uncached run: 103/103 turbo tasks, 604 test files, 4371 tests. pnpm pre-push 7/7. Integration suite 101 files / 347 tests, including 13 quantum flow tests.

Design and plan: docs/superpowers/specs/2026-07-28-pq-implementation-revisit-design.md, docs/superpowers/plans/2026-07-28-pq-implementation-revisit.md (gitignored locally).

🤖 Generated with Claude Code

[wjbeau]

This looks much cleaner. @fmsouza my only concern is that we're pinning joe-p's algosdk which is the right way to go but if we merge this now it will leak it out into production which is a little suspect to me. Will the app build against the official algosdk and if so do you think we should make that the default and add a commented out joe-p pin that we can easily enable locally for testing until we have our official release out and also a more official algosdk pq supporting build? wdyt?

[fmsouza]

@wjbeau yes, that's exactly why we had the fork hidden under a different alias before with some duplication. The types are bisecting in some of the main branches to accomodate the changes to let the transaction type have the format from the fork which holds the pq signature as well. So to clean up the code we need to promote it to the official slot temporarily until the official algosdk release comes.

I've tried to investigate an alternative in which the blast radius would be self-contained to PQ specific code without touching production code for the rest of the account types, but couldn't find a good way around it without needing to add a lot of type format manipulation to make sure the transaction signing pipeline would be able to sign quantum transactions as well.

So I'd say we either keep it like this and potentially push next build to the beta testers using Joe's fork until PQ is available on the official algosdk lib, or maybe we hold this PR for a bit longer and only wrap up and merge once the official sdk is released.

If you have different ideas or thoughts which could help mitigate this issue, I'm listening.

[wjbeau]

What about, as an exception just creating a long running feature branch? We can build bitrise builds from any branch manually so we could always kick out a QA build from that branch until things are a bit more stable and then merge everything back to main? Not our ideal flow, but given the weirdness around the dependencies in this case I think it's a justifiable option?

[fmsouza]

Yeah, I think that sounds fair. Should we use it as the feature branch in this case? I've just demoted this branch to a draft.

[fmsouza]

Superseded by #1062.

Changing strategy: rather than merging this into main, the work moves to a long-lived feature branch (feat/quantum) and stays there until the blocker clears.

Why: this work requires algosdk to be aliased to the PQ fork tree-wide, because official algosdk has no pqsig field and so cannot represent a post-quantum signature at all. Narrowing the alias to quantum-only code was measured and doesn't work — the two copies have distinct class identities, so only bytes can cross the boundary, and official decodeSignedTransaction silently drops pqsig. Details in #1062.

Swapping the SDK underneath the whole production app to reach a flag-dark feature isn't a stability trade worth making on main. Same commits, no work lost — #1062 continues from here.