authority_selection_inherents/

ariadne_inherent_data_provider.rs

//! Logic to provide committee selection inputs compatible with the Ariadne algorithm, based on Cardano observation.
#[cfg(feature = "std")]
use crate::authority_selection_inputs::AuthoritySelectionDataSource;
use crate::authority_selection_inputs::AuthoritySelectionInputs;
use parity_scale_codec::{Decode, Encode};
#[cfg(feature = "std")]
use {
	crate::authority_selection_inputs::AuthoritySelectionInputsCreationError,
	sidechain_domain::mainchain_epoch::MainchainEpochDerivation,
	sidechain_domain::*,
	sp_api::ProvideRuntimeApi,
	sp_inherents::{InherentData, InherentIdentifier},
	sp_runtime::traits::Block as BlockT,
	sp_session_validator_management::{
		INHERENT_IDENTIFIER, InherentError, MainChainScripts, SessionValidatorManagementApi,
	},
};

#[cfg(feature = "std")]
pub use sidechain_domain::mainchain_epoch::MainchainEpochConfig;

#[derive(Clone, Debug, Encode, Decode)]
/// Inherent data provider providing inputs for authority selection.
pub struct AriadneInherentDataProvider {
	/// Authority selection inputs.
	pub data: Option<AuthoritySelectionInputs>,
}

#[cfg(feature = "std")]
impl AriadneInherentDataProvider {
	/// Creates a new [AriadneInherentDataProvider] for use in [sp_inherents::CreateInherentDataProviders].
	///
	/// Parameters:
	/// - `client`: runtime client capable of providing [SessionValidatorManagementApi] runtime API
	/// - `sc_epoch_duration_millis`: duration of the Partner Chain epoch in milliseconds
	/// - `mc_epoch_config`: main chain epoch configuration
	/// - `parent_hash`: parent hash of the current block
	/// - `timestamp_millis`: timestamp of current block in milliseconds
	/// - `data_source`: data source implementing [AuthoritySelectionDataSource]
	/// - `mc_reference_epoch`: latest stable mainchain epoch
	pub async fn new<Block, AuthorityId, AuthorityKeys, T>(
		client: &T,
		sc_epoch_duration_millis: u64,
		mc_epoch_config: &MainchainEpochConfig,
		parent_hash: <Block as BlockT>::Hash,
		timestamp_millis: u64,
		data_source: &(dyn AuthoritySelectionDataSource + Send + Sync),
		mc_reference_epoch: McEpochNumber,
	) -> Result<Self, InherentProviderCreationError>
	where
		AuthorityKeys: Decode + Encode,
		AuthorityId: Decode + Encode,
		Block: BlockT,
		T: ProvideRuntimeApi<Block> + Send + Sync,
		T::Api: SessionValidatorManagementApi<Block, AuthorityId, AuthorityKeys, ScEpochNumber>,
	{
		let for_mc_epoch = mc_epoch_for_next_ariadne_cidp(
			client,
			sc_epoch_duration_millis,
			mc_epoch_config,
			parent_hash,
			timestamp_millis,
		)?;

		let data_epoch = data_source.data_epoch(for_mc_epoch).await?;
		// We could accept mc_reference at last slot of data_epoch, but calculations are much easier like that.
		// Additionally, in current implementation, the inequality below is always true, thus there is no need to make it more accurate.
		let scripts = client.runtime_api().get_main_chain_scripts(parent_hash)?;
		if data_epoch < mc_reference_epoch {
			Ok(AriadneInherentDataProvider::from_mc_data(data_source, for_mc_epoch, scripts)
				.await?)
		} else {
			Ok(AriadneInherentDataProvider { data: None })
		}
	}

	async fn from_mc_data(
		candidate_data_source: &(dyn AuthoritySelectionDataSource + Send + Sync),
		for_epoch: McEpochNumber,
		scripts: MainChainScripts,
	) -> Result<Self, InherentProviderCreationError> {
		use crate::authority_selection_inputs::authority_selection_inputs_from_mc_data;

		Ok(Self {
			data: Some(
				authority_selection_inputs_from_mc_data(candidate_data_source, for_epoch, scripts)
					.await?,
			),
		})
	}
}

#[cfg(feature = "std")]
#[derive(Debug, thiserror::Error)]
/// Error type returned when creation of [AriadneInherentDataProvider] fails.
pub enum InherentProviderCreationError {
	/// Couldn't convert timestamp to main chain epoch.
	#[error("Couldn't convert timestamp to main chain epoch: {0}")]
	McEpochDerivationError(#[from] sidechain_domain::mainchain_epoch::EpochDerivationError),
	/// Runtime API call failed.
	#[error("Runtime API call failed: {0}")]
	ApiError(#[from] sp_api::ApiError),
	/// Failed to create authority selection inputs.
	#[error("Failed to create authority selection inputs: {0}")]
	InputsCreationError(#[from] AuthoritySelectionInputsCreationError),
	/// Data source call failed.
	#[error("Data source call failed: {0}")]
	DataSourceError(#[from] Box<dyn std::error::Error + Send + Sync>),
}

#[cfg(feature = "std")]
fn mc_epoch_for_next_ariadne_cidp<Block, AuthorityId, AuthorityKeys, T>(
	client: &T,
	sc_epoch_duration_millis: u64,
	epoch_config: &MainchainEpochConfig,
	parent_hash: <Block as BlockT>::Hash,
	timestamp_millis: u64,
) -> Result<McEpochNumber, InherentProviderCreationError>
where
	Block: BlockT,
	AuthorityKeys: Decode + Encode,
	AuthorityId: Decode + Encode,
	T: ProvideRuntimeApi<Block> + Send + Sync,
	T::Api: SessionValidatorManagementApi<Block, AuthorityId, AuthorityKeys, ScEpochNumber>,
{
	use sp_core::offchain::Timestamp;

	let next_unset_epoch = client.runtime_api().get_next_unset_epoch_number(parent_hash)?;

	let for_timestamp = {
		// A special case for the genesis committee (current epoch 0, next unset epoch 1).
		// The genesis committee epoch is initialized with 0, so in the very first block we need to provide
		// the epoch number based on the current timestamp
		if next_unset_epoch == ScEpochNumber(1) {
			// We first convert the timestamp to PC epoch number and then use the starting time of this
			// to ensure that all timestamps within a PC epoch produce the same candidates. This is
			// necessary in case the boundaries of PC epochs and MC epochs do not align.
			let current_pc_epoch = timestamp_millis / sc_epoch_duration_millis;
			current_pc_epoch * sc_epoch_duration_millis
		} else {
			next_unset_epoch.0 * sc_epoch_duration_millis
		}
	};

	epoch_config
		.timestamp_to_mainchain_epoch(Timestamp::from_unix_millis(for_timestamp))
		.map_err(InherentProviderCreationError::McEpochDerivationError)
}

#[cfg(feature = "std")]
#[async_trait::async_trait]
impl sp_inherents::InherentDataProvider for AriadneInherentDataProvider {
	async fn provide_inherent_data(
		&self,
		inherent_data: &mut InherentData,
	) -> Result<(), sp_inherents::Error> {
		match &self.data {
			None => Ok(()),
			Some(data) => inherent_data.put_data(INHERENT_IDENTIFIER, data),
		}
	}

	async fn try_handle_error(
		&self,
		identifier: &InherentIdentifier,
		error: &[u8],
	) -> Option<Result<(), sp_inherents::Error>> {
		// Don't process inherents from other modules
		if *identifier != INHERENT_IDENTIFIER {
			return None;
		}

		let mut error = error;
		Some(Err(sp_inherents::Error::Application(Box::from(
			<InherentError as parity_scale_codec::Decode>::decode(&mut error).ok()?,
		))))
	}
}

#[cfg(test)]
mod tests {
	use super::*;
	use crate::ariadne_inherent_data_provider::AriadneInherentDataProvider;
	use crate::mock::MockAuthoritySelectionDataSource;
	use crate::runtime_api_mock::*;
	use sidechain_domain::mainchain_epoch::*;
	use sp_core::H256;
	use sp_core::offchain::Timestamp;

	const TIMESTAMP: u64 = 400_000;

	#[tokio::test]
	async fn return_empty_ariadne_cidp_if_runtime_requests_too_new_epoch() {
		// This is the epoch number that is too new
		let next_unset_epoch_number = ScEpochNumber(42);
		let mc_reference_epoch = McEpochNumber(1);
		let empty_ariadne_idp = AriadneInherentDataProvider::new(
			&client(next_unset_epoch_number),
			sc_epoch_duration_millis(),
			&epoch_config(),
			H256::zero(),
			// This is the timestamp that will be used to calculate current_epoch_number
			TIMESTAMP,
			&MockAuthoritySelectionDataSource::default(),
			mc_reference_epoch,
		)
		.await;

		assert!(empty_ariadne_idp.is_ok());
		assert!(empty_ariadne_idp.unwrap().data.is_none());
	}

	#[tokio::test]
	async fn error_if_num_permissioned_candidates_non_zero_and_no_permissioned_candidate_list() {
		use crate::ariadne_inherent_data_provider::InherentProviderCreationError::InputsCreationError;
		use crate::authority_selection_inputs::AuthoritySelectionInputsCreationError::AriadneParametersQuery;

		let next_unset_epoch_number = ScEpochNumber(42);
		let mc_reference_epoch = McEpochNumber(5);
		let ariadne_idp = AriadneInherentDataProvider::new(
			&client(next_unset_epoch_number),
			sc_epoch_duration_millis(),
			&epoch_config(),
			H256::zero(),
			// This is the timestamp that will be used to calculate current_epoch_number
			TIMESTAMP,
			&MockAuthoritySelectionDataSource::default()
				.with_permissioned_candidates(vec![None, None, None, None, None])
				.with_num_permissioned_candidates(3),
			mc_reference_epoch,
		)
		.await;

		assert!(ariadne_idp.is_err());
		assert!(matches!(
			ariadne_idp.unwrap_err(),
			InputsCreationError(AriadneParametersQuery(_, _, _, _))
		));
	}

	#[tokio::test]
	async fn ok_if_num_permissioned_candidates_zero_and_no_permissioned_candidate_list() {
		let next_unset_epoch_number = ScEpochNumber(42);
		let mc_reference_epoch = McEpochNumber(5);
		let ariadne_idp = AriadneInherentDataProvider::new(
			&client(next_unset_epoch_number),
			sc_epoch_duration_millis(),
			&epoch_config(),
			H256::zero(),
			// This is the timestamp that will be used to calculate current_epoch_number
			TIMESTAMP,
			&MockAuthoritySelectionDataSource::default()
				.with_permissioned_candidates(vec![None, None, None, None, None])
				.with_num_permissioned_candidates(0),
			mc_reference_epoch,
		)
		.await;

		assert!(ariadne_idp.is_ok());
		assert!(ariadne_idp.unwrap().data.is_some());
	}

	fn sc_epoch_duration_millis() -> u64 {
		60 * 60 * 1000
	}

	fn client(next_unset_epoch_number: ScEpochNumber) -> TestApi {
		TestApi { next_unset_epoch_number }
	}

	fn epoch_config() -> MainchainEpochConfig {
		MainchainEpochConfig {
			first_epoch_timestamp_millis: Timestamp::from_unix_millis(0),
			first_epoch_number: 0,
			epoch_duration_millis: Duration::from_millis(10 * sc_epoch_duration_millis()),
			first_slot_number: 0,
			slot_duration_millis: Duration::from_millis(1000),
		}
	}
}