From 876969d6f032be92d195a956ddc0dfd36a40535b Mon Sep 17 00:00:00 2001 From: Robert Habermeier Date: Mon, 5 Nov 2018 11:27:01 +0100 Subject: [PATCH] add some docs --- substrate/core/finality-grandpa/src/lib.rs | 34 +++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/substrate/core/finality-grandpa/src/lib.rs b/substrate/core/finality-grandpa/src/lib.rs index cc3d6b0349..0ea5d782b0 100644 --- a/substrate/core/finality-grandpa/src/lib.rs +++ b/substrate/core/finality-grandpa/src/lib.rs @@ -16,7 +16,39 @@ //! Integration of the GRANDPA finality gadget into substrate. //! -//! This is a long-running future that produces finality notifications. +//! This crate provides a long-running future that produces finality notifications. +//! +//! # Usage +//! +//! First, create a block-import wrapper with the `block_import` function. +//! The GRANDPA worker needs to be linked together with this block import object, +//! so a `LinkHalf` is returned as well. All blocks imported (from network or consensus or otherwise) +//! must pass through this wrapper, otherwise consensus is likely to break in +//! unexpected ways. +//! +//! Next, use the `LinkHalf` and a local configuration to `run_grandpa`. This requires a +//! `Network` implementation. The returned future should be driven to completion and +//! will finalize blocks in the background. +//! +//! # Changing authority sets +//! +//! The rough idea behind changing authority sets in GRANDPA is that at some point, +//! we obtain agreement for some maximum block height that the current set can +//! finalize, and once a block with that height is finalized the next set will +//! pick up finalization from there. +//! +//! Technically speaking, this would be implemented as a voting rule which says, +//! "if there is a signal for a change in N blocks in block B, only vote on +//! chains with length NUM(B) + N if they contain B". This conditional-inclusion +//! logic is complex to compute because it requires looking arbitrarily far +//! back in the chain. +//! +//! Instead, we keep track of a list of all signals we've seen so far, +//! sorted ascending by the block number they would be applied at. We never vote +//! on chains with number higher than the earliest handoff block number +//! (this is num(signal) + N). When finalizing a block, we either apply or prune +//! any signaled changes based on whether the signaling block is included in the +//! newly-finalized chain. extern crate finality_grandpa as grandpa; extern crate futures;