ovtools 0.0.0-stage → 1.0.1

package/assets/upgrade/20-upgrade.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# ===================================================================
+# 20-upgrade.sh - update the node with the OFFICIAL tool
+#
+# The upstream README ("How to update (if you are already a validator)") names one
+# command that monitors the repo, checks the packages, builds a fresh binary,
+# restarts the node and waits until it is guaranteed to be operational:
+#
+#   sh controls/upgrade.sh            # test the mechanics, changes nothing
+#   sh controls/upgrade.sh --apply    # do it
+#
+# This step runs the test first (the README recommends checking first), then the
+# apply, and reads the verdict from what the tool prints:
+#
+#   validator_active | observer_synced  -> the node is online, the binary is the
+#                                          one just built, the head is caught up
+#   pending                             -> do NOT restart, the chain/build is not
+#                                          ready yet: soft stop, re-run later
+#   refused                             -> the reason is in the output (FAILED)
+#
+# It NEVER runs `--sync`, never touches config/network.env and never re-enrolls.
+#
+# Usage:  sudo bash 20-upgrade.sh
+# Env:    UPGRADE_APPLY (1) - 0 = only the test run
+#         UPGRADE_WAIT_SECONDS (900) - passed to --wait-seconds
+#         UPGRADE_EXTRA - extra flags for the tool, e.g.
+#                         "--public-commit <sha> --source-commit <sha>", or
+#                         "--unit octra-node.service" / "--user-unit"
+#         UPGRADE_TEST_TIMEOUT (1800) / UPGRADE_TIMEOUT (5400)
+# ===================================================================
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+
+require_root
+set_status RUNNING "upgrade"
+
+APPLY="${UPGRADE_APPLY:-1}"
+WAIT="${UPGRADE_WAIT_SECONDS:-900}"
+EXTRA="${UPGRADE_EXTRA:-}"
+TOOL_OUT="${UPGRADE_DIR}/upgrade-tool.out"
+
+[[ -f "${UPGRADE_SH}" ]] || die "controls/upgrade.sh is missing on this node - use the manual update (fallback phase)"
+
+ensure_tool git git || die "git is missing and could not be installed"
+read_state
+[[ "${PROCESS}" == "online" || -z "${PROCESS}" ]] || warn "the node process is ${PROCESS} - the tool will start/restart it"
+
+BEFORE_COMMIT=$(source_commit)
+BEFORE_HEAD=$(git_head)
+log "=== update with the official tool: controls/upgrade.sh${EXTRA:+ ${EXTRA}} --wait-seconds ${WAIT} ==="
+log "before : SOURCE_COMMIT=${BEFORE_COMMIT:-unknown} git HEAD=${BEFORE_HEAD:-unknown} role=${ROLE:-?} rpc=${RPC:-?}"
+log "repository: $(git_remote)"
+log "the node is NOT re-synced and NOT re-enrolled (upstream rule)"
+
+: > "${TOOL_OUT}"
+
+run_tool() {  # run_tool <timeout> <command...> -> streams into the console + the log, returns the tool's rc
+  local limit="$1" rc=0
+  shift
+  set +e
+  timeout "${limit}" su - "${NODE_USER}" -c "cd ${NODE_SRC_DIR} && $*" 2>&1 \
+    | tee -a "${TOOL_OUT}" | sed 's/^/    /'
+  rc=${PIPESTATUS[0]}
+  set -e
+  return "${rc}"
+}
+
+# --- 1. the test run (changes nothing) ---------------------------------
+log "--- test run: sh controls/upgrade.sh (nothing is rebuilt or restarted) ---"
+TEST_RC=0
+run_tool "${UPGRADE_TEST_TIMEOUT:-1800}" "sh controls/upgrade.sh" || TEST_RC=$?
+TEST_VERDICT=$(upgrade_verdict "${TOOL_OUT}")
+if (( TEST_RC != 0 )); then
+  REASON=$(upgrade_reason "${TOOL_OUT}")
+  if [[ "${TEST_VERDICT}" == "pending" ]]; then
+    warn "the tool reports 'pending'${REASON:+ - ${REASON}}"
+    warn "do NOT restart the node manually: re-run this phase once the tool can finish"
+    set_status WAITING-UPGRADE "the test run is pending${REASON:+ - ${REASON}} - re-run the update later"
+    exit 2
+  fi
+  die "the test run refused (exit ${TEST_RC})${REASON:+: ${REASON}} - nothing was changed; see the output above"
+fi
+log "the test run passed${TEST_VERDICT:+ (${TEST_VERDICT})}"
+
+if [[ "${APPLY}" != "1" ]]; then
+  log "UPGRADE_APPLY=0: test only - the node is untouched"
+  set_status DONE "test-only (SOURCE_COMMIT=${BEFORE_COMMIT:-unknown})"
+  exit 0
+fi
+
+# --- 2. apply -----------------------------------------------------------
+# shellcheck disable=SC2086
+ARGS="--apply --wait-seconds ${WAIT} ${EXTRA}"
+log "--- apply: sh controls/upgrade.sh ${ARGS} (pull + build + restart + wait) ---"
+APPLY_RC=0
+run_tool "${UPGRADE_TIMEOUT:-5400}" "sh controls/upgrade.sh ${ARGS}" || APPLY_RC=$?
+VERDICT=$(upgrade_verdict "${TOOL_OUT}")
+REASON=$(upgrade_reason "${TOOL_OUT}")
+
+case "${VERDICT}" in
+  pending)
+    warn "the tool reports 'pending'${REASON:+ - ${REASON}}"
+    warn "do NOT restart the node manually (upstream) - re-run this phase later"
+    set_status WAITING-UPGRADE "status pending${REASON:+ - ${REASON}} - re-run the update later"
+    exit 2
+    ;;
+  refused)
+    die "the tool refused the update${REASON:+: ${REASON}} - see the output above"
+    ;;
+esac
+
+# --- 3. verify what is running now -------------------------------------
+AFTER_COMMIT=$(source_commit)
+AFTER_HEAD=$(git_head)
+read_state
+log "after  : SOURCE_COMMIT=${AFTER_COMMIT:-unknown} git HEAD=${AFTER_HEAD:-unknown} role=${ROLE:-?} process=${PROCESS:-?} rpc=${RPC:-?} voting=${VOTING:-?} epoch=${EPOCH:-?}"
+log "binary : ${BINARY:-unknown}${PVAC:+ pvac ${PVAC}}"
+
+if [[ "${PROCESS}" != "online" || "${RPC}" != "ready" ]]; then
+  warn "the node is not back yet (process=${PROCESS:-?} rpc=${RPC:-?})"
+  warn "check it with: su - ${NODE_USER} -c 'cd ${NODE_SRC_DIR} && sh controls/stat.sh --logs'"
+  set_status WAITING-UPGRADE "the update ran but the node is not ready yet (process=${PROCESS:-?} rpc=${RPC:-?}) - re-run the update or read stat.sh --logs"
+  exit 2
+fi
+
+if (( APPLY_RC != 0 )); then
+  warn "the tool exited ${APPLY_RC} but the node is online as ${ROLE:-?}${VERDICT:+ (verdict ${VERDICT})}"
+fi
+if [[ -n "${AFTER_COMMIT}" && -n "${AFTER_HEAD}" && "${AFTER_COMMIT}" != "${AFTER_HEAD}" ]]; then
+  warn "SOURCE_COMMIT (${AFTER_COMMIT}) does not match git HEAD (${AFTER_HEAD}) - check the checkout"
+fi
+
+if [[ -z "${VERDICT}" ]]; then
+  if [[ "${ACTIVE}" == "true" ]]; then VERDICT="validator_active"; else VERDICT="observer_synced"; fi
+fi
+if [[ "${ACTIVE}" == "true" ]]; then
+  log "=== the node is an ACTIVE validator again, running the binary it just built ==="
+else
+  log "=== the node is online and synced (observer) with the freshly built binary ==="
+fi
+set_status DONE "verdict=${VERDICT} commit=${AFTER_HEAD:-unknown} role=${ROLE:-?} active=${ACTIVE:-?} epoch=${EPOCH:-?}"

package/assets/upgrade/30-manual-upgrade.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# ===================================================================
+# 30-manual-upgrade.sh - the documented MANUAL update (fallback)
+#
+# Upstream README, "Manual update (when the tool cannot run)":
+#
+#   sudo -iu octra
+#   cd /opt/octra/libv_litecore
+#   git pull --ff-only
+#   cat SOURCE_COMMIT
+#   sh controls/check.sh
+#   SWITCH="$PWD/runtime_data/toolchains/ocaml"
+#   make -C mcl MCL_FP_BIT=256 MCL_FR_BIT=256 lib/libmcl.a
+#   opam exec --switch "$SWITCH" -- dune build --profile release \
+#     bin/octra_node.exe bin/octra_pvac_worker.exe \
+#     bin/octra_state_sync_client.exe bin/octra_state_sync_manifest.exe \
+#     bin/bft_control_tx.exe
+#   sh controls/stop.sh
+#   sh controls/run.sh --rebind-runtime
+#   sh controls/stat.sh
+#
+# Every command runs as the node user from the node directory (the checkout and
+# the opam switch belong to it). This step NEVER runs `--sync`, never edits
+# config/network.env and never re-enrolls - the node keeps its identity and its
+# data, only the binary is replaced and the process restarted.
+#
+# Usage:  sudo bash 30-manual-upgrade.sh
+# Env:    MANUAL_APPLY (1) - 0 = pull + check + build only (no stop/run)
+#         PULL_TIMEOUT (600) / CHECK_TIMEOUT (300) / MAKE_TIMEOUT (1800)
+#         BUILD_TIMEOUT (5400) / STOP_TIMEOUT (180) / RUN_TIMEOUT (900)
+# ===================================================================
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+
+require_root
+set_status RUNNING "manual-upgrade"
+
+APPLY="${MANUAL_APPLY:-1}"
+BUILD_LOG="${UPGRADE_DIR}/manual-build.out"
+
+[[ -d "${NODE_SRC_DIR}/.git" ]] || die "${NODE_SRC_DIR} is not a git checkout - cannot pull"
+[[ -f "${NODE_ENV}" ]] || die "node.env is missing (${NODE_ENV}) - this is not the node host"
+
+ensure_build_tools
+
+# the opam switch the toolchain step built (upstream: $PWD/runtime_data/toolchains/ocaml)
+SWITCH="$(ocaml_switch_root 2>/dev/null || printf '%s' "${NODE_SRC_DIR}/runtime_data/toolchains/ocaml")"
+[[ -d "${SWITCH}/_opam/.opam-switch" ]] || die "the opam switch is not built (${SWITCH}/_opam/.opam-switch missing) - run the toolchain step (scripts/deploy/20-install-toolchain.sh) first"
+
+BEFORE_COMMIT=$(source_commit)
+BEFORE_HEAD=$(git_head)
+log "=== manual update on $(hostname) ==="
+log "before : SOURCE_COMMIT=${BEFORE_COMMIT:-unknown} git HEAD=${BEFORE_HEAD:-unknown}"
+log "opam switch: ${SWITCH}"
+log "the node is NOT re-synced and NOT re-enrolled (upstream rule)"
+
+run_as_node() {  # run_as_node <timeout> <label> <command...>
+  local limit="$1" label="$2" rc=0
+  shift 2
+  log "--- ${label} ---"
+  set +e
+  timeout "${limit}" su - "${NODE_USER}" -c "cd ${NODE_SRC_DIR} && $*" 2>&1 \
+    | tee -a "${BUILD_LOG}" | sed 's/^/    /'
+  rc=${PIPESTATUS[0]}
+  set -e
+  return "${rc}"
+}
+
+: > "${BUILD_LOG}"
+
+
+# --- 1. pull + verify --------------------------------------------------
+run_as_node "${PULL_TIMEOUT:-600}" "git pull --ff-only" "git pull --ff-only" \
+  || die "git pull failed - see the output above (a dirty tree or a diverged branch stops here)"
+
+AFTER_COMMIT=$(source_commit)
+AFTER_HEAD=$(git_head)
+log "after the pull: SOURCE_COMMIT=${AFTER_COMMIT:-unknown} git HEAD=${AFTER_HEAD:-unknown}"
+
+if [[ -f "${CHECK_SH}" ]]; then
+  run_as_node "${CHECK_TIMEOUT:-300}" "controls/check.sh (verify the package)" "sh controls/check.sh" \
+    || die "controls/check.sh reported a problem - fix it before building"
+else
+  warn "controls/check.sh is missing - skipping the package verification"
+fi
+
+# --- 2. build ----------------------------------------------------------
+run_as_node "${MAKE_TIMEOUT:-1800}" "make -C mcl (MCL_FP_BIT=256 MCL_FR_BIT=256)" \
+  "make -C mcl MCL_FP_BIT=256 MCL_FR_BIT=256 lib/libmcl.a" \
+  || die "the mcl library did not build - see the output above"
+
+run_as_node "${BUILD_TIMEOUT:-5400}" "dune build --profile release (node + pvac + sync + bft)" \
+  "opam exec --switch '${SWITCH}' -- dune build --profile release bin/octra_node.exe bin/octra_pvac_worker.exe bin/octra_state_sync_client.exe bin/octra_state_sync_manifest.exe bin/bft_control_tx.exe" \
+  || die "the dune build failed - see the output above (the running node is untouched so far)"
+
+log "the build finished - the node is still running the old binary"
+
+if [[ "${APPLY}" != "1" ]]; then
+  log "MANUAL_APPLY=0: build only - the node was not restarted"
+  set_status DONE "build-only commit=${AFTER_HEAD:-unknown} (node still on the old binary)"
+  exit 0
+fi
+
+# --- 3. restart on the fresh binary ------------------------------------
+run_as_node "${STOP_TIMEOUT:-180}" "controls/stop.sh" "sh controls/stop.sh" \
+  || die "controls/stop.sh failed - the node may still be running; check it before retrying"
+
+run_as_node "${RUN_TIMEOUT:-900}" "controls/run.sh --rebind-runtime" "sh controls/run.sh --rebind-runtime" \
+  || warn "controls/run.sh reported an error - checking the node state anyway"
+
+read_state
+log "node after the restart: role=${ROLE:-?} process=${PROCESS:-?} rpc=${RPC:-?} voting=${VOTING:-?} epoch=${EPOCH:-?}"
+log "binary : ${BINARY:-unknown}${PVAC:+ pvac ${PVAC}}"
+
+if [[ "${PROCESS}" != "online" ]]; then
+  warn "the node process is ${PROCESS:-unknown} - the restart did not come up"
+  warn "read the log: su - ${NODE_USER} -c 'cd ${NODE_SRC_DIR} && sh controls/stat.sh --logs'"
+  set_status WAITING-UPGRADE "the manual build finished but the node is ${PROCESS:-unknown} - check stat.sh --logs"
+  exit 2
+fi
+if [[ "${RPC}" != "ready" ]]; then
+  warn "the node is online but its rpc is ${RPC:-unknown} - it is probably replaying; re-run to re-check"
+  set_status WAITING-RPC "the node is online again but rpc=${RPC:-unknown} - re-run the manual update to re-check"
+  exit 2
+fi
+
+log "=== the node is back on the freshly built binary ==="
+set_status DONE "manual-upgrade commit=${AFTER_HEAD:-unknown} role=${ROLE:-?} active=${ACTIVE:-?} epoch=${EPOCH:-?}"

package/assets/upgrade/40-storage-prune.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# ===================================================================
+# 40-storage-prune.sh - "Remove preserved states" (upstream README)
+#
+#   sh controls/storage.sh                        # report
+#   sh controls/storage.sh --prune-prior --yes    # drop the previous states
+#   sh controls/storage.sh                        # report again
+#
+# A node keeps the states of the previous epochs ("prior"/preserved states) so it
+# can serve peers that lag behind; they grow until the store is oversized. The
+# documented maintenance is to drop them from time to time - which is also what
+# the daily prune job on this host now does (dashboard/prune-node-junk.sh).
+#
+# Read-only when PRUNE_APPLY=0. Nothing else on the node is touched: no sync, no
+# re-enroll, the node keeps running.
+#
+# Usage:  sudo bash 40-storage-prune.sh
+# Env:    PRUNE_APPLY (1) - 0 = report only
+#         PRUNE_TIMEOUT (900) / STORAGE_TIMEOUT (180)
+# ===================================================================
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+
+require_root
+set_status RUNNING "storage-prune"
+
+APPLY="${PRUNE_APPLY:-1}"
+[[ -f "${STORAGE_SH}" ]] || die "controls/storage.sh is missing on this node - update the node first (the tool does not exist on this version)"
+
+log "=== preserved states on $(hostname) ==="
+log "--- storage before ---"
+BEFORE=$(storage_report)
+printf '%s\n' "${BEFORE}" | sed 's/^/    /'
+BEFORE_LINE=$(printf '%s\n' "${BEFORE}" | grep -iE 'preserved|reclaim|prior' | tail -1 || true)
+
+if [[ "${APPLY}" != "1" ]]; then
+  log "PRUNE_APPLY=0: report only - nothing was pruned"
+  set_status DONE "report-only${BEFORE_LINE:+ - ${BEFORE_LINE}}"
+  exit 0
+fi
+
+read_state
+log "node while pruning: process=${PROCESS:-?} rpc=${RPC:-?} role=${ROLE:-?} epoch=${EPOCH:-?}"
+
+log "--- storage.sh --prune-prior --yes ---"
+RC=0
+OUT=$(prune_states) || RC=$?
+printf '%s\n' "${OUT}" | sed 's/^/    /'
+if (( RC != 0 )); then
+  REASON=$(printf '%s\n' "${OUT}" | grep -aiE 'error|refus|denied|not |missing|failed' | tail -1 || true)
+  die "controls/storage.sh --prune-prior refused (exit ${RC})${REASON:+: ${REASON}}"
+fi
+
+log "--- storage after ---"
+AFTER=$(storage_report)
+printf '%s\n' "${AFTER}" | sed 's/^/    /'
+AFTER_LINE=$(printf '%s\n' "${AFTER}" | grep -iE 'preserved|reclaim|prior' | tail -1 || true)
+
+read_state
+log "node after pruning: process=${PROCESS:-?} rpc=${RPC:-?} role=${ROLE:-?} epoch=${EPOCH:-?}"
+[[ "${PROCESS}" == "online" ]] || warn "the node process is ${PROCESS:-unknown} - check it with stat.sh --logs"
+
+log "=== preserved states pruned ==="
+set_status DONE "${AFTER_LINE:-pruned}${BEFORE_LINE:+ (before: ${BEFORE_LINE})}"

package/assets/upgrade/50-status.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# ===================================================================
+# 50-status.sh - versions + storage of the running node (read-only)
+#
+# Prints what the console shows for the update program: the commit the checkout
+# says it is (SOURCE_COMMIT), the git HEAD/branch (and whether the tree is dirty),
+# the hashes of the BINARY that is actually running (stat.sh) and the storage
+# report of the node's own tool. Nothing is pulled, built or restarted.
+#
+# Usage:  sudo bash 50-status.sh
+# ===================================================================
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+
+require_root
+set_status RUNNING "status"
+
+ensure_tool git git || die "git is missing and could not be installed"
+ensure_tool jq  jq  || warn "jq is missing - the wallet address cannot be read"
+
+COMMIT=$(source_commit)
+HEAD=$(git_head)
+BRANCH=$(git_branch)
+DIRTY=$(git_dirty)
+REMOTE=$(git_remote)
+read_state
+ADDR=$(wallet_address || echo unknown)
+
+log "=== update status: $(hostname) ==="
+log "wallet    : ${ADDR}"
+log "repository: ${REMOTE}"
+log "checkout  : SOURCE_COMMIT=${COMMIT:-unknown} git HEAD=${HEAD:-unknown}${BRANCH:+ on ${BRANCH}}${DIRTY:+ (dirty working tree)}"
+if [[ -n "${COMMIT}" && -n "${HEAD}" && "${COMMIT}" != "${HEAD}" ]]; then
+  log "            SOURCE_COMMIT and git HEAD differ - the checkout was rebuilt from another commit"
+fi
+log "running   : role=${ROLE:-?} process=${PROCESS:-?} rpc=${RPC:-?} voting=${VOTING:-?} epoch=${EPOCH:-?} uptime=${PROCESS_UP:-?}"
+log "binary    : ${BINARY:-unknown}"
+log "pvac      : ${PVAC:-unknown}"
+log "membership: active=${ACTIVE:-?} scheduled=${SCHED:-?} enrollment=${ENROLL:-?}"
+
+if [[ -f "${STORAGE_SH}" ]]; then
+  log "--- controls/storage.sh ---"
+  STORE=$(storage_report)
+  printf '%s\n' "${STORE}" | sed 's/^/    /'
+  STORAGE_LINE=$(storage_fields)
+else
+  warn "controls/storage.sh is missing - this node version has no storage tool"
+  STORAGE_LINE=""
+fi
+
+if [[ -f "${UPGRADE_SH}" ]]; then
+  log "official tool: controls/upgrade.sh present (sh controls/upgrade.sh / --apply)"
+else
+  warn "controls/upgrade.sh is missing - use the manual update (fallback)"
+fi
+
+set_status DONE "commit=${HEAD:-unknown}${BRANCH:+ on ${BRANCH}} role=${ROLE:-?} active=${ACTIVE:-?}${STORAGE_LINE:+ - ${STORAGE_LINE}}"

package/assets/upgrade/lib.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+# ===================================================================
+# scripts/upgrade/lib.sh - shared helpers for the UPDATE-NODE actions
+#
+# The update actions of the console's "Manage active node" block (they are not a
+# tab of their own since 2026-11-05): they do not create, move or operate the
+# validator - they UPDATE the node that is already running, exactly as the
+# upstream README describes ("How to update (if you are already a validator)"):
+#
+#   * the official tool:   controls/upgrade.sh            (test, changes nothing)
+#                          controls/upgrade.sh --apply    (pull, build, restart,
+#                                                         wait, verify)
+#   * the manual fallback: git pull --ff-only -> controls/check.sh -> make -C mcl
+#                          -> dune build -> controls/stop.sh -> controls/run.sh
+#                          --rebind-runtime -> controls/stat.sh
+#   * housekeeping:        controls/storage.sh [--prune-prior --yes]
+#                          ("Remove preserved states")
+#
+# NEVER (upstream, in capitals): do not run `--sync` again, do not change
+# config/network.env, do not re-enroll the node. Every step here only pulls,
+# builds, restarts and reads.
+#
+#   /root/upgrade/          this program   (/root/deploy, /root/migration, /root/manage)
+# ===================================================================
+set -euo pipefail
+
+# Tool policy (check -> install -> continue) lives in scripts/config.sh, which is
+# pushed to /root/config.sh next to these scripts.
+CONFIG_FILE="${CONFIG_FILE:-/root/config.sh}"
+if [[ -f "${CONFIG_FILE}" ]]; then
+  # shellcheck disable=SC1090
+  source "${CONFIG_FILE}"
+fi
+if ! declare -F ensure_tool >/dev/null 2>&1; then
+  ensure_tool() { command -v "$1" >/dev/null 2>&1 || die "tool $1 is missing and ${CONFIG_FILE} cannot install it (push the scripts again)"; }
+fi
+
+UPGRADE_DIR="${UPGRADE_DIR:-/root/upgrade}"
+UPGRADE_LOG="${UPGRADE_LOG:-${UPGRADE_DIR}/upgrade.log}"
+UPGRADE_STATUS="${UPGRADE_STATUS:-${UPGRADE_DIR}/status}"
+
+NODE_SRC_DIR="${NODE_SRC_DIR:-/opt/octra/libv_litecore}"
+NODE_DATA_ROOT="${NODE_DATA_ROOT:-/var/lib/octra}"
+NODE_DATA_DIR="${NODE_DATA_DIR:-${NODE_DATA_ROOT}/devnet}"
+NODE_WALLET="${NODE_WALLET:-${NODE_SRC_DIR}/.keys/validator/wallet.json}"
+NODE_ENV="${NODE_ENV:-${NODE_SRC_DIR}/.keys/validator/node.env}"
+NODE_USER="${NODE_USER:-octra}"
+NODE_LOG="${NODE_LOG:-${NODE_SRC_DIR}/data/operator_logs/node.log}"
+# the control scripts the upstream README names
+UPGRADE_SH="${UPGRADE_SH:-${NODE_SRC_DIR}/controls/upgrade.sh}"
+STORAGE_SH="${STORAGE_SH:-${NODE_SRC_DIR}/controls/storage.sh}"
+CHECK_SH="${CHECK_SH:-${NODE_SRC_DIR}/controls/check.sh}"
+STOP_SH="${STOP_SH:-${NODE_SRC_DIR}/controls/stop.sh}"
+RUN_SH="${RUN_SH:-${NODE_SRC_DIR}/controls/run.sh}"
+# where SOURCE_COMMIT lives in the checkout (upstream ships it)
+SOURCE_COMMIT_FILE="${SOURCE_COMMIT_FILE:-${NODE_SRC_DIR}/SOURCE_COMMIT}"
+
+mkdir -p "${UPGRADE_DIR}"
+
+log()  { echo -e "[upgrade] $*" | tee -a "${UPGRADE_LOG}"; }
+warn() { echo -e "[warn]    $*" | tee -a "${UPGRADE_LOG}" >&2; }
+err()  { echo -e "[err]     $*" | tee -a "${UPGRADE_LOG}" >&2; }
+
+set_status() {  # set_status <STATE> [detail...] - read by the Windows console
+  local state="$1" detail
+  shift || true
+  detail="$*"
+  printf '%s %s %s\n' "${state}" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "${detail}" > "${UPGRADE_STATUS}"
+  log "status = ${state} ${detail}"
+}
+
+die() { err "$*"; set_status FAILED "$*"; exit 1; }
+
+require_root() { [[ $EUID -eq 0 ]] || die "run as root"; }
+
+# A step must never die leaving status = RUNNING: the console follows this file.
+_upgrade_on_err() {
+  local rc="$1" line="$2" cmd="$3" state
+  state=$(awk 'NR==1 {print $1}' "${UPGRADE_STATUS}" 2>/dev/null || true)
+  case "${state}" in
+    DONE|FAILED|WAITING-*) return 0 ;;
+  esac
+  err "unexpected failure (exit ${rc}) at line ${line}: ${cmd}"
+  set_status FAILED "line ${line}: ${cmd} (exit ${rc})"
+}
+trap '_upgrade_on_err "$?" "$LINENO" "$BASH_COMMAND"' ERR
+
+# --- the node's own controls (always as the octra user) ---------------
+as_octra() { su - "${NODE_USER}" -c "$*"; }
+
+# node_script <timeout> <command...>: run one of the node's control scripts from
+# the node directory as the node user, bounded so a control script that waits on
+# the chain can never freeze a step. stdout+stderr are merged (what the operator
+# needs to read).
+node_script() {
+  local limit="$1"
+  shift
+  timeout "${limit}" su - "${NODE_USER}" -c "cd ${NODE_SRC_DIR} && $*" 2>&1
+}
+
+# like node_script, but the caller decides what a non-zero exit means
+node_script_rc() {  # node_script_rc <timeout> <command...> -> prints output, returns the rc
+  local limit="$1" rc
+  shift
+  set +e
+  timeout "${limit}" su - "${NODE_USER}" -c "cd ${NODE_SRC_DIR} && $*" 2>&1
+  rc=$?
+  set -e
+  return "${rc}"
+}
+
+stat_raw() { node_script "${STATE_TIMEOUT:-60}" "sh controls/stat.sh" || true; }
+
+stat_field() {  # an unreadable field is EMPTY, not the string "None" (see deploy/lib.sh)
+  awk -F' = ' -v k="$1" '$1 == k { if ($2 == "None" || $2 == "null") { print ""; exit } print $2; exit }'
+}
+
+# read_state: the fields every step here cares about (never writes anything on the
+# node - stat.sh is read-only)
+read_state() {
+  SNAP=$(stat_raw)
+  ROLE=$(printf '%s\n' "${SNAP}" | stat_field role)
+  PROCESS=$(printf '%s\n' "${SNAP}" | stat_field process)
+  RPC=$(printf '%s\n' "${SNAP}" | stat_field rpc)
+  VOTING=$(printf '%s\n' "${SNAP}" | stat_field voting)
+  EPOCH=$(printf '%s\n' "${SNAP}" | stat_field epoch)
+  ACTIVE=$(printf '%s\n' "${SNAP}" | stat_field validator_active)
+  SCHED=$(printf '%s\n' "${SNAP}" | stat_field validator_scheduled)
+  ENROLL=$(printf '%s\n' "${SNAP}" | stat_field validator_enrollment)
+  BINARY=$(printf '%s\n' "${SNAP}" | stat_field binary)
+  PVAC=$(printf '%s\n' "${SNAP}" | stat_field pvac_worker)
+  PROCESS_UP=$(printf '%s\n' "${SNAP}" | stat_field uptime)
+}
+
+# --- the checkout: what is really there -------------------------------
+# The clone belongs to the node user, so `git` as root refuses with "dubious
+# ownership": ask with an explicit safe.directory (same as deploy/lib.sh).
+git_node() {  # git_node <args...>
+  git -c safe.directory="${NODE_SRC_DIR}" -C "${NODE_SRC_DIR}" "$@" 2>/dev/null || true
+}
+
+source_commit() {     # the commit the checkout SAYS it is (upstream file)
+  local out=""
+  [[ -f "${SOURCE_COMMIT_FILE}" ]] && out=$(head -c 64 "${SOURCE_COMMIT_FILE}" 2>/dev/null | tr -d '[:space:]' || true)
+  printf '%s' "${out}"
+}
+
+git_head() { git_node rev-parse --short HEAD | head -1; }
+git_branch() {
+  local out
+  out=$(git_node rev-parse --abbrev-ref HEAD | head -1)
+  [[ "${out}" == "HEAD" ]] && out=""
+  printf '%s' "${out}"
+}
+git_dirty() {   # 1 when the working tree has local changes (a build might depend on them)
+  local out
+  out=$(git_node status --porcelain | head -1)
+  [[ -n "${out}" ]] && printf '1'
+  return 0
+}
+git_remote() {
+  local out
+  out=$(git_node config --get remote.origin.url | head -1)
+  printf '%s' "${out:-https://github.com/octra-labs/lite_node.git}"
+}
+
+# --- tools the two update paths need ----------------------------------
+ensure_build_tools() {
+  ensure_tool git   git             || die "git is missing and could not be installed"
+  ensure_tool make  make            || die "make is missing and could not be installed"
+  ensure_tool opam  opam            || die "opam is missing and could not be installed"
+  # the manual build compiles the C++/mcl part and needs a compiler
+  if ! command -v g++ >/dev/null 2>&1 && ! command -v c++ >/dev/null 2>&1; then
+    ensure_package build-essential || true
+  fi
+}
+
+# --- storage.sh (preserved states) ------------------------------------
+storage_report() {   # read-only: what the store holds right now
+  node_script "${STORAGE_TIMEOUT:-180}" "sh controls/storage.sh" || true
+}
+
+storage_summary() {  # one line out of the report, for the status detail
+  # optional text: a report this version does not match must never fail the caller
+  storage_report | grep -iE 'preserved|reclaim|prior|free|used|total' | tail -3 \
+    | tr '\n' ' ' | sed 's/  */ /g' || true
+  return 0
+}
+
+# The report is emitted as `event = storage data_bytes = ... prior_count = ...`
+# lines; the status detail only needs the few numbers that matter. Like
+# storage_summary this is OPTIONAL text and must never return non-zero.
+storage_fields() {
+  storage_report | grep -oE '(prior_count|prior_bytes|free_bytes|data_bytes) = [0-9]+' \
+    | tr '\n' ' ' | sed -e 's/ = /=/g' -e 's/ *$//' || true
+  return 0
+}
+
+# the wallet address of the node (read-only)
+wallet_address() {
+  if [[ -f "${NODE_WALLET}" ]] && command -v jq >/dev/null 2>&1; then
+    jq -r '.address // empty' "${NODE_WALLET}" 2>/dev/null || true
+  fi
+}
+
+prune_states() {     # the documented "Remove preserved states"
+  node_script_rc "${PRUNE_TIMEOUT:-900}" "sh controls/storage.sh --prune-prior --yes"
+}
+
+# --- what the upgrade tool answered -----------------------------------
+# controls/upgrade.sh ends with a status line the README names: validator_active
+# or observer_synced = fine, pending = do NOT restart and try later, refused =
+# the reason is in the output.
+upgrade_verdict() {  # upgrade_verdict <output-file>
+  local file="$1"
+  [[ -f "${file}" ]] || return 0
+  awk '
+    /validator_active|observer_synced|status = pending|pending|refused/ {
+      if ($0 ~ /validator_active/) { print "validator_active"; exit }
+      if ($0 ~ /observer_synced/)  { print "observer_synced"; exit }
+      if ($0 ~ /pending/)          { print "pending"; exit }
+      if ($0 ~ /refused/)          { print "refused"; exit }
+    }' "${file}" | tail -1
+}
+
+upgrade_reason() {   # the last line that explains why (refused/pending)
+  local file="$1" line
+  [[ -f "${file}" ]] || return 0
+  line=$(grep -aiE 'status = (refused|pending)|reason = |error|denied|not allowed|dirty' "${file}" 2>/dev/null | tail -1 || true)
+  printf '%s' "${line##*: }"
+}
+

package/bin/ovtools.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const distPath = path.join(__dirname, '..', 'dist', 'cli.js');
+if (!fs.existsSync(distPath)) {
+  console.error('ovtools is not built (dist/cli.js is missing). Run: npm run build');
+  process.exit(1);
+}
+
+let cli;
+try {
+  cli = require(distPath);
+} catch (err) {
+  console.error('ovtools failed to load:', err && err.message ? err.message : err);
+  process.exit(1);
+}
+
+const main = cli && typeof cli.main === 'function' ? cli.main : null;
+if (!main) {
+  console.error('ovtools is corrupted: dist/cli.js does not export main()');
+  process.exit(1);
+}
+
+main(process.argv.slice(2)).then(code => {
+  process.exitCode = typeof code === 'number' ? code : 0;
+}).catch(err => {
+  console.error(`ERROR: ${err && err.message ? err.message : err}`);
+  process.exitCode = 1;
+});

package/dist/api/checks.d.ts

@@ -0,0 +1,6 @@
+import type { CheckResult } from '../types';
+export declare function runCheck(body: any): Promise<{
+    key: string;
+    result: CheckResult;
+}>;
+//# sourceMappingURL=checks.d.ts.map

package/dist/api/checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../../src/api/checks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,UAAU,CAAC;AAsFhE,wBAAsB,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC,CAwGvF"}