Validator operations

Keep the existing state directory, wallet, RPC configuration and signing command. Never clear a journal or rerun init to make an error disappear. Pending commitments remain on chain when the process stops.

#Upgrade an existing validator

The reviewed release is v0.5.1. Stop the existing process before replacing it, and restart with the same state and signing settings. For an existing official Compose installation:

docker compose stop validator
export VALIDATOR_IMAGE=ghcr.io/everyframe-studio/everyframe-validator:v0.5.1
docker compose pull validator
docker compose run --rm --no-deps validator --version
docker compose run --rm --no-deps validator doctor --state-dir /state
docker compose run --rm --no-deps validator doctor --state-dir /state --check-emissions
docker compose up -d validator
docker compose logs --tail 100 validator

Keep your existing Compose signing override, state volume and wallet mounts. For source installations, install the official release wheel into the service's existing virtual environment while that service is stopped. Do not renew authorization merely to upgrade.

v0.5.0 and older cannot read the current chain-derived emission evidence; v0.4.x also lacks the shared assignment scheduler. Upgrading independent validators to a compatible reader does not require changing chain parameters or replaying old epochs.

#Check status and signing readiness

everyframe-validator status --state-dir ./state/mainnet117
everyframe-validator doctor --state-dir ./state/mainnet117
everyframe-validator doctor --state-dir ./state/mainnet117 --check-emissions
everyframe-validator reconcile --state-dir ./state/mainnet117

Status is the latest completed iteration, not a heartbeat or payment receipt. Doctor checks local prerequisites and network evidence without sending a transaction. Check both the overall result and signing prerequisites. Offline diagnosis cannot establish live chain readiness.

#Wallet path or required file missing

Inspect only the profile's wallet name, hotkey name and wallet-root fields. Correct the root to the parent of named wallets; keep the selected hotkey and journals unchanged. Use an absolute path appropriate to the service/container user.

An unencrypted legacy hotkey with public metadata does not need defaultpub.txt. Encrypted or metadata-less files can defer public identity diagnosis until a configured authorized signer unlocks them; doctor does not decrypt a key. A missing or wrong wallet is not fixed by duplicating private bytes into a public file.

After correcting the path, rerun doctor and --check-emissions. Restart the same existing instance only when its signing prerequisites pass. Do not create a second instance under the same hotkey.

#Archive and emission-history errors

Mainnet defaults to wss://archive.chain.opentensor.ai:443. An alternative endpoint must serve finalized historical state and the expected genesis. To use the same override for doctor, run and reconcile:

export EVERYFRAME_RPC_URL=wss://YOUR_ARCHIVE_RPC
everyframe-validator doctor --state-dir ./state/mainnet117 --check-emissions

Configure an authenticated RPC through the documented API-key environment/file options, not a key in the URL. Check the RPC configuration. Missing history, bad signatures and unavailable evidence must block rather than produce guessed zero-work weights.

#Waiting, uncertain submissions and rewards

Waiting for the chain epoch window, an already-used epoch slot, a pending reveal or an unpublished assignment can be normal. Every validator should follow the same canonical assignment instead of choosing an older local backlog.

For uncertain submissions, inspect status and use reconcile against the existing journal. Do not resend a transaction blindly or clear pending state. Commit finality, reveal, application and received alpha are different milestones. See accounting and consensus and miner reward reconciliation.