Crate sc_finality_grandpa

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

report

Contains a number of data transfer objects for reporting data to the outside world.

Structs

BeforeBestBlockBy	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.
Config	Configuration for the GRANDPA service
FinalityProofFragment	Single fragment of proof-of-finality.
FinalityProofProvider	Finality proof provider for serving network requests.
GrandpaBlockImport	A block-import handler for GRANDPA.
GrandpaJustification	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.
GrandpaJustificationSender	The sending half of the Grandpa justification channel(s).
GrandpaJustificationStream	The receiving half of the Grandpa justification channel.
GrandpaLightBlockImport	A light block-import handler for GRANDPA.
GrandpaParams	Parameters used to run Grandpa.
LinkHalf	Link between the block importer and the background voter.
ScheduledChange	A scheduled change of authority set.
SharedAuthoritySet	A shared authority set.
SharedVoterState	Shared voter state for querying.
ThreeQuartersOfTheUnfinalizedChain	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.
VotingRulesBuilder	A builder of a composite voting rule that applies a set of rules to progressively restrict the vote.

Enums

Error

Errors that can occur while voting in GRANDPA.

Traits

BlockNumberOps	Arithmetic necessary for a block number.
ClientForGrandpa	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
GenesisAuthoritySetProvider	Provider for the Grandpa authority set configured on the genesis block.
GrandpaApi	APIs for integrating the GRANDPA finality gadget into runtimes. This should be implemented on the runtime side.
StorageAndProofProvider	Trait that combines StorageProvider and ProofProvider
VotingRule	A trait for custom voting rules in GRANDPA.

Functions

block_import	Make block importer and link half necessary to tie the background voter to it.
block_import_with_authority_set_hard_forks	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.
light_block_import	Create light block importer.
run_grandpa_voter	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.
setup_disabled_grandpa	When GRANDPA is not initialized we still need to register the finality tracker inherent provider which might be expected by the runtime for block authoring. Additionally, we register a gossip message validator that discards all GRANDPA messages (otherwise, we end up banning nodes that send us a Neighbor message, since there is no registered gossip validator for the engine id defined in the message.)

Type Definitions

AuthorityId	Identity of a Grandpa authority.
AuthorityPair	The grandpa crypto scheme defined via the keypair type.
CatchUp	A catch up message for this chain’s block type.
Commit	A commit message for this chain’s block type.
CompactCommit	A compact commit message for this chain’s block type.
Message	A GRANDPA message for a substrate chain.
Precommit	A precommit message for this chain’s block type.
Prevote	A prevote message for this chain’s block type.
PrimaryPropose	A primary propose message for this chain’s block type.
SignedMessage	A signed message.