Crate sp_block_participation

Crate providing block participation data through the inherent data mechanism.

Purpose of this crate

This crate provides logic to compute and expose as inherent data aggregated information on block producers’ and their delegators’ participation in block production. This feature is implemented in an unusual way in that it publishes inherent data but leaves it to the specific Partner Chain’s builders to implement the pallet that will consume this data. This is done because Partner Chains SDK can not anticipate how this data will have to be handled within every Partner Chain. The assumed use of the data provided is paying out of block production reward, however both ledger structure and reward calculation rules are inherently specific to their Partner Chain.

Outline of operation

1. The inherent data provider calls runtime API to check whether it should release block participation inherent data (all points below assume this check is positive) and gets the upper slot limit.
2. The inherent data provider retrieves data on block production up to the slot limit using runtime API and Cardano delegation data using observability data source. The IDP joins and aggregates this data together producing block participation data.
3. The IDP puts the block participation data into the inherent data of the current block, under the inherent identifier indicated by the runtime API. This inherent identifier belongs to the Partner Chain’s custom handler crate.
4. The IDP produces an additional “operational” inherent data to signal its own pallet that participation data has been released.
5. The Partner Chain’s custom handler pallet consumes the block participation inherent data and produces an inherent that performs block rewards payouts or otherwise handles the data according to this particular Partner Chain’s rules.
6. The block participation pallet consumes the operational inherent data and cleans up block production data up to the slot limit.

Usage

To incorporate this feature into a Partner Chain, one must do the following:

1. Implement a pallet consuming inherent data of type BlockProductionData
2. Include the block participation pallet into their runtime and configure it. Consult the documentation of pallet_block_participation for details.
3. Implement BlockParticipationApi for their runtime.
4. Include inherent_data::BlockParticipationInherentDataProvider in their node’s inherent data provider set for both proposal and verification of blocks.

Configuring the pallet and implementing the runtime API requires there to be a source of block production data present in the runtime that can be used by the feature. The intended source is pallet_block_production_log but in principle anu pallet offering a similar interfaces can be used. An example of runtime API implementation using the block participation log pallet looks like the following:

impl sp_block_participation::BlockParticipationApi<Block, BlockAuthor> for Runtime {
	fn should_release_data(slot: Slot) -> Option<Slot> {
		BlockParticipationPallet::should_release_data(slot)
	}
	fn blocks_produced_up_to_slot(slot: Slot) -> Vec<(Slot, BlockAuthor)> {
		<Runtime as pallet_block_participation::Config>::blocks_produced_up_to_slot(slot).collect()
	}
	fn target_inherent_id() -> InherentIdentifier {
		<Runtime as pallet_block_participation::Config>::TARGET_INHERENT_ID
	}
}

Modules

inherent_data

Inherent data provider definitions and implementation for Block Producer feature

Structs

BlockProducerParticipationData

Aggregated data on block production of one block producer in one aggregation period.

BlockProductionData

Aggregated data on block production, grouped by the block producer and aggregation period (main chain epoch).

DelegatorBlockParticipationData

Represents a block producer’s delegator along with their number of shares in that block producer’s pool.

Slot

Unit type wrapper that represents a slot.

SlotDuration

A slot duration defined in milliseconds.

Enums

InherentError

Error type returned by the Block Participation pallet’s inherent

Constants

INHERENT_IDENTIFIER

Inherent identifier used by the Block Participation pallet

Traits

AsCardanoSPO

Signifies that a type or some of its variants represents a Cardano stake pool operator

BlockParticipationApi

Runtime api exposing configuration and runtime bindings necessary for inherent_data::BlockParticipationInherentDataProvider.

CardanoDelegator

Signifies that a type represents a Cardano delegator