add elastic scaling MVP guide

docs/sdk/src/guides/enable_elastic_scaling_mvp.rs

@@ -0,0 +1,142 @@
+//! # Enable elastic scaling MVP for a parachain
+//!
+//! **This guide assumes full familiarity with Asynchronous Backing and its terminology, as defined
+//! in <https://wiki.polkadot.network/docs/maintain-guides-async-backing>.
+//! Furthermore, the parachain should have already been upgraded according to the guide.**
+//!
+//! ## Quick introduction to elastic scaling
+//!
+//! [Elastic scaling](https://polkadot.network/blog/elastic-scaling-streamling-growth-on-polkadot)
+//! is a feature that will enable parachains to seamlessly scale up/down their block space usage in
+//! order to increase throughput or lower their latency.
+//!
+//! At present, with Asynchronous Backing enabled, a parachain can only include a block on the relay
+//! chain every 6 seconds, irregardless of how many cores the parachain acquires. Elastic scaling
+//! builds further on the 10x throughput increase of Async Backing, enabling collators to submit up
+//! to 3 parachain blocks per relay chain block, resulting in a further 3x throughput increase.
+//!
+//! ## Current limitations of the MVP
+//!
+//! The full implementation of elastic scaling spans across the entire relay/parachain stack and is
+//! still [work in progress](https://github.com/paritytech/polkadot-sdk/issues/1829).
+//! Below are described the current limitations of the MVP:
+//!
+//! 1. **Limited core count**. Parachain block authoring is sequential, so the second block will
+//!    start being built only after the previous block is imported. The current block production is
+//!    capped at 2 seconds of execution. Therefore, assuming the full 2 seconds are used, a
+//!    parachain can only utilise at most 3 cores in a relay chain slot of 6 seconds. If the full
+//!    execution time is not being used, higher core counts can be achieved.
+//! 2. **Single collator requirement for consistently scaling beyond a core at full authorship
+//!    duration of 2 seconds per block.** Using the current implementation with multiple collators
+//!    adds additional latency to the block production pipeline. Assuming block execution takes
+//!    about the same as authorship, the additional overhead is equal the duration of the authorship
+//!    plus the block announcement. Since each collator must first import the previous block before
+//!    authoring a new one, this would amount to 12 seconds for 3 cores and 8 seconds for 2 cores.
+//! 3. **Trusted collator set.** The collator set needs to be trusted until there’s a mitigation
+//!    that would prevent or deter multiple collators from submitting the same collation.
+//!    A solution is being discussed [here](https://github.com/polkadot-fellows/RFCs/issues/92).
+//! 4. **Fixed scaling.** For true elasticity, the parachain must be able to seamlessly acquire or
+//!    sell coretime as the user demand grows and shrinks over time, in an automated manner. This is
+//!    currently lacking - a parachain can only scale up or down by “manually” acquiring coretime.
+//!    This is not in the scope of the relay chain functionality. Parachains can already start
+//!    implementing such autoscaling, but we aim to provide a framework/examples for developing
+//!    autoscaling strategies.
+//!
+//! ## Using elastic scaling MVP
+//!
+//! ### Prerequisites
+//!
+//! - Ensure Asynchronous Backing is enabled on the network and you have enabled it on the parachain
+//!   using [this guide](https://wiki.polkadot.network/docs/maintain-guides-async-backing).
+//! - Ensure the `AsyncBackingParams.max_candidate_depth` value is configured to a value that is at
+//!   least double the maximum targeted parachain velocity. For example, if the parachain will build
+//!   at most 3 candidates per relay chain block, the `max_candidate_depth` should be at least 6.
+//! - Use a trusted single collator for maximum throughput.
+//! - Ensure enough coretime is assigned to the parachain. For maximum throughput the upper bound is
+//!   3 cores.
+//! - Use the latest cumulus release, which includes the necessary elastic scaling changes.
+//!
+//! The following steps assume using the cumulus parachain template.
+//!
+//! ### Phase 1 - Update Parachain Node
+//!
+//! This phase consists of plugging in the new slot-based collator node.
+//!
+//! 1. In `node/src/service.rs` import the slot based collator instead of the lookahead collator.
+//!
+//! ```rust
+//! use cumulus_client_consensus_aura::collators::slot_based::{self as aura, Params as AuraParams};
+//! ```
+//!
+//! 2. In `start_consensus()`
+//!     - Remove the `overseer_handle` param (also remove the
+//!     `OverseerHandle` type import if it’s not used elsewhere).
+//!     - In `AuraParams`, remove the `sync_oracle` and `overseer_handle` fields and add a
+//!     `slot_drift` field with a   value of `Duration::from_secs(1)`.
+//!     - Replace the single future returned by `aura::run` with the two futures returned by it and
+//!     spawn them as separate tasks:
+//!      ```rust
+//!      let (collation_future, block_builder_future) = aura::run::<
+//!          Block,
+//!          sp_consensus_aura::sr25519::AuthorityPair,
+//!          _,
+//!          _,
+//!          _,
+//!          _,
+//!          _,
+//!          _,
+//!          _,
+//!          _>(params);
+//!      task_manager
+//!          .spawn_essential_handle()
+//!          .spawn("collation-task", None, collation_future);
+//!      task_manager
+//!          .spawn_essential_handle()
+//!          .spawn("block-builder-task", None, block_builder_future);
+//!     ```
+//!
+//! 3. In `start_parachain_node()` remove the `sync_service` and `overseer_handle` params passed to
+//!    `start_consensus`
+//!
+//! ### Phase 2 - Activate fixed factor scaling in the runtime
+//!
+//! This phase consists of a couple of changes needed to be made to the parachain’s runtime in order
+//! to utilise fixed factor scaling.
+//!
+//! First of all, you need to decide the upper limit to how many parachain blocks you need to
+//! produce per relay chain block (in direct correlation with the number of acquired cores). This
+//! should be either 1 (no scaling), 2 or 3. This is called the parachain velocity.
+//!
+//! If you configure a velocity which is different from the number of assigned cores, the measured
+//! velocity in practice will be the minimum of these two.
+//!
+//! The chosen velocity should also be used to compute:
+//! - The slot duration, by dividing the 6000 ms duration of the relay chain slot duration by the
+//! velocity.
+//! - The unincluded segment capacity, by multiplying the velocity with 2 and adding 1 to
+//! it.
+//!
+//! Let’s assume a desired velocity of 3 parachain blocks per relay chain block. The needed changes
+//! would all be done in `runtime/src/lib.rs`:
+//!
+//! 1. Increase the `BLOCK_PROCESSING_VELOCITY` to the desired value. In this example, 3.
+//!
+//!      ```rust
+//!      const BLOCK_PROCESSING_VELOCITY: u32 = 3;
+//!      ```
+//!
+//! 2. Set the `MILLISECS_PER_BLOCK` to the desired value.
+//!
+//!      ```rust
+//!      const MILLISECS_PER_BLOCK: u32 =
+//!          RELAY_CHAIN_SLOT_DURATION_MILLIS / BLOCK_PROCESSING_VELOCITY;
+//!      ```
+//!     Note: for a parachain which measures time in terms of its own block number, changing block
+//!     time may cause complications, requiring additional changes.  See the section ["Timing by
+//!     block number" of the async backing guide](https://wiki.polkadot.network/docs/maintain-guides-async-backing#timing-by-block-number).
+//!
+//! 3. Increase the `UNINCLUDED_SEGMENT_CAPACITY` to the desired value.
+//!
+//!     ```rust
+//!     const UNINCLUDED_SEGMENT_CAPACITY: u32 = 2 * BLOCK_PROCESSING_VELOCITY + 1;
+//!     ```

docs/sdk/src/guides/mod.rs

@@ -29,3 +29,6 @@ pub mod enable_pov_reclaim;
 
 /// How to enable metadata hash verification in the runtime.
 pub mod enable_metadata_hash;
+
+/// How to enable elastic scaling MVP on a parachain.
+pub mod enable_elastic_scaling_mvp;