Crate sc_finality_grandpa
source · [−]Expand description
Integration of the GRANDPA finality gadget into substrate.
This crate is unstable and the API and usage may change.
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_voter.
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 (across all forks), 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.
Modules
Contains a number of data transfer objects for reporting data to the outside world.
Structs
A set of authorities.
A custom voting rule that guarantees that our vote is always behind the best block by at least N blocks. In the best case our vote is exactly N blocks behind the best block.
Configuration for the GRANDPA service
Finality for block B is proved by providing:
Finality proof provider for serving network requests.
A block-import handler for GRANDPA.
A GRANDPA justification for block finality, it includes a commit message and an ancestry proof including all headers routing all precommit target blocks to the commit target block. Due to the current voting strategy the precommit targets should be the same as the commit target, since honest voters don’t vote past authority set change blocks.
The sending half of the Grandpa justification channel(s).
The receiving half of the Grandpa justification channel.
Parameters used to run Grandpa.
Link between the block importer and the background voter.
A scheduled change of authority set.
A shared authority set.
Shared voter state for querying.
A custom voting rule that limits votes towards 3/4 of the unfinalized chain,
using the given base and best_target to figure where the 3/4 target
should fall.
A builder of a composite voting rule that applies a set of rules to progressively restrict the vote.
Simple cache for warp sync queries.
Enums
Errors that can occur while voting in GRANDPA.
Errors occurring when trying to prove finality
Traits
Arithmetic necessary for a block number.
A trait that includes all the client functionalities grandpa requires. Ideally this would be a trait alias, we’re not there yet. tracking issue https://github.com/rust-lang/rust/issues/41517
Provider for the Grandpa authority set configured on the genesis block.
APIs for integrating the GRANDPA finality gadget into runtimes. This should be implemented on the runtime side.
A trait for custom voting rules in GRANDPA.
Functions
Make block importer and link half necessary to tie the background voter to it.
Make block importer and link half necessary to tie the background voter to it. A vector of authority set hard forks can be passed, any authority set change signaled at the given block (either already signalled or in a further block when importing it) will be replaced by a standard change with the given static authorities.
Returns the configuration value to put in
sc_network::config::NetworkConfiguration::extra_sets.
Prepare authority proof for the best possible block starting at a given trusted block.
Run a GRANDPA voter as a task. Provide configuration and a link to a
block import worker that has already been instantiated with block_import.
Type Definitions
Identity of a Grandpa authority.
The grandpa crypto scheme defined via the keypair type.
A catch up message for this chain’s block type.
A commit message for this chain’s block type.
A compact commit message for this chain’s block type.
A GRANDPA message for a substrate chain.
A precommit message for this chain’s block type.
A prevote message for this chain’s block type.
A primary propose message for this chain’s block type.
A signed message.