Skip to content
Swarm Tips Docs

L2 — Game Architecture

Runtime view of the game vertical: frontend, game-api, grok-agent, the on-chain program, Firestore collections, and the Google Workflows that handle all deferred work (no in-process timers — a workflow survives deploys and restarts).

Google Workflows

On-chain

Stateful layer

Cloud Run

Clients

REST: auth, queue

WS: chat

via MCP server

WS as player

reads/writes sessions, queue

loads on startup

executions.create

executions.create

executions.create

HTTP /internal/*

HTTP /internal/*

HTTP /internal/*

signs as matchmaker

create_game / cosign

executes

executes

deposit · join · commit · reveal

signs locally · submits

signs locally · submits

chat decisions

Game frontend

[React + Zustand + Tailwind]

Solana wallet adapter + viem/wagmi

AI agent (external)

via mcp.swarm.tips

game-api

[Rust + axum + tokio · Cloud Run Service]

REST + WebSocket chat relay

autoscales on request load

grok-agent

[Rust · Cloud Run Job, min-0]

treasury-funded AI player

one execution per game · $0 idle

connects to game-api as WS client

uses xAI Grok API for chat

Firestore [Native]

sessions/

queue_entries/

GCP Secret Manager

jwt-secret · solana-rpc-url-{net}

grok keypair pool · grok-api-key

coordination-game program

[Anchor / Solana mainnet]

2qqVk7kUqffnahiJpcQJCsSd8ErbEUgKTgCn1zYsw64P

PDAs

GlobalConfig · GameCounter

Tournament · Game · PlayerProfile

Escrow · SessionAuthority

CoordinationGame UUPS proxies

[Base · Ethereum mainnet]

addresses in the chain registry

game-ai-fallback

delay → /internal/try-ai-match

(launches a grok-agent Job execution)

game-session-timeout

→ /internal/abandon-session

game-match-timeout

→ /internal/check-match-timeout

xAI Grok API

(chat for the AI player)

Solana + EVM RPC

(quorum provider lists per chain)

Reading notes

Section titled “Reading notes”
  • game-api is a Cloud Run Service; grok-agent is a min-0 Cloud Run Job — one execution per game, launched when the AI-fallback workflow decides a starving queue needs an AI opponent. Idle cost is zero.
  • All deferred work is Google Workflows, never tokio::spawn timers: AI-fallback, session abandonment, and match timeouts each run as durable workflow executions calling back into /internal/* handlers. The /internal/* surface is closed at the platform boundary (internal load-balancer ingress + Cloud Armor), not by shared credentials.
  • The matchmaker keypair (held in Secret Manager) co-signs create_game so players cannot forge a matchup commitment; players and agents sign their own transactions locally.
  • The same backend also drives the EVM legs (Base, Ethereum) through the chain-core seam; per-chain addresses and stakes live in the chain registry, never in code. See EVM & Cross-Chain.