consensus/test/e2e

Cross-Language E2E Consensus Tests

Overview

This directory contains end-to-end (E2E) tests that verify interoperability and consensus agreement across all language implementations:

• Go - Native implementation
• C - Core FFI library
• C++ - C++ bindings
• Rust - Rust FFI bindings
• Python - Python ctypes bindings

The Ultimate Test

The cross-language consensus test (TestCrossLanguageConsensus) is designed to prove that:

1. All implementations are functionally equivalent - They implement the exact same consensus logic
2. Cross-language interoperability works - All languages can participate in the same network
3. Consensus is consistent - All nodes reach identical decisions on the same blocks
4. Implementation is scalable - Can be embedded in any language/platform

Test Architecture

┌─────────────────────────────────────────────────────────┐
│                  E2E Test Orchestrator                   │
│                        (Go Test)                         │
└──────────┬──────────┬──────────┬──────────┬─────────────┘
           │          │          │          │
     ┌─────▼────┐ ┌───▼────┐ ┌──▼─────┐ ┌──▼─────┐ ┌──▼──────┐
     │ Go Node  │ │ C Node │ │C++ Node│ │Rust Node│ │Py Node │
     │  (9000)  │ │ (9001) │ │ (9002) │ │ (9003)  │ │ (9004) │
     └─────┬────┘ └───┬────┘ └──┬─────┘ └──┬─────┘ └──┬──────┘
           │          │          │          │          │
           └──────────┴──────────┴──────────┴──────────┘
                            ▼
                    Same Consensus Network
                    (All nodes agree on blocks)

Test Flow

1. Start Phase

   • Initialize consensus engines in all 5 languages
   • Each node starts on a different port
   • Wait for all nodes to report healthy status

2. Proposal Phase

   • Propose 3 test blocks to all nodes simultaneously
   • Each block has: ID, ParentID, Height, Data
   • Blocks form a valid chain (block 2 → block 1 → genesis)

3. Consensus Phase

   • Each implementation processes blocks using its consensus logic
   • Nodes exchange votes (simulated for E2E stub)
   • Each node independently decides: accept or reject

4. Verification Phase

   • Query each node for its decision on each block
   • Compare decisions across all languages
   • PASS: All languages agree on all blocks
   • FAIL: Any mismatch indicates implementation inconsistency

5. Cleanup Phase

   • Stop all nodes gracefully
   • Verify no resource leaks

Running the Tests

Prerequisites

Build all language implementations:

# Go (always available)
go build ./...

# C library
cd pkg/c && make build && cd ../..

# C++ library (lives in ~/work/luxcpp/consensus/)
cd ~/work/luxcpp/consensus && cmake -B build && cmake --build build

# Rust library
cd pkg/rust && cargo build --release && cd ../..

# Python library
cd pkg/python && pip install -e . && cd ../..

Run E2E Test

# Full E2E test (all languages)
go test ./e2e -v -run TestCrossLanguageConsensus

# With timeout (recommended for CI)
go test ./e2e -v -run TestCrossLanguageConsensus -timeout 10m

# Skip in short mode
go test ./e2e -v -short  # Will skip E2E test

Expected Output

=== RUN   TestCrossLanguageConsensus
    cross_language_test.go:XX: Starting nodes in all languages...
    cross_language_test.go:XX: Starting Go node on port 9000
    cross_language_test.go:XX: ✅ Go node started successfully
    cross_language_test.go:XX: Starting C node on port 9001
    cross_language_test.go:XX: ✅ C node started successfully
    cross_language_test.go:XX: Starting C++ node on port 9002
    cross_language_test.go:XX: ✅ C++ node started successfully
    cross_language_test.go:XX: Starting Rust node on port 9003
    cross_language_test.go:XX: ✅ Rust node started successfully
    cross_language_test.go:XX: Starting Python node on port 9004
    cross_language_test.go:XX: ✅ Python node started successfully
    cross_language_test.go:XX: Waiting for all nodes to be healthy...
    cross_language_test.go:XX: All nodes are healthy!
    cross_language_test.go:XX: Proposing test blocks to all nodes...
    cross_language_test.go:XX: Proposing block 1 (ID: 2wXB..., Height: 1)
    cross_language_test.go:XX: Proposing block 2 (ID: 3aYC..., Height: 2)
    cross_language_test.go:XX: Proposing block 3 (ID: 4bZD..., Height: 3)
    cross_language_test.go:XX: Verifying consensus across all languages...
    cross_language_test.go:XX: ✅ All languages agree on block 2wXB...: true
    cross_language_test.go:XX: ✅ All languages agree on block 3aYC...: true
    cross_language_test.go:XX: ✅ All languages agree on block 4bZD...: true
    cross_language_test.go:XX: Stopping all nodes...
    cross_language_test.go:XX: ✅ Cross-language consensus test complete!
--- PASS: TestCrossLanguageConsensus (XX.XXs)
PASS

What This Proves

✅ Functional Equivalence: All implementations produce identical results ✅ 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 ⚠️ 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

Language	Build	Integration	Full E2E
Go	✅	✅	✅
C	✅	✅	🚧 Stub
C++	✅	✅	🚧 Stub
Rust	✅	✅	🚧 Stub
Python	✅	⚠️ Local	🚧 Stub

Legend:

• ✅ Complete and working
• 🚧 Stub implementation (simulates consensus)
• ⚠️ Works in CI, local environment issue

Next Steps

To evolve from stub to full E2E implementation:

1. Implement IPC Protocol - Define wire format for cross-language communication
2. Add Network Layer - Use ZMQ, gRPC, or Unix sockets for node communication
3. Real Consensus - Nodes actually exchange votes and run consensus protocol
4. Byzantine Testing - Add adversarial nodes to test fault tolerance
5. Performance Metrics - Measure throughput and latency across languages

Troubleshooting

C Node Fails to Start

# Rebuild C library
cd pkg/c && make clean && make build && cd ../..

C++ Node Fails to Start

# Rebuild C++ library (lives in ~/work/luxcpp/consensus/)
cd ~/work/luxcpp/consensus && rm -rf build && cmake -B build && cmake --build build

Rust Node Fails to Start

# Rebuild Rust library
cd pkg/rust && cargo clean && cargo build --release && cd ../..

Python Node Fails to Start

# Reinstall Python package
cd pkg/python && pip uninstall -y lux-consensus && pip install -e . && cd ../..

---

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.