mirror of
https://github.com/luxfi/consensus.git
synced 2026-09-24 00:26:58 +00:00
zeekay
ddbd6216eb
A verifier that sums the signers' keys and checks one signature against
the sum is sound only when every registrant proved possession of its
secret. Registration proves nothing of the kind — key_validate checks
encoding, subgroup and non-identity, all properties a chosen key has — so
pk_x = g1*x - sum(pk_others) collapsed the sum to a key the attacker
alone could sign under, and one signature stood for four signers.
The ruling allows deleting the path or requiring proof of possession.
Deleted, for three reasons that are not preference:
- Go has no aggregate to conform to. engine/chain/cert.go: "there is no
aggregate field, because nothing is aggregated." An aggregate accept
rule is an accept this network cannot express, so it can only differ
from the standard, never agree with it.
- The crate carried two accept rules, and the aggregate one skipped
every clause the other checks: version, type, tier, and the stake
floor. The weaker one was the one on the engine.
- It bought 654us against 13.6ms at n=21, and the sound way to buy that
back is batch verification of the same per-vote signatures — 1.26ms,
no summed keys, no proof of possession, no wire change, because the
certificate already carries every signature. Not done here: it is a
performance change and benchmarks come after conformance.
So QuasarConsensus now issues and verifies a cert::QuorumCert, which is
the Go rule: every signature checked against exactly one signer's key
over the message rebuilt from the certificate's own position, then the
tier's stake floor recomputed from the live set. A rogue key registers
and buys nothing — it cannot make anyone appear to have signed, and its
owner cannot even cast its own vote, holding no secret for what it
published.
The unbound header goes with it. Certificate.block_id and .height were
covered by no signature, so an honestly signed certificate re-labelled to
any block; a certificate now makes exactly one claim, its position, and
every part of it is signed. The map of issued certificates is keyed off
position.block_id rather than a field beside it.
rogue_key.rs keeps the forgery: it still builds the rogue key, still
shows one signature verifying against the summed key, and shows both
refusals. cert.rs and cert_conformance.rs test the per-vote rule the
aggregate tests used to cover.
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.