# ParaLifecycle Design with Delayed Session Changes

## Design Requirements

> Parachain Configuration and Parachain Registration must wait at least 1 full session.
>
> https://github.com/paritytech/polkadot/issues/2300

A requirement for parachains is that changes to their configuration and registration must wait at least 1 full session before being applied.

i.e. it is currently the middle of session index 3. We queue a parathread to be offboarded. The parathread will offboard at the beginning of session index 5, where we know at least 1 full session has passed.

These queued changes may affect what the parachain is able to do. For example, a parachain and a parathread are allowed to swap roles via the registrar pallet. However, if a parachain already queued to be downgraded to a parathread, or a parathread is queued to be offboarded, then a swap should not be allowed.

Such para objects may have different states in the eyes of different pallets.

For example, if a parathread is queued to be offboarded, then in the eyes of the registrar pallet, the parathread must be off limits for actions like swapping, but the Para ID should remain reserved while the offboarding is queued such that another malicious user does not temporarily gain ownership of the Para ID.

That same parathread may be considered fully funcational in the eyes of a parachain system, where while it is being offboarded, it is still functioning as a parathread and processing messages and producing new blocks.

## Current Design Approach

Due to these requirements, we must be very strict on allowing actions to be queued to a parachain.

We want to avoid a situation like the following:

* Session Index 3: Queue Parathread Onboarding for Session Index 5
* Session Index 4: Queue Upgrade to Parachain for Session Index 6
* Session Index 5: Parathread is onboarded. Queue Swap with parachain for Session Index 7.
* Session Index 6: Parathread is upgraded to Parachain.
* Session Index 7: How do handle swap?

Any situation like above will create a confusing and hard to use API since different pallets may need to know a different kind of state about a parachain, and may need to take into account all possible future transitions.

We will not allow multiple actions to be queued on a para even across multiple sessions. That is to say, if there is an action queued for the para on session index 5, we will not allow any new actions to be queued until session index 5 has passed.

* Session Index 3: Queue Parathread Onboarding for Session Index 5
* Session Index 4: -- No changes allowed --
* Session Index 5: Parathread is onboarded. Queue upgrade to parachain.
* Session Index 6: -- No changes allowed --

Additionally, the Paras module must be the source of truth for the current state of a para. All other pallets must query the paras module to ensure the exact state of a para, including any queued actions.

For example, the registrar pallet must query the paras module to see if a parachain/thread who wants to swap is already queued for some change in some future session. If so, it should reject any request.

### Para Lifecycle States

/// The possible states of a para, to take into account delayed lifecycle changes.
#[derive(PartialEq, Eq, Clone, Encode, Decode, RuntimeDebug)]
pub enum ParaLifecycle {
	/// Para is new and is onboarding as a Parathread or Parachain.
	Onboarding,
	/// Para is a Parathread.
	Parathread,
	/// Para is a Parachain.
	Parachain,
	/// Para is a Parathread which is upgrading to a Parachain.
	UpgradingToParachain,
	/// Para is a Parachain which is downgrading to a Parathread.
	DowngradingToParathread,
	/// Parathread is being offboarded.
	OutgoingParathread,
	/// Parachain is being offboarded.
	OutgoingParachain,
}

### Runtime Storage

/// The queue of actions to take at a specific session index.
ActionsQueue: map SessionIndex => Vec<ParaId>

/// The current lifecycle of all known ParaIds
ParaLifecycles: map hasher(twox_64_concat) ParaId => Option<ParaLifecycle>;

### Open Questions

* Can offboarding be instant?

Issue 2300 says:

> De-registering a parachain would require the same (1 session delay).

My simplified understanding of the design requirements is that we do not want to change any of the validator requirements / assignments without adequate preparation. Would offboarding a parachain actually do this? Wouldn't it be fine to treat the parachains that are offboarded as just not reporting new blocks?

If not, would it be allowable to offboard a parathread instantly?

> Answer: Potentially yes, but would require refactor of scheduler. In general such a feature may be tricky and we should avoid it.

* Should Offboarding Supersede Any Other Queued Changes?

If we are strict to only allow one action to be queued at a time, paras may potentially queue some change to their lifecycle to try and deny the runtime from placing it in the offboarding queue.

Because of this, should offboarding always work no matter what the current action queue of a para is?

> Answer: No. We should rely on returning a result and allowing downstream systems to offboard the parachain properly.

* Should functions which can schedule actions return a result?

If we are strict to only allow one action to be queued at a time, then it may make sense to have any functions which can queue schedule an action to return a result, rather than being a noop as designed today.

This would allow the calling code to know whether the action was successfully queued for that para.

Such functions would return Err if there were any queued actions or if the state of the para was incompatible with the action being queued.

> Answer: Yes