pvf-precheck: update rustdoc for paras module

Basically updates the docs for the paras module.

runtime/parachains/src/paras.rs

@@ -14,14 +14,97 @@
 // You should have received a copy of the GNU General Public License
 // along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
 
-//! The paras pallet is responsible for storing data on parachains and parathreads.
+//! The paras pallet acts as the main registry of paras.
 //!
-//! It tracks which paras are parachains, what their current head data is in
-//! this fork of the relay chain, what their validation code is, and what their past and upcoming
-//! validation code is.
+//! # Tracking State of Paras
+//!
+//! The most important responsibility of this module is to track which parachains and parathreads
+//! 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.
+//!
+//! # 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 parachain or a parathread.
+//!
+//! 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 supermajority is gained for reject, then the process is canceled.
+//!
+//! Below is a state diagram that depicts states of a single PVF pre-checking vote.
+//!
+//! ```text
+//!                                            ┌──────────┐
+//!                        supermajority       │          │
+//!                    ┌────────for───────────▶│ accepted │
+//!        vote────┐   │                       │          │
+//!         │      │   │                       └──────────┘
+//!         │      │   │
+//!         │  ┌───────┐
+//!         │  │       │
+//!         └─▶│ init  │────supermajority      ┌──────────┐
+//!            │       │       against         │          │
+//!            └───────┘           └──────────▶│ rejected │
+//!             ▲  │                           │          │
+//!             │  │ session                   └──────────┘
+//!             │  └──change
+//!             │     │
+//!             │     ▼
+//!             ┌─────┐
+//! start──────▶│reset│
+//!             └─────┘
+//! ```
 //!
-//! A para is not considered live until it is registered and activated in this pallet. Activation can
-//! only occur at session boundaries.
 
 use crate::{configuration, initializer::SessionChangeNotification, shared};
 use bitvec::{order::Lsb0 as BitOrderLsb0, vec::BitVec};