ovtools 0.0.0-stage → 1.0.0

package/assets/migrate/01-prepare-target.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# ===================================================================
+# 01-prepare-target.sh — prepare the NEW VPS for the data pull
+#
+#   * installs the tools needed by the migration (rsync, jq, git, ...)
+#   * creates the `octra` system user (same as scripts/install-deps.sh)
+#   * creates the node directories on the 1 TB volume
+#   * generates an SSH key for root so it can pull from the OLD VPS
+#
+# Run on the NEW VPS AFTER scripts/pre-run.sh:
+#   sudo bash 01-prepare-target.sh
+# Optional:
+#   FORCE=1         keep an existing data set (resumable copy of this migration)
+#   RESET_TARGET=1  drop a stale/foreign node state and start clean
+#
+# Idempotent - safe to re-run.
+# ===================================================================
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+
+require_root
+set_status RUNNING "prepare-target"
+rm -f "${MIG_DIR}/prep.blocked"
+
+# --- Freshness guard -------------------------------------------------
+# Never prepare over an existing node: a second copy of the same wallet is
+# exactly what must not happen.
+#
+# A provider block volume SURVIVES an OS re-install, so "I just reinstalled the
+# VPS" does not guarantee an empty chain state. pre-run.sh formats any volume
+# that does not carry an Octra data set (automatic, no checkbox) and records
+# what it did in /root/migration/prerun.env. The orchestrator reads that file and
+# passes the matching flag, so this script never contradicts pre-run.sh:
+#
+#   (nothing)          fresh target - nothing to protect
+#   FORCE=1            the data set is a resumable copy of THIS migration -
+#                      keep it and prepare anyway
+#   RESET_TARGET=1     the data set is stale/foreign - drop the node state
+#                      (chain state, sync stage, source tree + keys) and start
+#                      clean; the pull copies the source's state right after
+#   WIPE_VOLUME=1      ... bash /root/pre-run.sh  (reformat the volume instead)
+FRESH=1
+if [[ -f "${NODE_SRC_DIR}/.keys/validator/wallet.json" ]]; then
+  FRESH=0
+fi
+if [[ -f "${NODE_DATA_DIR}/HEAD.json" ]]; then
+  FRESH=0
+fi
+
+reset_target_state() {
+  local path
+  warn "RESET_TARGET=1 - dropping the stale node state on $(hostname):"
+  for path in "${NODE_DATA_DIR}" "${NODE_SYNC_STAGE}" "${NODE_SRC_DIR}"; do
+    [[ -e "${path}" ]] || continue
+    warn "  rm -rf ${path}"
+    rm -rf "${path}"
+  done
+  log "node state cleared - the pull will copy the source state next"
+}
+
+if [[ "${RESET_TARGET:-0}" == "1" ]]; then
+  if [[ -n "$(node_processes)" ]]; then
+    die "RESET_TARGET=1 refused: a node is already running on this host ($(node_processes | awk '{print $1}' | head -1)) - stop it first, this host would be a live validator"
+  fi
+  if (( FRESH == 0 )); then
+    reset_target_state
+  else
+    log "RESET_TARGET=1 requested, but the target is already fresh - nothing to clear"
+  fi
+elif [[ "${FORCE:-0}" == "1" ]]; then
+  if (( FRESH == 0 )); then
+    warn "FORCE=1 - keeping the existing data set on this host (resuming the same migration)"
+  fi
+elif (( FRESH == 0 )); then
+  if [[ -f "${NODE_SRC_DIR}/.keys/validator/wallet.json" ]]; then
+    FOUND="${NODE_SRC_DIR}/.keys/validator/wallet.json"
+  else
+    FOUND="${NODE_DATA_DIR}/HEAD.json"
+  fi
+  # Machine-readable marker: the orchestrator turns it into a self-heal
+  # (reformat the volume, or RESET_TARGET=1) instead of retrying the same call.
+  printf 'target-not-fresh %s\n' "${FOUND}" > "${MIG_DIR}/prep.blocked"
+  die "${FOUND} already exists - the target still holds a node (nothing of this migration has been copied yet): pre-run.sh with WIPE_VOLUME=1 reformats the volume, RESET_TARGET=1 drops just the node state, FORCE=1 keeps it (resume)"
+fi
+
+log "Checking the migration tooling (rsync, jq, git, curl, psmisc)..."
+export DEBIAN_FRONTEND=noninteractive
+export TERM="${TERM:-dumb}"
+# check -> install -> continue: a fresh VPS may have none of these, and a retry
+# must not re-run a full apt install for tools that are already there
+ensure_package ca-certificates || die "cannot install ca-certificates"
+ensure_tool rsync rsync || die "rsync is missing and could not be installed"
+ensure_tool jq    jq    || die "jq is missing and could not be installed"
+ensure_tool git   git   || die "git is missing and could not be installed"
+ensure_tool curl  curl  || die "curl is missing and could not be installed"
+ensure_tool wget  wget  || die "wget is missing and could not be installed"
+ensure_tool pgrep psmisc || die "pgrep (psmisc) is missing and could not be installed"
+ensure_tool pkill psmisc || die "pkill (psmisc) is missing and could not be installed"
+ensure_package procps   || die "cannot install procps"
+log "Packages ready: $(rsync --version | head -1)"
+
+# --- octra user (same convention as scripts/install-deps.sh) --------
+if ! id "${NODE_USER}" &>/dev/null; then
+  log "Creating system user '${NODE_USER}'..."
+  useradd -r -m -d "/home/${NODE_USER}" -s /bin/bash "${NODE_USER}"
+else
+  log "User '${NODE_USER}' already exists ($(id -u "${NODE_USER}"))"
+fi
+
+# --- Data store must exist before we write anything -----------------
+# pre-run.sh has already mounted a 1 TB volume, or (no volume attached) created
+# the directory on the largest filesystem. Either way the path must exist and be
+# writable, and every sub-directory is created here when missing.
+ensure_dirs
+if ! mountpoint -q "${NODE_DATA_ROOT}" 2>/dev/null; then
+  warn "${NODE_DATA_ROOT} is not a separate mount point - the node data lives on the root filesystem"
+fi
+FREE_GB=$(df -BG --output=avail "${NODE_DATA_ROOT}" 2>/dev/null | tail -1 | tr -dc '0-9')
+if [[ -n "${FREE_GB}" ]] && (( FREE_GB < 60 )); then
+  die "not enough free space on ${NODE_DATA_ROOT} (${FREE_GB}G free, ~41 GB is copied)"
+fi
+log "Data root: ${NODE_DATA_ROOT} ($(df -h "${NODE_DATA_ROOT}" | tail -1 | awk '{print $2}' ) total, $(df -h "${NODE_DATA_ROOT}" | tail -1 | awk '{print $4}') free)"
+
+# --- Root SSH key used to pull data from the OLD VPS ----------------
+# NOTE: we deliberately do NOT touch sshd_config. Password login is the
+# operator's out-of-band access path; pubkey auth is already enabled by
+# default on Debian, which is all the pull needs.
+install -d -m 700 /root/.ssh
+if [[ ! -f /root/.ssh/id_ed25519 ]]; then
+  log "Generating root SSH key for the data pull..."
+  ssh-keygen -t ed25519 -N "" -C "octra-migration@$(hostname)" -f /root/.ssh/id_ed25519 >/dev/null
+fi
+
+cp /root/.ssh/id_ed25519.pub "${MIG_DIR}/target_ssh_key.pub"
+chmod 644 "${MIG_DIR}/target_ssh_key.pub"
+
+log "Target prepared."
+log "Disk: $(df -h "${NODE_DATA_ROOT}" | tail -1 | awk '{print $2" total, "$4" free"}')"
+log "Swap: $(free -h | awk '/^Swap:/ {print $2}')"
+echo
+log "PUBLIC KEY (must be appended to ${OLD_USER}@${OLD_HOST:-<old-vps>}:~/.ssh/authorized_keys):"
+cat "${MIG_DIR}/target_ssh_key.pub"
+
+set_status DONE "prepare-target"

package/assets/migrate/02-authorize-pull.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# ===================================================================
+# 02-authorize-pull.sh — run ON THE OLD VPS
+#
+# Appends the NEW VPS root public key to root's authorized_keys so the
+# target can rsync the node state directly from the source machine.
+#
+# Usage (on the OLD vps):
+#   bash 02-authorize-pull.sh "ssh-ed25519 AAAA... octra-migration@onode"
+#   bash 02-authorize-pull.sh /root/migration/target_ssh_key.pub
+#
+# Idempotent — the key is only added once.
+# ===================================================================
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+
+require_root
+
+KEY_INPUT="${1:-${MIG_DIR}/target_ssh_key.pub}"
+[[ -n "${KEY_INPUT}" ]] || die "usage: $0 <pubkey-line|pubkey-file>"
+
+if [[ -f "${KEY_INPUT}" ]]; then
+  PUBKEY=$(tr -d '\r\n' < "${KEY_INPUT}")
+else
+  PUBKEY=$(printf '%s' "${KEY_INPUT}" | tr -d '\r\n')
+fi
+
+[[ "${PUBKEY}" == ssh-* ]] || die "not a public key: ${PUBKEY:0:40}..."
+
+install -d -m 700 /root/.ssh
+touch /root/.ssh/authorized_keys
+chmod 600 /root/.ssh/authorized_keys
+
+if grep -qxF "${PUBKEY}" /root/.ssh/authorized_keys; then
+  log "Key already authorized — nothing to do"
+else
+  printf '%s\n' "${PUBKEY}" >> /root/.ssh/authorized_keys
+  log "Key authorized for root"
+fi
+
+log "authorized_keys now holds $(wc -l < /root/.ssh/authorized_keys) key(s)"
+set_status DONE "authorize-pull"

package/assets/migrate/03-pull-state.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# ===================================================================
+# 03-pull-state.sh — copy the whole validator from OLD VPS to this one
+#
+#   pull 1 (initial) : while the old node is STILL RUNNING
+#                      → whole-file mode (-W), fastest for a cold copy
+#   pull 2 (final)   : after 04-stop-source.sh has stopped the old node
+#                      → rolling-checksum delta, so only appended bytes
+#                        of the live store suffixes are sent
+#
+# Usage (on the NEW vps):
+#   OLD_HOST=203.0.113.27 bash 03-pull-state.sh            # initial
+#   OLD_HOST=203.0.113.27 bash 03-pull-state.sh --final    # delta
+#
+# Copies:
+#   /opt/octra/libv_litecore/   (source tree, toolchain, binaries, .keys)
+#   /var/lib/octra/devnet/      (chain state, 39 GB)
+#   /var/lib/octra/devnet.state_sync/
+# ===================================================================
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+
+require_root
+require_old_host
+require_cmd rsync
+
+MODE="initial"
+[[ "${1:-}" == "--final" ]] && MODE="final"
+
+RSYNC_OPTS=(-aH --numeric-ids --info=progress2 --stats --no-inc-recursive)
+if [[ "${MODE}" == "initial" ]]; then
+  RSYNC_OPTS+=(-W)
+else
+  # delta mode: list everything so appended store bytes are found quickly
+  RSYNC_OPTS=(-aH --numeric-ids --info=progress2 --stats --delete --delete-delay)
+fi
+
+FREE_GB=$(df -BG --output=avail "${NODE_DATA_ROOT}" | tail -1 | tr -dc '0-9')
+[[ "${FREE_GB}" -ge 60 ]] || die "not enough free space on ${NODE_DATA_ROOT} (${FREE_GB}G)"
+
+# While the source node is RUNNING its logs/WAL/receipt files vanish under
+# rsync's feet, which makes rsync exit 23/24. That is expected: the final
+# delta pass (run with the source stopped) reconciles whatever moved.
+RSYNC_TOLERANT=(23 24)
+run_rsync() {  # run_rsync <label> <src> <dst>
+  local label="$1" src="$2" dst="$3" rc=0
+  log "--- ${label} ---"
+  # rsync 3.5 prints one progress line per parallel transfer thread, which
+  # produced multi-megabyte single-line log entries. Collapse each update to
+  # its last "bytes  N%  rate" field and keep byte totals / warnings, so the
+  # log stays readable while the orchestrator can still poll the percentage.
+  # set +e / PIPESTATUS: grep returns 1 when nothing matches, and we must not
+  # lose rsync's own exit code.
+  set +e
+  rsync "${RSYNC_OPTS[@]}" \
+    -e "ssh ${SSH_OPTS[*]} -o Compression=no" \
+    "${src}" "${dst}" 2>&1 \
+    | tr '\r' '\n' \
+    | grep -a --line-buffered -E '[0-9]+%|^sent |^total size|^rsync' \
+    | sed -u -E 's/^.* ([0-9,]+ +[0-9]+% +[0-9.]+[kMG]?B\/s).*$/\1/'
+  rc=${PIPESTATUS[0]}
+  set -e
+  if (( rc == 0 )); then
+    return 0
+  fi
+  local tolerated=0
+  for code in "${RSYNC_TOLERANT[@]}"; do
+    [[ "${rc}" -eq "${code}" ]] && tolerated=1
+  done
+  if (( tolerated == 1 )); then
+    warn "${label}: rsync exit ${rc} (files changed during the copy) — tolerated on a live node; the --final pass fixes it"
+    return 0
+  fi
+  die "${label}: rsync failed with exit ${rc}"
+}
+
+set_status RUNNING "pull-${MODE}"
+START=$(date +%s)
+log "=== pull (${MODE}) from ${OLD_USER}@${OLD_HOST} ==="
+
+run_rsync "1/3 source tree ${NODE_SRC_DIR}" \
+  "${OLD_USER}@${OLD_HOST}:${NODE_SRC_DIR}/" "${NODE_SRC_DIR}/"
+
+mkdir -p "${NODE_DATA_DIR}"
+run_rsync "2/3 chain state ${NODE_DATA_DIR}" \
+  "${OLD_USER}@${OLD_HOST}:${NODE_DATA_DIR}/" "${NODE_DATA_DIR}/"
+
+mkdir -p "${NODE_SYNC_STAGE}"
+if on_old "test -d ${NODE_SYNC_STAGE}"; then
+  run_rsync "3/3 state-sync stage ${NODE_SYNC_STAGE}" \
+    "${OLD_USER}@${OLD_HOST}:${NODE_SYNC_STAGE}/" "${NODE_SYNC_STAGE}/"
+else
+  warn "state-sync stage does not exist on the source — skipped"
+fi
+
+ELAPSED=$(( $(date +%s) - START ))
+log "=== pull (${MODE}) finished in $((ELAPSED / 60))m$((ELAPSED % 60))s ==="
+log "Local size: src $(du -sh "${NODE_SRC_DIR}" | awk '{print $1}'), data $(du -sh "${NODE_DATA_DIR}" | awk '{print $1}')"
+log "Source size: $(on_old "du -sh ${NODE_SRC_DIR} ${NODE_DATA_DIR} 2>/dev/null | tr '\n' ' '")"
+
+set_status DONE "pull-${MODE}" "${ELAPSED}s"

package/assets/migrate/04-stop-source.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# ===================================================================
+# 04-stop-source.sh — stop the validator on the OLD VPS (decommission)
+#
+# A validator wallet must NEVER be active on two machines at once
+# (double-signing / equivocation). This step:
+#   1. records the last status of the old node
+#   2. stops it via the node's own controls/stop.sh (pm2)
+#   3. proves no octra_node process is left
+#   4. disables the pm2 boot unit so it cannot resurrect after a reboot
+#   5. drops a decommission note in the old node's home
+#
+# Usage (on the NEW vps):
+#   OLD_HOST=203.0.113.27 bash 04-stop-source.sh
+# ===================================================================
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+
+require_root
+require_old_host
+set_status RUNNING "stop-source"
+log "=== stopping node on ${OLD_HOST} ==="
+
+# --- 1. record final status of the source node ----------------------
+# Keep the first (running) snapshot: on a re-run the node is already down
+# and the status no longer carries the live epoch/voting fields.
+if [[ ! -s "${MIG_DIR}/source-final-stat.txt" ]] || ! grep -q '^address = ' "${MIG_DIR}/source-final-stat.txt"; then
+  log "Capturing final status of the old node..."
+  on_old "su - ${NODE_USER} -c 'cd ${NODE_SRC_DIR} && sh controls/stat.sh' 2>&1" \
+    | tee "${MIG_DIR}/source-final-stat.txt" | grep -E '^(role|address|epoch|head_epoch|voting|validator_active) =' || true
+else
+  log "Keeping existing source status snapshot ($(grep -m1 '^address = ' "${MIG_DIR}/source-final-stat.txt"))"
+fi
+
+WALLET_ADDRESS=$(grep -m1 '^address = ' "${MIG_DIR}/source-final-stat.txt" | awk -F' = ' '{print $2}' || true)
+[[ -n "${WALLET_ADDRESS}" ]] || warn "could not read wallet address from source status"
+log "Source wallet: ${WALLET_ADDRESS:-unknown}"
+
+# --- 2. graceful stop ----------------------------------------------
+log "Running controls/stop.sh on the source..."
+on_old "su - ${NODE_USER} -c 'cd ${NODE_SRC_DIR} && sh controls/stop.sh' 2>&1" | tee -a "${MIG_LOG}"
+
+# --- 3. verify nothing is left running -----------------------------
+LEFT=$(on_old_node_processes)
+for i in {1..20}; do
+  [[ -z "${LEFT}" ]] && break
+  sleep 1
+  LEFT=$(on_old_node_processes)
+done
+
+if [[ -n "${LEFT}" ]]; then
+  warn "node processes still alive after stop — sending SIGTERM"
+  on_old "pkill -TERM -f '${NODE_PROC_RE}' || true"
+  sleep 5
+  LEFT=$(on_old_node_processes)
+fi
+if [[ -n "${LEFT}" ]]; then
+  die "could not stop the source node — DO NOT start the new node (wallet would be double-active)"
+fi
+log "Source node processes are gone (none left)"
+
+# --- 4. make sure it cannot come back on reboot ---------------------
+if on_old "systemctl is-enabled --quiet pm2-${NODE_USER} 2>/dev/null"; then
+  on_old "systemctl disable pm2-${NODE_USER} 2>/dev/null || true"
+  log "Disabled pm2-${NODE_USER} boot unit on the source"
+else
+  log "pm2 boot unit on the source already disabled"
+fi
+on_old "su - ${NODE_USER} -c 'pm2 save --force' >/dev/null 2>&1 || true"
+
+# --- 5. decommission note ------------------------------------------
+on_old "cat > /root/MIGRATED-AWAY.txt <<'EOF'
+This VPS no longer runs the Octra validator.
+The validator (wallet ${WALLET_ADDRESS:-unknown}) was migrated on $(date -u +%Y-%m-%dT%H:%M:%SZ).
+New host: $(hostname) / see the operator's records.
+DO NOT start the node here again while the new host is live: the same wallet
+would be active twice and the validator would equivocate.
+EOF"
+log "Decommission note written to ${OLD_HOST}:/root/MIGRATED-AWAY.txt"
+
+log "=== source stopped — safe to run the final delta pull ==="
+date -u +%Y-%m-%dT%H:%M:%SZ > "${MIG_DIR}/downtime-start.txt"
+log "downtime clock started: $(cat "${MIG_DIR}/downtime-start.txt")"
+set_status DONE "stop-source"

package/assets/migrate/05-finalize-target.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# ===================================================================
+# 05-finalize-target.sh — make the copied tree bootable on this host
+#
+#   1. back up node.env and point OCTRA_ADVERTISE_ENDPOINT at this VPS
+#   2. verify the binary hashes still match node.env (integrity gate)
+#   3. fix ownership (the copy may carry the source's numeric uid)
+#   4. run controls/install.sh (runtime libs + nodejs + pm2 + boot unit)
+#   5. run controls/lib/validator_config.py --check-runtime
+#
+# Nothing here touches config/network.env, the chain data or the wallet:
+# a migrated validator must NOT re-sync and must NOT re-enroll.
+#
+# Usage (on the NEW vps):
+#   NEW_HOST=203.0.113.133 bash 05-finalize-target.sh
+# ===================================================================
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+
+require_root
+NEW_HOST="${NEW_HOST:-${1:-}}"
+[[ -n "${NEW_HOST}" ]] || NEW_HOST=$(curl -s --max-time 5 https://api.ipify.org 2>/dev/null || hostname -I | awk '{print $1}')
+
+[[ -f "${NODE_ENV}" ]] || die "node.env missing at ${NODE_ENV} — did the pull complete?"
+[[ -f "${NODE_SRC_DIR}/.keys/validator/wallet.json" ]] || die "wallet.json missing"
+set_status RUNNING "finalize-target"
+
+# --- 1. advertise endpoint (the only host-specific field) -----------
+log "=== finalize (advertise → ${NEW_HOST}:${CONSENSUS_PORT}) ==="
+CURRENT_ADV=$(grep -m1 '^OCTRA_ADVERTISE_ENDPOINT=' "${NODE_ENV}" | cut -d= -f2-)
+log "current advertise: ${CURRENT_ADV}"
+
+if [[ "${CURRENT_ADV}" == "${NEW_HOST}:${CONSENSUS_PORT}" ]]; then
+  log "advertise already correct"
+else
+  cp -a "${NODE_ENV}" "${NODE_ENV}.pre-migration.bak"
+  sed -i "s|^OCTRA_ADVERTISE_ENDPOINT=.*|OCTRA_ADVERTISE_ENDPOINT=${NEW_HOST}:${CONSENSUS_PORT}|" "${NODE_ENV}"
+  log "advertise updated: $(grep -m1 '^OCTRA_ADVERTISE_ENDPOINT=' "${NODE_ENV}")"
+  log "backup kept at ${NODE_ENV}.pre-migration.bak"
+fi
+
+# --- 2. integrity gate: binaries must still match node.env ---------
+log "Verifying binary hashes against node.env..."
+check_hash() {  # check_hash <env_key> <file>
+  local key="$1" file="$2" want got
+  want=$(grep -m1 "^${key}=" "${NODE_ENV}" | cut -d= -f2-)
+  got=$(sha256sum "${file}" | awk '{print $1}')
+  if [[ "${want}" != "${got}" ]]; then
+    die "${key} mismatch: env=${want} file=${got} (${file})"
+  fi
+  log "  ${key} OK"
+}
+check_hash OCTRA_BINARY_HASH                "${NODE_SRC_DIR}/_build/default/bin/octra_node.exe"
+check_hash OCTRA_PVAC_VERIFY_WORKER_HASH    "${NODE_SRC_DIR}/_build/default/bin/octra_pvac_worker.exe"
+check_hash OCTRA_OPERATOR_SYNC_BINARY_HASH  "${NODE_SRC_DIR}/_build/default/bin/octra_state_sync_client.exe"
+check_hash OCTRA_OPERATOR_CONTROL_BINARY_HASH "${NODE_SRC_DIR}/_build/default/bin/bft_control_tx.exe"
+
+NET_WANT=$(grep -m1 '^OCTRA_OPERATOR_NETWORK_SHA256=' "${NODE_ENV}" | cut -d= -f2-)
+for f in "${NODE_SRC_DIR}/.keys/validator/network.env" "${NODE_SRC_DIR}/config/network.env"; do
+  [[ "$(sha256sum "$f" | awk '{print $1}')" == "${NET_WANT}" ]] || die "network bundle hash mismatch: $f"
+done
+log "  network bundle OK ($(grep -m1 '^OCTRA_CHAIN_ID=' "${NODE_ENV}"))"
+
+# --- 3. ownership ---------------------------------------------------
+log "Fixing ownership (${NODE_USER})..."
+chown -R "${NODE_USER}:${NODE_USER}" "${NODE_SRC_DIR}" "${NODE_DATA_ROOT}"
+chmod 700 "${NODE_SRC_DIR}/.keys/validator" "${NODE_DATA_DIR}" 2>/dev/null || true
+chmod 600 "${NODE_SRC_DIR}/.keys/validator/"*.json "${NODE_ENV}" 2>/dev/null || true
+
+# --- 4. runtime packages + process manager --------------------------
+# `install.sh` runs apt-get + npm, which can take minutes. Holding a single SSH
+# session open for that long is what killed the 2026-10-30 run ("Network error:
+# Software caused connection abort" mid-apt), so it runs detached in a systemd
+# unit and this script only polls a status file. A dropped SSH is then harmless:
+# re-running this step picks up the finished install.
+if command -v pm2 >/dev/null 2>&1 &&    dpkg -s libev4 libgmp10 liblmdb0 nodejs npm >/dev/null 2>&1; then
+  log "Runtime packages + pm2 already installed - skipping install.sh"
+else
+  INSTALL_UNIT="octra-finalize-install"
+  INSTALL_LOG="${MIG_DIR}/install-target.log"
+  INSTALL_STATUS="${MIG_DIR}/install-target.status"
+  INSTALL_TIMEOUT="${INSTALL_TIMEOUT:-1800}"
+  rm -f "${INSTALL_LOG}" "${INSTALL_STATUS}"
+  systemctl reset-failed "${INSTALL_UNIT}" 2>/dev/null || true
+
+  log "Running controls/install.sh detached (runtime libs, nodejs, pm2, boot unit)..."
+  systemd-run --unit="${INSTALL_UNIT}" --collect --no-block \
+    --working-directory="${NODE_SRC_DIR}" \
+    --setenv=OCTRA_OPERATOR_USER="${NODE_USER}" \
+    --setenv=OCTRA_DATA_ROOT="${NODE_DATA_ROOT}" \
+    --setenv=DEBIAN_FRONTEND=noninteractive \
+    --setenv=TERM=dumb \
+    bash -c "sh controls/install.sh > '${INSTALL_LOG}' 2>&1; echo \$? > '${INSTALL_STATUS}'"
+
+  log "install.sh runs as systemd unit ${INSTALL_UNIT} - polling (SSH may drop safely)"
+  START_TS=$(date +%s)
+  LAST_LOG=$START_TS
+  while [[ ! -s "${INSTALL_STATUS}" ]]; do
+    ELAPSED=$(( $(date +%s) - START_TS ))
+    if (( ELAPSED > INSTALL_TIMEOUT )); then
+      die "install.sh did not finish in ${INSTALL_TIMEOUT}s (see ${INSTALL_LOG})"
+    fi
+    # One line every 30 s: a \r progress line becomes its own row in the console,
+    # so a 5-minute apt run used to print ~30 near-identical rows.
+    if (( $(date +%s) - LAST_LOG >= 30 )); then
+      log "  install.sh still running... ${ELAPSED}s of ${INSTALL_TIMEOUT}s (unit ${INSTALL_UNIT})"
+      LAST_LOG=$(date +%s)
+    fi
+    sleep 10
+  done
+  log "install.sh finished in $(( $(date +%s) - START_TS ))s"
+
+  INSTALL_RC=$(tr -dc '0-9' < "${INSTALL_STATUS}")
+  tail -n 8 "${INSTALL_LOG}" 2>/dev/null | sed 's/^/    /' || true
+  [[ "${INSTALL_RC}" == "0" ]] || die "install.sh failed (exit ${INSTALL_RC}) - log: ${INSTALL_LOG}"
+fi
+command -v pm2 >/dev/null || die "pm2 was not installed by install.sh"
+log "pm2: $(pm2 -v)"
+
+# --- 5. runtime binding check --------------------------------------
+log "Checking runtime binding (--check-runtime)..."
+as_octra "cd ${NODE_SRC_DIR} && python3 controls/lib/validator_config.py --check-runtime --config ${NODE_ENV}" \
+  || die "runtime binding check failed"
+log "runtime binding OK"
+
+ADDRESS=$(jq -r '.address' "${NODE_SRC_DIR}/.keys/validator/wallet.json")
+log "wallet address on target: ${ADDRESS}"
+if [[ -f "${MIG_DIR}/source-final-stat.txt" ]]; then
+  SRC_ADDR=$(grep -m1 '^address = ' "${MIG_DIR}/source-final-stat.txt" | awk -F' = ' '{print $2}' || true)
+  if [[ -n "${SRC_ADDR}" && "${SRC_ADDR}" != "${ADDRESS}" ]]; then
+    die "wallet mismatch! source=${SRC_ADDR} target=${ADDRESS}"
+  fi
+  log "wallet matches the source validator: ${SRC_ADDR:-unknown}"
+fi
+# recorded for 07-verify.sh (and for the runbook)
+printf '%s\n' "${ADDRESS}" > "${MIG_DIR}/source-address.txt"
+
+log "=== finalize done — target is ready to start ==="
+set_status DONE "finalize-target" "${ADDRESS}"

package/assets/migrate/06-start-target.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# ===================================================================
+# 06-start-target.sh — start the migrated validator on the NEW vps
+#
+# Uses the node's own controls/run.sh, which performs:
+#   --check-runtime → validator_recover → validator_guard →
+#   validator_process → pm2 start
+#
+# Usage (on the NEW vps):
+#   bash 06-start-target.sh
+# ===================================================================
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+
+require_root
+[[ -f "${NODE_ENV}" ]] || die "node.env missing — run 05-finalize-target.sh first"
+set_status RUNNING "start-target"
+
+# --- Double-signing guard -------------------------------------------
+# Two live copies of one validator wallet would equivocate. If OLD_HOST is
+# given, refuse to start unless the source node is provably stopped.
+if [[ -n "${OLD_HOST}" ]]; then
+  require_old_host
+  if [[ -n "$(on_old_node_processes)" ]]; then
+    die "the source node on ${OLD_HOST} is STILL RUNNING — refusing to start a second copy of the wallet"
+  fi
+  log "source node on ${OLD_HOST} confirmed stopped"
+fi
+
+log "=== starting the node on $(hostname) ==="
+# Idempotent: never restart a node that is already up. A restart costs a full
+# ~38 GB store open plus RPC catch-up, so "start" must mean "ensure running".
+# A node that is already online is normal here: controls/install.sh (finalize)
+# starts it, and this step only has to prove it is up.
+if [[ -n "$(node_processes)" ]]; then
+  log "node already running - not restarting: $(node_processes | awk '{print $1, $2}' | head -1)"
+else
+  as_octra "cd ${NODE_SRC_DIR} && sh controls/run.sh" 2>&1 | tee -a "${MIG_LOG}"
+fi
+
+log "Waiting for the process to come up..."
+sleep 10
+
+log "--- pm2 ---"
+as_octra "pm2 list" 2>/dev/null || warn "pm2 list failed"
+
+log "--- status ---"
+node_stat | tee "${MIG_DIR}/target-initial-stat.txt" | \
+  grep -E '^(node|role|address|process|pid|rpc|epoch|head_epoch|voting|validator_active|validator_enrollment|p2p_connected) =' || true
+
+if grep -q '^process = online' "${MIG_DIR}/target-initial-stat.txt"; then
+  log "=== node is up ==="
+  set_status DONE "start-target"
+else
+  die "node did not reach process = online — check pm2 logs: pm2 logs ${NODE_PM2_NAME:-octra-node-1}"
+fi