Phase 9: BotFights Platform Upgrade — Context

Source: User-directed express path (2026-07-30 session; requirements stated verbatim by the user, equivalent to discuss-phase output)

Domain

BotFights is a standalone app (separate repo) distributed to Archipelago nodes as a container app via the signed catalog. Users register AI bots that battle in trivia/arcade fights; humans can also fight via controllers. Today every node runs a fully isolated arena (own SQLite DB), login is an unauthenticated "trust the pubkey" POST, and bot setup requires hopping across four markdown docs.

App source repo: /home/archipelago/Projects/botfight — main repo is now https://source.archipelago-foundation.org/lfg2025/botfights (mirrored 2026-07-30 from git.tx1138.com/lfg2025/botfight with full history; remote origin = our Gitea, remote tx1138 = old home). Stack: pnpm workspace, Vue 3 + Vite frontend, Hono/TypeScript server, SQLite via drizzle-orm, SSE fight streaming, Dockerfile → image published to vps2 registry 146.59.87.168:3000/lfg2025/botfights (currently 1.1.0).

Archy-side artifacts: apps/botfights/manifest.yml, signed app-catalog (app-catalog/catalog.json + releases), app icon in neode-ui.

Locked Decisions (user-stated)

BOT-01 — Native nostr signer login. Replace the bare-pubkey POST /api/auth/login trust model with a real signer flow: NIP-07 (window.nostr — browser extension / Amber on Android) + NIP-98 signed HTTP auth event verified server-side, per the design already written in the repo's nostr-login-implementation.md. The user never shares a private key with the app.
BOT-02 — One self-contained AI bot-setup prompt. The current DocsPage (BOTFIGHTS.md / BOTFIGHTS-EASY.md / BOTFIGHTS-POLLING.md / BOTFIGHTS-WEBHOOK.md + BOT_SETUP.md) is confusing. Replace with a single copy-paste prompt that contains EVERYTHING an AI agent needs to set up a working bot: registration, auth/secrets handling, webhook AND polling protocols, all API endpoints, response formats. "It all needs to be given inside the one prompt."
BOT-03 — Shared public match endpoint on VPS2. Every node's BotFights instance must use a public arena endpoint hosted on VPS2 (146.59.87.168, docker + nginx-proxy-manager; subdomains under archipelago-foundation.org available, pattern: new NPM proxy host + Let's Encrypt) by default, so all nodes see all fighters and battle across nodes. Node-local instance remains the runtime but match/fighter state is the shared public arena.
BOT-04 — Registry/manifest update. New app version: build + push new image to the vps2 registry, bump apps/botfights/manifest.yml, regenerate + re-sign + republish the signed catalog (catalog manifest overlay supremacy — disk edits don't apply to catalog-covered apps).

Architecture Decision (user, 2026-07-30): Arena-as-relay

BOT-03 is built and DOCUMENTED as a decentralized "arena = nostr relay" model, per project philosophy:

Any node can host a public arena — it is the same app image; a public arena is just a BotFights instance without ARENA_UPSTREAM_URL that others point at.
Each node chooses its arena community via ARENA_UPSTREAM_URL (env/manifest); unset = standalone.
The Foundation's VPS2 arena is only the well-known default, like the vps2 FIPS anchor — a rendezvous, not an authority. Nothing in the code hardcodes a center.
Canonical arena URL (updated 2026-07-30, supersedes the plain-IP decision): https://botfights.archipelago-foundation.org — the user created the DNS A record + NPM proxy host + Let's Encrypt cert mid-execution. TLS is live and verified; TRUSTED_PROXY=1 enabled on the arena. Raw fallback http://146.59.87.168:9100 still works. ARENA_UPSTREAM_URL in the manifest (09-06) and all docs/prompt examples use the HTTPS domain.
The game UI is always served from the user's own node; only match/fighter state lives on the chosen arena.
The unified AI prompt + docs (BOT-02) and docs/arena-deployment.md MUST present it this way, including "how to host your own arena" as a first-class section.
Later phase (roadmap note): nostr-event-based fighter/arena discovery across multiple arenas.

Claude's Discretion

Exact architecture for BOT-03 (thin-client mode vs sync/federation protocol) — chosen during planning based on research; bias toward the simplest thing that makes "all nodes see all fighters" true.
JWT/session mechanics, token TTLs, migration path for existing registered bots (preserve existing bots — migrations never destroy data).
Whether the unified prompt lives at a stable GET endpoint (e.g. /api/docs/prompt or /prompt.md) plus a copy button in the UI — recommended so the prompt is itself fetchable by AI agents.
Version number for the release (suggest 1.2.0).

Scope Fence

IN: botfights repo changes (server + frontend + docs/prompt), VPS2 public arena deployment, archy manifest/catalog update, dev-pair verification.
OUT: Lightning/cashu payment changes, arcade gameplay changes, tournament logic, companion app work, any archy core/orchestrator changes beyond the manifest/catalog.

Hard Deadline / Demo Constraint (added 2026-07-30)

The user demos this TOMORROW (2026-07-31) from archi-dev-box. Everything must be deployed and verified working on archi-dev-box before end of this phase. Real bot testing will be done with a cloud-hosted "openclaw" bot — meaning: the VPS2 public arena must be internet-reachable with TLS, the unified AI bot-setup prompt must be sufficient for a cloud agent to register and fight using only that prompt, and webhook/polling must work from outside the LAN (cloud bot → public arena). Prioritize the demo-critical path over nice-to-haves.

Constraints & Process Rules

Rootless podman invariants on nodes; VPS2 uses docker + nginx-proxy-manager (this is host infra, not a node app).
Commit + push every unit of work (botfights repo → origin = our Gitea main; archy → gitea-ai main).
Deploy/verify on dev pair (archi-dev-box + x250-dev) before any OTA/catalog publish.
Never commit secrets; catalog artifacts are signed offline by the user.
Test the real user path before claiming fixed (signer login in a real browser, a real cross-node fight visible from two instances).

6.2 KiB Raw Blame History