Builder Farcaster Bot

A Farcaster bot (@builderbot) that automatically sends you notifications for all your Nouns Builder DAOs. Never miss important governance updates again!

🤖 What is @builderbot?

@builderbot is a Farcaster bot that automatically monitors all Nouns Builder DAOs across multiple chains and sends you personalized notifications for the DAOs you're involved with.

🚀 How it works

1. Follow @builderbot on Farcaster
2. The bot automatically detects which DAOs you're a member of by checking your wallet addresses
3. You'll receive direct cast notifications for:
   • New proposals created in your DAOs
   • Proposal updates (propdates)
   • Voting period start/end notifications

🌐 Multi-chain Support

The bot monitors DAOs across all supported Nouns Builder networks:

• Ethereum Mainnet
• Optimism
• Base
• Zora

📬 Notification Types

• 📢 New Proposals: Get notified when new proposals are created in your DAOs
• 📝 Proposal Updates: Stay updated on proposal modifications and updates
• 🗳️ Voting Alerts: Know when voting starts and ends for active proposals

🏗️ About Nouns Builder

Nouns Builder is a protocol for creating and managing Nouns-style DAOs. It enables communities to:

• Create custom NFT collections with automatic auctions
• Govern treasuries through on-chain voting
• Build sustainable communities with continuous funding

For more information, visit:

• 🌐 Nouns Builder App
• 📚 Documentation
• 💬 Discord
• 🟣 Farcaster Channel

🛠️ Developer Setup

This repository contains the source code for the @builderbot Farcaster bot.

Prerequisites

• Node.js 18+
• pnpm
• Warpcast API credentials
• Database (SQLite)

Installation

1. Clone the repository:

   git clone https://github.com/BuilderOSS/builder-farcaster.git
   cd builder-farcaster

2. Install dependencies:

   pnpm install

3. Set up environment variables:

   cp .env.template .env

   Then configure the following variables:

   • WARPCAST_AUTH_TOKEN - Your Warpcast authentication token
   • WARPCAST_API_KEY - Your Warpcast API key
   • BUILDER_SUBGRAPH_*_URL - Subgraph URLs for each chain
   • DATABASE_URL - SQLite database connection string

4. Initialize the database:

   pnpm prisma:migrate
   pnpm prisma:generate

5. Build and run:

   pnpm build
   pnpm dev

Available Commands

• pnpm dev - Run the bot in development mode (processes proposals and consumes queue)
• pnpm dev:process - Process new proposals only
• pnpm dev:consume - Consume notification queue only
• pnpm dev:propdates - Process proposal updates only
• pnpm dev:invites - Process invitations
• pnpm dev:tokengen - Generate Warpcast token
• pnpm build - Build the project
• pnpm test - Run tests
• pnpm lint - Run linting
• pnpm prisma:generate - Generate Prisma client
• pnpm prisma:migrate - Deploy database migrations

Architecture

The bot is built with:

• CLI Interface: Commander.js for command-line operations
• Queue System: SQLite-based task queue with retry logic
• Multi-chain Integration: GraphQL queries to Builder subgraphs
• Farcaster Integration: Warpcast API for sending direct casts
• Database: Prisma ORM with SQLite

🚀 Deployment

The bot uses an automated deployment pipeline with GitHub Actions following Git Flow principles:

Branching Strategy

• develop - Main development branch for ongoing work
• master - Production branch for stable releases
• feature/* - Feature development branches
• bugfix/* - Bug fix branches
• release/* - Release preparation branches
• hotfix/* - Critical hotfix branches

Automated Workflows

1. Build Pipeline (.github/workflows/build.yml)

Runs on all pushes and pull requests:

• Build & Test: Compiles the application and runs tests
• Auto Release: Creates draft releases when changes are pushed to master
• Generates changelogs using git-cliff
• Creates GitHub releases with semantic versioning

2. Git Flow (.github/workflows/git-flow.yml)

Automatically creates pull requests for:

• Feature branches → develop
• Bugfix branches → develop
• Release branches → master
• Hotfix branches → master

3. Deployment (.github/workflows/deploy.yml)

Triggers when a GitHub release is published:

• Environment Setup: Creates .env file with production variables
• Build: Compiles the application for production
• Deploy: Uses SSH and rsync to deploy to remote server
• Database Migration: Runs Prisma migrations on the server
• Cron Jobs: Sets up automated tasks:
  • Process proposals: Every hour
  • Process propdates: Every hour
  • Consume queue: Every minute

Production Environment

The bot runs on a remote server with:

• Automated Processing: Cron jobs handle proposal processing and queue consumption
• Log Management: Separate logs for each process (process_proposals.log, process_propdates.log, consume_queues.log)
• Database Persistence: SQLite database survives deployments
• Zero-downtime Deployment: Atomic symlink updates

Environment Variables

Production deployment requires these environment variables:

# Application
NODE_ENV=production
DATABASE_URL=file:./prod.db

# Nouns Builder Subgraphs
BUILDER_SUBGRAPH_ETHEREUM_URL=<ethereum_subgraph_url>
BUILDER_SUBGRAPH_BASE_URL=<base_subgraph_url>
BUILDER_SUBGRAPH_OPTIMISM_URL=<optimism_subgraph_url>
BUILDER_SUBGRAPH_ZORA_URL=<zora_subgraph_url>

# Warpcast API
WARPCAST_BASE_URL=https://api.warpcast.com
WARPCAST_API_KEY=<your_api_key>
WARPCAST_AUTH_TOKEN=<your_auth_token>

# Deployment (GitHub variables)
REMOTE_HOST_NAME=<server_ip>
REMOTE_HOST_USER=<deploy_user>
REMOTE_HOST_PATH=<deployment_path>
REMOTE_HOST_NODE=<node_path>
REMOTE_HOST_PNPM=<pnpm_path>

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

⚠️ Disclaimer

Warning

This project is currently in an experimental phase and is subject to significant changes as it progresses. As we continue development, expect frequent changes and improvements, which may lead to breaking changes in some features. We appreciate your patience and feedback while we work on building a better and more stable version of this toolset.