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 avatar

@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 diff

Checkout locally

git fetch origin pull/44/head:pr-44
git checkout pr-44