ovtools 0.0.0-stage → 1.0.0

package/assets/manage/10-diagnose-node.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# ===================================================================
+# 10-diagnose-node.sh - WHY is this node not voting? (read-only)
+#
+# The state an operator reports as "ready / outside set" can mean four very
+# different things, and they need different actions:
+#
+#   rpc_slow        the node answers /rpc but /status times out -> every tool that
+#                   reads /status reports "rpc unavailable" (stat.sh, enroll.sh)
+#   frozen          head_epoch does not move: catch-up cannot fetch ranges
+#                   (`range_http_unavailable ... state_sync_range_busy`) and the
+#                   consensus ignores every vote (`unresolved_validator_set`)
+#   behind          head_epoch moves, but the node is still far from the network
+#   pm2_mismatch    rejoin.sh refuses: "data directory is used outside PM2" - the
+#                   running process and the pm2 entry disagree about who owns the
+#                   data directory, so the node's own recovery tools refuse to run
+#   outside_set     in sync and healthy, but not admitted by the set (ready/bonded,
+#                   scheduled=false) -> it needs a fold, not a repair
+#   active          fine
+#   recovery        the local store failed its checkpoint check -> recover.sh
+#
+# Nothing here changes anything: it signs nothing, restarts nothing, moves no
+# file. It prints the evidence and one machine line the console reads:
+#
+#   NODE_DIAG state=<class> head=<n> network=<n> behind=<n> rpc=<ready|slow|down>
+#
+# Usage:  sudo bash 10-diagnose-node.sh
+# Env:    HEAD_SAMPLE_SEC=<sec>  how long the head is watched for movement (20)
+#         SYNC_LAG_MAX=<n>       epochs behind that still count as "in sync" (5)
+# ===================================================================
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+
+require_root
+set_status RUNNING "diagnose-node"
+
+ensure_tool jq jq || die "jq is missing and could not be installed"
+ensure_tool curl curl || die "curl is missing and could not be installed"
+[[ -f "${NODE_ENV}" ]] || die "node.env is missing (${NODE_ENV}) - is this the validator host?"
+
+SAMPLE="${HEAD_SAMPLE_SEC:-20}"
+LAG_MAX="${SYNC_LAG_MAX:-5}"
+
+WALLET=$(wallet_address || echo unknown)
+log "=== diagnose ${WALLET} on $(hostname) ==="
+
+# --- 1. the process ------------------------------------------------------
+PS=$(pm2_state)
+log "pm2           : ${PS:-<no entry for $(pm2_name)>}"
+PROC_STATUS=$(printf '%s' "${PS}" | awk '{print $2}')
+case "${PROC_STATUS}" in
+  online) : ;;
+  "")     warn "pm2 has no entry named '$(pm2_name)' - the node is not supervised" ;;
+  *)      warn "pm2 reports '${PROC_STATUS}' for $(pm2_name)" ;;
+esac
+
+# --- 2. RPC: the small call vs the big snapshot --------------------------
+RPC_STATE="down"
+ENROLL=$(rpc_field octra_validatorEnrollment '[]' state)
+HEAD=$(head_epoch)
+CODE=$(status_code)
+if [[ "${HEAD}" =~ ^[0-9]+$ ]]; then
+  RPC_STATE="ready"
+  [[ "${CODE}" == "200" ]] || RPC_STATE="slow"
+fi
+log "rpc           : /rpc=${RPC_STATE} (/status HTTP ${CODE:-000})"
+[[ "${RPC_STATE}" == "slow" ]] && warn "the /status snapshot times out, so stat.sh and enroll.sh status read 'RPC unavailable' even though the node answers /rpc"
+log "enrollment    : state=${ENROLL:-?} head_epoch=${HEAD:-?}"
+BOND_RAW=$(rpc_field octra_validatorEnrollment '[]' bond)
+[[ -n "${BOND_RAW}" ]] && log "bond          : $(raw_to_oct "${BOND_RAW}") OCT"
+
+# --- 3. is head moving? --------------------------------------------------
+HEAD2="${HEAD}"
+if [[ "${HEAD}" =~ ^[0-9]+$ ]] && (( SAMPLE > 0 )); then
+  sleep "${SAMPLE}"
+  HEAD2=$(head_epoch)
+fi
+NET_EPOCH=$(network_epoch)
+BEHIND=""
+if [[ "${HEAD2}" =~ ^[0-9]+$ && "${NET_EPOCH}" =~ ^[0-9]+$ ]]; then
+  BEHIND=$(( NET_EPOCH - HEAD2 ))
+  (( BEHIND < 0 )) && BEHIND=0
+fi
+MOVED=$(( ${HEAD2:-0} - ${HEAD:-0} ))
+log "head          : ${HEAD:-?} -> ${HEAD2:-?} in ${SAMPLE}s (network epoch ${NET_EPOCH:-?}, behind ${BEHIND:-?})"
+
+# --- 4. what the node itself says about the set / catch-up ---------------
+REASON=$(catchup_reason)
+[[ -n "${REASON}" ]] && log "catch-up      : ${REASON}"
+POSTFAIL=$(post_hint)
+[[ -n "${POSTFAIL}" ]] && log "duty post     : ${POSTFAIL}"
+
+# --- 4b. memory and startup progress ------------------------------------
+# A node that opens a 38 GB store on a box that is too small spends its time in
+# GC/swap and never finishes starting: process up, RPC never listening, and no new
+# log line for many minutes (2026-11-06, .99: 5.9 GB RAM, node RSS 4.3 GB).
+MEM_TOTAL=$(awk '/MemTotal/ {printf "%d", $2/1024}' /proc/meminfo 2>/dev/null || echo 0)
+MEM_AVAIL=$(awk '/MemAvailable/ {printf "%d", $2/1024}' /proc/meminfo 2>/dev/null || echo 0)
+NODE_PID=$(pgrep -x octra_node.exe 2>/dev/null | head -1 || true)
+NODE_RSS=""
+[[ -n "${NODE_PID}" ]] && NODE_RSS=$(awk '/VmRSS/ {printf "%d", $2/1024}' "/proc/${NODE_PID}/status" 2>/dev/null || true)
+log "memory        : total=${MEM_TOTAL:-?}MB available=${MEM_AVAIL:-?}MB node_rss=${NODE_RSS:-n/a}MB${NODE_PID:+ (pid ${NODE_PID})}"
+if (( ${MEM_TOTAL:-0} > 0 && MEM_TOTAL < 7600 )); then
+  warn "less than 8 GB of RAM: the store needs ~8 GB (16 comfortable) - GC/swap makes the node slow or unable to finish starting"
+fi
+LOG_AGE=0
+if [[ -f "${NODE_LOG}" ]]; then
+  LAST_TS=$(date -r "${NODE_LOG}" +%s 2>/dev/null || echo 0)
+  LOG_AGE=$(( $(date +%s) - LAST_TS ))
+fi
+if [[ -n "${NODE_PID}" && "${RPC_STATE}" != "ready" && ${LOG_AGE} -ge 300 ]]; then
+  warn "the node has been up for a while without a new log line (${LOG_AGE}s) and its RPC is not answering: startup is stalled"
+fi
+
+# --- 5. the node's own recovery tool (it knows the set rules) ------------
+REJOIN=$(node_script 180 "sh controls/rejoin.sh --check" || true)
+REJOIN_LINE=$(printf '%s\n' "${REJOIN}" | grep -aE '^status = ' | tail -1 || true)
+log "rejoin --check: ${REJOIN_LINE:-<no status line>}"
+REJOIN_REFUSED=$(printf '%s' "${REJOIN_LINE}" | sed -n 's/.*reason = //p')
+PM2_MISMATCH=0
+printf '%s' "${REJOIN_REFUSED}" | grep -qi "used outside PM2" && PM2_MISMATCH=1
+RECOVERY=0
+
+# --- 6. classify ---------------------------------------------------------
+STATE="unknown"
+if (( RECOVERY )); then
+  STATE="recovery"
+elif [[ -n "${NODE_PID}" && "${RPC_STATE}" != "ready" && ${LOG_AGE} -ge 300 ]]; then
+  STATE="startup_stalled"
+elif [[ "${RPC_STATE}" == "down" ]]; then
+  STATE="rpc_down"
+elif (( PM2_MISMATCH )); then
+  STATE="pm2_mismatch"
+elif [[ "${RPC_STATE}" == "slow" && "${MOVED}" -le 0 ]]; then
+  STATE="frozen"
+elif [[ -n "${BEHIND}" ]] && (( BEHIND > LAG_MAX )); then
+  STATE="behind"
+elif (( MOVED <= 0 )); then
+  STATE="frozen"
+elif printf '%s' "${REJOIN_LINE}" | grep -q "validator_active"; then
+  STATE="active"
+elif printf '%s' "${REJOIN_LINE}" | grep -q "validator_scheduled"; then
+  STATE="scheduled"
+elif [[ "${ENROLL}" =~ ^(ready|bonded)$ ]]; then
+  STATE="outside_set"
+fi
+
+case "${STATE}" in
+  active)       log "verdict       : this node is the ACTIVE validator - nothing to fix" ;;
+  scheduled)    log "verdict       : it is in the next set - waiting for the fold, nothing to fix" ;;
+  "outside_set") log "verdict       : in sync and healthy, but not admitted yet (enrollment=${ENROLL}): it needs a set fold, not a repair" ;;
+  frozen)       log "verdict       : head_epoch is not moving, catch-up is blocked (${REASON:-no reason logged}) - a clean restart re-handshakes peers and asks for a fresh range" ;;
+  behind)       log "verdict       : still catching up (${BEHIND} epochs behind) - let it finish before touching the set" ;;
+  "pm2_mismatch") log "verdict       : the node's own tool refuses to run because the data directory is 'used outside PM2' - the pm2 entry and the running process disagree, so the official rejoin path cannot work" ;;
+  "startup_stalled") log "verdict       : the process is up but it stopped logging and its RPC never opened - the node cannot finish opening the store on this VM. Check the RAM line above: the store needs ~8 GB (16 comfortable). With less, GC/swap wins and the node never reaches the network (this is what happened on .99: 5.9 GB box, 4.3 GB node). Options: raise the RAM and start again, or move the node with Migrate node." ;;
+  "rpc_down")   log "verdict       : the local RPC does not answer at all" ;;
+  recovery)     log "verdict       : the local store failed its checkpoint check - the node's own tool asks for recover.sh" ;;
+  *)            log "verdict       : could not be classified from the evidence above" ;;
+esac
+
+printf 'NODE_DIAG state=%s head=%s network=%s behind=%s rpc=%s moved=%s enroll=%s rejoin=%s pm2=%s\n' \
+  "${STATE}" "${HEAD2:-none}" "${NET_EPOCH:-none}" "${BEHIND:-none}" "${RPC_STATE}" "${MOVED}" \
+  "${ENROLL:-none}" "$(printf '%s' "${REJOIN_LINE}" | sed -n 's/^status = \([a-z_]*\).*/\1/p')" \
+  "${PROC_STATUS:-none}"
+
+set_status DONE "state=${STATE} head=${HEAD2:-?} behind=${BEHIND:-?} enrollment=${ENROLL:-?} rpc=${RPC_STATE}"
+
+printf '%s' "${REJOIN_LINE}" | grep -qi "recovery_required" && RECOVERY=1

package/assets/manage/20-exit-validator.sh

@@ -0,0 +1,259 @@
+#!/usr/bin/env bash
+# ===================================================================
+# 20-exit-validator.sh - leave the validator set and get the stake back
+#
+# The node's own controls do the signing; this step drives the whole sequence:
+#
+#   1. `controls/enroll.sh exit`       -> exit intent + exit transaction
+#      (state becomes `exiting`, the duty loop stops publishing readiness)
+#   2. report WHEN the money comes back: the exit epoch the chain recorded and
+#      the epoch the bond unlocks (`withdraw_epoch`), converted to a duration
+#      with the measured epoch cadence - the two numbers the operator asks for
+#   3. if the unbonding is already over: `controls/enroll.sh withdraw` and wait
+#      until `validator_bond` is 0 (the stake is back in the wallet)
+#   4. otherwise: arm octra-exit-withdraw.timer on the host. The timer retries
+#      the withdrawal every 15 minutes - also after a reboot and with the
+#      console closed - and disarms itself once the bond is gone. Nothing has to
+#      be re-run by hand, and no week-long wait happens inside a step.
+#
+# Usage:  sudo bash 20-exit-validator.sh
+# Env:    EXIT_WAIT=<sec>          wait for the set fold (default 900)
+#         WITHDRAW_WAIT=<sec>      wait for the stake after the withdraw (default 900)
+#         STATUS_POLL=<sec>        poll interval (default 20)
+#         EXIT_PROGRESS_SEC=<sec>  progress line interval (default 120)
+#         EPOCH_SECONDS=<sec>      epoch cadence (default: measured from the chain)
+# Idempotent: a second run resumes wherever the first one stopped.
+# ===================================================================
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+
+require_root
+set_status RUNNING "exit-validator"
+
+EXIT_WAIT="${EXIT_WAIT:-900}"
+WITHDRAW_WAIT="${WITHDRAW_WAIT:-900}"
+POLL="${STATUS_POLL:-20}"
+
+ensure_tool jq jq || die "jq is missing and could not be installed"
+[[ -f "${NODE_WALLET}" ]] || die "wallet.json is missing (${NODE_WALLET}) - is this the validator host?"
+[[ -f "${NODE_ENV}" ]] || die "node.env is missing (${NODE_ENV})"
+
+read_state
+ADDR=$(wallet_address || echo unknown)
+log "=== exit validator: ${ADDR} ==="
+log "node: role=${ROLE:-?} process=${PROCESS:-?} rpc=${RPC:-?} voting=${VOTING:-?} epoch=${EPOCH:-?}"
+log "membership: active=${ACTIVE:-?} scheduled=${SCHED:-?} enrollment=${ENROLL:-?} bond=$(raw_to_oct "${BOND:-0}") OCT"
+
+# Already gone? (a previous run finished, or another host did it)
+if [[ "${BOND:-0}" == "0" && "${ENROLL:-}" != "bonded" && "${ENROLL:-}" != "ready" && "${ENROLL:-}" != "exiting" ]]; then
+  log "this wallet holds no bond on chain (enrollment=${ENROLL:-absent}) - nothing to exit"
+  exit_watch_disarm
+  echo "EXIT_DONE bond=0 state=${ENROLL:-absent}"
+  set_status DONE "already exited (enrollment=${ENROLL:-absent}, bond 0)"
+  exit 0
+fi
+
+status_events() { node_script 120 "sh controls/enroll.sh status" || true; }
+
+# one line: state=exiting exit_epoch=123 withdraw_epoch=456 head=789 remaining=8000
+enrollment_summary() {
+  local events state exit_ep withdraw_ep head remaining
+  events=$(status_events)
+  state=$(printf '%s\n' "${events}" | grep -oE 'committed_enrollment state = [a-z]+' | awk '{print $4}' | tail -1 || true)
+  exit_ep=$(printf '%s\n' "${events}" | grep -oE 'exit_epoch = [0-9]+' | awk '{print $3}' | tail -1 || true)
+  withdraw_ep=$(printf '%s\n' "${events}" | grep -oE 'withdraw_epoch = [0-9]+' | awk '{print $3}' | tail -1 || true)
+  head=$(printf '%s\n' "${events}" | grep -oE 'head_epoch = [0-9]+' | awk '{print $3}' | tail -1 || true)
+  remaining=$(printf '%s\n' "${events}" | grep -oE 'remaining_epochs = [0-9]+' | awk '{print $3}' | tail -1 || true)
+  printf 'state=%s exit_epoch=%s withdraw_epoch=%s head=%s remaining=%s\n' \
+    "${state:-unknown}" "${exit_ep:-none}" "${withdraw_ep:-none}" "${head:-0}" "${remaining:-none}"
+}
+
+summary_value() { printf '%s' "$1" | sed -n "s/.*$2=\([^ ]*\).*/\1/p"; }
+
+# The one line the console reads: state, both epochs, epochs left and the
+# duration that follows from the measured cadence. Printed as soon as the chain
+# has recorded the exit, i.e. before any wait - the operator learns the answer
+# at once instead of watching a spinner for a week.
+announce_schedule() {
+  local summary="$1" state exit_ep withdraw_ep head remaining left rate secs eta
+  state=$(summary_value "${summary}" state)
+  exit_ep=$(summary_value "${summary}" exit_epoch)
+  withdraw_ep=$(summary_value "${summary}" withdraw_epoch)
+  head=$(summary_value "${summary}" head)
+  remaining=$(summary_value "${summary}" remaining)
+  rate=""
+  secs=""
+  eta=""
+  if [[ "${state}" == "exiting" && "${withdraw_ep}" =~ ^[0-9]+$ ]]; then
+    [[ "${remaining}" =~ ^[0-9]+$ ]] || remaining=$(( withdraw_ep - ${head:-0} ))
+    (( remaining < 0 )) && remaining=0
+    left="${remaining}"
+    rate=$(epoch_seconds || true)
+    if [[ -n "${rate}" ]]; then
+      secs=$(epoch_eta "${left}" "${rate}" || true)
+      [[ -n "${secs}" ]] && eta=$(fmt_duration "${secs}")
+    fi
+    log "the chain recorded the exit at epoch ${exit_ep}"
+    if (( remaining == 0 )); then
+      log "the unbonding period is over (unlock epoch ${withdraw_ep}, head ${head}) - the stake can be withdrawn"
+    else
+      log "the stake unlocks at epoch ${withdraw_ep}: ${remaining} epoch(s) from head ${head}${eta:+ - about ${eta} at ${rate}s per epoch}"
+    fi
+  fi
+  printf 'EXIT_SCHEDULE state=%s exit_epoch=%s withdraw_epoch=%s head=%s remaining=%s rate=%s eta_seconds=%s\n' \
+    "${state}" "${exit_ep}" "${withdraw_ep}" "${head:-0}" "${left:-none}" "${rate:-none}" "${secs:-none}"
+  SCHED_STATE="${state}"     # the next caller can skip a second measurement
+}
+
+# --- 1. submit the exit ----------------------------------------------
+SUMMARY=$(enrollment_summary)
+log "enrollment: ${SUMMARY}"
+if [[ "${SUMMARY}" == *"state=exiting"* ]]; then
+  log "the exit is already committed - not signing another one"
+else
+  log "submitting the exit (controls/enroll.sh exit) - this pauses the validator duty"
+  set +e
+  OUT=$(node_script 600 "sh controls/enroll.sh exit")
+  RC=$?
+  set -e
+  printf '%s\n' "${OUT}" | sed 's/^/    /'
+  if (( RC != 0 )); then
+    if printf '%s' "${OUT}" | grep -q "already committed"; then
+      log "the exit was already committed on chain - continuing"
+    elif printf '%s' "${OUT}" | grep -qE "refused|retry same command|retained"; then
+      # the node keeps the signed transaction: the same command resumes it and the
+      # exit lands at the next fold. That is a schedule, not an error.
+      warn "the node kept the signed exit transaction: $(printf '%s' "${OUT}" | grep -oE 'reason = .*' | tail -1)"
+      warn "the exit lands at the next set fold - nothing else has to be signed"
+    elif printf '%s' "${OUT}" | grep -q "bond"; then
+      warn "controls/enroll.sh exit reports nothing to exit (or it is already exiting)"
+    else
+      die "controls/enroll.sh exit failed (exit ${RC}) - see the output above"
+    fi
+  fi
+fi
+
+read_state
+SUMMARY=$(enrollment_summary)
+announce_schedule "${SUMMARY}"
+
+# --- 2. wait (bounded) until the set released us and the unbonding is over --
+START=$(date +%s)
+LAST=${START}
+VERDICT=""
+while :; do
+  read_state
+  SUMMARY=$(enrollment_summary)
+  STATE=$(summary_value "${SUMMARY}" state)
+  WITHDRAW_EP=$(summary_value "${SUMMARY}" withdraw_epoch)
+  HEAD=$(summary_value "${SUMMARY}" head)
+  NOW=$(date +%s)
+
+  if [[ "${STATE}" == "absent" && "${BOND:-0}" == "0" ]]; then
+    log "the wallet is out of the set and holds no bond any more"
+    exit_watch_disarm
+    echo "EXIT_DONE bond=0 state=absent"
+    set_status DONE "exited (enrollment absent, bond 0)"
+    exit 0
+  fi
+
+  # withdrawable: exiting + not in the set + unbonding epoch reached
+  if [[ "${STATE}" == "exiting" && "${ACTIVE:-false}" != "true" && "${SCHED:-false}" != "true" ]] \
+     && { [[ -z "${WITHDRAW_EP}" || "${WITHDRAW_EP}" == "none" ]] \
+          || { [[ "${HEAD:-0}" =~ ^[0-9]+$ ]] && [[ "${WITHDRAW_EP}" =~ ^[0-9]+$ ]] && (( HEAD >= WITHDRAW_EP )); }; }; then
+    VERDICT="withdrawable"
+    break
+  fi
+
+  # The exit is committed and the set already released this validator, but the
+  # unbonding period is still running (weeks). There is NOTHING to wait for here:
+  # the host timer retries until the unlock epoch arrives, so the step reports the
+  # schedule and stops instead of sleeping for 15 minutes and saying "waiting for
+  # the set" while the set has long released it (2026-11-06, seen on .231).
+  if [[ "${STATE}" == "exiting" && "${ACTIVE:-false}" != "true" && "${SCHED:-false}" != "true" ]]; then
+    VERDICT="unbonding"
+    break
+  fi
+
+  if (( NOW - START >= EXIT_WAIT )); then
+    VERDICT="pending"
+    break
+  fi
+  if (( NOW - LAST >= EXIT_PROGRESS_SEC )); then
+    HINT=$(post_hint)
+    REASON="the set has not released this validator yet"
+    [[ "${STATE}" == "exiting" ]] && REASON="the set is still folding the exit out"
+    log "  waiting: ${REASON} (${SUMMARY}) active=${ACTIVE:-?} scheduled=${SCHED:-?}${HINT:+ (network: ${HINT})}"
+    LAST=${NOW}
+  fi
+  sleep "${POLL}"
+done
+
+# --- 3. not yet: hand the long part to the host timer ----------------
+# `pending` (the set has not released us yet) and `unbonding` (it did, the epoch
+# has not arrived) end the same way: report the schedule, arm the timer, stop.
+if [[ "${VERDICT}" != "withdrawable" ]]; then
+  # the schedule was already printed right after the exit committed: do not print
+  # (and measure) it twice - only when the state really changed since then
+  if [[ "${SCHED_STATE:-}" != "$(summary_value "${SUMMARY}" state)" ]]; then
+    announce_schedule "${SUMMARY}"
+  fi
+  exit_watch_install
+  if [[ "${STATE}" == "exiting" ]]; then
+    set_status WAITING-WITHDRAW "exited at epoch $(summary_value "${SUMMARY}" exit_epoch); the stake unlocks at epoch $(summary_value "${SUMMARY}" withdraw_epoch) ($(summary_value "${SUMMARY}" remaining) epoch(s) left) - the host withdraws it automatically"
+  else
+    set_status WAITING-EXIT "exit submitted; the set releases this validator at the next fold, then the stake unlocks at epoch $(summary_value "${SUMMARY}" withdraw_epoch) - the host withdraws it automatically"
+  fi
+  log "nothing else to do now: the console keeps following the unbonding, and this host retries the"
+  log "withdrawal every 15 minutes (systemd timer ${EXIT_WATCH_UNIT}.timer) - re-running this phase is safe"
+  exit 2
+fi
+
+log "unbonding finished (${SUMMARY}) - withdrawing the stake"
+set +e
+OUT=$(node_script 900 "sh controls/enroll.sh withdraw")
+RC=$?
+set -e
+printf '%s\n' "${OUT}" | sed 's/^/    /'
+if (( RC != 0 )); then
+  if printf '%s' "${OUT}" | grep -qE "unbonding period incomplete|withdraw_epoch|waits for removal"; then
+    warn "the chain is not ready for the withdrawal yet - the host timer keeps retrying"
+    exit_watch_install
+    set_status WAITING-WITHDRAW "withdrawal not signed yet (network) - the host retries it automatically"
+    exit 2
+  fi
+  if printf '%s' "${OUT}" | grep -qE "already|previously_confirmed"; then
+    log "the withdrawal was already submitted"
+  else
+    die "controls/enroll.sh withdraw failed (exit ${RC}) - see the output above"
+  fi
+fi
+
+# --- 5. wait until the bond is back in the wallet ---------------------
+START=$(date +%s)
+LAST=${START}
+while :; do
+  read_state
+  NOW=$(date +%s)
+  if [[ "${BOND:-0}" == "0" ]]; then
+    SUMMARY=$(enrollment_summary)
+    log "stake returned: validator_bond = 0 (${SUMMARY})"
+    exit_watch_disarm
+    echo "EXIT_DONE bond=0 state=$(summary_value "${SUMMARY}" state)"
+    set_status DONE "exited and withdrawn (bond 0, exit epoch $(summary_value "${SUMMARY}" exit_epoch))"
+    exit 0
+  fi
+  if (( NOW - START >= WITHDRAW_WAIT )); then
+    warn "the registry still shows a bond of $(raw_to_oct "${BOND:-0}") OCT after ${WITHDRAW_WAIT}s"
+    warn "the withdrawal transaction is on chain - the host timer keeps checking, this phase can be re-run"
+    exit_watch_install
+    set_status WAITING-WITHDRAW "withdraw submitted - bond still $(raw_to_oct "${BOND:-0}") OCT; the host keeps checking"
+    exit 2
+  fi
+  if (( NOW - LAST >= 60 )); then
+    log "  waiting for the stake: bond $(raw_to_oct "${BOND:-0}") OCT ($(( NOW - START ))s of ${WITHDRAW_WAIT}s)"
+    LAST=${NOW}
+  fi
+  sleep "${POLL}"
+done