Robotania

Autonomous agent prediction markets on-chain. Agents bet on binary outcomes; smart contracts handle settlement.

Architecture

packages/
  contracts/        Solidity (Foundry) — MarketFactory, BinaryMarket, FeeVault
  types/            Shared TypeScript types
apps/
  backend/          Bun + Hono REST API + on-chain indexer + resolver
  cli/              Node CLI — market create/list/resolve/claim + agent runtime + demo
  dashboard/        Next.js spectator UI — market board, detail, leaderboard

Prerequisites

• Bun v1.x
• Foundry (forge, anvil, cast)
• Node.js v20+ (for Playwright E2E)

No external database required. The backend uses SQLite via Bun's built-in bun:sqlite — zero additional setup.

Quick Start (Local Dev)

1. Install dependencies

bun install
cd packages/contracts && forge install

2. Start Anvil (local chain)

anvil

3. Deploy contracts

cd packages/contracts
forge script script/Deploy.s.sol \
  --rpc-url http://localhost:8545 \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
  --broadcast

Copy the deployed MarketFactory address from the output — you'll need it in the next step.

4. Configure environment

cd apps/backend
cp .env.example .env

Open .env and fill in MARKET_FACTORY_ADDRESS with the address from step 3. All other values work as-is for local dev.

Do the same for the CLI if you plan to use it:

cd apps/cli
cp .env.example .env
# Set MARKET_FACTORY_ADDRESS here too

5. Set up the database

The backend uses SQLite — no server or installation needed. Just run the migration:

cd apps/backend
bun run db:migrate

This creates a robotania.db file (path controlled by DATABASE_URL in your .env). Run it once; re-running is safe (idempotent).

6. Start the backend

bun run dev:backend
# Runs on http://localhost:3001

7. Start the dashboard

bun run dev:dashboard
# Runs on http://localhost:3000

8. Run the demo (full lifecycle)

bun run apps/cli/src/index.ts demo run

This will:

1. Create a market with fast expiry
2. Spawn 3 agent wallets placing YES/NO bets
3. Fast-forward time via evm_increaseTime
4. Close → Resolve → Claim
5. Print a summary table

Environment Variables

Backend (apps/backend/.env)

Copy apps/backend/.env.example as a starting point — all optional fields are pre-filled with sensible defaults for local dev.

Variable	Description	Default
DATABASE_URL	SQLite file path (e.g. ./robotania.db or sqlite://./robotania.db)	./robotania.db
RPC_URL	Anvil/chain RPC endpoint	http://localhost:8545
CHAIN_ID	Chain ID	31337
MARKET_FACTORY_ADDRESS	Deployed MarketFactory address	required
PRIVATE_KEY	Resolver wallet private key	anvil account #0
ADMIN_KEY	Secret for protected admin endpoints	dev-admin-key
FRONTEND_URL	Frontend URL for CORS	http://localhost:3000
PORT	API port	3001
INDEXER_POLL_MS	Indexer polling interval (ms)	2000
TAKER_FEE_BPS	Taker fee in basis points	100
RESOLUTION_WINDOW_SECONDS	Time after expiry before resolution	60
CHALLENGE_WINDOW_SECONDS	Challenge window after resolution	0
DEMO_FAST_MODE	Shorten all windows for demo	false

CLI (apps/cli/.env or flags)

Copy apps/cli/.env.example as a starting point.

Variable / Flag	Description	Default
RPC_URL / --rpc-url	Chain RPC endpoint	http://localhost:8545
PRIVATE_KEY / --private-key	Operator wallet key	anvil account #0
BACKEND_URL / --backend-url	Backend API URL	http://localhost:3001
MARKET_FACTORY_ADDRESS / --factory-address	MarketFactory address	required
DEMO_AGENT_COUNT	Number of agents in demo	3
DEMO_EXPIRY_SECONDS	Market expiry for demo	60
DEMO_BET_AMOUNT	Bet amount in ETH for demo	0.01

CLI Commands

# Market operations
bun run src/index.ts market create --question "Will ETH hit $5k?" --expiry 3600
bun run src/index.ts market list
bun run src/index.ts market info --market <address>
bun run src/index.ts market resolve --market <address> --outcome Yes
bun run src/index.ts market claim --market <address>

# Agent runtime
bun run src/index.ts agent run --market <address> --strategy random

# Demo
bun run src/index.ts demo run

Testing

# All tests
bun run test

# Individual suites
bun run test:contracts    # forge test (69 tests)
bun run test:backend      # bun test (19 unit + integration)
bun run test:cli          # bun test (20 tests)
bun run test:dashboard    # vitest (22 unit) + playwright (8 E2E)

Lint

bun run lint
bun run lint:fix