Crate sc_finality_grandpa[−][src]

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

report

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

warp_proof

Utilities for generating and verifying GRANDPA warp sync proofs.

Structs

AuthoritySet

A set of authorities.

AuthoritySetChanges

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.

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

FinalityProof

Finality for block B is proved by providing:

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.

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.

FinalityProofError

Errors occurring when trying to prove finality

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.

VotingRule

A trait for custom voting rules in GRANDPA.

Functions

best_justification

Fetch the justification for the latest block finalized by GRANDPA, if any.

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.

find_forced_change

Checks the given header for a consensus digest signalling a forced scheduled change and extracts it.

find_scheduled_change

Checks the given header for a consensus digest signalling a standard scheduled change and extracts it.

grandpa_peers_set_config

Returns the configuration value to put in sc_network::config::NetworkConfiguration::extra_sets.

run_grandpa_observer

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_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.