Port safe commits from master to polkadot-staging (paritytech#2761)

* introduce bp_messages::ChainWithMessages (paritytech#2171)

* Move Chain::ID from relay-level Chain to primitives-level Chain (paritytech#2181)

* move Chain::ID from relay-level Chain to primitives-level Chain

* removed chain IDs from bp-runtime

* add missing file header

* Some code grooming (paritytech#2276)

* some code grooming: enable warn(missing_docs) for all piblic crates + added missing documentation + removed obsolete clippy/deny workarounds

* removed strange allow + added comment related to other allow

* removed incorrect_clone_impl_on_copy_type which is unknown to CI clippy

bridges/bin/runtime-common/src/lib.rs

@@ -16,6 +16,7 @@
 
 //! Common types/functions that may be used by runtimes of all bridged chains.
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 use crate::messages_call_ext::MessagesCallSubType;

bridges/bin/runtime-common/src/messages_call_ext.rs

@@ -14,6 +14,9 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
 
+//! Signed extension for the `pallet-bridge-messages` that is able to reject obsolete
+//! (and some other invalid) transactions.
+
 use crate::messages::{
 	source::FromBridgedChainMessagesDeliveryProof, target::FromBridgedChainMessagesProof,
 };
@@ -116,7 +119,9 @@ impl ReceiveMessagesDeliveryProofInfo {
 /// which tries to update a single lane.
 #[derive(PartialEq, RuntimeDebug)]
 pub enum CallInfo {
+	/// Messages delivery call info.
 	ReceiveMessagesProof(ReceiveMessagesProofInfo),
+	/// Messages delivery confirmation call info.
 	ReceiveMessagesDeliveryProof(ReceiveMessagesDeliveryProofInfo),
 }
 
@@ -132,7 +137,7 @@ impl CallInfo {
 
 /// Helper struct that provides methods for working with a call supported by `CallInfo`.
 pub struct CallHelper<T: Config<I>, I: 'static> {
-	pub _phantom_data: sp_std::marker::PhantomData<(T, I)>,
+	_phantom_data: sp_std::marker::PhantomData<(T, I)>,
 }
 
 impl<T: Config<I>, I: 'static> CallHelper<T, I> {

bridges/bin/runtime-common/src/messages_xcm_extension.rs

@@ -40,11 +40,14 @@ use sp_std::{fmt::Debug, marker::PhantomData};
 use xcm::prelude::*;
 use xcm_builder::{DispatchBlob, DispatchBlobError};
 
-/// Message dispatch result type for single message
+/// Message dispatch result type for single message.
 #[derive(CloneNoBound, EqNoBound, PartialEqNoBound, Encode, Decode, Debug, TypeInfo)]
 pub enum XcmBlobMessageDispatchResult {
+	/// We've been unable to decode message payload.
 	InvalidPayload,
+	/// Message has been dispatched.
 	Dispatched,
+	/// Message has **NOT** been dispatched because of given error.
 	NotDispatched(#[codec(skip)] Option<DispatchBlobError>),
 }
 

bridges/bin/runtime-common/src/mock.rs

@@ -314,6 +314,8 @@ impl From<BridgedChainOrigin>
 pub struct ThisUnderlyingChain;
 
 impl Chain for ThisUnderlyingChain {
+	const ID: ChainId = *b"tuch";
+
 	type BlockNumber = ThisChainBlockNumber;
 	type Hash = ThisChainHash;
 	type Hasher = ThisChainHasher;
@@ -354,6 +356,8 @@ pub struct BridgedUnderlyingParachain;
 pub struct BridgedChainCall;
 
 impl Chain for BridgedUnderlyingChain {
+	const ID: ChainId = *b"buch";
+
 	type BlockNumber = BridgedChainBlockNumber;
 	type Hash = BridgedChainHash;
 	type Hasher = BridgedChainHasher;
@@ -380,6 +384,8 @@ impl ChainWithGrandpa for BridgedUnderlyingChain {
 }
 
 impl Chain for BridgedUnderlyingParachain {
+	const ID: ChainId = *b"bupc";
+
 	type BlockNumber = BridgedChainBlockNumber;
 	type Hash = BridgedChainHash;
 	type Hasher = BridgedChainHasher;

bridges/bin/runtime-common/src/parachains_benchmarking.rs

@@ -84,5 +84,5 @@ where
 	let (relay_block_number, relay_block_hash) =
 		insert_header_to_grandpa_pallet::<R, R::BridgesGrandpaPalletInstance>(state_root);
 
-	(relay_block_number, relay_block_hash, ParaHeadsProof(proof), parachain_heads)
+	(relay_block_number, relay_block_hash, ParaHeadsProof { storage_proof: proof }, parachain_heads)
 }

bridges/bin/runtime-common/src/refund_relayer_extension.rs

@@ -116,7 +116,7 @@ where
 
 /// Refund calculator.
 pub trait RefundCalculator {
-	// The underlying integer type in which the refund is calculated.
+	/// The underlying integer type in which the refund is calculated.
 	type Balance;
 
 	/// Compute refund for given transaction.
@@ -986,7 +986,7 @@ mod tests {
 				ParaId(TestParachain::get()),
 				[parachain_head_at_relay_header_number as u8; 32].into(),
 			)],
-			parachain_heads_proof: ParaHeadsProof(vec![]),
+			parachain_heads_proof: ParaHeadsProof { storage_proof: vec![] },
 		})
 	}
 
@@ -1732,7 +1732,7 @@ mod tests {
 							(ParaId(TestParachain::get()), [1u8; 32].into()),
 							(ParaId(TestParachain::get() + 1), [1u8; 32].into()),
 						],
-						parachain_heads_proof: ParaHeadsProof(vec![]),
+						parachain_heads_proof: ParaHeadsProof { storage_proof: vec![] },
 					}),
 					message_delivery_call(200),
 				],

bridges/modules/beefy/src/lib.rs

@@ -29,6 +29,7 @@
 //! Given the header hash, other pallets are able to verify header-based proofs
 //! (e.g. storage proofs, transaction inclusion proofs, etc.).
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 use bp_beefy::{ChainWithBeefy, InitializationData};

bridges/modules/beefy/src/mock.rs

@@ -22,7 +22,7 @@ use crate::{
 };
 
 use bp_beefy::{BeefyValidatorSignatureOf, ChainWithBeefy, Commitment, MmrDataOrHash};
-use bp_runtime::{BasicOperatingMode, Chain};
+use bp_runtime::{BasicOperatingMode, Chain, ChainId};
 use codec::Encode;
 use frame_support::{construct_runtime, derive_impl, weights::Weight};
 use sp_core::{sr25519::Signature, Pair};
@@ -81,6 +81,8 @@ impl beefy::Config for TestRuntime {
 pub struct TestBridgedChain;
 
 impl Chain for TestBridgedChain {
+	const ID: ChainId = *b"tbch";
+
 	type BlockNumber = TestBridgedBlockNumber;
 	type Hash = H256;
 	type Hasher = BlakeTwo256;

bridges/modules/grandpa/src/lib.rs

@@ -32,9 +32,8 @@
 //! Shall the fork occur on the bridged chain governance intervention will be required to
 //! re-initialize the bridge and track the right fork.
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
-// Runtime-generated enums
-#![allow(clippy::large_enum_variant)]
 
 pub use storage_types::StoredAuthoritySet;
 
@@ -408,7 +407,9 @@ pub mod pallet {
 	pub enum Event<T: Config<I>, I: 'static = ()> {
 		/// Best finalized chain header has been updated to the header with given number and hash.
 		UpdatedBestFinalizedHeader {
+			/// Number of the new best finalized header.
 			number: BridgedBlockNumber<T, I>,
+			/// Hash of the new best finalized header.
 			hash: BridgedBlockHash<T, I>,
 			/// The Grandpa info associated to the new best finalized header.
 			grandpa_info: StoredHeaderGrandpaInfo<BridgedHeader<T, I>>,

bridges/modules/grandpa/src/mock.rs

@@ -18,7 +18,7 @@
 #![allow(clippy::from_over_into)]
 
 use bp_header_chain::ChainWithGrandpa;
-use bp_runtime::Chain;
+use bp_runtime::{Chain, ChainId};
 use frame_support::{
 	construct_runtime, derive_impl, parameter_types, traits::Hooks, weights::Weight,
 };
@@ -64,7 +64,9 @@ impl grandpa::Config for TestRuntime {
 pub struct TestBridgedChain;
 
 impl Chain for TestBridgedChain {
-	type BlockNumber = TestNumber;
+	const ID: ChainId = *b"tbch";
+
+	type BlockNumber = frame_system::pallet_prelude::BlockNumberFor<TestRuntime>;
 	type Hash = <TestRuntime as frame_system::Config>::Hash;
 	type Hasher = <TestRuntime as frame_system::Config>::Hashing;
 	type Header = TestHeader;

bridges/modules/messages/src/lib.rs

@@ -33,9 +33,8 @@
 //! If this test fails with your weights, then either weights are computed incorrectly,
 //! or some benchmarks assumptions are broken for your runtime.
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
-// Generated by `decl_event!`
-#![allow(clippy::unused_unit)]
 
 pub use inbound_lane::StoredInboundLaneData;
 pub use outbound_lane::StoredMessagePayload;
@@ -514,13 +513,24 @@ pub mod pallet {
 	#[pallet::generate_deposit(pub(super) fn deposit_event)]
 	pub enum Event<T: Config<I>, I: 'static = ()> {
 		/// Message has been accepted and is waiting to be delivered.
-		MessageAccepted { lane_id: LaneId, nonce: MessageNonce },
+		MessageAccepted {
+			/// Lane, which has accepted the message.
+			lane_id: LaneId,
+			/// Nonce of accepted message.
+			nonce: MessageNonce,
+		},
 		/// Messages have been received from the bridged chain.
 		MessagesReceived(
+			/// Result of received messages dispatch.
 			Vec<ReceivedMessages<<T::MessageDispatch as MessageDispatch>::DispatchLevelResult>>,
 		),
 		/// Messages in the inclusive range have been delivered to the bridged chain.
-		MessagesDelivered { lane_id: LaneId, messages: DeliveredMessages },
+		MessagesDelivered {
+			/// Lane for which the delivery has been confirmed.
+			lane_id: LaneId,
+			/// Delivered messages.
+			messages: DeliveredMessages,
+		},
 	}
 
 	#[pallet::error]

bridges/modules/parachains/src/call_ext.rs

@@ -178,7 +178,7 @@ mod tests {
 		RuntimeCall::Parachains(crate::Call::<TestRuntime, ()>::submit_parachain_heads {
 			at_relay_block: (num, Default::default()),
 			parachains,
-			parachain_heads_proof: ParaHeadsProof(Vec::new()),
+			parachain_heads_proof: ParaHeadsProof { storage_proof: Vec::new() },
 		})
 		.check_obsolete_submit_parachain_heads()
 		.is_ok()

bridges/modules/parachains/src/lib.rs

@@ -21,6 +21,7 @@
 //! accepts storage proof of some parachain `Heads` entries from bridged relay chain.
 //! It requires corresponding relay headers to be already synced.
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 pub use weights::WeightInfo;
@@ -98,27 +99,49 @@ pub mod pallet {
 	#[pallet::generate_deposit(pub(super) fn deposit_event)]
 	pub enum Event<T: Config<I>, I: 'static = ()> {
 		/// The caller has provided head of parachain that the pallet is not configured to track.
-		UntrackedParachainRejected { parachain: ParaId },
+		UntrackedParachainRejected {
+			/// Identifier of the parachain that is not tracked by the pallet.
+			parachain: ParaId,
+		},
 		/// The caller has declared that he has provided given parachain head, but it is missing
 		/// from the storage proof.
-		MissingParachainHead { parachain: ParaId },
+		MissingParachainHead {
+			/// Identifier of the parachain with missing head.
+			parachain: ParaId,
+		},
 		/// The caller has provided parachain head hash that is not matching the hash read from the
 		/// storage proof.
 		IncorrectParachainHeadHash {
+			/// Identifier of the parachain with incorrect head hast.
 			parachain: ParaId,
+			/// Specified parachain head hash.
 			parachain_head_hash: ParaHash,
+			/// Actual parachain head hash.
 			actual_parachain_head_hash: ParaHash,
 		},
 		/// The caller has provided obsolete parachain head, which is already known to the pallet.
-		RejectedObsoleteParachainHead { parachain: ParaId, parachain_head_hash: ParaHash },
+		RejectedObsoleteParachainHead {
+			/// Identifier of the parachain with obsolete head.
+			parachain: ParaId,
+			/// Obsolete parachain head hash.
+			parachain_head_hash: ParaHash,
+		},
 		/// The caller has provided parachain head that exceeds the maximal configured head size.
 		RejectedLargeParachainHead {
+			/// Identifier of the parachain with rejected head.
 			parachain: ParaId,
+			/// Parachain head hash.
 			parachain_head_hash: ParaHash,
+			/// Parachain head size.
 			parachain_head_size: u32,
 		},
 		/// Parachain head has been updated.
-		UpdatedParachainHead { parachain: ParaId, parachain_head_hash: ParaHash },
+		UpdatedParachainHead {
+			/// Identifier of the parachain that has been updated.
+			parachain: ParaId,
+			/// Parachain head hash.
+			parachain_head_hash: ParaHash,
+		},
 	}
 
 	#[pallet::error]
@@ -137,6 +160,7 @@ pub mod pallet {
 	pub trait BoundedBridgeGrandpaConfig<I: 'static>:
 		pallet_bridge_grandpa::Config<I, BridgedChain = Self::BridgedRelayChain>
 	{
+		/// Type of the bridged relay chain.
 		type BridgedRelayChain: Chain<
 			BlockNumber = RelayBlockNumber,
 			Hash = RelayBlockHash,
@@ -336,7 +360,7 @@ pub mod pallet {
 
 			let mut storage = GrandpaPalletOf::<T, I>::storage_proof_checker(
 				relay_block_hash,
-				parachain_heads_proof.0,
+				parachain_heads_proof.storage_proof,
 			)
 			.map_err(Error::<T, I>::HeaderChainStorageProof)?;
 

bridges/modules/parachains/src/mock.rs

@@ -16,7 +16,7 @@
 
 use bp_header_chain::ChainWithGrandpa;
 use bp_polkadot_core::parachains::ParaId;
-use bp_runtime::{Chain, Parachain};
+use bp_runtime::{Chain, ChainId, Parachain};
 use frame_support::{
 	construct_runtime, derive_impl, parameter_types, traits::ConstU32, weights::Weight,
 };
@@ -49,6 +49,8 @@ pub type BigParachainHeader = sp_runtime::generic::Header<u128, BlakeTwo256>;
 pub struct Parachain1;
 
 impl Chain for Parachain1 {
+	const ID: ChainId = *b"pch1";
+
 	type BlockNumber = u64;
 	type Hash = H256;
 	type Hasher = RegularParachainHasher;
@@ -73,6 +75,8 @@ impl Parachain for Parachain1 {
 pub struct Parachain2;
 
 impl Chain for Parachain2 {
+	const ID: ChainId = *b"pch2";
+
 	type BlockNumber = u64;
 	type Hash = H256;
 	type Hasher = RegularParachainHasher;
@@ -97,6 +101,8 @@ impl Parachain for Parachain2 {
 pub struct Parachain3;
 
 impl Chain for Parachain3 {
+	const ID: ChainId = *b"pch3";
+
 	type BlockNumber = u64;
 	type Hash = H256;
 	type Hasher = RegularParachainHasher;
@@ -122,6 +128,8 @@ impl Parachain for Parachain3 {
 pub struct BigParachain;
 
 impl Chain for BigParachain {
+	const ID: ChainId = *b"bpch";
+
 	type BlockNumber = u128;
 	type Hash = H256;
 	type Hasher = RegularParachainHasher;
@@ -229,6 +237,8 @@ impl pallet_bridge_parachains::benchmarking::Config<()> for TestRuntime {
 pub struct TestBridgedChain;
 
 impl Chain for TestBridgedChain {
+	const ID: ChainId = *b"tbch";
+
 	type BlockNumber = crate::RelayBlockNumber;
 	type Hash = crate::RelayBlockHash;
 	type Hasher = crate::RelayBlockHasher;
@@ -260,6 +270,8 @@ impl ChainWithGrandpa for TestBridgedChain {
 pub struct OtherBridgedChain;
 
 impl Chain for OtherBridgedChain {
+	const ID: ChainId = *b"obch";
+
 	type BlockNumber = u64;
 	type Hash = crate::RelayBlockHash;
 	type Hasher = crate::RelayBlockHasher;

bridges/primitives/chain-bridge-hub-cumulus/src/lib.rs

@@ -14,6 +14,9 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
 
+//! Primitives of all Cumulus-based bridge hubs.
+
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 pub use bp_polkadot_core::{
@@ -61,6 +64,7 @@ const MAXIMUM_BLOCK_WEIGHT: Weight = Weight::from_parts(constants::WEIGHT_REF_TI
 pub const AVERAGE_ON_INITIALIZE_RATIO: Perbill = Perbill::from_percent(5);
 
 parameter_types! {
+	/// Size limit of the Cumulus-based bridge hub blocks.
 	pub BlockLength: limits::BlockLength = limits::BlockLength::max_with_normal_ratio(
 		5 * 1024 * 1024,
 		NORMAL_DISPATCH_RATIO,
@@ -73,6 +77,7 @@ parameter_types! {
 	pub const ExtrinsicBaseWeight: Weight = Weight::from_parts(constants::WEIGHT_REF_TIME_PER_NANOS, 0)
 		.saturating_mul(125_000);
 
+	/// Weight limit of the Cumulus-based bridge hub blocks.
 	pub BlockWeights: limits::BlockWeights = limits::BlockWeights::builder()
 		.base_block(BlockExecutionWeight::get())
 		.for_class(DispatchClass::all(), |weights| {