Trait Application 

pub trait Application<E>:
    Clone
    + Send
    + 'static {
    type SigningScheme: Scheme;
    type Context: Epochable;
    type Block: Block;
    type Input: Send;

    // Required methods
    fn propose(
        &mut self,
        context: (E, Self::Context),
        ancestry: impl Ancestry<Self::Block>,
        input: Self::Input,
    ) -> impl Future<Output = Option<Digested<Self::Block>>> + Send;
    fn verify(
        &mut self,
        context: (E, Self::Context),
        ancestry: impl Ancestry<Self::Block>,
    ) -> impl Future<Output = bool> + Send;

    // Provided method
    fn prepare(
        &mut self,
        _context: (E, Self::Context),
        _ancestry: impl Ancestry<Self::Block>,
        _input: Self::Input,
    ) -> impl Future<Output = Handoff<Digested<Self::Block>>> + Send { ... }
}

Application is a minimal interface for standard implementations that operate over a stream of epoched blocks.

Required Associated Types

type SigningScheme: Scheme

The signing scheme used by the application.

type Context: Epochable

Context is metadata provided by the consensus engine associated with a given payload.

This often includes things like the proposer, view number, the height, or the epoch.

type Block: Block

The block type produced by the application’s builder.

The builder hands marshal a Digested block, so the application computes the digest of a block it built exactly once, on its own strategy, before returning it.

type Input: Send

Per-proposal input handed to prepare and propose. Applications that need no input set this to ().

Required Methods

fn propose( &mut self, context: (E, Self::Context), ancestry: impl Ancestry<Self::Block>, input: Self::Input, ) -> impl Future<Output = Option<Digested<Self::Block>>> + Send

Build a new block on top of the provided parent ancestry. If the build job fails, or the proposer’s slot should be skipped, the implementor should return None.

input is the per-proposal input for this build.

This future may be cancelled before it completes. Implementations must be cancellation-safe.

fn verify( &mut self, context: (E, Self::Context), ancestry: impl Ancestry<Self::Block>, ) -> impl Future<Output = bool> + Send

Verify a block produced by the application’s proposer, relative to its ancestry.

This future should not resolve until the implementation can produce a stable verdict. Return false only when the block is permanently invalid for the supplied context and ancestry. If validity may still change as additional information becomes available, continue waiting instead of returning false.

In other words, to abstain from voting, do not resolve this future yet. Keep it pending until the implementation can either prove the block valid, prove it invalid, or the consensus engine cancels the request. Abstaining is not represented by a special return value.

This future may be cancelled before it completes. Implementations must be cancellation-safe.

Provided Methods

fn prepare( &mut self, _context: (E, Self::Context), _ancestry: impl Ancestry<Self::Block>, _input: Self::Input, ) -> impl Future<Output = Handoff<Digested<Self::Block>>> + Send

Build a block on a parent that has not yet certified, or decline with Handoff::Wait.

The marshal calls this in place of Self::propose for a term-start proposal whose parent is uncertified, with the same ancestry and after the same checks. It re-proposes the epoch boundary block and declines a parent it cannot build on with Handoff::Wait, in both cases without calling this method. The default declines.

With Handoff::Vote or Handoff::Stage, the marshal keeps the returned block for relay as it would a proposal. With Handoff::Wait, consensus waits for parent certification before requesting Self::propose for the same context, unless it has voted to nullify the context’s view or has left it. The decision is final for the request.

With deferred or coded verification, a prepared build can start before this node has verified the parent’s contents. The parent may later fail certification, which discards the candidate.

Parent certification does not cancel a prepared build. Consensus cancels it once the parent can no longer be built on before it certifies, as after a nullification in the parent’s term, or once it votes to nullify the view it is waiting in, at or below the parent. Unless it has voted to nullify the proposal’s view or has left it, it then requests an ordinary proposal for the same context if the parent certifies, or can request a proposal on a replacement parent once one is selectable.

Handoff::Vote trusts the outgoing consensus leader not to equivocate and to complete its term (see Handoff::Vote). The context names the parent by view and digest, and its leader field names the incoming leader, not the outgoing one. Identify the outgoing leader from the elector’s schedule or authenticated metadata for the parent’s consensus round. A verified parent block can name an earlier proposer in its embedded context, as with an epoch-boundary reproposal. If that identity or trust is uncertain, return Handoff::Stage, which can relay the block before the parent certifies but withholds the vote.

This future may be cancelled before it completes. Implementations must be cancellation-safe.

If readiness is uncertain, return Handoff::Wait.

A wrapper around another application must forward this method, since the default would otherwise replace the inner application’s choice with Handoff::Wait.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors