Crate pallet_staking_async_rc_client

Crate pallet_staking_async_rc_client 

Source
Expand description

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.

§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 SessionReports 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.

Re-exports§

pub use pallet::*;

Modules§

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

Macros§

log

Structs§

Offence
An offence on the relay chain. Based on sp_staking::offence::OffenceDetails.
SessionReport
The information that is sent from RC -> AH on session end.
ValidatorSetReport
A report about a new validator set. This is sent from AH -> RC.
XCMSender
Common utility to send XCM messages that can use SplittableMessage.

Traits§

AHStakingInterface
Our communication trait of pallet-staking-async-rc-client -> pallet-staking-async.
RcClientInterface
The communication trait of pallet-staking-async -> pallet-staking-async-rc-client.
SendToAssetHub
The interface to communicate to asset hub.
SendToRelayChain
The communication trait of pallet-staking-async-rc-client -> relay-chain.
SplittableMessage
A trait to encapsulate messages between RC and AH that can be splitted into smaller chunks.