change: ETCM-9687 docs and small fixes for native token crates (#809)

Author: AmbientTea

demo/node/src/staging.rs

@@ -150,7 +150,7 @@ pub fn staging_genesis(
 			main_chain_scripts: sp_session_validator_management::MainChainScripts::read_from_env()?,
 		},
 		native_token_management: NativeTokenManagementConfig {
-			main_chain_scripts: sp_native_token_management::MainChainScripts::read_from_env()?,
+			main_chain_scripts: Some(sp_native_token_management::MainChainScripts::read_from_env()?),
 			..Default::default()
 		},
 		governed_map: GovernedMapConfig {

demo/node/src/template_chain_spec.rs

@@ -40,7 +40,7 @@ pub fn chain_spec() -> Result<ChainSpec, envy::Error> {
 			main_chain_scripts: sp_session_validator_management::MainChainScripts::read_from_env()?,
 		},
 		native_token_management: NativeTokenManagementConfig {
-			main_chain_scripts: sp_native_token_management::MainChainScripts::read_from_env()?,
+			main_chain_scripts: Some(sp_native_token_management::MainChainScripts::read_from_env()?),
 			..Default::default()
 		},
 		governed_map: GovernedMapConfig {

demo/node/src/testnet.rs

@@ -202,7 +202,7 @@ pub fn testnet_genesis(
 			main_chain_scripts: sp_session_validator_management::MainChainScripts::read_from_env()?,
 		},
 		native_token_management: NativeTokenManagementConfig {
-			main_chain_scripts: sp_native_token_management::MainChainScripts::read_from_env()?,
+			main_chain_scripts: Some(sp_native_token_management::MainChainScripts::read_from_env()?),
 			..Default::default()
 		},
 		governed_map: GovernedMapConfig {

toolkit/native-token-management/pallet/src/benchmarking.rs

@@ -4,7 +4,6 @@
 
 use super::*;
 use crate::Pallet as NativeTokenManagement;
-
 use frame_benchmarking::v2::*;
 use frame_system::RawOrigin;
 

toolkit/native-token-management/pallet/src/lib.rs

@@ -1,5 +1,7 @@
 //! Pallet allowing Partner Chains to support movement of their native token from Cardano.
 //!
+//! # Context and purpose of this pallet
+//!
 //! Partner Chains Smart Contracts establish a notion of liquid and illiquid supply of the native
 //! token on Cardano, represented as native tokens being either freely available in user accounts
 //! or locked under a designated illiquid supply address. Movement of native tokens into the illiquid
@@ -9,12 +11,97 @@
 //! This pallet consumes inherent data containing information on the amount of native tokens newly
 //! locked on Cardano and produces an inherent extrinsic to handle their movement. The specific
 //! logic releasing the tokens is left for the Partner Chain developer to implement and is configured
-//! in the pallet via the `TokenTransferHandler`.
+//! in the pallet via the [TokenTransferHandler] trait.
+//!
+//! *IMPORTANT*: The mechanism implemented by this pallet is only concerned with the amount of tokens
+//!              moved and does not attach any metadata to the transfers. In particular it is not a
+//!              fully-featured token bridge and needs to be combined with a separate sender-receiver
+//!              metadata channel to implement one.
+//!
+//! # Usage
+//!
+//! ## Defining a transfer handler
+//!
+//! The main purpose of the pallet is to trigger user-defined runtime logic whenever a new batch of
+//! tokens is observed to have been locked on Cardano. To do that, the Partner Chain builder should
+//! define a type implementing the [TokenTransferHandler] trait, eg.:
+//!
+//! ```rust
+//! use sidechain_domain::NativeTokenAmount;
+//! use frame_support::pallet_prelude::DispatchResult;
+//!
+//! pub struct TransferHandler;
+//! impl pallet_native_token_management::TokenTransferHandler for TransferHandler {
+//! 	fn handle_token_transfer(token_amount: NativeTokenAmount) -> DispatchResult {
+//! 		log::info!("💸 Registered transfer of {} native tokens", token_amount.0);
+//! 		Ok(())
+//! 	}
+//! }
+//! ```
+//!
+//! ## Adding to the runtime
+//!
+//! Aside from the transfer handler, the pallet requires minimal runtime configuration: the runtime event
+//! type, origin for governance calls implementing [EnsureOrigin] and weights:
+//!
+//! ```rust,ignore
+//! impl pallet_native_token_management::Config for Runtime {
+//! 	type RuntimeEvent = RuntimeEvent;
+//! 	type TokenTransferHandler = TransferHandler;
+//! 	type MainChainScriptsOrigin = frame_system::EnsureRoot<Self::AccountId>;
+//! 	type WeightInfo = pallet_native_token_management::weights::SubstrateWeight<Runtime>;
+//! }
+//! ```
+//!
+//! Keep in mind that if the handler logic has to perform storage operations, the pallet's benchmarks
+//! should be rerun. Otherwise default weights are provided in [pallet_native_token_management::weights].
+//!
+//! ## Script configuration
+//!
+//! For token transfers to be observed, the pallet must be configured with correct Cardano addresses and
+//! scripts used to idendify them in the ledger. These scripts can be set in two ways: through genesis
+//! configuration if the pallet is present in the initial runtime of a chain; or via a governance action
+//! using the [set_main_chain_scripts] extrinsic.
+//!
+//! ### Genesis configuratin
+//!
+//! Initial main chain scripts can be set in the genesis configuration, like so:
+//! ```json
+//! {
+//!   "nativeTokenManagement": {
+//!     "mainChainScripts": {
+//!       "illiquid_supply_validator_address": "0x616464725f74657374317772687674767833663067397776397278386b66716336306a7661336530376e71756a6b32637370656b76346d717339726a64767a",
+//!       "native_token_asset_name": "0x5043546f6b656e44656d6f",
+//!       "native_token_policy_id": "0xada83ddd029614381f00e28de0922ab0dec6983ea9dd29ae20eef9b4"
+//!     }
+//!   }
+//! }
+//! ```
+//!
+//! Note that the `mainChainScripts` field is optional. If it is left empty, the pallet will stay inactive
+//! until configuration is set later.
+//!
+//! ### Main chain scripts extrinsic
+//!
+//! Once the chain is already started, to set initial main chain scripts to a newly added pallet, or to
+//! change the existing ones, the [set_main_chain_scripts] extrinsic must be submitted through on-chain
+//! governance mechanism like `sudo` or `pallet_democracy`. Who exactly can submit this extrinsic is
+//! controlled by the [Config::MainChainScriptsOrigin] field of the pallet's configuration, but for security
+//! it must be a trusted entity.
+//!
+//! #### Initialization state of the pallet
 //!
-//! IMPORTANT: The mechanism implemented via the pallet in this crate is only concerned with the
-//!            amount of tokens moved and does not attach any metadata to the transfers. In particular
-//!            it is not a fully-featured token bridge and needs to be combined with a separate
-//!            sender-receiver metadata channel to implement one.
+//! The pallet tracks its own initialization state through the [Initialized] storage flag. This information
+//! is necessary for it to correctly observe historical data and the state is reset every time main chain
+//! scripts are changed in the pallet. This allows the Partner Chain governance to switch to new versions
+//! of the smart contracts. However, some consideration must be taken while changing the scripts:
+//! 1. This mechanism can not handle changing the main chain scripts to values that were used before.
+//!    Doing so will cause some transfers to be registered again, resulting in potential double-spend.
+//!    This means that a script version roll-back is not possible.
+//! 2. Moving funds from an old illiquid supply address to a new one requires unlocking them and re-locking
+//!    at the new address, resulting in a new transfer being observed. The logic handling the token movement,
+//!    including the transfer handler, must be able to handle this unlock-relock behaviour if a Partner Chain
+//!    governance wishes to migrate tokens to the new address.
 //!
 #![cfg_attr(not(feature = "std"), no_std)]
 #![deny(missing_docs)]
@@ -106,15 +193,15 @@ pub mod pallet {
 	#[derive(frame_support::DefaultNoBound)]
 	pub struct GenesisConfig<T: Config> {
 		/// Initial main chain scripts
-		pub main_chain_scripts: sp_native_token_management::MainChainScripts,
+		pub main_chain_scripts: Option<sp_native_token_management::MainChainScripts>,
 		#[allow(missing_docs)]
 		pub _marker: PhantomData<T>,
 	}
 
 	#[pallet::genesis_build]
 	impl<T: Config> BuildGenesisConfig for GenesisConfig<T> {
 		fn build(&self) {
-			MainChainScriptsConfiguration::<T>::put(self.main_chain_scripts.clone());
+			MainChainScriptsConfiguration::<T>::set(self.main_chain_scripts.clone());
 		}
 	}
 

toolkit/native-token-management/pallet/src/mock.rs

@@ -87,8 +87,14 @@ impl crate::pallet::Config for Test {
 impl mock_pallet::Config for Test {}
 
 pub fn new_test_ext() -> sp_io::TestExternalities {
-	RuntimeGenesisConfig { system: Default::default(), native_token_management: Default::default() }
-		.build_storage()
-		.unwrap()
-		.into()
+	RuntimeGenesisConfig {
+		system: Default::default(),
+		native_token_management: NativeTokenManagementConfig {
+			main_chain_scripts: Some(Default::default()),
+			..Default::default()
+		},
+	}
+	.build_storage()
+	.unwrap()
+	.into()
 }

toolkit/native-token-management/primitives/src/lib.rs

@@ -1,4 +1,83 @@
+//! 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:
+//! ```rust,ignore
+//! 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:
+//!
+//! ```rust
+//! 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.
+//!
+//! [NativeTokenManagementApi]: sp_native_token_management::NativeTokenManagementApi
 #![cfg_attr(not(feature = "std"), no_std)]
+#![deny(missing_docs)]
 
 #[cfg(feature = "std")]
 use {core::str::FromStr, sp_runtime::traits::Block as BlockT};
@@ -14,6 +93,7 @@ use sp_runtime::scale_info::TypeInfo;
 #[cfg(test)]
 mod tests;
 
+/// Inherent identifier used by the Native Token Management pallet
 pub const INHERENT_IDENTIFIER: InherentIdentifier = *b"nattoken";
 
 /// Values identifying on-chain entities involved in the native token management system on Cardano.
@@ -31,9 +111,15 @@ pub struct MainChainScripts {
 
 #[cfg(feature = "std")]
 impl MainChainScripts {
+	/// Reads the main chain script values from local environment variables
+	///
+	/// It expects the following variables to be set:
+	/// - `NATIVE_TOKEN_POLICY_ID`
+	/// - `NATIVE_TOKEN_ASSET_NAME`
+	/// - `ILLIQUID_SUPPLY_VALIDATOR_ADDRESS`
 	pub fn read_from_env() -> Result<Self, envy::Error> {
 		#[derive(serde::Serialize, serde::Deserialize)]
-		pub struct MainChainScriptsEnvConfig {
+		struct MainChainScriptsEnvConfig {
 			pub native_token_policy_id: PolicyId,
 			pub native_token_asset_name: AssetName,
 			pub illiquid_supply_validator_address: String,
@@ -57,29 +143,37 @@ impl MainChainScripts {
 }
 
 sp_api::decl_runtime_apis! {
+	/// Runtime API exposing configuration and initialization status of the Native Token Management pallet
 	pub trait NativeTokenManagementApi {
+		/// Returns the current main chain scripts configured in the pallet or [None] if they are not set.
 		fn get_main_chain_scripts() -> Option<MainChainScripts>;
 		/// Gets current initializaion status and set it to `true` afterwards. This check is used to
 		/// determine whether historical data from the beginning of main chain should be queried.
 		fn initialized() -> bool;
 	}
 }
 
+/// Data about token transfers in some period of time
 #[derive(Decode, Encode)]
 pub struct TokenTransferData {
+	/// Aggregate number of tokens transfered
 	pub token_amount: NativeTokenAmount,
 }
 
+/// Error type returned by the Native Token Management pallet inherent logic
 #[derive(Encode, Debug, PartialEq)]
 #[cfg_attr(feature = "std", derive(Decode, thiserror::Error))]
 pub enum InherentError {
+	/// Signals that no inherent was submitted despite new token transfers being observed
 	#[cfg_attr(feature = "std", error("Inherent missing for token transfer of {0} tokens"))]
 	TokenTransferNotHandled(NativeTokenAmount),
+	/// Signals that the inherent registered an incorrect number of tokens transfered
 	#[cfg_attr(
 		feature = "std",
 		error("Incorrect token transfer amount: expected {0}, got {1} tokens")
 	)]
 	IncorrectTokenNumberTransfered(NativeTokenAmount, NativeTokenAmount),
+	/// Signals that an inherent was submitted when no token transfers were observed
 	#[cfg_attr(feature = "std", error("Unexpected transfer of {0} tokens"))]
 	UnexpectedTokenTransferInherent(NativeTokenAmount),
 }
@@ -97,6 +191,7 @@ mod inherent_provider {
 	use std::error::Error;
 	use std::sync::Arc;
 
+	/// Interface for a data source serving native token transfer data compatible with [NativeTokenManagementInherentDataProvider].
 	#[async_trait::async_trait]
 	pub trait NativeTokenManagementDataSource {
 		/// Retrieves total of native token transfers into the illiquid supply in the range (after_block, to_block]
@@ -113,13 +208,17 @@ mod inherent_provider {
 	///
 	/// This IDP will not provide any inherent data if `token_amount` is [None], but *will* provide data for `Some(0)`.
 	pub struct NativeTokenManagementInherentDataProvider {
+		/// Aggregate number of tokens transfered
 		pub token_amount: Option<NativeTokenAmount>,
 	}
 
+	/// Error type returned when creation of [NativeTokenManagementInherentDataProvider] fails
 	#[derive(thiserror::Error, sp_runtime::RuntimeDebug)]
 	pub enum IDPCreationError {
+		/// Signals that the data source used returned an error
 		#[error("Failed to read native token data from data source: {0:?}")]
 		DataSourceError(Box<dyn Error + Send + Sync>),
+		/// Signals that a runtime API call failed
 		#[error("Failed to call runtime API: {0:?}")]
 		ApiError(ApiError),
 	}
@@ -208,6 +307,7 @@ mod inherent_provider {
 		}
 	}
 
+	/// Mock implementation of the data source
 	#[cfg(any(test, feature = "mock"))]
 	pub mod mock {
 		use crate::{MainChainScripts, NativeTokenManagementDataSource};
@@ -216,6 +316,7 @@ mod inherent_provider {
 		use sidechain_domain::*;
 		use std::collections::HashMap;
 
+		/// Mock implementation of [NativeTokenManagementDataSource]
 		#[derive(new, Default)]
 		pub struct MockNativeTokenDataSource {
 			transfers: HashMap<(Option<McBlockHash>, McBlockHash), NativeTokenAmount>,