feat(validator): add SYNC_MODE so a fresh validator can warp sync

mainnet/validator/.env.example

@@ -13,6 +13,35 @@ VALIDATOR_NAME=Choose-Your-Validator-Name
 #   openssl rand -hex 32
 VALIDATOR_NODE_KEY=
 
+# ─── Sync ────────────────────────────────────────────────────────────────────
+
+# Empty = full sync, which is what a validator should normally run.
+#
+# `--sync warp` is for bootstrapping a NEW validator on an empty volume: it
+# proves finality and fetches the latest state instead of replaying every
+# block. Two things decide whether it does anything at all:
+#
+#   - Once the node has finalized state on disk it is ignored, and the node
+#     logs "Can't use warp sync mode with a partially synced database.
+#     Reverting to full sync mode." So setting this on a validator that has
+#     already synced changes nothing — it only does something on a fresh
+#     volume. (A volume that exists but never got past genesis, e.g. one that
+#     never found peers, still warps on restart.)
+#   - It waits for 3 peers before it starts, so on a small --reserved-only
+#     network it sits idle until enough of them are up.
+#
+# What it costs: this node does not run --blocks-pruning archive, so the gap
+# left behind is backfilled with HEADERS ONLY. It ends up with no block bodies
+# before the sync point, permanently. Fine for authoring from here on, not fine
+# if this node ever has to serve or replay history.
+#
+# Only the validator roles take this knob. The rpc and indexer-rpc nodes run
+# --blocks-pruning archive, and an archive node refuses to start under warp:
+# "Warp sync doesn't work for archive nodes", and the container crash-loops.
+#
+#   SYNC_MODE=--sync warp
+SYNC_MODE=
+
 # ─── Telemetry ───────────────────────────────────────────────────────────────
 
 # https://telemetry.orbinum.network — on by default. Publishes name, version,

mainnet/validator/docker-compose.yml

@@ -19,6 +19,7 @@ services:
       --chain /chain-specs/mainnet-spec.json
       --name "${VALIDATOR_NAME:-Orbinum-Validator}"
       --base-path /data
+      ${SYNC_MODE}
       --listen-addr /ip4/0.0.0.0/tcp/${P2P_PORT:-30333}
       --validator
       --node-key ${VALIDATOR_NODE_KEY}

testnet/validator/.env.example

@@ -13,6 +13,35 @@ VALIDATOR_NAME=Choose-Your-Validator-Name
 #   openssl rand -hex 32
 VALIDATOR_NODE_KEY=
 
+# ─── Sync ────────────────────────────────────────────────────────────────────
+
+# Empty = full sync, which is what a validator should normally run.
+#
+# `--sync warp` is for bootstrapping a NEW validator on an empty volume: it
+# proves finality and fetches the latest state instead of replaying every
+# block. Two things decide whether it does anything at all:
+#
+#   - Once the node has finalized state on disk it is ignored, and the node
+#     logs "Can't use warp sync mode with a partially synced database.
+#     Reverting to full sync mode." So setting this on a validator that has
+#     already synced changes nothing — it only does something on a fresh
+#     volume. (A volume that exists but never got past genesis, e.g. one that
+#     never found peers, still warps on restart.)
+#   - It waits for 3 peers before it starts, so on a small --reserved-only
+#     network it sits idle until enough of them are up.
+#
+# What it costs: this node does not run --blocks-pruning archive, so the gap
+# left behind is backfilled with HEADERS ONLY. It ends up with no block bodies
+# before the sync point, permanently. Fine for authoring from here on, not fine
+# if this node ever has to serve or replay history.
+#
+# Only the validator roles take this knob. The rpc and indexer-rpc nodes run
+# --blocks-pruning archive, and an archive node refuses to start under warp:
+# "Warp sync doesn't work for archive nodes", and the container crash-loops.
+#
+#   SYNC_MODE=--sync warp
+SYNC_MODE=
+
 # ─── Telemetry ───────────────────────────────────────────────────────────────
 
 # https://telemetry.orbinum.network — on by default. Publishes name, version,

testnet/validator/docker-compose.yml

@@ -20,6 +20,7 @@ services:
       --chain /chain-specs/testnet-spec.json
       --name "${VALIDATOR_NAME:-Orbinum-Validator}"
       --base-path /data
+      ${SYNC_MODE}
       --listen-addr /ip4/0.0.0.0/tcp/${P2P_PORT:-30333}
       --validator
       --node-key ${VALIDATOR_NODE_KEY}