How to Become a Farcaster Validator with Snapchain

[christopherwxyz]

How to Become a Farcaster Validator with Snapchain

A practical guide to running your own Snapchain node and becoming a Farcaster network validator, based on Uno's production experience operating a validator on GKE.

---

Table of Contents

1. Background
2. Architecture: Shards and Consensus
3. System Requirements
4. Quick Start: Running a Read Node
5. Monitoring Your Node
6. Becoming a Validator
7. Validator Configuration
8. Production Deployment (Kubernetes/GKE)
9. Networking and Ports
10. Environment Variables and Secrets
11. Operational Tips

---

Background

Snapchain is the decentralized, peer-to-peer network that powers the Farcaster social protocol. It is a blockchain-like data layer that stores all Farcaster messages (casts, reactions, user data, etc.) across a sharded validator set.

Validators participate in consensus to produce blocks. Read nodes sync blocks from the network and serve API queries without participating in consensus.

Start by running a read node. This proves you can operate reliable infrastructure and is a prerequisite for being considered as a validator.

---

Architecture: Shards and Consensus

Snapchain uses 3 shards today, numbered 0, 1, and 2:

Shard	Purpose	Contents
0	Chain metadata	Onchain events (ID Registry, Key Registry, Storage Registry from OP Mainnet and Base), storage lending messages, validator configuration, epoch data. Does NOT contain user data.
1	Data shard	User messages (casts, reactions, user data, verifications, etc.) — FIDs distributed by hash
2	Data shard	User messages — remaining FIDs

Why Shard 0 Matters Most

Shard 0 is the most important shard to sync first:

• Other shards read block events from shard 0 to obtain onchain event data (registry events, storage allocations)
• Shard 0 block production is decoupled from other shards — it can advance independently
• During initial sync, Snapchain performs a "fast catchup" on shard 0 by streaming blocks during replication
• Validator sets for all shards are determined by shard 0 blocks — the node only cares about validator sets from shard 0

When you query /v1/info, you will see separate blockDelay values for each shard. Shard 0 should reach single-digit block delay first, followed by shards 1 and 2.

Consensus

Snapchain uses Malachite BFT consensus. Each shard has its own validator set, and validator sets can change at specific block heights. The current network has 6 validators (5 operated by Neynar/Farcaster, 1 by Uno).

---

System Requirements

Minimum (Read Node)

Resource	Minimum
RAM	8 GB
CPU	4 cores / vCPUs
Storage	2 TB free (SSD recommended)
Network	Public IP, ports 3381–3383 open (TCP + UDP)

Recommended (Validator)

Resource	Recommended
RAM	16 GB
CPU	8–16 cores
Storage	1–2 TB SSD
Network	Static public IP, low-latency connection, ports 3381–3383 open

Uno runs on an n2-highmem-16 (16 vCPUs, 128 GB RAM) with a 1 TB persistent disk. The Snapchain container requests 8 CPU / 64 GB memory with limits of 14 CPU / 64 GB.

---

Quick Start: Running a Read Node

The easiest way to get started is with Docker on a dedicated server or VM.

1. Bootstrap

mkdir ~/snapchain && cd ~/snapchain
curl -sSL https://raw.githubusercontent.com/farcasterxyz/snapchain/refs/heads/main/scripts/snapchain-bootstrap.sh | bash

This downloads snapchain.sh and runs the initial setup. You will be prompted for your operator FID (your Farcaster account ID) and asked to acknowledge that read nodes do not earn rewards.

2. Start the Node

cd ~/snapchain
./snapchain.sh up

This starts the Snapchain container using docker compose with the official farcasterxyz/snapchain:latest image. The default configuration runs as a read node (read_node = true).

3. Wait for Snapshot Sync

A new node downloads ~200 GB of historical snapshots before it begins syncing live blocks. This takes 2–4 hours depending on your bandwidth and disk speed.

Monitor progress:

./snapchain.sh logs

You will see snapshot chunks downloading (chunk_0001.bin, chunk_0002.bin, etc.) followed by decompression and database loading.

4. Verify Sync Status

curl -s http://localhost:3381/v1/info | jq

Sample output:

{
  "version": "0.11.5",
  "shardInfos": [
    {
      "shardId": "0",
      "maxHeight": "29000000",
      "blockDelay": "2",
      "numMessages": "...",
      "numFidRegistrations": "..."
    },
    {
      "shardId": "1",
      "maxHeight": "29000000",
      "blockDelay": "3",
      ...
    },
    {
      "shardId": "2",
      "maxHeight": "29000000",
      "blockDelay": "2",
      ...
    }
  ]
}

Your node is synced when blockDelay values for all shards are in the single digits.

5. Query the Node

# Look up a user's FID
curl -s https://fnames.farcaster.xyz/transfers?name=farcaster | jq '.transfers[0].id'

# Fetch casts by FID
curl -s "http://localhost:3381/v1/castsByFid?fid=1" | jq '.messages[].data.castAddBody.text | select(. != null)'

Managing the Node

./snapchain.sh up       # Start (with logs)
./snapchain.sh down     # Stop
./snapchain.sh logs     # View logs
./snapchain.sh upgrade  # Upgrade to latest version

The bootstrap script sets up a cron job to auto-upgrade on a randomized schedule (weekdays, 0–6 AM) to prevent all nodes upgrading simultaneously.

---

Monitoring Your Node

Basic Health Check

curl -s http://localhost:3381/v1/info | jq '.shardInfos[] | {shardId, blockDelay, maxHeight}'

Grafana Dashboard

The bootstrap installs a Grafana instance on port 3000 with StatsD metrics collection:

http://localhost:3000
# Default credentials: admin / admin

Production Monitoring

For production deployments, we recommend pushing blockDelay per shard to your monitoring system and alerting when blockDelay > 300s for more than 5 minutes. See the monitoring CronJob section for a GCP Cloud Monitoring example.

---

Becoming a Validator

Snapchain validators are not permissionless — you cannot simply stake tokens and join. Validators are coordinated by Neynar (who acquired Farcaster protocol operations). Onboarding is coordinated directly with the Neynar team as of March 2026.

Prerequisites

Before approaching Neynar about becoming a validator:

1. Run a reliable read node — demonstrate uptime, operational competence, and that your node tracks chain head
2. Be known in the Farcaster community as a technically competent operator
3. Have production-grade infrastructure — static IP, monitoring, on-call availability

Step-by-Step Onboarding Process

Once Neynar agrees to onboard you as a validator, the process is:

Step 0: Have a Synced Read Node

Either stand up a new read node and wait for it to sync, or use an existing read node that is already tracking chain head. Your node must be fully synced (blockDelay in single digits for all shards) before proceeding.

Step 1: Generate a Validator Keypair

Generate an Ed25519 keypair. The Snapchain repo provides a command for this:

# From the snapchain repo
cargo run --bin keygen

This produces a private key (your signing key — keep secret) and a public key (shared with other validators).

Step 2: Share Your Node Details with Neynar

Neynar needs three things to update their configs:

Detail	How to Get It
Public IP address	Your node's static public IP (for gossip and RPC)
Public key	The Ed25519 public key from Step 1 (hex-encoded)
PeerId	Neynar can get this from your /v1/info endpoint, but provide it if you have it

Also ensure port 3382 (UDP) allows outbound traffic — this is the gossip port.

Step 3: Convert Your Read Node to Validator Mode

Using the validator config template (see Validator Configuration below):

1. Set read_node = false
2. Set your SNAPCHAIN_CONSENSUS__PRIVATE_KEY environment variable to your private key
3. Set announce_address to your public IP gossip address
4. Set announce_rpc_address to your public IP HTTP address
5. Restart the node

At this point, your node will not sign blocks yet — it is not in the validator set. But it will start tracking consensus, which validates that your setup is correct.

Step 4: Choose Cutover Block Heights

Once your node is running healthily as a validator (tracking consensus without errors):

1. Decide when you want your node to start validating — target 1–3 weeks out
2. Pick block heights for each shard, staggered to minimize risk. Allow approximately 1 block per second when calculating future block heights
3. Activate shard 0 first — it's the metadata shard that all other shards depend on
4. Share the config (with your chosen effective_at block heights) with Neynar so all existing validators can update their configs

Example staggering (approximately 3 days apart per shard):

Shard 0: current_height + ~250,000   (≈ 3 days from now)
Shard 2: current_height + ~540,000   (≈ 6 days)
Shard 1: current_height + ~680,000   (≈ 8 days)

Step 5: Cutover

• Be available during each shard's cutover time in case troubleshooting or devops is needed
• Monitor blockDelay for your shards — it should remain in single digits
• If issues arise, coordinate with Neynar immediately

Uno's Validator Cutover (Reference)

Uno was added as the 6th validator on Feb 23, 2026. Activation was staggered across shards:

Shard	Effective Block Height
0 (metadata)	28,415,000
2 (data)	28,706,000
1 (data)	28,852,000

---

Validator Configuration

The key difference between a read node and a validator is the config.toml. Here is an annotated validator configuration:

# Core settings
rpc_address = "0.0.0.0:3383"
http_address = "0.0.0.0:3381"
rocksdb_dir = "/home/node/app/.rocks"
fc_network = "Mainnet"

# CRITICAL: must be false for validators (true for read nodes)
read_node = false

# StatsD metrics
[statsd]
prefix = "snapchain"
addr = "127.0.0.1:8125"
use_tags = true

# Gossip network configuration
[gossip]
address = "/ip4/0.0.0.0/udp/3382/quic-v1"

# YOUR public IP for gossip (other nodes connect to you here)
announce_address = "/ip4/YOUR_PUBLIC_IP/udp/3382/quic-v1"

# YOUR public IP for RPC (used for block sync)
announce_rpc_address = "http://YOUR_PUBLIC_IP:3381"

# Bootstrap peers — existing validators
bootstrap_peers = "/ip4/54.236.164.51/udp/3382/quic-v1, /ip4/54.87.204.167/udp/3382/quic-v1, /ip4/44.197.255.20/udp/3382/quic-v1, /ip4/54.157.62.17/udp/3382/quic-v1, /ip4/34.195.157.114/udp/3382/quic-v1, /ip4/107.20.169.236/udp/3382/quic-v1"

# Direct peer IDs for reliable connectivity to known validators
direct_peers = "12D3KooWQaoBw2gvdmfGdXjepEQU9i47FXxvsCZ6wu8Vn4gwvHm2,12D3KooWH527dqZTziqzzuXunismeJ3iFVnUxV5spv6VkS7U7zL1,12D3KooWJVyaQRovV1rjV8TzkN3cRiysACyey86kXDLdvf6JRq5Z,12D3KooWGmXDC2SfjSG7h7DchyVJHMB4GpA8JYpHf9iwz8L8BFqB,12D3KooWCc28TYrrXFivwUshyZ8R5HqPMgx4f7AP54iCDLYr7kFR"

# Consensus — validator sets define who validates each shard at each block height.
# This section must match across ALL nodes in the network.
# When adding a new validator, ALL existing nodes must update this config.
[consensus]
max_messages_per_block = 1000
shard_ids = [1, 2]   # Which data shards this node validates
num_shards = 2       # Total number of DATA shards (excludes shard 0)

# Validator set history — each entry activates at a specific block height.
# Public keys are Ed25519, hex-encoded.
validator_sets = [
    { effective_at = 0, shard_ids = [0,1,2], validator_public_keys = ["key1...", "key2...", "..."] },
    # ... additional entries as validators join/leave ...
    # Your key gets added in new entries with future block heights
]

[block_receiver]
enabled = true

[fnames]
start_from = 1326867

[mempool]
allow_unlimited_mempool_size = false

[onchain_events]
start_block_number = 146752045

[base_onchain_events]
start_block_number = 41156800
stop_block_number = 9223372036854775807

# Validators do NOT need replication enabled
[replication]
enable = false

# Bootstrap from snapshot on first start
[snapshot]
endpoint_url = "https://e1f9f185c6e63471dd39f96abd3413c4.r2.cloudflarestorage.com"
load_db_from_snapshot = true

---

Production Deployment (Kubernetes/GKE)

For production validators, we recommend Kubernetes for reliability. Here is Uno's architecture:

Infrastructure Overview

                    ┌─────────────────────────────────┐
                    │         Internet                 │
                    └──────┬──────────────┬────────────┘
                           │              │
                    ┌──────▼──────┐ ┌─────▼──────┐
                    │ TCP LB      │ │ UDP LB     │
                    │ (3381,3383) │ │ (3382)     │
                    └──────┬──────┘ └─────┬──────┘
                           │              │
                    ┌──────▼──────┐       │
                    │ Caddy Proxy │       │
                    │ (TLS term)  │       │
                    └──────┬──────┘       │
                           │              │
                    ┌──────▼──────────────▼──────┐
                    │       Snapchain Pod        │
                    │  ┌──────────────────────┐  │
                    │  │ farcasterxyz/snapchain│  │
                    │  │ :3381 :3382 :3383    │  │
                    │  └──────────┬───────────┘  │
                    │             │               │
                    │  ┌──────────▼───────────┐  │
                    │  │ 2TB PD (RocksDB)     │  │
                    │  └──────────────────────┘  │
                    └────────────────────────────┘

Key Decisions

• Dedicated node pool with taints (dedicated=snapchain:NoSchedule) to prevent other workloads from being scheduled on the same node
• Recreate deployment strategy (not rolling) — only one Snapchain instance can use the persistent disk at a time
• Caddy reverse proxy for TLS termination with Let's Encrypt certificates (HTTP API on 3381, gRPC via h2c on 3383)
• UDP LoadBalancer bypasses Caddy — gossip traffic (3382) goes directly to the Snapchain pod since Caddy doesn't proxy UDP
• Static IPs for both TCP and UDP load balancers to maintain stable gossip addresses
• DNS: snapchain.farcaster.xyz points to the TCP load balancer IP (your DNS, we use a different, non-public domain)

Monitoring CronJob

A CronJob runs every 2 minutes, scrapes /v1/info, and pushes blockDelay per shard to GCP Cloud Monitoring:

# Alert policy: blockDelay > 300s for 5 minutes → SMS + Slack notification
# Metric: custom.googleapis.com/snapchain/block_delay (GAUGE, DOUBLE, seconds)
# Labels: shard_id (0=metadata, 1-N=data shards)

Auto-Update

A GitHub Actions workflow runs daily at 6 PM UTC to check for new Snapchain releases. If a new version is found, it automatically updates the image tag in Terraform and opens a PR.

---

Networking and Ports

Port	Protocol	Purpose	Notes
3381	TCP	HTTP REST API	Query the node, health checks (/v1/info)
3382	UDP	Gossip (QUIC-v1)	P2P communication between nodes — must be publicly reachable
3383	TCP	gRPC RPC	Block sync, programmatic access

All three ports must be open and reachable from the internet for a validator. For a read node, inbound on 3382 is required for gossip peering.

Firewall Rules

# Example: open ports on a cloud VM
# GCP
gcloud compute firewall-rules create snapchain-ports \
  --allow tcp:3381,tcp:3383,udp:3382 \
  --target-tags snapchain

# AWS
aws ec2 authorize-security-group-ingress \
  --group-id sg-xxx \
  --ip-permissions \
    IpProtocol=tcp,FromPort=3381,ToPort=3381,IpRanges='[{CidrIp=0.0.0.0/0}]' \
    IpProtocol=tcp,FromPort=3383,ToPort=3383,IpRanges='[{CidrIp=0.0.0.0/0}]' \
    IpProtocol=udp,FromPort=3382,ToPort=3382,IpRanges='[{CidrIp=0.0.0.0/0}]'

---

Environment Variables and Secrets

Required for Validators

Variable	Purpose
SNAPCHAIN_CONSENSUS__PRIVATE_KEY	Ed25519 private key (hex) — your validator signing key
SNAPCHAIN_ONCHAIN_EVENTS__RPC_URL	Optimism L2 RPC URL (for registry event tracking)
SNAPCHAIN_BASE_ONCHAIN_EVENTS__RPC_URL	Base L2 RPC URL (for Base registry events)
SNAPCHAIN_L1_RPC_URL	Ethereum L1 RPC URL

Optional

Variable	Default	Purpose
RUST_LOG	warn	Log level — suppress noisy modules: warn,informalsystems_malachitebft_sync=error,snapchain::network::gossip=error
RUST_BACKTRACE	unset	Set to full for debugging

RPC Providers

You need RPC access to three chains:

1. Optimism Mainnet — for Farcaster's ID Registry, Key Registry, and Storage Registry contracts
2. Base — for Base-deployed registry events
3. Ethereum L1 — for L1 anchoring

Use a reliable provider (Alchemy, Infura, QuickNode, or self-hosted) with sufficient rate limits. A validator makes continuous RPC calls to track onchain events.

---

Operational Tips

Initial Sync

• Snapshot download is ~200 GB and takes 2–4 hours
• Shard 0 (metadata) syncs first and fastest — watch for its blockDelay to drop to single digits
• Shards 1 and 2 follow — total sync time depends on disk I/O
• Set load_db_from_snapshot = true for first start, can be left on for subsequent restarts

File Descriptors

Ensure your system allows at least 65,535 open file descriptors:

# Check current limit
ulimit -n

# Set in docker-compose (already done in official compose file)
# ulimits:
#   nofile:
#     soft: 65535
#     hard: 65535

# Or set system-wide in /etc/security/limits.conf
* soft nofile 65535
* hard nofile 65535

Disk Space

• RocksDB data grows over time as new blocks are produced
• Monitor disk usage — at ~200 GB currently, plan for 1–2 TB
• Use SSD for better sync and query performance
• Persistent disks with Retain reclaim policy prevent accidental data loss

Upgrading

• The official Docker image is farcasterxyz/snapchain:latest
• Check GitHub releases for changelogs
• For Docker: ./snapchain.sh upgrade
• For Kubernetes: update the image tag in your deployment manifest
• Upgrades are generally safe — the node catches up on missed blocks after restart

Validator Key Management

• Generate an Ed25519 keypair for your validator
• Never expose the private key — use Kubernetes secrets, AWS Secrets Manager, Vault, etc.
• The public key must be shared with all other node operators for inclusion in validator_sets
• If your key is compromised, coordinate an emergency validator set rotation

Relay Mode

Read nodes can serve as relay points for the network without participating in consensus. This is the default mode (read_node = true). Running a relay is valuable for:

• Reducing load on validators by serving API queries
• Providing geographic distribution of API endpoints
• Building applications that query Farcaster data directly

Common Issues

Issue	Solution
blockDelay stuck at high values	Check gossip connectivity (port 3382 UDP), verify bootstrap peers are reachable
Node not syncing after restart	Ensure load_db_from_snapshot = true and snapshot endpoint is accessible
Gossip peers not connecting	Verify announce_address matches your actual public IP and UDP port is open
High memory usage	Expected — RocksDB caches aggressively. 64 GB recommended for validators
gRPC connection failures	If behind a proxy, ensure h2c (HTTP/2 cleartext) is supported upstream

---

References

• Snapchain Documentation
• Snapchain Getting Started
• Snapchain GitHub Repository
• FIP: Snapchain - Protocol Discussion #207
• Farcaster Documentation
• Snapchain Migration Guide