Quarantine Recovery

Your validator shows as quarantined, banned, or not active, and you need it earning again. This runbook takes you from symptom to fix: diagnose the cause, apply the recovery path for that cause, and escalate only when you actually need to.

For the full model behind these states — strikes, quarantine, bans, and slashing — see Staking Mechanics: Penalties & Validator Lifecycle.

Diagnose the Cause

Before doing anything, find out which state you are in. Run these against your validator wallet address:

# Is my validator in the active set at all?
genlayer staking active-validators
 
# What does the network think of my validator (stake, status, pending ops)?
genlayer staking validator-info 0xYourValidatorWallet...
 
# Am I quarantined?
genlayer staking quarantined-validators
 
# Am I banned — and is it temporary (has an end epoch) or permanent?
genlayer staking banned-validators
 
# What epoch are we in? (needed to know when a temporary ban clears)
genlayer staking epoch-info

Match what you find to one of these causes:

Cause 1: Idleness Strikes (Quarantine / Temporary Ban)

How you got here: your validator was selected for transactions but didn't respond (commit/reveal) in time, accumulated strikes within one epoch, and hit the strike threshold. That bans it for the current and next epoch. A quarantine tied to a deterministic-violation tribunal behaves similarly but resolves when the tribunal does.

Recovery path — wait one epoch, then confirm priming:

1. Confirm it is idleness-based, not a tribunal quarantine: banned-validators will list an end epoch for an idleness ban. Note that epoch.

2. Fix the root cause of the misses so it does not immediately recur — see Prevent idleness strikes below. Recovering only to be re-banned next epoch helps no one.

3. Wait for the ban window to pass. Idleness bans clear automatically at the start of the end epoch — there is no "unban" you need to call. Use epoch-info to watch the current epoch advance past the end epoch.

4. Ensure your node primes for the upcoming epoch so it re-enters the active set the moment the ban lifts:

   genlayer staking validator-info 0xYourValidatorWallet...   # verify priming / pending state

   Priming is normally automatic — your node calls validatorPrime() each epoch. If it isn't happening, treat it as a not-primed problem in parallel.

Prevent Idleness Strikes

Idleness almost always traces back to the node not answering in time when selected. Check, in rough order of likelihood:

• Node health / uptime — the node was down, restarting, or unreachable during a round it was selected for. Keep it running under a supervisor (systemd, screen/tmux, or the Docker restart: unless-stopped policy from the Setup Guide).
• LLM provider reachability — Intelligent Contract execution needs your configured LLM. If the provider is slow, rate-limited, or the API key expired, the node can miss its response window. Verify with ./bin/genlayernode doctor.
• GenVM modules — the web and llm modules must be running (or genvm.manage_modules: true). If they are down, execution stalls.
• ZKSync full node / RPC — a lagging or unreachable GenLayer-chain RPC means the node can't read state or submit votes in time. Confirm the RPC and WebSocket URLs in config.yaml are healthy.
• Clock / sync — a node behind on sync may act on stale slot information and miss phase deadlines.

Cause 2: Below-Minimum Stake (Not Active)

How you got here: "not active" (or "not participating" in the sense of not being in the active set) because your self-stake fell below the minimum — the 42,000 GEN reference minimum for validators. This is distinct from quarantine: you were not penalized, you simply no longer meet the bar for selection. It shows up as a low stake figure in validator-info, and the validator will not appear in any ban or quarantine list.

Recovery path — top up, then re-prime:

1. Deposit enough to get back above the minimum:

   genlayer staking validator-deposit --amount <amount>gen

2. Let the deposit activate. Deposits follow the epoch +2 activation rule — staged one epoch, active the next, and only if validatorPrime() runs in between. Watch it with:

   genlayer staking validator-info 0xYourValidatorWallet...

3. Confirm priming happens across the activation window so the topped-up stake is committed and the validator re-enters the active set.

Cause 3: Not Primed / Version / RPC

How you got here: the validator meets the minimum and isn't banned, but it's missing from the active set because validatorPrime() wasn't called for the upcoming epoch — or the node can't do its job because of a version mismatch or a broken RPC connection. If priming stops, the validator is excluded from the next epoch (no rewards), though its stake is untouched.

Recovery path — restore priming:

1. Verify the node is actually running as a validator, not silently as a full node. This happens when the operator key or validator wallet address is missing from the config — the Setup Guide calls this out explicitly. Both must be set.

2. Run diagnostics:

   ./bin/genlayernode doctor

   This checks consensus-contract accessibility, GenVM module health, LLM connectivity, and ZKSync node reachability — the usual reasons priming silently fails.

3. Check version. Running an outdated node can cause it to fall out of step with the network. List available versions and upgrade if you are behind (see the Upgrade Guide and the Setup Guide download steps).

4. Confirm RPC / WebSocket connectivity. A lagging or unreachable GenLayer-chain RPC prevents the node from priming on time. Verify the genlayerchainrpcurl and genlayerchainwebsocketurl values in config.yaml.

5. If priming must be nudged manually, it is permissionless — anyone can prime a validator:

   genlayer staking validator-prime --validator 0xYourValidatorWallet...

   Longer term, your node should prime automatically every epoch; a manual prime is a stopgap, not a fix for a node that has stopped priming on its own.

When to Escalate

Most states above are self-service. Escalate — rather than wait — when:

• banned-validators flags your validator as permanent. A permanent ban comes from a deterministic-violation conviction (provable fraud), not from downtime, and it does not auto-recover. On testnet, no validator has hit permanent ban, so seeing this is unexpected and worth raising with the team. Recovery generally means standing up a new validator; the banned wallet will not come back on its own.
• A temporary ban does not clear after its end epoch. If epoch-info shows the current epoch has passed the end epoch reported in banned-validators but the validator is still excluded, something is off beyond a normal idleness ban.
• You've corrected the root cause and still can't re-enter the active set after a full activation window — for example, priming succeeds, stake is above minimum, doctor is clean, yet the validator never rejoins active-validators.
• You suspect an incorrect slash or ban. Bans and slashes carry a 2-epoch governance delay specifically so an incorrect penalty can be reversed before it takes effect. If you believe a penalty is wrong, raise it within that window rather than waiting for it to enact.

Quick Reference

Related Resources

• Staking Mechanics: Penalties & Validator Lifecycle — the full model behind these states
• Setup Guide — installation, staking, priming, and running the node
• Upgrade Guide — keeping your node version current
• Monitoring & Telemetry — dashboards and alerting to catch idleness early
• Slashing (concept) — protocol-level slashing rationale
• genlayer staking validator-info · banned-validators · quarantined-validators · validator-deposit · validator-prime · epoch-info