feat(crypto): add post-quantum signature support for nile

[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.

This PR currently supports two PQ schemes:

• FN_DSA_512 / Falcon-512
• ML_DSA_44 / Dilithium-2

Each scheme is independently gated by a committee proposal and dispatched through PQSchemeRegistry.

Protocol changes

• Adds PQScheme with UNKNOWN_PQ_SCHEME, FN_DSA_512, and ML_DSA_44.
• Adds PQAuthSig { scheme, public_key, signature } as the common PQ authentication envelope.
• Adds repeated pq_auth_sig to Transaction so ECDSA signatures and PQ signatures can co-exist for account permission threshold checks.
• Adds pq_auth_sig to BlockHeader; block headers must use either legacy witness_signature or PQ pq_auth_sig.
• Adds pq_auth_sig to HelloMessage for fast-forward / relay authentication by PQ witnesses.

Address derivation

• PQ addresses are derived as 0x41 || deriveHash(scheme, public_key)[12..32].
• Current schemes use Keccak-256 for address derivation.
• PQSchemeRegistry.computeAddress(scheme, publicKey) is the single address derivation entry point.

Crypto module

• Adds FNDSA512 for Falcon-512 signing and verification.
• Adds MLDSA44 for ML-DSA-44 signing and verification.
• Adds PQSignature, PQSchemeRegistry, and PqKeypair as the shared PQ abstraction layer.
• Falcon signatures are variable-length and validated against the canonical range.
• ML-DSA-44 signatures are fixed-length.
• Scheme-specific key lengths, signature lengths, seed handling, sign, verify, and address derivation are centralized in PQSchemeRegistry.

Governance and activation

• Adds ALLOW_FN_DSA_512 proposal parameter.
• Adds ALLOW_ML_DSA_44 proposal parameter.
• Proposal validation is fork-gated on VERSION_4_8_2.
• Runtime checks reject PQ signatures whose specific scheme has not been activated.
• VM precompile registration is controlled by the corresponding VMConfig flags.

Witness and consensus support

• Adds PQ witness key configuration via localwitness_pq.keys.
• Each PQ witness entry declares its own scheme and provides either expanded key material or a supported deterministic seed.
• PQ-only witnesses can derive their witness address from the configured PQ public key when no explicit witness address is set.
• Consensus miners now 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 active on chain.

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.
• PQ signatures are rejected before activation.
• Shielded-transfer validation rejects transparent/PQ signatures on shielded-from transactions.

Block validation

• Block signature validation supports both legacy ECDSA and PQ signatures.
• PQ block signatures are accepted only when the scheme is registered and activated.
• The derived PQ address must match the witness permission address.
• Legacy and PQ block signatures are mutually exclusive.

TVM precompiles

• 0x16 verifyFnDsa512: single Falcon-512 verification.
• 0x18 batchValidateFnDsa512: batch Falcon-512 verification with bitmap result.
• 0x12 verifyMlDsa44Eip8051: EIP-8051 VERIFY_MLDSA verification using [msg 32B | sig 2420B | expandedPk 20512B].
• 0x19 verifyMlDsa44: existing TRON draft ML-DSA-44 verification using the standard 1312-byte public key.
• 0x1a validateMultiPQSig: unified ECDSA + PQ account-permission threshold verification.
• 0x1b batchValidateMlDsa44: batch ML-DSA-44 verification with bitmap result.

Relay / fast-forward support

• RelayService can sign and verify HelloMessage using either legacy signatures or PQAuthSig.
• PQ hello-message verification checks scheme registration, activation state, key length, signature length, address binding, and cryptographic validity.
• Legacy and PQ hello-message signatures are mutually exclusive.

Compatibility

• Pre-activation behavior remains legacy-only; PQ fields are rejected when no PQ scheme is active.
• PQ schemes are independently activated, so enabling one scheme does not implicitly enable the other.
• UNKNOWN_PQ_SCHEME is reserved and never treated as a valid signing scheme.
• Existing ECDSA transaction and block signing paths remain supported.

Tests

• Adds unit tests for Falcon-512 and ML-DSA-44 sign/verify behavior.
• Adds KAT regression tests for both PQ schemes.
• Adds PQSchemeRegistry and PQSignature tests.
• Adds TVM tests for single, batch, EIP-8051 ML-DSA address handling, and unified multi-sign PQ precompiles.
• Adds transaction and block capsule tests for PQ authentication.
• Adds witness config, proposal, relay, bandwidth, JSON, and account-permission tests.
• Adds demo programs for PQ witness/full node/client/transaction flows.

---

Summary by cubic

Adds post-quantum signatures to Nile with FN-DSA-512 (Falcon-512) and ML-DSA-44, including new TX/block auth, VM precompiles, and governance-controlled activation at fork v4.8.2. ECDSA paths remain unchanged.

• New Features

  • Protocol: added PQScheme enum and PQAuthSig message; TXs and blocks can carry per-signer PQ auth bound to Permission.keys[].address via scheme-specific address derivation.
  • Consensus/Config: PQ witness signing supported with localPqWitnessAccountAddress and localwitness_pq.keys config; LocalWitnesses and DPoS miner paths accept PQ keypairs.
  • VM: new precompiles for ML-DSA-44 (EIP-8051) and FN-DSA-512 verify, plus batch-verify; gated by VMConfig.allowMlDsa44/allowFnDsa512.
  • Governance: new proposals ALLOW_FN_DSA_512 and ALLOW_ML_DSA_44; activated only after VERSION_4_8_2. Chain parameters expose getAllowFnDsa512 and getAllowMlDsa44.
  • Runtime: signature weight and size checks accept variable-length PQ sigs; bandwidth accounting subtracts PQAuthSig bytes; added TX fetch and handshake latency histograms.
  • Dependencies: upgraded org.bouncycastle:bcprov-jdk18on to 1.84.

• Migration

  • Upgrade to block version 36 (v4.8.2).
  • Enable schemes via governance proposals (ALLOW_FN_DSA_512, ALLOW_ML_DSA_44).
  • For PQ-signing SRs, set localPqWitnessAccountAddress and define localwitness_pq.keys entries with scheme and key or seed; restart the node.
  • Precompiles become available only after the corresponding VM flags are enabled by the proposals. ECDSA nodes require no changes.

[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: 9ab62b41-89a0-4551-a31c-438753734714

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 nile-testnet/pq-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]

4 issues found across 72 files

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

Re-trigger cubic</sub>