Validator lifecycle and state sync

Joining involves three different kinds of state: an on-chain registry entry, a node's synchronized account state, and an epoch-specific consensus participant set. Registration creates the first. It does not immediately establish the other two.

The current source wires registry instructions into ordinary execution and manages separate Commonware Simplex engine instances for membership epochs. A pending joiner follows the chain until it meets the activation gates; an active validator participates in finalized-block execution. These are implemented source paths, not evidence that an arbitrary public deployment accepts permissionless joins. Check its release and operator configuration first.

This page explains how registration, synchronization and epoch rotation combine into participation. For artifact and configuration steps, use the node setup guide; for flags and defaults, use the CLI reference.

Each role advances state differently

CPU-friendly replica operation does not imply a CPU substitute for GPU-required SBF or CuEVM validation. Choose the build and configuration profile for the role you actually intend to run.

The public CLI's singularity validator join builds and submits registration using the managed consensus identity and configured endpoints. Its printed transaction signature is a submission result. Use node status, transaction status and registry reads to establish what happened afterward. The CLI reference documents the command's stake default, required inputs and confirmation limitation. Validator command dispatch.

Registration creates a pending identity

A Register instruction names the consensus identity, stake account, P2P endpoint and block-server endpoint. The native dispatcher derives the entry and aggregate registry addresses and requires them in the instruction account list. It verifies the identity's transaction signature; registration also requires the stake account to sign and the payer to fund newly created registry accounts.

The program checks a real account balance of at least 100,000,000,000 lamports, or 100 SING, and records that balance in the entry. Each new entry/root account needs 1,000,000 lamports from the payer. The shared aggregate registry account serializes set-wide count and churn decisions so concurrent transactions do not independently act on stale totals. Dispatcher authority and funding.

This registration path samples the supplied stake account's signed balance. It does not itself implement a complete escrow, withdrawal lock or stake-slashing transfer merely by recording stake_amount. Those financial guarantees require their actual stake/account program and enforcement path. The resulting registry entry starts Pending, with no active join epoch and reported synchronized height zero. Duplicate registration and malformed endpoint shapes are rejected. Registration transition.

Registry-only transactions are fee-exempt in the checkout's protocol-5 execution rule, including heartbeats from unfunded consensus identities. Every instruction must target the registry for this exemption; mixing another instruction restores ordinary fees. Registry-account funding is still a separate registration cost. See fee rules.

Follow state before promotion

A fresh non-sequencer needs a usable baseline. Snapshot installation fetches from the configured sequencer block server. Exhausting its bounded retry sequence is fatal when the node would otherwise continue from an incorrect height-zero view. The node exits for supervisor retry instead of quietly serving genesis-like balances. Bootstrap failure.

The snapshot provides account state at height H, but that alone does not provide the real block digest peers use as the parent of H+1. Startup therefore also fetches the canonical-parent candidate from the sequencer and inserts it into the block store. The implementation checks that bytes hash to the supplied digest; it explicitly does not quorum-cross-check that source's claim to canonicality. Parent-fetch boundary.

Pending validators use a gated diff poller because nonparticipants do not yet have consensus-driven execution. It fetches the next height in order and stops once the identity becomes active, preventing the same state from being applied both by the poller and by finalized execution. Read-only replicas keep following diffs. The pull path is the primary live path; the older push producer is dormant. Follow gate and polling.

Replica checks enforce sender allowlisting on the push receiver, ordered application, and a metadata digest. That digest binds height, claimed Merkle root, transaction count and oracle hash, not the diff bytes themselves. Bootstrap likewise uses one configured source without quorum cross-check. A replica is therefore a trusted-source read service, not an independently reexecuting validator. Explicit trust boundary.

Heartbeat, then wait for the boundary

The node's heartbeat sender signs ordinary registry transactions and posts them to the sequencer RPC. The default interval is thirty seconds; ETO_HEARTBEAT_SECS=0 disables it, and ETO_HEARTBEAT_RPC selects the destination. A missing consensus-key file disables the sender. Heartbeats record protocol version, binary hash, kernel hash and monotonically increasing synced_height. Sender startup, heartbeat configuration.

These fields are signed attestations by that identity. The heartbeat path is not a remote measurement of its executable or a cryptographic proof that it executed every reported height.

At new epoch N, promotion requires both:

• N >= registered_epoch + 2: registration in epoch e can first activate at e+2.
• synced_height >= epoch_start(N - 1): the recorded progress clears the preceding epoch's start.

A node that misses either gate stays pending and is reconsidered at a later boundary. The numerical progress gate should not be described as “exactly at the current tip” or as a separately verified state proof. Promotion rules.

Explore membership transitions.

Rotation changes the engine, not just a display field

Epoch processing persists the advancing epoch, handles stake activation/deactivation and rewards, rotates registry entries, and updates the aggregate root. Reward selection uses the on-chain registry when populated rather than a permanently frozen boot-time participant list. The execution pipeline has a boundary barrier so later blocks observe the transition. Epoch processing.

The orchestration layer derives the initial epoch from both recovered configuration and installed height, using the larger value for a snapshot joiner. It derives participants from active/warmdown registry entries when available, otherwise from the boot configuration. An Enter command creates an epoch-specific engine partition and communication subchannels; Exit retires the old handle. Initial participants, engine lifecycle.

A peer claiming a later epoch does not authorize a rotation by itself. Catch-up uses the node's own finalized height and registry state to decide which epoch it can enter. If the peer is ahead of that state, block/state catch-up must happen first.

The transition implementation still contains direct state writes and warning-only handling on some persistence failures. Its existence should not be promoted into an end-to-end authenticated epoch/storage guarantee. The public protocol-v8 service separately reported a durable HILSA root safety pause involving epoch transitions and authenticated state sync; that is a dated deployed observation, documented in availability, rather than a claim that this checkout contains that same gate.

Leave and ejection have distinct contracts

Voluntary deregistration moves an active identity to Warmdown; a later boundary removes it. Pending entries can cancel without first becoming active. Larger active sets have per-boundary churn limits, while small sets have a different exit rule. The pinned sequencer cannot deregister or be ejected because it remains the sole proposer in this design.

Eject marks a target Slashed and adjusts registry membership counts. The dispatcher checks that listed signers actually signed and are unique; the program checks their count against floor(2n/3)+1. The inspected path does not validate the supplied evidence payload, establish that every listed signer is an active registry member, or debit a stake balance. Therefore this interface must not be presented as a complete verified Byzantine-proof slashing mechanism. Eject transition, signature checks.

Recover the same epoch and chain

The default epoch length is 432,000 slots. SVM_SLOTS_PER_EPOCH is read once per process, shared with the Clock sysvar, and must match across nodes. The suggested fresh-testnet value of 200 is not the default and must not be applied casually to an existing chain: it changes the interpretation of past heights. Epoch math.

Strict recovery prefers a valid eight-byte epoch file. If it disagrees with the epoch derived from durable height, it warns and keeps the persisted value. A missing or corrupt epoch file can fall back to readable durable height; if that proof also fails, recovery refuses to guess. The explicit epoch-zero override is an operator escape hatch, not a general recovery instruction. Recovery decisions.

Recovery anchors bind height, not full account state. Equal recovered heights therefore do not prove equal account maps. Follow durability recovery, compare appropriate commitments at a common height, and verify membership before restoring voting or read traffic.

Focused registry tests cover delay, synchronization thresholds, unique-signature checks, account authority and fee exemption. validator_membership_sim exercises lifecycle state transitions and scheme construction; it is not a fleet join/leave acceptance test. This run inspected these paths without executing registration, changing stake or starting consensus engines.