diff --git a/docs/validator/README.md b/docs/validator/README.md index 9af84a97..356c7ed8 100644 --- a/docs/validator/README.md +++ b/docs/validator/README.md @@ -1,10 +1,18 @@ -# Validator Submitter Guide (Docker Swarm) +# Validator Guide (Docker Swarm) -This guide is only for normal validators. It installs the submit-only on-chain -weight submitter as a systemd service. The submitter fetches the master weight -vector from the public BASE endpoint and submits it on-chain. It runs -no challenge orchestration: all challenge services run on the BASE -master (manager) node. +This guide covers running a BASE validator on Docker Swarm. There is no +Kubernetes anywhere in BASE: the only backend is Docker Swarm. + +A validator runs in one of a few profiles, from a submit-only on-chain weight +submitter through a full challenge-evaluating validator node. The +[Compute Requirements](#compute-requirements) below size each profile, and the +[Automatic Install (One Command)](#automatic-install-one-command) section brings +up a self-updating validator node with the turnkey installer. + +The simplest profile is the submit-only on-chain weight submitter, installed as a +systemd service. The submitter fetches the master weight vector from the public +BASE endpoint and submits it on-chain. It runs no challenge orchestration: all +challenge services run on the BASE master (manager) node. The default weights endpoint is: @@ -12,6 +20,100 @@ The default weights endpoint is: https://chain.joinbase.ai/v1/weights/latest ``` +## Compute Requirements + +How much compute a validator needs depends on which evaluation work it performs. +The numbers in this table are authoritative. + +| Validator profile | Compute | +|-------------------|---------| +| Submit-only / simple validator (no challenge execution) | 2 vCPU, 4 GB RAM | +| Validator running the base (agent-challenge) evaluation | 8 vCPU, 32 GB RAM | +| PRISM challenge | No additional compute required | + +PRISM adds no compute to the validator: its heavy GPU evaluation is **delegated +to miner-funded worker agents** (the worker plane), and the validator only +performs light verification plus probabilistic replay audits. A validator +therefore never needs a local GPU for PRISM. + +## Automatic Install (One Command) + +`deploy/swarm/install-swarm.sh` is the automatic, one-command install path. On a +blank host it installs everything it needs: Docker Engine (its `ensure_docker` +step), the `uv` runtime (its `ensure_uv` step, when the supervisor is installed), +and the Docker Swarm (`swarm init`). + +### Dry-run by default + +The installer is **dry-run by default**: with no flags it prints every planned +command via its `plan` gate and changes nothing. Pass `--apply` to execute. +Every destructive step stays behind its own explicit flag, so nothing mutates +until you opt in. + +```bash +bash deploy/swarm/install-swarm.sh --help # list flags + required env +bash deploy/swarm/install-swarm.sh # dry-run: prints the plan, changes nothing +``` + +### Auto-update (base-supervisor image-updater) + +`--validator-node` brings up `base validator agent` as an **auto-updatable** +Docker Swarm service (`base-validator-agent`) plus a node-local base-supervisor +whose image-updater digest-pins that service on every new +`base-validator-runtime:latest` digest. That image-updater **is** the +auto-update: the validator's `base` code rolls forward automatically, with no +manual `docker service update`. + +`--install-supervisor` enables the `base-supervisor.service` systemd unit, the +control-plane auto-update unit. Its image-updater runs on a 60s interval, and +optional base self-update is wired only when `SUPERVISOR_SELF_UPDATE_MANIFEST_URL` +is set (otherwise self-update is explicitly disabled, never left inert). + +### Quick start: validator node (dry-run first, then `--apply`) + +Set the required environment, run a dry-run to review the plan, then re-run with +`--apply` (adding `--install-supervisor` to enable the node-local auto-update +unit). + +Required environment for `--validator-node`: + +- `VALIDATOR_MASTER_URL`: the MASTER coordination/gateway root (for example + `http://:19080`). There is no default: a validator must never + point at its own advertise address, so an unset value fails fast. +- `VALIDATOR_BROKER_TOKEN`: the validator's own broker token (mounted at + `/run/secrets/base_broker_token`). +- the validator hotkey wallet, staged under `VALIDATOR_WALLET_PATH` (default + `/var/lib/base/wallets`), wallet name `VALIDATOR_WALLET_NAME`. + +`VALIDATOR_CAPABILITIES` selects the evaluation work this node performs: + +- `["cpu"]` (default): the base agent-challenge (Terminal-Bench) CPU + evaluation. +- PRISM GPU evaluation is **delegated** to the miner-funded worker plane, so a + validator needs no GPU capability for PRISM; it only performs light + verification plus probabilistic replay audits. (`["gpu","cpu"]` remains + available for the legacy path where a validator itself runs PRISM GPU + re-execution at concurrency 1.) + +```bash +export VALIDATOR_MASTER_URL="http://:19080" +export VALIDATOR_BROKER_TOKEN="" +export VALIDATOR_CAPABILITIES='["cpu"]' # base agent-challenge; PRISM is delegated +# stage the validator hotkey wallet under /var/lib/base/wallets first + +# 1) DRY-RUN (default): prints the planned docker swarm commands, changes nothing +bash deploy/swarm/install-swarm.sh --validator-node + +# 2) APPLY: execute, and enable the node-local auto-update supervisor unit +bash deploy/swarm/install-swarm.sh --validator-node --apply --install-supervisor +``` + +The dry-run renders the node-local supervisor config +(`validator_agent_target_enabled: true`, watching +`base-validator-runtime:latest`) and the per-validator `validator.yaml`, and +prints the `docker service create base-validator-agent ...` it would run. Review +that plan before you pass `--apply`. + ## Secret Rule The submitter needs exactly one secret: the validator hotkey. Never place coldkey @@ -93,9 +195,12 @@ dependency. ### What are the minimum requirements? -A submit-only node needs very little: a Python runtime, network access to the -master endpoint and the chain, and the validator hotkey file. A node that also -acts as the Swarm manager should have at least 2 vCPUs and 8 GB RAM. +See [Compute Requirements](#compute-requirements) above for the authoritative +sizing per validator profile. In short: a submit-only node needs very little (a +Python runtime, network access to the master endpoint and the chain, and the +validator hotkey file) and fits in 2 vCPU / 4 GB RAM. A validator that runs the +base agent-challenge evaluation needs 8 vCPU and 32 GB RAM; PRISM adds no compute +because its GPU evaluation is delegated to the miner-funded worker plane. ### What if the requirements are too high?