@flayerlabs/gamemode-gate 0.4.3 → 0.5.1

package/src/economy.ts

@@ -7,41 +7,68 @@
  * environment variable was wrong, and no code was in a position to notice.
  *
  * So the arithmetic lives here, runs at round creation with the actual values, and refuses. A
- * creator sets one human number — how many points a dollar is worth — and never sees wei.
+ * creator sets one human number — how many points a dollar is worth — and never sees base units.
+ *
+ * Denomination. A pool's spend is measured on chain in its PAIRED token's own base units: wei for
+ * an ETH-paired coin, 10^-6 for a six-decimal stablecoin. Every amount in this package is
+ * therefore base units of the round's spend token, and the arithmetic here is parameterised by
+ * that token's decimals rather than assuming eighteen.
  */
 
-/** 1 ETH in wei. */
+/** The decimals of ETH, which is what every field was denominated in before paired-token rounds. */
+export const ETH_DECIMALS = 18;
+
+/** 1 ETH in wei. Kept as the default `unitsPerToken` so an ETH round is byte-identical to before. */
 const WEI_PER_ETH = 1_000_000_000_000_000_000n;
 
+/** 10^decimals: one whole spend token in its base units. */
+export function unitsPerToken(decimals: number): bigint {
+  return 10n ** BigInt(decimals);
+}
+
 export interface EconomyInput {
   /** The most one player can earn, declared by the game itself via `rewardBounds`. */
   maxPointsPerPlayer: number;
-  /** The pool's on-chain per-wallet ceiling. The chain enforces this whatever we do. */
-  walletCapWei: bigint;
+  /** The pool's on-chain per-wallet ceiling, in base units of the spend token. */
+  walletCap: bigint;
   /** The creator's one knob. 100 means 100 points is worth a dollar. */
   pointsPerDollar: number;
-  usdPerEth: number;
+  /** The market price of one whole spend token, in dollars. For an ETH round this IS the ETH price. */
+  usdPerSpendToken: number;
+  /** Decimals of the spend token. Defaults to 18 — ETH — which is what every older caller meant. */
+  decimals?: number;
 }
 
 export interface Economy {
-  weiPerPoint: bigint;
-  /** What a flawless round pays. Always at or under `walletCapWei`, or this would not exist. */
-  maxPayoutWei: bigint;
+  /** Base units of the spend token per point. */
+  unitsPerPoint: bigint;
+  /** What a flawless round pays. Always at or under `walletCap`, or this would not exist. */
+  maxPayout: bigint;
   /**
-   * The two inputs, returned beside the rate they produced.
+   * The inputs, returned beside the rate they produced.
    *
    * They travel together so a caller cannot persist a rate from one calculation and a dollar
    * figure from another. Both are process-wide settings, so the only place they are true of a
    * particular round is the moment that round's rate was fixed.
    */
   pointsPerDollar: number;
-  usdPerEth: number;
+  /** The market price of one whole spend token — what a display should call the token's price. */
+  usdPerSpendToken: number;
+  /** The spend token's decimals. */
+  decimals: number;
 }
 
 export type EconomyResult =
   | { ok: true; economy: Economy }
   | { ok: false; problem: string; suggestedPointsPerDollar: number };
 
+function resolveInputs(input: EconomyInput): { usdPerSpendToken: number; decimals: number } {
+  return {
+    usdPerSpendToken: input.usdPerSpendToken ?? Number.NaN,
+    decimals: input.decimals ?? ETH_DECIMALS,
+  };
+}
+
 /**
  * Resolve the rate for one round, or refuse with the number that fixes it.
  *
@@ -54,13 +81,25 @@ export type EconomyResult =
  * goes and reads this file.
  */
 export function resolveEconomy(input: EconomyInput): EconomyResult {
-  const { maxPointsPerPlayer, walletCapWei, pointsPerDollar, usdPerEth } = input;
+  const { maxPointsPerPlayer, walletCap, pointsPerDollar } = input;
+  const { usdPerSpendToken, decimals } = resolveInputs(input);
 
   if (!Number.isFinite(pointsPerDollar) || pointsPerDollar <= 0) {
     return { ok: false, problem: 'points per dollar must be a positive number', suggestedPointsPerDollar: 100 };
   }
-  if (!Number.isFinite(usdPerEth) || usdPerEth <= 0) {
-    return { ok: false, problem: 'the ETH price must be a positive number', suggestedPointsPerDollar: pointsPerDollar };
+  if (!Number.isSafeInteger(decimals) || decimals < 0 || decimals > 36) {
+    return {
+      ok: false,
+      problem: 'the spend token must have between 0 and 36 decimals',
+      suggestedPointsPerDollar: pointsPerDollar,
+    };
+  }
+  if (!Number.isFinite(usdPerSpendToken) || usdPerSpendToken <= 0) {
+    return {
+      ok: false,
+      problem: 'the spend token price must be a positive number',
+      suggestedPointsPerDollar: pointsPerDollar,
+    };
   }
   if (!Number.isSafeInteger(maxPointsPerPlayer) || maxPointsPerPlayer <= 0) {
     return {
@@ -69,7 +108,7 @@ export function resolveEconomy(input: EconomyInput): EconomyResult {
       suggestedPointsPerDollar: pointsPerDollar,
     };
   }
-  if (walletCapWei <= 0n) {
+  if (walletCap <= 0n) {
     return {
       ok: false,
       problem: 'this launch has no per-wallet spending cap, so nothing can be authorised',
@@ -77,30 +116,31 @@ export function resolveEconomy(input: EconomyInput): EconomyResult {
     };
   }
 
-  // How many points one ETH buys. Checked before it becomes a divisor: `pointsPerDollar` is
-  // guarded as positive above, but a small enough positive value still rounds this product to
+  // How many points one whole token buys. Checked before it becomes a divisor: `pointsPerDollar`
+  // is guarded as positive above, but a small enough positive value still rounds this product to
   // zero — and dividing by it threw `Division by zero` out of the one function whose entire job is
   // to refuse a bad economy with a sentence an operator can act on.
-  const pointsPerEth = Math.round(usdPerEth * pointsPerDollar);
-  if (pointsPerEth <= 0) {
+  const pointsPerToken = Math.round(usdPerSpendToken * pointsPerDollar);
+  if (pointsPerToken <= 0) {
     return {
       ok: false,
-      problem: 'one point would be worth more than a whole ETH, which cannot be what was meant',
+      problem: 'one point would be worth more than a whole spend token, which cannot be what was meant',
       suggestedPointsPerDollar: minimumPointsPerDollar(input),
     };
   }
 
-  const weiPerPoint = WEI_PER_ETH / BigInt(pointsPerEth);
-  if (weiPerPoint <= 0n) {
+  const units = unitsPerToken(decimals);
+  const unitsPerPoint = units / BigInt(pointsPerToken);
+  if (unitsPerPoint <= 0n) {
     return {
       ok: false,
-      problem: 'each point would be worth less than the smallest unit of ETH',
+      problem: 'each point would be worth less than the smallest unit of the spend token',
       suggestedPointsPerDollar: Math.max(1, Math.floor(pointsPerDollar / 1000)),
-      };
+    };
   }
 
-  const maxPayoutWei = BigInt(Math.floor(maxPointsPerPlayer)) * weiPerPoint;
-  if (maxPayoutWei > walletCapWei) {
+  const maxPayout = BigInt(Math.floor(maxPointsPerPlayer)) * unitsPerPoint;
+  if (maxPayout > walletCap) {
     return {
       ok: false,
       problem: 'a perfect round would earn more than this launch lets one wallet spend',
@@ -108,24 +148,36 @@ export function resolveEconomy(input: EconomyInput): EconomyResult {
     };
   }
 
-  return { ok: true, economy: { weiPerPoint, maxPayoutWei, pointsPerDollar, usdPerEth } };
+  return {
+    ok: true,
+    economy: {
+      unitsPerPoint,
+      maxPayout,
+      pointsPerDollar,
+      usdPerSpendToken,
+      decimals,
+    },
+  };
 }
 
 /**
  * The smallest `pointsPerDollar` that keeps a flawless round inside the cap.
  *
  * Rounded up, then nudged until it actually passes: the division that produces it floors, and a
- * value that is correct to the last wei but fails the check is worse than useless in an error
+ * value that is correct to the last unit but fails the check is worse than useless in an error
  * message. Two steps is enough for any input — the loop is a guard against an off-by-one in the
  * rounding, not an iterative search.
  */
 function minimumPointsPerDollar(input: EconomyInput): number {
-  const { maxPointsPerPlayer, walletCapWei, usdPerEth } = input;
+  const { maxPointsPerPlayer, walletCap } = input;
+  const { usdPerSpendToken, decimals } = resolveInputs(input);
   const points = BigInt(Math.floor(maxPointsPerPlayer));
-  const maxWeiPerPoint = walletCapWei / points;
-  if (maxWeiPerPoint <= 0n) return Math.ceil(maxPointsPerPlayer);
+  const maxUnitsPerPoint = walletCap / points;
+  if (maxUnitsPerPoint <= 0n) return Math.ceil(maxPointsPerPlayer);
 
-  let candidate = Math.ceil(Number(WEI_PER_ETH / maxWeiPerPoint) / usdPerEth);
+  const units =
+    Number.isSafeInteger(decimals) && decimals >= 0 && decimals <= 36 ? unitsPerToken(decimals) : WEI_PER_ETH;
+  let candidate = Math.ceil(Number(units / maxUnitsPerPoint) / usdPerSpendToken);
   for (let i = 0; i < 3; i++) {
     const result = resolveEconomy({ ...input, pointsPerDollar: candidate });
     if (result.ok) return candidate;

package/src/index.ts

@@ -11,10 +11,12 @@ export type {
   Admission,
   AdmissionRequest,
   Admit,
+  AnnouncedSpendToken,
   ConfigForLaunch,
   GameServerGateOptions,
   GateOptions,
   MaxPointsForLaunch,
+  PriceFor,
   VerifiedLaunch,
 } from './server.js';
 export { createTurnstileAdmit } from './turnstile.js';
@@ -28,7 +30,8 @@ export type { SignedPayload } from './chain/signer.js';
 export { Discovery, poolIdOf, verifyLaunch } from './chain/discover.js';
 export type { ChainReader, Deployment, Launch, LaunchCheck, PoolKey, Refused } from './chain/discover.js';
 export { Settlement } from './settlement.js';
-export { resolveEconomy } from './economy.js';
+export { Standings } from './standings.js';
+export { ETH_DECIMALS, resolveEconomy, unitsPerToken } from './economy.js';
 export type { Economy, EconomyInput, EconomyResult } from './economy.js';
 export { migrate } from './store.js';
 export { createDemoGate } from './demo.js';
@@ -62,9 +65,9 @@ export type { VerifiedPlayerJoin, VerifyPlayerJoinTicketOptions } from './player
  * gate (see DEPLOY.md), and the pieces below it stay exported for anyone wiring their own.
  */
 export { startGate, resolveGateEnv } from './main.js';
-export type { ResolvedGateConfig, StartedGate, StartGateOverrides } from './main.js';
+export type { ResolvedGateConfig, SpendTokenPricing, StartedGate, StartGateOverrides } from './main.js';
 export type { GateAnnouncement } from './server.js';
 export { NotSignedIn } from './sessions.js';
-export { DEPLOYMENTS, deploymentFor } from './chain/chains.js';
-export type { GateDeployment } from './chain/chains.js';
-export { assertSecureConfig } from './chain/secure.js';
+export { DEPLOYMENTS, PAIRED_DEPLOYMENTS, deploymentFor } from './chain/chains.js';
+export type { FlaunchVariant, GateDeployment } from './chain/chains.js';
+export { POSITION_MANAGER_ROLE, assertSecureConfig } from './chain/secure.js';

package/src/ledger.ts

@@ -37,12 +37,12 @@ export interface BalanceKey {
 
 interface LedgerState {
   points: bigint;
-  weiPerPoint: bigint;
+  unitsPerPoint: bigint;
   capWei: bigint;
   opensAt: number;
   closesAt: number;
   /** Authorisations still outstanding: issued, not yet expired, fate unknown. */
-  heldWei: bigint;
+  held: bigint;
   /** What the chain says has actually been spent. */
   chainSpentWei: bigint;
   /**
@@ -60,9 +60,9 @@ interface LedgerState {
  * wallet spend. Issuing past the second does not overspend — the chain refuses it — it mints a
  * signature that reverts at the swap, which to a player is indistinguishable from being robbed.
  */
-function availableFrom({ points, weiPerPoint, capWei, heldWei, chainSpentWei }: LedgerState): bigint {
-  const earnedWei = points * weiPerPoint;
-  const ceiling = earnedWei < capWei ? earnedWei : capWei;
+function availableFrom({ points, unitsPerPoint, capWei, held, chainSpentWei }: LedgerState): bigint {
+  const earned = points * unitsPerPoint;
+  const ceiling = earned < capWei ? earned : capWei;
 
   // Spent-on-chain PLUS still-outstanding, never the larger of the two.
   //
@@ -74,7 +74,7 @@ function availableFrom({ points, weiPerPoint, capWei, heldWei, chainSpentWei }:
   //
   // Adding them double-counts a hold whose swap has already landed, until that hold expires. That
   // errs towards authorising too little, which is the direction that costs nobody anything.
-  const available = ceiling - (chainSpentWei + heldWei);
+  const available = ceiling - (chainSpentWei + held);
   return available > 0n ? available : 0n;
 }
 
@@ -186,11 +186,11 @@ export class Ledger {
    *
    * Never allowed to go backwards: a read from a lagging node must not undo what a later one saw.
    */
-  async recordChainSpend(roundId: string, player: PlayerId, spentWei: bigint): Promise<boolean> {
+  async recordChainSpend(roundId: string, player: PlayerId, spent: bigint): Promise<boolean> {
     const result = await this.pool.query(
       `update balances set chain_spent_wei = greatest(chain_spent_wei, $3)
        where round_id = $1 and player = $2 and chain_spent_wei < $3`,
-      [roundId, player, spentWei.toString()],
+      [roundId, player, spent.toString()],
     );
     return result.rowCount === 1;
   }
@@ -227,23 +227,23 @@ export class Ledger {
     return [...unique.values()];
   }
 
-  async availableWei(roundId: string, player: PlayerId): Promise<bigint> {
-    return (await this.economyBalance(roundId, player)).availableWei;
+  async available(roundId: string, player: PlayerId): Promise<bigint> {
+    return (await this.economyBalance(roundId, player)).available;
   }
 
   /** The authoritative balance snapshot, derived from the same state and ceiling as `claim`. */
   async economyBalance(roundId: string, player: PlayerId): Promise<EconomyBalance> {
     const state = await this.readState(this.pool, roundId, player);
     if (!state) {
-      return { weiPerPoint: 0n, earnedWei: 0n, heldWei: 0n, spentWei: 0n, availableWei: 0n, holdExpiresAt: null };
+      return { unitsPerPoint: 0n, earned: 0n, held: 0n, spent: 0n, available: 0n, holdExpiresAt: null };
     }
 
     return {
-      weiPerPoint: state.weiPerPoint,
-      earnedWei: state.points * state.weiPerPoint,
-      heldWei: state.heldWei,
-      spentWei: state.chainSpentWei,
-      availableWei: availableFrom(state),
+      unitsPerPoint: state.unitsPerPoint,
+      earned: state.points * state.unitsPerPoint,
+      held: state.held,
+      spent: state.chainSpentWei,
+      available: availableFrom(state),
       // Seconds on the way in, because that is what the contract checks against; milliseconds on
       // the way out, because that is what a browser counts down with.
       holdExpiresAt: state.holdExpiresAtSeconds === null ? null : state.holdExpiresAtSeconds * 1000,
@@ -285,11 +285,11 @@ export class Ledger {
     return {
       points: toBigInt(balance.rows[0]?.points),
       chainSpentWei: toBigInt(balance.rows[0]?.chain_spent_wei),
-      weiPerPoint: toBigInt(row.wei_per_point),
+      unitsPerPoint: toBigInt(row.wei_per_point),
       capWei: toBigInt(row.wallet_cap_wei),
       opensAt: Number(row.opens_at),
       closesAt: Number(row.closes_at),
-      heldWei: toBigInt(held.rows[0]?.total),
+      held: toBigInt(held.rows[0]?.total),
       holdExpiresAtSeconds: earliest == null ? null : Number(earliest),
     };
   }

package/src/main.ts

@@ -1,8 +1,9 @@
 import pg from 'pg';
-import { createPublicClient, http, isAddress, type PublicClient } from 'viem';
+import { createPublicClient, http, isAddress, parseAbi, type PublicClient } from 'viem';
 import type { FastifyInstance } from 'fastify';
 import type { GameModule } from '@flayerlabs/gamemode-spec';
-import { createGate, type GateAnnouncement } from './server.js';
+import type { SpendToken } from '@flayerlabs/gamemode-spec/live';
+import { createGate, type AnnouncedSpendToken, type GateAnnouncement, type PriceFor } from './server.js';
 import { Ledger } from './ledger.js';
 import { Claims } from './claims.js';
 import { Sessions } from './sessions.js';
@@ -44,16 +45,31 @@ export interface ResolvedGateConfig {
   port: number;
   deployment: GateDeployment;
   /** Announced to launch tooling; the creator's launch writes it into the pool. */
-  walletCapWei: bigint;
+  walletCap: bigint;
   roundDurationMs: number;
   minLobbyLeadMs: number;
   gateEndsAtGraceS: number;
   pointsPerDollar: number;
+  /** The price of ETH; what ETH-paired rounds are priced at. Fractional values are fine. */
   usdPerEth: number;
+  /**
+   * The non-ETH paired tokens this gate will run rounds on, with the price it fixes them at and the
+   * per-wallet cap a launch on them should write. Keyed by lowercase address. Anything not here is
+   * refused at adoption — the gate does not guess a token's price.
+   */
+  spendTokens: ReadonlyMap<string, SpendTokenPricing>;
   /** May lift the gate early or rotate the signer on-chain. Defaults to the signing key's address. */
   settler: `0x${string}` | null;
 }
 
+export interface SpendTokenPricing {
+  address: `0x${string}`;
+  /** Dollars per whole token. */
+  usdPerToken: number;
+  /** Per-wallet cap for a launch on this token, in its base units. */
+  walletCap: bigint;
+}
+
 function required(env: Env, name: string): string {
   const value = env[name];
   if (!value) throw new Error(`${name} is not set — the gate refuses to guess it`);
@@ -68,6 +84,54 @@ function integer(env: Env, name: string, fallback: number): number {
   return value;
 }
 
+/** A price or a rate: positive, finite, and allowed to be fractional — a dollar stablecoin is 1.0. */
+function positiveNumber(env: Env, name: string, fallback: number): number {
+  const raw = env[name];
+  if (raw === undefined || raw === '') return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) throw new Error(`${name} must be a positive number`);
+  return value;
+}
+
+/**
+ * `SPEND_TOKENS`: a JSON array of `{ address, usdPerToken, walletCap }`.
+ *
+ * Only what the chain cannot tell us: the price, and the cap the operator wants launches on this
+ * token to carry. Symbol and decimals are read from the token itself at boot — an operator-typed
+ * decimals is the exact mistake this whole feature exists to make impossible.
+ */
+function spendTokens(env: Env): ReadonlyMap<string, SpendTokenPricing> {
+  const raw = env['SPEND_TOKENS'];
+  const out = new Map<string, SpendTokenPricing>();
+  if (raw === undefined || raw.trim() === '') return out;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error('SPEND_TOKENS must be a JSON array of { address, usdPerToken, walletCap }');
+  }
+  if (!Array.isArray(parsed)) throw new Error('SPEND_TOKENS must be a JSON array');
+  for (const entry of parsed as unknown[]) {
+    const value = (entry ?? {}) as Record<string, unknown>;
+    // Casing is not checked: operators paste addresses from explorers and configs in every case,
+    // and a rejected checksum here would read as "wrong address" for a right one.
+    if (typeof value.address !== 'string' || !isAddress(value.address, { strict: false })) {
+      throw new Error('SPEND_TOKENS: every entry needs an address');
+    }
+    const usdPerToken = Number(value.usdPerToken);
+    if (!Number.isFinite(usdPerToken) || usdPerToken <= 0) {
+      throw new Error(`SPEND_TOKENS: ${value.address} needs a positive usdPerToken`);
+    }
+    if (typeof value.walletCap !== 'string' || !/^[1-9][0-9]*$/.test(value.walletCap)) {
+      throw new Error(`SPEND_TOKENS: ${value.address} needs walletCap as a decimal string of base units`);
+    }
+    const key = value.address.toLowerCase();
+    if (out.has(key)) throw new Error(`SPEND_TOKENS lists ${value.address} twice`);
+    out.set(key, { address: value.address as `0x${string}`, usdPerToken, walletCap: BigInt(value.walletCap) });
+  }
+  return out;
+}
+
 function address(env: Env, name: string): `0x${string}` | null {
   const raw = env[name];
   if (raw === undefined || raw === '') return null;
@@ -88,23 +152,31 @@ function address(env: Env, name: string): `0x${string}` | null {
  *   GATE_ORIGIN              required; this gate's own public https origin (the SIWE audience)
  *   ALLOWED_ORIGINS          required; comma-separated origins that may call this gate
  *   PORT                     default 8790
- *   POSITION_MANAGER         optional address-book override
+ *   POSITION_MANAGER         optional; selects a recorded stack on the chain (the legacy one when
+ *                            unset), or overrides the address for a chain with no address book
  *   SPEND_GATED_CALCULATOR   optional address-book override
- *   FLAUNCH_VARIANT          optional; only meaningful alongside the overrides
+ *   POOL_SWAP                optional address-book override; required for a v1_3 stack
+ *   FLETH                    optional address-book override; the chain's flETH wrapper
+ *   FLAUNCH_VARIANT          optional; v1_2, multichain or v1_3
  *   SETTLER                  optional; defaults to the signing key's own address
- *   WALLET_CAP_WEI           default 0.025 ETH
+ *   WALLET_CAP_WEI           default 0.025 ETH; the cap for ETH-paired launches
  *   ROUND_MS                 default 90000
  *   MIN_LOBBY_LEAD_MS        default 60000
  *   GATE_ENDS_AT_GRACE_S     default 10
  *   POINTS_PER_DOLLAR        default 100
- *   USD_PER_ETH              default 3000
+ *   USD_PER_ETH              default 3000; fractional allowed
+ *   SPEND_TOKENS             optional JSON array of { address, usdPerToken, walletCap } — the non-ETH
+ *                            paired tokens this gate runs rounds on. Unlisted tokens are refused.
  */
 export function resolveGateEnv(env: Env): ResolvedGateConfig {
   const chainId = Number(required(env, 'CHAIN_ID'));
   if (!Number.isSafeInteger(chainId) || chainId <= 0) throw new Error('CHAIN_ID must be a positive integer');
 
-  const recorded = deploymentFor(chainId);
-  const positionManager = address(env, 'POSITION_MANAGER') ?? recorded?.positionManager ?? null;
+  const namedManager = address(env, 'POSITION_MANAGER');
+  // Naming a manager picks the recorded stack it belongs to — calculator and router with it — so a
+  // paired manager is never paired with the legacy calculator by a half-edited env file.
+  const recorded = deploymentFor(chainId, namedManager);
+  const positionManager = namedManager ?? recorded?.positionManager ?? null;
   const spendGatedCalculator = address(env, 'SPEND_GATED_CALCULATOR') ?? recorded?.spendGatedCalculator ?? null;
   if (!positionManager || !spendGatedCalculator) {
     throw new Error(
@@ -113,10 +185,20 @@ export function resolveGateEnv(env: Env): ResolvedGateConfig {
     );
   }
   const variantOverride = env['FLAUNCH_VARIANT'];
-  if (variantOverride !== undefined && variantOverride !== 'legacy11' && variantOverride !== 'current9') {
-    throw new Error(`FLAUNCH_VARIANT must be legacy11 or current9, not ${variantOverride}`);
+  if (
+    variantOverride !== undefined &&
+    variantOverride !== 'v1_2' &&
+    variantOverride !== 'multichain' &&
+    variantOverride !== 'v1_3'
+  ) {
+    throw new Error(`FLAUNCH_VARIANT must be v1_2, multichain or v1_3, not ${variantOverride}`);
   }
-  const flaunchVariant = variantOverride ?? recorded?.flaunchVariant ?? 'legacy11';
+  const flaunchVariant = variantOverride ?? recorded?.flaunchVariant ?? 'v1_2';
+  const poolSwap = address(env, 'POOL_SWAP') ?? recorded?.poolSwap ?? null;
+  if (flaunchVariant === 'v1_3' && !poolSwap) {
+    throw new Error('a v1_3 stack needs POOL_SWAP — the approved router a paired-token buy goes through');
+  }
+  const fleth = address(env, 'FLETH') ?? recorded?.fleth ?? null;
 
   const signerPrivateKey = required(env, 'SIGNER_PRIVATE_KEY');
   if (!/^0x[0-9a-fA-F]{64}$/.test(signerPrivateKey)) {
@@ -150,17 +232,50 @@ export function resolveGateEnv(env: Env): ResolvedGateConfig {
     gateOrigin: required(env, 'GATE_ORIGIN'),
     allowedOrigins,
     port: integer(env, 'PORT', 8790),
-    deployment: { positionManager, spendGatedCalculator, flaunchVariant },
-    walletCapWei: BigInt(env['WALLET_CAP_WEI'] ?? 25_000_000_000_000_000n.toString()),
+    deployment: {
+      positionManager,
+      spendGatedCalculator,
+      flaunchVariant,
+      ...(poolSwap ? { poolSwap } : {}),
+      ...(fleth ? { fleth } : {}),
+    },
+    walletCap: BigInt(env['WALLET_CAP_WEI'] ?? 25_000_000_000_000_000n.toString()),
     roundDurationMs: integer(env, 'ROUND_MS', 90_000),
     minLobbyLeadMs: integer(env, 'MIN_LOBBY_LEAD_MS', 60_000),
     gateEndsAtGraceS: integer(env, 'GATE_ENDS_AT_GRACE_S', 10),
     pointsPerDollar: integer(env, 'POINTS_PER_DOLLAR', 100),
-    usdPerEth: integer(env, 'USD_PER_ETH', 3_000),
+    usdPerEth: positiveNumber(env, 'USD_PER_ETH', 3_000),
+    spendTokens: spendTokens(env),
     settler: address(env, 'SETTLER'),
   };
 }
 
+const erc20 = parseAbi(['function symbol() view returns (string)', 'function decimals() view returns (uint8)']);
+
+/** Whether a paired token is ETH by another name: native, or the chain's flETH wrapper. */
+function isEthEquivalent(token: SpendToken, fleth: `0x${string}` | undefined): boolean {
+  return token.isNative || (fleth !== undefined && token.address.toLowerCase() === fleth.toLowerCase());
+}
+
+/**
+ * The price list a running gate answers adoption with.
+ *
+ * An override (an oracle, a test) is asked first; the env map second; ETH and its wrapper are the
+ * operator's `USD_PER_ETH`; anything else is unpriced and the launch is refused.
+ */
+function priceList(config: ResolvedGateConfig, override: PriceFor | undefined): PriceFor {
+  return async (token) => {
+    if (override) {
+      const quoted = await override(token);
+      if (quoted !== null) return quoted;
+    }
+    const listed = config.spendTokens.get(token.address.toLowerCase());
+    if (listed) return listed.usdPerToken;
+    if (isEthEquivalent(token, config.deployment.fleth)) return config.usdPerEth;
+    return null;
+  };
+}
+
 export interface StartedGate {
   app: FastifyInstance;
   port: number;
@@ -175,6 +290,11 @@ export interface StartGateOverrides {
   client?: PublicClient;
   /** False builds and checks everything but never binds a port. */
   listen?: boolean;
+  /**
+   * A price source consulted before `SPEND_TOKENS` — an oracle, or a test's constant. Answering
+   * null defers to the env list; a token neither knows is refused at adoption.
+   */
+  priceProvider?: PriceFor;
 }
 
 export async function startGate<Config, State, Event, Action, PublicView, PlayerView>(
@@ -183,13 +303,14 @@ export async function startGate<Config, State, Event, Action, PublicView, Player
   overrides: StartGateOverrides = {},
 ): Promise<StartedGate> {
   const config = resolveGateEnv(overrides.env ?? process.env);
+  const maxPointsPerPlayer = game.rewardBounds(gameConfig).maxPointsPerPlayer;
 
   // The same refusal the demo makes: an economy that cannot pay out is caught before anyone plays.
   const economy = resolveEconomy({
-    maxPointsPerPlayer: game.rewardBounds(gameConfig).maxPointsPerPlayer,
-    walletCapWei: config.walletCapWei,
+    maxPointsPerPlayer,
+    walletCap: config.walletCap,
     pointsPerDollar: config.pointsPerDollar,
-    usdPerEth: config.usdPerEth,
+    usdPerSpendToken: config.usdPerEth,
   });
   if (!economy.ok) {
     throw new Error(
@@ -203,8 +324,46 @@ export async function startGate<Config, State, Event, Action, PublicView, Player
     signerPrivateKey: config.signerPrivateKey,
     spendGatedCalculator: config.deployment.spendGatedCalculator,
     sessionSecret: config.sessionSecret,
+    positionManager: config.deployment.positionManager,
+    flaunchVariant: config.deployment.flaunchVariant,
+    ...(config.deployment.poolSwap ? { poolSwap: config.deployment.poolSwap } : {}),
   });
 
+  // Each listed spend token: read what the chain says it is, and refuse an economy that does not
+  // fit its cap now, at boot, rather than at the first launch somebody has already paid for.
+  const announcedSpendTokens: AnnouncedSpendToken[] = [];
+  for (const pricing of config.spendTokens.values()) {
+    let symbol: string;
+    let decimals: number;
+    try {
+      [symbol, decimals] = await Promise.all([
+        client.readContract({ address: pricing.address, abi: erc20, functionName: 'symbol' }),
+        client.readContract({ address: pricing.address, abi: erc20, functionName: 'decimals' }).then(Number),
+      ]);
+    } catch {
+      throw new Error(`SPEND_TOKENS: ${pricing.address} does not answer symbol()/decimals() on chain ${config.chainId}`);
+    }
+    const fit = resolveEconomy({
+      maxPointsPerPlayer,
+      walletCap: pricing.walletCap,
+      pointsPerDollar: config.pointsPerDollar,
+      usdPerSpendToken: pricing.usdPerToken,
+      decimals,
+    });
+    if (!fit.ok) {
+      throw new Error(
+        `That economy does not work for ${symbol}: ${fit.problem}. Try ${fit.suggestedPointsPerDollar} points per dollar.`,
+      );
+    }
+    announcedSpendTokens.push({
+      address: pricing.address,
+      symbol,
+      decimals,
+      usdPerToken: pricing.usdPerToken,
+      walletCap: pricing.walletCap.toString(),
+    });
+  }
+
   const pool = new pg.Pool({ connectionString: config.databaseUrl });
   await migrate(pool);
 
@@ -217,14 +376,16 @@ export async function startGate<Config, State, Event, Action, PublicView, Player
     contracts: {
       positionManager: config.deployment.positionManager,
       spendGatedCalculator: config.deployment.spendGatedCalculator,
+      ...(config.deployment.poolSwap ? { poolSwap: config.deployment.poolSwap } : {}),
     },
     signer: signer.address,
     settler,
-    walletCapWei: config.walletCapWei.toString(),
+    walletCap: config.walletCap.toString(),
     roundDurationMs: config.roundDurationMs,
     minLobbyLeadMs: config.minLobbyLeadMs,
     gateEndsAtGraceS: config.gateEndsAtGraceS,
     flaunchVariant: config.deployment.flaunchVariant,
+    ...(announcedSpendTokens.length > 0 ? { spendTokens: announcedSpendTokens } : {}),
     requiresEoa: false,
     accepting: true,
     publicLaunchesOpen: true,
@@ -237,6 +398,7 @@ export async function startGate<Config, State, Event, Action, PublicView, Player
     config: gameConfig,
     pointsPerDollar: config.pointsPerDollar,
     usdPerEth: config.usdPerEth,
+    priceFor: priceList(config, overrides.priceProvider),
     sessions: new Sessions(config.sessionSecret, config.signInDomain, config.gateOrigin),
     claims: new Claims(pool, ledger, signer),
     discovery: new Discovery(client, {