Module polkadot_runtime_parachains::paras

The paras pallet acts as the main registry of paras.

Tracking State of Paras

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 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

When a para signals the validation code upgrade it will be processed by this module. This can be in turn split into more fine grained items:

• Part of the acceptance criteria checks if the para can indeed signal an upgrade,

• When the candidate is enacted, this module schedules code upgrade, storing the prospective validation code.

• Actually assign the prospective validation code to be the current one after all conditions are fulfilled.

The conditions that must be met before the para can use the new validation code are:

1. The validation code should have been “soaked” in the storage for a given number of blocks. That is, the validation code should have been stored in on-chain storage for some time, so that in case of a revert with a non-extreme height difference, that validation code can still be found on-chain.

2. The validation code was vetted by the validators and declared as non-malicious in a processes known as PVF pre-checking.

Validation Code Management

Potentially, one validation code can be used by several different paras. For example, during initial stages of deployment several paras can use the same “shell” validation code, or there can be shards of the same para that use the same validation code.

In case a validation code ceases to have any users it must be pruned from the on-chain storage.

Para Lifecycle Management

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. Moreover, a brand new validation code should go through the PVF pre-checking process.

Once the para is in one of the two stable states, it can switch to the other stable state or to initiate offboarding process. The result of offboarding is removal of all data related to that para.

PVF Pre-checking

As was mentioned above, a brand new validation code should go through a process of approval. As part of this process, validators from the active set will take the validation code and check if it is malicious. Once they did that and have their judgement, either accept or reject, they issue a statement in a form of an unsigned extrinsic. This extrinsic is processed by this pallet. Once supermajority is gained for accept, then the process that initiated the check is resumed (as mentioned before this can be either upgrading of validation code or onboarding). If getting a supermajority becomes impossible (>1/3 of validators have already voted against), then we reject.

Below is a state diagram that depicts states of a single PVF pre-checking vote.

                                           ┌──────────┐
                       supermajority       │          │
                   ┌────────for───────────▶│ accepted │
       vote────┐   │                       │          │
        │      │   │                       └──────────┘
        │      │   │
        │  ┌───────┐
        │  │       │
        └─▶│ init  │──── >1/3 against      ┌──────────┐
           │       │           │           │          │
           └───────┘           └──────────▶│ rejected │
            ▲  │                           │          │
            │  │ session                   └──────────┘
            │  └──change
            │     │
            │     ▼
            ┌─────┐
start──────▶│reset│
            └─────┘

Re-exports

• pub use crate::Origin as ParachainOrigin;
• pub use pallet::*;

Modules

• pallet
  The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.

Structs

• ParaGenesisArgs
  Arguments for initializing a para.
• ParaPastCodeMeta
  Metadata used to track previous parachain validation code that we keep in the state.
• ReplacementTimes
• TestWeightInfo

Enums

• ParaKind
  Distinguishes between lease holding Parachain and Parathread (on-demand parachain)
• ParaLifecycle
  The possible states of a para, to take into account delayed lifecycle changes.

Traits

• WeightInfo