Shielded Vote

Validator Setup

zvote-1 (mainnet)

Fresh Join

Use Automatic for the supported install path. Switch to Manual when you need to build from source, manage TLS yourself, or run each setup stage directly.

  1. Provision The Validator Host

    Minimum production requirement: use at least this host size before running Fresh Join.

    Platform
    Linux amd64
    CPU
    4 vCPU
    Memory
    8 GB RAM
    Storage
    120 GB NVMe

    Linux arm64 is also supported. macOS builds are for local development, not production validators.

  2. Run Fresh Join

    Run this on the validator host. It initializes the validator, restores or syncs chain data, registers the operator for approval, and starts the local service.

    curl -fsSL https://shielded-vote.nyc3.digitaloceanspaces.com/join.sh | bash

    The helper server runs with svoted on local port 1317. Wallets submit shares to a public HTTPS URL, so the installer asks how to expose that helper API:

    1. Skip Caddy. Use this if you already handle the public HTTPS certificate with a load balancer or reverse proxy.
    2. Custom domain + Caddy. The script installs Caddy, gets a Let's Encrypt certificate, and proxies https://your-domain to localhost:1317.
    3. Auto sslip.io + Caddy. The script builds a public HTTPS URL from the host's detected IPv4, installs Caddy, and proxies it to localhost:1317.

    When registration finishes, contact Valar Group and tell them your validator is pending approval.

  3. Publish The Vote Server URL

    Add the public HTTPS helper URL to vote_servers[] in prod/dynamic-voting-config.json. If Fresh Join configured Caddy, use the URL it prints. If you skipped Caddy, use the public URL from your own HTTPS proxy. Add one JSON object with url and label, then open a PR from GitHub's edit flow. This can be done while the validator is still pending approval. Edit voting config. For a concrete example, see this merged voting config PR.

  4. Back Up Validator Identity

    Back up config/priv_validator_key.json, config/node_key.json, keyring-test/, pallas.*, and ea.* encrypted off-host. Keep the validator signing key live on exactly one host.

What Your Validator Does

A validator is more than a block producer. It helps keep the private-voting protocol live while preserving the rule that no single party can decrypt individual votes.

  • Runs consensus. Your node participates in the CometBFT validator set, proposes and votes on blocks, and verifies the Shielded Vote transactions that enter the chain.
  • Publishes a vote server. The public HTTPS helper URL lets wallets submit encrypted vote-share payloads. The helper stores them durably, waits until the wallet-provided submit_at time, generates the share reveal proof, and submits MsgRevealShare to the chain.
  • Participates in DKG. When a vote manager starts a round, the chain snapshots eligible validators. Each validator automatically contributes Joint-Feldman DKG material, encrypts per-validator shares with ECIES, verifies the shares it receives, and acks the ceremony. The result is an election authority public key; the private key is never assembled by one validator.
  • Protects private tallying. Wallet votes are ElGamal encrypted to the election authority public key, and the chain accumulates only encrypted totals while the vote is open. When the round moves to tallying, validators automatically submit threshold partial decryptions for the encrypted accumulators.
  • Finalizes aggregate results. Once enough partial decryptions are on-chain, a proposer combines them and submits the plaintext totals. Individual votes are not decrypted; only the aggregate result for each option becomes public.

Safe Snapshot Reset

curl -fsSL https://shielded-vote.nyc3.digitaloceanspaces.com/reset-validator-snapshot.sh | env \
  SVOTE_CHAIN_ID=zvote-1 \
  SVOTE_SNAPSHOT_BASE_URL=https://snapshots.valargroup.org \
  bash

Use this on an existing validator when chain data needs to be replaced from the latest pruned snapshot. The command pins the chain ID and snapshot service shown by this page.

Optional overrides
Variable Default Meaning
SVOTE_HOME $HOME/.svoted Existing validator home to reset.
SVOTE_SNAPSHOT_BASE_URL https://snapshots.valargroup.org Snapshot service base URL.
SVOTE_SERVICE_NAME svoted systemd service name on Linux.
SVOTE_POST_RESTART_SYNC_TIMEOUT 600 Seconds to wait after restart for catching_up=false.
SVOTE_TMPDIR ${TMPDIR:-/tmp} Parent directory for staged snapshot files.

Node Operations

Follow service logs

journalctl -u svoted -f

View syncing status

svoted status --home ~/.svoted | jq '{height: .sync_info.latest_block_height, catching_up: .sync_info.catching_up}'

Monitor The Vote

Use the admin dashboard's active vote page to monitor the live round: Open vote status.

  • Monitor status. This page shows whether the vote is pending, active, tallying, or finalized, plus the information validators need to confirm the vote is progressing. The same dashboard also includes tools for preparing and publishing voting rounds, so validators may see sections that are not part of normal validator monitoring.
  • Interpreting shares. Shares will trickle in for each option during the voting period. The option with the most shares is not necessarily the option with the most voting power behind it: up to 5 notes from a single voter are split across 16 shares, and each share's value depends on the voter's hidden note values. The actual result is only known after the vote reaches tallying and finalizes; there is no public running vote-power total, only the final aggregate.

Coordinated chain upgrades require validators to change binaries at the same height. The full process is:

  1. Coordinators schedule the upgrade at a future height.
  2. At that height the running process stops for all validators.
  3. Validators swap in the updated binary and restart.
  4. Once 2/3 of the voting power comes back online, the chain continues.

The supported path below uses Cosmovisor to perform the binary swap automatically. It also configures checksum-verified downloads and lets you pre-stage the current upgrade for an advance check.


Preparing in advance, by pre-downloading the binaries and configuring checksum-required Cosmovisor auto-download, avoids manual work during this and future upgrade halts.


Important:

  • Never run the same priv_validator_key.json on more than one process, to avoid double-signing.
  • Once this setup is complete, manage the validator only through svoted.service. Do not also run svoted start manually. Cosmovisor running with one child svoted process is the expected setup.
  • Ensure that you are aware of how your binary is configured: regular systemd, Cosmovisor or simply running the binary directly.
What is Cosmovisor?

Cosmovisor is the Cosmos SDK process manager for chain binaries. It runs your validator binary and, at a scheduled upgrade height, switches to the upgrade binary automatically. If the binary was not pre-staged, Cosmovisor can download it from the checksum-pinned URL in the on-chain plan.

These commands support the recommended validator setup. If your hardware or service layout differs from the documented setup, contact us before proceeding.


Automatic download and pre-staging are separate. Automatic download lets Cosmovisor fetch a checksum-pinned binary at the halt if it is not already present. Pre-staging is recommended because it removes that network dependency from the halt.

Choose Your Current Setup

Select how your validator runs today, then follow every step shown for that path.

This path keeps your current Cosmovisor service, enables checksum-required downloads, and pre-stages this upgrade.

  1. Confirm The Scheduled Plan

    Review the scheduled plan details (plan name, halt height, and release tag) on the upgrades page: Open scheduled upgrades. Find the environment variable values under Current plan on that page, then set these once and reuse them in every step below.

    PLAN_NAME=v1.3.1
    RELEASE_TAG=v1.3.1
    UPGRADE_SCRIPT_VERSION=v1.3.1
    CHAIN_API=https://vote-chain-primary.valargroup.org
  2. Pre-Stage The Upgrade Binary

    This downloads and verifies the release without stopping the running validator.

    curl -fsSL https://shielded-vote.nyc3.digitaloceanspaces.com/scripts/upgrade/$UPGRADE_SCRIPT_VERSION/update_chain.sh | sudo bash -s -- \
      --mode prepare --plan-name "$PLAN_NAME" --tag "$RELEASE_TAG" --chain-api "$CHAIN_API"
  3. Enable Automatic Downloads

    Run this once after the service is under Cosmovisor. It allows downloads only from an on-chain upgrade plan and refuses any download without a checksum. The guarded restart keeps running the current binary and fails if it finds another signer process.

    curl -fsSL https://shielded-vote.nyc3.digitaloceanspaces.com/scripts/upgrade/$UPGRADE_SCRIPT_VERSION/update_chain.sh | sudo bash -s -- \
      --mode configure-autodownload --plan-name "$PLAN_NAME" --tag "$RELEASE_TAG" --chain-api "$CHAIN_API"
  4. Verify Readiness (PASS/FAIL)

    Do not proceed on a failed pre-stage check. The final two lines must both report true from the running Cosmovisor process. The checklist also requires exactly one Cosmovisor-managed svoted signer.

    curl -fsSL https://shielded-vote.nyc3.digitaloceanspaces.com/scripts/upgrade/$UPGRADE_SCRIPT_VERSION/update_chain.sh | sudo bash -s -- \
      --mode verify-prestage --plan-name "$PLAN_NAME" --tag "$RELEASE_TAG" --chain-api "$CHAIN_API"
    
    sudo systemctl is-active svoted
    sudo sh -c 'tr "\0" "\n" <"/proc/$(systemctl show svoted -p MainPID --value)/environ"' \
      | grep -E '^DAEMON_(ALLOW_DOWNLOAD_BINARIES|DOWNLOAD_MUST_HAVE_CHECKSUM)=true$'

If verify-prestage fails, stay on the current binary and re-run --mode prepare with the exact plan name. Full operator checklist: Software upgrade runbook.

Run this once on each validator well before a scheduled upgrade. It permanently disables Cosmovisor's local pre-upgrade data copy and removes every existing data-backup-Y-M-D directory. Afterward, rollback requires your own external backup or a fresh Valar snapshot.

The script confirms the chain ID, active systemd service, Cosmovisor process tree, validator home, current binary link, and every deletion target. It briefly restarts svoted.service, verifies that UNSAFE_SKIP_BACKUP=true reached the running process, and only then removes the old backups. Active chain data, Cosmovisor binaries, validator keys, and off-host backups are not removed.

(
set -euo pipefail

script="$(mktemp)"
trap 'rm -f "$script"' EXIT

curl -fsSL \
  "https://shielded-vote.nyc3.digitaloceanspaces.com/scripts/disable-cosmovisor-backups/v1/disable-cosmovisor-backups.sh" \
  -o "$script"
printf '%s  %s\n' '86e8f293478090495eb8c7d53b6f5dae8b38e6a947f4e7a6749d387abd62eb1f' "$script" | sha256sum --check -

sudo bash "$script" \
  --apply \
  --service-name svoted \
  --expected-chain-id zvote-1
)

Do not run this during a chain halt or an upgrade. If the script refuses an unusual service or storage layout, do not bypass the check; contact Valar Group with the printed error.

Destructive Validator Teardown Permanently removes local validator data, keys, and services.

Validator Teardown

This permanently removes the local validator home, validator keys, chain data, and services. If the validator identity files were not backed up first, this operator must join again as a new validator and wait for approval before participating.

Use this when a test host should stop being a validator. If a vote is already in progress, remove or replace this host's public URL in vote_servers[] before clients depend on it.

  1. Run The Teardown Script

    Run this on the validator host. The script requires typing REMOVE VALIDATOR before it deletes local state.

    curl -fsSL https://shielded-vote.nyc3.digitaloceanspaces.com/remove-validator.sh | bash
    • Removes svoted and svoted-join services when present.
    • Deletes ${SVOTE_HOME:-$HOME/.svoted} and local join binaries under ${SVOTE_INSTALL_DIR:-$HOME/.local/bin}.
    • Backs up and removes generated Caddy config only when it clearly belongs to this validator.
  2. Remove Published References

    Remove this host's public helper URL from vote_servers[]. Otherwise clients may keep attempting to submit shares to a server that no longer exists. Edit voting config.

References