Crate pallet_block_production_log 

A Substrate pallet maintaining a consumable log of block production information.

Purpose of this pallet

This pallet keeps a log containing block producer IDs along with times of blocks produced by them. This log is updated every block and is meant to consumed by other features. The intended use of this pallet within the Partner Chains SDK is to expose block production data for consumption by the Block Participation feature implemented by the sp_block_participation and pallet_block_participation crates.

Usage - PC Builder

Adding to the runtime

The feature requires two types to be defind by the chain builders in their code:

• BlockProducerId: the type representing the block author
• Moment: a moment in time when the block was produced, which carries enough information to calculate the block’s author. Typcally, this type can be a timestamp, or a slot, depending on the consensus mechanism used, but can be a richer type if needed.

In addition, implementations of GetAuthor and GetMoment must be provided that can be used to retrieve the current block’s author and moment when it was produced.

An example configuration for a runtime using Aura consensus and Partner Chain toolkit’s session management pallet might look like this:

impl pallet_block_production_log::Config for Runtime {
    type BlockProducerId = BlockAuthor;

    type Moment = Slot;

    type GetMoment = FromStorage<pallet_aura::CurrentSlot<Runtime>>;
    type GetAuthor = FromFindAuthorIndex<Runtime, Aura, u32>;
}

Defining block producer ID

The pallet expects the Partner Chain to provide a type representing its block producers. This type can be as simple as an Aura public key but can also be a more complex type if block producers are not a homogenous group. For example, in the context of a Partner Chain using Ariadne committee selection, it’s typical to have two kinds of block producers: permissioned producers provided by the governance authority and registered candidates recruited from among Cardano stake pool operators. In this instance an example author type could be:

use sidechain_domain::*;

pub enum BlockAuthor {
    Incentivized(CrossChainPublicKey, StakePoolPublicKey),
    ProBono(CrossChainPublicKey),
}

Keep in mind that other Partner Chains SDK components put their own constraints on the block author type that need to be adhered to for a Partner Chain to integrated them.

Defining moment type

The pallet abstracts away the notion of time when a block was produced and allows the chain builders to configure it according to their chain’s needs by providing a Moment type. This type can be a timestamp, a slot or round number, depending on the consensus mechanism used.

Support for adding to a running chain

The pallet is written in a way that allows for adding it to an already live chain.

Consuming the log

Important: Consuming the log is a destructive operation. Multiple features should not consume the log data unless they are coordinated to read and clear the same log prefix.

The pallet exposes three functions that allow other pallets to consume its data: take_prefix, peek_prefix and drop_prefix. Any feature using the log should be able to identify the time up to which it should process the log data and either:

• call take_prefix from some pallet’s logic and process the returned data within the same block
• call peek_prefix inside an inherent data provider and use drop_prefix from the corresponding pallet to clear the previously peeked data within the same block

It is critically important to drop exactly the prefix processed to avoid either skipping or double-counting some blocks.

Usage - PC user

This pallet does not expose any user-facing functionalities.

Re-exports

pub use weights::WeightInfo;

pub use pallet::*;

Modules

pallet

The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.

weights

Autogenerated weights for pallet_block_production_log

Structs

FromFindAuthorIndex

GetAuthor implementation that uses a [FindAuthor] instance to get the current block’s author index of type I and uses it to read the author from pallet_session_validator_management.

FromStorage

GetMoment implementation that fetches current block’s Moment from storage S

Traits

GetAuthor

Source of the current block’s author

GetMoment

Source of the current block’s moment