FORGE Architecture

Deployment model

One DigitalOcean Ubuntu host, multiple isolated Node.js services under PM2. This is a monolithic deployment footprint, but service-based runtime boundaries reduce blast radius and let the indexer, WebSocket gateway and agent worker restart independently.

Internet
   |
Cloudflare DNS (optional proxy)
   |
Nginx :443
   |---------------------|-------------------|
   |                     |                   |
Next.js web :3000   Fastify API :3001   WS gateway :3002
                         |                   |
                         |----- Redis -------|
                         |
                  PostgreSQL :5432
                         ^
                         |
             Indexer :3010 / Worker :3011
                 |               |
           RPC HTTP/WS      xAI API / PONS escrow / Mobula Enterprise
                 |                    |
          Robinhood Chain      OHLCV + swap quoting (server-side)

Mobula: charts + swap routing only. Browser → FORGE API/WS → Mobula (enterprise key never leaves the server). See Market data.

PM2 services

forge-web

• Next.js production server
• SSR/public app
• no private chain signer
• talks to API and WS over localhost/public origin

forge-api

• Fastify TypeScript API
• auth nonce/session validation
• Agent CRUD
• launch intent creation
• read APIs
• admin APIs
• generates short-lived launch payloads, never signs user wallet transactions

forge-ws

• WebSocket gateway
• Redis pub/sub subscriber
• room subscriptions by token/agent/global
• sequence IDs and replay cursor
• heartbeat/ping

forge-indexer

• direct chain indexer
• one leader process in MVP
• HTTP RPC backfill + WS RPC tail
• reorg-aware block checkpoints
• emits normalized domain events to Redis
• writes canonical indexed state to PostgreSQL

forge-worker

• agent chat jobs if async processing is needed
• fee-vault claim keeper jobs — only claim when callerTip ≥ gas + min profit (Fee keeper)
• optional Mobula OHLCV WebSocket fan-out into Redis for TradingView live bars
• boost expiry
• usage aggregation
• scheduled data refreshes
• keeper / Mobula keys are worker-or-api-only; never shared with AI execution code

State domains

On-chain canonical

• launch token/curve
• trades
• graduation
• creator fee recipient
• vault split events
• FORGE burns/boost proof
• balances/holdings at read time

PostgreSQL canonical for product metadata

• Agent identity/prompt versions
• template configuration
• launch-to-agent mapping
• sessions
• boost campaign metadata after proof validation
• audit logs
• usage accounting

Redis ephemeral

• pub/sub events
• distributed lock for worker jobs
• rate limits
• short-lived chat streaming/session cursor
• cache

Launch adapter interface

interface LaunchAdapter {
  id: 'pons' | 'pumpfun' | 'flap';
  chain: string;
  getCapabilities(): Promise<LaunchCapabilities>;
  getLiveConfig(): Promise<LaunchConfig[]>;
  canLaunch(wallet: Address): Promise<boolean>;
  buildLaunchIntent(input: LaunchInput): Promise<UnsignedLaunchIntent>;
  parseLaunchReceipt(receipt: TransactionReceipt): Promise<LaunchResult>;
  getLaunchState(token: string): Promise<NormalizedLaunchState>;
  getQuote(input: TradeQuoteInput): Promise<TradeQuote>;
}

MVP only registers PonsLaunchAdapter. Other adapters return COMING_SOON and have no signing code shipped.

RPC manager

Provide at least two HTTP RPCs and preferably two WS RPCs.

Responsibilities:

• periodic eth_blockNumber/latency health check
• fail over reads after timeout/error threshold
• reconnect WS with exponential backoff + jitter
• after reconnect, backfill [last_finalized+1, latest] using HTTP before accepting live tail
• quarantine provider returning inconsistent chainId

Do not round-robin eth_getLogs across providers while indexing the same range unless results are validated; deterministic checkpointing is more important than spreading requests.

Reorg model

Tables store block_number, block_hash, tx_hash, log_index.

Indexer:

1. receives head
2. compares parent hash to stored last processed hash
3. on mismatch, walks backwards to common ancestor
4. deletes/reverts domain rows derived only from orphaned blocks
5. replays canonical blocks
6. publishes chain.reorg event so clients invalidate affected candles/trades

Use a small “unfinalized” window for UI and a finalized marker separately.

Event bus

Redis channels:

• forge:global
• forge:agent:{agentId}
• forge:token:{chainId}:{token}
• forge:ops:indexer

Normalized event envelope:

{
  "v": 1,
  "seq": "18492381-00012",
  "type": "trade.executed",
  "ts": "2026-10-08T00:00:00.000Z",
  "chainId": 4663,
  "agentId": "uuid",
  "token": "0x...",
  "data": {}
}

Authentication

MVP uses wallet auth:

• API issues nonce
• user signs EIP-4361-style message or equivalent clearly scoped challenge
• server verifies address/signature/domain/expiration
• session stored as secure HttpOnly cookie
• CSRF protection for mutations if cookie-based

Admin accounts require separate role assignment in DB and should be protected with an additional authentication factor/reverse-proxy restriction where practical.

Agent execution isolation

The LLM receives:

• explicit Agent system prompt
• conversation context
• public/user-authorized data
• JSON schemas for allowed tools

It never receives:

• .env
• database DSN
• Redis credentials
• platform wallet private key
• arbitrary RPC signer
• filesystem path
• shell
• generic outbound HTTP function

Tools are server functions identified by stable IDs and validate every parameter independently of model output.