mirror of
https://github.com/luxfi/consensus.git
synced 2026-09-24 00:26:58 +00:00
zeekay
667bbb4023
`lux-rs/consensus` is a filtered extraction of this crate that grew two modules this one never had — a vote on the wire, and the ZAP frame it travels under. Rust had no reader for that frame at all, so the Rust lane could not carry a consensus vote between validators; the extraction could, and that is the only reason it still exists. It is also a second crate answering the name `lux-consensus`, which is one implementation too many. So the two modules come here, where the rule they need already lives. They are not copied. The extraction predates proof of possession and the export rung's floors, and its `Tally` issued a certificate the moment a caller-declared count was reached — a threshold anyone could declare and nobody had to earn. Rewritten against this crate: `NodeId` and the proof path from `pop`, `ValidatorSet` for who may be counted at all, and `QuorumCert::verify_weighted` for whether the votes amount to anything. `Tally::cert` is the only door out of a tally and it runs the whole predicate — the stake supermajority, the distinct-signer count, and the minimum Byzantine committee, every one recomputed from the live set. A tally can no more declare its own quorum than a certificate can. That is `a_tally_cannot_declare_its_own_quorum`: one valid signature, a declared threshold of one, a set of seven, and no certificate. One tally reads one epoch. The height is fixed when it opens and both the signature check and the stake read use it, so a tally cannot verify against one set and weigh against another. `VoteError` spells only what the vote plane owns — the wire, the position, the accept bit, the signature — and carries every certificate clause as the `CertError` `cert` already names, so a refusal has one vocabulary. The frame's constants are pinned against the two lanes that must read it: `luxfi/api/zap` writes a 4-byte big-endian length, a type byte, and the payload, with `WriteBytes` prefixing a field the same way; `luxcpp/zap` matches. Go names no type mask and open-codes the strip, so `strip_flags_is_gos_own_expression` proves the named one is that expression over every byte. 62 is free in the Go registry, which spells 60 and 61 of the Quasar block. It is NOT free everywhere — `mpc/pkg/transport` extends the same frame with its own 60..69 — and the constant says so rather than claiming a clean id space this end cannot give. Public API addition, so 1.22.7.
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.