Skip to content
This repository was archived by the owner on Jun 16, 2026. It is now read-only.

consensus-flow.md

Latest commit

 

History

History
65 lines (45 loc) · 2.6 KB

consensus-flow.md

File metadata and controls

65 lines (45 loc) · 2.6 KB
Raw

DSV Consensus Flow

Document Status: Production Implementation (February 2026)
Purpose: Document the consensus mechanism from submission to on-chain finalization.
Related: aggregator-workflow.md, protocol-state-transitions.md, ../architecture/data-flow.md

Overview

DSV consensus is achieved through two-level aggregation:

  1. Level 1 (Local): Each validator aggregates collected submissions into a local finalized batch. Consensus CID per project = majority vote among submissions.
  2. Level 2 (Network): All validators' batches are aggregated. Consensus CID per project = majority vote among validator batches.
  3. On-Chain: VPA assigns which validator submits the Level 2 consensus batch. That validator submits via relayer-py.

Consensus Algorithm

Per-Project CID Selection

  • Input: Multiple CIDs for the same (epoch, project) from different submitters (L1) or validators (L2).
  • Algorithm: Count votes per CID. Select CID with majority. Tie-breaking: deterministic (e.g., lexicographic first).
  • Output: Single consensus CID per project for the epoch.

Determinism

  • L1: Same submissions → same local batch. Submissions collected deterministically (ZSET order, no SCAN).
  • L2: Same validator batches → same consensus. Aggregation window ensures all batches collected before computation.

Flow Summary

1. EpochReleased
2. Submission window opens (45s BDS mainnet)
3. Snapshotters submit CIDs via gossipsub
4. P2P Gateway → Dequeuer → Redis (epoch-keyed)
5. Window closes
6. Finalizer workers: vote count per project → consensus CID
7. Aggregator L1: combine parts → local batch → IPFS → stream
8. P2P Gateway: broadcast local batch to finalized-batches topic
9. Aggregator L2: collect batches (local + remote) for 30s window
10. Level 2 consensus → aggregated batch → IPFS
11. VPA: getPriorities → wait for window → submit via relayer-py
12. On-chain: epoch finalized

Byzantine Fault Tolerance

  • L1: Malicious snapshotter submissions can be outvoted by honest majority. Deduplication prevents self-voting amplification.
  • L2: Malicious validator batch can be outvoted by honest validators. Requires >1/2 honest validators.
  • VPA: On-chain priority prevents submission conflicts. Only one validator submits per epoch.

Code References

  • Aggregator: decentralized-sequencer/cmd/aggregator/main.go
  • Consensus logic: decentralized-sequencer/pkgs/consensus/
  • VPA: decentralized-sequencer/pkgs/vpa/client.go