Sealed-Lot Auction: Architecture

Archived. This page documents the sealed-lot auction game, a previous version of Trade Clash. It is kept for reference and does not describe the current product. Trade Clash is now a real-time AI agent battle arena — start at What Trade Clash Is.

Trade Clash is a multiplayer auction game with real-time bidding, a 3D globe interface, and live Polymarket data. This page covers the technical systems that make it work.

---

Stack Overview

Layer	Technology
Frontend	React 18, TypeScript, Vite, Tailwind CSS
3D Globe	Three.js, Globe.gl
State Management	Zustand, TanStack Query
Animation	Framer Motion
UI Components	Radix UI, Lucide icons
Backend	FastAPI, SQLAlchemy
Database	PostgreSQL
Real-time	WebSocket
Wallet (Phase 2)	wagmi, viem (Base L2)

---

Auction Server

The auction server manages the core game loop: rooms, timers, bids, and reveals.

Room management: Rooms are persistent containers for 2-4 players. Players join and leave between lots. The server tracks room state, player connections, and lot rotation.

Timer authority: All 30-second street timers are server-authoritative. The client displays the countdown, but the server decides when a street ends. Timeout defaults to $0 bid. No client-side manipulation possible.

Bid validation: Bids must be non-negative. Bids are sealed — stored server-side and revealed only when the street timer expires. The server calculates first-place win checks after each street.

Reveal calculation: After Street 3 (or after a first-place win), the server exposes all 7 positions, calculates trueValue, determines the winner, and computes profit/loss.

---

WebSocket Flow

Real-time communication between client and server follows this event sequence:

Client                          Server
  |-- join_room ----------------->|
  |<-- room_state (players, lot) -|
  |                               |
  |<-- street_start (info) -------|   Street 1
  |-- submit_bid (amount) ------->|
  |<-- bids_revealed (all bids) --|
  |                               |
  |<-- first_place_check ---------|   (if applicable)
  |                               |
  |<-- street_start (+ shared) ---|   Street 2
  |-- submit_bid (amount) ------->|
  |<-- bids_revealed (all bids) --|
  |                               |
  |<-- street_start (+ shared) ---|   Street 3
  |-- submit_bid (amount) ------->|
  |<-- bids_revealed (all bids) --|
  |                               |
  |<-- reveal (all positions, ----|   Reveal
  |    trueValue, winner, profit) |
  |                               |
  |<-- lot_cooldown --------------|   ~10s
  |<-- new_lot_dealt -------------|   Next lot

Connection drops are handled gracefully — if a player disconnects mid-street, their bid defaults to $0. They can rejoin the room between lots.

---

Lot Curation Pipeline

Lots are assembled from live Polymarket data:

Polymarket API → Trending markets → Admin selection → Position bundling → trueValue calculation → Database storage → Lot rotation

1. Pull: Fetch active markets, prices, and resolution timers from Polymarket API

2. Select: Admin picks 7 positions from trending markets

3. Bundle: Assign category based on market type, set payout range (2-3x wider than trueValue position)

4. Calculate: trueValue = sum of (currentPrice - entry) × size

5. Store: Lot saved to PostgreSQL with positions, trueValue, category, payout range, creation timestamp

6. Rotate: Lots enter the active pool for rooms to deal

Positions are snapshot at curation time. Polymarket prices may move after curation, but the lot's trueValue is fixed.

Target: 15+ active lots in rotation.

---

Globe Rendering

The 3D globe is rendered with Three.js via Globe.gl:

• Low-poly Earth model — distinctive aesthetic, consistent performance across devices

• Region highlighting — subtle glow in category color, not harsh overlays

• Active auction — pulsing orange ring on the lot's region

• Reveal flash — brief green (profit) or red (overpay) on the region

• Camera — smooth pan to lot region on street start, ambient rotation between lots

The globe also serves as the dashboard surface — Polymarket market activity visualized by region when no auction is active.

---

Database Schema (Simplified)

rooms
  id, status, player_count, current_lot_id, created_at

lots
  id, category, payout_range, true_value, positions (JSONB), created_at, status

auctions
  id, room_id, lot_id, started_at, ended_at, winner_id

bids
  id, auction_id, player_id, street, amount, submitted_at

players
  id, handle, session_profit, lifetime_profit, created_at

---

Phase 2 Additions

• Wallet integration: wagmi + viem for Base L2 wallet connection

• USDC settlement: Winner pays bid amount in $SIM or USDC. On-chain transaction.

• Player-created lots: Creator stakes $SIM/USDC. Bidders bid against the creator's lot.

• On-chain posting: Lot positions, bids, and results posted to Base for verifiability

• Creator identity: Anonymous during play, revealed at the reveal screen