mirror of
https://github.com/luxfi/consensus.git
synced 2026-09-24 00:26:58 +00:00
zeekayandHanzo Dev
8d94ad1e03
A certificate carries a Threshold, and until now that field was its own authority on the count-only road: Verify's last clause counts distinct valid accepts against the number the CERTIFICATE names, so one declaring 1 clears it on a single signature. C++ has always demanded the derived floor exactly, so the same certificate was accepted by two implementations and refused by the third. VerifyWeighted now requires Threshold == SignerFloor(tier, n) — the floor this set gives this rung. Equality and not a lower bound: an over-claim names a bar this set does not set, and tolerating it would let a certificate redefine the rung upward exactly as tolerating an under-claim lets it redefine the rung down. SignerFloor is the one definition of a rung's count floor, read by the rung predicates, by the assemblers and by the new clause, so the number enforced and the number declared cannot drift. Two corollaries the rule forces: No set, no export. BuildVerifiedQuorumCert refuses any tier that authorizes export when no stake source is supplied. That road counts votes against the caller's own alpha, so an export token could be minted over one signer with alpha of one — and AcceptWithCert trusts the token, which is the point of the token. The accept rung keeps the road: it authorizes local execution the chain can still reorg away. The assembler reads the same n the verifier does. assembleCertLocked derived Nova's declared floor from effectiveCommittee, which sizes the SAMPLE and is floored at the minimum Byzantine committee. At three signers the sampler said three and the set said two, so a node would have built a certificate its own peers refuse. The export path already read SignerCount. The corpus grows five rows — three that declare a quorum of their own, and two lopsided sets where the stake half binds alone, which an equal set cannot state because both halves bind at one edge there. Two frozen verdicts change the clause they are NAMED by, from the stake floor to the count, and neither changes from refused: over an equal set a certificate short of its stake is also short of the quorum it now has to declare. The rungs' own count clauses are unreachable as a result — Verify proves count reaches the declaration and the new clause proves the declaration is the floor — and are kept as the place the floor is defined and as the guard that survives any change to the declaration rule. Written down in LLM.md beside the other walls behind walls. 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.