pallet-staking-async-rc-client 0.4.0

The client for the relay chain, intended to be used in AssetHub.

The counter-part for this pallet is pallet-staking-async-ah-client on the relay chain.

This documentation is divided into the following sections:

1. Incoming messages: the messages that we receive from the relay chian.
2. Outgoing messages: the messaged that we sent to the relay chain.
3. Local interfaces: the interfaces that we expose to other pallets in the runtime.

Incoming Messages

All incoming messages are handled via [Call]. They are all gated to be dispatched only by the relay chain origin, as per [Config::RelayChainOrigin].

After potential queuing, they are passed to pallet-staking-async via [AHStakingInterface].

The calls are:

• [Call::relay_session_report]: A report from the relay chain, indicating the end of a session. We allow ourselves to know an implementation detail: The ending of session x always implies start of session x+1 and planning of session x+2. This allows us to have just one message per session.

Note that in the code, due to historical reasons, planning of a new session is called new_session.

• [Call::relay_new_offence_paged]: A report of one or more offences on the relay chain.

Outgoing Messages

The outgoing messages are expressed in [SendToRelayChain].

Local Interfaces

Within this pallet, we need to talk to the staking-async pallet in AH. This is done via [AHStakingInterface] trait.

The staking pallet in AH has no communication with session pallet whatsoever, therefore its implementation of SessionManager, and it associated type SessionInterface no longer exists. Moreover, pallet-staking-async no longer has a notion of timestamp locally, and only relies in the timestamp passed in in the SessionReport.

Shared Types

Note that a number of types need to be shared between this crate and ah-client. For now, as a convention, they are kept in this crate. This can later be decoupled into a shared crate, or sp-staking.

TODO: the rest should go to staking-async docs.

Session Change

Further details of how the session change works follows. These details are important to how pallet-staking-async should rotate sessions/eras going forward.

Synchronous Model

Let's first consider the old school model, when staking and session lived in the same runtime. Assume 3 sessions is one era.

The session pallet issues the following events:

end_session / start_session / new_session (plan session)

• end 0, start 1, plan 2
• end 1, start 2, plan 3 (new validator set returned)
• end 2, start 3 (new validator set activated), plan 4
• end 3, start 4, plan 5
• end 4, start 5, plan 6 (ah-client to already return validator set) and so on.

Staking should then do the following:

• once a request to plan session 3 comes in, it must return a validator set. This is queued internally in the session pallet, and is enacted later.
• at the same time, staking increases its notion of current_era by 1. Yet, active_era is intact. This is because the validator elected for era n+1 are not yet active in the session pallet.
• once a request to start session 3 comes in, staking will rotate its active_era to also be incremented to n+1.

Asynchronous Model

Now, if staking lives in AH and the session pallet lives in the relay chain, how will this look like?

Staking knows that by the time the relay-chain session index 3 (and later on 6 and so on) is planned, it must have already returned a validator set via XCM.

conceptually, staking must:

• listen to the [SessionReport]s coming in, and start a new staking election such that we can be sure it is delivered to the RC well before the the message for planning session 3 received.
• Staking should know that, regardless of the timing, these validators correspond to session 3, and an upcoming era.
• Staking will keep these pending validators internally within its state.
• Once the message to start session 3 is received, staking will act upon it locally.