🎮 Babylon

A multiplayer prediction market game with autonomous AI agents and continuous RL training

A real-time prediction market game with autonomous NPCs, perpetual futures, and gamified social mechanics.

NOTE: This is currently in development. We expect to launch publicly around December 1st, 2025. This repo will change heavily in the meantime.

📦 Installation

Requirements:

Node.js >= 18.0.0 (for Error cause support)
Bun >= 1.3.0

git clone https://github.com/BabylonSocial/babylon.git
cd babylon
bun install

# Setup environment & database
cp .env.example .env
bun run db:push

🚀 Quick Start

# 1. Install
bun install

# 2. Configure environment
cp .env.example .env
# (Optional) Create .env.local for Next.js-only overrides
# Edit .env (and optionally .env.local) with your Privy credentials + GROQ_API_KEY

# 3. Setup database
bun run db:push
bun run db:seed

# 4. (Optional) Enable Agent0 Integration
# Add to .env:
# AGENT0_ENABLED=true
# BASE_SEPOLIA_RPC_URL=...
# BABYLON_GAME_PRIVATE_KEY=...
# Then configure Agent0: babylon agent agent0-config

# 5. Start development
bun run dev   # ← Automatically starts web + game engine!

Visit http://localhost:3000 - everything runs and generates content automatically!

Development Modes

Default Mode (Recommended):

bun run dev   # ← Web + Game Engine (both automatically!)

Runs web server plus the local cron simulator. Content is generated via cron endpoints every 60 seconds.

Web Only (UI/API only, no local cron simulator):

bun run dev:web

Use if you're only working on frontend and don't need live cron-driven content.

Next.js Only (Run Next directly):

bun run dev:next-only

Useful if you want to bypass Turbo and run the Next dev flow directly.

Real-Time Updates

The application uses Server-Sent Events (SSE) for real-time updates (Vercel-compatible):

Feed updates (new posts)
Market price changes
Breaking news
Chat messages

For Production (Vercel): Optionally set up Redis for cross-instance broadcasting:

# Add to Vercel environment variables
UPSTASH_REDIS_REST_URL=https://your-redis-url.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token

🚀 Development

# Start dev server
bun run dev

# Build & test
bun run build
bun run typecheck
bun run lint
bun run test

Visit http://localhost:3000

🤖 AI Assistants (Ruler)

This repo uses Ruler to centralize AI coding instructions in .ruler/**.

# Install deps
bun install

# Generate local agent config files (gitignored)
bun run ruler:apply

Edit rules in .ruler/** only (generated files like AGENTS.md, CLAUDE.md, MCP configs should not be edited manually).
For OpenAI Codex CLI to pick up the project config/MCP, set CODEX_HOME="$(pwd)/.codex".

🧪 Testing

bun run test:unit           # Unit tests
bun run test:integration    # Integration tests
bun run test:e2e           # E2E tests
bun run contracts:test     # Smart contracts

🚢 Deploy to Vercel

npm i -g vercel
vercel deploy --prod

Required Environment Variables:

DATABASE_URL - PostgreSQL connection
NEXT_PUBLIC_PRIVY_APP_ID - Authentication
OPENAI_API_KEY - AI agents

See .env.example for complete list.

🖼️ NFT Deployment (ProtoMonkeys)

Deploy the ProtoMonkeys NFT collection for the Top 100 leaderboard rewards.

Local Development (Automatic)

NFT minting works automatically with bun run dev! The dev startup:

Deploys ProtoMonkeysNFT contract to local Hardhat
Seeds the NFT collection (100 NFTs with placeholder metadata)
Creates eligibility snapshots for all test users

bun run dev   # ← NFT minting ready out of the box!

Visit http://localhost:3000/nft to mint your NFT.

Manual Local Setup (if needed)

# 1. Start local Hardhat node
cd packages/contracts
bun hardhat:node

# 2. Deploy NFT contract (new terminal)
NFT_SIGNER_ADDRESS=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 \
NFT_BASE_URI=http://localhost:3000/api/nft/metadata/ \
forge script script/DeployProtoMonkeysNFT.s.sol:DeployProtoMonkeysNFTLocal \
  --rpc-url http://localhost:8545 --broadcast

# 3. Set the deployed address in .env
NFT_CONTRACT_ADDRESS=<deployed_address>
NFT_CHAIN_ID=31337
NFT_SIGNER_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

# 4. Seed NFT collection and snapshots
bun run scripts/seed-nft-collection.ts
bun run scripts/seed-nft-snapshot-local.ts

Environment Variables (Production)

# NFT Contract Configuration
NFT_CONTRACT_ADDRESS=0x...          # Set after deployment
NFT_CHAIN_ID=1                      # 1 = Mainnet, 11155111 = Sepolia, 31337 = Local
NFT_SIGNER_PRIVATE_KEY=0x...        # Backend signer private key (NEVER COMMIT)
NFT_SIGNER_ADDRESS=0x...            # Public address of signer
NFT_BASE_URI=https://babylon.market/api/nft/metadata/

Generate a signer keypair for production:

cast wallet new  # Save the private key securely!

Sepolia Testnet

cd packages/contracts

# Deploy to Sepolia
forge script script/DeployProtoMonkeysNFT.s.sol:DeployProtoMonkeysNFT \
  --rpc-url https://rpc.sepolia.org \
  --broadcast --verify

# Update environment
NFT_CONTRACT_ADDRESS=<deployed_address>
NFT_CHAIN_ID=11155111

Ethereum Mainnet

cd packages/contracts

# Deploy to mainnet (requires ETH for gas)
forge script script/DeployProtoMonkeysNFT.s.sol:DeployProtoMonkeysNFT \
  --rpc-url https://eth.llamarpc.com \
  --broadcast --verify

# Update environment
NFT_CONTRACT_ADDRESS=<deployed_address>
NFT_CHAIN_ID=1

Post-Deployment Setup

# 1. Seed NFT collection with metadata (100 NFTs)
bun run scripts/seed-nft-collection.ts

# 2. Create eligibility snapshot from leaderboard (top 100 users)
# This populates the nftSnapshot table for mint eligibility

Contract Tests

cd packages/contracts
forge test --match-contract ProtoMonkeysNFT -vvv

Architecture

Component	Description
`ProtoMonkeysNFT.sol`	ERC-721 contract with ECDSA signature-gated minting
`/api/nft/eligibility`	Check if user is in top 100 snapshot
`/api/nft/mint/prepare`	Generate signed mint transaction
`/api/nft/mint/confirm`	Verify on-chain mint, update database
`/api/nft/metadata/[tokenId]`	ERC-721 metadata endpoint

See docs/nft-drop-implementation-plan.md for complete technical details.

📚 Documentation

📖 Full Documentation →

Smart Contracts: bun run deploy:local|testnet
RL Training: See packages/training/README.md
Game Control: babylon game start|pause|status (via CLI)

📱 Farcaster Mini App Setup

Babylon is configured as a Farcaster Mini App with automatic authentication. Users opening your app from any Farcaster client (e.g., Warpcast) are logged in automatically!

Prerequisites

Privy account with Farcaster enabled
Production deployment at https://babylon.market

Configuration Steps

1. Configure Privy Dashboard (10 min)

Visit https://dashboard.privy.io/ and configure:

Enable Farcaster:

Navigate to: User management → Authentication → Socials
Enable Farcaster

⚠️ CRITICAL: Add Allowed Domains:

Navigate to: Configuration → App settings → Domains
Add these domains:
- ✅ https://babylon.market (your production domain)
- ⚠️ https://farcaster.xyz ← REQUIRED for Mini Apps!
- ✅ http://localhost:3000 (for development)

Why https://farcaster.xyz? Required for iframe-in-iframe support that Farcaster Mini Apps use.

Set Callback URL:

Add: https://babylon.market/api/auth/farcaster/callback

2. Verify Environment Variables

Ensure these are set in production:

NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id
PRIVY_APP_SECRET=your_privy_app_secret

3. Deploy

vercel --prod

4. Test in Farcaster

Create a cast in a Farcaster client (e.g., Warpcast):

Check out Babylon! 🏛️

https://babylon.market

Click to launch → Users are automatically logged in! ✨

How It Works

Mini App SDK detects Farcaster context
Auto-login triggers via Privy + @farcaster/miniapp-sdk
User approves once
Instant authentication - no forms or passwords!

Using Mini App Context in Code

import { useFarcasterMiniApp } from '@/components/providers/FarcasterFrameProvider'

function MyComponent() {
  const { isMiniApp, fid, username } = useFarcasterMiniApp()

  if (isMiniApp) {
    return <div>Welcome from Farcaster, {username}!</div>
  }

  return <div>Welcome to Babylon!</div>
}

Key Resources

Farcaster Mini Apps: https://miniapps.farcaster.xyz/
Privy Recipe: https://docs.privy.io/recipes/farcaster/mini-apps
Mini Apps SDK: https://github.com/farcaster/miniapp-sdk

Name		Name	Last commit message	Last commit date
Latest commit History 3,028 Commits
.github		.github
.husky		.husky
.ruler		.ruler
apps		apps
docs		docs
packages		packages
scripts		scripts
.actrc		.actrc
.env.example		.env.example
.gitignore		.gitignore
.secrets.local.template		.secrets.local.template
README.md		README.md
biome.json		biome.json
bun.lock		bun.lock
components.json		components.json
docker-compose.yml		docker-compose.yml
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation

🎮 Babylon

📦 Installation

🚀 Quick Start

Development Modes

Real-Time Updates

🚀 Development

🤖 AI Assistants (Ruler)

🧪 Testing

🚢 Deploy to Vercel

🖼️ NFT Deployment (ProtoMonkeys)

Local Development (Automatic)

Manual Local Setup (if needed)

Environment Variables (Production)

Sepolia Testnet

Ethereum Mainnet

Post-Deployment Setup

Contract Tests

Architecture

📚 Documentation

📱 Farcaster Mini App Setup

Prerequisites

Configuration Steps

1. Configure Privy Dashboard (10 min)

2. Verify Environment Variables

3. Deploy

4. Test in Farcaster

How It Works

Using Mini App Context in Code

Key Resources

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages