Skip to main content

Getting Started with Validators

This guide walks you through setting up your own beacon validator. Validators independently verify beacon rounds and submit signed attestations, increasing the network's trustworthiness.

What is a Validator?​

A validator is a service that:

  1. Fetches block data from blockchain sources
  2. Computes the beacon hash using the same algorithm as rng.dev
  3. Compares the result against what rng.dev published
  4. Submits a signed attestation confirming the verification

When multiple independent validators agree on a round's output, users gain confidence that the beacon is operating correctly.

Prerequisites​

Before you begin, you'll need:

  • A server with internet access (1 vCPU, 512MB RAM minimum)
  • Docker installed (installation guide)
  • An Ethereum wallet (MetaMask or any compatible wallet)
  • A Gitcoin Passport with score >= 20 (create one)

Step 1: Create Your Gitcoin Passport​

Validators must prove they're human using Gitcoin Passport. This prevents Sybil attacks where one entity runs many validators.

  1. Go to passport.gitcoin.co
  2. Connect your Ethereum wallet
  3. Complete verification stamps until your score reaches 20 or higher
  4. Common stamps: GitHub, Twitter, Google, Discord, BrightID

Your Passport score determines your validator type:

ScoreTypeWeight
>= 20Community1
>= 20 + ID VerificationCommunity+2

Step 2: SSH to Your Server with Port Forwarding​

The validator runs on your server but you'll complete registration from your local browser (where MetaMask is installed). SSH port forwarding makes this possible:

# From your laptop/desktop
ssh -L 8080:localhost:8080 user@your-server

This creates a secure tunnel so http://localhost:8080 on your machine connects to port 8080 on your server.

Why Port Forwarding?
  • Validator stays private (only binds to localhost on server)
  • No firewall changes needed
  • Secure - all traffic is encrypted through SSH
  • MetaMask works because the page loads in YOUR browser

Step 3: Run the Validator Container​

On your server (via the SSH session), run:

docker run -d \
  --name beacon-validator \
  --restart unless-stopped \
  -p 8080:8080 \
  -v validator-data:/data \
  ghcr.io/rngdotdev/beacon-validator:latest

The validator will:

  1. Generate an Ed25519 keypair (stored in the volume)
  2. Start the local web UI on port 8080
  3. Wait for registration before attesting

Step 4: Complete Registration​

  1. Open your browser to http://localhost:8080 (this is tunneled to your server)
  2. You'll see the validator status as "Waiting for Registration"
  3. Click Connect Wallet and approve the connection in MetaMask
  4. Your Gitcoin Passport score will be checked automatically
  5. Enter a name for your validator
  6. Click Sign & Register Validator
  7. Sign the message in MetaMask to prove wallet ownership
  8. Registration is submitted to rng.dev and your validator ID is saved automatically

The registration message you sign includes:

  • Your validator's key fingerprint
  • A timestamp (to prevent replay attacks)

Step 5: Verify It's Working​

After registration, the validator starts attesting immediately. Check the web UI at http://localhost:8080 to see:

  • Status changes to "Active"
  • Attestations submitted counter increases
  • Accuracy percentage

You can also check the logs:

docker logs -f beacon-validator

You should see output like:

2026-04-03T12:00:00Z INFO  Starting beacon validator...
2026-04-03T12:00:00Z INFO  Validator ID: abc123...
2026-04-03T12:00:01Z INFO  Round 1712145600: Verified (hash matches)
2026-04-03T12:00:01Z INFO  Round 1712145600: Attestation submitted

Troubleshooting​

"Passport score too low"​

Your Gitcoin Passport score must be at least 20. Visit passport.gitcoin.co and complete more verification stamps.

"No Ethereum wallet found"​

MetaMask or another Ethereum wallet must be installed in your browser. The registration page loads from localhost:8080 (via SSH tunnel), so your browser extensions work normally.

Port 8080 already in use​

If something else is using port 8080:

# Check what's using the port
lsof -i :8080

# Use a different port
docker run -d -p 9090:8080 -v validator-data:/data ghcr.io/rngdotdev/beacon-validator:latest

# SSH with the new port
ssh -L 9090:localhost:9090 user@your-server

"Connection refused" or network errors​

Check that your server has outbound internet access. The validator needs to reach:

  • rng.dev (beacon API)
  • Various blockchain RPC endpoints

Validator not appearing on dashboard​

After registration, it may take a few seconds for your validator to appear. The validator starts attesting immediately upon successful registration.

Stopping and Restarting​

# Stop the validator
docker stop beacon-validator

# Start it again
docker start beacon-validator

# View logs
docker logs -f beacon-validator

Your keys and validator ID are stored in the validator-data volume, so they persist across restarts.

Running Without SSH Tunnel​

If you prefer, you can expose the validator UI directly (not recommended for production):

# Run with external access (less secure)
docker run -d \
  -p 0.0.0.0:8080:8080 \
  -v validator-data:/data \
  ghcr.io/rngdotdev/beacon-validator:latest

Then access http://your-server-ip:8080 directly. However, this exposes your validator UI to the internet.

Next Steps​

Upgrading to Community+​

After your validator is running successfully, you can upgrade to Community+ (weight 2) by completing ID verification:

  1. Go to your dashboard
  2. In the Validator tab, click Upgrade to Community+
  3. Complete the ID verification process
  4. Your validator weight increases from 1 to 2

This helps prove you're a unique human, further strengthening the network.