diff --git a/README.md b/README.md index 03177de9..9f32dae0 100644 --- a/README.md +++ b/README.md @@ -36,8 +36,10 @@ concerning dBFT's time depending behaviour. ## Usage A client of the library must implement its own event loop. -The library provides 4 callbacks: +The library provides 5 callbacks that change the state of the consensus +process: - `Start()` which initializes internal dBFT structures +- `InitializeConsensus()` which resets the consensus process - `OnTransaction()` which must be called everytime new transaction appears - `OnReceive()` which must be called everytime new payload is received - `OnTimer()` which must be called everytime timer fires diff --git a/dbft.go b/dbft.go index 11f366d7..cc502ebe 100644 --- a/dbft.go +++ b/dbft.go @@ -12,8 +12,10 @@ import ( ) type ( - // DBFT is a wrapper over Context containing service configuration and - // some other parameters not directly related to dBFT's state machine. + // DBFT is a dBFT implementation, it includes [Context] (main state) + // and [Config] (service configuration). Data exposed from these fields + // is supposed to be read-only, state is changed via methods of this + // structure. DBFT[H crypto.Hash, A crypto.Address] struct { Context[H, A] Config[H, A] @@ -74,15 +76,19 @@ func (d *DBFT[H, A]) addTransaction(tx block.Transaction[H]) { } } -// Start initializes dBFT instance and starts protocol if node is primary. It -// accepts a timestamp of the previous block. +// Start initializes dBFT instance and starts the protocol if node is primary. +// It accepts the timestamp of the previous block. It should be called once +// per DBFT lifetime. func (d *DBFT[H, A]) Start(ts uint64) { d.cache = newCache[H, A]() d.InitializeConsensus(0, ts) d.start() } -// InitializeConsensus initializes dBFT instance. +// InitializeConsensus reinitializes dBFT instance and the given view with the +// given timestamp of the previous block. It's used if the current consensus +// state is outdated (which can happen when a new block is received by node +// before completing its assembly via dBFT). View 0 is expected to be used. func (d *DBFT[H, A]) InitializeConsensus(view byte, ts uint64) { d.reset(view, ts)