Run your own
Farcaster client.

Quickstart

Clone it, then run three commands.

Everything below explains what each command does, what the protocol is doing underneath, and the ways it goes wrong — all of which we hit while building it.

git clone https://github.com/webthethird/snapstart && cd snapstart

./snapstart provision      # 0. furnish the compute
./snapstart node up        # 1. start a Snapchain read node
./snapstart client create  # 2. issue an app key and launch the client

Concepts

What you are actually building.

If you have run an Ethereum node, you already understand this. You can read chain data from Alchemy with an API key and a rate limit, or run Reth yourself and query localhost with nobody's permission. Farcaster has the same split: Neynar is Alchemy, a Snapchain read node is your own Reth.

You cannot run a validator — the validator set lives in a contract and you are not in it. That is fine. A read node stores full state and serves every read API, which is everything a client needs.

Three identities, not one

An app key is a session key. One account can have many — Warpcast holds one, your client holds another, and revoking one does not touch the rest. That is also why a cast can tell you which client posted it: the signature identifies the software, not just the person.

Command 0

Provision the compute.

./snapstart provision

Four API calls and a boot script: an SSH keypair dedicated to this node, a firewall, an instance, a disk — then cloud-init installs Docker. Nothing mystical.

One credential, and the node never sees it

The cloud API key belongs to the provisioning script. provision, status and destroy need it; node and client do not. Once running, the node holds no credentials of any kind.

Command 1

Start the read node.

./snapstart node up

Installs upstream's snapchain.sh, writes its config without prompting, and starts the node. It then restores from a snapshot — the slow part, and the part with teeth. See the timing window above.

Check readiness properly

./snapstart node ready

"The API responds" and "the database has data" are both true of a broken node. This verifies every shard is present and within 100 blocks of the tip.

  shard           height          delay          messages  state
  0             49007206              1                 0  ok
  1             49007206              1         458606290  ok
  2             48842741              1         455621742  ok

  ready: all shards present and within 100 blocks of the tip

Shard 0 holds no user messages — which is exactly why a message-count check would call a broken node healthy.

Command 2

Create the client.

./snapstart client create

Asks for your seed phrase, uses it once to authorize an app key, then forgets it. From that point the client holds only the app key.

Only paste a seed phrase into software whose source you have read, from people you have reason to trust. That includes this project. The code that touches the phrase is scripts/app-key.ts — about 140 lines, worth the three minutes.

What issuing an app key actually does

Registering a key used to need an Optimism transaction. Under FIP-272 it does not: you submit a KEY_ADD message authorized by an EIP-712 signature from your custody address. No gas, no transaction. Three signatures are involved:

• a SignedKeyRequest — the app saying "I asked for this key"
• a KeyAdd signature from your custody address, authorizing the key, its scopes and lifetime
• the envelope itself, signed by the new key — proof whoever submits it holds it

Writes are confirmed, not assumed

A node returns 200 once your message is well-formed and handed to the gossip layer — then discards what happens next. A node with no peers logs InsufficientPeers, drops your cast, and still returns 200. So the client never trusts the status code: it knows the message hash before submitting and polls until the node reports it back.

The interesting part

Filter the feed by the client that posted.

Every cast carries the Ed25519 key that signed it. That key's registration records the FID of the app that requested it, and that FID has a profile with a name:

cast.signer  →  the key's registration  →  requestFid  →  that app's name

Which means a feed can be filtered by the software that produced it:

feed: 60 casts from 23 authors

   45  warpcast
   13  fireflyapp
    1  greg
    1  unknown client

include ["warpcast"] -> 45
exclude ["warpcast"] -> 15

That is a real feed on a real node, not a mockup. Casts that genuinely cannot be attributed — keys registered before the metadata existed — render as unknown client and are never silently dropped: a filter that hides posts because a lookup failed is a bug that looks like a feature.

The same field, two encodings

requestFid is reported two different ways depending on how the key was registered, which is easy to miss because the obvious one works:

onchain   signer.onChainEvent.signerEventBody.metadata
          base64, ABI-encoded SignedKeyRequestMetadata, decode to get requestFid

gasless   signer.requestFid
          a plain top-level field. `metadata` is absent entirely.

We shipped the bug this creates: decoding only the blob sends every gasless key to unknown client, including the one your own client just issued itself. Nothing errors. The feature simply fails to recognise your own posts, which is exactly the case you are least likely to test. Check both.

Money

What it costs, and how to stop paying.

Both bill hourly. Run it for a day or two, then:

./snapstart destroy

It names what it is about to delete, verifies the resources are actually gone before discarding local state, and keeps that state if anything survived — so you can retry rather than being told you have stopped paying when you have not.

Troubleshooting

When it goes wrong.

Every entry here is something we hit. Most are not documented anywhere.

Failed to download .rocks.snapshot/shard-0/chunk_0001.bin: HTTP 404
thread 'main' panicked at src/main.rs:422

Honest limitations

Worth knowing before you spend a day on this.

• The restore took 13h 22m and 9h 09m on two runs, and interruption is worse than it sounds. A restart does not resume a shard whose snapshot download failed — it sees a non-empty .rocks, skips the snapshot, and starts syncing that shard from genesis, which takes weeks. You have to reload that shard deliberately. snapchain#1044.
• It needs 2 TB at peak for a database that settles around 557 GB, because snapshot staging is not reclaimed until the end. We proposed a fix.
• Writing through someone else's validator is not an option — they require authentication. Your own read node is the only keyless write path.
• This is a tutorial client, not a product. It reads a feed, posts, follows, reacts and filters by source. It is not trying to be Warpcast.

Giving back

Corrections we filed upstream.

Where the documentation disagreed with what we measured, we reported it rather than silently working around it.