From c8d4ad8d89ccfd650b5079944c698288128eb48e Mon Sep 17 00:00:00 2001 From: Radha Date: Thu, 2 May 2024 23:18:12 +0200 Subject: [PATCH 01/16] Update Async Backing docs using Docify Update the instructions to work with the latest parachain template on Polkadot SDK --- docs/sdk/src/guides/mod.rs | 3 + .../guides/parachains/async_backing_guide.rs | 318 ++++++++++++++++++ docs/sdk/src/guides/parachains/mod.rs | 7 + .../parachain/runtime/src/configs/mod.rs | 1 + templates/parachain/runtime/src/lib.rs | 5 + 5 files changed, 334 insertions(+) create mode 100644 docs/sdk/src/guides/parachains/async_backing_guide.rs create mode 100644 docs/sdk/src/guides/parachains/mod.rs diff --git a/docs/sdk/src/guides/mod.rs b/docs/sdk/src/guides/mod.rs index 2dc807af8eae..0e2c6681561d 100644 --- a/docs/sdk/src/guides/mod.rs +++ b/docs/sdk/src/guides/mod.rs @@ -26,3 +26,6 @@ pub mod xcm_enabled_parachain; /// How to enable storage weight reclaiming in a parachain node and runtime. pub mod enable_pov_reclaim; + +/// Parachain guides +pub mod parachains; \ No newline at end of file diff --git a/docs/sdk/src/guides/parachains/async_backing_guide.rs b/docs/sdk/src/guides/parachains/async_backing_guide.rs new file mode 100644 index 000000000000..c1612eeeea3f --- /dev/null +++ b/docs/sdk/src/guides/parachains/async_backing_guide.rs @@ -0,0 +1,318 @@ +//! # Upgrade Parachain for Asynchronous Backing Compatibility +//! +//! This guide is relevant for cumulus based parachain projects started in 2023 or before. Later +//! projects should already be async backing compatible. If starting a new parachain project, please use +//! an async backing compatible template such as +//! [`cumulus/parachain-template`](https://github.com/paritytech/polkadot-sdk/tree/master/templates/parachain). +//! +//! The rollout process for Async Backing has three phases. Phases 1 and 2 below put new infrastructure +//! in place. Then we can simply turn on async backing in phase 3. But first, some pre-reqs and context +//! to set the stage. +//! ## Async Backing Prerequisites +//! +//! For more contextual information about asynchronous backing, see +//! [this page](https://wiki.polkadot.network/docs/learn-async-backing). +//! +//! Pull the latest version of Cumulus for use with your parachain. It contains necessary changes for +//! async backing compatibility. Latest on master branch of +//! [Polkadot-SDK](https://github.com/paritytech/polkadot-sdk) is currently sufficient. Any 2024 release +//! will work as well. +//! +//! ## Async Backing Terminology and Parameters +//! +//! Time for a bit of context before we get started. The following concepts will aid in demystifying the +//! collator side of Async Backing and establish a basic understanding of the changes being made: +//! +//! - **Unincluded segment** - From the perspective of a parachain block under construction, the +//! unincluded segment describes a chain of recent block ancestors which have yet to be included on +//! the relay chain. The ability to build new blocks on top of the unincluded segment rather than on +//! top of blocks freshly included in the relay chain is the core of asynchronous backing. +//! - **Capacity** - The maximum size of the unincluded segment. The longer this is, the farther ahead a +//! parachain can work, producing new candidates before the ancestors of those candidates have been +//! seen as included on-chain. Practically, a capacity of 2-3 is sufficient to realize the full +//! benefits of asynchronous backing, at least until the release of elastic scaling. +//! - **Velocity** - The base rate at which a parachain should produce blocks. A velocity of 1 indicates +//! that 1 parachain block should be produced per relay chain block. In order to fill the unincluded +//! segment with candidates, collators may build up to `Velocity + 1` candidates per aura slot while +//! there is remaining capacity. When elastic scaling has been released velocities greater than 1 will +//! be supported. +//! - **AllowMultipleBlocksPerSlot** - If this is `true`, Aura will allow slots to stay the same across +//! sequential parablocks. Otherwise the slot number must increase with each block. To fill the +//! unincluded segment as described above we need this to be `true`. +//! - **FixedVelocityConsensusHook** - This is a variety of `ConsensusHook` intended to be passed to +//! `parachain-system` as part of its `Config`. It is triggered on initialization of a new runtime. An +//! instance of `FixedVelocityConsensusHook` is defined with both a fixed capacity and velocity. It +//! aborts the runtime early if either capacity or velocity is exceeded, as the collator shouldn’t be +//! creating additional blocks in that case. +//! - **AsyncBackingParams.max_candidate_depth** - This parameter determines the maximum unincluded +//! segment depth the relay chain will support. Candidates sent to validators which exceed +//! `max_candidate_depth` will be ignored. `Capacity`, as mentioned above, should not exceed +//! `max_candidate_depth`. +//! - **AsyncBackingParams.allowed_ancestry_len** - Each parachain block candidate has a `relay_parent` +//! from which its execution and validation context is derived. Before async backing the +//! `relay_parent` for a candidate not yet backed was required to be the fresh head of a fork. With +//! async backing we can relax this requirement. Instead we set a conservative maximum age in blocks +//! for the `relay_parent`s of candidates in the unincluded segment. This age, `allowed_ancestry_len` +//! lives on the relay chain and is queried by parachains when deciding which block to build on top +//! of. +//! - **Lookahead Collator** - A collator for Aura that looks ahead of the most recently included +//! parachain block when determining what to build upon. This collator also builds additional blocks +//! when the maximum backlog is not saturated. The size of the backlog is determined by invoking the +//! AuraUnincludedSegmentApi. If that runtime API is not supported, this assumes a maximum backlog +//! size of 1. +//! +//! ## Prerequisite +//! +//! The relay chain needs to have async backing enabled so double-check that the relay-chain +//! configuration contains the following three parameters (especially when testing locally e.g. with +//! zombienet): +//! +//! ```json +//! "async_backing_params": { +//! "max_candidate_depth": 3, +//! "allowed_ancestry_len": 2 +//! }, +//! "scheduling_lookahead": 2 +//! ``` +//! +//!
`scheduling_lookahead` must be set to 2, otherwise parachain block times will degrade to worse than with sync backing!
+//! +//! +//! +//! +//! +//! ## Phase 1 - Update Parachain Runtime +//! +//! This phase involves configuring your parachain’s runtime to make use of async backing system. +//! +//! 1. Ensure constants for `capacity` and `velocity` are both set to 1 in +//! [`/runtime/src/lib.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/templates/parachain/runtime/src/lib.rs). +//! +//! Change capacity to 1 +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", capacity)] +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", velocity)] +//! +//! 2. Ensure the constant relay chain slot duration measured in milliseconds equal to `6000` in +//! [`/runtime/src/lib.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/templates/parachain/runtime/src/lib.rs). +//! +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", relay_slot_duration)] +//! +//! 3. Establish constants `MILLISECS_PER_BLOCK` and `SLOT_DURATION` if not already present in +//! [`/runtime/src/lib.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/templates/parachain/runtime/src/lib.rs). +//! +//! Change block time to 12000 +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", block_time)] +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", slot_duration)] +//! +//! +//! 4. Configure `pallet_aura` in [`/runtime/src/configs/mod.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/templates/parachain/runtime/src/configs/mod.rs). +#![doc = docify::embed!("../../templates/parachain/runtime/src/configs/mod.rs", aura_config)] +//! +//! - Set `AllowMultipleBlocksPerSlot` to `false` (don't worry, we will set it to `true` when we +//! activate async backing in phase 3). +//! - Ensure `pallet_aura::SlotDuration` is using the constant `SLOT_DURATION` +//! +//! +//! **Note:** With a capacity of 1 we have an effective velocity of ½ even when velocity is configured +//! to some larger value. This is because capacity will be filled after a single block is produced and +//! will only be freed up after that block is included on the relay chain, which takes 2 relay blocks to +//! accomplish. Thus with capacity 1 and velocity 1 we get the customary 12 second parachain block time. +//! +//! +//! ## Phase 2 - Update Parachain Nodes +//! +//! This phase consists of plugging in the new lookahead collator node. +//! +//! 1. Import `cumulus_primitives_core::ValidationCode` to `node/src/service.rs` +//! +//! ```text +//! use cumulus_primitives_core::{ +//! relay_chain::{CollatorPair, ValidationCode}, +//! ParaId, +//! }; +//! ``` +//! +//! 2. In `node/src/service.rs`, modify `sc_service::spawn_tasks` to use a clone of `Backend` rather +//! than the original +//! +//! ```text +//! sc_service::spawn_tasks(sc_service::SpawnTasksParams { +//! rpc_builder, +//! client: client.clone(), +//! transaction_pool: transaction_pool.clone(), +//! task_manager: &mut task_manager, +//! config: parachain_config, +//! keystore: params.keystore_container.keystore(), +//! backend: backend.clone(), +//! network: network.clone(), +//! sync_service: sync_service.clone(), +//! system_rpc_tx, +//! tx_handler_controller, +//! telemetry: telemetry.as_mut(), +//! })?; +//! ``` +//! +//! 3. Add `backend` as a parameter to `start_consensus()` in `node/src/service.rs` +//! +//! ```text +//! fn start_consensus( +//! client: Arc, +//! +//! backend: Arc, +//! block_import: ParachainBlockImport, +//! prometheus_registry: Option<&Registry>, +//! telemetry: Option, +//! task_manager: &TaskManager, +//! ``` +//! +//! ```text +//! if validator { +//! start_consensus( +//! client.clone(), +//! +//! backend.clone(), +//! block_import, +//! prometheus_registry.as_ref(), +//! ``` +//! +//! 4. In `node/src/service.rs` import the lookahead collator rather than the basic collator +//! +//! ```text +//! use cumulus_client_consensus_aura::collators::lookahead::{self as aura, Params as AuraParams}; +//! ``` +//! +//! 5. In `start_consensus()` replace the `BasicAuraParams` struct with `AuraParams` +//! - Change the struct type from `BasicAuraParams` to `AuraParams` +//! - In the `para_client` field, pass in a cloned para client rather than the original +//! - Add a `para_backend` parameter after `para_client`, passing in our para backend +//! - Provide a `code_hash_provider` closure like that shown below +//! - Increase `authoring_duration` from 500 milliseconds to 1500 +//! +//! ```text +//! let params = AuraParams { +//! create_inherent_data_providers: move |_, ()| async move { Ok(()) }, +//! block_import, +//! para_client: client.clone(), +//! para_backend: backend.clone(), +//! relay_client: relay_chain_interface, +//! code_hash_provider: move |block_hash| { +//! client.code_at(block_hash).ok().map(|c| ValidationCode::from(c).hash()) +//! }, +//! sync_oracle, +//! keystore, +//! collator_key, +//! para_id, +//! overseer_handle, +//! relay_chain_slot_duration, +//! proposer, +//! collator_service, +//! +//! authoring_duration: Duration::from_millis(1500), +//! reinitialize: false, +//! }; +//! ``` +//! +//! **Note:** Set `authoring_duration` to whatever you want, taking your own hardware into account. But +//! if the backer who should be slower than you due to reading from disk, times out at two seconds your +//! candidates will be rejected. +//! +//! 6. In `start_consensus()` replace `basic_aura::run` with `aura::run` +//! +//! ```text +//! let fut = aura::run::< +//! Block, +//! sp_consensus_aura::sr25519::AuthorityPair, +//! _, +//! _, +//! _, +//! _, +//! _, +//! _, +//! _, +//! _, +//! _, +//! >(params); +//! task_manager.spawn_essential_handle().spawn("aura", None, fut); +//! ``` +//! +//! ## Phase 3 - Activate Async Backing +//! +//! This phase consists of changes to your parachain’s runtime that activate async backing feature. +//! +//! 1. Configure `pallet_aura`, setting `AllowMultipleBlocksPerSlot` to true in `runtime/src/lib.rs`. +//! +//! ```text +//! impl pallet_aura::Config for Runtime { +//! type AuthorityId = AuraId; +//! type DisabledValidators = (); +//! type MaxAuthorities = ConstU32<100_000>; +//! +//! type AllowMultipleBlocksPerSlot = ConstBool; +//! #[cfg(feature = "experimental")] +//! type SlotDuration = ConstU64; +//! } +//! ``` +//! +//! 1. Increase the maximum `UNINCLUDED_SEGMENT_CAPACITY` in `runtime/src/lib.rs`. +//! +//! ```text +//! //!/ Maximum number of blocks simultaneously accepted by the Runtime, not yet included into the +//! //!/ relay chain. +//! pub const UNINCLUDED_SEGMENT_CAPACITY: u32 = 3; +//! //!/ How many parachain blocks are processed by the relay chain per parent. Limits the number of +//! //!/ blocks authored per slot. +//! pub const BLOCK_PROCESSING_VELOCITY: u32 = 1; +//! ``` +//! +//! 3. Decrease `MILLISECS_PER_BLOCK` to 6000. +//! +//! - Note: For a parachain which measures time in terms of its own block number rather than by relay +//! block number it may be preferable to increase velocity. Changing block time may cause +//! complications, requiring additional changes. See the section “Timing by Block Number”. +//! +//! ```text +//! //!/ This determines the average expected block time that we are targeting. +//! //!/ Blocks will be produced at a minimum duration defined by `SLOT_DURATION`. +//! //!/ `SLOT_DURATION` is picked up by `pallet_timestamp` which is in turn picked +//! //!/ up by `pallet_aura` to implement `fn slot_duration()`. +//! //!/ +//! //!/ Change this to adjust the block time. +//! pub const MILLISECS_PER_BLOCK: u64 = 6000; +//! ``` +//! +//! 4. Update `MAXIMUM_BLOCK_WEIGHT` to reflect the increased time available for block production. +//! +//! ```text +//! //!/ We allow for 2 seconds of compute with a 6 second average block. +//! pub const MAXIMUM_BLOCK_WEIGHT: Weight = Weight::from_parts( +//! WEIGHT_REF_TIME_PER_SECOND.saturating_mul(2), +//! cumulus_primitives_core::relay_chain::MAX_POV_SIZE as u64, +//! ); +//! ``` +//! +//! 5. Add a feature flagged alternative for `MinimumPeriod` in `pallet_timestamp`. The type should be +//! `ConstU64<0>` with the feature flag experimental, and `ConstU64<{SLOT_DURATION / 2}>` without. +//! +//! ```text +//! impl pallet_timestamp::Config for Runtime { +//! type Moment = u64; +//! type OnTimestampSet = Aura; +//! #[cfg(feature = "experimental")] +//! type MinimumPeriod = ConstU64<0>; +//! #[cfg(not(feature = "experimental"))] +//! type MinimumPeriod = ConstU64<{ SLOT_DURATION / 2 }>; +//! type WeightInfo = weights::pallet_timestamp::WeightInfo; +//! } +//! ``` +//! +//! ## Timing by Block Number +//! +//! With asynchronous backing it will be possible for parachains to opt for a block time of 6 seconds +//! rather than 12 seconds. But modifying block duration isn’t so simple for a parachain which was +//! measuring time in terms of its own block number. It could result in expected and actual time not +//! matching up, stalling the parachain. +//! +//! One strategy to deal with this issue is to instead rely on relay chain block numbers for timing. +//! Relay block number is kept track of by each parachain in `pallet-parachain-system` with the storage +//! value `LastRelayChainBlockNumber`. This value can be obtained and used wherever timing based on +//! block number is needed. \ No newline at end of file diff --git a/docs/sdk/src/guides/parachains/mod.rs b/docs/sdk/src/guides/parachains/mod.rs new file mode 100644 index 000000000000..6f6e53b02088 --- /dev/null +++ b/docs/sdk/src/guides/parachains/mod.rs @@ -0,0 +1,7 @@ +//! # Polkadot SDK Docs - Parachain Guides +//! +//! This crate contains a collection of guides for developers and maintainers of parachains built +//! with Polkadot SDK. + +/// Upgrade Parachain for Asynchronous Backing Compatibility +pub mod async_backing_guide; \ No newline at end of file diff --git a/templates/parachain/runtime/src/configs/mod.rs b/templates/parachain/runtime/src/configs/mod.rs index 0aec332feaf6..5809aed20028 100644 --- a/templates/parachain/runtime/src/configs/mod.rs +++ b/templates/parachain/runtime/src/configs/mod.rs @@ -261,6 +261,7 @@ impl pallet_session::Config for Runtime { type WeightInfo = (); } +#[docify::export(aura_config)] impl pallet_aura::Config for Runtime { type AuthorityId = AuraId; type DisabledValidators = (); diff --git a/templates/parachain/runtime/src/lib.rs b/templates/parachain/runtime/src/lib.rs index 179a425ca041..efede2a4b44d 100644 --- a/templates/parachain/runtime/src/lib.rs +++ b/templates/parachain/runtime/src/lib.rs @@ -168,6 +168,7 @@ pub const VERSION: RuntimeVersion = RuntimeVersion { state_version: 1, }; +#[docify::export(block_time)] /// This determines the average expected block time that we are targeting. /// Blocks will be produced at a minimum duration defined by `SLOT_DURATION`. /// `SLOT_DURATION` is picked up by `pallet_timestamp` which is in turn picked @@ -176,6 +177,7 @@ pub const VERSION: RuntimeVersion = RuntimeVersion { /// Change this to adjust the block time. pub const MILLISECS_PER_BLOCK: u64 = 6000; +#[docify::export(slot_duration)] // NOTE: Currently it is not possible to change the slot duration after the chain has started. // Attempting to do so will brick block production. pub const SLOT_DURATION: u64 = MILLISECS_PER_BLOCK; @@ -207,12 +209,15 @@ const MAXIMUM_BLOCK_WEIGHT: Weight = Weight::from_parts( cumulus_primitives_core::relay_chain::MAX_POV_SIZE as u64, ); +#[docify::export(capacity)] /// Maximum number of blocks simultaneously accepted by the Runtime, not yet included /// into the relay chain. const UNINCLUDED_SEGMENT_CAPACITY: u32 = 3; +#[docify::export(velocity)] /// How many parachain blocks are processed by the relay chain per parent. Limits the /// number of blocks authored per slot. const BLOCK_PROCESSING_VELOCITY: u32 = 1; +#[docify::export(relay_slot_duration)] /// Relay chain slot duration, in milliseconds. const RELAY_CHAIN_SLOT_DURATION_MILLIS: u32 = 6000; From 0864e27dc998507152243d5dabea06ba6f34a050 Mon Sep 17 00:00:00 2001 From: Radha Date: Fri, 3 May 2024 00:51:56 +0200 Subject: [PATCH 02/16] docify updates --- .../guides/parachains/async_backing_guide.rs | 130 ++++++++++++------ templates/parachain/node/src/service.rs | 5 + .../parachain/runtime/src/configs/mod.rs | 1 + templates/parachain/runtime/src/lib.rs | 2 + 4 files changed, 98 insertions(+), 40 deletions(-) diff --git a/docs/sdk/src/guides/parachains/async_backing_guide.rs b/docs/sdk/src/guides/parachains/async_backing_guide.rs index c1612eeeea3f..3fe73dc8392f 100644 --- a/docs/sdk/src/guides/parachains/async_backing_guide.rs +++ b/docs/sdk/src/guides/parachains/async_backing_guide.rs @@ -83,29 +83,49 @@ //! //! ## Phase 1 - Update Parachain Runtime //! -//! This phase involves configuring your parachain’s runtime to make use of async backing system. +//! This phase involves configuring your parachain’s runtime `/runtime/src/lib.rs` to make use of async backing system. //! -//! 1. Ensure constants for `capacity` and `velocity` are both set to 1 in -//! [`/runtime/src/lib.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/templates/parachain/runtime/src/lib.rs). +//! 1. Establish and ensure constants for `capacity` and `velocity` are both set to 1 in +//! `/runtime/src/lib.rs`. //! -//! Change capacity to 1 -#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", capacity)] +//! ```text +//! //!/ Maximum number of blocks simultaneously accepted by the Runtime, not yet included into the +//! //!/ relay chain. +//! pub const UNINCLUDED_SEGMENT_CAPACITY: u32 = 1; +//! //!/ How many parachain blocks are processed by the relay chain per parent. Limits the number of +//! //!/ blocks authored per slot. +//! ``` #![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", velocity)] //! -//! 2. Ensure the constant relay chain slot duration measured in milliseconds equal to `6000` in -//! [`/runtime/src/lib.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/templates/parachain/runtime/src/lib.rs). +//! 2. Establish and ensure the constant relay chain slot duration measured in milliseconds equal to `6000` in +//! `/runtime/src/lib.rs`. //! #![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", relay_slot_duration)] //! //! 3. Establish constants `MILLISECS_PER_BLOCK` and `SLOT_DURATION` if not already present in -//! [`/runtime/src/lib.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/templates/parachain/runtime/src/lib.rs). +//! `/runtime/src/lib.rs`. //! -//! Change block time to 12000 -#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", block_time)] +//! ```text +//! //!/ Change this to adjust the block time. +//! pub const MILLISECS_PER_BLOCK: u64 = 12000; +//! ``` #![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", slot_duration)] //! //! -//! 4. Configure `pallet_aura` in [`/runtime/src/configs/mod.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/templates/parachain/runtime/src/configs/mod.rs). +//! 4. Configure `cumulus_pallet_parachain_system` in `runtime/src/lib.rs` +//! +//! - Set the parachain system property `CheckAssociatedRelayNumber` to +//! `RelayNumberMonotonicallyIncreases` +//! +#![doc = docify::embed!("../../templates/parachain/runtime/src/configs/mod.rs", cumulus_parachain_config)] +//! +//! - Define a `FixedVelocityConsensusHook` using our capacity, velocity, and relay slot duration +//! constants. Use this to set the parachain system `ConsensusHook` property. +//! +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", consensus_hook)] +//! +//! +//! 5. Configure `pallet_aura` in your `runtime/src/lib.rs` or in [`/runtime/src/configs/mod.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/templates/parachain/runtime/src/configs/mod.rs). #![doc = docify::embed!("../../templates/parachain/runtime/src/configs/mod.rs", aura_config)] //! //! - Set `AllowMultipleBlocksPerSlot` to `false` (don't worry, we will set it to `true` when we @@ -113,6 +133,51 @@ //! - Ensure `pallet_aura::SlotDuration` is using the constant `SLOT_DURATION` //! //! +//! 6. Update `aura_api::SlotDuration()` to match the constant `SLOT_DURATION` +//! +//! ```text +//! impl_runtime_apis! { +//! impl sp_consensus_aura::AuraApi for Runtime { +//! fn slot_duration() -> sp_consensus_aura::SlotDuration { +//! +//! sp_consensus_aura::SlotDuration::from_millis(SLOT_DURATION) +//! } +//! +//! fn authorities() -> Vec { +//! Aura::authorities().into_inner() +//! } +//! } +//! ``` +//! +//! 7. Implement the `AuraUnincludedSegmentApi`, which allows the collator client to query its runtime +//! to determine whether it should author a block. +//! +//! - Add the dependency `cumulus-primitives-aura` to the `runtime/Cargo.toml` file for your runtime +//! +//! ```text +//! cumulus-pallet-aura-ext = { path = "../../../../pallets/aura-ext", default-features = false } +//! cumulus-pallet-parachain-system = { path = "../../../../pallets/parachain-system", default-features = false, features = ["parameterized-consensus-hook"] } +//! cumulus-pallet-session-benchmarking = { path = "../../../../pallets/session-benchmarking", default-features = false } +//! cumulus-pallet-xcm = { path = "../../../../pallets/xcm", default-features = false } +//! cumulus-pallet-xcmp-queue = { path = "../../../../pallets/xcmp-queue", default-features = false, features = ["bridging"] } +//! cumulus-primitives-aura = { path = "../../../../primitives/aura", default-features = false } +//! ``` +//! +//! - In the same file, add `"cumulus-primitives-aura/std",` to the `std` feature. +//! +//! - Inside the `impl_runtime_apis!` block for your runtime, implement the `AuraUnincludedSegmentApi` +//! as shown below. +//! +//! ```text +//! impl cumulus_primitives_aura::AuraUnincludedSegmentApi for Runtime { +//! fn can_build_upon( +//! included_hash: ::Hash, +//! slot: cumulus_primitives_aura::Slot, +//! ) -> bool { +//! ConsensusHook::can_build_upon(included_hash, slot) +//! } +//! } +//! ``` //! **Note:** With a capacity of 1 we have an effective velocity of ½ even when velocity is configured //! to some larger value. This is because capacity will be filled after a single block is produced and //! will only be freed up after that block is included on the relay chain, which takes 2 relay blocks to @@ -123,14 +188,9 @@ //! //! This phase consists of plugging in the new lookahead collator node. //! -//! 1. Import `cumulus_primitives_core::ValidationCode` to `node/src/service.rs` +//! 1. Import `cumulus_primitives_core::ValidationCode` to `node/src/service.rs`. //! -//! ```text -//! use cumulus_primitives_core::{ -//! relay_chain::{CollatorPair, ValidationCode}, -//! ParaId, -//! }; -//! ``` +#![doc = docify::embed!("../../templates/parachain/node/src/service.rs", cumulus_primitives)] //! //! 2. In `node/src/service.rs`, modify `sc_service::spawn_tasks` to use a clone of `Backend` rather //! than the original @@ -177,9 +237,7 @@ //! //! 4. In `node/src/service.rs` import the lookahead collator rather than the basic collator //! -//! ```text -//! use cumulus_client_consensus_aura::collators::lookahead::{self as aura, Params as AuraParams}; -//! ``` +#![doc = docify::embed!("../../templates/parachain/node/src/service.rs", lookahead_collator)] //! //! 5. In `start_consensus()` replace the `BasicAuraParams` struct with `AuraParams` //! - Change the struct type from `BasicAuraParams` to `AuraParams` @@ -241,28 +299,20 @@ //! //! 1. Configure `pallet_aura`, setting `AllowMultipleBlocksPerSlot` to true in `runtime/src/lib.rs`. //! -//! ```text -//! impl pallet_aura::Config for Runtime { -//! type AuthorityId = AuraId; -//! type DisabledValidators = (); -//! type MaxAuthorities = ConstU32<100_000>; -//! -//! type AllowMultipleBlocksPerSlot = ConstBool; -//! #[cfg(feature = "experimental")] -//! type SlotDuration = ConstU64; -//! } -//! ``` +#![doc = docify::embed!("../../templates/parachain/runtime/src/configs/mod.rs", aura_config)] //! //! 1. Increase the maximum `UNINCLUDED_SEGMENT_CAPACITY` in `runtime/src/lib.rs`. //! //! ```text //! //!/ Maximum number of blocks simultaneously accepted by the Runtime, not yet included into the //! //!/ relay chain. -//! pub const UNINCLUDED_SEGMENT_CAPACITY: u32 = 3; +//! ``` +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", capacity)] +//! ```text //! //!/ How many parachain blocks are processed by the relay chain per parent. Limits the number of //! //!/ blocks authored per slot. -//! pub const BLOCK_PROCESSING_VELOCITY: u32 = 1; //! ``` +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", velocity)] //! //! 3. Decrease `MILLISECS_PER_BLOCK` to 6000. //! @@ -277,18 +327,15 @@ //! //!/ up by `pallet_aura` to implement `fn slot_duration()`. //! //!/ //! //!/ Change this to adjust the block time. -//! pub const MILLISECS_PER_BLOCK: u64 = 6000; //! ``` +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", block_time)] //! //! 4. Update `MAXIMUM_BLOCK_WEIGHT` to reflect the increased time available for block production. //! //! ```text //! //!/ We allow for 2 seconds of compute with a 6 second average block. -//! pub const MAXIMUM_BLOCK_WEIGHT: Weight = Weight::from_parts( -//! WEIGHT_REF_TIME_PER_SECOND.saturating_mul(2), -//! cumulus_primitives_core::relay_chain::MAX_POV_SIZE as u64, -//! ); //! ``` +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", max_block_weight)] //! //! 5. Add a feature flagged alternative for `MinimumPeriod` in `pallet_timestamp`. The type should be //! `ConstU64<0>` with the feature flag experimental, and `ConstU64<{SLOT_DURATION / 2}>` without. @@ -315,4 +362,7 @@ //! One strategy to deal with this issue is to instead rely on relay chain block numbers for timing. //! Relay block number is kept track of by each parachain in `pallet-parachain-system` with the storage //! value `LastRelayChainBlockNumber`. This value can be obtained and used wherever timing based on -//! block number is needed. \ No newline at end of file +//! block number is needed. + +#![deny(rustdoc::broken_intra_doc_links)] +#![deny(rustdoc::private_intra_doc_links)] \ No newline at end of file diff --git a/templates/parachain/node/src/service.rs b/templates/parachain/node/src/service.rs index ad4689c6e55d..acef7487d060 100644 --- a/templates/parachain/node/src/service.rs +++ b/templates/parachain/node/src/service.rs @@ -12,6 +12,7 @@ use parachain_template_runtime::{ // Cumulus Imports use cumulus_client_collator::service::CollatorService; +#[docify::export(lookahead_collator)] use cumulus_client_consensus_aura::collators::lookahead::{self as aura, Params as AuraParams}; use cumulus_client_consensus_common::ParachainBlockImport as TParachainBlockImport; use cumulus_client_consensus_proposer::Proposer; @@ -20,6 +21,7 @@ use cumulus_client_service::{ BuildNetworkParams, CollatorSybilResistance, DARecoveryProfile, ParachainHostFunctions, StartRelayChainTasksParams, }; +#[docify::export(cumulus_primitives)] use cumulus_primitives_core::{ relay_chain::{CollatorPair, ValidationCode}, ParaId, @@ -160,6 +162,7 @@ fn build_import_queue( ) } + fn start_consensus( client: Arc, backend: Arc, @@ -194,6 +197,7 @@ fn start_consensus( client.clone(), ); + #[docify::export(aura_params)] let params = AuraParams { create_inherent_data_providers: move |_, ()| async move { Ok(()) }, block_import, @@ -317,6 +321,7 @@ pub async fn start_parachain_node( }) }; + #[docify::export(spawn_tasks)] sc_service::spawn_tasks(sc_service::SpawnTasksParams { rpc_builder, client: client.clone(), diff --git a/templates/parachain/runtime/src/configs/mod.rs b/templates/parachain/runtime/src/configs/mod.rs index 5809aed20028..7a2ded2acd81 100644 --- a/templates/parachain/runtime/src/configs/mod.rs +++ b/templates/parachain/runtime/src/configs/mod.rs @@ -184,6 +184,7 @@ parameter_types! { pub const RelayOrigin: AggregateMessageOrigin = AggregateMessageOrigin::Parent; } +#[docify::export(cumulus_parachain_config)] impl cumulus_pallet_parachain_system::Config for Runtime { type WeightInfo = (); type RuntimeEvent = RuntimeEvent; diff --git a/templates/parachain/runtime/src/lib.rs b/templates/parachain/runtime/src/lib.rs index efede2a4b44d..a09a4f225bdc 100644 --- a/templates/parachain/runtime/src/lib.rs +++ b/templates/parachain/runtime/src/lib.rs @@ -203,6 +203,7 @@ const AVERAGE_ON_INITIALIZE_RATIO: Perbill = Perbill::from_percent(5); /// `Operational` extrinsics. const NORMAL_DISPATCH_RATIO: Perbill = Perbill::from_percent(75); +#[docify::export(max_block_weight)] /// We allow for 2 seconds of compute with a 6 second average block time. const MAXIMUM_BLOCK_WEIGHT: Weight = Weight::from_parts( WEIGHT_REF_TIME_PER_SECOND.saturating_mul(2), @@ -221,6 +222,7 @@ const BLOCK_PROCESSING_VELOCITY: u32 = 1; /// Relay chain slot duration, in milliseconds. const RELAY_CHAIN_SLOT_DURATION_MILLIS: u32 = 6000; +#[docify::export(consensus_hook)] /// Aura consensus hook type ConsensusHook = cumulus_pallet_aura_ext::FixedVelocityConsensusHook< Runtime, From bbffef6e1a3acf6ead89534d4ae26a66cd1de7aa Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Sat, 25 May 2024 11:42:17 +0200 Subject: [PATCH 03/16] Improve rendering. Remove docify --- .../guides/parachains/async_backing_guide.rs | 214 ++++++++++++------ 1 file changed, 149 insertions(+), 65 deletions(-) diff --git a/docs/sdk/src/guides/parachains/async_backing_guide.rs b/docs/sdk/src/guides/parachains/async_backing_guide.rs index 3fe73dc8392f..d079f86ecb1f 100644 --- a/docs/sdk/src/guides/parachains/async_backing_guide.rs +++ b/docs/sdk/src/guides/parachains/async_backing_guide.rs @@ -87,51 +87,105 @@ //! //! 1. Establish and ensure constants for `capacity` and `velocity` are both set to 1 in //! `/runtime/src/lib.rs`. -//! -//! ```text -//! //!/ Maximum number of blocks simultaneously accepted by the Runtime, not yet included into the -//! //!/ relay chain. -//! pub const UNINCLUDED_SEGMENT_CAPACITY: u32 = 1; -//! //!/ How many parachain blocks are processed by the relay chain per parent. Limits the number of -//! //!/ blocks authored per slot. -//! ``` -#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", velocity)] //! //! 2. Establish and ensure the constant relay chain slot duration measured in milliseconds equal to `6000` in //! `/runtime/src/lib.rs`. -//! -#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", relay_slot_duration)] +//! ```rust +//! // Maximum number of blocks simultaneously accepted by the Runtime, not yet included into the +//! // relay chain. +//! pub const UNINCLUDED_SEGMENT_CAPACITY: u32 = 1; +//! // How many parachain blocks are processed by the relay chain per parent. Limits the number of +//! // blocks authored per slot. +//! pub const BLOCK_PROCESSING_VELOCITY: u32 = 1; +//! // Relay chain slot duration, in milliseconds. +//! pub const RELAY_CHAIN_SLOT_DURATION_MILLIS: u32 = 6000; +//! ``` //! //! 3. Establish constants `MILLISECS_PER_BLOCK` and `SLOT_DURATION` if not already present in //! `/runtime/src/lib.rs`. //! -//! ```text -//! //!/ Change this to adjust the block time. -//! pub const MILLISECS_PER_BLOCK: u64 = 12000; -//! ``` -#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", slot_duration)] -//! +//! ```rust +//! // BLOCKSkkhasd will be produced at a minimum duration defined by `SLOT_DURATION`. +//! // `SLOT_DURATION` is picked up by `pallet_timestamp` which is in turn picked +//! // up by `pallet_aura` to implement `fn slot_duration()`. +//! // +//! // Change this to adjust the block time. +//! pub const MILLISECS_PER_BLOCK: u64 = 12000; +//! pub const SLOT_DURATION: u64 = MILLISECS_PER_BLOCK; +//! ``` //! //! 4. Configure `cumulus_pallet_parachain_system` in `runtime/src/lib.rs` //! -//! - Set the parachain system property `CheckAssociatedRelayNumber` to -//! `RelayNumberMonotonicallyIncreases` -//! -#![doc = docify::embed!("../../templates/parachain/runtime/src/configs/mod.rs", cumulus_parachain_config)] -//! -//! - Define a `FixedVelocityConsensusHook` using our capacity, velocity, and relay slot duration -//! constants. Use this to set the parachain system `ConsensusHook` property. -//! -#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", consensus_hook)] -//! -//! -//! 5. Configure `pallet_aura` in your `runtime/src/lib.rs` or in [`/runtime/src/configs/mod.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/templates/parachain/runtime/src/configs/mod.rs). -#![doc = docify::embed!("../../templates/parachain/runtime/src/configs/mod.rs", aura_config)] -//! -//! - Set `AllowMultipleBlocksPerSlot` to `false` (don't worry, we will set it to `true` when we -//! activate async backing in phase 3). -//! - Ensure `pallet_aura::SlotDuration` is using the constant `SLOT_DURATION` +//! - Define a `FixedVelocityConsensusHook` using our capacity, velocity, and relay slot duration +//! constants. Use this to set the parachain system `ConsensusHook` property. + +//! ```rust +//! impl cumulus_pallet_parachain_system::Config for Runtime { +//! type RuntimeEvent = RuntimeEvent; +//! type OnSystemEvent = (); +//! type SelfParaId = parachain_info::Pallet; +//! type OutboundXcmpMessageSource = XcmpQueue; +//! type DmpQueue = frame_support::traits::EnqueueWithOrigin; +//! type ReservedDmpWeight = ReservedDmpWeight; +//! type XcmpMessageHandler = XcmpQueue; +//! type ReservedXcmpWeight = ReservedXcmpWeight; +//! type CheckAssociatedRelayNumber = RelayNumberMonotonicallyIncreases; +//! // here +//! type ConsensusHook = ConsensusHook; +//! type WeightInfo = weights::cumulus_pallet_parachain_system::WeightInfo; +//! } +//! // start +//! type ConsensusHook = cumulus_pallet_aura_ext::FixedVelocityConsensusHook< +//! Runtime, +//! RELAY_CHAIN_SLOT_DURATION_MILLIS, +//! BLOCK_PROCESSING_VELOCITY, +//! UNINCLUDED_SEGMENT_CAPACITY, +//! >; +//! // end +//! ``` +//! - Set the parachain system property `CheckAssociatedRelayNumber` to +//! `RelayNumberMonotonicallyIncreases` +//! +//! ```rust +//! impl cumulus_pallet_parachain_system::Config for Runtime { +//! type RuntimeEvent = RuntimeEvent; +//! type OnSystemEvent = (); +//! type SelfParaId = parachain_info::Pallet; +//! type OutboundXcmpMessageSource = XcmpQueue; +//! type DmpQueue = frame_support::traits::EnqueueWithOrigin; +//! type ReservedDmpWeight = ReservedDmpWeight; +//! type XcmpMessageHandler = XcmpQueue; +//! type ReservedXcmpWeight = ReservedXcmpWeight; +//! // here +//! type CheckAssociatedRelayNumber = RelayNumberMonotonicallyIncreases; +//! type ConsensusHook = ConsensusHook; +//! type WeightInfo = weights::cumulus_pallet_parachain_system::WeightInfo; +//! } +//! type ConsensusHook = cumulus_pallet_aura_ext::FixedVelocityConsensusHook< +//! Runtime, +//! RELAY_CHAIN_SLOT_DURATION_MILLIS, +//! BLOCK_PROCESSING_VELOCITY, +//! UNINCLUDED_SEGMENT_CAPACITY, +//! >; +//! ``` //! +//! 5. Configure `pallet_aura` in your `runtime/src/lib.rs` +//! - Set `AllowMultipleBlocksPerSlot` to `false` (don't worry, we will set it to `true` when we +//! activate async backing in phase 3). +//! - Define `pallet_aura::SlotDuration` using our constant `SLOT_DURATION` +//! +//! ```rust +//! impl pallet_aura::Config for Runtime { +//! type AuthorityId = AuraId; +//! type DisabledValidators = (); +//! type MaxAuthorities = ConstU32<100_000>; +//! // start +//! type AllowMultipleBlocksPerSlot = ConstBool; +//! #[cfg(feature = "experimental")] +//! type SlotDuration = ConstU64; +//! // highlight-end +//! } +//! ``` //! //! 6. Update `aura_api::SlotDuration()` to match the constant `SLOT_DURATION` //! @@ -154,12 +208,13 @@ //! //! - Add the dependency `cumulus-primitives-aura` to the `runtime/Cargo.toml` file for your runtime //! -//! ```text +//! ```rust //! cumulus-pallet-aura-ext = { path = "../../../../pallets/aura-ext", default-features = false } //! cumulus-pallet-parachain-system = { path = "../../../../pallets/parachain-system", default-features = false, features = ["parameterized-consensus-hook"] } //! cumulus-pallet-session-benchmarking = { path = "../../../../pallets/session-benchmarking", default-features = false } //! cumulus-pallet-xcm = { path = "../../../../pallets/xcm", default-features = false } //! cumulus-pallet-xcmp-queue = { path = "../../../../pallets/xcmp-queue", default-features = false, features = ["bridging"] } +//! // here //! cumulus-primitives-aura = { path = "../../../../primitives/aura", default-features = false } //! ``` //! @@ -168,7 +223,7 @@ //! - Inside the `impl_runtime_apis!` block for your runtime, implement the `AuraUnincludedSegmentApi` //! as shown below. //! -//! ```text +//! ```rust //! impl cumulus_primitives_aura::AuraUnincludedSegmentApi for Runtime { //! fn can_build_upon( //! included_hash: ::Hash, @@ -183,6 +238,16 @@ //! will only be freed up after that block is included on the relay chain, which takes 2 relay blocks to //! accomplish. Thus with capacity 1 and velocity 1 we get the customary 12 second parachain block time. //! +//! 8. If your `runtime/src/lib.rs` provides a `CheckInherents` type to `register_validate_block`, +//! remove it. `FixedVelocityConsensusHook` makes it unnecessary. The following example shows how +//! `register_validate_block` should look after removing `CheckInherents`. +//! +//! ```rust +//! cumulus_pallet_parachain_system::register_validate_block! { +//! Runtime = Runtime, +//! BlockExecutor = cumulus_pallet_aura_ext::BlockExecutor::, +//! } +//! ``` //! //! ## Phase 2 - Update Parachain Nodes //! @@ -190,12 +255,18 @@ //! //! 1. Import `cumulus_primitives_core::ValidationCode` to `node/src/service.rs`. //! -#![doc = docify::embed!("../../templates/parachain/node/src/service.rs", cumulus_primitives)] +//! ```rust +//! use cumulus_primitives_core::{ +//! // here +//! relay_chain::{CollatorPair, ValidationCode}, +//! ParaId, +//! }; +//! ``` //! //! 2. In `node/src/service.rs`, modify `sc_service::spawn_tasks` to use a clone of `Backend` rather //! than the original //! -//! ```text +//! ```rust //! sc_service::spawn_tasks(sc_service::SpawnTasksParams { //! rpc_builder, //! client: client.clone(), @@ -237,7 +308,9 @@ //! //! 4. In `node/src/service.rs` import the lookahead collator rather than the basic collator //! -#![doc = docify::embed!("../../templates/parachain/node/src/service.rs", lookahead_collator)] +//!```rust +//! use cumulus_client_consensus_aura::collators::lookahead::{self as aura, Params as AuraParams}; +//!``` //! //! 5. In `start_consensus()` replace the `BasicAuraParams` struct with `AuraParams` //! - Change the struct type from `BasicAuraParams` to `AuraParams` @@ -246,7 +319,7 @@ //! - Provide a `code_hash_provider` closure like that shown below //! - Increase `authoring_duration` from 500 milliseconds to 1500 //! -//! ```text +//! ```rust //! let params = AuraParams { //! create_inherent_data_providers: move |_, ()| async move { Ok(()) }, //! block_import, @@ -276,7 +349,7 @@ //! //! 6. In `start_consensus()` replace `basic_aura::run` with `aura::run` //! -//! ```text +//! ```rust //! let fut = aura::run::< //! Block, //! sp_consensus_aura::sr25519::AuthorityPair, @@ -299,20 +372,28 @@ //! //! 1. Configure `pallet_aura`, setting `AllowMultipleBlocksPerSlot` to true in `runtime/src/lib.rs`. //! -#![doc = docify::embed!("../../templates/parachain/runtime/src/configs/mod.rs", aura_config)] +//! ```rust +//! impl pallet_aura::Config for Runtime { +//! type AuthorityId = AuraId; +//! type DisabledValidators = (); +//! type MaxAuthorities = ConstU32<100_000>; +//! // here +//! type AllowMultipleBlocksPerSlot = ConstBool; +//! #[cfg(feature = "experimental")] +//! type SlotDuration = ConstU64; +//! } +//! ``` //! -//! 1. Increase the maximum `UNINCLUDED_SEGMENT_CAPACITY` in `runtime/src/lib.rs`. +//! 2. Increase the maximum `UNINCLUDED_SEGMENT_CAPACITY` in `runtime/src/lib.rs`. //! -//! ```text -//! //!/ Maximum number of blocks simultaneously accepted by the Runtime, not yet included into the -//! //!/ relay chain. +//! ```rust +//! // Maximum number of blocks simultaneously accepted by the Runtime, not yet included into the +//! // relay chain. +//! pub const UNINCLUDED_SEGMENT_CAPACITY: u32 = 3; +//! // How many parachain blocks are processed by the relay chain per parent. Limits the number of +//! // blocks authored per slot. +//! pub const BLOCK_PROCESSING_VELOCITY: u32 = 1; //! ``` -#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", capacity)] -//! ```text -//! //!/ How many parachain blocks are processed by the relay chain per parent. Limits the number of -//! //!/ blocks authored per slot. -//! ``` -#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", velocity)] //! //! 3. Decrease `MILLISECS_PER_BLOCK` to 6000. //! @@ -320,27 +401,30 @@ //! block number it may be preferable to increase velocity. Changing block time may cause //! complications, requiring additional changes. See the section “Timing by Block Number”. //! -//! ```text -//! //!/ This determines the average expected block time that we are targeting. -//! //!/ Blocks will be produced at a minimum duration defined by `SLOT_DURATION`. -//! //!/ `SLOT_DURATION` is picked up by `pallet_timestamp` which is in turn picked -//! //!/ up by `pallet_aura` to implement `fn slot_duration()`. -//! //!/ -//! //!/ Change this to adjust the block time. -//! ``` -#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", block_time)] +//! ```rust +//! // This determines the average expected block time that we are targeting. +//! // Blocks will be produced at a minimum duration defined by `SLOT_DURATION`. +//! // `SLOT_DURATION` is picked up by `pallet_timestamp` which is in turn picked +//! // up by `pallet_aura` to implement `fn slot_duration()`. +//! // +//! // Change this to adjust the block time. +//! pub const MILLISECS_PER_BLOCK: u64 = 6000; +//! ``` //! //! 4. Update `MAXIMUM_BLOCK_WEIGHT` to reflect the increased time available for block production. //! -//! ```text -//! //!/ We allow for 2 seconds of compute with a 6 second average block. +//! ```rust +//! // We allow for 2 seconds of compute with a 6 second average block. +//! pub const MAXIMUM_BLOCK_WEIGHT: Weight = Weight::from_parts( +//! WEIGHT_REF_TIME_PER_SECOND.saturating_mul(2), +//! cumulus_primitives_core::relay_chain::MAX_POV_SIZE as u64, +//! ); //! ``` -#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", max_block_weight)] //! //! 5. Add a feature flagged alternative for `MinimumPeriod` in `pallet_timestamp`. The type should be //! `ConstU64<0>` with the feature flag experimental, and `ConstU64<{SLOT_DURATION / 2}>` without. //! -//! ```text +//! ```rust //! impl pallet_timestamp::Config for Runtime { //! type Moment = u64; //! type OnTimestampSet = Aura; From a585c9f8e4eaef782e0a6c67c25d4e06881f1c5f Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Wed, 29 May 2024 08:53:58 +0200 Subject: [PATCH 04/16] Update service.rs - rm docify --- templates/parachain/node/src/service.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/templates/parachain/node/src/service.rs b/templates/parachain/node/src/service.rs index acef7487d060..7dc43d8711f1 100644 --- a/templates/parachain/node/src/service.rs +++ b/templates/parachain/node/src/service.rs @@ -12,7 +12,6 @@ use parachain_template_runtime::{ // Cumulus Imports use cumulus_client_collator::service::CollatorService; -#[docify::export(lookahead_collator)] use cumulus_client_consensus_aura::collators::lookahead::{self as aura, Params as AuraParams}; use cumulus_client_consensus_common::ParachainBlockImport as TParachainBlockImport; use cumulus_client_consensus_proposer::Proposer; @@ -21,7 +20,6 @@ use cumulus_client_service::{ BuildNetworkParams, CollatorSybilResistance, DARecoveryProfile, ParachainHostFunctions, StartRelayChainTasksParams, }; -#[docify::export(cumulus_primitives)] use cumulus_primitives_core::{ relay_chain::{CollatorPair, ValidationCode}, ParaId, From c7f7abd963e802319ee10a16b763f6c27fe04e23 Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Wed, 29 May 2024 08:55:06 +0200 Subject: [PATCH 05/16] Update service.rs rm docify --- templates/parachain/node/src/service.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/templates/parachain/node/src/service.rs b/templates/parachain/node/src/service.rs index 7dc43d8711f1..00b4054b0cea 100644 --- a/templates/parachain/node/src/service.rs +++ b/templates/parachain/node/src/service.rs @@ -195,7 +195,6 @@ fn start_consensus( client.clone(), ); - #[docify::export(aura_params)] let params = AuraParams { create_inherent_data_providers: move |_, ()| async move { Ok(()) }, block_import, @@ -319,7 +318,6 @@ pub async fn start_parachain_node( }) }; - #[docify::export(spawn_tasks)] sc_service::spawn_tasks(sc_service::SpawnTasksParams { rpc_builder, client: client.clone(), From 5c1bdeabecde0f84186f9ff619395325fa746e95 Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Wed, 29 May 2024 08:56:11 +0200 Subject: [PATCH 06/16] Update mod.rs rm docify --- templates/parachain/runtime/src/configs/mod.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/templates/parachain/runtime/src/configs/mod.rs b/templates/parachain/runtime/src/configs/mod.rs index 7a2ded2acd81..0aec332feaf6 100644 --- a/templates/parachain/runtime/src/configs/mod.rs +++ b/templates/parachain/runtime/src/configs/mod.rs @@ -184,7 +184,6 @@ parameter_types! { pub const RelayOrigin: AggregateMessageOrigin = AggregateMessageOrigin::Parent; } -#[docify::export(cumulus_parachain_config)] impl cumulus_pallet_parachain_system::Config for Runtime { type WeightInfo = (); type RuntimeEvent = RuntimeEvent; @@ -262,7 +261,6 @@ impl pallet_session::Config for Runtime { type WeightInfo = (); } -#[docify::export(aura_config)] impl pallet_aura::Config for Runtime { type AuthorityId = AuraId; type DisabledValidators = (); From 6f720602c509ff75170a85679591392aece723bb Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Wed, 29 May 2024 08:57:30 +0200 Subject: [PATCH 07/16] Update lib.rs rm docify --- templates/parachain/runtime/src/lib.rs | 7 ------- 1 file changed, 7 deletions(-) diff --git a/templates/parachain/runtime/src/lib.rs b/templates/parachain/runtime/src/lib.rs index a09a4f225bdc..179a425ca041 100644 --- a/templates/parachain/runtime/src/lib.rs +++ b/templates/parachain/runtime/src/lib.rs @@ -168,7 +168,6 @@ pub const VERSION: RuntimeVersion = RuntimeVersion { state_version: 1, }; -#[docify::export(block_time)] /// This determines the average expected block time that we are targeting. /// Blocks will be produced at a minimum duration defined by `SLOT_DURATION`. /// `SLOT_DURATION` is picked up by `pallet_timestamp` which is in turn picked @@ -177,7 +176,6 @@ pub const VERSION: RuntimeVersion = RuntimeVersion { /// Change this to adjust the block time. pub const MILLISECS_PER_BLOCK: u64 = 6000; -#[docify::export(slot_duration)] // NOTE: Currently it is not possible to change the slot duration after the chain has started. // Attempting to do so will brick block production. pub const SLOT_DURATION: u64 = MILLISECS_PER_BLOCK; @@ -203,26 +201,21 @@ const AVERAGE_ON_INITIALIZE_RATIO: Perbill = Perbill::from_percent(5); /// `Operational` extrinsics. const NORMAL_DISPATCH_RATIO: Perbill = Perbill::from_percent(75); -#[docify::export(max_block_weight)] /// We allow for 2 seconds of compute with a 6 second average block time. const MAXIMUM_BLOCK_WEIGHT: Weight = Weight::from_parts( WEIGHT_REF_TIME_PER_SECOND.saturating_mul(2), cumulus_primitives_core::relay_chain::MAX_POV_SIZE as u64, ); -#[docify::export(capacity)] /// Maximum number of blocks simultaneously accepted by the Runtime, not yet included /// into the relay chain. const UNINCLUDED_SEGMENT_CAPACITY: u32 = 3; -#[docify::export(velocity)] /// How many parachain blocks are processed by the relay chain per parent. Limits the /// number of blocks authored per slot. const BLOCK_PROCESSING_VELOCITY: u32 = 1; -#[docify::export(relay_slot_duration)] /// Relay chain slot duration, in milliseconds. const RELAY_CHAIN_SLOT_DURATION_MILLIS: u32 = 6000; -#[docify::export(consensus_hook)] /// Aura consensus hook type ConsensusHook = cumulus_pallet_aura_ext::FixedVelocityConsensusHook< Runtime, From 06ac61f2076f705394820f88b0fc3e30b57f44a9 Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Wed, 29 May 2024 08:58:01 +0200 Subject: [PATCH 08/16] Update service.rs --- templates/parachain/node/src/service.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/templates/parachain/node/src/service.rs b/templates/parachain/node/src/service.rs index 00b4054b0cea..ad4689c6e55d 100644 --- a/templates/parachain/node/src/service.rs +++ b/templates/parachain/node/src/service.rs @@ -160,7 +160,6 @@ fn build_import_queue( ) } - fn start_consensus( client: Arc, backend: Arc, From c5d5af99ce11fd3fbe458efa4aca751902580878 Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Wed, 29 May 2024 12:32:52 +0200 Subject: [PATCH 09/16] kian's feedback --- .../{parachains => }/async_backing_guide.rs | 69 +++---------------- docs/sdk/src/guides/mod.rs | 4 +- docs/sdk/src/guides/parachains/mod.rs | 7 -- 3 files changed, 13 insertions(+), 67 deletions(-) rename docs/sdk/src/guides/{parachains => }/async_backing_guide.rs (77%) delete mode 100644 docs/sdk/src/guides/parachains/mod.rs diff --git a/docs/sdk/src/guides/parachains/async_backing_guide.rs b/docs/sdk/src/guides/async_backing_guide.rs similarity index 77% rename from docs/sdk/src/guides/parachains/async_backing_guide.rs rename to docs/sdk/src/guides/async_backing_guide.rs index d079f86ecb1f..f36fc32a1913 100644 --- a/docs/sdk/src/guides/parachains/async_backing_guide.rs +++ b/docs/sdk/src/guides/async_backing_guide.rs @@ -1,65 +1,18 @@ //! # Upgrade Parachain for Asynchronous Backing Compatibility //! -//! This guide is relevant for cumulus based parachain projects started in 2023 or before. Later -//! projects should already be async backing compatible. If starting a new parachain project, please use -//! an async backing compatible template such as -//! [`cumulus/parachain-template`](https://github.com/paritytech/polkadot-sdk/tree/master/templates/parachain). +//! This guide is relevant for cumulus based parachain projects started in 2023 or before, whose backing process +//! is synchronous where parablocks can only be built on the latest Relay Chain block. Async Backing allows collators to build parablocks +//! on older Relay Chain blocks and create pipelines of multiple pending parablocks. This parallel block generation +//! increases efficiency and throughput. For more information on Async backing and its terminology, refer to the document +//! on [the Polkadot Wiki.](https://wiki.polkadot.network/docs/maintain-guides-async-backing) + +//! > If starting a new parachain project, please use +//! > an async backing compatible template such as the +//! > [parachain template](https://github.com/paritytech/polkadot-sdk/tree/master/templates/parachain). //! + //! The rollout process for Async Backing has three phases. Phases 1 and 2 below put new infrastructure -//! in place. Then we can simply turn on async backing in phase 3. But first, some pre-reqs and context -//! to set the stage. -//! ## Async Backing Prerequisites -//! -//! For more contextual information about asynchronous backing, see -//! [this page](https://wiki.polkadot.network/docs/learn-async-backing). -//! -//! Pull the latest version of Cumulus for use with your parachain. It contains necessary changes for -//! async backing compatibility. Latest on master branch of -//! [Polkadot-SDK](https://github.com/paritytech/polkadot-sdk) is currently sufficient. Any 2024 release -//! will work as well. -//! -//! ## Async Backing Terminology and Parameters -//! -//! Time for a bit of context before we get started. The following concepts will aid in demystifying the -//! collator side of Async Backing and establish a basic understanding of the changes being made: -//! -//! - **Unincluded segment** - From the perspective of a parachain block under construction, the -//! unincluded segment describes a chain of recent block ancestors which have yet to be included on -//! the relay chain. The ability to build new blocks on top of the unincluded segment rather than on -//! top of blocks freshly included in the relay chain is the core of asynchronous backing. -//! - **Capacity** - The maximum size of the unincluded segment. The longer this is, the farther ahead a -//! parachain can work, producing new candidates before the ancestors of those candidates have been -//! seen as included on-chain. Practically, a capacity of 2-3 is sufficient to realize the full -//! benefits of asynchronous backing, at least until the release of elastic scaling. -//! - **Velocity** - The base rate at which a parachain should produce blocks. A velocity of 1 indicates -//! that 1 parachain block should be produced per relay chain block. In order to fill the unincluded -//! segment with candidates, collators may build up to `Velocity + 1` candidates per aura slot while -//! there is remaining capacity. When elastic scaling has been released velocities greater than 1 will -//! be supported. -//! - **AllowMultipleBlocksPerSlot** - If this is `true`, Aura will allow slots to stay the same across -//! sequential parablocks. Otherwise the slot number must increase with each block. To fill the -//! unincluded segment as described above we need this to be `true`. -//! - **FixedVelocityConsensusHook** - This is a variety of `ConsensusHook` intended to be passed to -//! `parachain-system` as part of its `Config`. It is triggered on initialization of a new runtime. An -//! instance of `FixedVelocityConsensusHook` is defined with both a fixed capacity and velocity. It -//! aborts the runtime early if either capacity or velocity is exceeded, as the collator shouldn’t be -//! creating additional blocks in that case. -//! - **AsyncBackingParams.max_candidate_depth** - This parameter determines the maximum unincluded -//! segment depth the relay chain will support. Candidates sent to validators which exceed -//! `max_candidate_depth` will be ignored. `Capacity`, as mentioned above, should not exceed -//! `max_candidate_depth`. -//! - **AsyncBackingParams.allowed_ancestry_len** - Each parachain block candidate has a `relay_parent` -//! from which its execution and validation context is derived. Before async backing the -//! `relay_parent` for a candidate not yet backed was required to be the fresh head of a fork. With -//! async backing we can relax this requirement. Instead we set a conservative maximum age in blocks -//! for the `relay_parent`s of candidates in the unincluded segment. This age, `allowed_ancestry_len` -//! lives on the relay chain and is queried by parachains when deciding which block to build on top -//! of. -//! - **Lookahead Collator** - A collator for Aura that looks ahead of the most recently included -//! parachain block when determining what to build upon. This collator also builds additional blocks -//! when the maximum backlog is not saturated. The size of the backlog is determined by invoking the -//! AuraUnincludedSegmentApi. If that runtime API is not supported, this assumes a maximum backlog -//! size of 1. +//! in place. Then we can simply turn on async backing in phase 3. //! //! ## Prerequisite //! diff --git a/docs/sdk/src/guides/mod.rs b/docs/sdk/src/guides/mod.rs index 0e2c6681561d..ec01c6ad846c 100644 --- a/docs/sdk/src/guides/mod.rs +++ b/docs/sdk/src/guides/mod.rs @@ -27,5 +27,5 @@ pub mod xcm_enabled_parachain; /// How to enable storage weight reclaiming in a parachain node and runtime. pub mod enable_pov_reclaim; -/// Parachain guides -pub mod parachains; \ No newline at end of file +/// How to enable Async Backing on parachain projects that started in 2023 or before. +pub mod async_backing_guide; \ No newline at end of file diff --git a/docs/sdk/src/guides/parachains/mod.rs b/docs/sdk/src/guides/parachains/mod.rs deleted file mode 100644 index 6f6e53b02088..000000000000 --- a/docs/sdk/src/guides/parachains/mod.rs +++ /dev/null @@ -1,7 +0,0 @@ -//! # Polkadot SDK Docs - Parachain Guides -//! -//! This crate contains a collection of guides for developers and maintainers of parachains built -//! with Polkadot SDK. - -/// Upgrade Parachain for Asynchronous Backing Compatibility -pub mod async_backing_guide; \ No newline at end of file From e3228c9899c3620298f8101540ae38e0d74b16c1 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Fri, 31 May 2024 11:31:37 +0800 Subject: [PATCH 10/16] feedback and ideas --- docs/sdk/src/guides/async_backing_guide.rs | 293 ++++++++------------- templates/parachain/runtime/src/apis.rs | 20 +- templates/parachain/runtime/src/lib.rs | 47 ++-- 3 files changed, 154 insertions(+), 206 deletions(-) diff --git a/docs/sdk/src/guides/async_backing_guide.rs b/docs/sdk/src/guides/async_backing_guide.rs index f36fc32a1913..b0a1bec3983b 100644 --- a/docs/sdk/src/guides/async_backing_guide.rs +++ b/docs/sdk/src/guides/async_backing_guide.rs @@ -1,18 +1,18 @@ //! # Upgrade Parachain for Asynchronous Backing Compatibility //! -//! This guide is relevant for cumulus based parachain projects started in 2023 or before, whose backing process -//! is synchronous where parablocks can only be built on the latest Relay Chain block. Async Backing allows collators to build parablocks -//! on older Relay Chain blocks and create pipelines of multiple pending parablocks. This parallel block generation -//! increases efficiency and throughput. For more information on Async backing and its terminology, refer to the document +//! This guide is relevant for cumulus based parachain projects started in 2023 or before, whose +//! backing process is synchronous where parablocks can only be built on the latest Relay Chain +//! block. Async Backing allows collators to build parablocks on older Relay Chain blocks and create +//! pipelines of multiple pending parablocks. This parallel block generation increases efficiency +//! and throughput. For more information on Async backing and its terminology, refer to the document //! on [the Polkadot Wiki.](https://wiki.polkadot.network/docs/maintain-guides-async-backing) - -//! > If starting a new parachain project, please use -//! > an async backing compatible template such as the +//! +//! > If starting a new parachain project, please use an async backing compatible template such as +//! > the //! > [parachain template](https://github.com/paritytech/polkadot-sdk/tree/master/templates/parachain). //! - -//! The rollout process for Async Backing has three phases. Phases 1 and 2 below put new infrastructure -//! in place. Then we can simply turn on async backing in phase 3. +//! The rollout process for Async Backing has three phases. Phases 1 and 2 below put new +//! infrastructure in place. Then we can simply turn on async backing in phase 3. //! //! ## Prerequisite //! @@ -28,177 +28,110 @@ //! "scheduling_lookahead": 2 //! ``` //! -//!
`scheduling_lookahead` must be set to 2, otherwise parachain block times will degrade to worse than with sync backing!
-//! -//! -//! -//! +//!
`scheduling_lookahead` must be set to 2, otherwise parachain block times +//! will degrade to worse than with sync backing!
//! //! ## Phase 1 - Update Parachain Runtime //! -//! This phase involves configuring your parachain’s runtime `/runtime/src/lib.rs` to make use of async backing system. -//! -//! 1. Establish and ensure constants for `capacity` and `velocity` are both set to 1 in -//! `/runtime/src/lib.rs`. -//! -//! 2. Establish and ensure the constant relay chain slot duration measured in milliseconds equal to `6000` in -//! `/runtime/src/lib.rs`. -//! ```rust -//! // Maximum number of blocks simultaneously accepted by the Runtime, not yet included into the -//! // relay chain. -//! pub const UNINCLUDED_SEGMENT_CAPACITY: u32 = 1; -//! // How many parachain blocks are processed by the relay chain per parent. Limits the number of -//! // blocks authored per slot. -//! pub const BLOCK_PROCESSING_VELOCITY: u32 = 1; -//! // Relay chain slot duration, in milliseconds. -//! pub const RELAY_CHAIN_SLOT_DURATION_MILLIS: u32 = 6000; -//! ``` +//! This phase involves configuring your parachain’s runtime `/runtime/src/lib.rs` to make use of +//! async backing system. //! -//! 3. Establish constants `MILLISECS_PER_BLOCK` and `SLOT_DURATION` if not already present in -//! `/runtime/src/lib.rs`. +//! 1. Establish and ensure constants for `capacity` and `velocity` are both set to 1 in the +//! runtime. +//! 2. Establish and ensure the constant relay chain slot duration measured in milliseconds equal to +//! `6000` in the runtime. +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", async_backing_params)] //! -//! ```rust -//! // BLOCKSkkhasd will be produced at a minimum duration defined by `SLOT_DURATION`. -//! // `SLOT_DURATION` is picked up by `pallet_timestamp` which is in turn picked -//! // up by `pallet_aura` to implement `fn slot_duration()`. -//! // -//! // Change this to adjust the block time. -//! pub const MILLISECS_PER_BLOCK: u64 = 12000; -//! pub const SLOT_DURATION: u64 = MILLISECS_PER_BLOCK; -//! ``` +//! 3. Establish constants `MILLISECS_PER_BLOCK` and `SLOT_DURATION` if not already present in the +//! runtime. +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", block_times)] //! -//! 4. Configure `cumulus_pallet_parachain_system` in `runtime/src/lib.rs` +//! 4. Configure `cumulus_pallet_parachain_system` in the runtime. //! //! - Define a `FixedVelocityConsensusHook` using our capacity, velocity, and relay slot duration //! constants. Use this to set the parachain system `ConsensusHook` property. - +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", ConsensusHook)] //! ```rust //! impl cumulus_pallet_parachain_system::Config for Runtime { -//! type RuntimeEvent = RuntimeEvent; -//! type OnSystemEvent = (); -//! type SelfParaId = parachain_info::Pallet; -//! type OutboundXcmpMessageSource = XcmpQueue; -//! type DmpQueue = frame_support::traits::EnqueueWithOrigin; -//! type ReservedDmpWeight = ReservedDmpWeight; -//! type XcmpMessageHandler = XcmpQueue; -//! type ReservedXcmpWeight = ReservedXcmpWeight; -//! type CheckAssociatedRelayNumber = RelayNumberMonotonicallyIncreases; -//! // here -//! type ConsensusHook = ConsensusHook; -//! type WeightInfo = weights::cumulus_pallet_parachain_system::WeightInfo; +//! .. +//! type ConsensusHook = ConsensusHook; +//! .. //! } -//! // start -//! type ConsensusHook = cumulus_pallet_aura_ext::FixedVelocityConsensusHook< -//! Runtime, -//! RELAY_CHAIN_SLOT_DURATION_MILLIS, -//! BLOCK_PROCESSING_VELOCITY, -//! UNINCLUDED_SEGMENT_CAPACITY, -//! >; -//! // end -//! ``` +//! //! - Set the parachain system property `CheckAssociatedRelayNumber` to //! `RelayNumberMonotonicallyIncreases` -//! -//! ```rust +//! ```ignore //! impl cumulus_pallet_parachain_system::Config for Runtime { -//! type RuntimeEvent = RuntimeEvent; -//! type OnSystemEvent = (); -//! type SelfParaId = parachain_info::Pallet; -//! type OutboundXcmpMessageSource = XcmpQueue; -//! type DmpQueue = frame_support::traits::EnqueueWithOrigin; -//! type ReservedDmpWeight = ReservedDmpWeight; -//! type XcmpMessageHandler = XcmpQueue; -//! type ReservedXcmpWeight = ReservedXcmpWeight; -//! // here -//! type CheckAssociatedRelayNumber = RelayNumberMonotonicallyIncreases; -//! type ConsensusHook = ConsensusHook; -//! type WeightInfo = weights::cumulus_pallet_parachain_system::WeightInfo; +//! .. +//! type CheckAssociatedRelayNumber = RelayNumberMonotonicallyIncreases; +//! .. //! } -//! type ConsensusHook = cumulus_pallet_aura_ext::FixedVelocityConsensusHook< -//! Runtime, -//! RELAY_CHAIN_SLOT_DURATION_MILLIS, -//! BLOCK_PROCESSING_VELOCITY, -//! UNINCLUDED_SEGMENT_CAPACITY, -//! >; //! ``` +//! +//! 5. Configure `pallet_aura` in the runtime. //! -//! 5. Configure `pallet_aura` in your `runtime/src/lib.rs` //! - Set `AllowMultipleBlocksPerSlot` to `false` (don't worry, we will set it to `true` when we //! activate async backing in phase 3). -//! - Define `pallet_aura::SlotDuration` using our constant `SLOT_DURATION` //! -//! ```rust +//! - Define `pallet_aura::SlotDuration` using our constant `SLOT_DURATION` +//! ```ignore //! impl pallet_aura::Config for Runtime { -//! type AuthorityId = AuraId; -//! type DisabledValidators = (); -//! type MaxAuthorities = ConstU32<100_000>; -//! // start -//! type AllowMultipleBlocksPerSlot = ConstBool; -//! #[cfg(feature = "experimental")] -//! type SlotDuration = ConstU64; -//! // highlight-end +//! .. +//! type AllowMultipleBlocksPerSlot = ConstBool; +//! #[cfg(feature = "experimental")] +//! type SlotDuration = ConstU64; +//! .. //! } //! ``` +//! +//! // TODO Radha: example of how to better link to real items. See more in https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/DOCUMENTATION_GUIDELINES.md#how-to-document +//! 6. Update [`sp_consensus_aura::AuraApi::slot_duration`] in [`sp_api::impl_runtime_apis`] to match the constant `SLOT_DURATION` +#![doc = docify::embed!("../../templates/parachain/runtime/src/apis.rs", impl_slot_duration)] //! -//! 6. Update `aura_api::SlotDuration()` to match the constant `SLOT_DURATION` -//! -//! ```text -//! impl_runtime_apis! { -//! impl sp_consensus_aura::AuraApi for Runtime { -//! fn slot_duration() -> sp_consensus_aura::SlotDuration { -//! -//! sp_consensus_aura::SlotDuration::from_millis(SLOT_DURATION) -//! } -//! -//! fn authorities() -> Vec { -//! Aura::authorities().into_inner() -//! } -//! } -//! ``` -//! -//! 7. Implement the `AuraUnincludedSegmentApi`, which allows the collator client to query its runtime -//! to determine whether it should author a block. -//! -//! - Add the dependency `cumulus-primitives-aura` to the `runtime/Cargo.toml` file for your runtime +//! 7. Implement the `AuraUnincludedSegmentApi`, which allows the collator client to query its +//! runtime to determine whether it should author a block. //! +//! - Add the dependency `cumulus-primitives-aura` to the `runtime/Cargo.toml` file for your +//! runtime //! ```rust //! cumulus-pallet-aura-ext = { path = "../../../../pallets/aura-ext", default-features = false } -//! cumulus-pallet-parachain-system = { path = "../../../../pallets/parachain-system", default-features = false, features = ["parameterized-consensus-hook"] } -//! cumulus-pallet-session-benchmarking = { path = "../../../../pallets/session-benchmarking", default-features = false } -//! cumulus-pallet-xcm = { path = "../../../../pallets/xcm", default-features = false } -//! cumulus-pallet-xcmp-queue = { path = "../../../../pallets/xcmp-queue", default-features = false, features = ["bridging"] } -//! // here +//! cumulus-pallet-parachain-system = { path = "../../../../pallets/parachain-system", +//! default-features = false, features = ["parameterized-consensus-hook"] } +//! cumulus-pallet-session-benchmarking = { path = "../../../../pallets/session-benchmarking", +//! default-features = false } cumulus-pallet-xcm = { path = "../../../../pallets/xcm", +//! default-features = false } cumulus-pallet-xcmp-queue = { path = +//! "../../../../pallets/xcmp-queue", default-features = false, features = ["bridging"] } // here //! cumulus-primitives-aura = { path = "../../../../primitives/aura", default-features = false } //! ``` //! //! - In the same file, add `"cumulus-primitives-aura/std",` to the `std` feature. //! -//! - Inside the `impl_runtime_apis!` block for your runtime, implement the `AuraUnincludedSegmentApi` -//! as shown below. -//! +//! - Inside the `impl_runtime_apis!` block for your runtime, implement the +//! `AuraUnincludedSegmentApi` as shown below. //! ```rust //! impl cumulus_primitives_aura::AuraUnincludedSegmentApi for Runtime { -//! fn can_build_upon( -//! included_hash: ::Hash, -//! slot: cumulus_primitives_aura::Slot, -//! ) -> bool { -//! ConsensusHook::can_build_upon(included_hash, slot) -//! } +//! fn can_build_upon( +//! included_hash: ::Hash, +//! slot: cumulus_primitives_aura::Slot, +//! ) -> bool { +//! ConsensusHook::can_build_upon(included_hash, slot) +//! } //! } //! ``` -//! **Note:** With a capacity of 1 we have an effective velocity of ½ even when velocity is configured -//! to some larger value. This is because capacity will be filled after a single block is produced and -//! will only be freed up after that block is included on the relay chain, which takes 2 relay blocks to -//! accomplish. Thus with capacity 1 and velocity 1 we get the customary 12 second parachain block time. +//! +//! **Note:** With a capacity of 1 we have an effective velocity of ½ even when velocity is +//! configured to some larger value. This is because capacity will be filled after a single block is +//! produced and will only be freed up after that block is included on the relay chain, which takes +//! 2 relay blocks to accomplish. Thus with capacity 1 and velocity 1 we get the customary 12 second +//! parachain block time. //! //! 8. If your `runtime/src/lib.rs` provides a `CheckInherents` type to `register_validate_block`, //! remove it. `FixedVelocityConsensusHook` makes it unnecessary. The following example shows how //! `register_validate_block` should look after removing `CheckInherents`. -//! //! ```rust //! cumulus_pallet_parachain_system::register_validate_block! { -//! Runtime = Runtime, -//! BlockExecutor = cumulus_pallet_aura_ext::BlockExecutor::, +//! Runtime = Runtime, +//! BlockExecutor = cumulus_pallet_aura_ext::BlockExecutor::, //! } //! ``` //! @@ -207,63 +140,58 @@ //! This phase consists of plugging in the new lookahead collator node. //! //! 1. Import `cumulus_primitives_core::ValidationCode` to `node/src/service.rs`. -//! //! ```rust //! use cumulus_primitives_core::{ //! // here -//! relay_chain::{CollatorPair, ValidationCode}, -//! ParaId, +//! relay_chain::{CollatorPair, ValidationCode}, +//! ParaId, //! }; //! ``` //! //! 2. In `node/src/service.rs`, modify `sc_service::spawn_tasks` to use a clone of `Backend` rather //! than the original -//! //! ```rust //! sc_service::spawn_tasks(sc_service::SpawnTasksParams { -//! rpc_builder, -//! client: client.clone(), -//! transaction_pool: transaction_pool.clone(), -//! task_manager: &mut task_manager, -//! config: parachain_config, -//! keystore: params.keystore_container.keystore(), -//! backend: backend.clone(), -//! network: network.clone(), -//! sync_service: sync_service.clone(), -//! system_rpc_tx, -//! tx_handler_controller, -//! telemetry: telemetry.as_mut(), +//! rpc_builder, +//! client: client.clone(), +//! transaction_pool: transaction_pool.clone(), +//! task_manager: &mut task_manager, +//! config: parachain_config, +//! keystore: params.keystore_container.keystore(), +//! backend: backend.clone(), +//! network: network.clone(), +//! sync_service: sync_service.clone(), +//! system_rpc_tx, +//! tx_handler_controller, +//! telemetry: telemetry.as_mut(), //! })?; //! ``` //! //! 3. Add `backend` as a parameter to `start_consensus()` in `node/src/service.rs` -//! //! ```text //! fn start_consensus( //! client: Arc, -//! +//! //! backend: Arc, //! block_import: ParachainBlockImport, //! prometheus_registry: Option<&Registry>, //! telemetry: Option, //! task_manager: &TaskManager, //! ``` -//! //! ```text //! if validator { //! start_consensus( //! client.clone(), -//! +//! //! backend.clone(), //! block_import, //! prometheus_registry.as_ref(), //! ``` //! //! 4. In `node/src/service.rs` import the lookahead collator rather than the basic collator -//! -//!```rust +//! ```rust //! use cumulus_client_consensus_aura::collators::lookahead::{self as aura, Params as AuraParams}; -//!``` +//! ``` //! //! 5. In `start_consensus()` replace the `BasicAuraParams` struct with `AuraParams` //! - Change the struct type from `BasicAuraParams` to `AuraParams` @@ -271,7 +199,6 @@ //! - Add a `para_backend` parameter after `para_client`, passing in our para backend //! - Provide a `code_hash_provider` closure like that shown below //! - Increase `authoring_duration` from 500 milliseconds to 1500 -//! //! ```rust //! let params = AuraParams { //! create_inherent_data_providers: move |_, ()| async move { Ok(()) }, @@ -290,18 +217,17 @@ //! relay_chain_slot_duration, //! proposer, //! collator_service, -//! +//! //! authoring_duration: Duration::from_millis(1500), //! reinitialize: false, //! }; //! ``` //! -//! **Note:** Set `authoring_duration` to whatever you want, taking your own hardware into account. But -//! if the backer who should be slower than you due to reading from disk, times out at two seconds your -//! candidates will be rejected. +//! **Note:** Set `authoring_duration` to whatever you want, taking your own hardware into account. +//! But if the backer who should be slower than you due to reading from disk, times out at two +//! seconds your candidates will be rejected. //! //! 6. In `start_consensus()` replace `basic_aura::run` with `aura::run` -//! //! ```rust //! let fut = aura::run::< //! Block, @@ -323,8 +249,8 @@ //! //! This phase consists of changes to your parachain’s runtime that activate async backing feature. //! -//! 1. Configure `pallet_aura`, setting `AllowMultipleBlocksPerSlot` to true in `runtime/src/lib.rs`. -//! +//! 1. Configure `pallet_aura`, setting `AllowMultipleBlocksPerSlot` to true in +//! `runtime/src/lib.rs`. //! ```rust //! impl pallet_aura::Config for Runtime { //! type AuthorityId = AuraId; @@ -338,7 +264,6 @@ //! ``` //! //! 2. Increase the maximum `UNINCLUDED_SEGMENT_CAPACITY` in `runtime/src/lib.rs`. -//! //! ```rust //! // Maximum number of blocks simultaneously accepted by the Runtime, not yet included into the //! // relay chain. @@ -350,10 +275,9 @@ //! //! 3. Decrease `MILLISECS_PER_BLOCK` to 6000. //! -//! - Note: For a parachain which measures time in terms of its own block number rather than by relay -//! block number it may be preferable to increase velocity. Changing block time may cause +//! - Note: For a parachain which measures time in terms of its own block number rather than by +//! relay block number it may be preferable to increase velocity. Changing block time may cause //! complications, requiring additional changes. See the section “Timing by Block Number”. -//! //! ```rust //! // This determines the average expected block time that we are targeting. //! // Blocks will be produced at a minimum duration defined by `SLOT_DURATION`. @@ -365,7 +289,6 @@ //! ``` //! //! 4. Update `MAXIMUM_BLOCK_WEIGHT` to reflect the increased time available for block production. -//! //! ```rust //! // We allow for 2 seconds of compute with a 6 second average block. //! pub const MAXIMUM_BLOCK_WEIGHT: Weight = Weight::from_parts( @@ -374,9 +297,9 @@ //! ); //! ``` //! -//! 5. Add a feature flagged alternative for `MinimumPeriod` in `pallet_timestamp`. The type should be -//! `ConstU64<0>` with the feature flag experimental, and `ConstU64<{SLOT_DURATION / 2}>` without. -//! +//! 5. Add a feature flagged alternative for `MinimumPeriod` in `pallet_timestamp`. The type should +//! be `ConstU64<0>` with the feature flag experimental, and `ConstU64<{SLOT_DURATION / 2}>` +//! without. //! ```rust //! impl pallet_timestamp::Config for Runtime { //! type Moment = u64; @@ -391,15 +314,15 @@ //! //! ## Timing by Block Number //! -//! With asynchronous backing it will be possible for parachains to opt for a block time of 6 seconds -//! rather than 12 seconds. But modifying block duration isn’t so simple for a parachain which was -//! measuring time in terms of its own block number. It could result in expected and actual time not -//! matching up, stalling the parachain. +//! With asynchronous backing it will be possible for parachains to opt for a block time of 6 +//! seconds rather than 12 seconds. But modifying block duration isn’t so simple for a parachain +//! which was measuring time in terms of its own block number. It could result in expected and +//! actual time not matching up, stalling the parachain. //! //! One strategy to deal with this issue is to instead rely on relay chain block numbers for timing. -//! Relay block number is kept track of by each parachain in `pallet-parachain-system` with the storage -//! value `LastRelayChainBlockNumber`. This value can be obtained and used wherever timing based on -//! block number is needed. +//! Relay block number is kept track of by each parachain in `pallet-parachain-system` with the +//! storage value `LastRelayChainBlockNumber`. This value can be obtained and used wherever timing +//! based on block number is needed. #![deny(rustdoc::broken_intra_doc_links)] -#![deny(rustdoc::private_intra_doc_links)] \ No newline at end of file +#![deny(rustdoc::private_intra_doc_links)] diff --git a/templates/parachain/runtime/src/apis.rs b/templates/parachain/runtime/src/apis.rs index 107956ded410..f32b4dbe66a5 100644 --- a/templates/parachain/runtime/src/apis.rs +++ b/templates/parachain/runtime/src/apis.rs @@ -47,10 +47,26 @@ use super::{ SLOT_DURATION, VERSION, }; +// we move some impls outside so we can easily use them with `docify`. +impl Runtime { + #[docify::export] + fn impl_slot_duration() -> sp_consensus_aura::SlotDuration { + sp_consensus_aura::SlotDuration::from_millis(SLOT_DURATION) + } + + #[docify::export] + fn impl_can_build_upon( + included_hash: ::Hash, + slot: cumulus_primitives_aura::Slot, + ) -> bool { + ConsensusHook::can_build_upon(included_hash, slot) + } +} + impl_runtime_apis! { impl sp_consensus_aura::AuraApi for Runtime { fn slot_duration() -> sp_consensus_aura::SlotDuration { - sp_consensus_aura::SlotDuration::from_millis(SLOT_DURATION) + Runtime::impl_slot_duration() } fn authorities() -> Vec { @@ -63,7 +79,7 @@ impl_runtime_apis! { included_hash: ::Hash, slot: cumulus_primitives_aura::Slot, ) -> bool { - ConsensusHook::can_build_upon(included_hash, slot) + Runtime::impl_can_build_upon() } } diff --git a/templates/parachain/runtime/src/lib.rs b/templates/parachain/runtime/src/lib.rs index 179a425ca041..0e280efc4126 100644 --- a/templates/parachain/runtime/src/lib.rs +++ b/templates/parachain/runtime/src/lib.rs @@ -168,17 +168,21 @@ pub const VERSION: RuntimeVersion = RuntimeVersion { state_version: 1, }; -/// This determines the average expected block time that we are targeting. -/// Blocks will be produced at a minimum duration defined by `SLOT_DURATION`. -/// `SLOT_DURATION` is picked up by `pallet_timestamp` which is in turn picked -/// up by `pallet_aura` to implement `fn slot_duration()`. -/// -/// Change this to adjust the block time. -pub const MILLISECS_PER_BLOCK: u64 = 6000; - -// NOTE: Currently it is not possible to change the slot duration after the chain has started. -// Attempting to do so will brick block production. -pub const SLOT_DURATION: u64 = MILLISECS_PER_BLOCK; +#[docify::export] +mod block_times { + /// This determines the average expected block time that we are targeting. Blocks will be + /// produced at a minimum duration defined by `SLOT_DURATION`. `SLOT_DURATION` is picked up by + /// `pallet_timestamp` which is in turn picked up by `pallet_aura` to implement `fn + /// slot_duration()`. + /// + /// Change this to adjust the block time. + pub const MILLISECS_PER_BLOCK: u64 = 6000; + + // NOTE: Currently it is not possible to change the slot duration after the chain has started. + // Attempting to do so will brick block production. + pub const SLOT_DURATION: u64 = MILLISECS_PER_BLOCK; +} +pub use block_times::*; // Time is measured by number of blocks. pub const MINUTES: BlockNumber = 60_000 / (MILLISECS_PER_BLOCK as BlockNumber); @@ -207,15 +211,20 @@ const MAXIMUM_BLOCK_WEIGHT: Weight = Weight::from_parts( cumulus_primitives_core::relay_chain::MAX_POV_SIZE as u64, ); -/// Maximum number of blocks simultaneously accepted by the Runtime, not yet included -/// into the relay chain. -const UNINCLUDED_SEGMENT_CAPACITY: u32 = 3; -/// How many parachain blocks are processed by the relay chain per parent. Limits the -/// number of blocks authored per slot. -const BLOCK_PROCESSING_VELOCITY: u32 = 1; -/// Relay chain slot duration, in milliseconds. -const RELAY_CHAIN_SLOT_DURATION_MILLIS: u32 = 6000; +#[docify::export] +mod async_backing_params { + /// Maximum number of blocks simultaneously accepted by the Runtime, not yet included + /// into the relay chain. + pub(crate) const UNINCLUDED_SEGMENT_CAPACITY: u32 = 3; + /// How many parachain blocks are processed by the relay chain per parent. Limits the + /// number of blocks authored per slot. + pub(crate) const BLOCK_PROCESSING_VELOCITY: u32 = 1; + /// Relay chain slot duration, in milliseconds. + pub(crate) const RELAY_CHAIN_SLOT_DURATION_MILLIS: u32 = 6000; +} +pub(crate) use async_backing_params::*; +#[docify::export] /// Aura consensus hook type ConsensusHook = cumulus_pallet_aura_ext::FixedVelocityConsensusHook< Runtime, From 0f526e6ca4bee6d0f904c1c61f57c583fd8636fe Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Thu, 13 Jun 2024 17:21:12 +0800 Subject: [PATCH 11/16] Async Backing Phase 1 Docify --- docs/sdk/src/guides/async_backing_guide.rs | 228 +-------------------- templates/parachain/runtime/src/lib.rs | 1 + 2 files changed, 10 insertions(+), 219 deletions(-) diff --git a/docs/sdk/src/guides/async_backing_guide.rs b/docs/sdk/src/guides/async_backing_guide.rs index b0a1bec3983b..ddae6161f3f4 100644 --- a/docs/sdk/src/guides/async_backing_guide.rs +++ b/docs/sdk/src/guides/async_backing_guide.rs @@ -10,7 +10,6 @@ //! > If starting a new parachain project, please use an async backing compatible template such as //! > the //! > [parachain template](https://github.com/paritytech/polkadot-sdk/tree/master/templates/parachain). -//! //! The rollout process for Async Backing has three phases. Phases 1 and 2 below put new //! infrastructure in place. Then we can simply turn on async backing in phase 3. //! @@ -57,7 +56,7 @@ //! type ConsensusHook = ConsensusHook; //! .. //! } -//! +//! ``` //! - Set the parachain system property `CheckAssociatedRelayNumber` to //! `RelayNumberMonotonicallyIncreases` //! ```ignore @@ -83,41 +82,26 @@ //! .. //! } //! ``` -//! -//! // TODO Radha: example of how to better link to real items. See more in https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/DOCUMENTATION_GUIDELINES.md#how-to-document -//! 6. Update [`sp_consensus_aura::AuraApi::slot_duration`] in [`sp_api::impl_runtime_apis`] to match the constant `SLOT_DURATION` -#![doc = docify::embed!("../../templates/parachain/runtime/src/apis.rs", impl_slot_duration)] //! +//! 6. Update `sp_consensus_aura::AuraApi::slot_duration` in `sp_api::impl_runtime_apis` to match the constant `SLOT_DURATION` +#![doc = docify::embed!("../../templates/parachain/runtime/src/apis.rs", impl_slot_duration)] +//! //! 7. Implement the `AuraUnincludedSegmentApi`, which allows the collator client to query its //! runtime to determine whether it should author a block. //! //! - Add the dependency `cumulus-primitives-aura` to the `runtime/Cargo.toml` file for your //! runtime //! ```rust -//! cumulus-pallet-aura-ext = { path = "../../../../pallets/aura-ext", default-features = false } -//! cumulus-pallet-parachain-system = { path = "../../../../pallets/parachain-system", -//! default-features = false, features = ["parameterized-consensus-hook"] } -//! cumulus-pallet-session-benchmarking = { path = "../../../../pallets/session-benchmarking", -//! default-features = false } cumulus-pallet-xcm = { path = "../../../../pallets/xcm", -//! default-features = false } cumulus-pallet-xcmp-queue = { path = -//! "../../../../pallets/xcmp-queue", default-features = false, features = ["bridging"] } // here +//! .. //! cumulus-primitives-aura = { path = "../../../../primitives/aura", default-features = false } +//! .. //! ``` //! //! - In the same file, add `"cumulus-primitives-aura/std",` to the `std` feature. //! //! - Inside the `impl_runtime_apis!` block for your runtime, implement the -//! `AuraUnincludedSegmentApi` as shown below. -//! ```rust -//! impl cumulus_primitives_aura::AuraUnincludedSegmentApi for Runtime { -//! fn can_build_upon( -//! included_hash: ::Hash, -//! slot: cumulus_primitives_aura::Slot, -//! ) -> bool { -//! ConsensusHook::can_build_upon(included_hash, slot) -//! } -//! } -//! ``` +//! `cumulus_primitives_aura::AuraUnincludedSegmentApi` as shown below. +#![doc = docify::embed!("../../templates/parachain/runtime/src/apis.rs", impl_can_build_upon)] //! //! **Note:** With a capacity of 1 we have an effective velocity of ½ even when velocity is //! configured to some larger value. This is because capacity will be filled after a single block is @@ -128,201 +112,7 @@ //! 8. If your `runtime/src/lib.rs` provides a `CheckInherents` type to `register_validate_block`, //! remove it. `FixedVelocityConsensusHook` makes it unnecessary. The following example shows how //! `register_validate_block` should look after removing `CheckInherents`. -//! ```rust -//! cumulus_pallet_parachain_system::register_validate_block! { -//! Runtime = Runtime, -//! BlockExecutor = cumulus_pallet_aura_ext::BlockExecutor::, -//! } -//! ``` -//! -//! ## Phase 2 - Update Parachain Nodes -//! -//! This phase consists of plugging in the new lookahead collator node. -//! -//! 1. Import `cumulus_primitives_core::ValidationCode` to `node/src/service.rs`. -//! ```rust -//! use cumulus_primitives_core::{ -//! // here -//! relay_chain::{CollatorPair, ValidationCode}, -//! ParaId, -//! }; -//! ``` -//! -//! 2. In `node/src/service.rs`, modify `sc_service::spawn_tasks` to use a clone of `Backend` rather -//! than the original -//! ```rust -//! sc_service::spawn_tasks(sc_service::SpawnTasksParams { -//! rpc_builder, -//! client: client.clone(), -//! transaction_pool: transaction_pool.clone(), -//! task_manager: &mut task_manager, -//! config: parachain_config, -//! keystore: params.keystore_container.keystore(), -//! backend: backend.clone(), -//! network: network.clone(), -//! sync_service: sync_service.clone(), -//! system_rpc_tx, -//! tx_handler_controller, -//! telemetry: telemetry.as_mut(), -//! })?; -//! ``` -//! -//! 3. Add `backend` as a parameter to `start_consensus()` in `node/src/service.rs` -//! ```text -//! fn start_consensus( -//! client: Arc, -//! -//! backend: Arc, -//! block_import: ParachainBlockImport, -//! prometheus_registry: Option<&Registry>, -//! telemetry: Option, -//! task_manager: &TaskManager, -//! ``` -//! ```text -//! if validator { -//! start_consensus( -//! client.clone(), -//! -//! backend.clone(), -//! block_import, -//! prometheus_registry.as_ref(), -//! ``` -//! -//! 4. In `node/src/service.rs` import the lookahead collator rather than the basic collator -//! ```rust -//! use cumulus_client_consensus_aura::collators::lookahead::{self as aura, Params as AuraParams}; -//! ``` -//! -//! 5. In `start_consensus()` replace the `BasicAuraParams` struct with `AuraParams` -//! - Change the struct type from `BasicAuraParams` to `AuraParams` -//! - In the `para_client` field, pass in a cloned para client rather than the original -//! - Add a `para_backend` parameter after `para_client`, passing in our para backend -//! - Provide a `code_hash_provider` closure like that shown below -//! - Increase `authoring_duration` from 500 milliseconds to 1500 -//! ```rust -//! let params = AuraParams { -//! create_inherent_data_providers: move |_, ()| async move { Ok(()) }, -//! block_import, -//! para_client: client.clone(), -//! para_backend: backend.clone(), -//! relay_client: relay_chain_interface, -//! code_hash_provider: move |block_hash| { -//! client.code_at(block_hash).ok().map(|c| ValidationCode::from(c).hash()) -//! }, -//! sync_oracle, -//! keystore, -//! collator_key, -//! para_id, -//! overseer_handle, -//! relay_chain_slot_duration, -//! proposer, -//! collator_service, -//! -//! authoring_duration: Duration::from_millis(1500), -//! reinitialize: false, -//! }; -//! ``` -//! -//! **Note:** Set `authoring_duration` to whatever you want, taking your own hardware into account. -//! But if the backer who should be slower than you due to reading from disk, times out at two -//! seconds your candidates will be rejected. -//! -//! 6. In `start_consensus()` replace `basic_aura::run` with `aura::run` -//! ```rust -//! let fut = aura::run::< -//! Block, -//! sp_consensus_aura::sr25519::AuthorityPair, -//! _, -//! _, -//! _, -//! _, -//! _, -//! _, -//! _, -//! _, -//! _, -//! >(params); -//! task_manager.spawn_essential_handle().spawn("aura", None, fut); -//! ``` -//! -//! ## Phase 3 - Activate Async Backing -//! -//! This phase consists of changes to your parachain’s runtime that activate async backing feature. -//! -//! 1. Configure `pallet_aura`, setting `AllowMultipleBlocksPerSlot` to true in -//! `runtime/src/lib.rs`. -//! ```rust -//! impl pallet_aura::Config for Runtime { -//! type AuthorityId = AuraId; -//! type DisabledValidators = (); -//! type MaxAuthorities = ConstU32<100_000>; -//! // here -//! type AllowMultipleBlocksPerSlot = ConstBool; -//! #[cfg(feature = "experimental")] -//! type SlotDuration = ConstU64; -//! } -//! ``` -//! -//! 2. Increase the maximum `UNINCLUDED_SEGMENT_CAPACITY` in `runtime/src/lib.rs`. -//! ```rust -//! // Maximum number of blocks simultaneously accepted by the Runtime, not yet included into the -//! // relay chain. -//! pub const UNINCLUDED_SEGMENT_CAPACITY: u32 = 3; -//! // How many parachain blocks are processed by the relay chain per parent. Limits the number of -//! // blocks authored per slot. -//! pub const BLOCK_PROCESSING_VELOCITY: u32 = 1; -//! ``` -//! -//! 3. Decrease `MILLISECS_PER_BLOCK` to 6000. -//! -//! - Note: For a parachain which measures time in terms of its own block number rather than by -//! relay block number it may be preferable to increase velocity. Changing block time may cause -//! complications, requiring additional changes. See the section “Timing by Block Number”. -//! ```rust -//! // This determines the average expected block time that we are targeting. -//! // Blocks will be produced at a minimum duration defined by `SLOT_DURATION`. -//! // `SLOT_DURATION` is picked up by `pallet_timestamp` which is in turn picked -//! // up by `pallet_aura` to implement `fn slot_duration()`. -//! // -//! // Change this to adjust the block time. -//! pub const MILLISECS_PER_BLOCK: u64 = 6000; -//! ``` -//! -//! 4. Update `MAXIMUM_BLOCK_WEIGHT` to reflect the increased time available for block production. -//! ```rust -//! // We allow for 2 seconds of compute with a 6 second average block. -//! pub const MAXIMUM_BLOCK_WEIGHT: Weight = Weight::from_parts( -//! WEIGHT_REF_TIME_PER_SECOND.saturating_mul(2), -//! cumulus_primitives_core::relay_chain::MAX_POV_SIZE as u64, -//! ); -//! ``` -//! -//! 5. Add a feature flagged alternative for `MinimumPeriod` in `pallet_timestamp`. The type should -//! be `ConstU64<0>` with the feature flag experimental, and `ConstU64<{SLOT_DURATION / 2}>` -//! without. -//! ```rust -//! impl pallet_timestamp::Config for Runtime { -//! type Moment = u64; -//! type OnTimestampSet = Aura; -//! #[cfg(feature = "experimental")] -//! type MinimumPeriod = ConstU64<0>; -//! #[cfg(not(feature = "experimental"))] -//! type MinimumPeriod = ConstU64<{ SLOT_DURATION / 2 }>; -//! type WeightInfo = weights::pallet_timestamp::WeightInfo; -//! } -//! ``` -//! -//! ## Timing by Block Number -//! -//! With asynchronous backing it will be possible for parachains to opt for a block time of 6 -//! seconds rather than 12 seconds. But modifying block duration isn’t so simple for a parachain -//! which was measuring time in terms of its own block number. It could result in expected and -//! actual time not matching up, stalling the parachain. +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", register_validate_block)] //! -//! One strategy to deal with this issue is to instead rely on relay chain block numbers for timing. -//! Relay block number is kept track of by each parachain in `pallet-parachain-system` with the -//! storage value `LastRelayChainBlockNumber`. This value can be obtained and used wherever timing -//! based on block number is needed. - #![deny(rustdoc::broken_intra_doc_links)] #![deny(rustdoc::private_intra_doc_links)] diff --git a/templates/parachain/runtime/src/lib.rs b/templates/parachain/runtime/src/lib.rs index 0e280efc4126..c457acab96f4 100644 --- a/templates/parachain/runtime/src/lib.rs +++ b/templates/parachain/runtime/src/lib.rs @@ -273,6 +273,7 @@ construct_runtime!( } ); +#[docify::export(register_validate_block)] cumulus_pallet_parachain_system::register_validate_block! { Runtime = Runtime, BlockExecutor = cumulus_pallet_aura_ext::BlockExecutor::, From df4cedc85797fe9bb8a6086188a2a924036358f8 Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Fri, 14 Jun 2024 01:20:11 +0800 Subject: [PATCH 12/16] Async upgrade docs Phase 2 docify --- docs/sdk/src/guides/async_backing_guide.rs | 75 ++++++++++++++++++++++ templates/parachain/node/src/service.rs | 2 + 2 files changed, 77 insertions(+) diff --git a/docs/sdk/src/guides/async_backing_guide.rs b/docs/sdk/src/guides/async_backing_guide.rs index ddae6161f3f4..a0a1389c2960 100644 --- a/docs/sdk/src/guides/async_backing_guide.rs +++ b/docs/sdk/src/guides/async_backing_guide.rs @@ -114,5 +114,80 @@ //! `register_validate_block` should look after removing `CheckInherents`. #![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", register_validate_block)] //! +//! +//! ## Phase 2 - Update Parachain Nodes +//! +//! This phase consists of plugging in the new lookahead collator node. +//! +//! 1. Import `cumulus_primitives_core::ValidationCode` to `node/src/service.rs`. +#![doc = docify::embed!("../../templates/parachain/node/src/service.rs", cumulus_primitives)] +//! +//! 2. In `node/src/service.rs`, modify `sc_service::spawn_tasks` to use a clone of `Backend` rather +//! than the original +//! ```ignore +//! sc_service::spawn_tasks(sc_service::SpawnTasksParams { +//! .. +//! backend: backend.clone(), +//! .. +//! })?; +//! ``` +//! +//! 3. Add `backend` as a parameter to `start_consensus()` in `node/src/service.rs` +//! ```text +//! fn start_consensus( +//! .. +//! backend: Arc, +//! .. +//! ``` +//! ```ignore +//! if validator { +//! start_consensus( +//! .. +//! backend.clone(), +//! .. +//! )?; +//! } +//! ``` +//! +//! 4. In `node/src/service.rs` import the lookahead collator rather than the basic collator +#![doc = docify::embed!("../../templates/parachain/node/src/service.rs", lookahead_collator)] +//! +//! 5. In `start_consensus()` replace the `BasicAuraParams` struct with `AuraParams` +//! - Change the struct type from `BasicAuraParams` to `AuraParams` +//! - In the `para_client` field, pass in a cloned para client rather than the original +//! - Add a `para_backend` parameter after `para_client`, passing in our para backend +//! - Provide a `code_hash_provider` closure like that shown below +//! - Increase `authoring_duration` from 500 milliseconds to 1500 +//! ```ignore +//! let params = AuraParams { +//! .. +//! para_client: client.clone(), +//! para_backend: backend.clone(), +//! .. +//! code_hash_provider: move |block_hash| { +//! client.code_at(block_hash).ok().map(|c| ValidationCode::from(c).hash()) +//! }, +//! .. +//! authoring_duration: Duration::from_millis(1500), +//! .. +//! }; +//! ``` +//! +//! **Note:** Set `authoring_duration` to whatever you want, taking your own hardware into account. +//! But if the backer who should be slower than you due to reading from disk, times out at two +//! seconds your candidates will be rejected. +//! +//! 6. In `start_consensus()` replace `basic_aura::run` with `aura::run` +//! ```ignore +//! let fut = +//! aura::run::( +//! params, +//! ); +//! task_manager.spawn_essential_handle().spawn("aura", None, fut); +//! ``` +//! + + #![deny(rustdoc::broken_intra_doc_links)] #![deny(rustdoc::private_intra_doc_links)] + diff --git a/templates/parachain/node/src/service.rs b/templates/parachain/node/src/service.rs index ad4689c6e55d..98121dd3e7f4 100644 --- a/templates/parachain/node/src/service.rs +++ b/templates/parachain/node/src/service.rs @@ -12,6 +12,7 @@ use parachain_template_runtime::{ // Cumulus Imports use cumulus_client_collator::service::CollatorService; +#[docify::export(lookahead_collator)] use cumulus_client_consensus_aura::collators::lookahead::{self as aura, Params as AuraParams}; use cumulus_client_consensus_common::ParachainBlockImport as TParachainBlockImport; use cumulus_client_consensus_proposer::Proposer; @@ -20,6 +21,7 @@ use cumulus_client_service::{ BuildNetworkParams, CollatorSybilResistance, DARecoveryProfile, ParachainHostFunctions, StartRelayChainTasksParams, }; +#[docify::export(cumulus_primitives)] use cumulus_primitives_core::{ relay_chain::{CollatorPair, ValidationCode}, ParaId, From 628843d84a475258adf2cf798a29f006d19fbaf8 Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Fri, 14 Jun 2024 02:04:54 +0800 Subject: [PATCH 13/16] Async backing upgrade docs phase 3 --- docs/sdk/src/guides/async_backing_guide.rs | 67 ++++++++++++++++++- .../parachain/runtime/src/configs/mod.rs | 1 + templates/parachain/runtime/src/lib.rs | 1 + 3 files changed, 66 insertions(+), 3 deletions(-) diff --git a/docs/sdk/src/guides/async_backing_guide.rs b/docs/sdk/src/guides/async_backing_guide.rs index a0a1389c2960..e92ca0125851 100644 --- a/docs/sdk/src/guides/async_backing_guide.rs +++ b/docs/sdk/src/guides/async_backing_guide.rs @@ -39,11 +39,27 @@ //! runtime. //! 2. Establish and ensure the constant relay chain slot duration measured in milliseconds equal to //! `6000` in the runtime. -#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", async_backing_params)] +//! ```rust +//! // Maximum number of blocks simultaneously accepted by the Runtime, not yet included into the +//! // relay chain. +//! pub const UNINCLUDED_SEGMENT_CAPACITY: u32 = 1; +//! // How many parachain blocks are processed by the relay chain per parent. Limits the number of +//! // blocks authored per slot. +//! pub const BLOCK_PROCESSING_VELOCITY: u32 = 1; +//! // Relay chain slot duration, in milliseconds. +//! pub const RELAY_CHAIN_SLOT_DURATION_MILLIS: u32 = 6000; +//! ``` //! //! 3. Establish constants `MILLISECS_PER_BLOCK` and `SLOT_DURATION` if not already present in the //! runtime. -#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", block_times)] +//! ```ignore +//! // `SLOT_DURATION` is picked up by `pallet_timestamp` which is in turn picked +//! // up by `pallet_aura` to implement `fn slot_duration()`. +//! // +//! // Change this to adjust the block time. +//! pub const MILLISECS_PER_BLOCK: u64 = 12000; +//! pub const SLOT_DURATION: u64 = MILLISECS_PER_BLOCK; +//! ``` //! //! 4. Configure `cumulus_pallet_parachain_system` in the runtime. //! @@ -186,7 +202,52 @@ //! task_manager.spawn_essential_handle().spawn("aura", None, fut); //! ``` //! - +//! ## Phase 3 - Activate Async Backing +//! +//! This phase consists of changes to your parachain’s runtime that activate async backing feature. +//! +//! 1. Configure `pallet_aura`, setting `AllowMultipleBlocksPerSlot` to true in +//! `runtime/src/lib.rs`. +#![doc = docify::embed!("../../templates/parachain/runtime/src/configs/mod.rs", aura_config)] +//! +//! 2. Increase the maximum `UNINCLUDED_SEGMENT_CAPACITY` in `runtime/src/lib.rs`. +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", async_backing_params)] +//! +//! 3. Decrease `MILLISECS_PER_BLOCK` to 6000. +//! +//! - Note: For a parachain which measures time in terms of its own block number rather than by +//! relay block number it may be preferable to increase velocity. Changing block time may cause +//! complications, requiring additional changes. See the section “Timing by Block Number”. +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", block_times)] +//! +//! 4. Update `MAXIMUM_BLOCK_WEIGHT` to reflect the increased time available for block production. +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", max_block_weight)] +//! +//! 5. Add a feature flagged alternative for `MinimumPeriod` in `pallet_timestamp`. The type should +//! be `ConstU64<0>` with the feature flag experimental, and `ConstU64<{SLOT_DURATION / 2}>` +//! without. +//! ```ignore +//! impl pallet_timestamp::Config for Runtime { +//! .. +//! #[cfg(feature = "experimental")] +//! type MinimumPeriod = ConstU64<0>; +//! #[cfg(not(feature = "experimental"))] +//! type MinimumPeriod = ConstU64<{ SLOT_DURATION / 2 }>; +//! .. +//! } +//! ``` +//! +//! ## Timing by Block Number +//! +//! With asynchronous backing it will be possible for parachains to opt for a block time of 6 +//! seconds rather than 12 seconds. But modifying block duration isn’t so simple for a parachain +//! which was measuring time in terms of its own block number. It could result in expected and +//! actual time not matching up, stalling the parachain. +//! +//! One strategy to deal with this issue is to instead rely on relay chain block numbers for timing. +//! Relay block number is kept track of by each parachain in `pallet-parachain-system` with the +//! storage value `LastRelayChainBlockNumber`. This value can be obtained and used wherever timing +//! based on block number is needed. #![deny(rustdoc::broken_intra_doc_links)] #![deny(rustdoc::private_intra_doc_links)] diff --git a/templates/parachain/runtime/src/configs/mod.rs b/templates/parachain/runtime/src/configs/mod.rs index 0aec332feaf6..5809aed20028 100644 --- a/templates/parachain/runtime/src/configs/mod.rs +++ b/templates/parachain/runtime/src/configs/mod.rs @@ -261,6 +261,7 @@ impl pallet_session::Config for Runtime { type WeightInfo = (); } +#[docify::export(aura_config)] impl pallet_aura::Config for Runtime { type AuthorityId = AuraId; type DisabledValidators = (); diff --git a/templates/parachain/runtime/src/lib.rs b/templates/parachain/runtime/src/lib.rs index c457acab96f4..edee13676d7b 100644 --- a/templates/parachain/runtime/src/lib.rs +++ b/templates/parachain/runtime/src/lib.rs @@ -205,6 +205,7 @@ const AVERAGE_ON_INITIALIZE_RATIO: Perbill = Perbill::from_percent(5); /// `Operational` extrinsics. const NORMAL_DISPATCH_RATIO: Perbill = Perbill::from_percent(75); +#[docify::export(max_block_weight)] /// We allow for 2 seconds of compute with a 6 second average block time. const MAXIMUM_BLOCK_WEIGHT: Weight = Weight::from_parts( WEIGHT_REF_TIME_PER_SECOND.saturating_mul(2), From dc542680be3db3663ec6dca7e1c666c262cb4463 Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Wed, 19 Jun 2024 14:37:43 +0800 Subject: [PATCH 14/16] Update apis.rs minor fix - input args missing for impl_can_build_upon function --- templates/parachain/runtime/src/apis.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/parachain/runtime/src/apis.rs b/templates/parachain/runtime/src/apis.rs index f32b4dbe66a5..bc3c3808fb78 100644 --- a/templates/parachain/runtime/src/apis.rs +++ b/templates/parachain/runtime/src/apis.rs @@ -79,7 +79,7 @@ impl_runtime_apis! { included_hash: ::Hash, slot: cumulus_primitives_aura::Slot, ) -> bool { - Runtime::impl_can_build_upon() + Runtime::impl_can_build_upon(included_hash, slot) } } From 8f7268fe9bab8b19e4366a344f46b8247ab2052b Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Thu, 27 Jun 2024 11:52:30 +0200 Subject: [PATCH 15/16] cargo fmt --- docs/sdk/src/guides/async_backing_guide.rs | 8 ++++---- docs/sdk/src/guides/mod.rs | 3 +-- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/sdk/src/guides/async_backing_guide.rs b/docs/sdk/src/guides/async_backing_guide.rs index e92ca0125851..e56fe25876e1 100644 --- a/docs/sdk/src/guides/async_backing_guide.rs +++ b/docs/sdk/src/guides/async_backing_guide.rs @@ -82,7 +82,7 @@ //! .. //! } //! ``` -//! +//! //! 5. Configure `pallet_aura` in the runtime. //! //! - Set `AllowMultipleBlocksPerSlot` to `false` (don't worry, we will set it to `true` when we @@ -99,9 +99,10 @@ //! } //! ``` //! -//! 6. Update `sp_consensus_aura::AuraApi::slot_duration` in `sp_api::impl_runtime_apis` to match the constant `SLOT_DURATION` +//! 6. Update `sp_consensus_aura::AuraApi::slot_duration` in `sp_api::impl_runtime_apis` to match +//! the constant `SLOT_DURATION` #![doc = docify::embed!("../../templates/parachain/runtime/src/apis.rs", impl_slot_duration)] -//! +//! //! 7. Implement the `AuraUnincludedSegmentApi`, which allows the collator client to query its //! runtime to determine whether it should author a block. //! @@ -251,4 +252,3 @@ #![deny(rustdoc::broken_intra_doc_links)] #![deny(rustdoc::private_intra_doc_links)] - diff --git a/docs/sdk/src/guides/mod.rs b/docs/sdk/src/guides/mod.rs index 05340bd29e62..8296ed447e14 100644 --- a/docs/sdk/src/guides/mod.rs +++ b/docs/sdk/src/guides/mod.rs @@ -36,9 +36,8 @@ pub mod your_first_runtime; /// How to enable storage weight reclaiming in a parachain node and runtime. pub mod enable_pov_reclaim; -/// How to enable Async Backing on parachain projects that started in 2023 or before. +/// How to enable Async Backing on parachain projects that started in 2023 or before. pub mod async_backing_guide; /// How to enable metadata hash verification in the runtime. pub mod enable_metadata_hash; - From 6b53c0eca98573b28a5bfe27950227525d79d4f9 Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Thu, 27 Jun 2024 16:46:31 +0200 Subject: [PATCH 16/16] doc tests --- docs/sdk/src/guides/async_backing_guide.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sdk/src/guides/async_backing_guide.rs b/docs/sdk/src/guides/async_backing_guide.rs index e56fe25876e1..f2f4dcabfd29 100644 --- a/docs/sdk/src/guides/async_backing_guide.rs +++ b/docs/sdk/src/guides/async_backing_guide.rs @@ -66,7 +66,7 @@ //! - Define a `FixedVelocityConsensusHook` using our capacity, velocity, and relay slot duration //! constants. Use this to set the parachain system `ConsensusHook` property. #![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", ConsensusHook)] -//! ```rust +//! ```ignore //! impl cumulus_pallet_parachain_system::Config for Runtime { //! .. //! type ConsensusHook = ConsensusHook; @@ -108,7 +108,7 @@ //! //! - Add the dependency `cumulus-primitives-aura` to the `runtime/Cargo.toml` file for your //! runtime -//! ```rust +//! ```ignore //! .. //! cumulus-primitives-aura = { path = "../../../../primitives/aura", default-features = false } //! ..