Trait finality_grandpa::voter::Environment

pub trait Environment<H: Eq, N: BlockNumberOps>: Chain<H, N> {
    type Timer: Future<Output = Result<(), Self::Error>> + Unpin;
    type BestChain: Future<Output = Result<Option<(H, N)>, Self::Error>> + Send + Unpin;
    type Id: Clone + Eq + Ord + Debug;
    type Signature: Eq + Clone;
    type In: Stream<Item = Result<SignedMessage<H, N, Self::Signature, Self::Id>, Self::Error>> + Unpin;
    type Out: Sink<Message<H, N>, Error = Self::Error> + Unpin;
    type Error: From<Error> + Error;

    // Required methods
    fn best_chain_containing(&self, base: H) -> Self::BestChain;
    fn round_data(
        &self,
        round: u64
    ) -> RoundData<Self::Id, Self::Timer, Self::In, Self::Out>;
    fn round_commit_timer(&self) -> Self::Timer;
    fn proposed(
        &self,
        round: u64,
        propose: PrimaryPropose<H, N>
    ) -> Result<(), Self::Error>;
    fn prevoted(
        &self,
        round: u64,
        prevote: Prevote<H, N>
    ) -> Result<(), Self::Error>;
    fn precommitted(
        &self,
        round: u64,
        precommit: Precommit<H, N>
    ) -> Result<(), Self::Error>;
    fn completed(
        &self,
        round: u64,
        state: RoundState<H, N>,
        base: (H, N),
        votes: &HistoricalVotes<H, N, Self::Signature, Self::Id>
    ) -> Result<(), Self::Error>;
    fn concluded(
        &self,
        round: u64,
        state: RoundState<H, N>,
        base: (H, N),
        votes: &HistoricalVotes<H, N, Self::Signature, Self::Id>
    ) -> Result<(), Self::Error>;
    fn finalize_block(
        &self,
        hash: H,
        number: N,
        round: u64,
        commit: Commit<H, N, Self::Signature, Self::Id>
    ) -> Result<(), Self::Error>;
    fn prevote_equivocation(
        &self,
        round: u64,
        equivocation: Equivocation<Self::Id, Prevote<H, N>, Self::Signature>
    );
    fn precommit_equivocation(
        &self,
        round: u64,
        equivocation: Equivocation<Self::Id, Precommit<H, N>, Self::Signature>
    );
}

Necessary environment for a voter.

This encapsulates the database and networking layers of the chain.

Required Associated Types

type Timer: Future<Output = Result<(), Self::Error>> + Unpin

Associated timer type for the environment. See also Self::round_data and Self::round_commit_timer.

type BestChain: Future<Output = Result<Option<(H, N)>, Self::Error>> + Send + Unpin

Associated future type for the environment used when asynchronously computing the best chain to vote on. See also Self::best_chain_containing.

type Id: Clone + Eq + Ord + Debug

The associated Id for the Environment.

type Signature: Eq + Clone

The associated Signature type for the Environment.

type In: Stream<Item = Result<SignedMessage<H, N, Self::Signature, Self::Id>, Self::Error>> + Unpin

The input stream used to communicate with the outside world.

type Out: Sink<Message<H, N>, Error = Self::Error> + Unpin

The output stream used to communicate with the outside world.

type Error: From<Error> + Error

The associated Error type.

Required Methods

fn best_chain_containing(&self, base: H) -> Self::BestChain

Return a future that will resolve to the hash of the best block whose chain contains the given block hash, even if that block is base itself.

If base is unknown the future outputs None.

fn round_data( &self, round: u64 ) -> RoundData<Self::Id, Self::Timer, Self::In, Self::Out>

Produce data necessary to start a round of voting. This may also be called with the round number of the most recently completed round, in which case it should yield a valid input stream.

The input stream should provide messages which correspond to known blocks only.

The voting logic will push unsigned messages over-eagerly into the output stream. It is the job of this stream to determine if those messages should be sent (for example, if the process actually controls a permissioned key) and then to sign the message, multicast it to peers, and schedule it to be returned by the In stream.

This allows the voting logic to maintain the invariant that only incoming messages may alter the state, and the logic remains the same regardless of whether a node is a regular voter, the proposer, or simply an observer.

Furthermore, this means that actual logic of creating and verifying signatures is flexible and can be maintained outside this crate.

fn round_commit_timer(&self) -> Self::Timer

Return a timer that will be used to delay the broadcast of a commit message. This delay should not be static to minimize the amount of commit messages that are sent (e.g. random value in [0, 1] seconds).

fn proposed( &self, round: u64, propose: PrimaryPropose<H, N> ) -> Result<(), Self::Error>

Note that we’ve done a primary proposal in the given round.

fn prevoted( &self, round: u64, prevote: Prevote<H, N> ) -> Result<(), Self::Error>

Note that we have prevoted in the given round.

fn precommitted( &self, round: u64, precommit: Precommit<H, N> ) -> Result<(), Self::Error>

Note that we have precommitted in the given round.

fn completed( &self, round: u64, state: RoundState<H, N>, base: (H, N), votes: &HistoricalVotes<H, N, Self::Signature, Self::Id> ) -> Result<(), Self::Error>

Note that a round is completed. This is called when a round has been voted in and the next round can start. The round may continue to be run in the background until concluded. Should return an error when something fatal occurs.

fn concluded( &self, round: u64, state: RoundState<H, N>, base: (H, N), votes: &HistoricalVotes<H, N, Self::Signature, Self::Id> ) -> Result<(), Self::Error>

Note that a round has concluded. This is called when a round has been completed and additionally, the round’s estimate has been finalized.

There may be more votes than when completed, and it is the responsibility of the Environment implementation to deduplicate. However, the caller guarantees that the votes passed to completed for this round are a prefix of the votes passed here.

fn finalize_block( &self, hash: H, number: N, round: u64, commit: Commit<H, N, Self::Signature, Self::Id> ) -> Result<(), Self::Error>

Called when a block should be finalized.

fn prevote_equivocation( &self, round: u64, equivocation: Equivocation<Self::Id, Prevote<H, N>, Self::Signature> )

Note that an equivocation in prevotes has occurred.

fn precommit_equivocation( &self, round: u64, equivocation: Equivocation<Self::Id, Precommit<H, N>, Self::Signature> )

Note that an equivocation in precommits has occurred.

Implementors