402-trinity-gaming 0.1.0

package/dist/batch-manager.js

@@ -0,0 +1,291 @@
+import { createStorefront } from "./storefront.js";
+import { signPurchase } from "./signer.js";
+function createBatchManager(cfg) {
+  const sizes = Object.entries(cfg.tabs);
+  if (sizes.length === 0) throw new Error("batch manager: no tab sizes configured");
+  for (const [id, v] of sizes) {
+    if (!/^[0-9]+$/.test(v) || BigInt(v) <= 0n) {
+      throw new Error(`batch manager: tab '${id}' must be a positive integer in atomic units, got '${v}'`);
+    }
+  }
+  const store = createStorefront({ ...cfg, catalog: cfg.tabs });
+  const mem = /* @__PURE__ */ new Map();
+  const lowAt = cfg.lowWaterMark ?? 0.15;
+  const handlers = { opened: [], refunded: [], spent: [], low: [], exhausted: [] };
+  const emit = (n, e) => {
+    for (const h of handlers[n]) {
+      try {
+        h(e);
+      } catch (err) {
+        cfg.onDiagnostic?.({
+          code: "handler_threw",
+          message: `${n} handler threw: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+    }
+  };
+  const read = async (playerId) => cfg.ledger ? cfg.ledger.get(playerId) : mem.get(playerId) ?? null;
+  const write = async (playerId, s) => {
+    if (cfg.ledger) await cfg.ledger.set(playerId, s);
+    else mem.set(playerId, s);
+  };
+  return {
+    /** Tab sizes on offer. */
+    get sizes() {
+      return sizes.map(([id]) => id);
+    },
+    /** What the client signs to open tab `tabId`. */
+    quote(tabId) {
+      return store.quote(tabId);
+    },
+    on(n, h) {
+      handlers[n].push(h);
+      return () => {
+        const i = handlers[n].indexOf(h);
+        if (i >= 0) handlers[n].splice(i, 1);
+      };
+    },
+    /**
+     * Open or top up a tab. This is the ONLY on-chain step - one settlement covering every
+     * action the player takes until the balance runs out.
+     *
+     * Credit is added only after the transfer settles. A declined payment adds nothing.
+     */
+    async open(req) {
+      const result = await store.purchase({
+        itemId: req.tabId,
+        playerId: req.playerId,
+        playerAddress: req.playerAddress,
+        authorization: req.authorization,
+        signature: req.signature
+      });
+      if (!("transaction" in result)) return { ok: false, declined: result };
+      const add = BigInt(result.amount);
+      const cur = await read(req.playerId);
+      const next = {
+        playerAddress: req.playerAddress,
+        remaining: String((cur ? BigInt(cur.remaining) : 0n) + add),
+        opened: String((cur ? BigInt(cur.opened) : 0n) + add),
+        spent: cur?.spent ?? [],
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await write(req.playerId, next);
+      emit("opened", {
+        playerId: req.playerId,
+        playerAddress: req.playerAddress,
+        amount: result.amount,
+        transaction: result.transaction
+      });
+      return { ok: true, remaining: next.remaining, transaction: result.transaction };
+    },
+    /**
+     * Charge one micro-action. Synchronous in spirit - no signature, no chain, no network -
+     * so it is safe on a gameplay path.
+     *
+     * `actionId` makes it idempotent. A client that retries after a dropped response charges
+     * once, and the second call reports `duplicate: true` so you can grant without re-billing.
+     */
+    async spend(req) {
+      const { playerId, actionId, amount } = req;
+      if (!/^[0-9]+$/.test(amount) || BigInt(amount) <= 0n) {
+        return {
+          ok: false,
+          code: "invalid_amount",
+          remaining: "0",
+          message: `amount must be a positive integer in atomic units, got '${amount}'`
+        };
+      }
+      if (!await read(playerId)) {
+        return { ok: false, code: "no_tab", remaining: "0", message: "no open tab" };
+      }
+      let out = { ok: false, code: "no_tab", remaining: "0", message: "no open tab" };
+      const outcome = () => out;
+      let low = false, empty = false;
+      const step = (cur) => {
+        if (!cur) {
+          out = { ok: false, code: "no_tab", remaining: "0", message: "no open tab" };
+          return { playerAddress: "", remaining: "0", opened: "0", spent: [], updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+        }
+        if (cur.spent.some((e) => e.id === actionId)) {
+          out = { ok: true, remaining: cur.remaining, charged: "0", duplicate: true };
+          return cur;
+        }
+        const rem = BigInt(cur.remaining), amt = BigInt(amount);
+        if (rem < amt) {
+          out = {
+            ok: false,
+            code: "insufficient",
+            remaining: cur.remaining,
+            message: `tab has ${cur.remaining}, action costs ${amount}`
+          };
+          return cur;
+        }
+        const left = rem - amt;
+        out = { ok: true, remaining: String(left), charged: amount, duplicate: false };
+        low = left > 0n && Number(left) < Number(BigInt(cur.opened)) * lowAt;
+        empty = left === 0n;
+        return {
+          ...cur,
+          remaining: String(left),
+          // Bounded by age, not by count. The ledger store prunes on write as well; this
+          // keeps the in-memory path from growing without bound over a long session.
+          spent: [...cur.spent.filter((e) => e.at > Date.now() - 864e5), { id: actionId, at: Date.now() }],
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+      };
+      if (cfg.ledger?.update) await cfg.ledger.update(playerId, step);
+      else {
+        const cur = await read(playerId);
+        const next = step(cur);
+        if (cur) await write(playerId, next);
+      }
+      const res = outcome();
+      if (res.ok && !res.duplicate) {
+        emit("spent", { playerId, actionId, amount, remaining: res.remaining });
+        const st = await read(playerId);
+        if (low && st) emit("low", { playerId, remaining: st.remaining, opened: st.opened });
+        if (empty) emit("exhausted", { playerId });
+      }
+      return res;
+    },
+    /**
+     * Return unspent credit to the player's wallet.
+     *
+     * The studio signs an authorization to the player and the facilitator submits it, so the
+     * studio needs no gas - the same shape as every other transfer here, just pointing the
+     * other way. Requires `surcharge.proceedsKey`, because that is the key for the wallet
+     * holding the money.
+     *
+     * ORDER MATTERS. The credit is deducted BEFORE the transfer is attempted, so it cannot be
+     * spent while the refund is in flight, and restored if the transfer fails. The opposite
+     * order lets a player spend the same money twice - once in-game and once on-chain.
+     *
+     * The 0.1% taken when the tab opened is NOT reversed. It was charged on a sale that did
+     * happen, and clawing it back out of the vault is not something this can do.
+     */
+    async refund(req) {
+      const { playerId } = req;
+      const key = cfg.surcharge?.proceedsKey;
+      if (!key) {
+        return {
+          ok: false,
+          code: "no_key",
+          remaining: "0",
+          message: "refunds need surcharge.proceedsKey - the key for the payTo wallet"
+        };
+      }
+      const cur = await read(playerId);
+      if (!cur) return { ok: false, code: "no_tab", remaining: "0", message: "no open tab" };
+      const rem = BigInt(cur.remaining);
+      if (rem === 0n) {
+        return { ok: false, code: "nothing_to_refund", remaining: "0", message: "tab is empty" };
+      }
+      const amount = req.amount ?? cur.remaining;
+      if (!/^[0-9]+$/.test(amount) || BigInt(amount) <= 0n) {
+        return {
+          ok: false,
+          code: "too_much",
+          remaining: cur.remaining,
+          message: `amount must be a positive integer in atomic units, got '${amount}'`
+        };
+      }
+      if (BigInt(amount) > rem) {
+        return {
+          ok: false,
+          code: "too_much",
+          remaining: cur.remaining,
+          message: `tab has ${cur.remaining}, cannot refund ${amount}`
+        };
+      }
+      const reserved = {
+        ...cur,
+        remaining: String(rem - BigInt(amount)),
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      if (cfg.ledger?.update) await cfg.ledger.update(playerId, () => reserved);
+      else await write(playerId, reserved);
+      const restore = async () => {
+        const now = await read(playerId);
+        const back = {
+          ...now ?? reserved,
+          remaining: String(BigInt(now?.remaining ?? reserved.remaining) + BigInt(amount)),
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        if (cfg.ledger?.update) await cfg.ledger.update(playerId, () => back);
+        else await write(playerId, back);
+      };
+      try {
+        const quote = { ...store.quote(sizes[0][0]), amount, payTo: cur.playerAddress };
+        const signed = signPurchase(quote, key);
+        const r = await fetch(cfg.facilitator.replace(/\/$/, "") + "/settle", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            x402Version: 2,
+            paymentPayload: {
+              x402Version: 2,
+              scheme: "exact",
+              network: quote.network,
+              payload: { authorization: signed.authorization, signature: signed.signature }
+            },
+            paymentRequirements: {
+              scheme: "exact",
+              network: quote.network,
+              payTo: cur.playerAddress,
+              asset: quote.asset,
+              amount,
+              maxAmountRequired: amount,
+              maxTimeoutSeconds: 300,
+              extra: quote.extra
+            }
+          })
+        });
+        const body = r.ok ? await r.json().catch(() => null) : null;
+        if (body?.success !== true) {
+          await restore();
+          const why = body?.errorReason ?? `facilitator returned ${r.status}`;
+          cfg.onDiagnostic?.({ code: "refund_failed", message: String(why) });
+          return {
+            ok: false,
+            code: "failed",
+            remaining: cur.remaining,
+            message: `refund not settled: ${why} - the credit was returned to the tab`
+          };
+        }
+        const after = await read(playerId);
+        emit("refunded", {
+          playerId,
+          playerAddress: cur.playerAddress,
+          amount,
+          transaction: body.transaction
+        });
+        return {
+          ok: true,
+          refunded: amount,
+          remaining: after?.remaining ?? reserved.remaining,
+          transaction: body.transaction
+        };
+      } catch (err) {
+        await restore();
+        const message = err instanceof Error ? err.message : String(err);
+        cfg.onDiagnostic?.({ code: "refund_error", message });
+        return {
+          ok: false,
+          code: "failed",
+          remaining: cur.remaining,
+          message: `${message} - the credit was returned to the tab`
+        };
+      }
+    },
+    /** What the player has left. Read-only. */
+    async balance(playerId) {
+      const s = await read(playerId);
+      return s ? { remaining: s.remaining, opened: s.opened } : null;
+    },
+    /** The network fee taken from proceeds when a tab is opened. */
+    fee: store.fee
+  };
+}
+export {
+  createBatchManager
+};

package/dist/batch-manager.min.js

@@ -0,0 +1 @@
+import{createStorefront as x}from"./storefront.js";import{signPurchase as v}from"./signer.js";function $(r){const y=Object.entries(r.tabs);if(y.length===0)throw new Error("batch manager: no tab sizes configured");for(const[t,e]of y)if(!/^[0-9]+$/.test(e)||BigInt(e)<=0n)throw new Error(`batch manager: tab '${t}' must be a positive integer in atomic units, got '${e}'`);const b=x({...r,catalog:r.tabs}),k=new Map,A=r.lowWaterMark??.15,h={opened:[],refunded:[],spent:[],low:[],exhausted:[]},p=(t,e)=>{for(const s of h[t])try{s(e)}catch(n){r.onDiagnostic?.({code:"handler_threw",message:`${t} handler threw: ${n instanceof Error?n.message:String(n)}`})}},m=async t=>r.ledger?r.ledger.get(t):k.get(t)??null,w=async(t,e)=>{r.ledger?await r.ledger.set(t,e):k.set(t,e)};return{get sizes(){return y.map(([t])=>t)},quote(t){return b.quote(t)},on(t,e){return h[t].push(e),()=>{const s=h[t].indexOf(e);s>=0&&h[t].splice(s,1)}},async open(t){const e=await b.purchase({itemId:t.tabId,playerId:t.playerId,playerAddress:t.playerAddress,authorization:t.authorization,signature:t.signature});if(!("transaction"in e))return{ok:!1,declined:e};const s=BigInt(e.amount),n=await m(t.playerId),g={playerAddress:t.playerAddress,remaining:String((n?BigInt(n.remaining):0n)+s),opened:String((n?BigInt(n.opened):0n)+s),spent:n?.spent??[],updatedAt:new Date().toISOString()};return await w(t.playerId,g),p("opened",{playerId:t.playerId,playerAddress:t.playerAddress,amount:e.amount,transaction:e.transaction}),{ok:!0,remaining:g.remaining,transaction:e.transaction}},async spend(t){const{playerId:e,actionId:s,amount:n}=t;if(!/^[0-9]+$/.test(n)||BigInt(n)<=0n)return{ok:!1,code:"invalid_amount",remaining:"0",message:`amount must be a positive integer in atomic units, got '${n}'`};if(!await m(e))return{ok:!1,code:"no_tab",remaining:"0",message:"no open tab"};let g={ok:!1,code:"no_tab",remaining:"0",message:"no open tab"};const o=()=>g;let l=!1,f=!1;const i=a=>{if(!a)return g={ok:!1,code:"no_tab",remaining:"0",message:"no open tab"},{playerAddress:"",remaining:"0",opened:"0",spent:[],updatedAt:new Date().toISOString()};if(a.spent.some(I=>I.id===s))return g={ok:!0,remaining:a.remaining,charged:"0",duplicate:!0},a;const u=BigInt(a.remaining),S=BigInt(n);if(u<S)return g={ok:!1,code:"insufficient",remaining:a.remaining,message:`tab has ${a.remaining}, action costs ${n}`},a;const c=u-S;return g={ok:!0,remaining:String(c),charged:n,duplicate:!1},l=c>0n&&Number(c)<Number(BigInt(a.opened))*A,f=c===0n,{...a,remaining:String(c),spent:[...a.spent.filter(I=>I.at>Date.now()-864e5),{id:s,at:Date.now()}],updatedAt:new Date().toISOString()}};if(r.ledger?.update)await r.ledger.update(e,i);else{const a=await m(e),u=i(a);a&&await w(e,u)}const d=o();if(d.ok&&!d.duplicate){p("spent",{playerId:e,actionId:s,amount:n,remaining:d.remaining});const a=await m(e);l&&a&&p("low",{playerId:e,remaining:a.remaining,opened:a.opened}),f&&p("exhausted",{playerId:e})}return d},async refund(t){const{playerId:e}=t,s=r.surcharge?.proceedsKey;if(!s)return{ok:!1,code:"no_key",remaining:"0",message:"refunds need surcharge.proceedsKey - the key for the payTo wallet"};const n=await m(e);if(!n)return{ok:!1,code:"no_tab",remaining:"0",message:"no open tab"};const g=BigInt(n.remaining);if(g===0n)return{ok:!1,code:"nothing_to_refund",remaining:"0",message:"tab is empty"};const o=t.amount??n.remaining;if(!/^[0-9]+$/.test(o)||BigInt(o)<=0n)return{ok:!1,code:"too_much",remaining:n.remaining,message:`amount must be a positive integer in atomic units, got '${o}'`};if(BigInt(o)>g)return{ok:!1,code:"too_much",remaining:n.remaining,message:`tab has ${n.remaining}, cannot refund ${o}`};const l={...n,remaining:String(g-BigInt(o)),updatedAt:new Date().toISOString()};r.ledger?.update?await r.ledger.update(e,()=>l):await w(e,l);const f=async()=>{const i=await m(e),d={...i??l,remaining:String(BigInt(i?.remaining??l.remaining)+BigInt(o)),updatedAt:new Date().toISOString()};r.ledger?.update?await r.ledger.update(e,()=>d):await w(e,d)};try{const i={...b.quote(y[0][0]),amount:o,payTo:n.playerAddress},d=v(i,s),a=await fetch(r.facilitator.replace(/\/$/,"")+"/settle",{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify({x402Version:2,paymentPayload:{x402Version:2,scheme:"exact",network:i.network,payload:{authorization:d.authorization,signature:d.signature}},paymentRequirements:{scheme:"exact",network:i.network,payTo:n.playerAddress,asset:i.asset,amount:o,maxAmountRequired:o,maxTimeoutSeconds:300,extra:i.extra}})}),u=a.ok?await a.json().catch(()=>null):null;if(u?.success!==!0){await f();const c=u?.errorReason??`facilitator returned ${a.status}`;return r.onDiagnostic?.({code:"refund_failed",message:String(c)}),{ok:!1,code:"failed",remaining:n.remaining,message:`refund not settled: ${c} - the credit was returned to the tab`}}const S=await m(e);return p("refunded",{playerId:e,playerAddress:n.playerAddress,amount:o,transaction:u.transaction}),{ok:!0,refunded:o,remaining:S?.remaining??l.remaining,transaction:u.transaction}}catch(i){await f();const d=i instanceof Error?i.message:String(i);return r.onDiagnostic?.({code:"refund_error",message:d}),{ok:!1,code:"failed",remaining:n.remaining,message:`${d} - the credit was returned to the tab`}}},async balance(t){const e=await m(t);return e?{remaining:e.remaining,opened:e.opened}:null},fee:b.fee}}export{$ as createBatchManager};

package/dist/budget-file.d.ts

@@ -0,0 +1,106 @@
+export interface BudgetStore {
+    reserve: (amount: bigint, totalBudget: bigint) => Promise<boolean>;
+    release?: (amount: bigint) => Promise<void>;
+    /** Current spend, for reporting. */
+    spent: () => bigint;
+}
+export declare function createFileBudgetStore(path: string, opts?: {
+    lockTimeoutMs?: number;
+}): BudgetStore;
+/**
+ * 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 declare function createFileFeeStore(path: string, opts?: {
+    lockTimeoutMs?: number;
+}): {
+    get: () => Promise<{
+        accrued: bigint;
+        count: bigint;
+    }>;
+    set: (v: {
+        accrued: bigint;
+        count: bigint;
+    }) => Promise<void>;
+    /**
+     * 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: (fn: (cur: {
+        accrued: bigint;
+        count: bigint;
+    }) => {
+        accrued: bigint;
+        count: bigint;
+    }) => Promise<{
+        accrued: bigint;
+        count: bigint;
+    }>;
+};
+/**
+ * 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 declare function createFileCollectorStore(path: string): {
+    pending: () => Promise<any>;
+    add: (item: any) => Promise<void>;
+    remove: (nonces: string[]) => Promise<void>;
+    seen: (nonce: string) => Promise<any>;
+    markSeen: (nonce: string) => Promise<void>;
+};
+/**
+ * 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 declare function createFileNonceStore(path: string): {
+    seen: (nonce: string) => Promise<boolean>;
+    add: (nonce: string, expiresAtUnix: number) => Promise<void>;
+    /** Entries currently held (after pruning expired ones). */
+    size: () => number;
+};
+/**
+ * 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 declare function createFileLedgerStore(path: string, opts?: {
+    lockTimeoutMs?: number;
+}): {
+    get: (playerId: string) => Promise<{
+        playerAddress: string;
+        remaining: string;
+        opened: string;
+        spent: Array<{
+            id: string;
+            at: number;
+        }>;
+        updatedAt: string;
+    }>;
+    set: (playerId: string, s: any) => Promise<void>;
+    /**
+     * 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: (playerId: string, fn: (cur: any) => any) => Promise<{
+        playerAddress: string;
+        remaining: string;
+        opened: string;
+        spent: Array<{
+            id: string;
+            at: number;
+        }>;
+        updatedAt: string;
+    }>;
+};

package/dist/budget-file.js

@@ -0,0 +1,270 @@
+import { openSync, closeSync, unlinkSync, readFileSync, writeFileSync, renameSync, existsSync } from "node:fs";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function createFileBudgetStore(path, opts = {}) {
+  const lockPath = path + ".lock";
+  const timeout = opts.lockTimeoutMs ?? 5e3;
+  const read = () => {
+    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 {
+      throw new Error(`x402 budget file is unreadable: ${path}. Refusing to treat it as zero spend.`);
+    }
+  };
+  const write = (v) => {
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, JSON.stringify({ spent: v.toString(), updated: (/* @__PURE__ */ new Date()).toISOString() }));
+    renameSync(tmp, path);
+  };
+  async function withLock(fn) {
+    const deadline = Date.now() + timeout;
+    let fd;
+    for (; ; ) {
+      try {
+        fd = openSync(lockPath, "wx");
+        break;
+      } 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 {
+      }
+      try {
+        unlinkSync(lockPath);
+      } catch {
+      }
+    }
+  }
+  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()
+  };
+}
+function createFileFeeStore(path, opts = {}) {
+  const lockPath = path + ".lock";
+  const timeout = opts.lockTimeoutMs ?? 5e3;
+  const read = () => {
+    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 {
+      throw new Error(`x402 fee tally is unreadable: ${path}. Refusing to treat it as zero.`);
+    }
+  };
+  const write = (v) => {
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, JSON.stringify({
+      accruedScaled: v.accrued.toString(),
+      count: v.count.toString(),
+      updated: (/* @__PURE__ */ new Date()).toISOString()
+    }));
+    renameSync(tmp, path);
+  };
+  async function withLock(fn) {
+    const deadline = Date.now() + timeout;
+    let fd;
+    for (; ; ) {
+      try {
+        fd = openSync(lockPath, "wx");
+        break;
+      } 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 {
+      }
+      try {
+        unlinkSync(lockPath);
+      } catch {
+      }
+    }
+  }
+  return {
+    get: async () => withLock(read),
+    set: async (v) => {
+      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) => withLock(() => {
+      const next = fn(read());
+      write(next);
+      return next;
+    })
+  };
+}
+function createFileCollectorStore(path) {
+  const read = () => {
+    if (!existsSync(path)) return { pending: [], seen: [] };
+    try {
+      return JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      throw new Error(`x402 collector store is unreadable: ${path}. Refusing to treat it as empty.`);
+    }
+  };
+  const write = (d) => {
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, JSON.stringify(d));
+    renameSync(tmp, path);
+  };
+  return {
+    pending: async () => read().pending ?? [],
+    add: async (item) => {
+      const d = read();
+      d.pending = [...d.pending ?? [], item];
+      write(d);
+    },
+    remove: async (nonces) => {
+      const d = read();
+      const drop = new Set(nonces.map((n) => n.toLowerCase()));
+      d.pending = (d.pending ?? []).filter((i) => !drop.has(i.authorization.nonce.toLowerCase()));
+      write(d);
+    },
+    seen: async (nonce) => (read().seen ?? []).includes(nonce.toLowerCase()),
+    markSeen: async (nonce) => {
+      const d = read();
+      d.seen = [...d.seen ?? [], nonce.toLowerCase()];
+      write(d);
+    }
+  };
+}
+function createFileNonceStore(path) {
+  const read = () => {
+    if (!existsSync(path)) return {};
+    try {
+      return JSON.parse(readFileSync(path, "utf8")).nonces ?? {};
+    } catch {
+      throw new Error(`x402 nonce store is unreadable: ${path}. Refusing to treat it as empty.`);
+    }
+  };
+  const write = (n) => {
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, JSON.stringify({ nonces: n, updated: (/* @__PURE__ */ new Date()).toISOString() }));
+    renameSync(tmp, path);
+  };
+  return {
+    seen: async (nonce) => {
+      const now = Math.floor(Date.now() / 1e3);
+      const exp = read()[nonce.toLowerCase()];
+      return exp !== void 0 && exp > now;
+    },
+    add: async (nonce, expiresAtUnix) => {
+      const now = Math.floor(Date.now() / 1e3);
+      const n = read();
+      for (const [k, exp] of Object.entries(n)) if (exp <= now) delete n[k];
+      n[nonce.toLowerCase()] = expiresAtUnix;
+      write(n);
+    },
+    /** Entries currently held (after pruning expired ones). */
+    size: () => {
+      const now = Math.floor(Date.now() / 1e3);
+      return Object.values(read()).filter((e) => e > now).length;
+    }
+  };
+}
+function createFileLedgerStore(path, opts = {}) {
+  const lockPath = path + ".lock";
+  const timeout = opts.lockTimeoutMs ?? 5e3;
+  const readAll = () => {
+    if (!existsSync(path)) return {};
+    try {
+      return JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      throw new Error(`x402 tab ledger unreadable: ${path} - fix or remove it deliberately`);
+    }
+  };
+  const writeAll = (all) => {
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, JSON.stringify(all));
+    renameSync(tmp, path);
+  };
+  async function withLock(fn) {
+    const deadline = Date.now() + timeout;
+    let fd;
+    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 {
+      }
+      try {
+        unlinkSync(lockPath);
+      } catch {
+      }
+    }
+  }
+  const KEEP_MS = 24 * 60 * 60 * 1e3;
+  const prune = (spent) => {
+    const cutoff = Date.now() - KEEP_MS;
+    const kept = spent.filter((e) => e.at > cutoff);
+    return kept.length > 5e3 ? kept.slice(-5e3) : kept;
+  };
+  return {
+    get: async (playerId) => withLock(() => readAll()[playerId] ?? null),
+    set: async (playerId, s) => {
+      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, fn) => withLock(() => {
+      const all = readAll();
+      const next = fn(all[playerId] ?? null);
+      all[playerId] = { ...next, spent: prune(next.spent ?? []) };
+      writeAll(all);
+      return all[playerId];
+    })
+  };
+}
+export {
+  createFileBudgetStore,
+  createFileCollectorStore,
+  createFileFeeStore,
+  createFileLedgerStore,
+  createFileNonceStore
+};

package/dist/budget-file.min.js

@@ -0,0 +1 @@
+import{openSync as b,closeSync as S,unlinkSync as p,readFileSync as g,writeFileSync as f,renameSync as w,existsSync as y}from"node:fs";const k=t=>new Promise(s=>setTimeout(s,t));function T(t,s={}){const a=t+".lock",o=s.lockTimeoutMs??5e3,e=()=>{if(!y(t))return 0n;try{const n=JSON.parse(g(t,"utf8")),r=BigInt(n.spent??"0");return r<0n?0n:r}catch{throw new Error(`x402 budget file is unreadable: ${t}. Refusing to treat it as zero spend.`)}},u=n=>{const r=t+".tmp";f(r,JSON.stringify({spent:n.toString(),updated:new Date().toISOString()})),w(r,t)};async function c(n){const r=Date.now()+o;let i;for(;;)try{i=b(a,"wx");break}catch{if(Date.now()>r)throw new Error(`x402 budget lock timed out: ${a}`);await k(15)}try{return n()}finally{try{S(i)}catch{}try{p(a)}catch{}}}return{reserve:(n,r)=>c(()=>{const i=e();return i+n>r?!1:(u(i+n),!0)}),release:n=>c(()=>{const r=e();u(r-n<0n?0n:r-n)}),spent:()=>e()}}function O(t,s={}){const a=t+".lock",o=s.lockTimeoutMs??5e3,e=()=>{if(!y(t))return{accrued:0n,count:0n};try{const n=JSON.parse(g(t,"utf8"));return{accrued:BigInt(n.accruedScaled??"0"),count:BigInt(n.count??"0")}}catch{throw new Error(`x402 fee tally is unreadable: ${t}. Refusing to treat it as zero.`)}},u=n=>{const r=t+".tmp";f(r,JSON.stringify({accruedScaled:n.accrued.toString(),count:n.count.toString(),updated:new Date().toISOString()})),w(r,t)};async function c(n){const r=Date.now()+o;let i;for(;;)try{i=b(a,"wx");break}catch{if(Date.now()>r)throw new Error(`x402 fee lock timed out: ${a}`);await k(15)}try{return n()}finally{try{S(i)}catch{}try{p(a)}catch{}}}return{get:async()=>c(e),set:async n=>{await c(()=>u(n))},update:async n=>c(()=>{const r=n(e());return u(r),r})}}function D(t){const s=()=>{if(!y(t))return{pending:[],seen:[]};try{return JSON.parse(g(t,"utf8"))}catch{throw new Error(`x402 collector store is unreadable: ${t}. Refusing to treat it as empty.`)}},a=o=>{const e=t+".tmp";f(e,JSON.stringify(o)),w(e,t)};return{pending:async()=>s().pending??[],add:async o=>{const e=s();e.pending=[...e.pending??[],o],a(e)},remove:async o=>{const e=s(),u=new Set(o.map(c=>c.toLowerCase()));e.pending=(e.pending??[]).filter(c=>!u.has(c.authorization.nonce.toLowerCase())),a(e)},seen:async o=>(s().seen??[]).includes(o.toLowerCase()),markSeen:async o=>{const e=s();e.seen=[...e.seen??[],o.toLowerCase()],a(e)}}}function h(t){const s=()=>{if(!y(t))return{};try{return JSON.parse(g(t,"utf8")).nonces??{}}catch{throw new Error(`x402 nonce store is unreadable: ${t}. Refusing to treat it as empty.`)}},a=o=>{const e=t+".tmp";f(e,JSON.stringify({nonces:o,updated:new Date().toISOString()})),w(e,t)};return{seen:async o=>{const e=Math.floor(Date.now()/1e3),u=s()[o.toLowerCase()];return u!==void 0&&u>e},add:async(o,e)=>{const u=Math.floor(Date.now()/1e3),c=s();for(const[n,r]of Object.entries(c))r<=u&&delete c[n];c[o.toLowerCase()]=e,a(c)},size:()=>{const o=Math.floor(Date.now()/1e3);return Object.values(s()).filter(e=>e>o).length}}}function P(t,s={}){const a=t+".lock",o=s.lockTimeoutMs??5e3,e=()=>{if(!y(t))return{};try{return JSON.parse(g(t,"utf8"))}catch{throw new Error(`x402 tab ledger unreadable: ${t} - fix or remove it deliberately`)}},u=i=>{const l=t+".tmp";f(l,JSON.stringify(i)),w(l,t)};async function c(i){const l=Date.now()+o;let d;for(;;)try{d=b(a,"wx");break}catch{if(Date.now()>l)throw new Error(`x402 tab ledger lock timed out: ${a}`);await k(15)}try{return i()}finally{try{S(d)}catch{}try{p(a)}catch{}}}const n=1440*60*1e3,r=i=>{const l=Date.now()-n,d=i.filter(m=>m.at>l);return d.length>5e3?d.slice(-5e3):d};return{get:async i=>c(()=>e()[i]??null),set:async(i,l)=>{await c(()=>{const d=e();d[i]={...l,spent:r(l.spent??[])},u(d)})},update:async(i,l)=>c(()=>{const d=e(),m=l(d[i]??null);return d[i]={...m,spent:r(m.spent??[])},u(d),d[i]})}}export{T as createFileBudgetStore,D as createFileCollectorStore,O as createFileFeeStore,P as createFileLedgerStore,h as createFileNonceStore};