@flayerlabs/gamemode-gate 0.5.5 → 0.6.0

package/src/chain/discover.ts

@@ -1,5 +1,6 @@
 import { encodeAbiParameters, keccak256, parseAbi, type PublicClient } from 'viem';
 import { ETH_SPEND_TOKEN, type SpendToken } from '@flayerlabs/gamemode-spec/live';
+import { checkPositionManagerWiring, type PositionManagerWiring } from './secure.js';
 
 /**
  * All this needs of a client: the ability to read a contract.
@@ -22,11 +23,15 @@ export type ChainReader = Pick<PublicClient, 'readContract'>;
  * can forge. So adoption needs no API key and no allowlist — anyone may ask, and the chain decides.
  * That single property is what makes third-party games permissionless.
  *
- * A gate serves exactly one (PositionManager, calculator) pair and adopts only coins launched on
- * THAT manager: `poolKey(coin)` is asked of the configured manager alone, so a coin on a superseded
- * generation of hooks (which keeps trading on its own gate) reads back as not a launch here. That
- * is deliberate — the EIP-712 domain binds every authorisation to the calculator, so a coin this
- * gate cannot sign for must not be given a room by it.
+ * A gate serves one calculator and adopts a coin on ANY PositionManager wired to it. The coin
+ * names its own manager (`Memecoin.flaunch()` is the launch ERC721, whose `positionManager()` is
+ * the hook), and that manager is accepted when its fee wiring routes to the gate's calculator —
+ * the same three reads boot makes of the primary manager, made here per manager and cached. There
+ * is no list: wiring a new manager to the dispatcher on chain is what approves it. A coin on a
+ * manager wired to some OTHER calculator is refused for good — the EIP-712 domain binds every
+ * authorisation to the calculator, so a coin this gate cannot sign for must not be given a room
+ * by it — and every later read (`poolKey`, `flaunchesAt`, `pairedToken`) is asked of the coin's
+ * own manager, never the configured one.
  */
 
 const poolKeyComponents = [
@@ -37,6 +42,12 @@ const poolKeyComponents = [
   { name: 'hooks', type: 'address' },
 ] as const;
 
+/** What a coin knows about its own launch: `flaunch()` is the ERC721 that minted it. */
+const memecoinAbi = parseAbi(['function flaunch() view returns (address)']);
+
+/** The launch ERC721 (`Flaunch`, `AnyFlaunch`) names the PositionManager that hooks its pools. */
+const flaunchAbi = parseAbi(['function positionManager() view returns (address)']);
+
 export const positionManagerAbi = [
   {
     type: 'function',
@@ -91,6 +102,11 @@ export interface Launch {
   name: string;
   symbol: string;
   imageUrl?: string | null;
+  /**
+   * The PositionManager the coin was launched on — the pool's hook — resolved from the coin
+   * itself. Absent only from hand-built launches (demos, tests), where it means the primary one.
+   */
+  positionManager?: `0x${string}`;
   /**
    * The token spend is measured in: the coin's paired token, read from the manager. Absent only
    * from hand-built launches (demos, tests), where it means ETH.
@@ -115,12 +131,122 @@ export interface Refused {
 export type LaunchCheck = ({ ok: true } & Launch) | Refused;
 
 export interface Deployment {
+  /**
+   * The primary manager: what boot asserted and `/config` announces. Adoption does not require a
+   * coin to be on it — see {@link verifyLaunch} — but it is the one manager known wired before any
+   * coin arrives, so its wiring is never asked of the chain again.
+   */
   positionManager: `0x${string}`;
   spendGatedCalculator: `0x${string}`;
   /** The signer this gate holds. A launch naming anyone else is not ours to run. */
   signer: `0x${string}`;
 }
 
+/**
+ * Whether a manager's fee wiring routes to a calculator. {@link checkPositionManagerWiring} is the
+ * one implementation; this is its shape, so a test can stand in for the chain.
+ */
+export type WiringCheck = (
+  client: ChainReader,
+  wiring: { positionManager: `0x${string}`; spendGatedCalculator: `0x${string}` },
+) => Promise<PositionManagerWiring>;
+
+/**
+ * Remembers which managers are wired to this gate's calculator, so the three wiring reads happen
+ * once per manager rather than once per coin.
+ *
+ * A yes is kept for the life of the process: wiring is a one-time owner action, and un-wiring a
+ * manager with live pools would also strand every coin already adopted on it, so nothing is lost
+ * by not re-asking. A no is kept a minute — long enough that a coin page polling an unwired
+ * manager is not a lever on the RPC, short enough that the owner wiring it up sees the gate follow.
+ */
+export class WiringCache {
+  private readonly verdicts = new Map<string, { verdict: PositionManagerWiring; until: number }>();
+  private readonly inFlight = new Map<string, Promise<PositionManagerWiring>>();
+
+  constructor(
+    private readonly check: WiringCheck = checkPositionManagerWiring,
+    private readonly now: () => number = Date.now,
+    private readonly negativeHoldMs = 60_000,
+  ) {}
+
+  async isWired(
+    client: ChainReader,
+    positionManager: `0x${string}`,
+    spendGatedCalculator: `0x${string}`,
+  ): Promise<PositionManagerWiring> {
+    const key = positionManager.toLowerCase();
+    const cached = this.verdicts.get(key);
+    if (cached && cached.until > this.now()) return cached.verdict;
+
+    const existing = this.inFlight.get(key);
+    if (existing) return existing;
+
+    const flight = this.check(client, { positionManager, spendGatedCalculator })
+      .then((verdict) => {
+        const until = verdict.ok ? Number.POSITIVE_INFINITY : this.now() + this.negativeHoldMs;
+        this.verdicts.set(key, { verdict, until });
+        return verdict;
+      })
+      .finally(() => this.inFlight.delete(key));
+    this.inFlight.set(key, flight);
+    return flight;
+  }
+
+  /** A fresh cache that already trusts the primary manager, which boot asserted before any coin arrived. */
+  static trusting(positionManager: `0x${string}`): WiringCache {
+    const cache = new WiringCache();
+    cache.trust(positionManager);
+    return cache;
+  }
+
+  /** Record a manager known wired without asking — the primary one, which boot already asserted. */
+  trust(positionManager: `0x${string}`, dispatcher: `0x${string}` = ZERO_ADDRESS): void {
+    this.verdicts.set(positionManager.toLowerCase(), {
+      verdict: { ok: true, dispatcher },
+      until: Number.POSITIVE_INFINITY,
+    });
+  }
+}
+
+/**
+ * Which PositionManager a coin was launched on, from the coin itself.
+ *
+ * Two reads: `Memecoin.flaunch()` names the launch ERC721 that minted the coin, and that contract's
+ * `positionManager()` names the hook. Both are public state written at launch, so the answer is the
+ * coin's and cannot be steered by whoever offers it for adoption. Null when the CONTRACT says no —
+ * an address with no code, or one that is not a Flaunch coin, answers `flaunch()` with no data.
+ * An RPC that did not answer is not a statement about the coin, so that is thrown to the caller
+ * rather than folded into null.
+ */
+export async function resolvePositionManager(
+  client: ChainReader,
+  memecoin: `0x${string}`,
+): Promise<`0x${string}` | null> {
+  let flaunch: `0x${string}`;
+  try {
+    flaunch = (await client.readContract({ address: memecoin, abi: memecoinAbi, functionName: 'flaunch' })) as `0x${string}`;
+  } catch (error) {
+    if (isMissingFunction(error)) return null;
+    throw error;
+  }
+  if (!flaunch || flaunch.toLowerCase() === ZERO_ADDRESS) return null;
+
+  let manager: `0x${string}`;
+  try {
+    manager = (await client.readContract({
+      address: flaunch,
+      abi: flaunchAbi,
+      functionName: 'positionManager',
+    })) as `0x${string}`;
+  } catch (error) {
+    if (isMissingFunction(error)) return null;
+    throw error;
+  }
+  if (!manager || manager.toLowerCase() === ZERO_ADDRESS) return null;
+  return manager;
+}
+
 export function poolIdOf(key: PoolKey): `0x${string}` {
   return keccak256(
     encodeAbiParameters(
@@ -142,11 +268,28 @@ export async function verifyLaunch(
   client: ChainReader,
   deployment: Deployment,
   memecoin: `0x${string}`,
+  wiring: WiringCache = WiringCache.trusting(deployment.positionManager),
 ): Promise<LaunchCheck> {
+  // The coin's own manager first. A coin the protocol has never heard of has no `flaunch()`, which
+  // is still "not yet": the coin page loads the instant a launch is submitted, before the chain has
+  // caught up, and that must not be remembered as "no".
+  let positionManager: `0x${string}` | null;
+  try {
+    positionManager = await resolvePositionManager(client, memecoin);
+  } catch {
+    return refuse('launch.unreadable', true);
+  }
+  if (!positionManager) return refuse('launch.not_flaunched', true);
+
+  // Approval is a fact about the chain: is this manager's fee wiring routed to OUR calculator? A
+  // manager wired elsewhere is another gate's, permanently — no amount of waiting rewires it.
+  const wired = await wiring.isWired(client, positionManager, deployment.spendGatedCalculator);
+  if (!wired.ok) return refuse('launch.unapproved_position_manager', false);
+
   let poolKey: PoolKey;
   try {
     poolKey = (await client.readContract({
-      address: deployment.positionManager,
+      address: positionManager,
       abi: positionManagerAbi,
       functionName: 'poolKey',
       args: [memecoin],
@@ -164,9 +307,8 @@ export async function verifyLaunch(
 
   let settings: readonly [boolean, bigint, `0x${string}`, bigint];
   let trusted: readonly [`0x${string}`, boolean];
-  let flaunchesAt: bigint;
   try {
-    [settings, trusted, flaunchesAt] = (await Promise.all([
+    [settings, trusted] = (await Promise.all([
       client.readContract({
         address: deployment.spendGatedCalculator,
         abi: spendGatedAbi,
@@ -179,17 +321,27 @@ export async function verifyLaunch(
         functionName: 'trustedPoolKeySigner',
         args: [poolId],
       }),
-      client.readContract({
-        address: deployment.positionManager,
-        abi: positionManagerAbi,
-        functionName: 'flaunchesAt',
-        args: [poolId],
-      }),
-    ])) as [typeof settings, typeof trusted, bigint];
+    ])) as [typeof settings, typeof trusted];
   } catch {
     return refuse('launch.unreadable', true);
   }
 
+  // The window's open is the manager's to report. A manager that is wired but has no
+  // `flaunchesAt` is a generation this gate has no round model for — a permanent fact about the
+  // contract, not an outage, so it is refused as unsupported rather than as unreadable and retried
+  // forever.
+  let flaunchesAt: bigint;
+  try {
+    flaunchesAt = (await client.readContract({
+      address: positionManager,
+      abi: positionManagerAbi,
+      functionName: 'flaunchesAt',
+      args: [poolId],
+    })) as bigint;
+  } catch (error) {
+    return refuse(isMissingFunction(error) ? 'launch.unsupported_position_manager' : 'launch.unreadable', !isMissingFunction(error));
+  }
+
   const [enabled, walletCap, , endsAt] = settings;
   const [signer, signerEnabled] = trusted;
 
@@ -204,7 +356,7 @@ export async function verifyLaunch(
   const closesAt = Number(endsAt) * 1000;
   if (closesAt <= Date.now()) return refuse('launch.already_over', false);
 
-  const spendToken = await resolveSpendToken(client, deployment, memecoin, poolKey, poolId);
+  const spendToken = await resolveSpendToken(client, positionManager, memecoin, poolKey, poolId);
   if (!spendToken) return refuse('launch.paired_unreadable', true);
 
   let name = '';
@@ -231,9 +383,38 @@ export async function verifyLaunch(
     name,
     symbol,
     spendToken,
+    positionManager,
   };
 }
 
+/**
+ * Did a read fail because the contract has no such function, rather than because the chain did
+ * not answer? viem reports the former as a call that returned no data or reverted at the
+ * contract (`ContractFunctionZeroDataError`, `ContractFunctionRevertedError`); a transport
+ * failure looks nothing like it, and a `view` that exists does not revert on a pool id.
+ */
+function isMissingFunction(error: unknown): boolean {
+  const seen = new Set<unknown>();
+  let current: unknown = error;
+  while (current && typeof current === 'object' && !seen.has(current)) {
+    seen.add(current);
+    const name = (current as { name?: unknown }).name;
+    if (
+      name === 'ContractFunctionZeroDataError' ||
+      name === 'AbiDecodingZeroDataError' ||
+      name === 'ContractFunctionRevertedError'
+    ) {
+      return true;
+    }
+    const message = (current as { message?: unknown }).message;
+    if (typeof message === 'string' && /returned no data|zero data|function (selector )?was not (recognized|found)/i.test(message)) {
+      return true;
+    }
+    current = (current as { cause?: unknown }).cause;
+  }
+  return false;
+}
+
 /**
  * Which token this pool's spend is measured in.
  *
@@ -246,7 +427,7 @@ export async function verifyLaunch(
  */
 async function resolveSpendToken(
   client: ChainReader,
-  deployment: Deployment,
+  positionManager: `0x${string}`,
   memecoin: `0x${string}`,
   poolKey: PoolKey,
   poolId: `0x${string}`,
@@ -254,7 +435,7 @@ async function resolveSpendToken(
   let paired: `0x${string}`;
   try {
     paired = (await client.readContract({
-      address: deployment.positionManager,
+      address: positionManager,
       abi: positionManagerAbi,
       functionName: 'pairedToken',
       args: [poolId],
@@ -278,7 +459,7 @@ async function resolveSpendToken(
 /**
  * Verification with a memory, because every coin-page view asks.
  *
- * Unmemoised, each call costs five chain reads against one endpoint from one address — which is a
+ * Unmemoised, each call costs seven chain reads against one endpoint from one address — which is a
  * free denial-of-service lever, and public endpoints rate-limit long before a launch does.
  *
  * A positive verdict is cached until the window closes, because a launch that qualifies cannot
@@ -288,12 +469,22 @@ async function resolveSpendToken(
 export class Discovery {
   private readonly verdicts = new Map<string, { verdict: LaunchCheck; until: number }>();
   private readonly inFlight = new Map<string, Promise<LaunchCheck>>();
+  /**
+   * Which managers are wired to this gate's calculator, remembered per manager. The primary one is
+   * trusted from the start: boot asserted it, and asking again would be the only three reads that
+   * could never answer differently.
+   */
+  readonly wiring: WiringCache;
 
   constructor(
     private readonly client: ChainReader,
     private readonly deployment: Deployment,
     private readonly now: () => number = Date.now,
-  ) {}
+    wiring: WiringCache = new WiringCache(checkPositionManagerWiring, now),
+  ) {
+    this.wiring = wiring;
+    this.wiring.trust(deployment.positionManager);
+  }
 
   async verify(memecoin: `0x${string}`): Promise<LaunchCheck> {
     const key = memecoin.toLowerCase();
@@ -305,7 +496,7 @@ export class Discovery {
     const existing = this.inFlight.get(key);
     if (existing) return existing;
 
-    const flight = verifyLaunch(this.client, this.deployment, memecoin)
+    const flight = verifyLaunch(this.client, this.deployment, memecoin, this.wiring)
       .then((verdict) => {
         this.verdicts.set(key, { verdict, until: this.now() + this.holdFor(verdict) });
         return verdict;

package/src/chain/registry-prices.ts

@@ -0,0 +1,194 @@
+import { formatUnits, parseAbi, type PublicClient } from 'viem';
+import type { SpendToken } from '@flayerlabs/gamemode-spec/live';
+import type { AnnouncedSpendToken, PriceFor } from '../server.js';
+import { resolveEconomy, unitsPerToken } from '../economy.js';
+
+/**
+ * Prices for any paired token the chain itself has approved, so a gate runs rounds on every
+ * pairing the protocol allows without anyone listing it first.
+ *
+ * A v1.3 PositionManager names its `PairedTokenRegistry`, and the registry names the price
+ * calculator each approved token was registered with — the same quote a launch uses to size a
+ * coin's starting price. That calculator answers "how many tokens is one ETH", and the operator's
+ * `USD_PER_ETH` turns that into dollars. Nothing here is typed by a person: an unapproved token has
+ * no calculator and is refused, exactly as the launch itself would be.
+ *
+ * Quotes are cached briefly. Adoption happens once per launch, so the cache protects the RPC from a
+ * burst of `/config/spend-tokens` reads by launch tooling, not from adoption itself. A quote that
+ * cannot be read throws, and the server answers adoption with 503 rather than a made-up price.
+ */
+
+const managerAbi = parseAbi(['function pairedTokenRegistry() view returns (address)']);
+const registryAbi = parseAbi([
+  'function isApproved(address token) view returns (bool)',
+  'function tokenConfig(address token) view returns ((bool approved, uint8 tokenType, uint8 decimals, address underlying, address feeEscrow, address priceCalculator, uint256 minDistribute, uint256 bidWallThreshold))',
+]);
+const calculatorAbi = parseAbi(['function ethToPairedToken(uint256 ethAmount) view returns (uint256)']);
+const erc20Abi = parseAbi(['function symbol() view returns (string)', 'function decimals() view returns (uint8)']);
+
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+
+/** The subset of a viem public client this module needs, so tests can script it. */
+export type RegistryReader = Pick<PublicClient, 'readContract'>;
+
+export interface RegistryPricesOptions {
+  /** The manager whose registry decides which pairings exist. */
+  positionManager: `0x${string}`;
+  /** The chain's flETH wrapper, priced as ETH and never asked of the registry. */
+  fleth?: `0x${string}`;
+  /** Dollars per ETH; every registry quote is in ETH. */
+  usdPerEth: number;
+  /** How long a quote is reused, in milliseconds. */
+  ttlMs?: number;
+  /** Injectable for tests. */
+  now?: () => number;
+}
+
+export interface RegistryQuote {
+  /** Dollars per whole token, to eight significant digits. */
+  usdPerToken: number;
+  /** Whole tokens per ETH as the registry's calculator quoted them. */
+  tokensPerEth: number;
+  priceCalculator: `0x${string}`;
+}
+
+/** What `/config/spend-tokens/:address` needs to size a launch's cap. */
+export interface AnnounceOptions {
+  maxPointsPerPlayer: number;
+  pointsPerDollar: number;
+  /** Percent added over the smallest cap a flawless round fits under. */
+  headroomPercent: number;
+}
+
+export class RegistryPrices {
+  private registry: Promise<`0x${string}` | null> | undefined;
+  private readonly quotes = new Map<string, { quote: RegistryQuote | null; at: number }>();
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+
+  constructor(
+    private readonly client: RegistryReader,
+    private readonly options: RegistryPricesOptions,
+  ) {
+    this.ttlMs = options.ttlMs ?? 60_000;
+    this.now = options.now ?? Date.now;
+  }
+
+  /**
+   * The registry the manager names, or null for a manager that predates paired tokens. Read once:
+   * the address is immutable on chain, and a gate serves exactly one manager.
+   */
+  registryAddress(): Promise<`0x${string}` | null> {
+    this.registry ??= this.client
+      .readContract({ address: this.options.positionManager, abi: managerAbi, functionName: 'pairedTokenRegistry' })
+      .then((address) => (address.toLowerCase() === ZERO_ADDRESS ? null : address))
+      .catch(() => null);
+    return this.registry;
+  }
+
+  /** ETH by any name is the operator's `USD_PER_ETH`; it is never asked of the registry. */
+  private isEthEquivalent(address: string): boolean {
+    const lower = address.toLowerCase();
+    return lower === ZERO_ADDRESS || (this.options.fleth !== undefined && lower === this.options.fleth.toLowerCase());
+  }
+
+  /**
+   * The registry's quote for a token, or null when it is not approved or has no calculator.
+   * Throws when the chain cannot be read, so a caller refuses for now rather than for good.
+   */
+  async quote(address: string): Promise<RegistryQuote | null> {
+    const key = address.toLowerCase();
+    const cached = this.quotes.get(key);
+    if (cached && this.now() - cached.at < this.ttlMs) return cached.quote;
+    const quote = await this.read(address as `0x${string}`);
+    this.quotes.set(key, { quote, at: this.now() });
+    return quote;
+  }
+
+  private async read(token: `0x${string}`): Promise<RegistryQuote | null> {
+    const registry = await this.registryAddress();
+    if (!registry) return null;
+    const approved = await this.client.readContract({ address: registry, abi: registryAbi, functionName: 'isApproved', args: [token] });
+    if (!approved) return null;
+    const config = await this.client.readContract({ address: registry, abi: registryAbi, functionName: 'tokenConfig', args: [token] });
+    const priceCalculator = config.priceCalculator;
+    if (!priceCalculator || priceCalculator.toLowerCase() === ZERO_ADDRESS) return null;
+    const decimals = Number(config.decimals);
+    const perEth = await this.client.readContract({
+      address: priceCalculator,
+      abi: calculatorAbi,
+      functionName: 'ethToPairedToken',
+      args: [unitsPerToken(18)],
+    });
+    if (perEth <= 0n) return null;
+    // String-based division: no binary float noise in a whole-token quote.
+    const tokensPerEth = Number(formatUnits(perEth, decimals));
+    if (!Number.isFinite(tokensPerEth) || tokensPerEth <= 0) return null;
+    const usdPerToken = Number((this.options.usdPerEth / tokensPerEth).toPrecision(8));
+    return { usdPerToken, tokensPerEth, priceCalculator };
+  }
+
+  /** A {@link PriceFor}: dollars per whole token for any approved pairing, null for the rest. */
+  priceFor: PriceFor = async (token: SpendToken) => {
+    if (this.isEthEquivalent(token.address)) return null;
+    const quote = await this.quote(token.address);
+    return quote?.usdPerToken ?? null;
+  };
+
+  /**
+   * The entry launch tooling needs before a coin is paid for: the token as the chain describes
+   * it, the price the gate will fix a round at, and the smallest per-wallet cap a flawless round
+   * fits under plus the operator's headroom. Null for a token the registry does not approve.
+   */
+  async announce(address: `0x${string}`, options: AnnounceOptions): Promise<AnnouncedSpendToken | null> {
+    if (this.isEthEquivalent(address)) return null;
+    const quote = await this.quote(address);
+    if (!quote) return null;
+    const [symbol, decimals] = await Promise.all([
+      this.client.readContract({ address, abi: erc20Abi, functionName: 'symbol' }),
+      this.client.readContract({ address, abi: erc20Abi, functionName: 'decimals' }).then(Number),
+    ]);
+    const walletCap = minimumWalletCap(quote.usdPerToken, decimals, options);
+    if (walletCap === null) return null;
+    return {
+      address,
+      symbol,
+      decimals,
+      usdPerToken: quote.usdPerToken,
+      walletCap: withHeadroom(walletCap, options.headroomPercent).toString(),
+    };
+  }
+}
+
+/**
+ * The smallest per-wallet cap under which a flawless round fits, in the token's base units, or
+ * null when no cap makes the economy work at this price. Checked against {@link resolveEconomy}
+ * rather than trusted, because that function is the one place the rule is written down.
+ */
+export function minimumWalletCap(
+  usdPerToken: number,
+  decimals: number,
+  options: Pick<AnnounceOptions, 'maxPointsPerPlayer' | 'pointsPerDollar'>,
+): bigint | null {
+  const pointsPerToken = Math.round(usdPerToken * options.pointsPerDollar);
+  if (pointsPerToken <= 0) return null;
+  const unitsPerPoint = unitsPerToken(decimals) / BigInt(pointsPerToken);
+  if (unitsPerPoint <= 0n) return null;
+  const minimum = BigInt(Math.floor(options.maxPointsPerPlayer)) * unitsPerPoint;
+  const fit = resolveEconomy({
+    maxPointsPerPlayer: options.maxPointsPerPlayer,
+    walletCap: minimum,
+    pointsPerDollar: options.pointsPerDollar,
+    usdPerSpendToken: usdPerToken,
+    decimals,
+  });
+  return fit.ok ? minimum : null;
+}
+
+/** A cap with the operator's percentage headroom, rounded down to base units. */
+export function withHeadroom(cap: bigint, headroomPercent: number): bigint {
+  if (!Number.isSafeInteger(headroomPercent) || headroomPercent < 0) {
+    throw new Error('headroom percent must be a non-negative integer');
+  }
+  return (cap * BigInt(100 + headroomPercent)) / 100n;
+}