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.
Utilities for generating and verifying GRANDPA warp sync proofs.

Structs

A set of authorities.
Tracks historical authority set changes. We store the block numbers for the last block of each authority set, once they have been finalized. These blocks are guaranteed to have a justification unless they were triggered by a forced change.
A descriptor for an authority set hard fork. These are authority set changes that are not signalled by the runtime and instead are defined off-chain (hence the hard fork).
A custom voting rule that guarantees that our vote is always behind the best block by at least N blocks, unless the base number is < N blocks behind the best, in which case it votes for the base.
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.
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.

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

Fetch the justification for the latest block finalized by GRANDPA, if any.
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.
Checks the given header for a consensus digest signalling a forced scheduled change and extracts it.
Checks the given header for a consensus digest signalling a standard scheduled change and extracts it.
Returns the configuration value to put in [sc_network::config::NetworkConfiguration::extra_sets]. For standard protocol name see crate::protocol_standard_name.
Name of the notifications protocol used by GRANDPA.
Reverts protocol aux data to at most the last finalized block. In particular, standard and forced authority set changes announced after the revert point are removed.
Run a GRANDPA observer as a task, the observer will finalize blocks only by listening for and validating GRANDPA commits instead of following the full protocol. Provide configuration and a link to a block import worker that has already been instantiated with block_import. NOTE: this is currently not part of the crate’s public API since we don’t consider it stable enough to use on a live network.
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.
The sending half of the Grandpa justification channel(s).
The receiving half of the Grandpa justification channel.
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.
A future returned by a VotingRule to restrict a given vote, if any restriction is necessary.