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

  • 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.
  • AuthoritySetHardFork
    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).
  • BeforeBestBlockBy
    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.
  • 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.
  • 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

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. For standard protocol name see crate::protocol_standard_name.
  • protocol_standard_name
    Name of the notifications protocol used by GRANDPA.
  • revert
    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_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.

Type Definitions