402-trinity-gaming 0.1.0

package/src/budget-file.ts

@@ -0,0 +1,314 @@
+/**
+ * File-backed durable budget store. OPTIONAL - not part of the core, so it does not
+ * count against the wrapper's footprint. Import it only if you want one.
+ *
+ * Needs no Cloudflare, no database, no network. Works anywhere Node/Bun/Deno runs:
+ * your laptop, a VPS, a Raspberry Pi, a robotics controller.
+ *
+ *     import { createX402Fetch } from './x402.ts';
+ *     import { createFileBudgetStore } from './budget-file.ts';
+ *
+ *     const x402Fetch = createX402Fetch({
+ *       privateKey: process.env.X402_PRIVATE_KEY,
+ *       policy: { maxAmountPerRequest: '5000', totalBudget: '1000000', allowNetworks: ['base'] },
+ *       budgetStore: createFileBudgetStore('./.x402-budget.json'),
+ *     });
+ *
+ * The spend total survives process restarts, which is the entire point: an in-memory
+ * budget resets every time the process starts, so on mainnet it caps nothing.
+ *
+ * Concurrency: uses an exclusive lock file (O_EXCL), so multiple processes on the same
+ * machine cannot both pass the same check. It does NOT coordinate across machines - for
+ * that, back the same interface with Redis/Postgres/Workers KV instead.
+ */
+import { openSync, closeSync, unlinkSync, readFileSync, writeFileSync, renameSync, existsSync } from 'node:fs';
+
+export interface BudgetStore {
+  reserve: (amount: bigint, totalBudget: bigint) => Promise<boolean>;
+  release?: (amount: bigint) => Promise<void>;
+  /** Current spend, for reporting. */
+  spent: () => bigint;
+}
+
+const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
+
+export function createFileBudgetStore(path: string, opts: { lockTimeoutMs?: number } = {}): BudgetStore {
+  const lockPath = path + '.lock';
+  const timeout = opts.lockTimeoutMs ?? 5000;
+
+  const read = (): bigint => {
+    if (!existsSync(path)) return 0n;
+    try {
+      const j = JSON.parse(readFileSync(path, 'utf8'));
+      const v = BigInt(j.spent ?? '0');
+      return v < 0n ? 0n : v;
+    } catch {
+      // A corrupt ledger must NOT read as zero - that would silently reset the budget
+      // and re-open unlimited spending. Fail closed instead.
+      throw new Error(`x402 budget file is unreadable: ${path}. Refusing to treat it as zero spend.`);
+    }
+  };
+
+  const write = (v: bigint): void => {
+    const tmp = path + '.tmp';
+    writeFileSync(tmp, JSON.stringify({ spent: v.toString(), updated: new Date().toISOString() }));
+    renameSync(tmp, path);        // atomic replace on the same filesystem
+  };
+
+  async function withLock<T>(fn: () => T): Promise<T> {
+    const deadline = Date.now() + timeout;
+    let fd: number | undefined;
+    for (;;) {
+      try { fd = openSync(lockPath, 'wx'); break; }        // O_CREAT|O_EXCL - one winner
+      catch {
+        if (Date.now() > deadline) throw new Error(`x402 budget lock timed out: ${lockPath}`);
+        await sleep(15);
+      }
+    }
+    try { return fn(); }
+    finally {
+      try { closeSync(fd!); } catch { /* already closed */ }
+      try { unlinkSync(lockPath); } catch { /* already gone */ }
+    }
+  }
+
+  return {
+    /** Atomic check-and-increment. Returns false if the payment would exceed the budget. */
+    reserve: (amount, totalBudget) => withLock(() => {
+      const now = read();
+      if (now + amount > totalBudget) return false;
+      write(now + amount);
+      return true;
+    }),
+    release: (amount) => withLock(() => {
+      const now = read();
+      write(now - amount < 0n ? 0n : now - amount);
+    }),
+    spent: () => read(),
+  };
+}
+
+
+/**
+ * File-backed fee tally. Node-only, same atomic-rename pattern. `accrued` is ATOMIC x 1e6
+ * so sub-unit fees are not rounded away; `count` is payments since the last settlement.
+ */
+export function createFileFeeStore(path: string, opts: { lockTimeoutMs?: number } = {}) {
+  const lockPath = path + '.lock';
+  const timeout = opts.lockTimeoutMs ?? 5000;
+
+  const read = (): { accrued: bigint; count: bigint } => {
+    if (!existsSync(path)) return { accrued: 0n, count: 0n };
+    try {
+      const j = JSON.parse(readFileSync(path, 'utf8'));
+      return { accrued: BigInt(j.accruedScaled ?? '0'), count: BigInt(j.count ?? '0') };
+    } catch {
+      // Never read a corrupt tally as zero - that silently discards fees already owed.
+      throw new Error(`x402 fee tally is unreadable: ${path}. Refusing to treat it as zero.`);
+    }
+  };
+
+  const write = (v: { accrued: bigint; count: bigint }): void => {
+    const tmp = path + '.tmp';
+    writeFileSync(tmp, JSON.stringify({
+      accruedScaled: v.accrued.toString(), count: v.count.toString(),
+      updated: new Date().toISOString(),
+    }));
+    renameSync(tmp, path);
+  };
+
+  async function withLock<T>(fn: () => T): Promise<T> {
+    const deadline = Date.now() + timeout;
+    let fd: number | undefined;
+    for (;;) {
+      try { fd = openSync(lockPath, 'wx'); break; }        // O_CREAT|O_EXCL - one winner
+      catch {
+        if (Date.now() > deadline) throw new Error(`x402 fee lock timed out: ${lockPath}`);
+        await sleep(15);
+      }
+    }
+    try { return fn(); }
+    finally {
+      try { closeSync(fd!); } catch { /* already closed */ }
+      try { unlinkSync(lockPath); } catch { /* already gone */ }
+    }
+  }
+
+  return {
+    get: async () => withLock(read),
+    set: async (v: { accrued: bigint; count: bigint }) => { await withLock(() => write(v)); },
+    /**
+     * Read, modify and write while HOLDING the lock. Separate get/set calls each take the
+     * lock and release it, so two processes can both read the same count and both write
+     * count+1 - one increment vanishes. Measured at 82% loss with eight concurrent writers,
+     * which shows up as the fee firing far less often than it is owed.
+     */
+    update: async (fn: (cur: { accrued: bigint; count: bigint }) => { accrued: bigint; count: bigint }) =>
+      withLock(() => { const next = fn(read()); write(next); return next; }),
+  };
+}
+
+/**
+ * File-backed collector queue. Node-only. Keeps pending authorizations and the set of
+ * nonces ever seen, so a replay is rejected even across restarts.
+ */
+export function createFileCollectorStore(path: string) {
+  const read = () => {
+    if (!existsSync(path)) return { pending: [] as any[], seen: [] as string[] };
+    try { return JSON.parse(readFileSync(path, 'utf8')); }
+    catch {
+      // Reading a corrupt queue as empty would forget owed fees AND re-open replay.
+      throw new Error(`x402 collector store is unreadable: ${path}. Refusing to treat it as empty.`);
+    }
+  };
+  const write = (d: any) => {
+    const tmp = path + '.tmp';
+    writeFileSync(tmp, JSON.stringify(d));
+    renameSync(tmp, path);
+  };
+  return {
+    pending: async () => read().pending ?? [],
+    add: async (item: any) => { const d = read(); d.pending = [...(d.pending ?? []), item]; write(d); },
+    remove: async (nonces: string[]) => {
+      const d = read();
+      const drop = new Set(nonces.map(n => n.toLowerCase()));
+      d.pending = (d.pending ?? []).filter((i: any) => !drop.has(i.authorization.nonce.toLowerCase()));
+      write(d);
+    },
+    seen: async (nonce: string) => (read().seen ?? []).includes(nonce.toLowerCase()),
+    markSeen: async (nonce: string) => {
+      const d = read();
+      d.seen = [...(d.seen ?? []), nonce.toLowerCase()];
+      write(d);
+    },
+  };
+}
+
+/**
+ * File-backed replay guard for the seller. Node-only.
+ *
+ * Remembers each settled authorization nonce only until it expires - after `validBefore`
+ * the authorization can never settle again, so the entry is prunable. Without that, a
+ * long-running seller's guard grows forever.
+ */
+export function createFileNonceStore(path: string) {
+  const read = (): Record<string, number> => {
+    if (!existsSync(path)) return {};
+    try { return JSON.parse(readFileSync(path, 'utf8')).nonces ?? {}; }
+    catch {
+      // Reading a corrupt guard as empty would re-open replay of every settled payment.
+      throw new Error(`x402 nonce store is unreadable: ${path}. Refusing to treat it as empty.`);
+    }
+  };
+  const write = (n: Record<string, number>) => {
+    const tmp = path + '.tmp';
+    writeFileSync(tmp, JSON.stringify({ nonces: n, updated: new Date().toISOString() }));
+    renameSync(tmp, path);
+  };
+  return {
+    seen: async (nonce: string): Promise<boolean> => {
+      const now = Math.floor(Date.now() / 1000);
+      const exp = read()[nonce.toLowerCase()];
+      return exp !== undefined && exp > now;
+    },
+    add: async (nonce: string, expiresAtUnix: number): Promise<void> => {
+      const now = Math.floor(Date.now() / 1000);
+      const n = read();
+      for (const [k, exp] of Object.entries(n)) if (exp <= now) delete n[k];   // prune
+      n[nonce.toLowerCase()] = expiresAtUnix;
+      write(n);
+    },
+    /** Entries currently held (after pruning expired ones). */
+    size: (): number => {
+      const now = Math.floor(Date.now() / 1000);
+      return Object.values(read()).filter(e => e > now).length;
+    },
+  };
+}
+
+/**
+ * File-backed tab ledger. Node-only, same atomic-rename and lock pattern as the fee tally.
+ *
+ * WHY THIS EXISTS. A tab is money a player has already paid. Holding that balance only in
+ * process memory means a deploy, a crash or a scale-down silently deletes credit somebody
+ * bought - and unlike a failed payment, nothing fails loudly when it happens.
+ *
+ * Single-instance only. If more than one game server can serve the same player, back the
+ * ledger with your database instead and hold a row lock across the read and the write - the
+ * `update` contract below is what that lock has to protect.
+ */
+export function createFileLedgerStore(path: string, opts: { lockTimeoutMs?: number } = {}) {
+  const lockPath = path + '.lock';
+  const timeout = opts.lockTimeoutMs ?? 5000;
+
+  type Row = {
+    playerAddress: string; remaining: string; opened: string;
+    spent: Array<{ id: string; at: number }>; updatedAt: string;
+  };
+
+  const readAll = (): Record<string, Row> => {
+    if (!existsSync(path)) return {};
+    try { return JSON.parse(readFileSync(path, 'utf8')); }
+    catch {
+      // Reading a corrupt ledger as empty would erase every player's paid-for credit.
+      throw new Error(`x402 tab ledger unreadable: ${path} - fix or remove it deliberately`);
+    }
+  };
+
+  const writeAll = (all: Record<string, Row>): void => {
+    const tmp = path + '.tmp';
+    writeFileSync(tmp, JSON.stringify(all));
+    renameSync(tmp, path);
+  };
+
+  async function withLock<T>(fn: () => T): Promise<T> {
+    const deadline = Date.now() + timeout;
+    let fd: number | undefined;
+    for (;;) {
+      try { fd = openSync(lockPath, 'wx'); break; }
+      catch {
+        if (Date.now() > deadline) throw new Error(`x402 tab ledger lock timed out: ${lockPath}`);
+        await sleep(15);
+      }
+    }
+    try { return fn(); }
+    finally {
+      try { closeSync(fd!); } catch { /* already closed */ }
+      try { unlinkSync(lockPath); } catch { /* already gone */ }
+    }
+  }
+
+  // Spent action ids exist to catch a client retry, which happens within seconds. Keeping
+  // them by AGE rather than by count means a long-lived tab cannot quietly forget an id and
+  // charge for it twice, and a busy one cannot grow without bound.
+  const KEEP_MS = 24 * 60 * 60 * 1000;
+  const prune = (spent: Array<{ id: string; at: number }>) => {
+    const cutoff = Date.now() - KEEP_MS;
+    const kept = spent.filter(e => e.at > cutoff);
+    return kept.length > 5000 ? kept.slice(-5000) : kept;
+  };
+
+  return {
+    get: async (playerId: string) => withLock(() => readAll()[playerId] ?? null),
+    set: async (playerId: string, s: any) => {
+      await withLock(() => {
+        const all = readAll();
+        all[playerId] = { ...s, spent: prune(s.spent ?? []) };
+        writeAll(all);
+      });
+    },
+    /**
+     * Read, modify and write while HOLDING the lock. Separate get/set calls each take and
+     * release it, so two writers can both read the same balance and both approve a spend it
+     * could only cover once.
+     */
+    update: async (playerId: string, fn: (cur: any) => any) =>
+      withLock(() => {
+        const all = readAll();
+        const next = fn(all[playerId] ?? null);
+        all[playerId] = { ...next, spent: prune(next.spent ?? []) };
+        writeAll(all);
+        return all[playerId];
+      }),
+  };
+}

package/src/evm-tx.ts

@@ -0,0 +1,244 @@
+/**
+ * x402-trinity/evm-tx - sign and submit EIP-1559 transactions, plus signature recovery.
+ *
+ * OPTIONAL server-side module. The buyer core never needs this: it produces signed
+ * authorizations and hands them over. This is for whoever SUBMITS them - a facilitator,
+ * a collector, or anything else that puts transactions on a chain.
+ *
+ * Zero dependencies: RLP, EIP-1559 encoding and ecrecover are all inline.
+ */
+import { keccak256, toHex, fromHex, __internals } from './x402.ts';
+
+type Jac = [bigint, bigint, bigint];
+// Typed rather than `as any`: the curve constants must stay bigint or arithmetic below
+// silently degrades to number and stops type-checking.
+const {
+  toBig, beBytes, signWith, makeNonce, addressOf, jMul, jAdd, affine, G, N, P,
+} = __internals as unknown as {
+  toBig: (b: Uint8Array) => bigint;
+  beBytes: (v: bigint, len: number) => Uint8Array;
+  signWith: (nonce: unknown, z: bigint, d: bigint) => string;
+  makeNonce: () => unknown;
+  addressOf: (d: bigint) => string;
+  jMul: (k: bigint, p: Jac) => Jac;
+  jAdd: (a: Jac, b: Jac) => Jac;
+  affine: (p: Jac) => [bigint, bigint];
+  G: Jac; N: bigint; P: bigint;
+};
+
+/* ------------------------------- RLP ------------------------------- */
+
+const cat = (...a: Uint8Array[]): Uint8Array => {
+  const t = new Uint8Array(a.reduce((n, x) => n + x.length, 0));
+  let o = 0;
+  for (const x of a) { t.set(x, o); o += x.length; }
+  return t;
+};
+/** integer -> minimal big-endian bytes; zero is the empty string, per RLP */
+const minimal = (v: bigint): Uint8Array => {
+  if (v === 0n) return new Uint8Array(0);
+  let h = v.toString(16);
+  if (h.length % 2) h = '0' + h;
+  return fromHex('0x' + h);
+};
+const rlpLen = (len: number, offset: number): Uint8Array => {
+  if (len < 56) return new Uint8Array([offset + len]);
+  const lb = minimal(BigInt(len));
+  return cat(new Uint8Array([offset + 55 + lb.length]), lb);
+};
+type RlpInput = Uint8Array | RlpInput[];
+export function rlp(x: RlpInput): Uint8Array {
+  if (Array.isArray(x)) {
+    const payload = cat(...x.map(rlp));
+    return cat(rlpLen(payload.length, 0xc0), payload);
+  }
+  if (x.length === 1 && x[0] < 0x80) return x;
+  return cat(rlpLen(x.length, 0x80), x);
+}
+
+/* --------------------------- ecrecover --------------------------- */
+
+const mod = (a: bigint, m: bigint): bigint => { const r = a % m; return r < 0n ? r + m : r; };
+const modPow = (b: bigint, e: bigint, m: bigint): bigint => {
+  let r = 1n; b = mod(b, m);
+  while (e > 0n) { if (e & 1n) r = mod(r * b, m); b = mod(b * b, m); e >>= 1n; }
+  return r;
+};
+const inv = (a: bigint, m: bigint): bigint => {
+  let r = m, nr = mod(a, m), s = 0n, ns = 1n;
+  while (nr !== 0n) { const q = r / nr; [r, nr] = [nr, r - q * nr]; [s, ns] = [ns, s - q * ns]; }
+  return mod(s, m);
+};
+
+/**
+ * Recover the signing address from a digest and a 65-byte r||s||v signature.
+ * This is exactly what EIP-3009 does on-chain, so it is the right local check before
+ * spending gas submitting something that would revert.
+ */
+export function recoverSigner(digest: bigint, signature: string): string | null {
+  try {
+    const sig = fromHex(signature);
+    if (sig.length !== 65) return null;
+    const r = toBig(sig.slice(0, 32)), s = toBig(sig.slice(32, 64)), v = sig[64] - 27;
+    if (r === 0n || r >= N || s === 0n || s >= N || v < 0 || v > 3) return null;
+    const x = r + (v >> 1 ? N : 0n);
+    if (x >= P) return null;
+    let y = modPow(mod(x * x * x + 7n, P), (P + 1n) / 4n, P);
+    if (mod(y * y, P) !== mod(x * x * x + 7n, P)) return null;   // not on the curve
+    if ((y & 1n) !== BigInt(v & 1)) y = P - y;
+    const Q = jMul(inv(r, N), jAdd(jMul(s, [x, y, 1n]), jMul(mod(-digest, N), G)));
+    if (Q[2] === 0n) return null;
+    const xy = affine(Q);
+    return toHex(keccak256(beBytes(xy[0], 32), beBytes(xy[1], 32)).slice(12));
+  } catch {
+    return null;
+  }
+}
+
+/* --------------------------- JSON-RPC --------------------------- */
+
+export interface RpcConfig { urls: string[]; timeoutMs?: number; retries?: number }
+
+export function createRpc(cfg: RpcConfig) {
+  const urls = cfg.urls;
+  const timeoutMs = cfg.timeoutMs ?? 15000;
+  const retries = cfg.retries ?? 3;
+  if (!urls.length) throw new Error('evm-tx: at least one RPC url is required');
+
+  return async function rpc(method: string, params: unknown[] = []): Promise<any> {
+    let last: unknown;
+    for (let attempt = 0; attempt < retries; attempt++) {
+      for (const url of urls) {
+        try {
+          const r = await fetch(url, {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+            signal: AbortSignal.timeout(timeoutMs),
+          });
+          const j = await r.json();
+          if (j.error) {
+            const msg = String(j.error.message ?? '');
+            // Transient infrastructure problems are worth failing over for; a real
+            // contract revert is not - surface it immediately.
+            if (!/healthy|unavailable|rate|limit|timeout|busy|capacity/i.test(msg)) {
+              throw new Error(`${method}: ${msg}`);
+            }
+            last = new Error(`${method}: ${msg}`);
+            continue;
+          }
+          return j.result;
+        } catch (e) {
+          if (e instanceof Error && e.message.startsWith(method + ':')) throw e;
+          last = e;
+        }
+      }
+      await new Promise(r => setTimeout(r, 800 * (attempt + 1)));
+    }
+    throw last instanceof Error ? last : new Error(`${method}: all RPCs failed`);
+  };
+}
+
+/* ----------------------- transaction signing ----------------------- */
+
+export interface TxRequest {
+  chainId: number;
+  to: string;
+  data: string;
+  gasLimit?: bigint;
+  value?: bigint;
+  /** Multiplier applied to the observed gas price for maxFeePerGas. Default 4. */
+  feeMultiplier?: bigint;
+}
+
+/**
+ * Sign and broadcast an EIP-1559 transaction.
+ *
+ * Re-submitting the SAME signed transaction is idempotent at the network layer: identical
+ * nonce plus identical signature yields an identical hash. That makes RPC failover safe here.
+ */
+export async function sendTransaction(
+  rpc: (m: string, p?: unknown[]) => Promise<any>,
+  privateKey: string,
+  tx: TxRequest,
+): Promise<{ hash: string; from: string }> {
+  const d = toBig(fromHex(privateKey));
+  if (d === 0n || d >= N) throw new Error('evm-tx: invalid key material');
+  const from = addressOf(d);
+
+  const [nonceHex, gasPriceHex] = await Promise.all([
+    rpc('eth_getTransactionCount', [from, 'pending']),
+    rpc('eth_gasPrice', []),
+  ]);
+  const tip = 1_000_000n;                                    // 0.001 gwei
+  const maxFee = BigInt(gasPriceHex) * (tx.feeMultiplier ?? 4n) + tip;
+
+  const fields: RlpInput[] = [
+    minimal(BigInt(tx.chainId)), minimal(BigInt(nonceHex)), minimal(tip), minimal(maxFee),
+    minimal(tx.gasLimit ?? 200_000n), fromHex(tx.to), minimal(tx.value ?? 0n),
+    fromHex(tx.data), [],
+  ];
+  const sigHash = toBig(keccak256(new Uint8Array([0x02]), rlp(fields)));
+  const sig = fromHex(signWith(makeNonce(), sigHash, d));
+
+  // Self-check before spending gas: if RLP or the signing hash were wrong this would not
+  // recover to us, and the node would reject or - worse - mis-attribute the transaction.
+  if (recoverSigner(sigHash, toHex(sig)) !== from) {
+    throw new Error('evm-tx: signed transaction does not recover to the sender; refusing to broadcast');
+  }
+
+  // r and s are fixed 32-byte values, but RLP integers must be MINIMAL: a leading zero
+  // byte makes them non-canonical and go-ethereum rejects the whole transaction with
+  // "rlp: non-canonical integer (leading zero bytes) for *big.Int". Either value starts
+  // with a zero byte roughly one time in 256, so this is invisible until it is not - it
+  // took seventy-one consecutive broadcasts to surface.
+  const trimZeros = (b: Uint8Array): Uint8Array => {
+    let i = 0;
+    while (i < b.length && b[i] === 0) i++;
+    return b.subarray(i);
+  };
+  const raw = toHex(cat(new Uint8Array([0x02]),
+    rlp([...fields, minimal(BigInt(sig[64] - 27)),
+         trimZeros(sig.slice(0, 32)), trimZeros(sig.slice(32, 64))])));
+  const hash = await rpc('eth_sendRawTransaction', [raw]);
+  return { hash, from };
+}
+
+export async function waitForReceipt(
+  rpc: (m: string, p?: unknown[]) => Promise<any>,
+  hash: string,
+  opts: { timeoutMs?: number; pollMs?: number } = {},
+): Promise<{ ok: boolean; gasUsed: number; blockNumber: number } | null> {
+  const deadline = Date.now() + (opts.timeoutMs ?? 120000);
+  const poll = opts.pollMs ?? 2500;
+  while (Date.now() < deadline) {
+    await new Promise(r => setTimeout(r, poll));
+    const rc = await rpc('eth_getTransactionReceipt', [hash]).catch(() => null);
+    if (rc) return { ok: rc.status === '0x1', gasUsed: Number(BigInt(rc.gasUsed)), blockNumber: Number(BigInt(rc.blockNumber)) };
+  }
+  return null;
+}
+
+/** abi.encode word: bigint, 0x-hex, or bytes. */
+export const word = (v: bigint | string | Uint8Array): string => {
+  if (typeof v === 'bigint') return toHex(beBytes(v, 32)).slice(2);
+  const b = typeof v === 'string' ? fromHex(v) : v;
+  const w = new Uint8Array(32);
+  w.set(b, 32 - b.length);
+  return toHex(w).slice(2);
+};
+
+/** 4-byte selector for a solidity signature. */
+export const selector = (sig: string): string =>
+  toHex(keccak256(new TextEncoder().encode(sig))).slice(0, 10);
+
+/** Calldata for USDC's transferWithAuthorization. */
+export function transferWithAuthorizationData(
+  auth: { from: string; to: string; value: string; validAfter: string; validBefore: string; nonce: string },
+  signature: string,
+): string {
+  const sig = fromHex(signature);
+  return selector('transferWithAuthorization(address,address,uint256,uint256,uint256,bytes32,uint8,bytes32,bytes32)')
+    + word(auth.from) + word(auth.to) + word(BigInt(auth.value))
+    + word(BigInt(auth.validAfter)) + word(BigInt(auth.validBefore)) + word(auth.nonce)
+    + word(BigInt(sig[64])) + word(sig.slice(0, 32)) + word(sig.slice(32, 64));
+}