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

Files

T

zeekayandHanzo Dev 19a120e632 rust: ask what a refusal says, not only that there was one

The crate measured 74.95% of regions, and the shape of the gap was the point:
lib.rs — the engine, the rounds, the sampler, the identity types — sat at 67%
with 52 of its 123 functions never called by a test at all. A door nothing opens
is a door nobody has checked is a door.

cert.rs already broke one valid certificate at a time and asked whether it still
passed. The new tests ask the other half: when the gate refuses, does the refusal
name the clause that actually failed and carry the numbers to act on? A gate that
refuses everything for one reason is as useless as one that accepts everything,
and the copy-pasted match arm is invisible to a test that only checks for Err.

What the rest found, stated as properties rather than counts: an engine with no
validators counted nobody and let a block through; asking the sampler for a
threshold advanced the FPC phase, so two nodes that asked a different number of
times drew different committees; a validator that shouted its ballot contributed
one vote to the evidence and not many. Each of those is a fork, and each was
reachable through the public API of a crate that read as tested.

99.19% of regions, 99.42% of functions, 167 tests. The remaining six lines are
arms the type system or an earlier clause already excludes — a tier the verifier
refused before the weighted switch sees it, a state lookup its only caller just
created, an Undecided arm of a match reached only when a decision was made.

Two things were left uncovered rather than padded: whether two adjacent block ids
differ (a fact about the host clock, so the test would pass or fail by machine)
and version() == CARGO_PKG_VERSION (tautological). The semver shape is asserted
instead, which catches the plausible mistake.

Tests only — src/ is untouched, and the crate's API has not moved.

Co-authored-by: Hanzo Dev <[email protected]>

2026-09-01 22:01:03 -07:00

benches

…

src

…

tests

rust: ask what a refusal says, not only that there was one

2026-09-01 22:01:03 -07:00

Cargo.toml

…

LICENSE

…

README.md

…

README.md

lux-consensus

Pure-Rust SDK for the Lux Quasar consensus stack — Wave threshold voting, FPC (Fast Probabilistic Consensus), Photon validator sampling, Focus confidence accumulation, and post-quantum hybrid finality via BLS12-381 + Pulsar (Module-LWE threshold, FIPS 204 byte-equal).

Features

Flag	What it pulls in
default	CPU-only, no extra deps beyond `blst` and `hex`
`simd`	`blake3` (SIMD hashing) + `rayon` (data-parallel vote tally)
`mlx`	Apple Silicon GPU acceleration via `mlx-sys` (implies `simd`)
`cuda`	NVIDIA GPU acceleration (implies `simd`) — work in progress
`gpu`	`mlx` + `cuda` — auto-select per platform

Usage

use lux_consensus::*;

let config = QuasarConfig::mainnet();
let mut engine = QuasarEngine::new(config);
engine.start().unwrap();

let block = Block::new(
    ID::from([1u8; 32]),
    ID::from([0u8; 32]),
    1,
    b"Hello, Lux!".to_vec(),
);
engine.add(block.clone()).unwrap();

// A validator is named by its 20-byte NodeID — never the 32-byte block id.
for i in 0..20 {
    engine.add_validator(NodeID::from([i; 20]), 1).unwrap();
}

for i in 0..20 {
    let vote = Vote::new(block.id.clone(), VoteType::Preference, NodeID::from([i; 20]));
    engine.record_vote(vote).unwrap();
}

assert!(engine.is_accepted(&block.id));
engine.stop().unwrap();

Architecture

Wave — adaptive-threshold voting driven by FPC outputs
FPC — PRF-derived per-round thresholds for fast probabilistic consensus
Photon — luminance-tracked validator sampling
Focus — β consecutive rounds of confidence before commit
Quasar — a two-thirds-by-stake certificate: the distinct signed accepts themselves, each checked against its own signer's key

License

Lux Ecosystem License 1.2 — see the LICENSE file.