A Farcaster bot (@builderbot) that automatically sends you notifications for all your Nouns Builder DAOs. Never miss important governance updates again!
@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.
- Follow @builderbot on Farcaster
- The bot automatically detects which DAOs you're a member of by checking your wallet addresses
- You'll receive direct cast notifications for:
- New proposals created in your DAOs
- Proposal updates (propdates)
- Voting period start/end notifications
The bot monitors DAOs across all supported Nouns Builder networks:
- Ethereum Mainnet
- Optimism
- Base
- Zora
- π’ 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
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
This repository contains the source code for the @builderbot Farcaster bot.
- Node.js 18+
- pnpm
- Warpcast API credentials
- Database (SQLite)
-
Clone the repository:
git clone https://github.com/BuilderOSS/builder-farcaster.git cd builder-farcaster
-
Install dependencies:
pnpm install
-
Set up environment variables:
cp .env.template .env
Then configure the following variables:
WARPCAST_AUTH_TOKEN
- Your Warpcast authentication tokenWARPCAST_API_KEY
- Your Warpcast API keyBUILDER_SUBGRAPH_*_URL
- Subgraph URLs for each chainDATABASE_URL
- SQLite database connection string
-
Initialize the database:
pnpm prisma:migrate pnpm prisma:generate
-
Build and run:
pnpm build pnpm dev
pnpm dev
- Run the bot in development mode (processes proposals and consumes queue)pnpm dev:process
- Process new proposals onlypnpm dev:consume
- Consume notification queue onlypnpm dev:propdates
- Process proposal updates onlypnpm dev:invites
- Process invitationspnpm dev:tokengen
- Generate Warpcast tokenpnpm build
- Build the projectpnpm test
- Run testspnpm lint
- Run lintingpnpm prisma:generate
- Generate Prisma clientpnpm prisma:migrate
- Deploy database migrations
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
The bot uses an automated deployment pipeline with GitHub Actions following Git Flow principles:
develop
- Main development branch for ongoing workmaster
- Production branch for stable releasesfeature/*
- Feature development branchesbugfix/*
- Bug fix branchesrelease/*
- Release preparation brancheshotfix/*
- Critical hotfix branches
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
Automatically creates pull requests for:
- Feature branches β
develop
- Bugfix branches β
develop
- Release branches β
master
- Hotfix branches β
master
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
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
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>
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
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.