Crate sp_native_token_management

Primitives and inherent data provider for the Native Token Management feature

Purpose and context

This crate defines shared types used by components that implement the Native Token Management feature of the Partner Chains toolkit, along with an inherent data provider for token transfer data.

The Native Token Management feature allows a Partner Chain to keep its token as a native asset on Cardano and have it be transferable to the Partner Chain. This is achieved by the native token being locked at an illiquid supply address on Cardano, and the Partner Chain handling this locking event (a transfer) after it has been observed as part of a stable block.

The inherent data provider defined in this crate is responsible for providing information about the transfers in form of inherent data, and handling them is the responsibility of the pallet, which allows the Partner Chain builders to define their own transfer handling logic to suit their needs.

Usage

Prerequisites

This features depends on the MC Reference Hash feature to provide Cardano block reference for querying the token transfers. See the documentation of sidechain_mc_hash crate for more information.

Implementing runtime APIs

NativeTokenManagementInherentDataProvider requires the runtime to implement the NativeTokenManagementApi runtime API. This only requires passing relevant values from the pallet:

impl sp_native_token_management::NativeTokenManagementApi<Block> for Runtime {
	fn get_main_chain_scripts() -> Option<sp_native_token_management::MainChainScripts> {
		NativeTokenManagement::get_main_chain_scripts()
	}
	fn initialized() -> bool {
		NativeTokenManagement::initialized()
	}
}

Adding the inherent data provider

The inherent data provider requires a data source implementing NativeTokenManagementDataSource. A Db-Sync implementation is provided by the partner_chains_db_sync_data_sources crate.

With the data source present, the IDP is straightfoward to create:

use std::sync::Arc;
use sp_runtime::traits::Block as BlockT;
use sp_native_token_management::*;

async fn create_idps<Block: BlockT, C>(
    parent_hash: Block::Hash,
    client: Arc<C>,
    native_token_data_source: &(dyn NativeTokenManagementDataSource + Send + Sync)
) -> Result<(NativeTokenManagementInherentDataProvider /* other IDPs */), Box<dyn std::error::Error + Send + Sync>>
where
    C: sp_api::ProvideRuntimeApi<Block> + Send + Sync,
    C::Api: NativeTokenManagementApi<Block>
{
    let (mc_hash, previous_mc_hash) = todo!("Should come from the MC Reference Hash feature");

    let native_token_idp = NativeTokenManagementInherentDataProvider::new(
    	client.clone(),
    	native_token_data_source,
    	mc_hash,
    	previous_mc_hash,
    	parent_hash,
    )
    .await?;
    Ok((native_token_idp /* other IDPs */))
}

The same constructor can be used for both proposal and validation of blocks.

Structs

MainChainScripts

Values identifying on-chain entities involved in the native token management system on Cardano.

NativeTokenManagementInherentDataProvider

Inherent data provider that provides aggregate number of native token transfers to the illiquid supply on Cardano in some time range.

TokenTransferData

Data about token transfers in some period of time

Enums

IDPCreationError

Error type returned when creation of NativeTokenManagementInherentDataProvider fails

InherentError

Error type returned by the Native Token Management pallet inherent logic

Constants

INHERENT_IDENTIFIER

Inherent identifier used by the Native Token Management pallet

Traits

NativeTokenManagementApi

Runtime API exposing configuration and initialization status of the Native Token Management pallet

NativeTokenManagementDataSource

Interface for a data source serving native token transfer data compatible with NativeTokenManagementInherentDataProvider.