mirror of
https://github.com/luxfi/consensus.git
synced 2026-09-24 00:26:58 +00:00
zeekayandHanzo Dev
82ab92a70f
The Quasar rung read only stake. Two thirds of the stake is one signature wherever two thirds of the stake is one validator, so a whale holding a supermajority could mint an export-grade certificate alone — and export-grade finality is what a bridge, a settlement and a cross-chain message admit on. A certificate one key can produce is not a claim that a Byzantine supermajority agreed, however much weight stands behind the key. VerifyWeighted now demands config.TwoThirdsCount(n) = floor(2n/3)+1 DISTINCT signers of a Quasar certificate as well as the stake. Two independent predicates, neither sufficient alone, the same shape Nova has one rung up. TwoThirdsCount is the count that value has always been, given its own name and one home. It is derived from TwoThirdsStakeFloor over unit weights rather than restated, so the count and the stake predicate cannot drift. It replaces three spellings of the same closed form that had grown apart in reach if not yet in value: config.EqualStakeSupermajorityThreshold (the alpha sizer), the private chain.quasarQuorum (the attestor's assembly trigger), and the clause that was missing from the verifier entirely. Stake is read first and the count second. Both must hold, so the order names only which clause a refusal reports: on an equal-stake set the two are one bar in two units and bind together, and the count clause binds ALONE only where the weights are lopsided — so reaching it means the stake was there and the signers were not. Every verdict the R3 corpus froze is unchanged. Liveness. Nothing that exports today stops exporting. QuasarAttestor, the only producer of export certificates, already assembled at exactly floor(2n/3)+1 attestations, and FeasibleParams already sized alpha — the floor HandleIncomingCert applies to a gossiped Quasar cert — to the same number. Producer, gossip door and verifier now read one function, so the verifier's new clause refuses nothing the engine can build and exactly what it never could. quasar_count_floor_test.go holds all three to that. The tests that moved were the ones written on three seats, where floor(2n/3)+1 is three and no two-signer certificate can isolate the stake half any more. They ask the same question on four. Rust: the same clause in Cert::verify_quasar_supermajority, the same name. 1.22.4 -> 1.22.5 — this changes what the crate accepts. Also, at the already-admitted door: the zero-weight refusal is justified by agreement with Register, not by the phantom-signer argument alone. A seat whose key does not decode can never sign and is refused anyway, because the weight is read before the key is — and deferring it would make admission depend on which keys a node's crypto build can parse. Co-authored-by: Hanzo Dev <[email protected]>
Lux Consensus Source Code Organization
This directory contains implementations of the Lux consensus framework in multiple programming languages. Each language implementation provides the same consensus algorithms with language-specific optimizations and idioms.
Directory Structure
src/
├── c/ # C implementation (high-performance, minimal overhead)
├── cpp/ # C++ implementation with MLX extensions (GPU acceleration)
├── go/ # Go implementation (production blockchain integration)
├── python/ # Python implementation (research and prototyping)
└── rust/ # Rust implementation (memory-safe systems programming)
Language Implementations
Go (/src/go/)
- Status: Production-ready
- Use Case: Core blockchain node integration
- Import Path:
github.com/luxfi/consensus(via go.work at root) - Features: Full integration with Lux node, concurrent processing
C (/src/c/)
- Status: Data structures only — not real consensus (per SDK audit)
- Use Case: Embedded systems, performance-critical applications
- Features: Minimal dependencies, ZeroMQ networking, SIMD optimizations
Rust (/src/rust/)
- Status: FFI wrapper around the C library — inherits C limitations, not native consensus (per SDK audit)
- Use Case: Memory-safe systems, async applications
- Features: Zero-cost abstractions, async/await, compile-time guarantees
Python (/src/python/)
- Status: Research/Development
- Use Case: Prototyping, research, data analysis
- Features: NumPy integration, ML frameworks, visualization
C++ (/src/cpp/)
- Status: Development
- Use Case: High-performance with GPU acceleration
- Features: MLX extensions, template metaprogramming, SIMD/GPU support
Building
From the repository root:
# Build all implementations
make build
# Build specific language
make build-go
make build-c
make build-rust
make build-python
make build-cpp
Testing
From the repository root:
# Test all implementations
make test
# Test specific language
make test-go
make test-c
make test-rust
make test-python
make test-cpp
Consensus Engines
All implementations support these consensus engines (Quasar family):
- Wave - Threshold voting with fast probabilistic consensus (production)
- Nova - Linear chain consensus (wraps Ray sub-protocol)
- Nebula - DAG consensus with safe-prefix commit (wraps Field sub-protocol)
- PostQuantum - Quantum-resistant consensus with BLS + Pulsar + ML-DSA
- Chain - Linear chain consensus for ordered blocks
- DAG - Full directed acyclic graph consensus
Performance Benchmarks
| Implementation | Votes/Second | Memory Usage | Latency |
|---|---|---|---|
| C | 14,000+ | < 10 MB | < 1ms |
| Rust | 13,500+ | < 15 MB | < 1ms |
| Go | 12,000+ | < 20 MB | < 2ms |
| C++ (w/ MLX) | 15,000+ | < 25 MB | < 1ms |
| Python | 5,000+ | < 50 MB | < 5ms |
Note. These per-implementation votes/sec figures are unverified and, per the SDK audit, several measure data-structure insertion on stub/wrapper SDKs (C = data structures only, Rust = FFI wrapper over C, C++ = Wave-only stub); only the Python SDK implements real consensus. Treat as illustrative, not measured consensus throughput. See
.github/workflows/README.mdand the "Honest Assessment" block inLLM.md.
Protocol Compatibility
All implementations use the same binary protocol for network communication:
┌─────────────┬────────────┬──────────┬───────────┬──────────┐
│ Engine Type │ Node ID │ Block ID │ Vote Type │ Reserved │
│ (1 byte) │ (2 bytes) │ (2 bytes)│ (1 byte) │ (2 bytes)│
└─────────────┴────────────┴──────────┴───────────┴──────────┘
This ensures interoperability between different language implementations.
Development Guidelines
- Consistency: All implementations should provide the same consensus guarantees
- Testing: Each implementation must have comprehensive test coverage
- Documentation: Language-specific documentation in
docs/{language}/ - Performance: Optimize for language strengths while maintaining correctness
- Compatibility: Maintain protocol compatibility across all implementations
Contributing
When adding features or fixes:
- Implement in the reference implementation (Go)
- Port to other languages maintaining consistency
- Add tests for all implementations
- Update documentation
See CONTRIBUTING.md for detailed guidelines.
License
Copyright (C) 2019-2025, Lux Industries Inc. All rights reserved.