What Farcaster sync actually means
When you hear "sync" in the context of Farcaster, it’s easy to assume we’re talking about cross-posting tools that duplicate your posts across multiple social apps. That is user-facing sync. This guide is about infrastructure sync: the backbone that keeps the network running.
Farcaster is a public social network built on Ethereum, but its reliability doesn’t come from the blockchain alone. It comes from Hubs. These are independent nodes that store and replicate messages—casts, reactions, and follows—across the network. If one Hub goes down, the others continue to sync, ensuring the data remains available.
Think of Hubs like a distributed library system. Each Hub holds a full copy of the social graph. When you post a cast, it lands on a Hub. That Hub then syncs with others, spreading the message until everyone has it. This replication process is what makes Farcaster resilient and decentralized.
Setting up your own Hub means you become part of this replication chain. You’re not just storing data; you’re helping verify and propagate it. This is the real "sync" that powers the network’s uptime and integrity. Without these nodes, Farcaster would be just another centralized app. With them, it’s a resilient public utility.
Install and configure Hubble
Hubble is the reference implementation for a Farcaster hub. It runs locally or on a cloud server to store casts, reactions, and user data. Because the network relies on these hubs to sync state, a misconfigured instance can miss blocks or fail to replicate data correctly. You need to set up the environment, configure the storage engine, and launch the process.
Start by installing Node.js (v18 or later) and Docker. Clone the official farcaster-hubble repository from GitHub. Run npm install in the root directory to install the necessary packages. This ensures you have the correct binaries and dependencies for your operating system.
Create a .env file in the project root. You must define the DATA_DIR to point to a persistent storage volume. Set NETWORK to mainnet or testnet depending on your needs. Configure IPFS settings if you plan to use IPFS for message storage, though standard file storage is recommended for most users. Ensure your GAS_STATION_API_KEY is set if you are running on mainnet to handle gas fees for on-chain registrations.
Run npm run init to generate the initial configuration files and database schema. This step creates the RocksDB or LevelDB instance required for high-performance message storage. Verify that the DATA_DIR has write permissions. If you are using Docker, ensure the volume mount is correctly mapped to your host machine to prevent data loss on restart.
Start the hub with npm run start. The process will begin syncing from the genesis block. This can take several hours depending on your hardware and internet connection. Monitor the logs for sync messages. Check the sync percentage against other known hubs to ensure you are catching up. Once the sync percentage reaches 100%, your hub is fully operational and ready to serve requests.
As an Amazon Associate, we may earn from qualifying purchases.
Verify hub synchronization status
Your hub is online, but it might not be ready to serve the network yet. Being online doesn't mean it has fully synchronized with the rest of the Farcaster ecosystem. You need to compare your hub's state against the network to see the actual sync percentage.
Think of this like checking a library's catalog. The building is open (online), but the books (data) might still be on the trucks. If you try to serve data before the sync is complete, you'll give users incomplete or stale information.
Run the following command to check your hub's current status:
npx @farcaster/hub-cli hub status
Look for the syncPercentage field in the output. A healthy, fully synced hub should show a percentage close to 100%. If it's stuck at a lower number, your hub is still catching up. This process can take some time, depending on the network size and your connection speed.
If the sync percentage isn't increasing, check your network connectivity and ensure your hub is properly connected to other peers. You can also view the list of connected peers to confirm you're talking to the right nodes.
Build frames for monetization
Interactive frames let you embed actions directly into Farcaster posts. Instead of linking out to a website, users can mint, vote, or tip without leaving the app. This frictionless experience drives higher engagement and opens clear revenue paths.
To start, define the frame’s purpose. Will it sell a digital collectible, run a paid poll, or offer a premium subscription? Your choice dictates the technical setup. For most creators, a simple minting frame offers the lowest barrier to entry and the fastest path to revenue.
Set up the frame server
Your frame needs a server to handle requests. Use a framework like Next.js or Express to create an API endpoint. This endpoint must respond to Farcaster’s frame specification with valid HTML containing specific meta tags. These tags tell the client how to render the frame and what actions are available.
Ensure your server is publicly accessible via HTTPS. Farcaster hubs and clients require secure connections to verify the frame’s integrity. Test your endpoint using a frame validator to catch syntax errors before deployment.
Define interactive actions
Actions are the buttons inside your frame. Each button can trigger a different outcome. For monetization, use post actions for simple interactions or mint actions for selling assets. When a user clicks a button, the client sends a signed message to your server.
Your server must verify this signature. This step is critical. Without verification, anyone can fake a transaction. Once verified, process the payment or update the user’s state. Return the updated frame HTML so the user sees the result immediately.
Integrate payment rails
To collect money, connect a payment processor. Options include Stripe for fiat currency or on-chain wallets for crypto payments. If you’re selling digital goods, consider integrating with a minting service like Zora or Manifold. These services handle the blockchain complexity, letting you focus on the user experience.
Display the price clearly in the frame’s metadata. Users should know the cost before they click. Ambiguity kills conversion rates. Make the transaction path obvious and the confirmation instant.
Test and launch
Before going live, test every action thoroughly. Simulate user clicks, check signature verification, and verify payment processing. Use a testnet or sandbox environment if available. Once confident, deploy your frame to production.
Share your frame in relevant Farcaster channels. Engage with early users to gather feedback. Iterate on the design and functionality based on real usage data. A well-tested frame builds trust and encourages repeat interactions.
Common sync errors and fixes
Even after configuring your hub, the connection between your node and the Farcaster network can falter. When sync issues arise, they typically manifest as lag, dropped connections, or data inconsistency. Here is how to identify and resolve the most frequent problems.
Hub appears online but isn’t syncing
A hub showing as "online" does not guarantee it has fully synchronized with the network. The status might indicate the process is running, but the data could be hours behind.
Check the actual sync percentage by querying the hub against the network. If the percentage is low or stuck, the hub may be missing recent casts or messages. Restarting the service often clears temporary state issues.
Connection drops and timeouts
Frequent disconnections usually stem from network instability or resource limits. If your hub drops packets, it will fail to receive new events from other hubs.
Ensure your firewall allows inbound connections on the designated port. Also, monitor system resources; if your server runs out of RAM or CPU, the hub will pause operations to prevent crashes.
Data inconsistency and missing casts
If you notice missing casts or incorrect user data, the local database might be corrupted or partially synced. This often happens after an unexpected shutdown.
Run a verification check against the official Farcaster protocol documentation. If discrepancies persist, consider rebuilding the local database from the latest snapshot to ensure data integrity.
Frequently asked: what to check next
How do I find my Farcaster FID?
Your Farcaster ID (FID) is the unique numerical identifier for your account, distinct from your username. If you are running your own hub infrastructure, you can locate it by querying the fnames table in your replicator database using a SQL statement like SELECT username, fid FROM fnames WHERE username = 'your_username'. For standard users, your FID is typically visible in your profile settings or via developer APIs.
Can I send private messages on Farcaster?
Yes. Beyond public casting and replying, Farcaster supports direct messaging. You can send private messages to friends or specific users by searching for their username in the client. This allows for encrypted, one-to-one conversations separate from the public feed.
How does "Sign in with Farcaster" work?
This protocol lets websites verify your identity without passwords. The process involves three steps: the user clicks a "Sign in with Farcaster" button, scans a QR code or approves the request in their wallet app, and the site receives a cryptographic signature to verify the login. This method is secure and decentralized, relying on your existing Farcaster account rather than third-party logins.
How do I create a new channel?
Anyone can create a channel by paying a small fee in the client and choosing a name. The channel name must be under 16 characters and can only contain lowercase letters and numbers. The creator becomes the "host" and can invite co-hosts to help manage the community. Channels are public by default and serve as dedicated spaces for specific topics.
No comments yet. Be the first to share your thoughts!