Vote for your favorite SkillMD. The submission with the most likes wins the $1,000 Audience Choice Award for the NandaHack x HCLTech hackathon. Voting is open through September 25.Vote now →
in reviewhumanPR #171Coordination

Problem 10: Add namespaced BFT quorum protocol with signed equivocation exclusion and view change

This PR adds a new, submission-owned BFT quorum consensus implementation for Problem 10.

Author

saurabhvmagdum avatar

@saurabhvmagdum

github profile →
Status
In review
Opened on
Jul 10
Branch
hackathon/saurabhvmagdum-bft-quorum

Description

The pitch.

## Summary

This PR adds a new, submission-owned BFT quorum consensus implementation for Problem 10.

It is implemented on a fresh branch from current `main` and does not modify the merged HotStuff submission, its scenarios, or unrelated repository configuration. All protocol artifacts use the `saurabhvmagdum_bft_quorum` namespace to avoid collisions with existing solutions.

## Protocol Differentiator

The protocol’s load-bearing differentiator is **evidence-carrying equivocation exclusion**.

When a validator issues conflicting signed votes for the same `(height, round, phase)`:

1. Both conflicting votes are retained as equivocation evidence.
2. The validator is excluded from every vote tally for that round.
3. An `equivocation:` event is emitted into the trace.
4. Decision certificates include the relevant equivocation-evidence hashes.
5. Validators reject a commit certificate that counts an excluded or equivocating voter.

This behavior is implemented in the runtime plugin, represented in scenario traces, enforced by runtime validators, and covered by end-to-end tests.

## BFT Model

- Validator set: `N = 3f + 1`
- Byzantine tolerance: at most `f` Byzantine validators
- Commit quorum: `Q = 2f + 1` distinct authenticated validators
- Authentication: proposals, votes, round-change messages, equivocation evidence, and commit certificates are signed using the configured `did_key` identity material
- Vote counting: only unique, validly signed, non-excluded voters are counted
- Self-votes: counted only when emitted as an ordinary signed trace vote
- Liveness: deterministic timeout-driven round change and rotating leadership

The quorum threshold remains fixed to the original validator set for the height. Excluding equivocators does not reduce the required `2f + 1` threshold.

## Changes

### Coordination Plugin

- Added `quorum_bft.py` under the reference coordination-plugin package.
- Registered the plugin as `saurabhvmagdum_bft_quorum`.
- Added canonical signed envelopes for:
  - `proposal`
  - `vote`
  - `round_change`
  - `equivocation`
  - `commit`
- Added deterministic leader selection:

  ```python
  leader_index = (height + round) % total_validators
  ```

- Added logical-clock timeout handling and deterministic view changes.
- Removed any scenario-local consensus tally that could bypass the selected plugin.

### Validators

- Added and registered runtime validators under `saurabhvmagdum_bft_quorum`:
  - `validate_no_conflicting_commits`
  - `validate_no_equivocation_in_certificate`
  - `validate_no_forged_quorum`
  - `validate_no_stuck_view`
- Validators are fail-closed for empty, malformed, missing-commit, and non-scorable traces.
- Validators use the same shared quorum calculation and message-validation rules as the protocol runtime.

### Scenarios

Added submission-owned scenarios only:

- `saurabhvmagdum_bft_quorum_byzantine.yaml`
  - Seven validators: `N = 7`, `f = 2`, `Q = 5`
  - Exactly two Byzantine agents
  - Conflicting signed votes
  - Equivocation evidence and exclusion before commit
  - Commit supported by five distinct valid, non-excluded signers

- `saurabhvmagdum_bft_quorum_partition.yaml`
  - Seven validators
  - Deterministic 4/3 network partition
  - Timeout and view-change evidence
  - Network healing
  - Post-heal proposal and valid commit quorum

### Tests

Added tests for:

- Plugin execution-path verification: the trace differs when the coordination plugin is changed to `contract_net`.
- Signed-message verification and malformed-message rejection.
- Fixed BFT quorum math.
- Unique-voter tallying and duplicate-message handling.
- Equivocation exclusion across all round tallies.
- Self-vote accounting consistency between runtime and trace validators.
- Byzantine scenario end-to-end behavior.
- Partition, timeout, view-change, heal, and post-heal commit behavior.
- Validator registration through the runtime

…

Try it

Open PR on GitHubView diff

Checkout locally

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