Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kynesys.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
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 codeStatusMeaning
"2"ACTIVEParticipating in consensus, eligible for shard selection.
"3"UNSTAKINGUnstake requested, lock running. Still active until exit.
"0"EXITEDStake withdrawn, removed from active set.
Transitions are driven by four transaction types — each one a reflexive tx signed by the validator’s own key:
FromTxToNotes
(none)validatorStakeACTIVEFirst stake; requires staked_amount ≥ minValidatorStake and a connectionUrl.
ACTIVEvalidatorStakeACTIVETop-up — adds to existing staked_amount.
UNSTAKINGvalidatorStakeACTIVETop-up resets the unstake. unstake_requested_at and unstake_available_at are cleared.
ACTIVEvalidatorUnstakeUNSTAKINGArms the lock period. Validator continues participating in consensus.
UNSTAKINGvalidatorExitEXITEDOnly 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:
  1. Stake → ACTIVE
  2. Submit unstake → UNSTAKING, lock starts at block N
  3. Wait 1001 blocks → lock elapsed
  4. Submit validatorStake (top-up) → adds new stake, but status stays UNSTAKING with the already-elapsed lock
  5. 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:
VariableDefault
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