From 0fa1b01f70f7315889bfdd7fcdec37d71ce58577 Mon Sep 17 00:00:00 2001 From: Svyatoslav Nikolsky Date: Mon, 17 Jul 2023 12:26:09 +0300 Subject: [PATCH] Some code grooming (#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 --- .gitlab-ci.yml | 3 +- bin/runtime-common/src/lib.rs | 1 + bin/runtime-common/src/messages_call_ext.rs | 7 ++- .../src/messages_xcm_extension.rs | 5 ++- .../src/parachains_benchmarking.rs | 2 +- .../src/refund_relayer_extension.rs | 2 +- deny.toml | 9 ---- modules/beefy/src/lib.rs | 1 + modules/grandpa/src/lib.rs | 5 ++- modules/messages/src/lib.rs | 18 ++++++-- modules/parachains/src/lib.rs | 32 ++++++++++++-- modules/shift-session-manager/src/lib.rs | 1 + .../chain-bridge-hub-cumulus/src/lib.rs | 5 +++ primitives/chain-bridge-hub-kusama/src/lib.rs | 1 + .../chain-bridge-hub-polkadot/src/lib.rs | 1 + primitives/chain-bridge-hub-rococo/src/lib.rs | 1 + primitives/chain-bridge-hub-wococo/src/lib.rs | 1 + primitives/chain-kusama/src/lib.rs | 5 ++- primitives/chain-millau/src/lib.rs | 12 +++++- primitives/chain-polkadot/src/lib.rs | 5 ++- primitives/chain-rialto-parachain/src/lib.rs | 7 ++- primitives/chain-rialto/src/lib.rs | 15 +++++-- primitives/chain-rococo/src/lib.rs | 11 ++--- primitives/chain-westend/src/lib.rs | 5 ++- primitives/chain-wococo/src/lib.rs | 7 +-- primitives/header-chain/src/justification.rs | 1 + primitives/header-chain/src/lib.rs | 11 ++++- primitives/messages/src/lib.rs | 13 ++++-- primitives/parachains/src/lib.rs | 4 ++ primitives/polkadot-core/src/lib.rs | 10 +++++ primitives/polkadot-core/src/parachains.rs | 1 + primitives/runtime/src/extensions.rs | 4 +- primitives/runtime/src/lib.rs | 43 ++++--------------- primitives/runtime/src/storage_proof.rs | 2 + primitives/test-utils/src/keyring.rs | 11 ++++- primitives/test-utils/src/lib.rs | 4 ++ 36 files changed, 178 insertions(+), 88 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index c0117509e70..f152d31bea9 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -100,8 +100,7 @@ clippy-nightly: variables: RUSTFLAGS: "-D warnings" script: - # clippy currently is raising `derive-partial-eq-without-eq` warning even if `Eq` is actually derived - - SKIP_WASM_BUILD=1 cargo +nightly clippy --all-targets -- -A clippy::redundant_closure -A clippy::derive-partial-eq-without-eq -A clippy::or_fun_call + - SKIP_WASM_BUILD=1 cargo +nightly clippy --all-targets fmt: stage: test diff --git a/bin/runtime-common/src/lib.rs b/bin/runtime-common/src/lib.rs index 7501ce4a692..459466264eb 100644 --- a/bin/runtime-common/src/lib.rs +++ b/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; diff --git a/bin/runtime-common/src/messages_call_ext.rs b/bin/runtime-common/src/messages_call_ext.rs index 4ec82b84656..daf51e0a334 100644 --- a/bin/runtime-common/src/messages_call_ext.rs +++ b/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 . +//! Signed extension for the `pallet-bridge-messages` that is able to reject obsolete +//! (and some other invalid) transactions. + use bp_messages::{ChainWithMessages, InboundLaneData, LaneId, MessageNonce}; use bp_runtime::AccountIdOf; use frame_support::{dispatch::CallableCallFor, traits::IsSubType, RuntimeDebug}; @@ -105,7 +108,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), } @@ -121,7 +126,7 @@ impl CallInfo { /// Helper struct that provides methods for working with a call supported by `CallInfo`. pub struct CallHelper, I: 'static> { - pub _phantom_data: sp_std::marker::PhantomData<(T, I)>, + _phantom_data: sp_std::marker::PhantomData<(T, I)>, } impl, I: 'static> CallHelper { diff --git a/bin/runtime-common/src/messages_xcm_extension.rs b/bin/runtime-common/src/messages_xcm_extension.rs index c6a7703a72e..6b412747f68 100644 --- a/bin/runtime-common/src/messages_xcm_extension.rs +++ b/bin/runtime-common/src/messages_xcm_extension.rs @@ -57,11 +57,14 @@ where } } -/// 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), } diff --git a/bin/runtime-common/src/parachains_benchmarking.rs b/bin/runtime-common/src/parachains_benchmarking.rs index c9967197dfb..b3c220b56f0 100644 --- a/bin/runtime-common/src/parachains_benchmarking.rs +++ b/bin/runtime-common/src/parachains_benchmarking.rs @@ -60,7 +60,7 @@ where } } -pub fn do_prepare_parachain_heads_proof( +fn do_prepare_parachain_heads_proof( parachains: &[ParaId], parachain_head_size: u32, proof_params: UnverifiedStorageProofParams, diff --git a/bin/runtime-common/src/refund_relayer_extension.rs b/bin/runtime-common/src/refund_relayer_extension.rs index 90f6d4bfce1..0b0be3f0049 100644 --- a/bin/runtime-common/src/refund_relayer_extension.rs +++ b/bin/runtime-common/src/refund_relayer_extension.rs @@ -118,7 +118,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. diff --git a/deny.toml b/deny.toml index 264a37bd989..e2d514603f2 100644 --- a/deny.toml +++ b/deny.toml @@ -50,15 +50,6 @@ notice = "warn" ignore = [ # time (origin: Substrate RPC + benchmarking crates) "RUSTSEC-2020-0071", - # ansi_term (The maintainer has adviced that this crate is deprecated and will not receive any maintenance. - # Once other crates will move to some alternative, we'll do that too) - "RUSTSEC-2021-0139", - # deprecated parity-wasm (origin: Substrate) - "RUSTSEC-2022-0061", - # atty (origin: Substrate, clap) - "RUSTSEC-2021-0145", - # wasmtime (origin: Substrate) - "RUSTSEC-2022-0076", ] # Threshold for security vulnerabilities, any vulnerability with a CVSS score # lower than the range specified will be ignored. Note that ignored advisories diff --git a/modules/beefy/src/lib.rs b/modules/beefy/src/lib.rs index cd7bc06a11d..31c2c7d2594 100644 --- a/modules/beefy/src/lib.rs +++ b/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}; diff --git a/modules/grandpa/src/lib.rs b/modules/grandpa/src/lib.rs index 59c56df47f6..f917a2bd1e2 100644 --- a/modules/grandpa/src/lib.rs +++ b/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; @@ -400,7 +399,9 @@ pub mod pallet { pub enum Event, 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, + /// Hash of the new best finalized header. hash: BridgedBlockHash, }, } diff --git a/modules/messages/src/lib.rs b/modules/messages/src/lib.rs index bbbc639a511..b1ab14b73a4 100644 --- a/modules/messages/src/lib.rs +++ b/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::{InboundLane, InboundLaneStorage, StoredInboundLaneData}; pub use lanes_manager::{ @@ -426,13 +425,24 @@ pub mod pallet { #[pallet::generate_deposit(pub(super) fn deposit_event)] pub enum Event, 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. ReceivedMessages<::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] diff --git a/modules/parachains/src/lib.rs b/modules/parachains/src/lib.rs index 050fa67485d..a6e12a16348 100644 --- a/modules/parachains/src/lib.rs +++ b/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, 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: pallet_bridge_grandpa::Config { + /// Type of the bridged relay chain. type BridgedRelayChain: Chain< BlockNumber = RelayBlockNumber, Hash = RelayBlockHash, diff --git a/modules/shift-session-manager/src/lib.rs b/modules/shift-session-manager/src/lib.rs index 1c38a52b0c2..efa34fc4303 100644 --- a/modules/shift-session-manager/src/lib.rs +++ b/modules/shift-session-manager/src/lib.rs @@ -17,6 +17,7 @@ //! Substrate session manager that selects 2/3 validators from initial set, //! starting from session 2. +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] use frame_support::traits::{ValidatorSet, ValidatorSetWithIdentification}; diff --git a/primitives/chain-bridge-hub-cumulus/src/lib.rs b/primitives/chain-bridge-hub-cumulus/src/lib.rs index 64146dafd32..59c9c33adc2 100644 --- a/primitives/chain-bridge-hub-cumulus/src/lib.rs +++ b/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 . +//! Primitives of all Cumulus-based bridge hubs. + +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] pub use bp_polkadot_core::{ @@ -62,6 +65,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, @@ -74,6 +78,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| { diff --git a/primitives/chain-bridge-hub-kusama/src/lib.rs b/primitives/chain-bridge-hub-kusama/src/lib.rs index ed50a9c4fd3..4383121df83 100644 --- a/primitives/chain-bridge-hub-kusama/src/lib.rs +++ b/primitives/chain-bridge-hub-kusama/src/lib.rs @@ -17,6 +17,7 @@ //! Module with configuration which reflects BridgeHubKusama runtime setup (AccountId, Headers, //! Hashes...) +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] pub use bp_bridge_hub_cumulus::*; diff --git a/primitives/chain-bridge-hub-polkadot/src/lib.rs b/primitives/chain-bridge-hub-polkadot/src/lib.rs index 60cf213ba5e..d316d266420 100644 --- a/primitives/chain-bridge-hub-polkadot/src/lib.rs +++ b/primitives/chain-bridge-hub-polkadot/src/lib.rs @@ -17,6 +17,7 @@ //! Module with configuration which reflects BridgeHubPolkadot runtime setup //! (AccountId, Headers, Hashes...) +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] pub use bp_bridge_hub_cumulus::*; diff --git a/primitives/chain-bridge-hub-rococo/src/lib.rs b/primitives/chain-bridge-hub-rococo/src/lib.rs index e4a97d9e99a..5e853cc4c0e 100644 --- a/primitives/chain-bridge-hub-rococo/src/lib.rs +++ b/primitives/chain-bridge-hub-rococo/src/lib.rs @@ -17,6 +17,7 @@ //! Module with configuration which reflects BridgeHubRococo runtime setup (AccountId, Headers, //! Hashes...) +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] pub use bp_bridge_hub_cumulus::*; diff --git a/primitives/chain-bridge-hub-wococo/src/lib.rs b/primitives/chain-bridge-hub-wococo/src/lib.rs index ea6f12361e4..ccea6dda361 100644 --- a/primitives/chain-bridge-hub-wococo/src/lib.rs +++ b/primitives/chain-bridge-hub-wococo/src/lib.rs @@ -17,6 +17,7 @@ //! Module with configuration which reflects BridgeHubWococo runtime setup //! (AccountId, Headers, Hashes...) +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] pub use bp_bridge_hub_cumulus::*; diff --git a/primitives/chain-kusama/src/lib.rs b/primitives/chain-kusama/src/lib.rs index 7970c84c451..a8a5302391f 100644 --- a/primitives/chain-kusama/src/lib.rs +++ b/primitives/chain-kusama/src/lib.rs @@ -14,9 +14,10 @@ // You should have received a copy of the GNU General Public License // along with Parity Bridges Common. If not, see . +//! Primitives of the Kusama chain. + +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] -// RuntimeApi generated functions -#![allow(clippy::too_many_arguments)] pub use bp_polkadot_core::*; use frame_support::StateVersion; diff --git a/primitives/chain-millau/src/lib.rs b/primitives/chain-millau/src/lib.rs index eb8e1943604..2ee863dda96 100644 --- a/primitives/chain-millau/src/lib.rs +++ b/primitives/chain-millau/src/lib.rs @@ -14,9 +14,10 @@ // You should have received a copy of the GNU General Public License // along with Parity Bridges Common. If not, see . +//! Primitives of the Millau chain. + +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] -// RuntimeApi generated functions -#![allow(clippy::too_many_arguments)] mod millau_hash; @@ -112,11 +113,16 @@ pub use time_units::*; pub mod time_units { use super::BlockNumber; + /// Milliseconds between Millau chain blocks. pub const MILLISECS_PER_BLOCK: u64 = 6000; + /// Slot duration in Millau chain consensus algorithms. pub const SLOT_DURATION: u64 = MILLISECS_PER_BLOCK; + /// A minute, expressed in Millau chain blocks. pub const MINUTES: BlockNumber = 60_000 / (MILLISECS_PER_BLOCK as BlockNumber); + /// A hour, expressed in Millau chain blocks. pub const HOURS: BlockNumber = MINUTES * 60; + /// A day, expressed in Millau chain blocks. pub const DAYS: BlockNumber = HOURS * 24; } @@ -245,8 +251,10 @@ impl sp_runtime::traits::Hash for BlakeTwoAndKeccak256 { } frame_support::parameter_types! { + /// Size limit of the Millau blocks. pub BlockLength: limits::BlockLength = limits::BlockLength::max_with_normal_ratio(2 * 1024 * 1024, NORMAL_DISPATCH_RATIO); + /// Weight limit of the Millau blocks. pub BlockWeights: limits::BlockWeights = limits::BlockWeights::with_sensible_defaults(MAXIMUM_BLOCK_WEIGHT, NORMAL_DISPATCH_RATIO); } diff --git a/primitives/chain-polkadot/src/lib.rs b/primitives/chain-polkadot/src/lib.rs index ca624393b9e..b7e071cd753 100644 --- a/primitives/chain-polkadot/src/lib.rs +++ b/primitives/chain-polkadot/src/lib.rs @@ -14,9 +14,10 @@ // You should have received a copy of the GNU General Public License // along with Parity Bridges Common. If not, see . +//! Primitives of the Polkadot chain. + +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] -// RuntimeApi generated functions -#![allow(clippy::too_many_arguments)] pub use bp_polkadot_core::*; use frame_support::StateVersion; diff --git a/primitives/chain-rialto-parachain/src/lib.rs b/primitives/chain-rialto-parachain/src/lib.rs index 9a1fc5e719d..0a7e710b64c 100644 --- a/primitives/chain-rialto-parachain/src/lib.rs +++ b/primitives/chain-rialto-parachain/src/lib.rs @@ -14,9 +14,10 @@ // You should have received a copy of the GNU General Public License // along with Parity Bridges Common. If not, see . +//! Primitives of the Rialto parachain. + +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] -// RuntimeApi generated functions -#![allow(clippy::too_many_arguments)] use bp_messages::{ ChainWithMessages, InboundMessageDetails, LaneId, MessageNonce, MessagePayload, @@ -152,8 +153,10 @@ impl ChainWithMessages for RialtoParachain { pub use bp_bridge_hub_cumulus::SignedExtension; frame_support::parameter_types! { + /// Size limit of the Rialto parachain blocks. pub BlockLength: limits::BlockLength = limits::BlockLength::max_with_normal_ratio(5 * 1024 * 1024, NORMAL_DISPATCH_RATIO); + /// Weight limit of the Rialto parachain blocks. pub BlockWeights: limits::BlockWeights = limits::BlockWeights::with_sensible_defaults(MAXIMUM_BLOCK_WEIGHT, NORMAL_DISPATCH_RATIO); } diff --git a/primitives/chain-rialto/src/lib.rs b/primitives/chain-rialto/src/lib.rs index c987ba91cf3..60f6cf24fb7 100644 --- a/primitives/chain-rialto/src/lib.rs +++ b/primitives/chain-rialto/src/lib.rs @@ -14,9 +14,10 @@ // You should have received a copy of the GNU General Public License // along with Parity Bridges Common. If not, see . +//! Primitives of the Rialto chain. + +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] -// RuntimeApi generated functions -#![allow(clippy::too_many_arguments)] use bp_header_chain::ChainWithGrandpa; use bp_messages::{ @@ -109,16 +110,22 @@ pub use time_units::*; pub mod time_units { use super::{BlockNumber, SESSION_LENGTH}; + /// Milliseconds between Rialto chain blocks. pub const MILLISECS_PER_BLOCK: u64 = 6000; + /// Slot duration in Rialto chain consensus algorithms. pub const SLOT_DURATION: u64 = MILLISECS_PER_BLOCK; + /// A minute, expressed in Rialto chain blocks. pub const MINUTES: BlockNumber = 60_000 / (MILLISECS_PER_BLOCK as BlockNumber); + /// A hour, expressed in Rialto chain blocks. pub const HOURS: BlockNumber = MINUTES * 60; + /// A day, expressed in Rialto chain blocks. pub const DAYS: BlockNumber = HOURS * 24; + /// BABE epoch duration at Rialto. pub const EPOCH_DURATION_IN_SLOTS: BlockNumber = SESSION_LENGTH; - // 1 in 4 blocks (on average, not counting collisions) will be primary babe blocks. + /// 1 in 4 blocks (on average, not counting collisions) will be primary babe blocks. pub const PRIMARY_PROBABILITY: (u64, u64) = (1, 4); } @@ -205,8 +212,10 @@ impl ChainWithMessages for Rialto { } frame_support::parameter_types! { + /// Size limit of the Rialto blocks. pub BlockLength: limits::BlockLength = limits::BlockLength::max_with_normal_ratio(5 * 1024 * 1024, NORMAL_DISPATCH_RATIO); + /// Weight limit of the Rialto blocks. pub BlockWeights: limits::BlockWeights = limits::BlockWeights::with_sensible_defaults(MAXIMUM_BLOCK_WEIGHT, NORMAL_DISPATCH_RATIO); } diff --git a/primitives/chain-rococo/src/lib.rs b/primitives/chain-rococo/src/lib.rs index ccac5dccd40..a1c596fa4dd 100644 --- a/primitives/chain-rococo/src/lib.rs +++ b/primitives/chain-rococo/src/lib.rs @@ -14,15 +14,16 @@ // You should have received a copy of the GNU General Public License // along with Parity Bridges Common. If not, see . +//! Primitives of the Rococo chain. + +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] -// RuntimeApi generated functions -#![allow(clippy::too_many_arguments)] pub use bp_polkadot_core::*; use bp_header_chain::ChainWithGrandpa; use bp_runtime::{decl_bridge_finality_runtime_apis, Chain, ChainId}; -use frame_support::{parameter_types, weights::Weight, StateVersion}; +use frame_support::{weights::Weight, StateVersion}; /// Rococo Chain pub struct Rococo; @@ -60,10 +61,6 @@ impl ChainWithGrandpa for Rococo { const AVERAGE_HEADER_SIZE_IN_JUSTIFICATION: u32 = AVERAGE_HEADER_SIZE_IN_JUSTIFICATION; } -parameter_types! { - pub const SS58Prefix: u8 = 42; -} - /// Name of the parachains pallet in the Rococo runtime. pub const PARAS_PALLET_NAME: &str = "Paras"; diff --git a/primitives/chain-westend/src/lib.rs b/primitives/chain-westend/src/lib.rs index 9e4223a6416..1c10ab844d9 100644 --- a/primitives/chain-westend/src/lib.rs +++ b/primitives/chain-westend/src/lib.rs @@ -14,9 +14,10 @@ // You should have received a copy of the GNU General Public License // along with Parity Bridges Common. If not, see . +//! Primitives of the Westend chain. + +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] -// RuntimeApi generated functions -#![allow(clippy::too_many_arguments)] pub use bp_polkadot_core::*; use frame_support::StateVersion; diff --git a/primitives/chain-wococo/src/lib.rs b/primitives/chain-wococo/src/lib.rs index 06d9fc83680..20c113cf838 100644 --- a/primitives/chain-wococo/src/lib.rs +++ b/primitives/chain-wococo/src/lib.rs @@ -14,13 +14,14 @@ // You should have received a copy of the GNU General Public License // along with Parity Bridges Common. If not, see . +//! Primitives of the Rococo chain. + +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] -// RuntimeApi generated functions -#![allow(clippy::too_many_arguments)] pub use bp_polkadot_core::*; pub use bp_rococo::{ - SS58Prefix, MAX_AUTHORITIES_COUNT, MAX_NESTED_PARACHAIN_HEAD_DATA_SIZE, PARAS_PALLET_NAME, + MAX_AUTHORITIES_COUNT, MAX_NESTED_PARACHAIN_HEAD_DATA_SIZE, PARAS_PALLET_NAME, }; use frame_support::StateVersion; diff --git a/primitives/header-chain/src/justification.rs b/primitives/header-chain/src/justification.rs index b83c697d608..0a3685d6345 100644 --- a/primitives/header-chain/src/justification.rs +++ b/primitives/header-chain/src/justification.rs @@ -85,6 +85,7 @@ impl GrandpaJustification { .saturating_add(max_expected_votes_ancestries_size) } + /// Return identifier of header that this justification claims to finalize. pub fn commit_target_id(&self) -> HeaderId { HeaderId(self.commit.target_number, self.commit.target_hash) } diff --git a/primitives/header-chain/src/lib.rs b/primitives/header-chain/src/lib.rs index 81992d28255..dcda651f9ca 100644 --- a/primitives/header-chain/src/lib.rs +++ b/primitives/header-chain/src/lib.rs @@ -17,6 +17,7 @@ //! Defines traits which represent a common interface for Substrate pallets which want to //! incorporate bridge functionality. +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] use bp_runtime::{ @@ -153,6 +154,7 @@ pub trait ConsensusLogReader { pub struct GrandpaConsensusLogReader(sp_std::marker::PhantomData); impl GrandpaConsensusLogReader { + /// Find and return scheduled (regular) change digest item. pub fn find_scheduled_change( digest: &Digest, ) -> Option> { @@ -166,6 +168,8 @@ impl GrandpaConsensusLogReader { }) } + /// Find and return forced change digest item. Or light client can't do anything + /// with forced changes, so we can't accept header with the forced change digest. pub fn find_forced_change( digest: &Digest, ) -> Option<(Number, sp_consensus_grandpa::ScheduledChange)> { @@ -193,12 +197,17 @@ pub enum BridgeGrandpaCall { /// `pallet-bridge-grandpa::Call::submit_finality_proof` #[codec(index = 0)] submit_finality_proof { + /// The header that we are going to finalize. finality_target: Box
, + /// Finality justification for the `finality_target`. justification: justification::GrandpaJustification
, }, /// `pallet-bridge-grandpa::Call::initialize` #[codec(index = 1)] - initialize { init_data: InitializationData
}, + initialize { + /// All data, required to initialize the pallet. + init_data: InitializationData
, + }, } /// The `BridgeGrandpaCall` used by a chain. diff --git a/primitives/messages/src/lib.rs b/primitives/messages/src/lib.rs index e757f974087..34c40fff68f 100644 --- a/primitives/messages/src/lib.rs +++ b/primitives/messages/src/lib.rs @@ -16,9 +16,8 @@ //! 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::{ @@ -451,6 +450,7 @@ pub struct ReceivedMessages { } impl ReceivedMessages { + /// Creates new `ReceivedMessages` structure from given results. pub fn new( lane: LaneId, receive_results: Vec<(MessageNonce, ReceivalResult)>, @@ -458,6 +458,7 @@ impl ReceivedMessages { ReceivedMessages { lane, receive_results } } + /// Push `result` of the `message` delivery onto `receive_results` vector. pub fn push(&mut self, message: MessageNonce, result: ReceivalResult) { self.receive_results.push((message, result)); } @@ -529,7 +530,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(&self, lane_data: &InboundLaneData) -> bool { self == &lane_data.into() } @@ -621,15 +622,21 @@ pub enum BridgeMessagesCall { /// `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, }, } diff --git a/primitives/parachains/src/lib.rs b/primitives/parachains/src/lib.rs index e619fc7b641..2c96a3b31dd 100644 --- a/primitives/parachains/src/lib.rs +++ b/primitives/parachains/src/lib.rs @@ -16,6 +16,7 @@ //! Primitives of parachains module. +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] pub use bp_header_chain::StoredHeaderData; @@ -173,8 +174,11 @@ pub enum BridgeParachainCall { /// `pallet-bridge-parachains::Call::submit_parachain_heads` #[codec(index = 0)] submit_parachain_heads { + /// Relay chain block, for which we have submitted the `parachain_heads_proof`. at_relay_block: (RelayBlockNumber, RelayBlockHash), + /// Parachain identifiers and their head hashes. parachains: Vec<(ParaId, ParaHash)>, + /// Parachain heads proof. parachain_heads_proof: ParaHeadsProof, }, } diff --git a/primitives/polkadot-core/src/lib.rs b/primitives/polkadot-core/src/lib.rs index 96a58267303..97d83bdfe53 100644 --- a/primitives/polkadot-core/src/lib.rs +++ b/primitives/polkadot-core/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 . +//! Primitives of the Polkadot-like chains. + +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] use bp_messages::MessageNonce; @@ -167,11 +170,16 @@ pub use time_units::*; pub mod time_units { use super::BlockNumber; + /// Milliseconds between Polkadot-like chain blocks. pub const MILLISECS_PER_BLOCK: u64 = 6000; + /// Slot duration in Polkadot-like chain consensus algorithms. pub const SLOT_DURATION: u64 = MILLISECS_PER_BLOCK; + /// A minute, expressed in Polkadot-like chain blocks. pub const MINUTES: BlockNumber = 60_000 / (MILLISECS_PER_BLOCK as BlockNumber); + /// A hour, expressed in Polkadot-like chain blocks. pub const HOURS: BlockNumber = MINUTES * 60; + /// A day, expressed in Polkadot-like chain blocks. pub const DAYS: BlockNumber = HOURS * 24; } @@ -254,8 +262,10 @@ impl StorageMapKeyProvider for AccountInfoStorageMapKeyProvider { } impl AccountInfoStorageMapKeyProvider { + /// Name of the system pallet. const PALLET_NAME: &'static str = "System"; + /// Return storage key for given account data. pub fn final_key(id: &AccountId) -> StorageKey { ::final_key(Self::PALLET_NAME, id) } diff --git a/primitives/polkadot-core/src/parachains.rs b/primitives/polkadot-core/src/parachains.rs index fedbce22986..f3e24bb3502 100644 --- a/primitives/polkadot-core/src/parachains.rs +++ b/primitives/polkadot-core/src/parachains.rs @@ -89,6 +89,7 @@ pub type ParaHasher = crate::Hasher; /// Raw storage proof of parachain heads, stored in polkadot-like chain runtime. #[derive(Clone, Decode, Encode, Eq, PartialEq, RuntimeDebug, TypeInfo)] pub struct ParaHeadsProof { + /// Unverified storage proof of finalized parachain heads. pub storage_proof: UnverifiedStorageProof, } diff --git a/primitives/runtime/src/extensions.rs b/primitives/runtime/src/extensions.rs index 96ee9d1e6ec..784793992be 100644 --- a/primitives/runtime/src/extensions.rs +++ b/primitives/runtime/src/extensions.rs @@ -35,7 +35,7 @@ pub trait SignedExtensionSchema: Encode + Decode + Debug + Eq + Clone + StaticTy type AdditionalSigned: Encode + Debug + Eq + Clone + StaticTypeInfo; } -// An implementation of `SignedExtensionSchema` using generic params. +/// An implementation of `SignedExtensionSchema` using generic params. #[derive(Encode, Decode, Clone, Debug, PartialEq, Eq, TypeInfo)] pub struct GenericSignedExtensionSchema(PhantomData<(P, S)>); @@ -94,6 +94,7 @@ impl SignedExtensionSchema for Tuple { /// and signed payloads in the client code. #[derive(Encode, Decode, Debug, PartialEq, Eq, Clone, TypeInfo)] pub struct GenericSignedExtension { + /// A payload that is included in the transaction. pub payload: S::Payload, #[codec(skip)] // It may be set to `None` if extensions are decoded. We are never reconstructing transactions @@ -104,6 +105,7 @@ pub struct GenericSignedExtension { } impl GenericSignedExtension { + /// Create new `GenericSignedExtension` object. pub fn new(payload: S::Payload, additional_signed: Option) -> Self { Self { payload, additional_signed } } diff --git a/primitives/runtime/src/lib.rs b/primitives/runtime/src/lib.rs index eb8fb4deadc..69f72d331bc 100644 --- a/primitives/runtime/src/lib.rs +++ b/primitives/runtime/src/lib.rs @@ -16,6 +16,7 @@ //! Primitives that may be used at (bridges) runtime level. +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] use codec::{Decode, Encode, FullCodec, MaxEncodedLen}; @@ -90,10 +91,10 @@ pub type HeaderIdOf = HeaderId, BlockNumberOf>; /// Generic header id provider. pub trait HeaderIdProvider { - // Get the header id. + /// Get the header id. fn id(&self) -> HeaderId; - // Get the header id for the parent block. + /// Get the header id for the parent block. fn parent_id(&self) -> Option>; } @@ -326,7 +327,7 @@ pub enum OwnedBridgeModuleError { /// Operating mode for a bridge module. pub trait OperatingMode: Send + Copy + Debug + FullCodec { - // Returns true if the bridge module is halted. + /// Returns true if the bridge module is halted. fn is_halted(&self) -> bool; } @@ -368,8 +369,11 @@ pub trait OwnedBridgeModule { /// The target that will be used when publishing logs related to this module. const LOG_TARGET: &'static str; + /// A storage entry that holds the module `Owner` account. type OwnerStorage: StorageValue>; + /// Operating mode type of the pallet. type OperatingMode: OperatingMode; + /// A storage value that holds the pallet operating mode. type OperatingModeStorage: StorageValue; /// Check if the module is halted. @@ -445,9 +449,11 @@ impl WeightExtraOps for Weight { /// Trait that provides a static `str`. pub trait StaticStrProvider { + /// Static string. const STR: &'static str; } +/// A macro that generates `StaticStrProvider` with the string set to its stringified argument. #[macro_export] macro_rules! generate_static_str_provider { ($str:expr) => { @@ -461,37 +467,6 @@ macro_rules! generate_static_str_provider { }; } -#[derive(Encode, Decode, Clone, Eq, PartialEq, PalletError, TypeInfo)] -#[scale_info(skip_type_params(T))] -pub struct StrippableError { - _phantom_data: sp_std::marker::PhantomData, - #[codec(skip)] - #[cfg(feature = "std")] - message: String, -} - -impl From for StrippableError { - fn from(_err: T) -> Self { - Self { - _phantom_data: Default::default(), - #[cfg(feature = "std")] - message: format!("{:?}", _err), - } - } -} - -impl Debug for StrippableError { - #[cfg(feature = "std")] - fn fmt(&self, f: &mut sp_std::fmt::Formatter<'_>) -> sp_std::fmt::Result { - f.write_str(&self.message) - } - - #[cfg(not(feature = "std"))] - fn fmt(&self, f: &mut sp_std::fmt::Formatter<'_>) -> sp_std::fmt::Result { - f.write_str("Stripped error") - } -} - /// A trait defining helper methods for `RangeInclusive` (start..=end) pub trait RangeInclusiveExt { /// Computes the length of the `RangeInclusive`, checking for underflow and overflow. diff --git a/primitives/runtime/src/storage_proof.rs b/primitives/runtime/src/storage_proof.rs index d1ee2620fc9..e4836862132 100644 --- a/primitives/runtime/src/storage_proof.rs +++ b/primitives/runtime/src/storage_proof.rs @@ -260,11 +260,13 @@ impl VerifiedStorageProof { #[cfg(feature = "test-helpers")] #[derive(Clone, Copy, Debug, Default)] pub struct UnverifiedStorageProofParams { + /// Expected storage proof size in bytes. pub db_size: Option, } #[cfg(feature = "test-helpers")] impl UnverifiedStorageProofParams { + /// Make storage proof parameters that require proof of at least `db_size` bytes. pub fn from_db_size(db_size: u32) -> Self { Self { db_size: Some(db_size) } } diff --git a/primitives/test-utils/src/keyring.rs b/primitives/test-utils/src/keyring.rs index b1782109668..e100bf1c6c2 100644 --- a/primitives/test-utils/src/keyring.rs +++ b/primitives/test-utils/src/keyring.rs @@ -23,12 +23,17 @@ use sp_consensus_grandpa::{AuthorityId, AuthorityList, AuthorityWeight}; use sp_runtime::RuntimeDebug; use sp_std::prelude::*; -/// Set of test accounts with friendly names. +/// Set of test accounts with friendly names: Alice. pub const ALICE: Account = Account(0); +/// Set of test accounts with friendly names: Bob. pub const BOB: Account = Account(1); +/// Set of test accounts with friendly names: Charlie. pub const CHARLIE: Account = Account(2); +/// Set of test accounts with friendly names: Dave. pub const DAVE: Account = Account(3); +/// Set of test accounts with friendly names: Eve. pub const EVE: Account = Account(4); +/// Set of test accounts with friendly names: Ferdie. pub const FERDIE: Account = Account(5); /// A test account which can be used to sign messages. @@ -36,10 +41,12 @@ pub const FERDIE: Account = Account(5); pub struct Account(pub u16); impl Account { + /// Returns public key of this account. pub fn public(&self) -> PublicKey { (&self.secret()).into() } + /// Returns secret key of this account. pub fn secret(&self) -> SecretKey { let data = self.0.encode(); let mut bytes = [0_u8; 32]; @@ -48,6 +55,7 @@ impl Account { .expect("A static array of the correct length is a known good.") } + /// Returns key pair, used to sign data on behalf of this account. pub fn pair(&self) -> Keypair { let mut pair: [u8; 64] = [0; 64]; @@ -61,6 +69,7 @@ impl Account { .expect("We expect the SecretKey to be good, so this must also be good.") } + /// Generate a signature of given message. pub fn sign(&self, msg: &[u8]) -> Signature { use ed25519_dalek::Signer; self.pair().sign(msg) diff --git a/primitives/test-utils/src/lib.rs b/primitives/test-utils/src/lib.rs index 4317cf37d45..faab70cbce3 100644 --- a/primitives/test-utils/src/lib.rs +++ b/primitives/test-utils/src/lib.rs @@ -16,6 +16,7 @@ //! Utilities for testing runtime code. +#![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] use bp_header_chain::justification::{required_justification_precommits, GrandpaJustification}; @@ -33,8 +34,11 @@ pub use keyring::*; mod keyring; +/// GRANDPA round number used across tests. pub const TEST_GRANDPA_ROUND: u64 = 1; +/// GRANDPA validators set id used across tests. pub const TEST_GRANDPA_SET_ID: SetId = 1; +/// Name of the `Paras` pallet used across tests. pub const PARAS_PALLET_NAME: &str = "Paras"; /// Configuration parameters when generating test GRANDPA justifications.