Validator Lifecycle

A DEMOS validator is an on-chain row in the validators table. Its state machine is enforced by the protocol on every node — the SDK is just one of several ways to drive it.

State machine

Status code	Status	Meaning
`"2"`	`ACTIVE`	Participating in consensus, eligible for shard selection.
`"3"`	`UNSTAKING`	Unstake requested, lock running. Still active until exit.
`"0"`	`EXITED`	Stake withdrawn, removed from active set.

Transitions are driven by four transaction types — each one a reflexive tx signed by the validator’s own key:

From	Tx	To	Notes
(none)	`validatorStake`	`ACTIVE`	First stake; requires `staked_amount ≥ minValidatorStake` and a `connectionUrl`.
`ACTIVE`	`validatorStake`	`ACTIVE`	Top-up — adds to existing `staked_amount`.
`UNSTAKING`	`validatorStake`	`ACTIVE`	Top-up resets the unstake. `unstake_requested_at` and `unstake_available_at` are cleared.
`ACTIVE`	`validatorUnstake`	`UNSTAKING`	Arms the lock period. Validator continues participating in consensus.
`UNSTAKING`	`validatorExit`	`EXITED`	Only valid after the lock has elapsed.

Unstake lock

UNSTAKE_LOCK_BLOCKS = 1000 (≈ 10× the governance voting window). When a validator submits validatorUnstake, the node sets:

unstake_requested_at  = current_block
unstake_available_at  = current_block + UNSTAKE_LOCK_BLOCKS

validatorExit is rejected until current_block ≥ unstake_available_at. The lock window is non-governable. Its purpose is to make vote-and-run attacks economically unattractive: a validator who votes maliciously on a governance proposal cannot exit before the proposal’s tally + grace period (≈ 150 blocks) leaves time for the network to react (slashing is on the Phase-2 roadmap; the lock alone already keeps the malicious stake at risk).

Why restake clears unstake

Without this rule, an attacker could:

Stake → ACTIVE
Submit unstake → UNSTAKING, lock starts at block N
Wait 1001 blocks → lock elapsed
Submit validatorStake (top-up) → adds new stake, but status stays UNSTAKING with the already-elapsed lock
Immediately submit validatorExit → withdraws ALL stake, including the freshly-added portion that never sat under a lock

By forcing the top-up to reset to ACTIVE and clear the unstake timestamps, the protocol guarantees every stake unit sits under a fresh 1000-block lock before exit.

Eligibility & weight

A validator’s staked_amount is the basis for two protocol mechanics:

Shard selection — the consensus layer picks shard members from online validators. Stake doesn’t currently weight the random pick (Phase 2), but it gates eligibility (you must be ACTIVE).
Governance vote weight — a vote’s weight equals the validator’s staked_amount at the proposal’s snapshotBlock. The snapshot freezes weights so unstaking during the voting window does not retroactively reduce a recorded vote.

Persistence guarantees

Validator state changes ride the same atomicity rails as block insertion:

The gcr_edit for a staking tx is attached before the RPC node signs validityData, so it travels through DTR relay and consensus verification untouched.
GCRValidatorStakeRoutines.apply runs on every node when the block containing the tx is committed. The routine is idempotent — replaying the same edit yields the same result.
A failed routine throws inside dataSource.transaction(...) → insertBlock rolls the entire block back. Either every node applies the state transition or none do.

Configuration

Operators control the genesis-state minimum stake via env:

Variable	Default
`MIN_VALIDATOR_STAKE`	`"1000000000000000000"` (10^18, raw bigint)

Once a governance proposal activates a different minValidatorStake, the env value is overridden for the rest of the chain’s life (until the next governance change).

SDK / Validator Staking

stake / unstake / validatorExit builders + read queries

Network Governance

Stackable Genesis: how validator stake feeds vote weight

Internal Mechanisms