Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Getting Started

Requirements

  • 16 GB of RAM
  • 4 CPU cores or vCPUs
  • 2 TB of free storage
  • A public IP address with ports 3381 - 3383 exposed

Sync a node

The easiest way to run Snapchain is with the install script, which runs the node under Docker and installs Docker for you if it is missing:

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

The script installs everything into ~/snapchain, whichever directory you run it from. It asks you to confirm that you will not receive rewards for running a node and for your FID, then starts the node and follows its logs. See Manage a node with snapchain.sh for what each step does and how to start, stop and upgrade the node later.

Check the logs to make sure the snapshot is downloading:

./snapchain.sh logs
 
2025-04-16T02:40:11.265909Z  INFO snapchain: Downloading snapshots
2025-04-16T02:40:11.266021Z  INFO snapchain::storage::db::snapshot: Retrieving metadata from https://pub-d352dd8819104a778e20d08888c5a661.r2.dev/FARCASTER_NETWORK_MAINNET/1/latest.json
2025-04-16T02:40:11.637368Z  INFO snapchain::storage::db::snapshot: Downloading zipped snapshot chunk chunk_0001.bin
2025-04-16T02:40:12.952768Z  INFO snapchain::storage::db::snapshot: Downloading zipped snapshot chunk chunk_0002.bin
2025-04-16T02:40:15.305951Z  INFO snapchain::storage::db::snapshot: Downloading zipped snapshot chunk chunk_0003.bin
2025-04-16T02:40:17.742041Z  INFO snapchain::storage::db::snapshot: Downloading zipped snapshot chunk chunk_0004.bin
2025-04-16T02:40:20.720477Z  INFO snapchain::storage::db::snapshot: Downloading zipped snapshot chunk chunk_0005.bin
....

The snapshot is several hundred gigabytes and can take a few hours to download and decompress. Once it is done, you should see logs like this:

2025-04-16T08:20:01.749980Z  INFO node{name=Block}:sync{height.tip=[0] 1875918 height.sync=[0] 1875919}: informalsystems_malachitebft_sync::handle: Requesting sync value from peer height.sync=[0] 1875920 peer=12D3KooWCc28TYrrXFivwUshyZ8R5HqPMgx4f7AP54iCDLYr7kFR
2025-04-16T08:20:01.752425Z  INFO Actor{id="0.7"}: snapchain::consensus::read_validator: Processed decided block height=[0] 1875920 hash="d7a6e107fed6e1e90d4888f4aa2bfb922d9e6950d83c621db0500b15e1caccfe"

The node then syncs the blocks produced since the snapshot was taken. Check its progress with:

curl -s localhost:3381/v1/info | jq
{
  "dbStats": {
    "numMessages": 914092103,
    "numFidRegistrations": 3354008,
    "approxSize": 548529692074
  },
  "numShards": 2,
  "shardInfos": [
    {
      "shardId": 0,
      "maxHeight": 47583086,
      "numMessages": 12661169,
      "numFidRegistrations": 0,
      "approxSize": 38012136899,
      "blockDelay": 1,
      "mempoolSize": 0
    },
    {
      "shardId": 2,
      "maxHeight": 48091473,
      "numMessages": 455556375,
      "numFidRegistrations": 1676871,
      "approxSize": 273017268128,
      "blockDelay": 0,
      "mempoolSize": 4294967295
    },
    {
      "shardId": 1,
      "maxHeight": 48256318,
      "numMessages": 458535728,
      "numFidRegistrations": 1677137,
      "approxSize": 275512423946,
      "blockDelay": 0,
      "mempoolSize": 4294967295
    }
  ],
  "version": "0.14.2",
  "peer_id": "12D3KooWCjFRfnj2yrWyADcW3adS45YigbUPwEyGZ6fB9rbxDW2T",
  "nextEngineVersionTimestamp": 0
}

blockDelay is how many seconds each shard's newest block is behind the current time. While the node catches up it counts down; once every shard is in the single digits, the node is in sync. maxHeight differs between shards because each shard is its own chain. On a read node mempoolSize reads 4294967295 for shards 1 and 2, which means "not reported" (see Validators vs. read nodes).

Query a node

Once the node is in sync you can start querying it for the latest messages from a user. You'll need the user's account id to get their messages. If you don't have this handy, you can do a lookup by username from the public Farcaster name server.

# Query for the id associated with the @farcaster account
curl https://fnames.farcaster.xyz/transfers?name=farcaster
 
{
  "transfers": [
    {
      "id": 1,
      "timestamp": 1628882891,
      "username": "farcaster",
      "owner": "0x877...06ed",
      "from": 0,
      "to": 1,
      "user_signature": "0xa6fdd...471b",
      "server_signature": "0xb718...c41b"
    }
  ]
}

The @farcaster user's account id is 1, and so you can fetch the latest messages by querying the node over its HTTP API:

curl http://localhost:3381/v1/castsByFid\?fid\=1 \
 | jq ".messages[].data.castAddBody.text \
 | select( . != null)"

Next steps