feat(crypto): add post-quantum signature support

[Federico2014]

Summary

Adds post-quantum (PQ) signature support to TRON across protocol, crypto, transaction/block validation, TVM precompiles, witness configuration, consensus signing, relay handshakes, governance flags, and tests.

Two PQ schemes are supported, each independently gated by a committee proposal:

• FN_DSA_512 / Falcon-512 (variable-length signature, max 667 B, pubkey 896 B)
• ML_DSA_44 / Dilithium-2 (fixed-length signature 2420 B, pubkey 1312 B)

---

Protocol changes

• Adds PQScheme enum: UNKNOWN_PQ_SCHEME, FN_DSA_512, ML_DSA_44.
• Adds PQAuthSig { scheme, public_key, signature } as the shared PQ authentication envelope.
• Adds repeated pq_auth_sig to Transaction so ECDSA and PQ signatures coexist for account permission threshold checks.
• Adds pq_auth_sig to BlockHeader; legacy witness_signature and PQ pq_auth_sig are mutually exclusive.
• Adds pq_auth_sig to HelloMessage for relay/fast-forward authentication by PQ witnesses.

Address derivation

• PQ addresses: 0x41 || deriveHash(scheme, public_key)[12..32], matching the ECDSA shape.
• Both schemes use Keccak-256 as the fingerprint hash.
• PQSchemeRegistry.computeAddress(scheme, publicKey) is the single entry point.

Crypto module (crypto)

• FNDSA512: Falcon-512 sign/verify; variable-length signatures validated against the canonical [SIGNATURE_MIN_LENGTH, SIGNATURE_MAX_LENGTH] range.
• MLDSA44: ML-DSA-44 sign/verify; fixed-length 2420-byte signatures.
• PQSignature, PQSchemeRegistry, PqKeypair: shared PQ abstraction layer.
• PQSchemeRegistry centralises key lengths, signature lengths, seed handling, address derivation, sign, verify, and block-size wire-size computation (computePQAuthSigWireSize).

Governance and activation

• Adds ALLOW_FN_DSA_512 (proposal id 99) and ALLOW_ML_DSA_44 (proposal id 100).
• Both proposals are fork-gated on VERSION_4_8_2.
• Runtime checks reject PQ signatures and precompile calls when the scheme is not yet active.

Witness configuration

• PQ witness keys are configured via localPqWitness.keys — a list of paths to JSON key files (relative paths resolve against the working directory); each file holds one keypair, keeping the long key material out of config.conf.
• Each JSON key file names a scheme and defines exactly one material source:
  • seed — FN_DSA_512: 96 hex chars / 48 B (accepted with a drift warning — Falcon keygen is FFT-based and not bit-stable across JVMs or CPU architectures); ML_DSA_44: 64 hex chars / 32 B (deterministic, accepted without restriction).
  • privateKey — FN_DSA_512 must also supply publicKey (BouncyCastle exposes no API to derive it from the private key); ML_DSA_44 supplies privateKey only (public key is derived, so publicKey must be omitted).
• PqKeyFile (Jackson-bound) is the JSON shape; pq-witness-key.template.json ships as a fill-in template.
• PQ-only witnesses derive their witness address from the configured PQ public key when no explicit localPqWitness.accountAddress is set.
• A node can host a mix of ECDSA and PQ SRs simultaneously.

Consensus and block production

• Consensus miners carry optional PQ key material and sign blocks with the configured PQ scheme.
• Block production fails fast if a PQ miner is configured for a scheme that is not yet active on-chain.
• generateBlock pre-reserves the exact proto3 wire size of pq_auth_sig (via PQSchemeRegistry.computePQAuthSigWireSize) before the transaction packing loop, preventing PQ SR blocks from exceeding the receiver-side maxBlockSize check in BlockMsgHandler.

Transaction validation

• TransactionCapsule validates mixed ECDSA + PQ signatures against the same account permission threshold.
• PQ signer identity is derived from the in-band public key and matched against Permission.keys[].address.
• Duplicate signers are rejected across ECDSA and PQ paths.
• Shielded-transfer validation rejects transparent/PQ signatures on shielded-from transactions.

Block validation

• Block signature validation supports both legacy ECDSA and PQ schemes.
• The derived PQ address must match the on-chain witness permission address.

Bandwidth

• PQ pq_auth_sig bytes are subtracted from net bandwidth as signature overhead (same treatment as ECDSA signature bytes).

Transaction and pending pool limits

• Per-block PQ transaction cap: 1000 (PQ_TRANS_IN_BLOCK_COUNTS).
• Configurable pending pool cap: node.pqTransInPendingMaxCounts (default 1000).

TVM precompiles

• 0x16 verifyFnDsa512: single Falcon-512 signature verification.
• 0x17 batchValidateFnDsa512: batch Falcon-512 verification with bitmap result.
• 0x18 verifyMlDsa44: ML-DSA-44 single verification (standard 1312-byte public key).
• 0x19 batchValidateMlDsa44: batch ML-DSA-44 verification with bitmap result.
• 0x1a validateMultiPQSig: unified ECDSA + PQ account-permission threshold verification.

Relay / fast-forward support

• RelayService signs and verifies HelloMessage using either legacy signatures or PQAuthSig.
• PQ hello-message verification checks scheme registration, activation, key/signature lengths, address binding, and cryptographic validity.

Example module (example:pqc-example)

• New Gradle sub-module example:pqc-example (package org.tron.example.pqc).
• PQWitnessNode: in-process PQ witness node with deterministic keypairs.
• PQFullNode: fullnode that dials PQWitnessNode via P2P and validates PQ-signed blocks.
• PQClient: broadcasts a single PQ-signed transfer transaction.
• PQTxSender: continuous multi-scheme (FN-DSA-512, ML-DSA-44, ECDSA) transfer and TRC20 load generator.
• Run via ./gradlew :example:pqc-example:run -PmainClass=org.tron.example.pqc.PQWitnessNode.

Compatibility

• Pre-activation behavior is legacy-only; PQ fields are rejected when no scheme is active.
• UNKNOWN_PQ_SCHEME is reserved and never treated as a valid signing scheme.
• Existing ECDSA transaction and block signing paths remain fully supported.

Tests

• Unit tests: Falcon-512 and ML-DSA-44 sign/verify, KAT regression, PQSchemeRegistry, PQSignature.
• TVM tests: single, batch, and unified multi-sign PQ precompiles.
• Transaction and block capsule tests for PQ authentication.
• Witness config, proposal, relay, bandwidth, JSON, and account-permission tests.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1ad0886d-847b-4561-b348-df043e8649c9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/pqc-signature-v4.8.2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

7 issues found across 74 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

2 issues found across 10 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

You're iterating quickly on this pull request. To help protect your rate limits, cubic has paused automatic reviews on new pushes for now—when you're ready for another review, comment @cubic-dev-ai review.

[cubic-dev-ai]

You're iterating quickly on this pull request. To help protect your rate limits, cubic has paused automatic reviews on new pushes for now—when you're ready for another review, comment @cubic-dev-ai review.