Update bridges subtree (#2996)

Update bridges subtree

bridges/primitives/messages/src/lib.rs

@@ -16,14 +16,13 @@
 
 //! Primitives of messages module.
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
-// RuntimeApi generated functions
-#![allow(clippy::too_many_arguments)]
 
 use bp_header_chain::HeaderChainError;
 use bp_runtime::{
-	messages::MessageDispatchResult, BasicOperatingMode, OperatingMode, RangeInclusiveExt,
-	StorageProofError,
+	messages::MessageDispatchResult, BasicOperatingMode, Chain, OperatingMode, RangeInclusiveExt,
+	StorageProofError, UnderlyingChainOf, UnderlyingChainProvider,
 };
 use codec::{Decode, Encode, MaxEncodedLen};
 use frame_support::PalletError;
@@ -39,6 +38,36 @@ pub mod source_chain;
 pub mod storage_keys;
 pub mod target_chain;
 
+/// Substrate-based chain with messaging support.
+pub trait ChainWithMessages: Chain {
+	/// Name of the bridge messages pallet (used in `construct_runtime` macro call) that is
+	/// deployed at some other chain to bridge with this `ChainWithMessages`.
+	///
+	/// We assume that all chains that are bridging with this `ChainWithMessages` are using
+	/// the same name.
+	const WITH_CHAIN_MESSAGES_PALLET_NAME: &'static str;
+
+	/// Maximal number of unrewarded relayers in a single confirmation transaction at this
+	/// `ChainWithMessages`.
+	const MAX_UNREWARDED_RELAYERS_IN_CONFIRMATION_TX: MessageNonce;
+	/// Maximal number of unconfirmed messages in a single confirmation transaction at this
+	/// `ChainWithMessages`.
+	const MAX_UNCONFIRMED_MESSAGES_IN_CONFIRMATION_TX: MessageNonce;
+}
+
+impl<T> ChainWithMessages for T
+where
+	T: Chain + UnderlyingChainProvider,
+	UnderlyingChainOf<T>: ChainWithMessages,
+{
+	const WITH_CHAIN_MESSAGES_PALLET_NAME: &'static str =
+		UnderlyingChainOf::<T>::WITH_CHAIN_MESSAGES_PALLET_NAME;
+	const MAX_UNREWARDED_RELAYERS_IN_CONFIRMATION_TX: MessageNonce =
+		UnderlyingChainOf::<T>::MAX_UNREWARDED_RELAYERS_IN_CONFIRMATION_TX;
+	const MAX_UNCONFIRMED_MESSAGES_IN_CONFIRMATION_TX: MessageNonce =
+		UnderlyingChainOf::<T>::MAX_UNCONFIRMED_MESSAGES_IN_CONFIRMATION_TX;
+}
+
 /// Messages pallet operating mode.
 #[derive(
 	Encode,
@@ -264,6 +293,7 @@ pub struct ReceivedMessages<DispatchLevelResult> {
 }
 
 impl<DispatchLevelResult> ReceivedMessages<DispatchLevelResult> {
+	/// Creates new `ReceivedMessages` structure from given results.
 	pub fn new(
 		lane: LaneId,
 		receive_results: Vec<(MessageNonce, ReceivalResult<DispatchLevelResult>)>,
@@ -271,6 +301,7 @@ impl<DispatchLevelResult> ReceivedMessages<DispatchLevelResult> {
 		ReceivedMessages { lane, receive_results }
 	}
 
+	/// Push `result` of the `message` delivery onto `receive_results` vector.
 	pub fn push(&mut self, message: MessageNonce, result: ReceivalResult<DispatchLevelResult>) {
 		self.receive_results.push((message, result));
 	}
@@ -342,7 +373,7 @@ pub struct UnrewardedRelayersState {
 }
 
 impl UnrewardedRelayersState {
-	// Verify that the relayers state corresponds with the `InboundLaneData`.
+	/// Verify that the relayers state corresponds with the `InboundLaneData`.
 	pub fn is_valid<RelayerId>(&self, lane_data: &InboundLaneData<RelayerId>) -> bool {
 		self == &lane_data.into()
 	}
@@ -423,15 +454,21 @@ pub enum BridgeMessagesCall<AccountId, MessagesProof, MessagesDeliveryProof> {
 	/// `pallet-bridge-messages::Call::receive_messages_proof`
 	#[codec(index = 2)]
 	receive_messages_proof {
+		/// Account id of relayer at the **bridged** chain.
 		relayer_id_at_bridged_chain: AccountId,
+		/// Messages proof.
 		proof: MessagesProof,
+		/// A number of messages in the proof.
 		messages_count: u32,
+		/// Total dispatch weight of messages in the proof.
 		dispatch_weight: Weight,
 	},
 	/// `pallet-bridge-messages::Call::receive_messages_delivery_proof`
 	#[codec(index = 3)]
 	receive_messages_delivery_proof {
+		/// Messages delivery proof.
 		proof: MessagesDeliveryProof,
+		/// "Digest" of unrewarded relayers state at the bridged chain.
 		relayers_state: UnrewardedRelayersState,
 	},
 }

bridges/primitives/messages/src/source_chain.rs

@@ -16,7 +16,7 @@
 
 //! Primitives of messages module, that are used on the source chain.
 
-use crate::{InboundLaneData, LaneId, MessageNonce, OutboundLaneData, VerificationError};
+use crate::{InboundLaneData, LaneId, MessageNonce, VerificationError};
 
 use crate::UnrewardedRelayer;
 use bp_runtime::Size;
@@ -64,24 +64,6 @@ pub trait TargetHeaderChain<Payload, AccountId> {
 	) -> Result<(LaneId, InboundLaneData<AccountId>), VerificationError>;
 }
 
-/// Lane message verifier.
-///
-/// Runtime developer may implement any additional validation logic over message-lane mechanism.
-/// E.g. if lanes should have some security (e.g. you can only accept Lane1 messages from
-/// Submitter1, Lane2 messages for those who has submitted first message to this lane, disable
-/// Lane3 until some block, ...), then it may be built using this verifier.
-///
-/// Any fee requirements should also be enforced here.
-pub trait LaneMessageVerifier<Payload> {
-	/// Verify message payload and return Ok(()) if message is valid and allowed to be sent over the
-	/// lane.
-	fn verify_message(
-		lane: &LaneId,
-		outbound_data: &OutboundLaneData,
-		payload: &Payload,
-	) -> Result<(), VerificationError>;
-}
-
 /// Manages payments that are happening at the source chain during delivery confirmation
 /// transaction.
 pub trait DeliveryConfirmationPayments<AccountId> {
@@ -143,25 +125,25 @@ pub trait MessagesBridge<Payload> {
 	/// Error type.
 	type Error: Debug;
 
+	/// Intermediary structure returned by `validate_message()`.
+	///
+	/// It can than be passed to `send_message()` in order to actually send the message
+	/// on the bridge.
+	type SendMessageArgs;
+
+	/// Check if the message can be sent over the bridge.
+	fn validate_message(
+		lane: LaneId,
+		message: &Payload,
+	) -> Result<Self::SendMessageArgs, Self::Error>;
+
 	/// Send message over the bridge.
 	///
 	/// Returns unique message nonce or error if send has failed.
-	fn send_message(lane: LaneId, message: Payload) -> Result<SendMessageArtifacts, Self::Error>;
+	fn send_message(message: Self::SendMessageArgs) -> SendMessageArtifacts;
 }
 
-/// Bridge that does nothing when message is being sent.
-#[derive(Eq, RuntimeDebug, PartialEq)]
-pub struct NoopMessagesBridge;
-
-impl<Payload> MessagesBridge<Payload> for NoopMessagesBridge {
-	type Error = &'static str;
-
-	fn send_message(_lane: LaneId, _message: Payload) -> Result<SendMessageArtifacts, Self::Error> {
-		Ok(SendMessageArtifacts { nonce: 0, enqueued_messages: 0 })
-	}
-}
-
-/// Structure that may be used in place of `TargetHeaderChain`, `LaneMessageVerifier` and
+/// Structure that may be used in place of `TargetHeaderChain` and
 /// `MessageDeliveryAndDispatchPayment` on chains, where outbound messages are forbidden.
 pub struct ForbidOutboundMessages;
 
@@ -183,16 +165,6 @@ impl<Payload, AccountId> TargetHeaderChain<Payload, AccountId> for ForbidOutboun
 	}
 }
 
-impl<Payload> LaneMessageVerifier<Payload> for ForbidOutboundMessages {
-	fn verify_message(
-		_lane: &LaneId,
-		_outbound_data: &OutboundLaneData,
-		_payload: &Payload,
-	) -> Result<(), VerificationError> {
-		Err(VerificationError::Other(ALL_OUTBOUND_MESSAGES_REJECTED))
-	}
-}
-
 impl<AccountId> DeliveryConfirmationPayments<AccountId> for ForbidOutboundMessages {
 	type Error = &'static str;