Set up the replicator node

To build onchain growth tools, you first need a local copy of the Farcaster social graph. The Snapchain replicator is the engine that does this, syncing state from the Farcaster network into a local PostgreSQL database. This setup gives you direct, low-latency access to casts, links, and user data without relying on third-party hubs.

The process involves cloning the repository, configuring your environment variables, and launching the sync process. We will walk through the exact steps to get this running on your local machine.

1
Clone the Snapchain repository

Start by fetching the official Snapchain codebase. This repository contains the core logic for ingesting Farcaster messages and managing the local database schema. Clone the repo to your preferred development directory using git. This gives you the baseline binaries and configuration files needed for the next steps.

2
Install dependencies and build

Once cloned, install the necessary Rust dependencies and compile the binary. Snapchain is built on Rust, so ensure your toolchain is up to date. Run the build command to generate the executable. This step can take a few minutes depending on your machine’s specs, but it ensures you are running the latest stable version of the replicator.

3
Configure PostgreSQL and environment variables

The replicator requires a PostgreSQL database to store the sync state. Create a new database and user with appropriate permissions. Next, create a .env file in the root directory. You will need to set the DATABASE_URL to point to your local Postgres instance. If you are syncing from a specific hub or network, configure the RPC_URL or HUB_ENDPOINT accordingly. This configuration file is the control panel for your node.

4
Run the replicator and verify sync

Launch the replicator binary with your configuration. The tool will begin connecting to Farcaster hubs and downloading the delta graph. The delta graph represents incremental changes to the social graph, making the sync process efficient. Monitor the logs to confirm that messages are being ingested. Once the initial backlog is cleared, your local database will reflect the current state of Farcaster.

Configure hub sync peers

Connecting your local hub to the broader Farcaster network requires configuring sync peers. This step ensures your instance stays in sync with the rest of the network, maintaining data consistency and redundancy. Without proper peer configuration, your hub will operate in isolation, missing updates and failing to propagate your messages.

Farcaster uses a delta-based sync model. Instead of transferring entire message histories, hubs exchange only the changes (deltas). This approach is efficient for high-throughput social data but relies on a robust mesh of peers to function correctly.

Follow these steps to configure your sync peers:

1
Identify trusted public peers

Start by selecting well-known, public hubs. These peers are typically maintained by reputable organizations or developers and offer stable connections. Examples include hubs operated by major clients or infrastructure providers. Check the official Farcaster documentation or community resources for a list of recommended peers.

2
Update your hub configuration

Open your hub’s configuration file (usually hubble.conf or similar, depending on your deployment). Locate the peers or sync_peers section. Add the IP addresses or hostnames of your selected peers. Ensure the format matches your hub’s requirements, typically a list of strings.

3
Restart the hub service

Apply the changes by restarting your hub service. This forces the hub to establish new connections to the specified peers. Monitor the startup logs to confirm that the sync process begins and connections are established successfully.

4
Verify sync status

Check your hub’s logs or status endpoint to verify that it is actively syncing. Look for messages indicating that it has received blocks or messages from peers. A healthy sync rate indicates that your peer configuration is working correctly.

Index casts and reactions for monetization

Syncing data is only the first step. The real value emerges when you query that data to find who is actually listening. By indexing casts and reactions, you can identify high-engagement content and users, turning social signals into a targeted monetization strategy.

1. Define your engagement metrics

Not all attention is equal. A cast with 100 views and zero reactions is less valuable than one with 20 views and 15 recasts. Start by defining the metrics that matter for your specific monetization goal. Are you looking for brand awareness (views) or community trust (recasts and likes)?

Query your synced database for casts that exceed a threshold of interaction relative to their audience size. This helps you filter out noise and focus on content that resonates deeply with a niche.

2. Identify power users and influencers

Once you have your engagement metrics, look at the users driving them. Who are the top 1% of recasters and likers? These users often act as amplifiers in the Farcaster network. Their endorsements carry more weight than standard promotional posts.

Create a list of these high-value users. Note their interests, typical posting times, and the types of content they engage with most. This profile will serve as your target audience for paid integrations or sponsored content.

3. Match content to monetization opportunities

With your high-engagement content and power users identified, you can now match them. If a specific cast about onchain identity is performing well, and your power users are heavily interested in identity protocols, that is a prime opportunity for sponsorship.

Reach out to the creators of that content or the brands associated with those topics. Use the engagement data as proof of concept. Show them the specific metrics of their audience’s interest to justify premium rates.

4. Monitor and adjust

Engagement trends shift quickly. What works today might not work next month. Set up regular queries to track changes in your key metrics. Are certain types of reactions declining? Are new influencers rising?

Adjust your monetization strategy based on these shifts. If reaction-based engagement is dropping, consider focusing more on cast volume or cross-platform activity. Keep your data fresh to stay relevant.

Avoid common sync pitfalls

Sync errors are the most common reason onchain growth infrastructure fails. If your hub is out of step with the network, your data is wrong, and your users see nothing. You can fix most issues by checking three things: peer connectivity, replication health, and sync state.

Check peer connectivity

Farcaster hubs sync by exchanging messages with other hubs. If your hub cannot reach its peers, it stops receiving new data. This often happens when firewalls block ports or DNS fails.

Run npx w2 sync to see your connected peers. If the list is empty or stale, check your network configuration. Ensure port 2281 is open and reachable. A single broken peer can slow down sync, but a total disconnect stops it completely.

Verify replication slots

Your hub stores data in a Postgres database. Postgres uses replication slots to track which messages have been sent to other hubs. If a slot is not maintained, it can grow indefinitely and fill your disk.

Check your replication slots with:

SQL
SELECT slot_name, active FROM pg_replication_slots;

If a slot is inactive for a long time, drop it to free up space. Also, monitor your disk usage. If your hub runs out of disk, it will stop syncing. Set up alerts for disk usage above 80%.

Monitor sync state

Even with good peers and healthy slots, your hub might fall behind. This happens if your hub is too slow to process incoming messages or if you have too many peers.

Check your sync status with:

Shell
npx w2 status

Look at the synced field. If it is false, your hub is not fully synced. Check the lag field to see how far behind you are. If the lag is growing, you might need to add more peers or optimize your database queries.

Fixing these issues keeps your data accurate and your onchain growth efforts on track. Regular monitoring prevents small problems from becoming big ones.

Verify data consistency

Before you launch any monetization campaign, you need to know your local database actually matches the official Farcaster protocol. If your sync is lagging or corrupted, your analytics will lie, and your users will lose trust.

The Farcaster protocol uses a delta-based sync model. Hubs don’t just copy everything; they compare and copy only the changes (deltas) from their peers. This means your local node is constantly catching up. You need to verify that these catches-up are complete and accurate.

Run a full re-sync

Don’t trust your incremental syncs blindly. Every few weeks, force a full re-sync against a trusted primary hub. This clears out any stale state or corrupted frames that might have slipped through during a network hiccup.

Check frame parity

Compare the total count of casts, reactions, and profiles in your database against a well-known, highly trusted hub (like Neynar or Warpcast’s primary backend). If your numbers are off by more than a small margin, you have a sync gap. Investigate the fid ranges where the discrepancy starts.

Audit message validity

Run a script to validate the cryptographic signatures of your most recent 1,000 messages. Farcaster messages are signed by the user’s key. If a signature fails, that message is invalid and should be pruned. Keeping invalid messages can lead to incorrect user counts and broken social graphs.

Verify hub health

Check the health endpoint of your hub. It should report that your sync is current. If the hub reports it’s behind, check your network connectivity to your peers. A healthy hub syncs continuously, not in bursts.

  • Run a full re-sync against a trusted primary hub
  • Compare frame counts with a major hub like Warpcast
  • Validate cryptographic signatures of recent messages
  • Check hub health endpoint for sync lag

Farcaster sync infrastructure FAQ

Building a Farcaster hub involves specific technical hurdles around data integrity and network overhead. These answers address the most common friction points for builders setting up sync infrastructure.