diff --git a/node/core/provisioner/src/lib.rs b/node/core/provisioner/src/lib.rs index c989366ffa05..e1d450112ff8 100644 --- a/node/core/provisioner/src/lib.rs +++ b/node/core/provisioner/src/lib.rs @@ -663,7 +663,7 @@ async fn request_backable_candidates( // The candidate occupying the core is available, choose its // child in the fragment tree. // - // TODO: doesn't work for parathreads. We lean hard on the assumption + // TODO: doesn't work for on-demand parachains. We lean hard on the assumption // that cores are fixed to specific parachains within a session. // https://github.com/paritytech/polkadot/issues/5492 (scheduled_core.para_id, vec![occupied_core.candidate_hash]) diff --git a/node/network/collator-protocol/src/validator_side/mod.rs b/node/network/collator-protocol/src/validator_side/mod.rs index aad945defcdb..aae5e5cb8ee5 100644 --- a/node/network/collator-protocol/src/validator_side/mod.rs +++ b/node/network/collator-protocol/src/validator_side/mod.rs @@ -520,9 +520,9 @@ where }, }; - // This code won't work well, if at all for parathreads. For parathreads we'll - // have to be aware of which core the parathread claim is going to be multiplexed - // onto. The parathread claim will also have a known collator, and we should always + // This code won't work well, if at all for on-demand parachains. For on-demand we'll + // have to be aware of which core the on-demand claim is going to be multiplexed + // onto. The on-demand claim will also have a known collator, and we should always // allow an incoming connection from that collator. If not even connecting to them // directly. // diff --git a/node/network/statement-distribution/src/vstaging/mod.rs b/node/network/statement-distribution/src/vstaging/mod.rs index 711ad0df33b2..f12c64957f0c 100644 --- a/node/network/statement-distribution/src/vstaging/mod.rs +++ b/node/network/statement-distribution/src/vstaging/mod.rs @@ -549,7 +549,7 @@ fn find_local_validator_state( let our_group = groups.by_validator_index(validator_index)?; - // note: this won't work well for parathreads because it only works + // note: this won't work well for on-demand parachains because it only works // when core assignments to paras are static throughout the session. let core = group_rotation_info.core_for_group(our_group, availability_cores.len()); @@ -1708,7 +1708,7 @@ fn group_for_para( group_rotation_info: &GroupRotationInfo, para_id: ParaId, ) -> Option { - // Note: this won't work well for parathreads as it assumes that core assignments are fixed + // Note: this won't work well for on-demand parachains as it assumes that core assignments are fixed // across blocks. let core_index = availability_cores.iter().position(|c| c.para_id() == Some(para_id)); diff --git a/primitives/src/v4/mod.rs b/primitives/src/v4/mod.rs index 3bb561ce46ba..75acf39e0576 100644 --- a/primitives/src/v4/mod.rs +++ b/primitives/src/v4/mod.rs @@ -802,12 +802,13 @@ impl TypeIndex for GroupIndex { } } -/// A claim on authoring the next block for a given parathread. +/// A claim on authoring the next block for a given parathread (on-demand parachain). #[derive(Clone, Encode, Decode, TypeInfo, RuntimeDebug)] #[cfg_attr(feature = "std", derive(PartialEq))] pub struct ParathreadClaim(pub Id, pub CollatorId); -/// An entry tracking a claim to ensure it does not pass the maximum number of retries. +/// An entry tracking a parathread (on-demand parachain) claim to ensure it does not +/// pass the maximum number of retries. #[derive(Clone, Encode, Decode, TypeInfo, RuntimeDebug)] #[cfg_attr(feature = "std", derive(PartialEq))] pub struct ParathreadEntry { @@ -821,7 +822,7 @@ pub struct ParathreadEntry { #[derive(Clone, Encode, Decode, TypeInfo, RuntimeDebug)] #[cfg_attr(feature = "std", derive(PartialEq))] pub enum CoreOccupied { - /// A parathread. + /// A parathread (on-demand parachain). Parathread(ParathreadEntry), /// A parachain. Parachain, @@ -974,8 +975,9 @@ pub enum CoreState { /// variant. #[codec(index = 1)] Scheduled(ScheduledCore), - /// The core is currently free and there is nothing scheduled. This can be the case for parathread - /// cores when there are no parathread blocks queued. Parachain cores will never be left idle. + /// The core is currently free and there is nothing scheduled. This can be the case for + /// on-demand parachain cores when there are no on-demand blocks queued. Leased parachain + /// cores will never be left idle. #[codec(index = 2)] Free, } @@ -1176,10 +1178,10 @@ pub const POLKADOT_ENGINE_ID: runtime_primitives::ConsensusEngineId = *b"POL1"; /// A consensus log item for polkadot validation. To be used with [`POLKADOT_ENGINE_ID`]. #[derive(Decode, Encode, Clone, PartialEq, Eq)] pub enum ConsensusLog { - /// A parachain or parathread upgraded its code. + /// A parachain upgraded its code. #[codec(index = 1)] ParaUpgradeCode(Id, ValidationCodeHash), - /// A parachain or parathread scheduled a code upgrade. + /// A parachain scheduled a code upgrade. #[codec(index = 2)] ParaScheduleUpgradeCode(Id, ValidationCodeHash, BlockNumber), /// Governance requests to auto-approve every candidate included up to the given block diff --git a/roadmap/implementers-guide/src/SUMMARY.md b/roadmap/implementers-guide/src/SUMMARY.md index ef94ef3659c6..3095013409d9 100644 --- a/roadmap/implementers-guide/src/SUMMARY.md +++ b/roadmap/implementers-guide/src/SUMMARY.md @@ -12,18 +12,17 @@ - [Messaging Overview](messaging.md) - [PVF Pre-checking](pvf-prechecking.md) - [Runtime Architecture](runtime/README.md) - - [`Initializer` Module](runtime/initializer.md) - - [`Configuration` Module](runtime/configuration.md) - - [`Shared`](runtime/shared.md) - - [`Disputes` Module](runtime/disputes.md) - - [`Paras` Module](runtime/paras.md) - - [`Scheduler` Module](runtime/scheduler.md) - - [`Inclusion` Module](runtime/inclusion.md) - - [`ParaInherent` Module](runtime/parainherent.md) - - [`DMP` Module](runtime/dmp.md) - - [`UMP` Module](runtime/ump.md) - - [`HRMP` Module](runtime/hrmp.md) - - [`Session Info` Module](runtime/session_info.md) + - [`Initializer` Pallet](runtime/initializer.md) + - [`Configuration` Pallet](runtime/configuration.md) + - [`Shared` Pallet](runtime/shared.md) + - [`Disputes` Pallet](runtime/disputes.md) + - [`Paras` Pallet](runtime/paras.md) + - [`Scheduler` Pallet](runtime/scheduler.md) + - [`Inclusion` Pallet](runtime/inclusion.md) + - [`ParaInherent` Pallet](runtime/parainherent.md) + - [`DMP` Pallet](runtime/dmp.md) + - [`HRMP` Pallet](runtime/hrmp.md) + - [`Session Info` Pallet](runtime/session_info.md) - [Runtime APIs](runtime-api/README.md) - [Validators](runtime-api/validators.md) - [Validator Groups](runtime-api/validator-groups.md) diff --git a/roadmap/implementers-guide/src/glossary.md b/roadmap/implementers-guide/src/glossary.md index d379c2813b59..e3c34458184b 100644 --- a/roadmap/implementers-guide/src/glossary.md +++ b/roadmap/implementers-guide/src/glossary.md @@ -24,11 +24,12 @@ exactly one downward message queue. - **Parablock:** A block in a parachain. - **Parachain:** A constituent chain secured by the Relay Chain's validators. - **Parachain Validators:** A subset of validators assigned during a period of time to back candidates for a specific parachain -- **Parathread:** A parachain which is scheduled on a pay-as-you-go basis. +- **On-demand parachain:** A parachain which is scheduled on a pay-as-you-go basis. +- **Lease holding parachain:** A parachain possessing an active slot lease. The lease holder is assigned a single availability core for the duration of the lease, granting consistent blockspace scheduling at the rate 1 parablock per relay block. - **PDK (Parachain Development Kit):** A toolset that allows one to develop a parachain. Cumulus is a PDK. - **Preimage:** In our context, if `H(X) = Y` where `H` is a hash function and `Y` is the hash, then `X` is the hash preimage. - **Proof-of-Validity (PoV):** A stateless-client proof that a parachain candidate is valid, with respect to some validation function. -- **PVF:** Parachain Validation Function. The validation code that is run by validators on parachains or parathreads. +- **PVF:** Parachain Validation Function. The validation code that is run by validators on parachains. - **PVF Prechecking:** This is the process of initially checking the PVF when it is first added. We attempt preparation of the PVF and make sure it succeeds within a given timeout. - **PVF Preparation:** This is the process of preparing the WASM blob and includes both prevalidation and compilation. As prevalidation is pretty minimal right now, preparation mostly consists of compilation. - **Relay Parent:** A block in the relay chain, referred to in a context where work is being done in the context of the state at this block. diff --git a/roadmap/implementers-guide/src/node/utility/provisioner.md b/roadmap/implementers-guide/src/node/utility/provisioner.md index 4cb930b1a159..a3998cabba6c 100644 --- a/roadmap/implementers-guide/src/node/utility/provisioner.md +++ b/roadmap/implementers-guide/src/node/utility/provisioner.md @@ -179,7 +179,7 @@ The response is a vector of `BackedCandidate`s, sorted in order of their core in - Often referred to simply as "cores", availability cores are an abstraction used for resource management. For the provisioner, availability cores are most relevant in that core states determine which `para_id`s to provision backable candidates for. - For more on availability cores see [Scheduler Module: Availability Cores](../../runtime/scheduler.md#availability-cores) - **Availability Bitfield:** - - Often referred to simply as a "bitfield", an availability bitfield represents the view of parablock candidate availability from a particular validator's perspective. Each bit in the bitfield corresponds to a single [availability core](../runtime-api/availability-cores.md). + - Often referred to simply as a "bitfield", an availability bitfield represents the view of parablock candidate availability from a particular validator's perspective. Each bit in the bitfield corresponds to a single [availability core](../../runtime-api/availability-cores.md). - For more on availability bitfields see [availability](../../types/availability.md) - **Backable vs. Backed:** - Note that we sometimes use "backed" to refer to candidates that are "backable", but not yet backed on chain. diff --git a/roadmap/implementers-guide/src/pvf-prechecking.md b/roadmap/implementers-guide/src/pvf-prechecking.md index 155d32d52898..961f9323308f 100644 --- a/roadmap/implementers-guide/src/pvf-prechecking.md +++ b/roadmap/implementers-guide/src/pvf-prechecking.md @@ -4,7 +4,7 @@ ## Motivation -Parachains' and parathreads' validation function is described by a wasm module that we refer to as a PVF. Since a PVF is a wasm module the typical way of executing it is to compile it to machine code. +Parachains' validation function is described by a wasm module that we refer to as a PVF. Since a PVF is a wasm module the typical way of executing it is to compile it to machine code. Typically an optimizing compiler consists of algorithms that are able to optimize the resulting machine code heavily. However, while those algorithms perform quite well for a typical wasm code produced by standard toolchains (e.g. rustc/LLVM), those algorithms can be abused to consume a lot of resources. Moreover, since those algorithms are rather complex there is a lot of room for a bug that can crash the compiler. @@ -23,8 +23,8 @@ As a result of this issue we need a fairly hard guarantee that the PVFs of regis The problem is solved by having a pre-checking process which is run when a new validation code is included in the chain. A new PVF can be added in two cases: -- A new parachain or parathread is registered. -- An existing parachain or parathread signalled an upgrade of its validation code. +- A new parachain is registered. +- An existing parachain signalled an upgrade of its validation code. Before any of those operations finish, the PVF pre-checking vote is initiated. The PVF pre-checking vote is identified by the PVF code hash that is being voted on. If there is already PVF pre-checking process running, then no new PVF pre-checking vote will be started. Instead, the operation just subscribes to the existing vote. @@ -48,7 +48,7 @@ On the node-side, there is a PVF pre-checking [subsystem][pvf-prechecker-subsyst ## Summary -Parachains' and parathreads' validation function is described by a wasm module that we refer to as a PVF. +Parachains' validation function is described by a wasm module that we refer to as a PVF. In order to make the PVF usable for candidate validation it has to be registered on-chain. diff --git a/roadmap/implementers-guide/src/runtime-api/availability-cores.md b/roadmap/implementers-guide/src/runtime-api/availability-cores.md index b95af2343b36..9402924f0013 100644 --- a/roadmap/implementers-guide/src/runtime-api/availability-cores.md +++ b/roadmap/implementers-guide/src/runtime-api/availability-cores.md @@ -52,8 +52,8 @@ enum CoreState { /// If a particular Collator is required to author this block, that is also present in this /// variant. Scheduled(ScheduledCore), - /// The core is currently free and there is nothing scheduled. This can be the case for parathread - /// cores when there are no parathread blocks queued. Parachain cores will never be left idle. + /// The core is currently free and there is nothing scheduled. This can be the case for on-demand + /// cores when there are no on-demand parachain blocks queued. Leased cores will never be left idle. Free, } ``` diff --git a/roadmap/implementers-guide/src/runtime/README.md b/roadmap/implementers-guide/src/runtime/README.md index f1f9d6c950e2..995b684b1f06 100644 --- a/roadmap/implementers-guide/src/runtime/README.md +++ b/roadmap/implementers-guide/src/runtime/README.md @@ -6,7 +6,7 @@ Due to the (lack of) guarantees provided by a particular blockchain-runtime fram We also expect, although it's beyond the scope of this guide, that these runtime modules will exist alongside various other modules. This has two facets to consider. First, even if the modules that we describe here don't invoke each others' entry points or routines during initialization, we still have to protect against those other modules doing that. Second, some of those modules are expected to provide governance capabilities for the chain. Configuration exposed by parachain-host modules is mostly for the benefit of these governance modules, to allow the operators or community of the chain to tweak parameters. -The runtime's primary roles to manage scheduling and updating of parachains and parathreads, as well as handling misbehavior reports and slashing. This guide doesn't focus on how parachains or parathreads are registered, only that they are. Also, this runtime description assumes that validator sets are selected somehow, but doesn't assume any other details than a periodic _session change_ event. Session changes give information about the incoming validator set and the validator set of the following session. +The runtime's primary role is to manage scheduling and updating of parachains, as well as handling misbehavior reports and slashing. This guide doesn't focus on how parachains are registered, only that they are. Also, this runtime description assumes that validator sets are selected somehow, but doesn't assume any other details than a periodic _session change_ event. Session changes give information about the incoming validator set and the validator set of the following session. The runtime also serves another role, which is to make data available to the Node-side logic via Runtime APIs. These Runtime APIs should be sufficient for the Node-side code to author blocks correctly. @@ -17,9 +17,9 @@ We will split the logic of the runtime up into these modules: * Initializer: manages initialization order of the other modules. * Shared: manages shared storage and configurations for other modules. * Configuration: manages configuration and configuration updates in a non-racy manner. -* Paras: manages chain-head and validation code for parachains and parathreads. -* Scheduler: manages parachain and parathread scheduling as well as validator assignments. -* Inclusion: handles the inclusion and availability of scheduled parachains and parathreads. +* Paras: manages chain-head and validation code for parachains. +* Scheduler: manages parachain scheduling as well as validator assignments. +* Inclusion: handles the inclusion and availability of scheduled parachains. * SessionInfo: manages various session keys of validators and other params stored per session. * Disputes: handles dispute resolution for included, available parablocks. * Slashing: handles slashing logic for concluded disputes. diff --git a/roadmap/implementers-guide/src/runtime/configuration.md b/roadmap/implementers-guide/src/runtime/configuration.md index 96d63faccedd..e3463846b3cb 100644 --- a/roadmap/implementers-guide/src/runtime/configuration.md +++ b/roadmap/implementers-guide/src/runtime/configuration.md @@ -1,4 +1,4 @@ -# Configuration Module +# Configuration Pallet This module is responsible for managing all configuration of the parachain host in-flight. It provides a central point for configuration updates to prevent races between configuration changes and parachain-processing logic. Configuration can only change during the session change routine, and as this module handles the session change notification first it provides an invariant that the configuration does not change throughout the entire session. Both the [scheduler](scheduler.md) and [inclusion](inclusion.md) modules rely on this invariant to ensure proper behavior of the scheduler. diff --git a/roadmap/implementers-guide/src/runtime/disputes.md b/roadmap/implementers-guide/src/runtime/disputes.md index 1d3e3f62dc01..a2558b74f562 100644 --- a/roadmap/implementers-guide/src/runtime/disputes.md +++ b/roadmap/implementers-guide/src/runtime/disputes.md @@ -1,4 +1,4 @@ -# Disputes Module +# Disputes Pallet After a backed candidate is made available, it is included and proceeds into an acceptance period during which validators are randomly selected to do (secondary) approval checks of the parablock. Any reports disputing the validity of the candidate will cause escalation, where even more validators are requested to check the block, and so on, until either the parablock is determined to be invalid or valid. Those on the wrong side of the dispute are slashed and, if the parablock is deemed invalid, the relay chain is rolled back to a point before that block was included. diff --git a/roadmap/implementers-guide/src/runtime/dmp.md b/roadmap/implementers-guide/src/runtime/dmp.md index bade5ad4b8c4..f56df31934ef 100644 --- a/roadmap/implementers-guide/src/runtime/dmp.md +++ b/roadmap/implementers-guide/src/runtime/dmp.md @@ -1,4 +1,4 @@ -# DMP Module +# DMP Pallet A module responsible for Downward Message Processing (DMP). See [Messaging Overview](../messaging.md) for more details. diff --git a/roadmap/implementers-guide/src/runtime/hrmp.md b/roadmap/implementers-guide/src/runtime/hrmp.md index 2b0b4751e30a..927c14cd5969 100644 --- a/roadmap/implementers-guide/src/runtime/hrmp.md +++ b/roadmap/implementers-guide/src/runtime/hrmp.md @@ -1,4 +1,4 @@ -# HRMP Module +# HRMP Pallet A module responsible for Horizontally Relay-routed Message Passing (HRMP). See [Messaging Overview](../messaging.md) for more details. diff --git a/roadmap/implementers-guide/src/runtime/inclusion.md b/roadmap/implementers-guide/src/runtime/inclusion.md index 8b8ea944d7fd..3fe7711ae2d0 100644 --- a/roadmap/implementers-guide/src/runtime/inclusion.md +++ b/roadmap/implementers-guide/src/runtime/inclusion.md @@ -1,6 +1,6 @@ -# Inclusion Module +# Inclusion Pallet -The inclusion module is responsible for inclusion and availability of scheduled parachains and parathreads. It also manages the UMP dispatch queue of each parachain/thread. +The inclusion module is responsible for inclusion and availability of scheduled parachains. It also manages the UMP dispatch queue of each parachain. ## Storage @@ -61,9 +61,9 @@ No initialization routine runs for this module. However, the initialization of t All failed checks should lead to an unrecoverable error making the block invalid. * `process_bitfields(expected_bits, Bitfields, core_lookup: Fn(CoreIndex) -> Option)`: - 1. call `sanitize_bitfields` and use the sanitized `signed_bitfields` from now on. - 1. call `sanitize_backed_candidates` and use the sanitized `backed_candidates` from now on. - 1. apply each bit of bitfield to the corresponding pending candidate. looking up parathread cores using the `core_lookup`. Disregard bitfields that have a `1` bit for any free cores. + 1. Call `sanitize_bitfields` and use the sanitized `signed_bitfields` from now on. + 1. Call `sanitize_backed_candidates` and use the sanitized `backed_candidates` from now on. + 1. Apply each bit of bitfield to the corresponding pending candidate, looking up on-demand parachain cores using the `core_lookup`. Disregard bitfields that have a `1` bit for any free cores. 1. For each applied bit of each availability-bitfield, set the bit for the validator in the `CandidatePendingAvailability`'s `availability_votes` bitfield. Track all candidates that now have >2/3 of bits set in their `availability_votes`. These candidates are now available and can be enacted. 1. For all now-available candidates, invoke the `enact_candidate` routine with the candidate and relay-parent number. 1. Return a list of `(CoreIndex, CandidateHash)` from freed cores consisting of the cores where candidates have become available. diff --git a/roadmap/implementers-guide/src/runtime/initializer.md b/roadmap/implementers-guide/src/runtime/initializer.md index ffeacd5cb357..19dfcbde50a9 100644 --- a/roadmap/implementers-guide/src/runtime/initializer.md +++ b/roadmap/implementers-guide/src/runtime/initializer.md @@ -1,4 +1,4 @@ -# Initializer Module +# Initializer Pallet This module is responsible for initializing the other modules in a deterministic order. It also has one other purpose as described in the overview of the runtime: accepting and forwarding session change notifications. diff --git a/roadmap/implementers-guide/src/runtime/paras.md b/roadmap/implementers-guide/src/runtime/paras.md index a89cca6b658e..71e5fcbaea21 100644 --- a/roadmap/implementers-guide/src/runtime/paras.md +++ b/roadmap/implementers-guide/src/runtime/paras.md @@ -1,7 +1,7 @@ -# Paras Module +# Paras Pallet -The Paras module is responsible for storing information on parachains and parathreads. Registered -parachains and parathreads cannot change except at session boundaries and after at least a full +The Paras module is responsible for storing information on parachains. Registered +parachains cannot change except at session boundaries and after at least a full session has passed. This is primarily to ensure that the number and meaning of bits required for the availability bitfields does not change except at session boundaries. @@ -54,15 +54,15 @@ struct ParaGenesisArgs { pub enum ParaLifecycle { /// A Para is new and is onboarding. Onboarding, - /// Para is a Parathread. + /// Para is a Parathread (on-demand parachain). Parathread, - /// Para is a Parachain. + /// Para is a lease holding Parachain. Parachain, - /// Para is a Parathread which is upgrading to a Parachain. + /// Para is a Parathread (on-demand Parachain) which is upgrading to a lease holding Parachain. UpgradingParathread, - /// Para is a Parachain which is downgrading to a Parathread. + /// Para is a lease holding Parachain which is downgrading to an on-demand parachain. DowngradingParachain, - /// Parathread is being offboarded. + /// Parathread (on-demand parachain) is being offboarded. OutgoingParathread, /// Parachain is being offboarded. OutgoingParachain, @@ -102,11 +102,11 @@ struct PvfCheckActiveVoteState { #### Para Lifecycle -Because the state changes of parachains and parathreads are delayed, we track the specific state of +Because the state changes of parachains are delayed, we track the specific state of the para using the `ParaLifecycle` enum. ``` -None Parathread Parachain +None Parathread (on-demand parachain) Parachain + + + | | | | (≈2 Session Delay) | | @@ -147,7 +147,7 @@ During the transition period, the para object is still considered in its existin PvfActiveVoteMap: map ValidationCodeHash => PvfCheckActiveVoteState; /// The list of all currently active PVF votes. Auxiliary to `PvfActiveVoteMap`. PvfActiveVoteList: Vec; -/// All parachains. Ordered ascending by ParaId. Parathreads are not included. +/// All parachains. Ordered ascending by ParaId. On-demand parachains are not included. Parachains: Vec, /// The current lifecycle state of all known Para Ids. ParaLifecycle: map ParaId => Option, @@ -229,10 +229,10 @@ CodeByHash: map ValidationCodeHash => Option 1. Apply all incoming paras by initializing the `Heads` and `CurrentCode` using the genesis parameters as well as `MostRecentContext` to `0`. 1. Amend the `Parachains` list and `ParaLifecycle` to reflect changes in registered parachains. - 1. Amend the `ParaLifecycle` set to reflect changes in registered parathreads. - 1. Upgrade all parathreads that should become parachains, updating the `Parachains` list and + 1. Amend the `ParaLifecycle` set to reflect changes in registered on-demand parachains. + 1. Upgrade all on-demand parachains that should become lease holding parachains, updating the `Parachains` list and `ParaLifecycle`. - 1. Downgrade all parachains that should become parathreads, updating the `Parachains` list and + 1. Downgrade all lease holding parachains that should become on-demand parachains, updating the `Parachains` list and `ParaLifecycle`. 1. (Deferred) Return list of outgoing paras to the initializer for use by other modules. 1. Go over all active PVF pre-checking votes: @@ -254,8 +254,8 @@ CodeByHash: map ValidationCodeHash => Option * `schedule_para_initialize(ParaId, ParaGenesisArgs)`: Schedule a para to be initialized at the next session. Noop if para is already registered in the system with some `ParaLifecycle`. * `schedule_para_cleanup(ParaId)`: Schedule a para to be cleaned up after the next full session. -* `schedule_parathread_upgrade(ParaId)`: Schedule a parathread to be upgraded to a parachain. -* `schedule_parachain_downgrade(ParaId)`: Schedule a parachain to be downgraded to a parathread. +* `schedule_parathread_upgrade(ParaId)`: Schedule a parathread (on-demand parachain) to be upgraded to a parachain. +* `schedule_parachain_downgrade(ParaId)`: Schedule a parachain to be downgraded from lease holding to on-demand. * `schedule_code_upgrade(ParaId, new_code, relay_parent: BlockNumber, HostConfiguration)`: Schedule a future code upgrade of the given parachain. In case the PVF pre-checking is disabled, or the new code is already present in the storage, the upgrade will be applied after inclusion of a block of the same parachain executed in the context of a relay-chain block with number >= `relay_parent + config.validation_upgrade_delay`. If the upgrade is scheduled `UpgradeRestrictionSignal` is set and it will remain set until `relay_parent + config.validation_upgrade_cooldown`. @@ -263,12 +263,12 @@ In case the PVF pre-checking is enabled, or the new code is not already present * `note_new_head(ParaId, HeadData, BlockNumber)`: note that a para has progressed to a new head, where the new head was executed in the context of a relay-chain block with given number, the latter value is inserted into the `MostRecentContext` mapping. This will apply pending code upgrades based on the block number provided. If an upgrade took place it will clear the `UpgradeGoAheadSignal`. * `lifecycle(ParaId) -> Option`: Return the `ParaLifecycle` of a para. -* `is_parachain(ParaId) -> bool`: Returns true if the para ID references any live parachain, - including those which may be transitioning to a parathread in the future. -* `is_parathread(ParaId) -> bool`: Returns true if the para ID references any live parathread, - including those which may be transitioning to a parachain in the future. -* `is_valid_para(ParaId) -> bool`: Returns true if the para ID references either a live parathread - or live parachain. +* `is_parachain(ParaId) -> bool`: Returns true if the para ID references any live lease holding parachain, + including those which may be transitioning to an on-demand parachain in the future. +* `is_parathread(ParaId) -> bool`: Returns true if the para ID references any live parathread (on-demand parachain), + including those which may be transitioning to a lease holding parachain in the future. +* `is_valid_para(ParaId) -> bool`: Returns true if the para ID references either a live on-demand parachain + or live lease holding parachain. * `can_upgrade_validation_code(ParaId) -> bool`: Returns true if the given para can signal code upgrade right now. * `pvfs_require_prechecking() -> Vec`: Returns the list of PVF validation code hashes that require PVF pre-checking votes. diff --git a/roadmap/implementers-guide/src/runtime/scheduler.md b/roadmap/implementers-guide/src/runtime/scheduler.md index 7383177aa1cb..312ecedcb50f 100644 --- a/roadmap/implementers-guide/src/runtime/scheduler.md +++ b/roadmap/implementers-guide/src/runtime/scheduler.md @@ -1,24 +1,24 @@ -# Scheduler Module +# Scheduler Pallet > TODO: this section is still heavily under construction. key questions about availability cores and validator assignment are still open and the flow of the the section may be contradictory or inconsistent The Scheduler module is responsible for two main tasks: -- Partitioning validators into groups and assigning groups to parachains and parathreads. -- Scheduling parachains and parathreads +- Partitioning validators into groups and assigning groups to parachains. +- Scheduling parachains for each block It aims to achieve these tasks with these goals in mind: - It should be possible to know at least a block ahead-of-time, ideally more, which validators are going to be assigned to which parachains. - Parachains that have a candidate pending availability in this fork of the chain should not be assigned. - Validator assignments should not be gameable. Malicious cartels should not be able to manipulate the scheduler to assign themselves as desired. -- High or close to optimal throughput of parachains and parathreads. Work among validator groups should be balanced. +- High or close to optimal throughput of parachains. Work among validator groups should be balanced. ## Availability Cores -The Scheduler manages resource allocation using the concept of "Availability Cores". There will be one availability core for each parachain, and a fixed number of cores used for multiplexing parathreads. Validators will be partitioned into groups, with the same number of groups as availability cores. Validator groups will be assigned to different availability cores over time. +The Scheduler manages resource allocation using the concept of "Availability Cores". There will be one availability core for each lease holding parachain, and a fixed number of cores used for multiplexing on-demand parachains. Validators will be partitioned into groups, with the same number of groups as availability cores. Validator groups will be assigned to different availability cores over time. -An availability core can exist in either one of two states at the beginning or end of a block: free or occupied. A free availability core can have a parachain or parathread assigned to it for the potential to have a backed candidate included. After backing, the core enters the occupied state as the backed candidate is pending availability. There is an important distinction: a core is not considered occupied until it is in charge of a block pending availability, although the implementation may treat scheduled cores the same as occupied ones for brevity. A core exits the occupied state when the candidate is no longer pending availability - either on timeout or on availability. A core starting in the occupied state can move to the free state and back to occupied all within a single block, as availability bitfields are processed before backed candidates. At the end of the block, there is a possible timeout on availability which can move the core back to the free state if occupied. +An availability core can exist in either one of two states at the beginning or end of a block: free or occupied. A free availability core can have a lease holding or on-demand parachain assigned to it for the potential to have a backed candidate included. After backing, the core enters the occupied state as the backed candidate is pending availability. There is an important distinction: a core is not considered occupied until it is in charge of a block pending availability, although the implementation may treat scheduled cores the same as occupied ones for brevity. A core exits the occupied state when the candidate is no longer pending availability - either on timeout or on availability. A core starting in the occupied state can move to the free state and back to occupied all within a single block, as availability bitfields are processed before backed candidates. At the end of the block, there is a possible timeout on availability which can move the core back to the free state if occupied. Cores are treated as an ordered list and are typically referred to by their index in that list. @@ -82,54 +82,57 @@ digraph { ## Validator Groups -Validator group assignments do not need to change very quickly. The security benefits of fast rotation are redundant with the challenge mechanism in the [Approval process](../protocol-approval.md). Because of this, we only divide validators into groups at the beginning of the session and do not shuffle membership during the session. However, we do take steps to ensure that no particular validator group has dominance over a single parachain or parathread-multiplexer for an entire session to provide better guarantees of live-ness. +Validator group assignments do not need to change very quickly. The security benefits of fast rotation are redundant with the challenge mechanism in the [Approval process](../protocol-approval.md). Because of this, we only divide validators into groups at the beginning of the session and do not shuffle membership during the session. However, we do take steps to ensure that no particular validator group has dominance over a single lease holding parachain or on-demand parachain-multiplexer for an entire session to provide better guarantees of live-ness. Validator groups rotate across availability cores in a round-robin fashion, with rotation occurring at fixed intervals. The i'th group will be assigned to the `(i+k)%n`'th core at any point in time, where `k` is the number of rotations that have occurred in the session, and `n` is the number of cores. This makes upcoming rotations within the same session predictable. -When a rotation occurs, validator groups are still responsible for distributing availability chunks for any previous cores that are still occupied and pending availability. In practice, rotation and availability-timeout frequencies should be set so this will only be the core they have just been rotated from. It is possible that a validator group is rotated onto a core which is currently occupied. In this case, the validator group will have nothing to do until the previously-assigned group finishes their availability work and frees the core or the availability process times out. Depending on if the core is for a parachain or parathread, a different timeout `t` from the [`HostConfiguration`](../types/runtime.md#host-configuration) will apply. Availability timeouts should only be triggered in the first `t-1` blocks after the beginning of a rotation. +When a rotation occurs, validator groups are still responsible for distributing availability chunks for any previous cores that are still occupied and pending availability. In practice, rotation and availability-timeout frequencies should be set so this will only be the core they have just been rotated from. It is possible that a validator group is rotated onto a core which is currently occupied. In this case, the validator group will have nothing to do until the previously-assigned group finishes their availability work and frees the core or the availability process times out. Depending on if the core is for a lease holding parachain or on-demand parachain, a different timeout `t` from the [`HostConfiguration`](../types/runtime.md#host-configuration) will apply. Availability timeouts should only be triggered in the first `t-1` blocks after the beginning of a rotation. ## Claims -Parathreads operate on a system of claims. Collators participate in auctions to stake a claim on authoring the next block of a parathread, although the auction mechanism is beyond the scope of the scheduler. The scheduler guarantees that they'll be given at least a certain number of attempts to author a candidate that is backed. Attempts that fail during the availability phase are not counted, since ensuring availability at that stage is the responsibility of the backing validators, not of the collator. When a claim is accepted, it is placed into a queue of claims, and each claim is assigned to a particular parathread-multiplexing core in advance. Given that the current assignments of validator groups to cores are known, and the upcoming assignments are predictable, it is possible for parathread collators to know who they should be talking to now and how they should begin establishing connections with as a fallback. +On-demand parachains operate on a system of claims. Collators purchase claims on authoring the next block of an on-demand parachain, although the purchase mechanism is beyond the scope of the scheduler. The scheduler guarantees that they'll be given at least a certain number of attempts to author a candidate that is backed. Attempts that fail during the availability phase are not counted, since ensuring availability at that stage is the responsibility of the backing validators, not of the collator. When a claim is accepted, it is placed into a queue of claims, and each claim is assigned to a particular on-demand parachain-multiplexing core in advance. Given that the current assignments of validator groups to cores are known, and the upcoming assignments are predictable, it is possible for on-demand parachain collators to know who they should be talking to now and how they should begin establishing connections with as a fallback. -With this information, the Node-side can be aware of which parathreads have a good chance of being includable within the relay-chain block and can focus any additional resources on backing candidates from those parathreads. Furthermore, Node-side code is aware of which validator group will be responsible for that thread. If the necessary conditions are reached for core reassignment, those candidates can be backed within the same block as the core being freed. +With this information, the Node-side can be aware of which on-demand parachains have a good chance of being includable within the relay-chain block and can focus any additional resources on backing candidates from those on-demand parachains. Furthermore, Node-side code is aware of which validator group will be responsible for that thread. If the necessary conditions are reached for core reassignment, those candidates can be backed within the same block as the core being freed. -Parathread claims, when scheduled onto a free core, may not result in a block pending availability. This may be due to collator error, networking timeout, or censorship by the validator group. In this case, the claims should be retried a certain number of times to give the collator a fair shot. +On-demand claims, when scheduled onto a free core, may not result in a block pending availability. This may be due to collator error, networking timeout, or censorship by the validator group. In this case, the claims should be retried a certain number of times to give the collator a fair shot. ## Storage Utility structs: ```rust -// A claim on authoring the next block for a given parathread. +// A claim on authoring the next block for a given parathread (on-demand parachain). struct ParathreadClaim(ParaId, CollatorId); -// An entry tracking a claim to ensure it does not pass the maximum number of retries. +// An entry tracking a parathread (on-demand parachain) claim to ensure it does not +// pass the maximum number of retries. struct ParathreadEntry { claim: ParathreadClaim, retries: u32, } -// A queued parathread entry, pre-assigned to a core. +// A queued parathread (on-demand parachain) entry, pre-assigned to a core. struct QueuedParathread { claim: ParathreadEntry, - /// offset within the set of para-threads ranged `0..config.parathread_cores`. + /// offset within the set of parathreads (on-demand parachains) ranged `0..config.parathread_cores`. core_offset: u32, } struct ParathreadQueue { queue: Vec, - /// offset within the set of para-threads ranged `0..config.parathread_cores`. + /// offset within the set of parathreads (on-demand parachains) ranged `0..config.parathread_cores`. next_core_offset: u32, } enum CoreOccupied { + // On-demand parachain Parathread(ParathreadEntry), // claim & retries Parachain, } enum AssignmentKind { Parachain, + // On-demand parachain Parathread(CollatorId, u32), } @@ -150,13 +153,13 @@ Storage layout: ```rust /// All the validator groups. One for each core. Indices are into the `ActiveValidators` storage. ValidatorGroups: Vec>; -/// A queue of upcoming claims and which core they should be mapped onto. +/// A queue of upcoming parathread (on-demand parachain) claims and which core they should be mapped onto. ParathreadQueue: ParathreadQueue; /// One entry for each availability core. Entries are `None` if the core is not currently occupied. -/// The i'th parachain belongs to the i'th core, with the remaining cores all being -/// parathread-multiplexers. +/// The i'th parachain lease belongs to the i'th core, with the remaining cores all being +/// on-demand parachain-multiplexers. AvailabilityCores: Vec>; -/// An index used to ensure that only one claim on a parathread exists in the queue or is +/// An index used to ensure that only one claim on a parathread (on-demand parachain) exists in the queue or is /// currently being handled by an occupied core. ParathreadClaimIndex: Vec; /// The block number where the session start occurred. Used to track how many group rotations have occurred. @@ -186,11 +189,11 @@ Actions: - Note that the total number of validators `V` in AV may not be evenly divided by `n_cores`. - The groups are selected by partitioning AV. The first `V % N` groups will have `(V / n_cores) + 1` members, while the remaining groups will have `(V / N)` members each. - Instead of using the indices within AV, which point to the broader set, indices _into_ AV should be used. This implies that groups should have simply ascending validator indices. -1. Prune the parathread queue to remove all retries beyond `configuration.parathread_retries`. - - Also prune all parathread claims corresponding to de-registered parathreads. - - all pruned claims should have their entry removed from the parathread index. - - assign all non-pruned claims to new cores if the number of parathread cores has changed between the `new_config` and `old_config` of the `SessionChangeNotification`. - - Assign claims in equal balance across all cores if rebalancing, and set the `next_core` of the `ParathreadQueue` by incrementing the relative index of the last assigned core and taking it modulo the number of parathread cores. +1. Prune the parathread (on-demand parachain) queue to remove all retries beyond `configuration.parathread_retries`. + - Also prune all on-demand claims corresponding to de-registered parachains. + - all pruned claims should have their entry removed from the parathread (on-demand parachain) index. + - assign all non-pruned claims to new cores if the number of on-demand parachain cores has changed between the `new_config` and `old_config` of the `SessionChangeNotification`. + - Assign claims in equal balance across all cores if rebalancing, and set the `next_core` of the `ParathreadQueue` (on-demand queue) by incrementing the relative index of the last assigned core and taking it modulo the number of on-demand cores. ## Initialization @@ -202,17 +205,17 @@ No finalization routine runs for this module. ## Routines -- `add_parathread_claim(ParathreadClaim)`: Add a parathread claim to the queue. - - Fails if any parathread claim on the same parathread is currently indexed. +- `add_parathread_claim(ParathreadClaim)`: Add a parathread (on-demand parachain) claim to the queue. + - Fails if any on-demand claim on the same parachain is currently indexed. - Fails if the queue length is >= `config.scheduling_lookahead * config.parathread_cores`. - - The core used for the parathread claim is the `next_core` field of the `ParathreadQueue` and adding `Paras::parachains().len()` to it. + - The core used for the on-demand claim is the `next_core` field of the `ParathreadQueue` (on-demand queue) and adding `Paras::parachains().len()` to it. - `next_core` is then updated by adding 1 and taking it modulo `config.parathread_cores`. - The claim is then added to the claim index. - `free_cores(Vec<(CoreIndex, FreedReason)>)`: indicate previosuly-occupied cores which are to be considered returned and why they are being returned. - - All freed parachain cores should be assigned to their respective parachain - - All freed parathread cores whose reason for freeing was `FreedReason::Concluded` should have the claim removed from the claim index. - - All freed parathread cores whose reason for freeing was `FreedReason::TimedOut` should have the claim added to the parathread queue again without retries incremented - - All freed parathread cores should take the next parathread entry from the queue. + - All freed lease holding parachain cores should be assigned to their respective parachain + - All freed on-demand parachain cores whose reason for freeing was `FreedReason::Concluded` should have the claim removed from the claim index. + - All freed on-demand cores whose reason for freeing was `FreedReason::TimedOut` should have the claim added to the parathread queue (on-demand queue) again without retries incremented + - All freed on-demand cores should take the next on-demand parachain entry from the queue. - `schedule(Vec<(CoreIndex, FreedReason)>, now: BlockNumber)`: schedule new core assignments, with a parameter indicating previously-occupied cores which are to be considered returned and why they are being returned. - Invoke `free_cores(freed_cores)` - The i'th validator group will be assigned to the `(i+k)%n`'th core at any point in time, where `k` is the number of rotations that have occurred in the session, and `n` is the total number of cores. This makes upcoming rotations within the same session predictable. Rotations are based off of `now`. @@ -224,9 +227,9 @@ No finalization routine runs for this module. - Since both the availability cores and the newly-occupied cores lists are sorted ascending, this method can be implemented efficiently. - `core_para(CoreIndex) -> ParaId`: return the currently-scheduled or occupied ParaId for the given core. - `group_validators(GroupIndex) -> Option>`: return all validators in a given group, if the group index is valid for this session. -- `availability_timeout_predicate() -> Option bool>`: returns an optional predicate that should be used for timing out occupied cores. if `None`, no timing-out should be done. The predicate accepts the index of the core, and the block number since which it has been occupied. The predicate should be implemented based on the time since the last validator group rotation, and the respective parachain and parathread timeouts, i.e. only within `max(config.chain_availability_period, config.thread_availability_period)` of the last rotation would this return `Some`. +- `availability_timeout_predicate() -> Option bool>`: returns an optional predicate that should be used for timing out occupied cores. if `None`, no timing-out should be done. The predicate accepts the index of the core, and the block number since which it has been occupied. The predicate should be implemented based on the time since the last validator group rotation, and the respective parachain timeouts, i.e. only within `max(config.chain_availability_period, config.thread_availability_period)` of the last rotation would this return `Some`. - `group_rotation_info(now: BlockNumber) -> GroupRotationInfo`: Returns a helper for determining group rotation. -- `next_up_on_available(CoreIndex) -> Option`: Return the next thing that will be scheduled on this core assuming it is currently occupied and the candidate occupying it became available. Returns in `ScheduledCore` format (todo: link to Runtime APIs page; linkcheck doesn't allow this right now). For parachains, this is always the ID of the parachain and no specified collator. For parathreads, this is based on the next item in the `ParathreadQueue` assigned to that core, and is `None` if there isn't one. -- `next_up_on_time_out(CoreIndex) -> Option`: Return the next thing that will be scheduled on this core assuming it is currently occupied and the candidate occupying it timed out. Returns in `ScheduledCore` format (todo: link to Runtime APIs page; linkcheck doesn't allow this right now). For parachains, this is always the ID of the parachain and no specified collator. For parathreads, this is based on the next item in the `ParathreadQueue` assigned to that core, or if there isn't one, the claim that is currently occupying the core. Otherwise `None`. +- `next_up_on_available(CoreIndex) -> Option`: Return the next thing that will be scheduled on this core assuming it is currently occupied and the candidate occupying it became available. Returns in `ScheduledCore` format (todo: link to Runtime APIs page; linkcheck doesn't allow this right now). For lease holding parachains, this is always the ID of the parachain and no specified collator. For on-demand parachains, this is based on the next item in the `ParathreadQueue` (on-demand queue) assigned to that core, and is `None` if there isn't one. +- `next_up_on_time_out(CoreIndex) -> Option`: Return the next thing that will be scheduled on this core assuming it is currently occupied and the candidate occupying it timed out. Returns in `ScheduledCore` format (todo: link to Runtime APIs page; linkcheck doesn't allow this right now). For parachains, this is always the ID of the parachain and no specified collator. For on-demand parachains, this is based on the next item in the `ParathreadQueue` (on-demand queue) assigned to that core, or if there isn't one, the claim that is currently occupying the core. Otherwise `None`. - `clear()`: - - Free all scheduled cores and return parathread claims to queue, with retries incremented. Skip parathreads which no longer exist under paras. + - Free all scheduled cores and return on-demand claims to queue, with retries incremented. Skip on-demand parachains which no longer exist under paras. diff --git a/roadmap/implementers-guide/src/runtime/shared.md b/roadmap/implementers-guide/src/runtime/shared.md index 58845e19a0dc..0f173134e2a2 100644 --- a/roadmap/implementers-guide/src/runtime/shared.md +++ b/roadmap/implementers-guide/src/runtime/shared.md @@ -1,4 +1,4 @@ -# Shared Module +# Shared Pallet This module is responsible for managing shared storage and configuration for other modules. diff --git a/roadmap/implementers-guide/src/types/candidate.md b/roadmap/implementers-guide/src/types/candidate.md index 729c72180ee5..a37f98054c5e 100644 --- a/roadmap/implementers-guide/src/types/candidate.md +++ b/roadmap/implementers-guide/src/types/candidate.md @@ -1,7 +1,7 @@ # Candidate Types Para candidates are some of the most common types, both within the runtime and on the Node-side. -Candidates are the fundamental datatype for advancing parachains and parathreads, encapsulating the collator's signature, the context of the parablock, the commitments to the output, and a commitment to the data which proves it valid. +Candidates are the fundamental datatype for advancing parachains, encapsulating the collator's signature, the context of the parablock, the commitments to the output, and a commitment to the data which proves it valid. In a way, this entire guide is about these candidates: how they are scheduled, constructed, backed, included, and challenged. @@ -142,7 +142,7 @@ struct PersistedValidationData { ## `HeadData` -Head data is a type-safe abstraction around bytes (`Vec`) for the purposes of representing heads of parachains or parathreads. +Head data is a type-safe abstraction around bytes (`Vec`) for the purposes of representing heads of parachains. ```rust struct HeadData(Vec); @@ -150,7 +150,7 @@ struct HeadData(Vec); ## Candidate Commitments -The execution and validation of parachain or parathread candidates produces a number of values which either must be committed to on the relay chain or committed to the state of the relay chain. +The execution and validation of parachain candidates produces a number of values which either must be committed to blocks on the relay chain or committed to the state of the relay chain. ```rust /// Commitments made in a `CandidateReceipt`. Many of these are outputs of validation. diff --git a/roadmap/implementers-guide/src/types/runtime.md b/roadmap/implementers-guide/src/types/runtime.md index 55c0a571b6c8..79da899bd35e 100644 --- a/roadmap/implementers-guide/src/types/runtime.md +++ b/roadmap/implementers-guide/src/types/runtime.md @@ -19,9 +19,9 @@ struct HostConfiguration { pub max_code_size: u32, /// The maximum head-data size, in bytes. pub max_head_data_size: u32, - /// The amount of availability cores to dedicate to parathreads. + /// The amount of availability cores to dedicate to parathreads (on-demand parachains). pub parathread_cores: u32, - /// The number of retries that a parathread author has to submit their block. + /// The number of retries that a parathread (on-demand parachain) author has to submit their block. pub parathread_retries: u32, /// How often parachain groups should be rotated across parachains. pub group_rotation_frequency: BlockNumber, @@ -29,10 +29,10 @@ struct HostConfiguration { /// after inclusion that validators have to make the block available and signal its availability to /// the chain. Must be at least 1. pub chain_availability_period: BlockNumber, - /// The availability period, in blocks, for parathreads. Same as the `chain_availability_period`, + /// The availability period, in blocks, for parathreads (on-demand parachains). Same as the `chain_availability_period`, /// but a differing timeout due to differing requirements. Must be at least 1. pub thread_availability_period: BlockNumber, - /// The amount of blocks ahead to schedule parathreads. + /// The amount of blocks ahead to schedule on-demand parachains. pub scheduling_lookahead: u32, /// The maximum number of validators to have per core. `None` means no maximum. pub max_validators_per_core: Option, @@ -88,7 +88,7 @@ struct HostConfiguration { pub hrmp_channel_max_total_size: u32, /// The maximum number of inbound HRMP channels a parachain is allowed to accept. pub hrmp_max_parachain_inbound_channels: u32, - /// The maximum number of inbound HRMP channels a parathread is allowed to accept. + /// The maximum number of inbound HRMP channels a parathread (on-demand parachain) is allowed to accept. pub hrmp_max_parathread_inbound_channels: u32, /// The maximum size of a message that could ever be put into an HRMP channel. /// @@ -96,7 +96,7 @@ struct HostConfiguration { pub hrmp_channel_max_message_size: u32, /// The maximum number of outbound HRMP channels a parachain is allowed to open. pub hrmp_max_parachain_outbound_channels: u32, - /// The maximum number of outbound HRMP channels a parathread is allowed to open. + /// The maximum number of outbound HRMP channels a parathread (on-demand parachain) is allowed to open. pub hrmp_max_parathread_outbound_channels: u32, /// The maximum number of outbound HRMP messages can be sent by a candidate. /// diff --git a/roadmap/parachains.md b/roadmap/parachains.md index 89e8fdaf3892..9d6c014a1c7c 100644 --- a/roadmap/parachains.md +++ b/roadmap/parachains.md @@ -41,13 +41,13 @@ Category: Runtime Auctioning and registration of parachains. This is already implemented and follows the [Parachain Allocation — Research at W3F](https://research.web3.foundation/en/latest/polkadot/Parachain-Allocation.html) document. -#### *Parathread Auctions* +#### *On-demand Blockspace Purchase* Category: Runtime -Parathreads are pay-as-you-go parachains. This consists of an on-chain mechanism for resolving an auction by collators and ensuring that they author a block. +The blockspace purchasing system for on-demand parachains consists of an on-chain mechanism for resolving block space purchases by collators and ensuring that they author a block. -The node-side portion of parathreads is for collators to actually cast bids and to be configured for which conditions to cast bids under. +The node-side portion of on-demand parachains is for collators to actually purchase blockspace and to configure the conditions in which purchases are made. #### *Validator Assignment* @@ -76,11 +76,11 @@ Category: Networking A black-box networking component for validators or fishermen on a parachain to obtain the PoV block referenced by hash in an attestation, for the purpose of validating. When fetching "current" PoV blocks (close to the head of the chain, or relating to the block currently being built), this should be fast. When fetching "old" PoV blocks, it should be possible and fall back on recovering from the availability erasure-coding. -#### *Parathread Auction Voting* +#### *On-demand Blockspace Purchase* Category: Node, Networking -How and when collators are configured to cast votes in parathread auctions. +How and when collators are configured to purchase on-demand blockspace. #### *Collation Loop* @@ -146,7 +146,7 @@ We will need a network where collators of paras can discover and fetch the relev Category: Runtime -Runtime logic for paras to open and close channels by putting down a deposit. The amount of channels a parathread can open will be limited. Channels that are pending close should remain open until the watermark of the recipient has reached the block height of the close request. +Runtime logic for paras to open and close channels by putting down a deposit. The amount of channels an on-demand parachain can open will be limited. Channels that are pending close should remain open until the watermark of the recipient has reached the block height of the close request. --- ### Fishing/Slashing @@ -197,7 +197,7 @@ The very first phase - this is parachains without slashing (full security) or cr ### Assignment: - Auctions - - Parathread Auctions + - On-demand Blockspace purchase - Validator Assignment ### Agreement: diff --git a/runtime/common/src/assigned_slots.rs b/runtime/common/src/assigned_slots.rs index f2da950d0b16..053f22e5415a 100644 --- a/runtime/common/src/assigned_slots.rs +++ b/runtime/common/src/assigned_slots.rs @@ -160,13 +160,15 @@ pub mod pallet { #[pallet::error] pub enum Error { - /// The specified parachain or parathread is not registered. + /// The specified parachain is not registered. ParaDoesntExist, - /// Not a parathread. + /// Not a parathread (on-demand parachain). NotParathread, - /// Cannot upgrade parathread. + /// Cannot upgrade on-demand parachain to lease holding + /// parachain. CannotUpgrade, - /// Cannot downgrade parachain. + /// Cannot downgrade lease holding parachain to + /// on-demand. CannotDowngrade, /// Permanent or Temporary slot already assigned. SlotAlreadyAssigned, @@ -371,7 +373,7 @@ pub mod pallet { } } - // Force downgrade to parathread (if needed) before end of lease period + // Force downgrade to on-demand parachain (if needed) before end of lease period if is_parachain { if let Err(err) = runtime_parachains::schedule_parachain_downgrade::(id) { // Treat failed downgrade as warning .. slot lease has been cleared, @@ -507,7 +509,7 @@ impl Pallet { TemporarySlots::::contains_key(id) } - /// Returns whether a para is currently a parachain. + /// Returns whether a para is currently a lease holding parachain. fn is_parachain(id: ParaId) -> bool { T::Registrar::is_parachain(id) } @@ -897,7 +899,7 @@ mod tests { ParaId::from(1_u32), )); - // Para is a parachain for PermanentSlotLeasePeriodLength * LeasePeriod blocks + // Para is a lease holding parachain for PermanentSlotLeasePeriodLength * LeasePeriod blocks while block < 9 { println!("block #{}", block); @@ -913,7 +915,7 @@ mod tests { run_to_block(block); } - // Para lease ended, downgraded back to parathread + // Para lease ended, downgraded back to parathread (on-demand parachain) assert_eq!(TestRegistrar::::is_parathread(ParaId::from(1_u32)), true); assert_eq!(Slots::already_leased(ParaId::from(1_u32), 0, 5), false); }); @@ -1080,7 +1082,7 @@ mod tests { assert_eq!(AssignedSlots::active_temporary_slot_count(), 1); // Block 1-5 - // Para is a parachain for TemporarySlotLeasePeriodLength * LeasePeriod blocks + // Para is a lease holding parachain for TemporarySlotLeasePeriodLength * LeasePeriod blocks while block < 6 { println!("block #{}", block); println!("lease period #{}", AssignedSlots::current_lease_period_index()); @@ -1112,7 +1114,7 @@ mod tests { println!("lease period #{}", AssignedSlots::current_lease_period_index()); println!("lease {:?}", Slots::lease(ParaId::from(1_u32))); - // Para lease ended, downgraded back to parathread + // Para lease ended, downgraded back to on-demand parachain assert_eq!(TestRegistrar::::is_parathread(ParaId::from(1_u32)), true); assert_eq!(Slots::already_leased(ParaId::from(1_u32), 0, 3), false); assert_eq!(AssignedSlots::active_temporary_slot_count(), 0); diff --git a/runtime/common/src/integration_tests.rs b/runtime/common/src/integration_tests.rs index cf879e6bb182..6707be94bd6e 100644 --- a/runtime/common/src/integration_tests.rs +++ b/runtime/common/src/integration_tests.rs @@ -382,7 +382,7 @@ fn basic_end_to_end_works() { // User 1 and 2 will own parachains Balances::make_free_balance_be(&account_id(1), 1_000_000_000); Balances::make_free_balance_be(&account_id(2), 1_000_000_000); - // First register 2 parathreads + // First register 2 on-demand parachains let genesis_head = Registrar::worst_head_data(); let validation_code = Registrar::worst_validation_code(); assert_ok!(Registrar::reserve(signed(1))); @@ -414,7 +414,7 @@ fn basic_end_to_end_works() { lease_period_index_start )); - // 2 sessions later they are parathreads + // 2 sessions later they are parathreads (on-demand parachains) run_to_session(START_SESSION_INDEX + 2); assert_eq!(Paras::lifecycle(ParaId::from(para_1)), Some(ParaLifecycle::Parathread)); assert_eq!(Paras::lifecycle(ParaId::from(para_2)), Some(ParaLifecycle::Parathread)); @@ -499,7 +499,7 @@ fn basic_end_to_end_works() { let lease_start_block = start_block + 400 + offset; run_to_block(lease_start_block); - // First slot, Para 1 should be transitioning to Parachain + // First slot, Para 1 should be transitioning to lease holding Parachain assert_eq!( Paras::lifecycle(ParaId::from(para_1)), Some(ParaLifecycle::UpgradingParathread) @@ -815,7 +815,7 @@ fn competing_bids() { #[test] fn basic_swap_works() { - // This test will test a swap between a parachain and parathread works successfully. + // This test will test a swap between a lease holding parachain and on-demand parachain works successfully. new_test_ext().execute_with(|| { assert!(System::block_number().is_one()); /* So events are emitted */ @@ -825,7 +825,7 @@ fn basic_swap_works() { // User 1 and 2 will own paras Balances::make_free_balance_be(&account_id(1), 1_000_000_000); Balances::make_free_balance_be(&account_id(2), 1_000_000_000); - // First register 2 parathreads with different data + // First register 2 on-demand parachains with different data let validation_code = test_validation_code(10); assert_ok!(Registrar::reserve(signed(1))); assert_ok!(Registrar::register( @@ -859,7 +859,7 @@ fn basic_swap_works() { lease_period_index_start )); - // 2 sessions later they are parathreads + // 2 sessions later they are on-demand parachains run_to_session(START_SESSION_INDEX + 2); assert_eq!(Paras::lifecycle(ParaId::from(2000)), Some(ParaLifecycle::Parathread)); assert_eq!(Paras::lifecycle(ParaId::from(2001)), Some(ParaLifecycle::Parathread)); @@ -932,7 +932,7 @@ fn basic_swap_works() { assert_eq!(Paras::lifecycle(ParaId::from(2000)), Some(ParaLifecycle::Parathread)); assert_eq!(Paras::lifecycle(ParaId::from(2001)), Some(ParaLifecycle::Parachain)); - // Deregister parathread + // Deregister on-demand parachain assert_ok!(Registrar::deregister(para_origin(2000).into(), ParaId::from(2000))); // Correct deposit is unreserved assert_eq!(Balances::reserved_balance(&account_id(1)), 100); // crowdloan deposit left over @@ -987,7 +987,7 @@ fn parachain_swap_works() { // User 1 and 2 will own paras Balances::make_free_balance_be(&account_id(1), 1_000_000_000); Balances::make_free_balance_be(&account_id(2), 1_000_000_000); - // First register 2 parathreads with different data + // First register 2 on-demand parachains with different data let validation_code = test_validation_code(10); assert_ok!(Registrar::reserve(signed(1))); assert_ok!(Registrar::register( @@ -1028,7 +1028,7 @@ fn parachain_swap_works() { lease_period_index_start )); - // 2 sessions later they are parathreads + // 2 sessions later they are on-demand parachains run_to_block(starting_block + 20); assert_eq!(Paras::lifecycle(ParaId::from(winner)), Some(ParaLifecycle::Parathread)); @@ -1165,8 +1165,7 @@ fn crowdloan_ending_period_bid() { // User 1 and 2 will own paras Balances::make_free_balance_be(&account_id(1), 1_000_000_000); Balances::make_free_balance_be(&account_id(2), 1_000_000_000); - - // First register 2 parathreads + // First register 2 on-demand parachains let validation_code = test_validation_code(10); assert_ok!(Registrar::reserve(signed(1))); assert_ok!(Registrar::register( @@ -1201,7 +1200,7 @@ fn crowdloan_ending_period_bid() { lease_period_index_start )); - // 2 sessions later they are parathreads + // 2 sessions later they are on-demand parachains run_to_session(START_SESSION_INDEX + 2); assert_eq!(Paras::lifecycle(ParaId::from(2000)), Some(ParaLifecycle::Parathread)); assert_eq!(Paras::lifecycle(ParaId::from(2001)), Some(ParaLifecycle::Parathread)); @@ -1534,7 +1533,7 @@ fn cant_bid_on_existing_lease_periods() { run_to_session(START_SESSION_INDEX); Balances::make_free_balance_be(&account_id(1), 1_000_000_000); - // First register a parathread + // First register an on-demand parachain let validation_code = test_validation_code(10); assert_ok!(Registrar::reserve(signed(1))); assert_ok!(Registrar::register( @@ -1555,7 +1554,7 @@ fn cant_bid_on_existing_lease_periods() { lease_period_index_start )); - // 2 sessions later they are parathreads + // 2 sessions later they are on-demand parachains run_to_session(START_SESSION_INDEX + 2); // Open a crowdloan for Para 1 for slots 0-3 diff --git a/runtime/common/src/mock.rs b/runtime/common/src/mock.rs index 06cc7771dede..f5e4f1f48daa 100644 --- a/runtime/common/src/mock.rs +++ b/runtime/common/src/mock.rs @@ -31,6 +31,7 @@ use std::{cell::RefCell, collections::HashMap}; thread_local! { static OPERATIONS: RefCell> = RefCell::new(Vec::new()); static PARACHAINS: RefCell> = RefCell::new(Vec::new()); + // On-demand parachains static PARATHREADS: RefCell> = RefCell::new(Vec::new()); static LOCKS: RefCell> = RefCell::new(HashMap::new()); static MANAGERS: RefCell>> = RefCell::new(HashMap::new()); @@ -49,6 +50,7 @@ impl Registrar for TestRegistrar { PARACHAINS.with(|x| x.borrow().clone()) } + // Is on-demand parachain fn is_parathread(id: ParaId) -> bool { PARATHREADS.with(|x| x.borrow().binary_search(&id).is_ok()) } @@ -75,7 +77,7 @@ impl Registrar for TestRegistrar { Err(_) => Ok(()), } })?; - // Should not be parathread, then make it. + // Should not be parathread (on-demand parachain), then make it. PARATHREADS.with(|x| { let mut parathreads = x.borrow_mut(); match parathreads.binary_search(&id) { @@ -99,7 +101,7 @@ impl Registrar for TestRegistrar { Err(_) => Ok(()), } })?; - // Remove from parathread. + // Remove from parathreads (on-demand parachains). PARATHREADS.with(|x| { let mut parathreads = x.borrow_mut(); match parathreads.binary_search(&id) { @@ -114,6 +116,8 @@ impl Registrar for TestRegistrar { Ok(()) } + /// If the ParaId corresponds to a parathread (on-demand parachain), + /// then upgrade it to a lease holding parachain fn make_parachain(id: ParaId) -> DispatchResult { PARATHREADS.with(|x| { let mut parathreads = x.borrow_mut(); @@ -144,6 +148,9 @@ impl Registrar for TestRegistrar { }); Ok(()) } + + /// If the ParaId corresponds to a lease holding parachain, then downgrade it to a + /// parathread (on-demand parachain) fn make_parathread(id: ParaId) -> DispatchResult { PARACHAINS.with(|x| { let mut parachains = x.borrow_mut(); diff --git a/runtime/common/src/paras_registrar.rs b/runtime/common/src/paras_registrar.rs index 5ecef73fae1c..8653e6f19123 100644 --- a/runtime/common/src/paras_registrar.rs +++ b/runtime/common/src/paras_registrar.rs @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Polkadot. If not, see . -//! Pallet to handle parathread/parachain registration and related fund management. +//! Pallet to handle parachain registration and related fund management. //! In essence this is a simple wrapper around `paras`. use frame_support::{ @@ -113,13 +113,13 @@ pub mod pallet { type RuntimeOrigin: From<::RuntimeOrigin> + Into::RuntimeOrigin>>; - /// The system's currency for parathread payment. + /// The system's currency for on-demand parachain payment. type Currency: ReservableCurrency; - /// Runtime hook for when a parachain and parathread swap. + /// Runtime hook for when a lease holding parachain and on-demand parachain swap. type OnSwap: crate::traits::OnSwap; - /// The deposit to be paid to run a parathread. + /// The deposit to be paid to run a on-demand parachain. /// This should include the cost for storing the genesis head and validation code. #[pallet::constant] type ParaDeposit: Get>; @@ -155,13 +155,13 @@ pub mod pallet { HeadDataTooLarge, /// Para is not a Parachain. NotParachain, - /// Para is not a Parathread. + /// Para is not a Parathread (on-demand parachain). NotParathread, /// Cannot deregister para CannotDeregister, - /// Cannot schedule downgrade of parachain to parathread + /// Cannot schedule downgrade of lease holding parachain to on-demand parachain CannotDowngrade, - /// Cannot schedule upgrade of parathread to parachain + /// Cannot schedule upgrade of on-demand parachain to lease holding parachain CannotUpgrade, /// Para is locked from manipulation by the manager. Must use parachain or relay chain governance. ParaLocked, @@ -263,7 +263,7 @@ pub mod pallet { /// Deregister a Para Id, freeing all data and returning any deposit. /// - /// The caller must be Root, the `para` owner, or the `para` itself. The para must be a parathread. + /// The caller must be Root, the `para` owner, or the `para` itself. The para must be an on-demand parachain. #[pallet::call_index(2)] #[pallet::weight(::WeightInfo::deregister())] pub fn deregister(origin: OriginFor, id: ParaId) -> DispatchResult { @@ -271,7 +271,7 @@ pub mod pallet { Self::do_deregister(id) } - /// Swap a parachain with another parachain or parathread. + /// Swap a lease holding parachain with another parachain, either on-demand or lease holding. /// /// The origin must be Root, the `para` owner, or the `para` itself. /// @@ -280,8 +280,8 @@ pub mod pallet { /// /// The `ParaId`s remain mapped to the same head data and code so external code can rely on /// `ParaId` to be a long-term identifier of a notional "parachain". However, their - /// scheduling info (i.e. whether they're a parathread or parachain), auction information - /// and the auction deposit are switched. + /// scheduling info (i.e. whether they're an on-demand parachain or lease holding parachain), + /// auction information and the auction deposit are switched. #[pallet::call_index(3)] #[pallet::weight(::WeightInfo::swap())] pub fn swap(origin: OriginFor, id: ParaId, other: ParaId) -> DispatchResult { @@ -301,7 +301,7 @@ pub mod pallet { if PendingSwap::::get(other) == Some(id) { let other_lifecycle = paras::Pallet::::lifecycle(other).ok_or(Error::::NotRegistered)?; - // identify which is a parachain and which is a parathread + // identify which is a lease holding parachain and which is a parathread (on-demand parachain) if id_lifecycle == ParaLifecycle::Parachain && other_lifecycle == ParaLifecycle::Parathread { @@ -345,7 +345,8 @@ pub mod pallet { /// /// This function will reserve a new Para Id to be owned/managed by the origin account. /// The origin account is able to register head data and validation code using `register` to create - /// a parathread. Using the Slots pallet, a parathread can then be upgraded to get a parachain slot. + /// an on-demand parachain. Using the Slots pallet, an on-demand parachain can then be upgraded to + /// a lease holding parachain. /// /// ## Arguments /// - `origin`: Must be called by a `Signed` origin. Becomes the manager/owner of the new para ID. @@ -417,17 +418,17 @@ impl Registrar for Pallet { Some(Paras::::get(id)?.manager) } - // All parachains. Ordered ascending by ParaId. Parathreads are not included. + // All lease holding parachains. Ordered ascending by ParaId. On-demand parachains are not included. fn parachains() -> Vec { paras::Pallet::::parachains() } - // Return if a para is a parathread + // Return if a para is a parathread (on-demand parachain) fn is_parathread(id: ParaId) -> bool { paras::Pallet::::is_parathread(id) } - // Return if a para is a parachain + // Return if a para is a lease holding parachain fn is_parachain(id: ParaId) -> bool { paras::Pallet::::is_parachain(id) } @@ -460,9 +461,9 @@ impl Registrar for Pallet { Self::do_deregister(id) } - // Upgrade a registered parathread into a parachain. + // Upgrade a registered on-demand parachain into a lease holding parachain. fn make_parachain(id: ParaId) -> DispatchResult { - // Para backend should think this is a parathread... + // Para backend should think this is an on-demand parachain... ensure!( paras::Pallet::::lifecycle(id) == Some(ParaLifecycle::Parathread), Error::::NotParathread @@ -475,7 +476,7 @@ impl Registrar for Pallet { Ok(()) } - // Downgrade a registered para into a parathread. + // Downgrade a registered para into a parathread (on-demand parachain). fn make_parathread(id: ParaId) -> DispatchResult { // Para backend should think this is a parachain... ensure!( @@ -602,7 +603,7 @@ impl Pallet { /// Deregister a Para Id, freeing all data returning any deposit. fn do_deregister(id: ParaId) -> DispatchResult { match paras::Pallet::::lifecycle(id) { - // Para must be a parathread, or not exist at all. + // Para must be a parathread (on-demand parachain), or not exist at all. Some(ParaLifecycle::Parathread) | None => {}, _ => return Err(Error::::NotParathread.into()), } @@ -642,7 +643,7 @@ impl Pallet { Ok((ParaGenesisArgs { genesis_head, validation_code, para_kind }, deposit)) } - /// Swap a parachain and parathread, which involves scheduling an appropriate lifecycle update. + /// Swap a lease holding parachain and parathread (on-demand parachain), which involves scheduling an appropriate lifecycle update. fn do_thread_and_chain_swap(to_downgrade: ParaId, to_upgrade: ParaId) { let res1 = runtime_parachains::schedule_parachain_downgrade::(to_downgrade); debug_assert!(res1.is_ok()); @@ -928,16 +929,16 @@ mod tests { conclude_pvf_checking::(&validation_code, VALIDATORS, START_SESSION_INDEX); run_to_session(START_SESSION_INDEX + 2); - // It is now a parathread. + // It is now a parathread (on-demand parachain). assert!(Parachains::is_parathread(para_id)); assert!(!Parachains::is_parachain(para_id)); - // Some other external process will elevate parathread to parachain + // Some other external process will elevate on-demand to lease holding parachain assert_ok!(Registrar::make_parachain(para_id)); run_to_session(START_SESSION_INDEX + 4); - // It is now a parachain. + // It is now a lease holding parachain. assert!(!Parachains::is_parathread(para_id)); assert!(Parachains::is_parachain(para_id)); - // Turn it back into a parathread + // Turn it back into a parathread (on-demand parachain) assert_ok!(Registrar::make_parathread(para_id)); run_to_session(START_SESSION_INDEX + 6); assert!(Parachains::is_parathread(para_id)); @@ -1325,7 +1326,7 @@ mod tests { run_to_session(START_SESSION_INDEX + 2); - // They are now a parathread. + // They are now parathreads (on-demand parachains). assert!(Parachains::is_parathread(para_1)); assert!(Parachains::is_parathread(para_2)); @@ -1336,7 +1337,8 @@ mod tests { Error::::CannotSwap ); - // Some other external process will elevate one parathread to parachain + // Some other external process will elevate one on-demand + // parachain to a lease holding parachain assert_ok!(Registrar::make_parachain(para_1)); // Cannot swap @@ -1357,7 +1359,7 @@ mod tests { run_to_session(START_SESSION_INDEX + 4); - // It is now a parachain. + // It is now a lease holding parachain. assert!(Parachains::is_parachain(para_1)); assert!(Parachains::is_parathread(para_2)); @@ -1518,6 +1520,7 @@ mod benchmarking { } swap { + // On demand parachain let parathread = register_para::(LOWEST_PUBLIC_ID.into()); let parachain = register_para::((LOWEST_PUBLIC_ID + 1).into()); diff --git a/runtime/common/src/paras_sudo_wrapper.rs b/runtime/common/src/paras_sudo_wrapper.rs index 8944e932e9ef..c1c2973568fa 100644 --- a/runtime/common/src/paras_sudo_wrapper.rs +++ b/runtime/common/src/paras_sudo_wrapper.rs @@ -41,22 +41,22 @@ pub mod pallet { #[pallet::error] pub enum Error { - /// The specified parachain or parathread is not registered. + /// The specified parachain is not registered. ParaDoesntExist, - /// The specified parachain or parathread is already registered. + /// The specified parachain is already registered. ParaAlreadyExists, /// A DMP message couldn't be sent because it exceeds the maximum size allowed for a downward /// message. ExceedsMaxMessageSize, /// Could not schedule para cleanup. CouldntCleanup, - /// Not a parathread. + /// Not a parathread (on-demand parachain). NotParathread, - /// Not a parachain. + /// Not a lease holding parachain. NotParachain, - /// Cannot upgrade parathread. + /// Cannot upgrade on-demand parachain to lease holding parachain. CannotUpgrade, - /// Cannot downgrade parachain. + /// Cannot downgrade lease holding parachain to on-demand. CannotDowngrade, } @@ -89,7 +89,7 @@ pub mod pallet { Ok(()) } - /// Upgrade a parathread to a parachain + /// Upgrade a parathread (on-demand parachain) to a lease holding parachain #[pallet::call_index(2)] #[pallet::weight((1_000, DispatchClass::Operational))] pub fn sudo_schedule_parathread_upgrade( @@ -97,7 +97,7 @@ pub mod pallet { id: ParaId, ) -> DispatchResult { ensure_root(origin)?; - // Para backend should think this is a parathread... + // Para backend should think this is a parathread (on-demand parachain)... ensure!( paras::Pallet::::lifecycle(id) == Some(ParaLifecycle::Parathread), Error::::NotParathread, @@ -107,7 +107,7 @@ pub mod pallet { Ok(()) } - /// Downgrade a parachain to a parathread + /// Downgrade a lease holding parachain to an on-demand parachain #[pallet::call_index(3)] #[pallet::weight((1_000, DispatchClass::Operational))] pub fn sudo_schedule_parachain_downgrade( diff --git a/runtime/common/src/slots/mod.rs b/runtime/common/src/slots/mod.rs index 202062fd7ce9..3eaa4bfec870 100644 --- a/runtime/common/src/slots/mod.rs +++ b/runtime/common/src/slots/mod.rs @@ -14,9 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Polkadot. If not, see . -//! Parathread and parachains leasing system. Allows para IDs to be claimed, the code and data to be initialized and -//! parachain slots (i.e. continuous scheduling) to be leased. Also allows for parachains and parathreads to be -//! swapped. +//! Parachains leasing system. Allows para IDs to be claimed, the code and data to be initialized and +//! parachain slots (i.e. continuous scheduling) to be leased. Also allows for lease holding parachains and +//! on-demand parachains to be swapped. //! //! This doesn't handle the mechanics of determining which para ID actually ends up with a parachain lease. This //! must handled by a separately, through the trait interface that this pallet provides or the root dispatchables. @@ -244,7 +244,7 @@ impl Pallet { if lease_periods.len() == 1 { // Just one entry, which corresponds to the now-ended lease period. // - // `para` is now just a parathread. + // `para` is now just an on-demand parachain. // // Unreserve whatever is left. if let Some((who, value)) = &lease_periods[0] { @@ -944,7 +944,7 @@ mod tests { Error::::ParaNotOnboarding ); - // Trying Para 2 again should fail cause they are not currently a parathread + // Trying Para 2 again should fail cause they are not currently an on-demand parachain assert!(Slots::trigger_onboard(RuntimeOrigin::signed(1), 2.into()).is_err()); assert_eq!(TestRegistrar::::operations(), vec![(2.into(), 1, true),]); @@ -1003,6 +1003,7 @@ mod benchmarking { assert_eq!(event, &system_event); } + // Registers a parathread (on-demand parachain) fn register_a_parathread(i: u32) -> (ParaId, T::AccountId) { let para = ParaId::from(i); let leaser: T::AccountId = account("leaser", i, 0); @@ -1051,7 +1052,7 @@ mod benchmarking { }.into()); } - // Worst case scenario, T parathreads onboard, and C parachains offboard. + // Worst case scenario, T on-demand parachains onboard, and C lease holding parachains offboard. manage_lease_period_start { // Assume reasonable maximum of 100 paras at any time let c in 0 .. 100; @@ -1063,14 +1064,14 @@ mod benchmarking { // If there is an offset, we need to be on that block to be able to do lease things. frame_system::Pallet::::set_block_number(T::LeaseOffset::get() + One::one()); - // Make T parathreads + // Make T parathreads (on-demand parachains) let paras_info = (0..t).map(|i| { register_a_parathread::(i) }).collect::>(); T::Registrar::execute_pending_transitions(); - // T parathread are upgrading to parachains + // T on-demand parachains are upgrading to lease holding parachains for (para, leaser) in paras_info { let amount = T::Currency::minimum_balance(); let origin = T::ForceOrigin::try_successful_origin() @@ -1080,7 +1081,7 @@ mod benchmarking { T::Registrar::execute_pending_transitions(); - // C parachains are downgrading to parathreads + // C lease holding parachains are downgrading to on-demand parachains for i in 200 .. 200 + c { let (para, leaser) = register_a_parathread::(i); T::Registrar::make_parachain(para)?; diff --git a/runtime/common/src/traits.rs b/runtime/common/src/traits.rs index f24a5b977968..3fd97c7cb8c7 100644 --- a/runtime/common/src/traits.rs +++ b/runtime/common/src/traits.rs @@ -31,15 +31,16 @@ pub trait Registrar { /// Report the manager (permissioned owner) of a parachain, if there is one. fn manager_of(id: ParaId) -> Option; - /// All parachains. Ordered ascending by `ParaId`. Parathreads are not included. + /// All lease holding parachains. Ordered ascending by `ParaId`. On-demand + /// parachains are not included. fn parachains() -> Vec; - /// Return if a `ParaId` is a Parachain. + /// Return if a `ParaId` is a lease holding Parachain. fn is_parachain(id: ParaId) -> bool { Self::parachains().binary_search(&id).is_ok() } - /// Return if a `ParaId` is a Parathread. + /// Return if a `ParaId` is a Parathread (on-demand parachain). fn is_parathread(id: ParaId) -> bool; /// Return if a `ParaId` is registered in the system. @@ -70,7 +71,7 @@ pub trait Registrar { /// Elevate a para to parachain status. fn make_parachain(id: ParaId) -> DispatchResult; - /// Lower a para back to normal from parachain status. + /// Downgrade lease holding parachain into parathread (on-demand parachain) fn make_parathread(id: ParaId) -> DispatchResult; #[cfg(any(feature = "runtime-benchmarks", test))] @@ -80,7 +81,8 @@ pub trait Registrar { fn worst_validation_code() -> ValidationCode; /// Execute any pending state transitions for paras. - /// For example onboarding to parathread, or parathread to parachain. + /// For example onboarding to on-demand parachain, or upgrading on-demand to + /// lease holding parachain. #[cfg(any(feature = "runtime-benchmarks", test))] fn execute_pending_transitions(); } @@ -250,7 +252,7 @@ pub trait Auctioneer { fn has_won_an_auction(para: ParaId, bidder: &Self::AccountId) -> bool; } -/// Runtime hook for when we swap a parachain and parathread. +/// Runtime hook for when we swap a lease holding parachain and an on-demand parachain. #[impl_trait_for_tuples::impl_for_tuples(30)] pub trait OnSwap { /// Updates any needed state/references to enact a logical swap of two parachains. Identity, diff --git a/runtime/parachains/src/configuration.rs b/runtime/parachains/src/configuration.rs index 05b0ca1fc538..62efc095334d 100644 --- a/runtime/parachains/src/configuration.rs +++ b/runtime/parachains/src/configuration.rs @@ -43,7 +43,7 @@ pub use pallet::*; const LOG_TARGET: &str = "runtime::configuration"; -/// All configuration of the runtime with respect to parachains and parathreads. +/// All configuration of the runtime with respect to parachains. #[derive(Clone, Encode, Decode, PartialEq, sp_core::RuntimeDebug, scale_info::TypeInfo)] #[cfg_attr(feature = "std", derive(serde::Serialize, serde::Deserialize))] pub struct HostConfiguration { @@ -135,7 +135,8 @@ pub struct HostConfiguration { pub max_downward_message_size: u32, /// The maximum number of outbound HRMP channels a parachain is allowed to open. pub hrmp_max_parachain_outbound_channels: u32, - /// The maximum number of outbound HRMP channels a parathread is allowed to open. + /// The maximum number of outbound HRMP channels a parathread (on-demand parachain) is allowed + /// to open. pub hrmp_max_parathread_outbound_channels: u32, /// The deposit that the sender should provide for opening an HRMP channel. pub hrmp_sender_deposit: Balance, @@ -147,7 +148,8 @@ pub struct HostConfiguration { pub hrmp_channel_max_total_size: u32, /// The maximum number of inbound HRMP channels a parachain is allowed to accept. pub hrmp_max_parachain_inbound_channels: u32, - /// The maximum number of inbound HRMP channels a parathread is allowed to accept. + /// The maximum number of inbound HRMP channels a parathread (on-demand parachain) is allowed + /// to accept. pub hrmp_max_parathread_inbound_channels: u32, /// The maximum size of a message that could ever be put into an HRMP channel. /// @@ -163,9 +165,9 @@ pub struct HostConfiguration { /// How long to keep code on-chain, in blocks. This should be sufficiently long that disputes /// have concluded. pub code_retention_period: BlockNumber, - /// The amount of execution cores to dedicate to parathread execution. + /// The amount of execution cores to dedicate to parathread (on-demand parachain) execution. pub parathread_cores: u32, - /// The number of retries that a parathread author has to submit their block. + /// The number of retries that a parathread (on-demand parachain) author has to submit their block. pub parathread_retries: u32, /// How often parachain groups should be rotated across parachains. /// @@ -177,12 +179,12 @@ pub struct HostConfiguration { /// /// Must be at least 1. pub chain_availability_period: BlockNumber, - /// The availability period, in blocks, for parathreads. Same as the `chain_availability_period`, - /// but a differing timeout due to differing requirements. + /// The availability period, in blocks, for parathreads (on-demand parachains). Same as the + /// `chain_availability_period`, but a differing timeout due to differing requirements. /// /// Must be at least 1. pub thread_availability_period: BlockNumber, - /// The amount of blocks ahead to schedule parachains and parathreads. + /// The amount of blocks ahead to schedule parachains. pub scheduling_lookahead: u32, /// The maximum number of validators to have per core. /// @@ -633,7 +635,7 @@ pub mod pallet { }) } - /// Set the number of parathread execution cores. + /// Set the number of parathread (on-demand parachain) execution cores. #[pallet::call_index(6)] #[pallet::weight(( T::WeightInfo::set_config_with_u32(), @@ -646,7 +648,7 @@ pub mod pallet { }) } - /// Set the number of retries for a particular parathread. + /// Set the number of retries for a particular parathread (on-demand parachain). #[pallet::call_index(7)] #[pallet::weight(( T::WeightInfo::set_config_with_u32(), @@ -691,7 +693,7 @@ pub mod pallet { }) } - /// Set the availability period for parathreads. + /// Set the availability period for parathreads (on-demand parachains). #[pallet::call_index(10)] #[pallet::weight(( T::WeightInfo::set_config_with_block_number(), @@ -995,7 +997,7 @@ pub mod pallet { }) } - /// Sets the maximum number of inbound HRMP channels a parathread is allowed to accept. + /// Sets the maximum number of inbound HRMP channels a parathread (on-demand parachain) is allowed to accept. #[pallet::call_index(35)] #[pallet::weight(( T::WeightInfo::set_config_with_u32(), @@ -1040,7 +1042,7 @@ pub mod pallet { }) } - /// Sets the maximum number of outbound HRMP channels a parathread is allowed to open. + /// Sets the maximum number of outbound HRMP channels a parathread (on-demand parachain) is allowed to open. #[pallet::call_index(38)] #[pallet::weight(( T::WeightInfo::set_config_with_u32(), diff --git a/runtime/parachains/src/hrmp.rs b/runtime/parachains/src/hrmp.rs index 993c4a2fcbb2..12ef3a6384e9 100644 --- a/runtime/parachains/src/hrmp.rs +++ b/runtime/parachains/src/hrmp.rs @@ -331,7 +331,7 @@ pub mod pallet { StorageMap<_, Twox64Concat, HrmpChannelId, HrmpOpenChannelRequest>; // NOTE: could become bounded, but we don't have a global maximum for this. - // `HRMP_MAX_INBOUND_CHANNELS_BOUND` are per parachain/parathread, while this storage tracks the + // `HRMP_MAX_INBOUND_CHANNELS_BOUND` are per parachain, while this storage tracks the // global state. #[pallet::storage] pub type HrmpOpenChannelRequestsList = diff --git a/runtime/parachains/src/inclusion/mod.rs b/runtime/parachains/src/inclusion/mod.rs index c77b51f6b6f9..09902dbe39d7 100644 --- a/runtime/parachains/src/inclusion/mod.rs +++ b/runtime/parachains/src/inclusion/mod.rs @@ -14,8 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Polkadot. If not, see . -//! The inclusion pallet is responsible for inclusion and availability of scheduled parachains -//! and parathreads. +//! The inclusion pallet is responsible for inclusion and availability of scheduled parachains. //! //! It is responsible for carrying candidates from being backable to being backed, and then from backed //! to included. diff --git a/runtime/parachains/src/lib.rs b/runtime/parachains/src/lib.rs index 43c5c6441ad9..a80898b97480 100644 --- a/runtime/parachains/src/lib.rs +++ b/runtime/parachains/src/lib.rs @@ -76,12 +76,12 @@ pub fn schedule_para_cleanup(id: primitives::Id) -> Result<(), >::schedule_para_cleanup(id).map_err(|_| ()) } -/// Schedule a parathread to be upgraded to a parachain. +/// Schedule a parathread (on-demand parachain) to be upgraded to a lease holding parachain. pub fn schedule_parathread_upgrade(id: ParaId) -> Result<(), ()> { paras::Pallet::::schedule_parathread_upgrade(id).map_err(|_| ()) } -/// Schedule a parachain to be downgraded to a parathread. +/// Schedule a lease holding parachain to be downgraded to an on-demand parachain. pub fn schedule_parachain_downgrade(id: ParaId) -> Result<(), ()> { paras::Pallet::::schedule_parachain_downgrade(id).map_err(|_| ()) } diff --git a/runtime/parachains/src/paras/mod.rs b/runtime/parachains/src/paras/mod.rs index 68ebd15aeb6a..26d94f4a908c 100644 --- a/runtime/parachains/src/paras/mod.rs +++ b/runtime/parachains/src/paras/mod.rs @@ -18,15 +18,15 @@ //! //! # Tracking State of Paras //! -//! The most important responsibility of this module is to track which parachains and parathreads +//! The most important responsibility of this module is to track which parachains //! are active and what their current state is. The current state of a para consists of the current //! head data and the current validation code (AKA Parachain Validation Function (PVF)). //! //! A para is not considered live until it is registered and activated in this pallet. //! -//! The set of parachains and parathreads cannot change except at session boundaries. This is -//! primarily to ensure that the number and meaning of bits required for the availability bitfields -//! does not change except at session boundaries. +//! The set of parachains cannot change except at session boundaries. This is primarily to ensure +//! that the number and meaning of bits required for the availability bitfields does not change +//! except at session boundaries. //! //! # Validation Code Upgrades //! @@ -61,7 +61,8 @@ //! //! # Para Lifecycle Management //! -//! A para can be in one of the two stable states: it is either a parachain or a parathread. +//! A para can be in one of the two stable states: it is either a lease holding parachain or an +//! on-demand parachain. //! //! However, in order to get into one of those two states, it must first be onboarded. Onboarding //! can be only enacted at session boundaries. Onboarding must take at least one full session. @@ -181,17 +182,17 @@ pub struct ParaPastCodeMeta { /// state will be used to determine the state transition to apply to the para. #[derive(PartialEq, Eq, Clone, Encode, Decode, RuntimeDebug, TypeInfo)] pub enum ParaLifecycle { - /// Para is new and is onboarding as a Parathread or Parachain. + /// Para is new and is onboarding as an on-demand or lease holding Parachain. Onboarding, - /// Para is a Parathread. + /// Para is a Parathread (on-demand parachain). Parathread, - /// Para is a Parachain. + /// Para is a lease holding Parachain. Parachain, - /// Para is a Parathread which is upgrading to a Parachain. + /// Para is a Parathread (on-demand parachain) which is upgrading to a lease holding Parachain. UpgradingParathread, - /// Para is a Parachain which is downgrading to a Parathread. + /// Para is a lease holding Parachain which is downgrading to an on-demand parachain. DowngradingParachain, - /// Parathread is queued to be offboarded. + /// Parathread (on-demand parachain) is queued to be offboarded. OffboardingParathread, /// Parachain is queued to be offboarded. OffboardingParachain, @@ -199,14 +200,14 @@ pub enum ParaLifecycle { impl ParaLifecycle { /// Returns true if parachain is currently onboarding. To learn if the - /// parachain is onboarding as a parachain or parathread, look at the + /// parachain is onboarding as a lease holding or on-demand parachain, look at the /// `UpcomingGenesis` storage item. pub fn is_onboarding(&self) -> bool { matches!(self, ParaLifecycle::Onboarding) } /// Returns true if para is in a stable state, i.e. it is currently - /// a parachain or parathread, and not in any transition state. + /// a lease holding or on-demand parachain, and not in any transition state. pub fn is_stable(&self) -> bool { matches!(self, ParaLifecycle::Parathread | ParaLifecycle::Parachain) } @@ -223,7 +224,7 @@ impl ParaLifecycle { ) } - /// Returns true if para is currently treated as a parathread. + /// Returns true if para is currently treated as a parathread (on-demand parachain). /// This also includes transitioning states, so you may want to combine /// this check with `is_stable` if you specifically want `Paralifecycle::Parathread`. pub fn is_parathread(&self) -> bool { @@ -297,12 +298,12 @@ pub struct ParaGenesisArgs { pub genesis_head: HeadData, /// The initial validation code to use. pub validation_code: ValidationCode, - /// Parachain or Parathread. + /// Lease holding or on-demand parachain. #[cfg_attr(feature = "std", serde(rename = "parachain"))] pub para_kind: ParaKind, } -/// Distinguishes between Parachain and Parathread +/// Distinguishes between lease holding Parachain and Parathread (on-demand parachain) #[derive(PartialEq, Eq, Clone, RuntimeDebug)] pub enum ParaKind { Parathread, @@ -602,9 +603,9 @@ pub mod pallet { CannotOnboard, /// Para cannot be offboarded at this time. CannotOffboard, - /// Para cannot be upgraded to a parachain. + /// Para cannot be upgraded to a lease holding parachain. CannotUpgrade, - /// Para cannot be downgraded to a parathread. + /// Para cannot be downgraded to an on-demand parachain. CannotDowngrade, /// The statement for PVF pre-checking is stale. PvfCheckStatementStale, @@ -640,7 +641,7 @@ pub mod pallet { pub(super) type PvfActiveVoteList = StorageValue<_, Vec, ValueQuery>; - /// All parachains. Ordered ascending by `ParaId`. Parathreads are not included. + /// All lease holding parachains. Ordered ascending by `ParaId`. On demand parachains are not included. /// /// Consider using the [`ParachainsCache`] type of modifying. #[pallet::storage] @@ -1219,7 +1220,7 @@ impl Pallet { // The actions to take are based on the lifecycle of of the paras. // // The final state of any para after the actions queue should be as a - // parachain, parathread, or not registered. (stable states) + // lease holding parachain, on-demand parachain, or not registered. (stable states) // // Returns the list of outgoing paras from the actions queue. fn apply_actions_queue(session: SessionIndex) -> Vec { @@ -1238,17 +1239,17 @@ impl Pallet { Self::initialize_para_now(&mut parachains, para, &genesis_data); } }, - // Upgrade a parathread to a parachain + // Upgrade an on-demand parachain to a lease holding parachain Some(ParaLifecycle::UpgradingParathread) => { parachains.add(para); ParaLifecycles::::insert(¶, ParaLifecycle::Parachain); }, - // Downgrade a parachain to a parathread + // Downgrade a lease holding parachain to an on-demand parachain Some(ParaLifecycle::DowngradingParachain) => { parachains.remove(para); ParaLifecycles::::insert(¶, ParaLifecycle::Parathread); }, - // Offboard a parathread or parachain from the system + // Offboard a lease holding or on-demand parachain from the system Some(ParaLifecycle::OffboardingParachain) | Some(ParaLifecycle::OffboardingParathread) => { parachains.remove(para); @@ -1688,7 +1689,7 @@ impl Pallet { /// /// Will return error if either is true: /// - /// - para is not a stable parachain or parathread (i.e. [`ParaLifecycle::is_stable`] is `false`) + /// - para is not a stable parachain (i.e. [`ParaLifecycle::is_stable`] is `false`) /// - para has a pending upgrade. /// - para has unprocessed messages in its UMP queue. /// @@ -1738,7 +1739,7 @@ impl Pallet { Ok(()) } - /// Schedule a parathread to be upgraded to a parachain. + /// Schedule a parathread (on-demand parachain) to be upgraded to a lease holding parachain. /// /// Will return error if `ParaLifecycle` is not `Parathread`. pub(crate) fn schedule_parathread_upgrade(id: ParaId) -> DispatchResult { @@ -1757,7 +1758,7 @@ impl Pallet { Ok(()) } - /// Schedule a parachain to be downgraded to a parathread. + /// Schedule a lease holding parachain to be downgraded to an on-demand parachain. /// /// Noop if `ParaLifecycle` is not `Parachain`. pub(crate) fn schedule_parachain_downgrade(id: ParaId) -> DispatchResult { @@ -2036,9 +2037,9 @@ impl Pallet { ParaLifecycles::::get(&id).map_or(false, |state| state.is_offboarding()) } - /// Whether a para ID corresponds to any live parachain. + /// Whether a para ID corresponds to any live lease holding parachain. /// - /// Includes parachains which will downgrade to a parathread in the future. + /// Includes lease holding parachains which will downgrade to a on-demand parachains in the future. pub fn is_parachain(id: ParaId) -> bool { if let Some(state) = ParaLifecycles::::get(&id) { state.is_parachain() @@ -2047,9 +2048,9 @@ impl Pallet { } } - /// Whether a para ID corresponds to any live parathread. + /// Whether a para ID corresponds to any live parathread (on-demand parachain). /// - /// Includes parathreads which will upgrade to parachains in the future. + /// Includes on-demand parachains which will upgrade to lease holding parachains in the future. pub fn is_parathread(id: ParaId) -> bool { if let Some(state) = ParaLifecycles::::get(&id) { state.is_parathread() diff --git a/runtime/parachains/src/scheduler.rs b/runtime/parachains/src/scheduler.rs index ccbb237f3ba5..44333183c528 100644 --- a/runtime/parachains/src/scheduler.rs +++ b/runtime/parachains/src/scheduler.rs @@ -14,11 +14,11 @@ // You should have received a copy of the GNU General Public License // along with Polkadot. If not, see . -//! The scheduler module for parachains and parathreads. +//! The scheduler module for parachains. //! //! This module is responsible for two main tasks: -//! - Partitioning validators into groups and assigning groups to parachains and parathreads -//! - Scheduling parachains and parathreads +//! - Partitioning validators into groups and assigning groups to parachains +//! - Scheduling parachains //! //! It aims to achieve these tasks with these goals in mind: //! - It should be possible to know at least a block ahead-of-time, ideally more, @@ -27,11 +27,11 @@ //! should not be assigned. //! - Validator assignments should not be gameable. Malicious cartels should not be able to //! manipulate the scheduler to assign themselves as desired. -//! - High or close to optimal throughput of parachains and parathreads. Work among validator groups should be balanced. +//! - High or close to optimal throughput of parachains. Work among validator groups should be balanced. //! //! The Scheduler manages resource allocation using the concept of "Availability Cores". //! There will be one availability core for each parachain, and a fixed number of cores -//! used for multiplexing parathreads. Validators will be partitioned into groups, with the same +//! used for multiplexing on-demand parachains. Validators will be partitioned into groups, with the same //! number of groups as availability cores. Validator groups will be assigned to different availability cores //! over time. @@ -55,7 +55,7 @@ pub mod migration; const LOG_TARGET: &str = "runtime::scheduler"; -/// A queued parathread entry, pre-assigned to a core. +/// A queued parathread (on-demand parachain) entry, pre-assigned to a core. #[derive(Encode, Decode, TypeInfo)] #[cfg_attr(test, derive(PartialEq, Debug))] pub struct QueuedParathread { @@ -63,7 +63,7 @@ pub struct QueuedParathread { core_offset: u32, } -/// The queue of all parathread claims. +/// The queue of all parathread (on-demand parachain) claims. #[derive(Encode, Decode, TypeInfo)] #[cfg_attr(test, derive(PartialEq, Debug))] pub struct ParathreadClaimQueue { @@ -73,9 +73,10 @@ pub struct ParathreadClaimQueue { } impl ParathreadClaimQueue { - /// Queue a parathread entry to be processed. + /// Queue a parathread (on-demand parachain) entry to be processed. /// - /// Provide the entry and the number of parathread cores, which must be greater than 0. + /// Provide the entry and the number of parathread (on-demand parachain) cores, + /// which must be greater than 0. fn enqueue_entry(&mut self, entry: ParathreadEntry, n_parathread_cores: u32) { let core_offset = self.next_core_offset; self.next_core_offset = (self.next_core_offset + 1) % n_parathread_cores; @@ -117,7 +118,7 @@ pub enum FreedReason { pub enum AssignmentKind { /// A parachain. Parachain, - /// A parathread. + /// A parathread (on-demand parachain). Parathread(CollatorId, u32), } @@ -171,8 +172,9 @@ pub mod pallet { /// broader set of Polkadot validators, but instead just the subset used for parachains during /// this session. /// - /// Bound: The number of cores is the sum of the numbers of parachains and parathread multiplexers. - /// Reasonably, 100-1000. The dominant factor is the number of validators: safe upper bound at 10k. + /// Bound: The number of cores is the sum of the numbers of lease holding parachains and on-demand + /// parachain multiplexers. Reasonably, 100-1000. The dominant factor is the number of validators: + /// safe upper bound at 10k. #[pallet::storage] #[pallet::getter(fn validator_groups)] pub(crate) type ValidatorGroups = StorageValue<_, Vec>, ValueQuery>; @@ -180,26 +182,27 @@ pub mod pallet { /// A queue of upcoming claims and which core they should be mapped onto. /// /// The number of queued claims is bounded at the `scheduling_lookahead` - /// multiplied by the number of parathread multiplexer cores. Reasonably, 10 * 50 = 500. + /// multiplied by the number of parathread (on-demand parachain) multiplexer cores. Reasonably, + /// 10 * 50 = 500. #[pallet::storage] pub(crate) type ParathreadQueue = StorageValue<_, ParathreadClaimQueue, ValueQuery>; /// One entry for each availability core. Entries are `None` if the core is not currently occupied. Can be /// temporarily `Some` if scheduled but not occupied. /// The i'th parachain belongs to the i'th core, with the remaining cores all being - /// parathread-multiplexers. + /// on-demand parachain-multiplexers. /// /// Bounded by the maximum of either of these two values: - /// * The number of parachains and parathread multiplexers + /// * The number of lease holding parachains and on-demand parachain multiplexers /// * The number of validators divided by `configuration.max_validators_per_core`. #[pallet::storage] #[pallet::getter(fn availability_cores)] pub(crate) type AvailabilityCores = StorageValue<_, Vec>, ValueQuery>; - /// An index used to ensure that only one claim on a parathread exists in the queue or is - /// currently being handled by an occupied core. + /// An index used to ensure that only one claim on a parathread (on-demand parachain) exists in the queue + /// or is currently being handled by an occupied core. /// - /// Bounded by the number of parathread cores and scheduling lookahead. Reasonably, 10 * 50 = 500. + /// Bounded by the number of parathread (on-demand parachain) cores and scheduling lookahead. Reasonably, 10 * 50 = 500. #[pallet::storage] pub(crate) type ParathreadClaimIndex = StorageValue<_, Vec, ValueQuery>; @@ -215,7 +218,7 @@ pub mod pallet { /// Currently scheduled cores - free but up to be occupied. /// - /// Bounded by the number of cores: one for each parachain and parathread multiplexer. + /// Bounded by the number of cores: one for each lease holding parachain and on-demand parachain multiplexer. /// /// The value contained here will not be valid after the end of a block. Runtime APIs should be used to determine scheduled cores/ /// for the upcoming block. @@ -301,17 +304,17 @@ impl Pallet { ValidatorGroups::::set(groups); } - // prune out all parathread claims with too many retries. + // prune out all parathread (on-demand parachain) claims with too many retries. // assign all non-pruned claims to new cores, if they've changed. ParathreadClaimIndex::::mutate(|claim_index| { - // wipe all parathread metadata if no parathread cores are configured. + // wipe all on-demand metadata if no parathread (on-demand parachain) cores are configured. if config.parathread_cores == 0 { thread_queue = ParathreadClaimQueue { queue: Vec::new(), next_core_offset: 0 }; claim_index.clear(); return } - // prune out all entries beyond retry or that no longer correspond to live parathread. + // prune out all entries beyond retry or that no longer correspond to live parathread (on-demand parachain). thread_queue.queue.retain(|queued| { let will_keep = queued.claim.retries <= config.parathread_retries && >::is_parathread(queued.claim.claim.0); @@ -344,10 +347,11 @@ impl Pallet { >::set(now); } - /// Add a parathread claim to the queue. If there is a competing claim in the queue or currently - /// assigned to a core, this call will fail. This call will also fail if the queue is full. + /// Add a parathread (on-demand parachain) claim to the queue. If there is a competing claim in the + /// queue or currently assigned to a core, this call will fail. This call will also fail if the queue + /// is full. /// - /// Fails if the claim does not correspond to any live parathread. + /// Fails if the claim does not correspond to any live on-demand parachain. #[allow(unused)] pub fn add_parathread_claim(claim: ParathreadClaim) { if !>::is_parathread(claim.0) { @@ -396,7 +400,7 @@ impl Pallet { Some(CoreOccupied::Parathread(entry)) => { match freed_reason { FreedReason::Concluded => { - // After a parathread candidate has successfully been included, + // After a parathread (on-demand parachain) candidate has successfully been included, // open it up for further claims! ParathreadClaimIndex::::mutate(|index| { if let Ok(i) = index.binary_search(&entry.claim.0) { @@ -405,7 +409,7 @@ impl Pallet { }) }, FreedReason::TimedOut => { - // If a parathread candidate times out, it's not the collator's fault, + // If a parathread (on-demand parachain) candidate times out, it's not the collator's fault, // so we don't increment retries. ParathreadQueue::::mutate(|queue| { queue.enqueue_entry(entry, config.parathread_cores); @@ -485,7 +489,7 @@ impl Pallet { core, }) } else { - // parathread core offset, rel. to beginning. + // parathread (on-demand parachain) core offset, rel. to beginning. let core_offset = (core_index - parachains.len()) as u32; parathread_queue.take_next_on_core(core_offset).map(|entry| CoreAssignment { @@ -613,7 +617,7 @@ impl Pallet { /// Returns an optional predicate that should be used for timing out occupied cores. /// /// If `None`, no timing-out should be done. The predicate accepts the index of the core, and the - /// block number since which it has been occupied, and the respective parachain and parathread + /// block number since which it has been occupied, and the respective lease holding and on-demand parachain /// timeouts, i.e. only within `max(config.chain_availability_period, config.thread_availability_period)` /// of the last rotation would this return `Some`, unless there are no rotations. /// @@ -673,8 +677,8 @@ impl Pallet { /// Return the next thing that will be scheduled on this core assuming it is currently /// occupied and the candidate occupying it became available. /// - /// For parachains, this is always the ID of the parachain and no specified collator. - /// For parathreads, this is based on the next item in the `ParathreadQueue` assigned to that + /// For lease holding parachains, this is always the ID of the parachain and no specified collator. + /// For on-demand parachains, this is based on the next item in the `ParathreadQueue` assigned to that /// core, and is None if there isn't one. pub(crate) fn next_up_on_available(core: CoreIndex) -> Option { let parachains = >::parachains(); @@ -693,8 +697,8 @@ impl Pallet { /// Return the next thing that will be scheduled on this core assuming it is currently /// occupied and the candidate occupying it became available. /// - /// For parachains, this is always the ID of the parachain and no specified collator. - /// For parathreads, this is based on the next item in the `ParathreadQueue` assigned to that + /// For lease holding parachains, this is always the ID of the parachain and no specified collator. + /// For on-demand parachains, this is based on the next item in the `ParathreadQueue` assigned to that /// core, or if there isn't one, the claim that is currently occupying the core, as long /// as the claim's retries would not exceed the limit. Otherwise None. pub(crate) fn next_up_on_time_out(core: CoreIndex) -> Option { @@ -729,7 +733,7 @@ impl Pallet { } } - // Free all scheduled cores and return parathread claims to queue, with retries incremented. + // Free all scheduled cores and return parathread (on-demand parachain) claims to queue, with retries incremented. pub(crate) fn clear() { let config = >::config(); ParathreadQueue::::mutate(|queue| { diff --git a/runtime/parachains/src/scheduler/tests.rs b/runtime/parachains/src/scheduler/tests.rs index be77ec03ed84..aa99008d18e6 100644 --- a/runtime/parachains/src/scheduler/tests.rs +++ b/runtime/parachains/src/scheduler/tests.rs @@ -170,7 +170,7 @@ fn add_parathread_claim_works() { ); } - // claims on non-live parathreads have no effect. + // claims on non-live parathreads (on-demand parachains) have no effect. { let thread_id2 = ParaId::from(11); Scheduler::add_parathread_claim(ParathreadClaim(thread_id2, collator.clone())); @@ -276,7 +276,7 @@ fn session_change_prunes_cores_beyond_retries_and_those_from_non_live_parathread 4, ); - // Will be pruned: not a live parathread. + // Will be pruned: not a live parathread (on-demand parachain). queue.enqueue_entry( ParathreadEntry { claim: ParathreadClaim(thread_d, collator.clone()), retries: 0 }, 4, @@ -450,11 +450,11 @@ fn schedule_schedules() { new_test_ext(genesis_config).execute_with(|| { assert_eq!(default_config().parathread_cores, 3); - // register 2 parachains + // register 2 lease holding parachains schedule_blank_para(chain_a, ParaKind::Parachain); schedule_blank_para(chain_b, ParaKind::Parachain); - // and 3 parathreads + // and 3 parathreads (on-demand parachains) schedule_blank_para(thread_a, ParaKind::Parathread); schedule_blank_para(thread_b, ParaKind::Parathread); schedule_blank_para(thread_c, ParaKind::Parathread); @@ -498,7 +498,7 @@ fn schedule_schedules() { ); } - // add a couple of parathread claims. + // add a couple of parathread (on-demand parachain) claims. Scheduler::add_parathread_claim(ParathreadClaim(thread_a, collator.clone())); Scheduler::add_parathread_claim(ParathreadClaim(thread_c, collator.clone())); @@ -571,11 +571,11 @@ fn schedule_schedules_including_just_freed() { new_test_ext(genesis_config).execute_with(|| { assert_eq!(default_config().parathread_cores, 3); - // register 2 parachains + // register 2 lease holding parachains schedule_blank_para(chain_a, ParaKind::Parachain); schedule_blank_para(chain_b, ParaKind::Parachain); - // and 5 parathreads + // and 5 parathreads (on-demand parachains) schedule_blank_para(thread_a, ParaKind::Parathread); schedule_blank_para(thread_b, ParaKind::Parathread); schedule_blank_para(thread_c, ParaKind::Parathread); @@ -598,7 +598,7 @@ fn schedule_schedules_including_just_freed() { _ => None, }); - // add a couple of parathread claims now that the parathreads are live. + // add a couple of parathread (on-demand parachain) claims now that the on-demand parachains are live. Scheduler::add_parathread_claim(ParathreadClaim(thread_a, collator.clone())); Scheduler::add_parathread_claim(ParathreadClaim(thread_c, collator.clone())); @@ -621,9 +621,9 @@ fn schedule_schedules_including_just_freed() { assert!(Scheduler::scheduled().is_empty()); } - // add a couple more parathread claims - the claim on `b` will go to the 3rd parathread core (4) - // and the claim on `d` will go back to the 1st parathread core (2). The claim on `e` then - // will go for core `3`. + // add a couple more parathread (on-demand parachain) claims - the claim on `b` will go to + // the 3rd on-demand core (4) and the claim on `d` will go back to the 1st on-demand + // core (2). The claim on `e` then will go for core `3`. Scheduler::add_parathread_claim(ParathreadClaim(thread_b, collator.clone())); Scheduler::add_parathread_claim(ParathreadClaim(thread_d, collator.clone())); Scheduler::add_parathread_claim(ParathreadClaim(thread_e, collator.clone())); @@ -633,8 +633,8 @@ fn schedule_schedules_including_just_freed() { { let scheduled = Scheduler::scheduled(); - // cores 0 and 1 are occupied by parachains. cores 2 and 3 are occupied by parathread - // claims. core 4 was free. + // cores 0 and 1 are occupied by lease holding parachains. cores 2 and 3 are occupied by + // on-demand parachain claims. core 4 was free. assert_eq!(scheduled.len(), 1); assert_eq!( scheduled[0], @@ -812,7 +812,7 @@ fn schedule_rotates_groups() { let config = { let mut config = default_config(); - // make sure parathread requests don't retry-out + // make sure parathread (on-demand parachain) requests don't retry-out config.parathread_retries = config.group_rotation_frequency * 3; config.parathread_cores = 2; config diff --git a/runtime/polkadot/src/lib.rs b/runtime/polkadot/src/lib.rs index ffe7daab5b39..a14bdfc690c2 100644 --- a/runtime/polkadot/src/lib.rs +++ b/runtime/polkadot/src/lib.rs @@ -836,6 +836,7 @@ where } parameter_types! { + // Deposit for a parathread (on-demand parachain) pub const ParathreadDeposit: Balance = 500 * DOLLARS; pub const MaxRetries: u32 = 3; }