Architecture Overview

​

System Architecture

​

Components

​

Frontend: Mouth Web App

• Framework: Next.js (App Router)
• Auth & Wallets: Privy SDK
• Styling: Tailwind CSS
• State management: React Query for server state
• Key pages:
  • / — Landing page + explore active bets
  • /create — Create a new bet
  • /bet/[id] — Bet detail page (view, accept, claim)
  • /@[handle] — User profile page
  • /leaderboard — Global leaderboard

​

Backend: Mouth API

• Runtime: Node.js
• Framework: Express or Hono
• Database: PostgreSQL (bet metadata, user profiles, X handles)
• Key responsibilities:
  • User registration and X handle mapping
  • Bet CRUD operations (off-chain metadata)
  • Serve data to the web app (bet lists, profiles, leaderboard)
  • Trigger smart contract interactions via server-side Privy wallets

​

X Bot Service

• Runtime: Node.js (standalone service)
• X API: v2 (filtered stream or polling for mentions)
• Key responsibilities:
  • Monitor @MouthBet mentions
  • Post bet links, notifications, and results
  • Parse tweet context for pre-filling bet creation

​

Resolution Engine

• Runtime: Node.js (cron-based or event-driven)
• Key responsibilities:
  • Monitor bets approaching expiration
  • Fetch data from oracles for automatic resolution
  • Queue manual resolutions for the Mouth team
  • Submit resolution transactions to smart contracts
  • Manage dispute windows

​

Event Indexer

• Options: Custom indexer, Envio, or The Graph subgraph
• Key responsibilities:
  • Listen to on-chain events from bet contracts (BetCreated, BetAccepted, BetResolved, FundsClaimed)
  • Update the database in real-time
  • Ensure the web app reflects the latest on-chain state

​

Smart Contracts (Base)

• MouthBetFactory: Deploys individual bet contracts
• MouthBet: Individual bet escrow contract (holds USDC, enforces rules)
• Language: Solidity ^0.8.24
• USDC: Native USDC on Base (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)

​

Data Flow

​

Bet Creation

1. User authenticates via Privy (X login → embedded wallet)
2. User fills bet form on web app
3. API stores off-chain metadata (description, tweet URL, category)
4. API triggers Factory contract to deploy a new Bet contract
5. User’s embedded wallet deposits USDC into the Bet contract
6. Indexer picks up BetCreated event, updates database
7. Bot posts on X (if applicable)

​

Bet Resolution

1. Resolution Engine detects bet has reached expiration
2. For auto-resolution: fetches oracle data, determines outcome
3. For manual resolution: flags for Mouth team review
4. Resolution is submitted to the Bet contract via resolve()
5. If disputeable: 48-hour dispute window starts → finalize() after window expires
6. If non-disputeable: bet is immediately finalized
7. Indexer picks up Resolved / Finalized events
8. Bot posts result on X
9. For non-disputeable PvP 1v1: backend calls resolverClaim() to distribute funds automatically
10. For disputeable / Open PvP: winner claims via web app → USDC sent to embedded wallet