mirror of https://github.com/luxfi/chains.git synced 2026-09-24 00:26:00 +00:00

Files

T

zeekay d4c7d5440b quantumvm: an accepted block is one the node still holds after a restart

Accept wrote the block, the tip pointer and the height through the version
layer and never committed, so a node that had accepted a thousand blocks came
back from a restart naming genesis — while its peers held it to the tip it had
already told them about. The three writes were also three early returns, so a
failure part-way left the block stored under a tip that named its parent. They
are now one commit with a rollback, alongside the height index that makes
GetBlockIDAtHeight an answer rather than a refusal.

Verify checked only that the parent existed, and only above height one. A
height-one block could name a parent no node has ever seen; any block could
name genesis as the parent of height 500, rewind chain time to revive expired
quantum stamps, or jump forward and expire every stamp in flight. It now sits
on its parent in height and in time, under a skew cap — and BuildBlock never
stamps behind its own parent, so a node whose clock trails a slightly fast peer
does not build blocks it will itself refuse.

Verify held the VM's read lock and then called GetBlock, which takes it again.
Go queues a waiting writer ahead of any later reader, so a build arriving
between the two acquisitions deadlocked the chain with nothing to time out.

The Quasar validator id was the CHAIN id — a field never assigned — so every
node signed as the empty id, each peer's signature arrived as a duplicate of
the first, and no threshold above one could ever be met. It is the node id.
The default threshold was derived from a committee size that had not yet been
defaulted, so a config naming neither got one-of-three. Cleanup released only
FINALIZED entries, which are exactly the ones that do not accumulate. Corona
keyed its PRF off the first 32 bytes of the message, so any shorter message
through StampBlock killed the process; the signature counts were read outside
the lock that appends them.

A transaction whose quantum stamp has aged out never verifies again; left in
the pool it held its slot for good, and enough of them stopped the chain
accepting work. BuildBlock evicts what it could not verify, and re-arms the
builder when the batch limit leaves work behind — the latch holds one signal,
so the remainder had nothing to wake it.

A wire too short to hold the header decoded to height 0, time 0 and the empty
parent rather than failing, so every truncation named one value under as many
ids as an attacker cared to send.

Deleted, all proven unreferenced: the dlopen GPU plugin bridge (a second way to
do what quantum.ParallelVerifyWithThreshold already does through accel), the
stamper package (near-verbatim copy of the signer's accel path, with a
mode-confusion bug the original does not have, and the only reason the tree
needed geth/core), the Q-witness adapter, the NTT helpers (whose inverse did
not invert), and a signature cache that was written and never read — and whose
ids.ToID over a >32-byte input gave every entry the empty id, so all ten
thousand slots were one.

Coverage 20.0% -> 97.0%, with every load-bearing guard mutation-checked.

2026-08-28 08:37:25 -07:00

5.6 KiB

Raw Blame History

Q-chain Virtual Machine (QVM)

The Q-chain Virtual Machine (QVM) hosts the Q lane of Lux's parallel-witness finality model (LP-020 Quasar). When the operator-selected witness set includes WitnessQ (policies PolicyPQ or PolicyQuantum), Q-Chain runs a Corona 2-round threshold ceremony per consensus round and emits the resulting threshold signature as the round's Q-witness. Q-Chain is one of three parallel finality producers (P, Q, Z); adding it does not change finality latency, only parallel verification cost.

The VM also provides per-validator ML-DSA-65 (FIPS 204) identity signatures and a quantum stamp for individual transactions.

Features

Q-witness production (Quasar parallel-witness finality)

Corona threshold (Module-LWE, the two-round Corona construction, eprint 2024/1113): 2-round threshold signing per consensus round, t = ⌊2n/3⌋ + 1 of n validators, combined public key rooted in qchain_ceremony_root.
Per-validator ML-DSA-65 (FIPS 204): identity signatures over round digests, used by the Z lane (chains/zkvm) to produce the Groth16 rollup.
Quantum stamp: time-windowed transaction-level binding.

Performance Optimization

Parallel Transaction Processing: Process multiple transactions concurrently
Configurable Batch Sizes: Optimize throughput based on network conditions
Worker Pool Architecture: Efficient resource utilization with pooled workers

Configuration

The QVM can be configured through the config.Config structure:

type Config struct {
    MaxParallelTxs          int           // Maximum parallel transactions
    QuantumAlgorithmVersion uint32        // 1=ML-DSA-44, 2=ML-DSA-65, 3=ML-DSA-87
    QuantumStampEnabled     bool          // Enable quantum stamp validation
    QuantumStampWindow      time.Duration // Validity window for quantum stamps
    ParallelBatchSize       int           // Batch size for parallel processing
    CoronaEnabled           bool          // Enable Corona key support
    GPUBatchThreshold       int           // Batch size at which GPU verification takes over
}

There is no fee schedule. Q-Chain has no user-payable blockspace (LP-0130 §6): finality-cert inclusion is a validator obligation paid through P-Chain reward distribution, so IssueTx refuses every user transaction whatever it offers, and state advances only through consensus-internal cert aggregation.

Architecture

Core Components

VM (vm.go): Main virtual machine implementation
Factory (factory.go): VM factory for creating QVM instances
Config (config/config.go): Configuration management
Quantum Signer (quantum/signer.go): Quantum signature implementation

Transaction Flow

Transactions are submitted to the transaction pool
Worker threads process transactions in parallel batches
Quantum signatures are verified using the quantum signer
Valid transactions are included in blocks
Blocks are signed at the CONSENSUS layer (Quasar BLS + Corona), never on the wire — the block id is the hash of its own bytes, so a signature inside it would give two honest nodes two ids for one block

RPC API

The QVM exposes the following RPC endpoints:

qvm.getBlock: Retrieve a block by ID
qvm.generateCoronaKey: Generate a new Corona key pair
qvm.verifyQuantumSignature: Verify a quantum signature
qvm.getPendingTransactions: Get pending transactions
qvm.getHealth: Get VM health status
qvm.getConfig: Get current configuration

Security Features

Quantum Signatures

The QVM uses ML-DSA (FIPS 204, NIST module-lattice DSA) for per-validator quantum-resistant signatures:

ML-DSA-44/65/87 supported (NIST Level 2/3/5)
Quantum stamp: time-windowed binding of message + nonce + timestamp, prevents stamp replay
GPU batch verification via accel.DilithiumVerifyBatch (accel.Available(), threshold 64+ signatures)

Validator key material

Two distinct categories live on Q-Chain validators:

Per-validator ML-DSA-65 identity key: MLDSAValidatorKey in quantum/signer.go (kept exposed via the legacy GenerateCoronaKey RPC name). Used for individual round attestations and the Z-witness rollup input.
Corona threshold share: per-validator share of the combined Corona key, produced by the Q-Chain DKG ceremony (rooted in qchain_ceremony_root). Lives in luxfi/threshold/protocols/corona.

Parallel Processing Safety

Thread-safe transaction pool with mutex protection
Isolated worker threads for transaction processing
Atomic operations for state updates

Usage

Creating a QVM Instance

factory := &qvm.Factory{
    Config: config.DefaultConfig(),
}

vm, err := factory.New(logger)
if err != nil {
    return err
}

Initializing the VM

err := vm.Initialize(
    ctx,
    chainRuntime,
    db,
    genesisBytes,
    upgradeBytes,
    configBytes,
    toEngine,
    fxs,
    appSender,
)

Building Blocks

block, err := vm.BuildBlock(ctx)
if err != nil {
    return err
}

Testing

The QVM includes comprehensive error handling and logging for production use:

Error recovery for parallel processing failures
Detailed logging at all levels (Info, Debug, Error)
Health check monitoring
Metrics collection

Future Enhancements

Planned improvements include:

Additional quantum-resistant algorithms (SPHINCS+, Dilithium, Falcon)
Enhanced parallel processing with GPU acceleration
Cross-chain quantum signature verification
Advanced caching strategies for improved performance

5.6 KiB Raw Blame History