mirror of
https://github.com/luxfi/consensus.git
synced 2026-09-24 00:26:58 +00:00
docs: retract fabricated throughput numbers (honesty pass)
Remove impossible/mislabeled per-second figures from consensus docs: the "3.9B blocks/sec" / "6.6B votes/sec" u8-overflow artifacts (real C-FFI ≈21K votes/sec per the CI README), the 20.26M/11.5M "TPS" that are ZAP wire-message microbenches (relabeled, not consensus finality), stub-SDK "sub-second finality" claims, and downgraded "production-ready" labels on SDKs the CI audit documents as stubs. Genuinely-measured go-test numbers left intact. Fixed stale LUX_CONSENSUS_PQ_MODE → CONSENSUS_PQ_MODE. Docs only, no Go logic touched. Co-authored-by: Hanzo Dev <[email protected]>
This commit is contained in:
Hanzo Dev
+5
-4
@@ -128,10 +128,11 @@ This release introduces complete multi-language support for the Lux consensus en
|
||||
- Example implementation provided
|
||||
|
||||
#### Performance Achievements
|
||||
- C: 9M+ blocks/sec, 19M+ votes/sec
|
||||
- Rust: 607ns engine creation
|
||||
- Python: 6.7M blocks/sec
|
||||
- Go: 14M+ blocks/sec
|
||||
- Per-second throughput figures from this release were retracted by the
|
||||
2025-11-10 SDK audit: the C/Rust/Python/Go SDKs measure data-structure
|
||||
insertion (or the Rust `u8` overflow bug), not consensus. The honest
|
||||
consensus-bound rate is ≈21K votes/sec (C FFI). See
|
||||
`.github/workflows/README.md` and the "Honest Assessment" block in `LLM.md`.
|
||||
|
||||
### 📊 Test Coverage
|
||||
- 100% test parity across all 4 implementations
|
||||
|
||||
@@ -147,7 +147,7 @@ Crypto: `luxfi/crypto/bls`, `luxfi/crypto/mldsa`, `luxfi/corona/threshold`.
|
||||
### PQ Mode Selection
|
||||
|
||||
`config/pq_mode.go` defines the configurable PQ mode enum, selectable via
|
||||
the `LUX_CONSENSUS_PQ_MODE` env var or `Parameters.PQMode` field:
|
||||
the `CONSENSUS_PQ_MODE` env var or `Parameters.PQMode` field:
|
||||
|
||||
| Mode | Value | Description |
|
||||
|------|-------|-------------|
|
||||
@@ -275,11 +275,14 @@ path only unless noted. See `BENCHMARKS.md` for full raw output and reproduce
|
||||
commands.
|
||||
|
||||
### ZAP Wire Protocol (bench/)
|
||||
| Config | Throughput |
|
||||
|--------|------------|
|
||||
| Single connection | 114K TPS |
|
||||
| 20 parallel connections | 376K TPS |
|
||||
| 50 conns + batch 1000 | 20.26M TPS |
|
||||
|
||||
Raw wire message throughput (ZAP transport microbench), NOT consensus finality TPS.
|
||||
|
||||
| Config | Wire messages/sec |
|
||||
|--------|-------------------|
|
||||
| Single connection | 114K msg/s |
|
||||
| 20 parallel connections | 376K msg/s |
|
||||
| 50 conns + batch 1000 | 20.26M msg/s |
|
||||
|
||||
### Protocol Microbenchmarks
|
||||
| Component | Operation | Time/Op |
|
||||
@@ -364,7 +367,8 @@ chain-read; unrelated to consensus correctness but flagged for evmgpu repo.
|
||||
|
||||
### Lux vs prior-gen EVM (bench/)
|
||||
ZAP deserialization: 157x faster than protobuf (21 ns vs 3231 ns, zero allocs).
|
||||
End-to-end throughput: 11.5M TPS (Lux) vs 246K (prior-gen baseline).
|
||||
Wire deserialization throughput: 11.5M msg/s (Lux ZAP) vs 246K (protobuf baseline)
|
||||
— a raw serialization microbench, NOT consensus finality TPS.
|
||||
Run: `GOWORK=off go test -v -run TestLuxVsLegacy_EndToEnd -bench=. ./bench/`
|
||||
|
||||
## Key Technical Notes
|
||||
|
||||
+16
-5
@@ -41,7 +41,7 @@ Skipped: 0
|
||||
Performance:
|
||||
─────────────────────────────────
|
||||
1000 blocks: < 0.001 seconds
|
||||
Throughput: > 1M blocks/second
|
||||
Throughput: data-structure inserts only, not consensus (real C-FFI ≈21K votes/sec)
|
||||
Memory Footprint: < 10 MB
|
||||
```
|
||||
|
||||
@@ -75,10 +75,17 @@ Ignored: 0
|
||||
| Metric | Go | C | Rust | Python | C++ |
|
||||
|-----------------------|-----------|------------|-----------|----------|----------|
|
||||
| **Latency** | 1.7 μs | < 1 μs | 607 ns | ~10 μs | TBD |
|
||||
| **Throughput** | 660K/s | 1M+/s | - | ~100K/s | TBD |
|
||||
| **Throughput** | see note | see note | - | see note | TBD |
|
||||
| **Memory (typical)** | 912 B | < 10 MB | < 15 MB | ~50 MB | TBD |
|
||||
| **Test Coverage** | 74.5% | 100% | 100% | - | - |
|
||||
| **Status** | ✅ Prod | ✅ Prod | ✅ Prod | 🔬 Res | 🚧 Dev |
|
||||
| **Status** | ⚠️ core | ⚠️ structs | ⚠️ FFI | 🔬 Res | 🚧 Dev |
|
||||
|
||||
> **Note (throughput / status).** The per-second figures above measured the
|
||||
> AI-package microbench and data-structure insertion, not consensus, and any
|
||||
> value >100K/s exceeds the honest consensus-bound C-FFI ceiling of
|
||||
> ≈21K votes/sec. Per the SDK audit, C is data-structures-only, Rust is an FFI
|
||||
> wrapper over C, and only the Python SDK implements real consensus. See
|
||||
> `.github/workflows/README.md` and the "Honest Assessment" block in `LLM.md`.
|
||||
|
||||
## AI Consensus Performance Deep Dive
|
||||
|
||||
@@ -143,8 +150,12 @@ Ignored: 0
|
||||
|
||||
| Version | Go AI Decision | C Throughput | Coverage |
|
||||
|---------|----------------|--------------|----------|
|
||||
| v1.21.0 | 1.70 μs | 1M+ blocks/s | 74.5% |
|
||||
| v1.17.0 | 1.50 μs | 9M+ blocks/s | - |
|
||||
| v1.21.0 | 1.70 μs | see note* | 74.5% |
|
||||
| v1.17.0 | 1.50 μs | see note* | - |
|
||||
|
||||
\* C throughput figures ("1M+/9M+ blocks/s") retracted — they measured
|
||||
data-structure insertion, not consensus (real C-FFI ≈21K votes/sec). See
|
||||
`.github/workflows/README.md` and the "Honest Assessment" block in `LLM.md`.
|
||||
|
||||
**Observation**: Go latency increased slightly (1.5→1.7 μs) but with better accuracy and test coverage.
|
||||
|
||||
|
||||
@@ -195,11 +195,11 @@ BenchmarkSigmoid-10 214260781 5.600 ns/op 0 B/op 0 a
|
||||
|
||||
### Performance Summary
|
||||
|
||||
✅ **Current Performance**: Excellent for production use
|
||||
✅ **Current Performance**: Good for the measured microbench workload (not a consensus-throughput claim)
|
||||
✅ **Scalability**: Linear to 10 nodes, tested to 3
|
||||
✅ **Memory Efficiency**: Minimal allocations, low overhead
|
||||
✅ **Latency**: Sub-millisecond for critical operations
|
||||
✅ **Throughput**: Multi-million operations per second
|
||||
✅ **Throughput**: Multi-million *microbench* ops/sec (Sigmoid / state ops) — NOT consensus block/vote throughput
|
||||
|
||||
### Recommendations
|
||||
|
||||
|
||||
+9
-2
@@ -22,12 +22,12 @@ src/
|
||||
- **Features**: Full integration with Lux node, concurrent processing
|
||||
|
||||
### C (`/src/c/`)
|
||||
- **Status**: Production-ready
|
||||
- **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**: Production-ready
|
||||
- **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
|
||||
|
||||
@@ -94,6 +94,13 @@ All implementations support these consensus engines (Quasar family):
|
||||
| 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:
|
||||
|
||||
@@ -5,14 +5,26 @@
|
||||
**Rust Binding**: lux-consensus v1.17.0
|
||||
**Benchmark Tool**: Criterion 0.7.0
|
||||
|
||||
> **CORRECTION — retracted numbers.** The throughput figures in this report are
|
||||
> NOT valid and are retained only as a record of the debunked results. The
|
||||
> 2025-11-10 SDK audit found this Rust binding is an FFI wrapper around the C
|
||||
> library and measures data-structure insertion, not consensus; the batch
|
||||
> figures are the known Rust `u8` overflow bug (a counter capped at 255 instead
|
||||
> of 10,000). The honest consensus-bound ceiling is the C-FFI rate of
|
||||
> **≈21K votes/sec** — Rust wraps C and cannot exceed it, so any figure above
|
||||
> ~100K/sec below is measuring the wrong thing. See
|
||||
> `.github/workflows/README.md` (lines 41-49, 67) and the "Honest Assessment"
|
||||
> block in `LLM.md`.
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The Lux Consensus Rust FFI bindings demonstrate exceptional performance across all operations:
|
||||
Original summary (retracted — see correction above; the honest consensus-bound
|
||||
rate is ≈21K votes/sec):
|
||||
|
||||
- **Single block addition**: ~611ns (1.6M blocks/sec)
|
||||
- **Vote processing**: ~639ns per vote (1.5M votes/sec)
|
||||
- **10,000 block batch**: 256ns per block (3.9B blocks/sec throughput)
|
||||
- **10,000 vote batch**: 151ns per vote (6.6B votes/sec throughput)
|
||||
- **Single block addition**: ~611ns raw FFI-call time (derived "1.6M blocks/sec" measures data-structure insert, not consensus)
|
||||
- **Vote processing**: ~639ns raw FFI-call time (derived "1.5M votes/sec" not consensus)
|
||||
- **10,000 block batch**: raw ns/op invalid — `u8` overflow-bug artifact, NOT a real 3.9B blocks/sec
|
||||
- **10,000 vote batch**: raw ns/op invalid — `u8` overflow-bug artifact, NOT a real 6.6B votes/sec
|
||||
- **Complete consensus flow**: 2.6µs for 5 blocks with full voting
|
||||
|
||||
## Detailed Benchmark Results
|
||||
@@ -23,21 +35,21 @@ The Lux Consensus Rust FFI bindings demonstrate exceptional performance across a
|
||||
|-----------|-------------|------------|-------|
|
||||
| **Single Block** | 610.87 ns | 1.6M blocks/sec | Individual block addition |
|
||||
| **100 Blocks** | 114.95 ns/block | 8.7M blocks/sec | Batch efficiency gain |
|
||||
| **1,000 Blocks** | 28.16 ns/block | 35.5M blocks/sec | 22x faster than single |
|
||||
| **10,000 Blocks** | 256.1 ps/block | 3.9B blocks/sec | Maximum throughput |
|
||||
| **1,000 Blocks** | 28.16 ns/block | overflow-bug artifact (not 35.5M/s) | measures data-structure insert, not consensus |
|
||||
| **10,000 Blocks** | 256.1 ps/block | overflow-bug artifact (not 3.9B/s) | `u8` counter capped at 255 |
|
||||
|
||||
**Key Insight**: Batch operations show massive performance improvements due to reduced FFI overhead and better memory locality. The 10,000 block batch achieves an astounding 3.9 billion blocks/second throughput.
|
||||
**Key Insight (retracted)**: The apparent batch speedups are the Rust `u8` overflow bug (counter caps at 255 instead of 10,000), not real throughput. The honest consensus-bound rate is ≈21K votes/sec — Rust cannot exceed the C FFI it wraps. See `.github/workflows/README.md:41-49,67`.
|
||||
|
||||
### Vote Processing Performance
|
||||
|
||||
| Operation | Time (mean) | Throughput | Notes |
|
||||
|-----------|-------------|------------|-------|
|
||||
| **Single Vote** | 639.05 ns | 1.56M votes/sec | Individual vote processing |
|
||||
| **100 Votes** | 59.62 ns/vote | 16.8M votes/sec | 10x improvement |
|
||||
| **1,000 Votes** | 12.86 ns/vote | 77.8M votes/sec | Cache optimization |
|
||||
| **10,000 Votes** | 151.7 ps/vote | 6.6B votes/sec | Peak throughput |
|
||||
| **100 Votes** | 59.62 ns/vote | overflow-bug artifact (not 16.8M/s) | not consensus |
|
||||
| **1,000 Votes** | 12.86 ns/vote | overflow-bug artifact (not 77.8M/s) | not consensus |
|
||||
| **10,000 Votes** | 151.7 ps/vote | overflow-bug artifact (not 6.6B/s) | `u8` counter capped at 255 |
|
||||
|
||||
**Key Insight**: Vote batching provides even better scaling than block operations, achieving 6.6 billion votes/second for large batches.
|
||||
**Key Insight (retracted)**: The "6.6 billion votes/second" figure is the Rust `u8` overflow bug, not a real measurement. Honest ceiling ≈21K votes/sec (C FFI). See `.github/workflows/README.md:41-49,67`.
|
||||
|
||||
### Consensus Operations
|
||||
|
||||
@@ -79,9 +91,8 @@ The complete consensus flow benchmark simulates a realistic scenario:
|
||||
|
||||
### Throughput Achievements
|
||||
|
||||
- **Block Processing**: Up to 3.9 billion blocks/sec
|
||||
- **Vote Processing**: Up to 6.6 billion votes/sec
|
||||
- **Complete Flow**: 378,000 consensus rounds/sec
|
||||
- **Block/Vote Processing**: the "billions/sec" figures are the `u8` overflow bug, not real throughput; honest ceiling ≈21K votes/sec (C FFI)
|
||||
- **Complete Flow**: "378,000 consensus rounds/sec" exceeds the C-FFI ceiling and is unverified — treat as not measured
|
||||
|
||||
### FFI Overhead
|
||||
|
||||
@@ -107,13 +118,12 @@ The benchmark results show minimal FFI overhead:
|
||||
|
||||
## Conclusion
|
||||
|
||||
The Lux Consensus Rust bindings demonstrate production-ready performance with:
|
||||
- **Nanosecond-level latency** for all operations
|
||||
- **Billion-scale throughput** for batch operations
|
||||
- **Predictable performance** with low variance
|
||||
- **Efficient FFI design** with minimal overhead
|
||||
|
||||
These benchmarks confirm the Rust implementation is suitable for high-performance blockchain applications requiring extreme throughput and low latency.
|
||||
These bindings are an FFI wrapper around the C library. The batch "billion-scale"
|
||||
throughput reported above is the Rust `u8` overflow bug, not real performance;
|
||||
the honest consensus-bound rate is ≈21K votes/sec (Rust cannot exceed the C FFI
|
||||
it wraps). This report is retained only as a record of the debunked 2025-11-10
|
||||
numbers — it is NOT evidence of production readiness. See
|
||||
`.github/workflows/README.md` and the "Honest Assessment" block in `LLM.md`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ Native performance through NAPI-RS with full TypeScript type safety.
|
||||
- **Native Performance**: Rust-based consensus engine compiled to native Node.js addon
|
||||
- **Type Safety**: Full TypeScript definitions for all APIs
|
||||
- **69% Byzantine Tolerance**: Industry-leading fault tolerance (2% above standard 67%)
|
||||
- **Sub-second Finality**: ~500ms block time with 2-round finality
|
||||
- **2-round finality API** (block time / finality latency not measured for this binding)
|
||||
- **Quantum-Ready**: Optional ML-DSA (FIPS 204) post-quantum signatures
|
||||
- **GPU Acceleration**: Optional MLX (Apple Silicon) and CUDA support
|
||||
|
||||
@@ -190,13 +190,12 @@ pnpm test
|
||||
|
||||
## Performance
|
||||
|
||||
Benchmarks on Apple M2 Pro:
|
||||
|
||||
| Operation | Throughput |
|
||||
| -------------- | --------------- |
|
||||
| Add block | 1.2M blocks/sec |
|
||||
| Record vote | 850K votes/sec |
|
||||
| Batch votes | 1.5M votes/sec |
|
||||
Not independently benchmarked. This package is a NAPI wrapper around the Rust
|
||||
FFI binding, which itself wraps the C library — it measures data-structure
|
||||
insertion, not consensus. The honest consensus-bound ceiling is the C-FFI rate
|
||||
of ≈21K votes/sec; a wrapper cannot exceed it. Earlier per-second throughput
|
||||
figures here were retracted. See `.github/workflows/README.md` and the "Honest
|
||||
Assessment" block in `LLM.md`.
|
||||
|
||||
## Related Packages
|
||||
|
||||
|
||||
+2
-2
@@ -138,7 +138,7 @@ PASS
|
||||
✅ **Interoperability**: Languages can coexist in the same consensus network
|
||||
✅ **Consistency**: Consensus logic is correct across all implementations
|
||||
✅ **Scalability**: Can be embedded in any programming environment
|
||||
✅ **Production Ready**: Cross-language consensus works end-to-end
|
||||
⚠️ **Not production-ready**: only the Go node runs real consensus; the C/C++/Rust/Python nodes are stubs that simulate consensus (see status table below)
|
||||
|
||||
## Implementation Status
|
||||
|
||||
@@ -197,4 +197,4 @@ cd pkg/python && pip uninstall -y lux-consensus && pip install -e . && cd ../..
|
||||
|
||||
---
|
||||
|
||||
**This E2E test is the ultimate proof that Lux Consensus is truly language-agnostic and production-ready for any platform.**
|
||||
**This E2E test is a scaffold: today only the Go node runs real consensus; the C/C++/Rust/Python nodes are stubs that simulate consensus. It is not yet proof of language-agnostic or production-ready cross-language consensus.**
|
||||
|
||||
Reference in New Issue
Block a user