lux/consensus
2
0
Fork 0
mirror of https://github.com/luxfi/consensus.git synced 2026-09-24 00:26:58 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
v1.36.91
consensus/pkg
T
History
zeekayandHanzo Dev 7d990c2592 quasar: the engine issues certificates its own accept rule accepts 
It did not. QuasarConsensus::create_certificate stamped ceil(alpha * k), the
CONFIGURED accept quorum, while every floor that certificate is then held to is
derived from the SET. Those are two quantities: one is about a committee, the
other about who can sign. They part at every n != k, and the testnet preset parts
at its own k — five validators, alpha 0.6, a stamped 3 against a derived 4 — so
the public issue path was dead on that preset at every set size, and its refusal
came back as NoQuorum over a set holding a unanimous one.

So the threshold is derived here and now, exactly as Tally::cert derives it:
signer_floor(tier, signer_count) at the moment of issue. The liveness pre-gate
reads the same derived number rather than the configured one, so it can never stop
short of a quorum the predicate below would have admitted — the door-in-front-of-a-
gate mistake, which this one was also making at every n where the config asked more
than the set does.

The suite stayed at 170 green through all of it because it only ever asked the
DEFAULT preset at n=20, which is the one point where ceil(0.69 * 20) and
two_thirds_count(20) are both 14. The new rows straddle that point, on both presets,
and every one of them fails on the old stamp.

THE REFUSAL IS CARRIED WHOLE. verify_weighted's answer was flattened to NoQuorum,
so "the voters hold 3 of 10_003 stake" and "two seats cannot carry a supermajority
at all" and "the votes are not in yet" were one sentence. ConsensusError::Cert
carries the CertError, and the two registration doors stop stringifying theirs
through CryptoError — one way to carry one thing.

THE CONFIGURED NUMBER STAYS, under its own name. QuasarConsensus::alpha is what
has_quorum asks: has the membership grown to the committee this node was told to
expect. It is a readiness question and it touches no certificate. It was called
`threshold`, which is why it ended up stamped on one.

ONE READ PER ISSUE. Tally::cert derived its threshold from signer_count and then
handed verify_weighted the source, which reads signer_count again to check that
same threshold. A source that need not answer twice alike makes those two numbers,
and the second refuses what the first built. The count is taken once and answers
every clause of the issue. Only the issue: the ARRIVAL road keeps its independent
reads, and the rung's count clause reading the set again is what refuses a
certificate whose set moved under it — which is why that clause is not dead.

CertError and ConsensusError are #[non_exhaustive]. A refusal is a fact about the
protocol and the protocol acquires facts; ThresholdNotDerived is one it just
acquired. This cut breaks an exhaustive match either way, so it is the cut that
should make it the last time. 1.23.0: new API, non-breaking variants after.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-02 02:56:40 -07:00
..
c
pkg/c: add trailing newline to lux_consensus.h
2026-06-27 10:37:49 -07:00
python
feat: unify Python SDK with MCP mesh consensus
2026-01-13 09:49:03 -08:00
rust
quasar: the engine issues certificates its own accept rule accepts
2026-09-02 02:56:40 -07:00
typescript
cert: the weight clause Go runs last, the set admitted whole, and one workspace
2026-09-01 11:53:54 -07:00
wire
consensus: comments state the invariant, not the incident
2026-08-14 14:57:08 -07:00
README.md
docs: retract fabricated throughput numbers (honesty pass)
2026-07-02 08:53:06 -07:00

README.md

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):

  1. Wave - Threshold voting with fast probabilistic consensus (production)
  2. Nova - Linear chain consensus (wraps Ray sub-protocol)
  3. Nebula - DAG consensus with safe-prefix commit (wraps Field sub-protocol)
  4. PostQuantum - Quantum-resistant consensus with BLS + Pulsar + ML-DSA
  5. Chain - Linear chain consensus for ordered blocks
  6. 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.md and the "Honest Assessment" block in LLM.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

  1. Consistency: All implementations should provide the same consensus guarantees
  2. Testing: Each implementation must have comprehensive test coverage
  3. Documentation: Language-specific documentation in docs/{language}/
  4. Performance: Optimize for language strengths while maintaining correctness
  5. Compatibility: Maintain protocol compatibility across all implementations

Contributing

When adding features or fixes:

  1. Implement in the reference implementation (Go)
  2. Port to other languages maintaining consistency
  3. Add tests for all implementations
  4. Update documentation

See CONTRIBUTING.md for detailed guidelines.

License

Copyright (C) 2019-2025, Lux Industries Inc. All rights reserved.

Reference in New Issue View Git Blame Copy Permalink