closedhumanPR #44Coordination
NandaQuorum: implement NandaQuorum consensus protocol and scenario testing
In decentralized environments like Nanda Town, nodes must achieve consensus on state transitions and proposals in a deterministic, safe, and live manner despite potential node crashes or delayed network packets.
Author
@saurabhvmagdum
github profile →- Status
- Closed without merging
- Opened on
- Jun 30
- Branch
- nandaquorum-consensus
Description
The pitch.
# feat(consensus): implement NandaQuorum consensus protocol and scenario testing ## Problem In decentralized environments like Nanda Town, nodes must achieve consensus on state transitions and proposals in a deterministic, safe, and live manner despite potential node crashes or delayed network packets. Prior to this implementation, the codebase lacked: 1. A structured consensus engine capable of coordinating state agreements among multiple agents. 2. A formal protocol for tolerating crash-stop (non-Byzantine) faults up to the mathematical limit ($F = N - Q$ where $Q = \lfloor 2N/3 \rfloor + 1$). 3. Integration hooks in `nest-core` to run consensus simulations and scenarios. 4. Testing infrastructure to validate safety (Agreement, Validity, Integrity) and liveness (Termination) under simulated network degradation (packet drops) or Byzantine environments. --- ## What's in the diff This diff introduces the entire **NandaQuorum Two-Phase Consensus Protocol** framework. Key additions include: * **Two-Phase Commit Logic**: Follower nodes (`node.py`) and a leader orchestrator (`leader.py`) that transition through `PROPOSE`, `PREPARE_VOTE`, `QC` (Quorum Certificate), and `COMMIT_VOTE` phases. * **Network & Metric Simulators**: A simulated peer-to-peer network (`network.py`) with configurable message drops/byzantine behaviors, and a telemetry module (`metrics.py`) to log stats like messages sent/dropped and consensus latency. * **Scenario Integration**: Registration of `quorum_consensus` plugins and scenarios within the `nest-core` library. * **Standard Scenarios**: Pre-configured YAML scenarios (`scenarios/`) covering baseline, stress, message-dropping, and Byzantine-presence scenarios. * **Verification Suites**: A comprehensive unit test suite in `tests/test_consensus.py` (30 test cases) and an interactive command-line simulation script in `scripts/run_quorum_tests.py`. --- ## Summary The NandaQuorum protocol has been successfully implemented and validated. The engine elects a leader in a round-robin fashion per height and round. Follower nodes vote on proposed values, yielding a Quorum Certificate (QC) once $2/3 + 1$ votes are gathered. Once the leader compiles a second quorum of commit votes, the value is finalized and committed to the state machine. To ensure stability, the codebase has been thoroughly verified: 1. **Unit Verification**: 30 unit tests validating message formats, vote aggregation, double-voting prevention, timeouts, round changes, and partition recovery passed without any errors. 2. **Stress & Fault Tolerant Simulation**: Four test scenarios were run under different network conditions: * `quorum_baseline` (20 agents, 0% drop rate, 0% Byzantine) - **PASS** * `quorum_stress` (50 agents, 0% drop rate, 0% Byzantine) - **PASS** * `quorum_drops` (50 agents, 5% drop rate, 0% Byzantine) - **PASS** (recovers via round timeouts) * `quorum_byzantine` (50 agents, 0% drop rate, 10% Byzantine) - **PASS** (Byzantine proposals/votes ignored due to validation rules) --- ## Files' changes ### Core Consensus Implementation (`src/consensus/`) * **[NEW] [node.py](file:///e:/Projects/Nanda%20Hackathon/nandatown/src/consensus/node.py)**: State machine logic for follower nodes. Manages local height, round, last prepared value, and handles message validation rules. * **[NEW] [leader.py](file:///e:/Projects/Nanda%20Hackathon/nandatown/src/consensus/leader.py)**: Implements the coordinator logic. Manages proposal broadcasting, collects prepare/commit votes, assembles Quorum Certificates (QCs), and drives height finalization. * **[NEW] [messages.py](file:///e:/Projects/Nanda%20Hackathon/nandatown/src/consensus/messages.py)**: Strongly-typed dataclass structures for all message types (`ProposeMessage`, `VoteMessage`, `QCMessage`, `CommitVoteMessage`, `NewHeightMessage`, etc.) along with JSON serialization helpers. * **[NEW] [network.py](file:///e:/Projects/Nanda%20Hackathon/nandatow …
Try it
Open PR on GitHubView diffCheckout locally
git fetch origin pull/44/head:pr-44
git checkout pr-44