Crate sp_governed_map

Governed Map primitives

This crate provides shared types and logic of the Governed Map feature, together with its inherent data provider logic.

Usage

This crate supports operation of pallet_governed_map. Consult the pallet’s documentation on how to include it in the runtime

Adding to the node

Implementing the runtime API

GovernedMapInherentDataProvider requires access to the pallet’s configuration via a runtime API. Assuming the pallet has been added to the runtime and is named GovernedMap, the API should be implemented like this:

impl sp_governed_map::GovernedMapIDPApi<Block> for Runtime {
    fn get_main_chain_scripts() -> Option<MainChainScriptsV1> {
        GovernedMap::get_main_chain_scripts()
    }
    fn get_pallet_version() -> u32 {
        GovernedMap::get_version()
    }
}

Adding the data source

GovernedMapInherentDataProvider needs a data source implementing the GovernedMapDataSource trait. For nodes using Db-Sync, one is provided by the partner_chains_db_sync_data_sources crate. Consult its documentation for more information.

Adding the inherent data provider

The GovernedMapInherentDataProvider should be added to your IDP stack using GovernedMapInherentDataProvider::new for both block proposal and validation, like so:

type InherentDataProviders = (/* other IDPs */ GovernedMapInherentDataProvider);
async fn create_idps<T, Block>(
    client: &T,
    governed_map_data_source: &(impl GovernedMapDataSource + Send + Sync),
    parent_hash: Block::Hash,
) -> Result<InherentDataProviders, Box<dyn std::error::Error + Send + Sync>>
where
    Block: sp_runtime::traits::Block,
    T: sp_api::ProvideRuntimeApi<Block> + Send + Sync,
    T::Api: GovernedMapIDPApi<Block> + Send + Sync
{
    /*
     Create other IDPs
     */
    let governed_map = GovernedMapInherentDataProvider::new(
        client,
        parent_hash,
        mc_hash,
        previous_mc_hash,
        governed_map_data_source
    )
    .await?;
    Ok((/* other IDPs */ governed_map))

Note that it requires access to the current and previous referenced Cardano block hash (mc_hash and previous_mc_hash). These are provided by the Partner Chains Toolkit’s MC Hash inherent data provider from the sidechain_mc_hash crate.

Adding to a running chain

As with any other feature, if the Governed Map feature is to be added to an already running chain, a strict order of operations is required:

1. The node should be updated according to the steps described above, so that the inherent data provider is present in the nodes IDP stack for both proposal and verfication.
2. The updated node binary should be distributed to the block producers who should update their nodes.
3. A new runtime version should be released with the pallet added according to its documentation and the runtime API implemented as described above.
4. The Governed Map main chain scripts should be set through the set_main_chain_scripts extrinsic in the pallet.

GovernedMapInherentDataProvider is version-aware and will stay inactive until the pallet is added and fully configured.

Structs

MainChainScriptsV1

Cardano identifiers necessary for observation of the Governed Map

Enums

GovernedMapInherentDataProvider

Inherent data provider providing the list of Governed Map changes that occurred since previous observation.

InherentError

Error type returned when creating or validating the Governed Map inherent

InherentProviderCreationError

Error type returned when creation of GovernedMapInherentDataProvider fails.

Constants

INHERENT_IDENTIFIER

Inherent identifier used by the Governed Map pallet

Traits

GovernedMapDataSource

Cardano observability data source API used by GovernedMapInherentDataProvider.

GovernedMapIDPApi

Runtime API exposing data required for the GovernedMapInherentDataProvider to operate.

OnGovernedMappingChange

Handler trait for runtime components which need to react to changes in the Governed Map.

Type Aliases

GovernedMapInherentDataV1

Inherent data produced by the Governed Map observation