# enable_elastic_scaling.rs - source
Source of the Rust file `docs/sdk/src/guides/enable_elastic_scaling.rs`.

#
pezkuwi_sdk_docs/guides/
enable_elastic_scaling.rs

    1//! # Enable elastic scaling for a teyrchain
    2//!
    3//! <div class="warning">This guide assumes full familiarity with Asynchronous Backing and its
    4//! terminology, as defined in <a href="https://docs.pezkuwichain.io/sdk/master/pezkuwi_sdk_docs/guides/async_backing_guide/index.html">the Pezkuwi SDK Docs</a>.
    5//! </div>
    6//!
    7//! ## Quick introduction to Elastic Scaling
    8//!
    9//! [Elastic scaling](https://www.parity.io/blog/pezkuwi-web3-cloud) is a feature that enables teyrchains (rollups) to use multiple cores.
    10//! Teyrchains can adjust their usage of core resources on the fly to increase TPS and decrease
    11//! latency.
    12//!
    13//! ### When do you need Elastic Scaling?
    14//!
    15//! Depending on their use case, applications might have an increased need for the following:
    16//! - compute (CPU weight)
    17//! - bandwidth (proof size)
    18//! - lower latency (block time)
    19//!
    20//! ### High throughput (TPS) and lower latency
    21//!
    22//! If the main bottleneck is the CPU, then your teyrchain needs to maximize the compute usage of
    23//! each core while also achieving a lower latency.
    24//! 3 cores provide the best balance between CPU, bandwidth and latency: up to 6s of execution,
    25//! 5MB/s of DA bandwidth and fast block time of just 2 seconds.
    26//!
    27//! ### High bandwidth
    28//!
    29//! Useful for applications that are bottlenecked by bandwidth.
    30//! By using 6 cores, applications can make use of up to 6s of compute, 10MB/s of bandwidth
    31//! while also achieving 1 second block times.
    32//!
    33//! ### Ultra low latency
    34//!
    35//! When latency is the primary requirement, Elastic scaling is currently the only solution. The
    36//! caveat is the efficiency of core time usage decreases as more cores are used.
    37//!
    38//! For example, using 12 cores enables fast transaction confirmations with 500ms blocks and up to
    39//! 20 MB/s of DA bandwidth.
    40//!
    41//! ## Dependencies
    42//!
    43//! Prerequisites: Pezkuwi-SDK `2509` or newer.
    44//!
    45//! To ensure the security and reliability of your chain when using this feature you need the
    46//! following:
    47//! - An omni-node based collator. This has already become the default choice for collators.
    48//! - UMP signal support.
    49//! [RFC103](https://github.com/pezkuwichain/pezkuwi-fellows/RFCs/blob/main/text/0103-introduce-core-index-commitment.md).
    50//!   This is mandatory protection against PoV replay attacks.
    51//! - Enabling the relay parent offset feature. This is required to ensure the teyrchain block times
    52//!   and transaction in-block confidence are not negatively affected by relay chain forks. Read
    53//!   [`crate::guides::handling_teyrchain_forks`] for more information.
    54//! - Block production configuration adjustments.
    55//!
    56//! ### Upgrade to Pezkuwi Omni node
    57//!
    58//! Your collators need to run `pezkuwi-teyrchain` or `pezkuwi-omni-node` with the `--authoring
    59//! slot-based` CLI argument.
    60//! To avoid potential issues and get best performance it is recommeneded to always run the
    61//! latest release on all of the collators.
    62//!
    63//! Further information about omni-node and how to upgrade is available:
    64//! - [high level docs](https://docs.pezkuwichain.io/develop/toolkit/teyrchains/pezkuwi-omni-node/)
    65//! - [`crate::reference_docs::omni_node`]
    66//!
    67//! ### UMP signals
    68//!
    69//! UMP signals are now enabled by default in the `teyrchain-system` pezpallet and are used for
    70//! elastic scaling. You can find more technical details about UMP signals and their usage for
    71//! elastic scaling
    72//! [here](https://github.com/pezkuwichain/pezkuwi-fellows/RFCs/blob/main/text/0103-introduce-core-index-commitment.md).
    73//!
    74//! ### Enable the relay parent offset feature
    75//!
    76//! It is recommended to use an offset of `1`, which is sufficient to eliminate any issues
    77//! with relay chain forks.
    78//!
    79//! Configure the relay parent offset like this:
    80//! ```ignore
    81//!     /// Build with an offset of 1 behind the relay chain best block.
    82//!     const RELAY_PARENT_OFFSET: u32 = 1;
    83//!
    84//!     impl pezcumulus_pezpallet_teyrchain_system::Config for Runtime {
    85//!         // ...
    86//!         type RelayParentOffset = ConstU32<RELAY_PARENT_OFFSET>;
    87//!     }
    88//! ```
    89//!
    90//! Implement the runtime API to retrieve the offset on the client side.
    91//! ```ignore
    92//!     impl pezcumulus_primitives_core::RelayParentOffsetApi<Block> for Runtime {
    93//!         fn relay_parent_offset() -> u32 {
    94//!             RELAY_PARENT_OFFSET
    95//!         }
    96//!     }
    97//! ```
    98//!
    99//! ### Block production configuration
    100//!
    101//! This configuration directly controls the minimum block time and maximum number of cores
    102//! the teyrchain can use.
    103//!
    104//! Example configuration for a 3 core teyrchain:
    105//!  ```ignore
    106//!     /// The upper limit of how many teyrchain blocks are processed by the relay chain per
    107//!     /// parent. Limits the number of blocks authored per slot. This determines the minimum
    108//!     /// block time of the teyrchain:
    109//!     /// `RELAY_CHAIN_SLOT_DURATION_MILLIS/BLOCK_PROCESSING_VELOCITY`
    110//!     const BLOCK_PROCESSING_VELOCITY: u32 = 3;
    111//!
    112//!     /// Maximum number of blocks simultaneously accepted by the Runtime, not yet included
    113//!     /// into the relay chain.
    114//!     const UNINCLUDED_SEGMENT_CAPACITY: u32 = (2 + RELAY_PARENT_OFFSET) *
    115//! BLOCK_PROCESSING_VELOCITY + 1;
    116//!
    117//!     /// Relay chain slot duration, in milliseconds.
    118//!     const RELAY_CHAIN_SLOT_DURATION_MILLIS: u32 = 6000;
    119//!
    120//!     type ConsensusHook = pezcumulus_pezpallet_aura_ext::FixedVelocityConsensusHook<
    121//!         Runtime,
    122//!         RELAY_CHAIN_SLOT_DURATION_MILLIS,
    123//!         BLOCK_PROCESSING_VELOCITY,
    124//!         UNINCLUDED_SEGMENT_CAPACITY,
    125//!     >;
    126//!
    127//!  ```
    128//!
    129//! ### Teyrchain Slot Duration
    130//!
    131//! A common source of confusion is the correct configuration of the `SlotDuration` that is passed
    132//! to `pezpallet-aura`.
    133//! ```ignore
    134//! impl pezpallet_aura::Config for Runtime {
    135//!     // ...
    136//!     type SlotDuration = ConstU64<SLOT_DURATION>;
    137//! }
    138//! ```
    139//!
    140//! The slot duration determines the length of each author's turn and is decoupled from the block
    141//! production interval. During their slot, authors are allowed to produce multiple blocks. **The
    142//! slot duration is required to be at least 6s (same as on the relay chain).**
    143//!
    144//! **Configuration recommendations:**
    145//! - For new teyrchains starting from genesis: use a slot duration of 24 seconds
    146//! - For existing live teyrchains: leave the slot duration unchanged
    147//!
    148//!
    149//! ## Current limitations
    150//!
    151//! ### Maximum execution time per relay chain block.
    152//!
    153//! Since teyrchain block authoring is sequential, the next block can only be built after
    154//! the previous one has been imported.
    155//! At present, a core allows up to 2 seconds of execution per relay chain block.
    156//!
    157//! If we assume a 6s teyrchain slot, and each block takes the full 2 seconds to execute,
    158//! the teyrchain will not be able to fully utilize the compute resources of all 3 cores.
    159//!
    160//! If the collator hardware is faster, it can author and import full blocks more quickly,
    161//! making it possible to utilize even more than 3 cores efficiently.
    162//!
    163//! #### Why?
    164//!
    165//! Within a 6-second teyrchain slot, collators can author multiple teyrchain blocks.
    166//! Before building the first block in a slot, the new block author must import the last
    167//! block produced by the previous author.
    168//! If the import of the last block is not completed before the next relay chain slot starts,
    169//! the new author will build on its parent (assuming it was imported). This will create a fork
    170//! which degrades the teyrchain block confidence and block times.
    171//!
    172//! This means that, on reference hardware, a teyrchain with a slot time of 6s can
    173//! effectively utilize up to 4 seconds of execution per relay chain block, because it needs to
    174//! ensure the next block author has enough time to import the last block.
    175//! Hardware with higher single-core performance can enable a teyrchain to fully utilize more
    176//! cores.
    177//!
    178//! ### Fixed factor scaling.
    179//!
    180//! For true elasticity, a teyrchain needs to acquire more cores when needed in an automated
    181//! manner. This functionality is not yet available in the SDK, thus acquiring additional
    182//! on-demand or bulk cores has to be managed externally.