oxedyne/fe2o3/fe2o3_o3db_sync/src/dist/hotstuff/mod.rs
2.0 KiB, 23 runs
created by r1870400018:11224, which is this file's identity for as long as the history lasts, whatever it is later renamed to
download · who wrote it · its history
| 1 | //! A HotStuff Byzantine-fault-tolerant consensus primitive for small |
| 2 | //! cohorts, intended for the strong-consistency tables of the Hematite |
| 3 | //! distributed Ozone layer. |
| 4 | //! |
| 5 | //! # Protocol |
| 6 | //! |
| 7 | //! This is Basic HotStuff: a fixed leader drives a single view through |
| 8 | //! `Prepare -> PreCommit -> Commit -> Decide`, and the cohort recovers from |
| 9 | //! a silent or misbehaving leader through a view-change round. The primitive |
| 10 | //! is a pure, deterministic state machine; it has no transport, no crypto, |
| 11 | //! and no time. Signatures are opaque byte vectors supplied by the caller |
| 12 | //! and aggregated without inspection. |
| 13 | //! |
| 14 | //! # Safety predicate |
| 15 | //! |
| 16 | //! Every `Prepare` proposal in view `v > 1` must either carry a justify QC |
| 17 | //! that endorses the locally-locked block or carry a justify QC from a view |
| 18 | //! strictly newer than the locally-locked QC. A fresh proposal with no |
| 19 | //! justify is only legal when the replica holds no lock -- which happens |
| 20 | //! when the NewView quorum collected by the new leader saw no prior prepare |
| 21 | //! QC anywhere in the cohort. [`replica::Replica::on_proposal`] enforces |
| 22 | //! this. |
| 23 | //! |
| 24 | //! # Cohort sizes |
| 25 | //! |
| 26 | //! The spec recommends `λ ∈ {5, 7, 9}` with `z = floor((λ - 1) / 3)` |
| 27 | //! tolerated Byzantine members. The quorum threshold is `λ - z`: |
| 28 | //! |
| 29 | //! | `λ` | `z` | quorum | |
| 30 | //! |-----|-----|--------| |
| 31 | //! | 5 | 1 | 4 | |
| 32 | //! | 7 | 2 | 5 | |
| 33 | //! | 9 | 2 | 7 | |
| 34 | //! |
| 35 | //! [`replica::Config::validate`] enforces the `λ >= 3z + 1` requirement. |
| 36 | //! |
| 37 | //! # Deferred |
| 38 | //! |
| 39 | //! - Checkpointing of multiple decisions (this primitive is one-decision). |
| 40 | //! - Byzantine-fault simulation tests beyond the single unsafe-proposal case |
| 41 | //! currently in the integration-test suite. |
| 42 | //! - Signature aggregation (we pass individual signatures through the QC; |
| 43 | //! callers implementing threshold signatures can swap the aggregation |
| 44 | //! logic at their integration layer). |
| 45 | //! |
| 46 | //! [Written with AI entirely](https://need2know.ai/entirely-ai/code)\ |
| 47 | //! Anthropic Claude |
| 48 | |
| 49 | pub mod replica; |
| 50 | pub mod types; |