Unify RelayChainInterface error handling and introduce async (#909)

cumulus/client/relay-chain-interface/src/lib.rs

@@ -14,136 +14,140 @@
 // You should have received a copy of the GNU General Public License
 // along with Cumulus.  If not, see <http://www.gnu.org/licenses/>.
 
-use std::{collections::BTreeMap, sync::Arc};
+use std::{collections::BTreeMap, pin::Pin, sync::Arc};
 
 use cumulus_primitives_core::{
 	relay_chain::{
 		v1::{CommittedCandidateReceipt, OccupiedCoreAssumption, SessionIndex, ValidatorId},
-		Block as PBlock, BlockId, Hash as PHash, InboundHrmpMessage,
+		BlockId, Hash as PHash, Header as PHeader, InboundHrmpMessage,
 	},
 	InboundDownwardMessage, ParaId, PersistedValidationData,
 };
 use polkadot_overseer::Handle as OverseerHandle;
 use sc_client_api::{blockchain::BlockStatus, StorageProof};
 
+use futures::Stream;
+
+use async_trait::async_trait;
 use sp_api::ApiError;
 use sp_state_machine::StorageValue;
 
-use async_trait::async_trait;
+pub type RelayChainResult<T> = Result<T, RelayChainError>;
 
-#[derive(Debug, derive_more::Display)]
-pub enum WaitError {
-	#[display(fmt = "Timeout while waiting for relay-chain block `{}` to be imported.", _0)]
-	Timeout(PHash),
-	#[display(
-		fmt = "Import listener closed while waiting for relay-chain block `{}` to be imported.",
-		_0
-	)]
+#[derive(thiserror::Error, Debug)]
+pub enum RelayChainError {
+	#[error("Error occured while calling relay chain runtime: {0:?}")]
+	ApiError(#[from] ApiError),
+	#[error("Timeout while waiting for relay-chain block `{0}` to be imported.")]
+	WaitTimeout(PHash),
+	#[error("Import listener closed while waiting for relay-chain block `{0}` to be imported.")]
 	ImportListenerClosed(PHash),
-	#[display(
-		fmt = "Blockchain returned an error while waiting for relay-chain block `{}` to be imported: {:?}",
-		_0,
-		_1
-	)]
-	BlockchainError(PHash, sp_blockchain::Error),
+	#[error("Blockchain returned an error while waiting for relay-chain block `{0}` to be imported: {1:?}")]
+	WaitBlockchainError(PHash, sp_blockchain::Error),
+	#[error("Blockchain returned an error: {0:?}")]
+	BlockchainError(#[from] sp_blockchain::Error),
+	#[error("State machine error occured: {0:?}")]
+	StateMachineError(Box<dyn sp_state_machine::Error>),
+	#[error("Unspecified error occured: {0:?}")]
+	GenericError(String),
 }
 
 /// Trait that provides all necessary methods for interaction between collator and relay chain.
 #[async_trait]
 pub trait RelayChainInterface: Send + Sync {
 	/// Fetch a storage item by key.
-	fn get_storage_by_key(
+	async fn get_storage_by_key(
 		&self,
 		block_id: &BlockId,
 		key: &[u8],
-	) -> Result<Option<StorageValue>, sp_blockchain::Error>;
+	) -> RelayChainResult<Option<StorageValue>>;
 
 	/// Fetch a vector of current validators.
-	fn validators(&self, block_id: &BlockId) -> Result<Vec<ValidatorId>, ApiError>;
+	async fn validators(&self, block_id: &BlockId) -> RelayChainResult<Vec<ValidatorId>>;
 
 	/// Get the status of a given block.
-	fn block_status(&self, block_id: BlockId) -> Result<BlockStatus, sp_blockchain::Error>;
+	async fn block_status(&self, block_id: BlockId) -> RelayChainResult<BlockStatus>;
 
 	/// Get the hash of the current best block.
-	fn best_block_hash(&self) -> PHash;
+	async fn best_block_hash(&self) -> RelayChainResult<PHash>;
 
 	/// Returns the whole contents of the downward message queue for the parachain we are collating
 	/// for.
 	///
 	/// Returns `None` in case of an error.
-	fn retrieve_dmq_contents(
+	async fn retrieve_dmq_contents(
 		&self,
 		para_id: ParaId,
 		relay_parent: PHash,
-	) -> Option<Vec<InboundDownwardMessage>>;
+	) -> RelayChainResult<Vec<InboundDownwardMessage>>;
 
 	/// Returns channels contents for each inbound HRMP channel addressed to the parachain we are
 	/// collating for.
 	///
 	/// Empty channels are also included.
-	fn retrieve_all_inbound_hrmp_channel_contents(
+	async fn retrieve_all_inbound_hrmp_channel_contents(
 		&self,
 		para_id: ParaId,
 		relay_parent: PHash,
-	) -> Option<BTreeMap<ParaId, Vec<InboundHrmpMessage>>>;
+	) -> RelayChainResult<BTreeMap<ParaId, Vec<InboundHrmpMessage>>>;
 
 	/// Yields the persisted validation data for the given `ParaId` along with an assumption that
 	/// should be used if the para currently occupies a core.
 	///
 	/// Returns `None` if either the para is not registered or the assumption is `Freed`
 	/// and the para already occupies a core.
-	fn persisted_validation_data(
+	async fn persisted_validation_data(
 		&self,
 		block_id: &BlockId,
 		para_id: ParaId,
 		_: OccupiedCoreAssumption,
-	) -> Result<Option<PersistedValidationData>, ApiError>;
+	) -> RelayChainResult<Option<PersistedValidationData>>;
 
 	/// Get the receipt of a candidate pending availability. This returns `Some` for any paras
 	/// assigned to occupied cores in `availability_cores` and `None` otherwise.
-	fn candidate_pending_availability(
+	async fn candidate_pending_availability(
 		&self,
 		block_id: &BlockId,
 		para_id: ParaId,
-	) -> Result<Option<CommittedCandidateReceipt>, ApiError>;
+	) -> RelayChainResult<Option<CommittedCandidateReceipt>>;
 
 	/// Returns the session index expected at a child of the block.
-	fn session_index_for_child(&self, block_id: &BlockId) -> Result<SessionIndex, ApiError>;
+	async fn session_index_for_child(&self, block_id: &BlockId) -> RelayChainResult<SessionIndex>;
 
 	/// Get a stream of import block notifications.
-	fn import_notification_stream(&self) -> sc_client_api::ImportNotifications<PBlock>;
+	async fn import_notification_stream(
+		&self,
+	) -> RelayChainResult<Pin<Box<dyn Stream<Item = PHeader> + Send>>>;
+
+	/// Get a stream of new best block notifications.
+	async fn new_best_notification_stream(
+		&self,
+	) -> RelayChainResult<Pin<Box<dyn Stream<Item = PHeader> + Send>>>;
 
 	/// Wait for a block with a given hash in the relay chain.
 	///
 	/// This method returns immediately on error or if the block is already
 	/// reported to be in chain. Otherwise, it waits for the block to arrive.
-	async fn wait_for_block(&self, hash: PHash) -> Result<(), WaitError>;
+	async fn wait_for_block(&self, hash: PHash) -> RelayChainResult<()>;
 
 	/// Get a stream of finality notifications.
-	fn finality_notification_stream(&self) -> sc_client_api::FinalityNotifications<PBlock>;
-
-	/// Get a stream of storage change notifications.
-	fn storage_changes_notification_stream(
+	async fn finality_notification_stream(
 		&self,
-		filter_keys: Option<&[sc_client_api::StorageKey]>,
-		child_filter_keys: Option<
-			&[(sc_client_api::StorageKey, Option<Vec<sc_client_api::StorageKey>>)],
-		>,
-	) -> sc_client_api::blockchain::Result<sc_client_api::StorageEventStream<PHash>>;
+	) -> RelayChainResult<Pin<Box<dyn Stream<Item = PHeader> + Send>>>;
 
 	/// Whether the synchronization service is undergoing major sync.
 	/// Returns true if so.
-	fn is_major_syncing(&self) -> bool;
+	async fn is_major_syncing(&self) -> RelayChainResult<bool>;
 
 	/// Get a handle to the overseer.
-	fn overseer_handle(&self) -> Option<OverseerHandle>;
+	fn overseer_handle(&self) -> RelayChainResult<Option<OverseerHandle>>;
 
 	/// Generate a storage read proof.
-	fn prove_read(
+	async fn prove_read(
 		&self,
 		block_id: &BlockId,
 		relevant_keys: &Vec<Vec<u8>>,
-	) -> Result<Option<StorageProof>, Box<dyn sp_state_machine::Error>>;
+	) -> RelayChainResult<StorageProof>;
 }
 
 #[async_trait]
@@ -151,98 +155,100 @@ impl<T> RelayChainInterface for Arc<T>
 where
 	T: RelayChainInterface + ?Sized,
 {
-	fn retrieve_dmq_contents(
+	async fn retrieve_dmq_contents(
 		&self,
 		para_id: ParaId,
 		relay_parent: PHash,
-	) -> Option<Vec<InboundDownwardMessage>> {
-		(**self).retrieve_dmq_contents(para_id, relay_parent)
+	) -> RelayChainResult<Vec<InboundDownwardMessage>> {
+		(**self).retrieve_dmq_contents(para_id, relay_parent).await
 	}
 
-	fn retrieve_all_inbound_hrmp_channel_contents(
+	async fn retrieve_all_inbound_hrmp_channel_contents(
 		&self,
 		para_id: ParaId,
 		relay_parent: PHash,
-	) -> Option<BTreeMap<ParaId, Vec<InboundHrmpMessage>>> {
-		(**self).retrieve_all_inbound_hrmp_channel_contents(para_id, relay_parent)
+	) -> RelayChainResult<BTreeMap<ParaId, Vec<InboundHrmpMessage>>> {
+		(**self).retrieve_all_inbound_hrmp_channel_contents(para_id, relay_parent).await
 	}
 
-	fn persisted_validation_data(
+	async fn persisted_validation_data(
 		&self,
 		block_id: &BlockId,
 		para_id: ParaId,
 		occupied_core_assumption: OccupiedCoreAssumption,
-	) -> Result<Option<PersistedValidationData>, ApiError> {
-		(**self).persisted_validation_data(block_id, para_id, occupied_core_assumption)
+	) -> RelayChainResult<Option<PersistedValidationData>> {
+		(**self)
+			.persisted_validation_data(block_id, para_id, occupied_core_assumption)
+			.await
 	}
 
-	fn candidate_pending_availability(
+	async fn candidate_pending_availability(
 		&self,
 		block_id: &BlockId,
 		para_id: ParaId,
-	) -> Result<Option<CommittedCandidateReceipt>, ApiError> {
-		(**self).candidate_pending_availability(block_id, para_id)
+	) -> RelayChainResult<Option<CommittedCandidateReceipt>> {
+		(**self).candidate_pending_availability(block_id, para_id).await
 	}
 
-	fn session_index_for_child(&self, block_id: &BlockId) -> Result<SessionIndex, ApiError> {
-		(**self).session_index_for_child(block_id)
+	async fn session_index_for_child(&self, block_id: &BlockId) -> RelayChainResult<SessionIndex> {
+		(**self).session_index_for_child(block_id).await
 	}
 
-	fn validators(&self, block_id: &BlockId) -> Result<Vec<ValidatorId>, ApiError> {
-		(**self).validators(block_id)
+	async fn validators(&self, block_id: &BlockId) -> RelayChainResult<Vec<ValidatorId>> {
+		(**self).validators(block_id).await
 	}
 
-	fn import_notification_stream(&self) -> sc_client_api::ImportNotifications<PBlock> {
-		(**self).import_notification_stream()
-	}
-
-	fn finality_notification_stream(&self) -> sc_client_api::FinalityNotifications<PBlock> {
-		(**self).finality_notification_stream()
-	}
-
-	fn storage_changes_notification_stream(
+	async fn import_notification_stream(
 		&self,
-		filter_keys: Option<&[sc_client_api::StorageKey]>,
-		child_filter_keys: Option<
-			&[(sc_client_api::StorageKey, Option<Vec<sc_client_api::StorageKey>>)],
-		>,
-	) -> sc_client_api::blockchain::Result<sc_client_api::StorageEventStream<PHash>> {
-		(**self).storage_changes_notification_stream(filter_keys, child_filter_keys)
+	) -> RelayChainResult<Pin<Box<dyn Stream<Item = PHeader> + Send>>> {
+		(**self).import_notification_stream().await
 	}
 
-	fn best_block_hash(&self) -> PHash {
-		(**self).best_block_hash()
+	async fn finality_notification_stream(
+		&self,
+	) -> RelayChainResult<Pin<Box<dyn Stream<Item = PHeader> + Send>>> {
+		(**self).finality_notification_stream().await
 	}
 
-	fn block_status(&self, block_id: BlockId) -> Result<BlockStatus, sp_blockchain::Error> {
-		(**self).block_status(block_id)
+	async fn best_block_hash(&self) -> RelayChainResult<PHash> {
+		(**self).best_block_hash().await
 	}
 
-	fn is_major_syncing(&self) -> bool {
-		(**self).is_major_syncing()
+	async fn block_status(&self, block_id: BlockId) -> RelayChainResult<BlockStatus> {
+		(**self).block_status(block_id).await
 	}
 
-	fn overseer_handle(&self) -> Option<OverseerHandle> {
+	async fn is_major_syncing(&self) -> RelayChainResult<bool> {
+		(**self).is_major_syncing().await
+	}
+
+	fn overseer_handle(&self) -> RelayChainResult<Option<OverseerHandle>> {
 		(**self).overseer_handle()
 	}
 
-	fn get_storage_by_key(
+	async fn get_storage_by_key(
 		&self,
 		block_id: &BlockId,
 		key: &[u8],
-	) -> Result<Option<StorageValue>, sp_blockchain::Error> {
-		(**self).get_storage_by_key(block_id, key)
+	) -> RelayChainResult<Option<StorageValue>> {
+		(**self).get_storage_by_key(block_id, key).await
 	}
 
-	fn prove_read(
+	async fn prove_read(
 		&self,
 		block_id: &BlockId,
 		relevant_keys: &Vec<Vec<u8>>,
-	) -> Result<Option<StorageProof>, Box<dyn sp_state_machine::Error>> {
-		(**self).prove_read(block_id, relevant_keys)
+	) -> RelayChainResult<StorageProof> {
+		(**self).prove_read(block_id, relevant_keys).await
 	}
 
-	async fn wait_for_block(&self, hash: PHash) -> Result<(), WaitError> {
+	async fn wait_for_block(&self, hash: PHash) -> RelayChainResult<()> {
 		(**self).wait_for_block(hash).await
 	}
+
+	async fn new_best_notification_stream(
+		&self,
+	) -> RelayChainResult<Pin<Box<dyn Stream<Item = PHeader> + Send>>> {
+		(**self).new_best_notification_stream().await
+	}
 }