pallet_sidechain/

lib.rs

//! Pallet that establishes a Partner Chain as a Cardano sidechain
//!
//! # Purpose of this pallet
//!
//! This pallet serves as the starting point for building a Partner Chain runtime.
//! It stores its genesis UTXO which serves as its global identifier and divides
//! time into Partner Chain epochs.
//!
//! ## Genesis UTXO
//!
//! When a Partner Chain governance is initialized on Cardano, the transaction spends
//! a special _genesis UTXO_. This UTXO serves multiple crucial roles:
//! - it serves as the unique identifier of the Partner Chain
//! - it affects the addresses of all Partner Chain Toolkit's Plutus smart contracts
//!   to allow multiple Partner Chains to exist
//! - it is included in messages signed by various participants of the Partner Chain
//!   when submitting transactions (on both Cardano and the Partner Chain) to prevent
//!   replay attacks
//!
//! The genesis UTXO is immutable throughout the lifetime of a Partner Chain in order
//! to preserve its identity.
//!
//! ## Partner Chain Epochs
//!
//! When producing blocks, Partner Chains divide time epochs which other Partner
//! Chains features use as boundaries for some of their state transitions (eg. a Partner
//! Chain block producing committees change at epoch boundaries). Epoch duration should
//! be constant and immutable throughout a Partner Chain's lifetime.
//!
//! # Usage
//!
//! ## Prerequisites
//!
//! Before a Partner Chain can be started, its Cardano governance must be established by
//! running the _init_ transaction, which also determines the _genesis UTXO_ of the
//! Partner Chain. Consult `docs/user-guides/governance/governance.md` for instructions.
//!
//! ### Optional - defining a new epoch hook
//!
//! A Partner Chain may need to perform custom logic when a new epoch starts, eg. pay
//! out block production rewards, update chain participant standings etc. For this purpose,
//! the pallet can be configured with a handler that will be triggered during initialization
//! of each first block of a new epoch.
//!
//! To create a new epoch handler, simply define a type and have it implement the [sp_sidechain::OnNewEpoch] trait:
//! ```rust
//! use sidechain_domain::ScEpochNumber;
//! use sp_runtime::Weight;
//!
//! struct MyNewEpochHandler;
//! impl sp_sidechain::OnNewEpoch for MyNewEpochHandler {
//!     fn on_new_epoch(old_epoch: ScEpochNumber, new_epoch: ScEpochNumber) -> Weight {
//!         log::info!("Partner Chain epoch changed from {old_epoch} to {new_epoch}");
//!         Weight::zero()
//!     }
//! }
//! ```
//! The weight returned by `on_new_epoch` should match its real resource use.
//!
//! ## Adding to runtime
//!
//! The pallet requires minimal configuration, as it is only mandatory to inject the function
//! that provides a *reference timestamp*. This timestamp is not required to be the exact timestamp
//! of the block but must be close enough to it for the purpose of epoch calculation. For example,
//! a Partner Chain that uses Aura can use the starting time of the current slot as the reference.
//!
//! *Important*: The reference timestamp must be available during block initialization. Due to this,
//!              the timestamp stored by `pallet_timestamp` can not be used as it is only set during
//!              block execution. Chain builders that wish to use the exact block timestamp as the
//!              reference timestamp should store it in the pre-runtime digest.
//!
//! A complete configuration can like the following:
//! ```rust,ignore
//! pub const SLOT_DURATION: u64 = 6000;
//!
//! impl pallet_sidechain::Config for Runtime {
//!     fn reference_timestamp_millis() -> u64 {
//!         *pallet_aura::CurrentSlot::<Runtime>::get() * SLOT_DURATION
//!     }
//!     type OnNewEpoch = MyNewEpochHandler;
//! }
//! ```
//! Optionally, a new epoch handler can be configured like in the example above. Partner Chains
//! that do not need to run additional logic at epoch change can use the empty implementation
//! available for [()]:
//! ```rust
//! # struct MyNewEpochHandler;
//! type OnNewEpoch = MyNewEpochHandler;
//! ```
//! If multiple handlers need to be added, a tuple can be used for convenience:
//! ```rust
//! # struct NewEpochHandler1;
//! # struct NewEpochHandler2;
//! type OnNewEpoch = (NewEpochHandler1, NewEpochHandler2);
//! ```
//!
//! ## Genesis configuration
//!
//! After the pallet is added to the runtime, configure it in your rust node code:
//! ```rust
//! # use std::str::FromStr;
//! # use sidechain_domain::UtxoId;
//! #
//! # fn create_genesis_config<Runtime>() -> pallet_sidechain::GenesisConfig<Runtime>
//! # where Runtime: frame_system::Config + pallet_sidechain::Config
//! # {
//! pallet_sidechain::GenesisConfig::<Runtime> {
//!     genesis_utxo: UtxoId::from_str("0000000000000000000000000000000000000000000000000000000000000000#0").unwrap(),
//!     ..Default::default()
//! }
//! # }
//! ```
//! or via a chain spec Json file:
//! ```json
//! {
//!     "sidechain_pallet": {
//!         "genesisUtxo": "0000000000000000000000000000000000000000000000000000000000000000#0"
//!     }
//! }
//! ```
#![cfg_attr(not(feature = "std"), no_std)]
#![deny(missing_docs)]

#[cfg(test)]
#[allow(missing_docs)]
pub mod mock;
#[cfg(test)]
mod tests;

/// Storage migrations for previous versions of `pallet-sidechain`
pub mod migrations;

pub use pallet::*;

#[frame_support::pallet]
pub mod pallet {
	use frame_support::pallet_prelude::*;
	use frame_system::pallet_prelude::BlockNumberFor;
	use sidechain_domain::ScEpochDuration;
	use sidechain_domain::ScEpochNumber;
	use sidechain_domain::UtxoId;
	use sp_sidechain::OnNewEpoch;

	const STORAGE_VERSION: StorageVersion = StorageVersion::new(1);

	#[pallet::pallet]
	#[pallet::storage_version(STORAGE_VERSION)]
	pub struct Pallet<T>(_);

	#[pallet::config]
	pub trait Config: frame_system::Config {
		/// Should return the reference timestamp of the current block in milliseconds
		///
		/// The reference timestamp does not necessarily have to be the exact timestamp of the block
		/// but must be one close enough for the purpose of epoch calculation, eg. the slot starting
		/// time in case of chains using a slot-based consensus such as Aura or Babe.
		///
		/// Warning: this function must be safe to call during block initialisation, which means that
		/// in particular block timestamp stored in `pallet_timestamp` can not be used.
		fn reference_timestamp_millis() -> u64;

		/// Handler that is called at initialization of the first block of a new Partner Chain epoch
		type OnNewEpoch: OnNewEpoch;
	}

	/// Current epoch number
	#[pallet::storage]
	pub(super) type EpochNumber<T: Config> = StorageValue<_, ScEpochNumber, ValueQuery>;

	/// Partner Chain epoch duration in milliseconds. This value must not be changed.
	#[pallet::storage]
	pub(crate) type EpochDurationMillis<T: Config> = StorageValue<_, ScEpochDuration, ValueQuery>;

	/// Number of slots per epoch. Currently this value must not change for a running chain.
	#[pallet::storage]
	#[deprecated(
		since = "1.9.0",
		note = "This storage is left for migration purposes and will be removed in later version"
	)]
	pub(crate) type SlotsPerEpoch<T: Config> = StorageValue<_, u32, ValueQuery>;

	/// Genesis Cardano UTXO of the Partner Chain
	///
	/// This is the UTXO that is burned by the transaction that establishes Partner Chain
	/// governance on Cardano and serves as the identifier of the Partner Chain. It is also
	/// included in various signed messages to prevent replay attacks on other Partner Chains.
	#[pallet::storage]
	pub(super) type GenesisUtxo<T: Config> = StorageValue<_, UtxoId, ValueQuery>;

	impl<T: Config> Pallet<T> {
		/// Returns the genesis UTXO of the Partner Chain
		pub fn genesis_utxo() -> UtxoId {
			GenesisUtxo::<T>::get()
		}

		/// Returns the Partner Chain epoch duration in milliseconds
		pub fn epoch_duration_millis() -> u64 {
			EpochDurationMillis::<T>::get().millis()
		}

		/// Returns current epoch number
		pub fn current_epoch_number() -> ScEpochNumber {
			ScEpochNumber(T::reference_timestamp_millis() / Self::epoch_duration_millis())
		}
	}

	#[pallet::genesis_config]
	#[derive(frame_support::DefaultNoBound)]
	pub struct GenesisConfig<T: Config> {
		/// Genesis UTXO of the Partner Chain. This value is immutable.
		pub genesis_utxo: UtxoId,
		/// Duration of Partner Chain epoch in milliseconds
		pub epoch_duration: ScEpochDuration,
		#[serde(skip)]
		#[allow(missing_docs)]
		pub _config: sp_std::marker::PhantomData<T>,
	}

	#[pallet::genesis_build]
	impl<T: Config> BuildGenesisConfig for GenesisConfig<T> {
		fn build(&self) {
			GenesisUtxo::<T>::put(self.genesis_utxo);
			EpochDurationMillis::<T>::put(self.epoch_duration);
		}
	}

	#[pallet::hooks]
	impl<T: Config> Hooks<BlockNumberFor<T>> for Pallet<T> {
		fn on_initialize(n: BlockNumberFor<T>) -> Weight {
			let real_epoch = Self::current_epoch_number();

			match EpochNumber::<T>::try_get().ok() {
				Some(saved_epoch) if saved_epoch != real_epoch => {
					log::info!("⏳ New epoch {real_epoch} starting at block {:?}", n);
					EpochNumber::<T>::put(real_epoch);
					<T::OnNewEpoch as OnNewEpoch>::on_new_epoch(saved_epoch, real_epoch)
						.saturating_add(T::DbWeight::get().reads_writes(2, 1))
				},
				None => {
					log::info!("⏳ Initial epoch {real_epoch} starting at block {:?}", n);
					EpochNumber::<T>::put(real_epoch);
					T::DbWeight::get().reads_writes(2, 1)
				},
				_ => T::DbWeight::get().reads_writes(2, 0),
			}
		}
	}
}