Crate pallet_chain_manager

The Chain Manager pallet is the primary orchestration layer for managing session validators as a coordinated, session-driven system.

It governs the full validator lifecycle spanning participation, election, activation, rewards, and penalties by materializing the abstractions defined in frame_suite::blockchain into a concrete runtime execution model.

This pallet does not introduce new primitives. Instead, it binds together traits, plugins, and adapters to drive deterministic validator selection and behavior across sessions, enabling the game-theoretic guarantees required for a decentralized network.

• Config - Runtime configuration
• Call - Dispatchable extrinsics (includes unsigned)
• Pallet - External usage and trait implementations

Overview

A validator (author) in this system is an actor who:

• signals intent to participate in validation,
• submits affidavit data (backers) for election,
• competes in a session-based selection process,
• becomes an active session validator upon selection,
• receives rewards or penalties based on behavior.

Validators are modeled as session-scoped actors, where participation, selection, and compensation are tied to deterministic session transitions.

Architectural Role

The pallet acts as an orchestration boundary, integrating:

• role management and funding via Config::RoleAdapter
• election logic via Config::ElectionAdapter
• asset interactions via Config::Asset
• session and authorship via [pallet_session] and [pallet_authorship]
• offence handling via [pallet_offences]

It only tightly integrates with these essential core pallets, allowing any Substrate runtime that composes them to adopt this pallet for validator lifecycle and session management.

Validator Lifecycle

The system progresses through session-scoped phases:

• Pursuing Validation
  Authors signal intent to validate and may pause participation (chill).

• Affidavit Phase
  Active participants submit affidavit declarations representing election weights for the upcoming validator set.

• Election Phase
  Elections are executed for all active participants to determine the next session validators.

• Activation
  Elected authors transition into active session validators.

• Reward & Penalty
  Validators are compensated or penalized based on behavior.

All transitions are derived relative to session progression, ensuring predictable and deterministic execution.

Execution Model

The pallet operates as a session-driven orchestration engine, primarily driven by offchain workers and unsigned extrinsics.

Once validation intent is externally invoked by an author, the system progresses automatically:

• Offchain workers
  coordinate affidavit submission, election execution, and key rotation

• Unsigned extrinsics
  are submitted to finalize deterministic state transitions

• Block hooks (on_initialize)
  process accumulated state and scheduled transitions

This enables:

• automated validator lifecycle progression
• continuous election participation for active candidates
• minimal manual interaction beyond intent signaling

Economic Model

Rewards and penalties are externally defined and injected:

• Config::InflationModel: derives total session payout
• Config::RewardModel: distributes rewards from points
• Config::PenaltyModel: transforms and normalizes penalties

Final application is delegated via Config::RoleAdapter, ensuring consistent integration with role and funding systems.

Design Intent

This pallet is a composition layer, not a monolithic system:

• structure is defined via traits
• behavior is injected via plugins
• coordination is driven by sessions and routines

enabling a modular, replaceable, and evolvable validator system while preserving strong type safety and deterministic execution.

Development Feature Gate

This pallet includes a dev feature gate for development and testing.

Core functionality is exposed via public APIs for RPC and UI usage. The dev feature provides thin wrapper extrinsics and extended event emissions for direct inspection.

This feature must be disabled in production runtimes due to additional debugging overhead.

Re-exports

pub use crate::crypto::AffidavitCryptoEd25519;

pub use crate::crypto::AffidavitCryptoSr25519;

pub use pallet::*;

Modules

blockchain 🔒

Provides the core runtime logic for managing blockchain actors (authors/validators) across their full lifecycle.

crypto

Affidavit crypto and payload types for offchain operations used for validation, affidavit declaration, and author election

mocks 🔒

offence 🔒

Implements [OnOffenceHandler] for Pallet.

pallet

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

roles 🔒

Implements RoleActivity for Pallet.

routines 🔒

Offchain routines orchestrating the affidavit lifecycle and election execution.

session 🔒

Implements [SessionManager] for Pallet.

types

Core types and aliases for the Chain Manager system.

weights

Autogenerated weights for pallet_chain_manager