@piprail/sdk 2.7.0 → 2.9.0

package/dist/index.js

@@ -1,7 +1,11 @@
+import {
+  memorySpendStore
+} from "./chunk-SK3CB7UA.js";
 import {
   ConfirmationTimeoutError,
   InsufficientFundsError,
   InvalidEnvelopeError,
+  MAX_DECIMALS,
   MaxRetriesExceededError,
   MissingDriverError,
   NoCompatibleAcceptError,
@@ -24,7 +28,7 @@ import {
   parseUnits,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-7XK22JSQ.js";
+} from "./chunk-SC2ZYDHD.js";
 
 // src/drivers/registry.ts
 var byFamily = /* @__PURE__ */ new Map();
@@ -1840,7 +1844,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-3FMCWSEE.js");
+      mod = await import("./solana-ELUWO6N5.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -1852,7 +1856,7 @@ var loaders = {
   ton: async () => {
     let mod;
     try {
-      mod = await import("./ton-5ZPT5PSP.js");
+      mod = await import("./ton-7GKCTC5H.js");
     } catch (cause) {
       throw new MissingDriverError(
         `TON selected, but its packages aren't installed. Run: npm install @ton/ton @ton/core @ton/crypto`,
@@ -1864,7 +1868,7 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await import("./stellar-U5NCRIOJ.js");
+      mod = await import("./stellar-BEMT7UYF.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
@@ -1876,7 +1880,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await import("./xrpl-2MZEOIFY.js");
+      mod = await import("./xrpl-DD7TJL5L.js");
     } catch (cause) {
       throw new MissingDriverError(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
@@ -1888,7 +1892,7 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await import("./tron-WYS4X2I5.js");
+      mod = await import("./tron-ZZZS3FNN.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
@@ -1900,7 +1904,7 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await import("./sui-Y53M4GUM.js");
+      mod = await import("./sui-F5JQ2N6I.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
@@ -1912,7 +1916,7 @@ var loaders = {
   near: async () => {
     let mod;
     try {
-      mod = await import("./near-OTPQD6BI.js");
+      mod = await import("./near-FZBUICCS.js");
     } catch (cause) {
       throw new MissingDriverError(
         `NEAR selected, but its package isn't installed. Run: npm install near-api-js`,
@@ -1924,7 +1928,7 @@ var loaders = {
   aptos: async () => {
     let mod;
     try {
-      mod = await import("./aptos-QAAXIUY3.js");
+      mod = await import("./aptos-LY67Q6QF.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Aptos selected, but its package isn't installed. Run: npm install @aptos-labs/ts-sdk`,
@@ -1936,7 +1940,7 @@ var loaders = {
   algorand: async () => {
     let mod;
     try {
-      mod = await import("./algorand-WB6PBJU4.js");
+      mod = await import("./algorand-AA3WXKW4.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Algorand selected, but its package isn't installed. Run: npm install algosdk`,
@@ -2027,7 +2031,7 @@ var SLUG_TO_CAIP2 = {
   bsc: "eip155:56",
   // non-EVM families — values mirror each driver's bound caip2 exactly
   solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
-  ton: "ton:-239",
+  ton: "tvm:-239",
   tron: "tron:mainnet",
   near: "near:mainnet",
   sui: "sui:mainnet",
@@ -2036,7 +2040,12 @@ var SLUG_TO_CAIP2 = {
   stellar: "stellar:pubnet",
   xrpl: "xrpl:0"
 };
+var LEGACY_CAIP2_ALIAS = {
+  "ton:-239": "tvm:-239"
+};
 function normalizeNetwork(network) {
+  const legacy = LEGACY_CAIP2_ALIAS[network];
+  if (legacy) return legacy;
   if (network.includes(":")) return network;
   return SLUG_TO_CAIP2[network.toLowerCase()] ?? network;
 }
@@ -2577,6 +2586,53 @@ function encodeBase642(str) {
 }
 
 // src/policy.ts
+var DENOM_PRECISION = MAX_DECIMALS;
+var BUILTIN_DENOMS = {
+  USDC: "USD",
+  USDT: "USD",
+  USD1: "USD",
+  FDUSD: "USD",
+  RLUSD: "USD",
+  EURC: "EUR"
+};
+function denomOf(symbol, asset, policy) {
+  if (asset === "native") return void 0;
+  const norm = (v) => typeof v === "string" && v.trim() !== "" ? v.trim().toUpperCase() : void 0;
+  const override = policy?.denomFor;
+  if (override && typeof override === "object") {
+    if (asset && asset in override) {
+      const d = norm(override[asset]);
+      if (d) return d;
+    }
+    if (symbol) {
+      const hit = Object.entries(override).find(([k]) => k.trim().toUpperCase() === symbol.trim().toUpperCase());
+      if (hit) {
+        const d = norm(hit[1]);
+        if (d) return d;
+      }
+    }
+  }
+  if (symbol) {
+    const builtin = BUILTIN_DENOMS[symbol.trim().toUpperCase()];
+    if (builtin) return builtin;
+  }
+  return void 0;
+}
+function scaleToDenom(amountBase, decimals) {
+  if (!Number.isSafeInteger(decimals) || decimals < 0 || decimals > DENOM_PRECISION) return null;
+  return amountBase * 10n ** BigInt(DENOM_PRECISION - decimals);
+}
+function capForDenom(caps, denom) {
+  if (!caps || typeof caps !== "object") return void 0;
+  const target = denom.trim().toUpperCase();
+  let best;
+  for (const [k, v] of Object.entries(caps)) {
+    if (typeof k !== "string" || typeof v !== "string") continue;
+    if (k.trim().toUpperCase() !== target) continue;
+    if (best === void 0 || Number(v) < Number(best)) best = v;
+  }
+  return best;
+}
 var ALLOW = { allowed: true };
 var deny = (code, reason) => ({
   allowed: false,
@@ -2660,6 +2716,34 @@ function evaluatePolicy(intent, policy, spentForAssetBase, ctx) {
       );
     }
   }
+  if (ctx && policy.maxTotalPerDenom) {
+    const denom = denomOf(intent.symbol, intent.asset, policy);
+    const capStr = denom ? capForDenom(policy.maxTotalPerDenom, denom) : void 0;
+    if (denom && capStr !== void 0) {
+      const thisScaled = scaleToDenom(intent.amountBase, intent.decimals);
+      if (thisScaled === null) {
+        return deny(
+          "MAX_TOTAL_DENOM",
+          `token for ${denom} has more than ${DENOM_PRECISION} decimals \u2014 refusing to count it toward policy.maxTotalPerDenom.${denom} on trust (it can't be summed safely).`
+        );
+      }
+      const capScaled = floorUnits(capStr, DENOM_PRECISION);
+      if ((ctx.spentInDenomScaled ?? 0n) + thisScaled > capScaled) {
+        return deny(
+          "MAX_TOTAL_DENOM",
+          `this payment would push total ${denom} spend past policy.maxTotalPerDenom.${denom} (${capStr}) \u2014 summed across every ${denom} token and chain.`
+        );
+      }
+    }
+  }
+  if (ctx && policy.maxPayments !== void 0) {
+    if ((ctx.paymentCount ?? 0) + 1 > policy.maxPayments) {
+      return deny(
+        "MAX_PAYMENTS",
+        `this payment would exceed policy.maxPayments (${policy.maxPayments}); already settled ${ctx.paymentCount ?? 0}.`
+      );
+    }
+  }
   if (ctx && policy.windowTotal !== void 0 && policy.windowSeconds !== void 0) {
     const cap = floorUnits(policy.windowTotal, intent.decimals);
     if (ctx.spentInWindowBase + intent.amountBase > cap) {
@@ -2669,6 +2753,14 @@ function evaluatePolicy(intent, policy, spentForAssetBase, ctx) {
       );
     }
   }
+  if (ctx && policy.maxPaymentsPerWindow !== void 0 && policy.windowSeconds !== void 0) {
+    if ((ctx.paymentCountInWindow ?? 0) + 1 > policy.maxPaymentsPerWindow) {
+      return deny(
+        "WINDOW_COUNT",
+        `this payment would exceed policy.maxPaymentsPerWindow (${policy.maxPaymentsPerWindow}) within the last ${policy.windowSeconds}s.`
+      );
+    }
+  }
   return ALLOW;
 }
 
@@ -2677,37 +2769,135 @@ var keyFor = (network, asset) => `${network}|${asset}`;
 var SpendLedger = class {
   records = [];
   buckets = /* @__PURE__ */ new Map();
+  /** Per-denomination running total, scaled to {@link DENOM_PRECISION}. Keyed by the
+   *  UPPERCASE denomination so lookups are case-insensitive. */
+  denomTotals = /* @__PURE__ */ new Map();
+  /** Threshold keys already warned (`warnAtFraction` fires once per crossing per cap).
+   *  Lives on the LEDGER — not the client — so clients SHARING one (a cross-chain
+   *  MultiChainPayer) dedupe together: a denomination/count threshold fires once across the
+   *  whole shared budget, not once per chain. */
+  warned = /* @__PURE__ */ new Set();
+  store;
   /**
    * Session clock origin (epoch-ms) — process/session start = ledger
    * construction. In-memory; a new process is a new session. The client reads it
    * to compute the `ttlSeconds` deadline and the rolling-window slice.
    */
   sessionStart = Date.now();
-  /** Record a settled payment. `decimals` is the TRUE token decimals (for the
-   *  per-asset running total used by maxTotal + the formatted summary). */
-  record(r, decimals) {
-    this.records.push(r);
-    const key = keyFor(r.network, r.asset);
+  /**
+   * @param store Optional durable {@link SpendStore}. When supplied, the ledger
+   *   HYDRATES from `store.load()` here (so prior spend resumes after a restart) and
+   *   `append()`s every settled payment. A throwing/absent store fails SAFE to an
+   *   empty in-memory ledger — it never blocks construction (ERRORS.md: never throw).
+   */
+  constructor(store) {
+    this.store = store;
+    if (store) {
+      let seed = [];
+      try {
+        seed = store.load() ?? [];
+      } catch {
+        seed = [];
+      }
+      for (const r of seed) this.ingest(r, r?.decimals ?? 0, r?.denom);
+    }
+  }
+  /**
+   * A record is safe to tally iff its `amountBase` is a non-negative integer STRING and its
+   * `decimals` is an integer in `[0, MAX_DECIMALS]`. The live `record()` path always passes
+   * (the client validated the quote), but a hydrated record comes from an UNTRUSTED store
+   * (a tampered/corrupt/future-version JSONL line), so we gate it here — a bad record is
+   * dropped rather than allowed to throw `BigInt(...)`/`formatUnits(...)` later and brick a
+   * read or the constructor.
+   */
+  isTallyable(r, decimals) {
+    return !!r && typeof r.amountBase === "string" && /^\d+$/.test(r.amountBase) && Number.isInteger(decimals) && decimals >= 0 && decimals <= MAX_DECIMALS;
+  }
+  /** Apply a record to the in-memory tallies (records + per-asset bucket + denom total).
+   *  Shared by {@link record} and constructor hydration; does NOT persist. Returns the
+   *  stored record, or `null` when the record is corrupt and was skipped. */
+  ingest(r, decimals, denom) {
+    if (!this.isTallyable(r, decimals)) return null;
+    const denomStr = typeof denom === "string" && denom.trim() !== "" ? denom : void 0;
+    const rec = { ...r, decimals, ...denomStr ? { denom: denomStr } : {} };
+    this.records.push(rec);
+    const key = keyFor(rec.network, rec.asset);
     const bucket = this.buckets.get(key);
     if (bucket) {
-      bucket.total += BigInt(r.amountBase);
+      bucket.total += BigInt(rec.amountBase);
       bucket.count += 1;
-      if (!bucket.symbol && r.symbol) bucket.symbol = r.symbol;
+      if (!bucket.symbol && rec.symbol) bucket.symbol = rec.symbol;
     } else {
       this.buckets.set(key, {
-        network: r.network,
-        asset: r.asset,
-        symbol: r.symbol,
+        network: rec.network,
+        asset: rec.asset,
+        symbol: rec.symbol,
         decimals,
-        total: BigInt(r.amountBase),
+        total: BigInt(rec.amountBase),
         count: 1
       });
     }
+    if (denomStr) {
+      const scaled = scaleToDenom(BigInt(rec.amountBase), decimals);
+      if (scaled !== null) {
+        const k = denomStr.toUpperCase();
+        this.denomTotals.set(k, (this.denomTotals.get(k) ?? 0n) + scaled);
+      }
+    }
+    return rec;
+  }
+  /** Record a settled payment. `decimals` is the TRUE token decimals (for the
+   *  per-asset running total + the formatted summary). `denom` is the unit-of-account
+   *  the payment counts toward in the grand total (or omit for none). Persists to the
+   *  {@link SpendStore} when one is configured (a failed append never throws). */
+  record(r, decimals, denom) {
+    const rec = this.ingest(r, decimals, denom);
+    if (rec && this.store) {
+      try {
+        this.store.append(rec);
+      } catch {
+      }
+    }
   }
   /** Running total (base units) already spent on this (network, asset). */
   totalFor(network, asset) {
     return this.buckets.get(keyFor(network, asset))?.total ?? 0n;
   }
+  /**
+   * Running grand total for a DENOMINATION, scaled to {@link DENOM_PRECISION} (so
+   * tokens of different decimals add up exactly). Summed across every token of that
+   * denomination and every chain this ledger has seen. Powers `maxTotalPerDenom`.
+   * `0n` for a denomination never spent on. Case-insensitive.
+   */
+  totalForDenom(denom) {
+    return this.denomTotals.get(denom.toUpperCase()) ?? 0n;
+  }
+  /** Total number of settled payments (across every chain + token). Powers `maxPayments`. */
+  count() {
+    return this.records.length;
+  }
+  /** Mark a `warnAtFraction` threshold key as fired; returns `true` the FIRST time (so the
+   *  caller emits the `budget-threshold` event once) and `false` thereafter. Shared across
+   *  every client on this ledger, so a cross-chain threshold fires once for the whole budget. */
+  markWarned(key) {
+    if (this.warned.has(key)) return false;
+    this.warned.add(key);
+    return true;
+  }
+  /**
+   * Number of settled payments whose `at` (ISO) is at or after `sinceMs` (epoch-ms),
+   * across every chain + token. Backs the rolling payment-count cap
+   * (`maxPaymentsPerWindow`, `sinceMs = now - windowSeconds*1000`). Linear scan —
+   * negligible at agent-session cardinality and only when a window count cap is set.
+   */
+  countSince(sinceMs) {
+    let n = 0;
+    for (const r of this.records) {
+      const t = Date.parse(r.at);
+      if (Number.isNaN(t) || t >= sinceMs) n += 1;
+    }
+    return n;
+  }
   /**
    * Sum of base-unit amounts for (network, asset) whose record `at` (ISO
    * timestamp) is at or after `sinceMs` (epoch-ms). Backs the rolling window
@@ -2718,9 +2908,9 @@ var SpendLedger = class {
   totalSince(network, asset, sinceMs) {
     let sum = 0n;
     for (const r of this.records) {
-      if (r.network === network && r.asset === asset && Date.parse(r.at) >= sinceMs) {
-        sum += BigInt(r.amountBase);
-      }
+      if (r.network !== network || r.asset !== asset) continue;
+      const t = Date.parse(r.at);
+      if (Number.isNaN(t) || t >= sinceMs) sum += BigInt(r.amountBase);
     }
     return sum;
   }
@@ -2740,6 +2930,14 @@ var SpendLedger = class {
       totalBase: b.total
     }));
   }
+  /**
+   * The per-denomination grand totals, as read-only tuples — `denom` and the running
+   * `totalScaled` (at {@link DENOM_PRECISION}). Lets the client compose the grand-total
+   * budget view; the cap math lives in the client. A never-spent denomination is absent.
+   */
+  denomBuckets() {
+    return [...this.denomTotals.entries()].map(([denom, totalScaled]) => ({ denom, totalScaled }));
+  }
   /** An immutable snapshot of all spend so far. */
   summary() {
     return {
@@ -2753,6 +2951,12 @@ var SpendLedger = class {
         totalFormatted: formatUnits(b.total, b.decimals),
         count: b.count
       })),
+      byDenom: [...this.denomTotals.entries()].map(([denom, scaled]) => ({
+        denom,
+        totalScaled: scaled.toString(),
+        totalFormatted: formatUnits(scaled, DENOM_PRECISION),
+        count: this.records.filter((r) => r.denom?.toUpperCase() === denom).length
+      })),
       records: [...this.records]
     };
   }
@@ -2771,9 +2975,14 @@ var PipRailClient = class {
   maxRetries;
   retryTimeoutMs;
   onEvent;
-  // Per-asset tally of everything this client has paid (powers spent() and the
-  // policy's maxTotal cap).
-  ledger = new SpendLedger();
+  // Per-asset (+ per-denomination + count) tally of everything this client has paid —
+  // powers spent()/budget() and the maxTotal/maxTotalPerDenom/maxPayments caps. Either
+  // its own (optionally store-backed) ledger, or a SHARED one injected so the grand
+  // total + count caps span several chains (MultiChainPayer.fromWallets).
+  ledger;
+  // `warnAtFraction` threshold dedup lives on the LEDGER (`ledger.markWarned`), so clients
+  // sharing one ledger (a cross-chain MultiChainPayer) fire each threshold once for the whole
+  // shared budget — not once per chain.
   // Resolved lazily on first request — this is what lets Solana (and future
   // families) auto-mount with no setup call.
   bound;
@@ -2782,8 +2991,15 @@ var PipRailClient = class {
     this.maxRetries = Math.max(1, opts.maxPaymentRetries ?? 3);
     this.retryTimeoutMs = opts.retryTimeoutMs ?? 3e4;
     this.onEvent = opts.onEvent ?? (() => void 0);
+    if (opts.ledger && opts.spendStore) {
+      throw new TypeError(
+        "Pass either `ledger` (a shared SpendLedger) or `spendStore`, not both \u2014 a shared ledger already owns its store."
+      );
+    }
+    this.ledger = opts.ledger ?? new SpendLedger(opts.spendStore);
     this.assertPolicyAmountCaps(opts.policy);
     this.assertPolicyTimeOptions(opts.policy);
+    this.assertPolicySpendControls(opts.policy);
   }
   /**
    * Fail LOUDLY at construction on a malformed amount cap — a security boundary
@@ -2804,6 +3020,65 @@ var PipRailClient = class {
         );
       }
     }
+    if (policy.maxTotalPerDenom !== void 0) {
+      const m = policy.maxTotalPerDenom;
+      const proto = m && typeof m === "object" ? Object.getPrototypeOf(m) : false;
+      if (!m || typeof m !== "object" || Array.isArray(m) || proto !== Object.prototype && proto !== null) {
+        throw new TypeError(
+          `policy.maxTotalPerDenom must be a plain { DENOM: amount } object (e.g. { USD: '20.00' }); got ${JSON.stringify(policy.maxTotalPerDenom)}.`
+        );
+      }
+      for (const [denom, v] of Object.entries(policy.maxTotalPerDenom)) {
+        if (denom.trim() === "") {
+          throw new TypeError("policy.maxTotalPerDenom has a blank denomination key.");
+        }
+        if (typeof v !== "string" || !/^\d+(\.\d+)?$/.test(v)) {
+          throw new TypeError(
+            `policy.maxTotalPerDenom.${denom} must be a non-negative decimal string (e.g. '20.00'); got ${JSON.stringify(v)}.`
+          );
+        }
+      }
+    }
+    if (policy.denomFor !== void 0) {
+      const m = policy.denomFor;
+      if (!m || typeof m !== "object" || Array.isArray(m)) {
+        throw new TypeError(`policy.denomFor must be a { token: DENOM } object; got ${JSON.stringify(m)}.`);
+      }
+      for (const [k, v] of Object.entries(policy.denomFor)) {
+        if (typeof v !== "string" || v.trim() === "") {
+          throw new TypeError(`policy.denomFor.${k} must be a non-empty denomination string; got ${JSON.stringify(v)}.`);
+        }
+      }
+    }
+  }
+  /**
+   * Fail LOUDLY at construction on a misconfigured count / threshold control (a
+   * programmer error → `TypeError`): payment counts must be positive safe integers,
+   * `maxPaymentsPerWindow` needs `windowSeconds` (it shares the window), and
+   * `warnAtFraction` must be in (0, 1].
+   */
+  assertPolicySpendControls(policy) {
+    if (!policy) return;
+    for (const field of ["maxPayments", "maxPaymentsPerWindow"]) {
+      const v = policy[field];
+      if (v === void 0) continue;
+      if (!Number.isSafeInteger(v) || v <= 0) {
+        throw new TypeError(`policy.${field} must be a positive integer; got ${JSON.stringify(v)}.`);
+      }
+    }
+    if (policy.maxPaymentsPerWindow !== void 0 && policy.windowSeconds === void 0) {
+      throw new TypeError(
+        "policy.maxPaymentsPerWindow needs policy.windowSeconds (the rolling window it counts within) \u2014 set both, or neither."
+      );
+    }
+    if (policy.warnAtFraction !== void 0) {
+      const f = policy.warnAtFraction;
+      if (typeof f !== "number" || !(f > 0 && f <= 1)) {
+        throw new TypeError(
+          `policy.warnAtFraction must be a number in (0, 1] (e.g. 0.8); got ${JSON.stringify(f)}.`
+        );
+      }
+    }
   }
   /**
    * Fail LOUDLY at construction on a misconfigured time policy — a security
@@ -2818,11 +3093,17 @@ var PipRailClient = class {
     if (!policy) return;
     const hasWindowTotal = policy.windowTotal !== void 0;
     const hasWindowSeconds = policy.windowSeconds !== void 0;
-    if (hasWindowTotal !== hasWindowSeconds) {
+    const hasWindowCount = policy.maxPaymentsPerWindow !== void 0;
+    if (hasWindowTotal && !hasWindowSeconds) {
       throw new TypeError(
         "policy.windowTotal and policy.windowSeconds must be set together \u2014 a rolling-window cap can't be half-armed (set both, or neither)."
       );
     }
+    if (hasWindowSeconds && !hasWindowTotal && !hasWindowCount) {
+      throw new TypeError(
+        "policy.windowSeconds must be set together with policy.windowTotal and/or policy.maxPaymentsPerWindow \u2014 a window width alone bounds nothing."
+      );
+    }
     if (hasWindowSeconds && !(Number.isSafeInteger(policy.windowSeconds) && policy.windowSeconds > 0)) {
       throw new TypeError("policy.windowSeconds must be a positive integer number of seconds.");
     }
@@ -2834,6 +3115,14 @@ var PipRailClient = class {
         );
       }
     }
+    if (policy.expiresAt !== void 0) {
+      const at = policy.expiresAt;
+      if (!Number.isSafeInteger(at) || Math.abs(at) > 864e13) {
+        throw new TypeError(
+          `policy.expiresAt must be an absolute epoch-MILLISECONDS integer (like Date.now()); got ${JSON.stringify(at)}.`
+        );
+      }
+    }
   }
   /** Emit an observability event, never letting a throwing handler break the
    * payment flow (mirrors the server gate's `onPaid` isolation). */
@@ -2927,15 +3216,25 @@ var PipRailClient = class {
     return { quote, cost };
   }
   /** Aggregated snapshot of every payment this client has settled — total
-   *  count, cumulative spend per token, and the individual records. */
+   *  count, cumulative spend per token, cumulative spend per denomination (the
+   *  cross-token grand total), and the individual records. */
   spent() {
     return this.ledger.summary();
   }
+  /** The CONFIGURED spend policy, read back unchanged — so an agent can self-check
+   *  its WHOLE leash (caps, allowlists, time, denom + count limits) without hitting a
+   *  decline. `undefined` when no policy is set. Pure; never throws. */
+  policy() {
+    return this.opts.policy;
+  }
   /**
    * Read-only budget + time leash for a Mode-A (headless) agent — the policy IS
    * the consent, and this is how the agent SEES what's left of it before paying.
-   * Composes the in-memory ledger with the configured policy; never throws, moves
-   * no funds. PROCESS-SCOPED — every figure resets on restart (see {@link SessionBudget}).
+   * Composes the ledger with the configured policy: the per-asset money leash
+   * (`byAsset`), the cross-token GRAND TOTAL per denomination (`byDenom`, present
+   * from the start), and the payment-COUNT leash (`counts`). Never throws, moves no
+   * funds. The money/count figures persist if a `spendStore` is set; the time
+   * envelope is process-scoped (see {@link SessionBudget}).
    */
   budget() {
     const view = this.sessionView();
@@ -2946,9 +3245,54 @@ var PipRailClient = class {
         expiresAt: view?.expiresAt != null ? new Date(view.expiresAt).toISOString() : null,
         secondsRemaining: view?.secondsRemaining ?? null
       },
-      byAsset: this.remaining()
+      byAsset: this.remaining(),
+      byDenom: this.denomRemaining(),
+      counts: this.countStatus()
     };
   }
+  /**
+   * The cross-token GRAND-TOTAL leash — one row per denomination capped by
+   * `policy.maxTotalPerDenom`. Unlike `remaining()`, rows exist from the START
+   * (the cap is a single declared number, so headroom is previewable before any
+   * spend). `[]` when no `maxTotalPerDenom` is set. Pure; never throws; never a
+   * price-converted figure (tokens grouped as one unit, each 1:1).
+   */
+  denomRemaining() {
+    const caps = this.opts.policy?.maxTotalPerDenom;
+    if (!caps) return [];
+    return Object.entries(caps).map(([rawDenom, capStr]) => {
+      const denom = rawDenom.toUpperCase();
+      const spentScaled = this.ledger.totalForDenom(denom);
+      const capScaled = floorUnits(capStr, DENOM_PRECISION);
+      const remainingScaled = capScaled > spentScaled ? capScaled - spentScaled : 0n;
+      const fraction = capScaled === 0n ? spentScaled > 0n ? 1 : 0 : Number(spentScaled * 1000000n / capScaled) / 1e6;
+      return {
+        denom,
+        spentFormatted: formatUnits(spentScaled, DENOM_PRECISION),
+        capFormatted: formatUnits(capScaled, DENOM_PRECISION),
+        remainingFormatted: formatUnits(remainingScaled, DENOM_PRECISION),
+        fraction
+      };
+    });
+  }
+  /** The payment-COUNT leash — settled count so far + the configured lifetime/window
+   *  caps and what's left. Pure; never throws. */
+  countStatus() {
+    const policy = this.opts.policy;
+    const settled = this.ledger.count();
+    const out = { settled };
+    if (policy?.maxPayments !== void 0) {
+      out.lifetimeCap = policy.maxPayments;
+      out.lifetimeRemaining = Math.max(0, policy.maxPayments - settled);
+    }
+    if (policy?.maxPaymentsPerWindow !== void 0 && policy.windowSeconds !== void 0) {
+      const windowSettled = this.ledger.countSince(Date.now() - policy.windowSeconds * 1e3);
+      out.windowCap = policy.maxPaymentsPerWindow;
+      out.windowSettled = windowSettled;
+      out.windowRemaining = Math.max(0, policy.maxPaymentsPerWindow - windowSettled);
+    }
+    return out;
+  }
   /**
    * Per-(network, asset) remaining budget — ONE row per pair the ledger already
    * holds (decimals are known only after the first spend), so a fresh client with
@@ -3366,7 +3710,7 @@ var PipRailClient = class {
     const shortfall = {};
     if (!quote.withinPolicy) {
       blockers.push(
-        quote.policyCode === "SESSION_EXPIRED" || quote.policyCode === "WINDOW_TOTAL" ? "OUTSIDE_WINDOW" : "OUTSIDE_POLICY"
+        quote.policyCode === "SESSION_EXPIRED" || quote.policyCode === "WINDOW_TOTAL" || quote.policyCode === "WINDOW_COUNT" ? "OUTSIDE_WINDOW" : "OUTSIDE_POLICY"
       );
     }
     if (quote.symbolMismatch) warnings.push("SYMBOL_MISMATCH");
@@ -3445,6 +3789,11 @@ var PipRailClient = class {
         `challenge for ${accept.asset} on ${accept.network} states no valid decimals and the SDK doesn't recognise the token \u2014 refusing to price it.`
       );
     }
+    if (decimals > MAX_DECIMALS) {
+      throw new InvalidEnvelopeError(
+        `challenge for ${accept.asset} on ${accept.network} states ${decimals} decimals (> ${MAX_DECIMALS}) \u2014 refusing to price it (no real token is that deep).`
+      );
+    }
     const symbol = described?.symbol ?? accept.extra?.symbol;
     const amountFormatted = formatUnits(amountBase, decimals);
     const intent = {
@@ -3459,9 +3808,14 @@ var PipRailClient = class {
     };
     const policy = this.opts.policy;
     const hasWindow = !!policy && policy.windowTotal != null && policy.windowSeconds != null;
+    const hasWindowCount = !!policy && policy.maxPaymentsPerWindow != null && policy.windowSeconds != null;
+    const hasDenomCap = !!policy && policy.maxTotalPerDenom != null && Object.keys(policy.maxTotalPerDenom).length > 0;
+    const hasCountCap = !!policy && policy.maxPayments != null;
     const hasTimePolicy = !!policy && (policy.ttlSeconds != null || policy.expiresAt != null || hasWindow);
+    const needsCtx = hasTimePolicy || hasWindowCount || hasDenomCap || hasCountCap;
+    const denom = hasDenomCap ? denomOf(intent.symbol, intent.asset, policy) : void 0;
     const now = Date.now();
-    const ctx = hasTimePolicy ? {
+    const ctx = needsCtx ? {
       now,
       sessionStart: this.ledger.sessionStart,
       // Window slice ONLY when BOTH fields are set — never a `?? 0` width.
@@ -3469,7 +3823,12 @@ var PipRailClient = class {
         accept.network,
         accept.asset,
         now - policy.windowSeconds * 1e3
-      ) : 0n
+      ) : 0n,
+      // Running grand total on this intent's denomination, across the (shared) ledger.
+      spentInDenomScaled: denom ? this.ledger.totalForDenom(denom) : 0n,
+      // Settled-payment counts (lifetime + window) for the count caps.
+      paymentCount: hasCountCap ? this.ledger.count() : 0,
+      paymentCountInWindow: hasWindowCount ? this.ledger.countSince(now - policy.windowSeconds * 1e3) : 0
     } : void 0;
     const decision = evaluatePolicy(
       intent,
@@ -3505,9 +3864,11 @@ var PipRailClient = class {
   async authorize(quote) {
     if (!quote.withinPolicy) {
       const reason = `Payment refused by policy: ${quote.policyReason ?? "not allowed"}`;
-      const reasonCode = reasonCodeForPolicy(quote.policyCode);
-      this.safeEmit({ kind: "payment-failed", reason, code: reasonCode });
-      throw new PaymentDeclinedError(reason, { reasonCode });
+      this.refuse(reason, {
+        reasonCode: reasonCodeForPolicy(quote.policyCode),
+        policyCode: quote.policyCode,
+        quote
+      });
     }
     const hook = this.opts.onBeforePay;
     if (!hook) return;
@@ -3515,32 +3876,125 @@ var PipRailClient = class {
     try {
       approved = await hook(quote);
     } catch (err) {
-      const reason = "onBeforePay threw \u2014 refusing to pay.";
-      this.safeEmit({ kind: "payment-failed", reason, code: "APPROVAL" });
-      throw new PaymentDeclinedError(reason, { cause: err, reasonCode: "APPROVAL" });
+      this.refuse("onBeforePay threw \u2014 refusing to pay.", { reasonCode: "APPROVAL", quote, cause: err });
     }
     if (!approved) {
       const reason = `onBeforePay declined ${quote.amountFormatted} ${quote.symbol ?? ""}`.trimEnd() + ` on ${quote.network}.`;
-      this.safeEmit({ kind: "payment-failed", reason, code: "APPROVAL" });
-      throw new PaymentDeclinedError(reason, { reasonCode: "APPROVAL" });
+      this.refuse(reason, { reasonCode: "APPROVAL", quote });
     }
   }
-  /** Record a settled payment in the ledger (true decimals for the running total). */
+  /**
+   * Refuse a payment BEFORE any send: emit BOTH the legacy `payment-failed` (so existing
+   * `onEvent` consumers are unaffected) AND the richer, dedicated `payment-declined`
+   * (typed reasonCode + fine PolicyDenyCode + the quote + a budget snapshot), then throw
+   * the typed {@link PaymentDeclinedError}. Returns `never` so callers' control flow is
+   * exhaustive.
+   */
+  refuse(reason, opts) {
+    this.safeEmit({ kind: "payment-failed", reason, ...opts.reasonCode ? { code: opts.reasonCode } : {} });
+    this.safeEmit({
+      kind: "payment-declined",
+      reason,
+      ...opts.reasonCode ? { reasonCode: opts.reasonCode } : {},
+      ...opts.policyCode ? { code: opts.policyCode } : {},
+      ...opts.quote ? { quote: opts.quote } : {},
+      budget: this.budget()
+    });
+    throw new PaymentDeclinedError(reason, {
+      ...opts.reasonCode ? { reasonCode: opts.reasonCode } : {},
+      ...opts.cause !== void 0 ? { cause: opts.cause } : {}
+    });
+  }
+  /** Record a settled payment in the ledger (TRUE decimals for the running total + the
+   *  denomination it counts toward in the grand total). Then fire the `onSpend` callback
+   *  with the record + the post-payment budget, and emit any `warnAtFraction` thresholds
+   *  this payment just crossed. All observability is isolated — a throwing hook never
+   *  affects the (already-settled) payment. */
   recordSpend(quote, ref) {
-    this.ledger.record(
-      {
-        url: quote.url,
-        host: hostOf2(quote.url),
-        network: quote.network,
-        asset: quote.asset,
-        amountBase: quote.amount,
-        amountFormatted: quote.amountFormatted,
-        ...quote.symbol ? { symbol: quote.symbol } : {},
-        ref,
-        at: (/* @__PURE__ */ new Date()).toISOString()
-      },
-      quote.decimals
-    );
+    const denom = denomOf(quote.symbol, quote.asset, this.opts.policy);
+    const record = {
+      url: quote.url,
+      host: hostOf2(quote.url),
+      network: quote.network,
+      asset: quote.asset,
+      amountBase: quote.amount,
+      amountFormatted: quote.amountFormatted,
+      ...quote.symbol ? { symbol: quote.symbol } : {},
+      decimals: quote.decimals,
+      ...denom ? { denom } : {},
+      ref,
+      at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.ledger.record(record, quote.decimals, denom);
+    const budget = this.budget();
+    if (this.opts.onSpend) {
+      try {
+        this.opts.onSpend(record, budget);
+      } catch {
+      }
+    }
+    this.emitThresholds(budget);
+  }
+  /**
+   * Emit a `budget-threshold` event for each cap whose used-fraction just reached
+   * `policy.warnAtFraction` — the early warning before a hard decline. Fires ONCE per
+   * crossing per cap (deduped on the shared ledger via `markWarned`, so a cross-chain
+   * threshold fires once for the whole budget, not once per chain). No-op when no
+   * `warnAtFraction` is set. Reads the just-computed {@link SessionBudget}; isolated (safeEmit).
+   */
+  emitThresholds(budget) {
+    const frac = this.opts.policy?.warnAtFraction;
+    if (frac === void 0) return;
+    const fire = (scope, label, spentFormatted, capFormatted, fraction) => {
+      if (fraction < frac) return;
+      if (!this.ledger.markWarned(`${scope}:${label}`)) return;
+      this.safeEmit({ kind: "budget-threshold", scope, label, spentFormatted, capFormatted, fraction });
+    };
+    for (const r of budget.byAsset) {
+      if (r.capBase === void 0) continue;
+      const cap = BigInt(r.capBase);
+      const spent = BigInt(r.spentBase);
+      const fraction = cap === 0n ? spent > 0n ? 1 : 0 : Number(spent * 1000000n / cap) / 1e6;
+      fire(
+        "asset",
+        `${r.symbol ?? r.asset} on ${r.network}`,
+        formatUnits(spent, r.decimals),
+        formatUnits(cap, r.decimals),
+        fraction
+      );
+    }
+    for (const d of budget.byDenom) {
+      fire("denom", d.denom, d.spentFormatted, d.capFormatted, d.fraction);
+    }
+    const policy = this.opts.policy;
+    if (policy?.windowTotal !== void 0 && policy.windowSeconds !== void 0) {
+      const since = Date.now() - policy.windowSeconds * 1e3;
+      for (const r of budget.byAsset) {
+        const cap = floorUnits(policy.windowTotal, r.decimals);
+        const spent = this.ledger.totalSince(r.network, r.asset, since);
+        const fraction = cap === 0n ? spent > 0n ? 1 : 0 : Number(spent * 1000000n / cap) / 1e6;
+        fire(
+          "window",
+          `${r.symbol ?? r.asset} on ${r.network}`,
+          formatUnits(spent, r.decimals),
+          formatUnits(cap, r.decimals),
+          fraction
+        );
+      }
+    }
+    const c = budget.counts;
+    if (c.lifetimeCap !== void 0 && c.lifetimeCap > 0) {
+      fire("count", "maxPayments", String(c.settled), String(c.lifetimeCap), c.settled / c.lifetimeCap);
+    }
+    if (c.windowCap !== void 0 && c.windowCap > 0 && c.windowSettled !== void 0) {
+      fire(
+        "window-count",
+        "maxPaymentsPerWindow",
+        String(c.windowSettled),
+        String(c.windowCap),
+        c.windowSettled / c.windowCap
+      );
+    }
   }
   async payAndConfirm(net, wallet, accept) {
     if (!this.supportsNetwork(net, accept.network)) {
@@ -3838,8 +4292,11 @@ function reasonCodeForPolicy(code) {
     case "SESSION_EXPIRED":
       return "SESSION_EXPIRED";
     case "WINDOW_TOTAL":
+    case "WINDOW_COUNT":
       return "OUTSIDE_WINDOW";
     case "MAX_TOTAL":
+    case "MAX_TOTAL_DENOM":
+    case "MAX_PAYMENTS":
       return "BUDGET";
     case void 0:
       return void 0;
@@ -3897,6 +4354,10 @@ async function readInvalidReason(response) {
 // src/payer.ts
 var MultiChainPayer = class _MultiChainPayer {
   _clients;
+  /** True when every client shares ONE ledger (the `fromWallets` path) — so spend +
+   *  budget are read from that single source, never concatenated (which would
+   *  double-count a shared ledger). */
+  _shared;
   /**
    * Wrap an explicit, ordered set of single-chain clients — use this when a client
    * needs full control (e.g. a custom EVM chain configured by a viem `Chain`). The
@@ -3904,12 +4365,18 @@ var MultiChainPayer = class _MultiChainPayer {
    * at MOST one client per chain — two clients on the SAME network would double-count in
    * `spent()`/`budget()` and waste a plan round-trip (`fromWallets` can't produce this).
    * For the common case, prefer {@link MultiChainPayer.fromWallets}.
+   *
+   * For a cross-chain grand total / count cap via this path, build the clients with a
+   * SHARED `ledger` (`new SpendLedger(store?)` passed to each client's `ledger` option)
+   * and set `opts.shared = true` so reads come from that one ledger. `fromWallets` does
+   * this for you.
    */
-  constructor(clients) {
+  constructor(clients, opts = {}) {
     if (clients.length === 0) {
       throw new TypeError("MultiChainPayer needs at least one PipRailClient.");
     }
     this._clients = [...clients];
+    this._shared = opts.shared ?? false;
   }
   /**
    * Build one client per funded chain from a `{ chain → wallet }` map — the
@@ -3924,20 +4391,26 @@ var MultiChainPayer = class _MultiChainPayer {
    *     solana:  { key: process.env.SOLANA_SECRET! },
    *     xrpl:    { key: process.env.XRPL_SEED! },
    *   },
-   *   policy: { maxAmount: '1.00', maxTotal: '20.00', tokens: ['USDC', 'USDT'] },
+   *   // ONE budget across all three chains: $20 total + at most 100 payments.
+   *   policy: { maxAmount: '1.00', maxTotalPerDenom: { USD: '20.00' }, maxPayments: 100 },
    * })
    * const res = await payer.get('https://api.example.com/paid')  // pays on the first funded chain that can settle
    * ```
+   *
+   * Every client shares ONE {@link SpendLedger} (optionally backed by `spendStore`), so
+   * the cross-token grand total + the count caps span all chains as a single budget.
    */
   static fromWallets(opts) {
     const entries = Object.entries(opts.wallets);
     if (entries.length === 0) {
       throw new TypeError("MultiChainPayer.fromWallets needs at least one wallet.");
     }
+    const ledger = new SpendLedger(opts.spendStore);
     const clients = entries.map(
       ([chain, wallet]) => new PipRailClient({
         chain,
         wallet,
+        ledger,
         ...opts.policy ? { policy: opts.policy } : {},
         ...opts.schemes ? { schemes: opts.schemes } : {},
         ...opts.rpcUrls?.[chain] ? { rpcUrl: opts.rpcUrls[chain] } : {},
@@ -3947,7 +4420,7 @@ var MultiChainPayer = class _MultiChainPayer {
         ...opts.retryTimeoutMs != null ? { retryTimeoutMs: opts.retryTimeoutMs } : {}
       })
     );
-    return new _MultiChainPayer(clients);
+    return new _MultiChainPayer(clients, { shared: true });
   }
   /** The underlying single-chain clients, in preference order. Reach for one of
    *  these for chain-specific reads (`estimateCost`, `discoverySigner`, per-chain
@@ -4041,28 +4514,50 @@ var MultiChainPayer = class _MultiChainPayer {
   register(url, opts = {}) {
     return this._clients[0].register(url, opts);
   }
-  /** Aggregate spend across every chain — counts summed; per-(network,asset) rows
-   *  and records concatenated (no cross-chain collisions, never a cross-token sum). */
+  /**
+   * Aggregate spend across every chain. With a SHARED ledger (`fromWallets`), this reads
+   * that single ledger ONCE (its records already span every chain) — so the count and the
+   * cross-token `byDenom` grand total are correct and never double-counted. With
+   * independent clients (the explicit constructor), it concatenates: counts summed,
+   * per-(network,asset) `byAsset` + `byDenom` + records concatenated.
+   */
   spent() {
+    if (this._shared) return this._clients[0].spent();
     const summaries = this._clients.map((c) => c.spent());
     return {
       count: summaries.reduce((n, s) => n + s.count, 0),
       byAsset: summaries.flatMap((s) => s.byAsset),
+      byDenom: summaries.flatMap((s) => s.byDenom),
       records: summaries.flatMap((s) => s.records)
     };
   }
-  /** A merged budget view: every chain's per-(network,asset) remaining rows, plus the
-   *  MOST-RESTRICTIVE session time envelope across chains (the soonest deadline wins).
-   *  Mirrors {@link PipRailClient.budget}'s shape so the agent toolkit reads it
-   *  unchanged; per-chain session detail is on each `clients[i].budget()`. */
+  /**
+   * A merged budget view. With a SHARED ledger (`fromWallets`) it's the single source of
+   * truth — `byAsset`/`byDenom`/`counts` already span every chain, so the grand-total and
+   * count leashes read as ONE budget. With independent clients it merges: per-(network,
+   * asset) rows + per-denom rows concatenated, counts summed, and the MOST-RESTRICTIVE
+   * session time envelope (the soonest deadline wins). Per-chain detail is on each
+   * `clients[i].budget()`.
+   */
   budget() {
+    if (this._shared) return this._clients[0].budget();
     const budgets = this._clients.map((c) => c.budget());
     const session = budgets.map((b) => b.session).reduce((soonest, s) => {
       if (soonest.secondsRemaining == null) return s;
       if (s.secondsRemaining == null) return soonest;
       return s.secondsRemaining < soonest.secondsRemaining ? s : soonest;
     });
-    return { session, byAsset: budgets.flatMap((b) => b.byAsset) };
+    return {
+      session,
+      byAsset: budgets.flatMap((b) => b.byAsset),
+      byDenom: budgets.flatMap((b) => b.byDenom),
+      counts: { settled: budgets.reduce((n, b) => n + b.counts.settled, 0) }
+    };
+  }
+  /** The CONFIGURED spend policy (the shared policy `fromWallets` applies to every chain;
+   *  the first client's for the explicit constructor). `undefined` when none is set. */
+  policy() {
+    return this._clients[0].policy();
   }
 };
 function isBodyInit(value) {
@@ -4167,9 +4662,12 @@ function explainDecline(err) {
 }
 function formatSpendReport(summary) {
   if (summary.count === 0) return "No payments yet.";
-  return summary.byAsset.map(
+  const perAsset = summary.byAsset.map(
     (a) => `${a.totalFormatted} ${a.symbol ?? a.asset} on ${a.network} (${a.count} payment${a.count === 1 ? "" : "s"})`
   ).join("; ");
+  if (summary.byDenom.length === 0) return perAsset;
+  const grand = summary.byDenom.map((d) => `${d.totalFormatted} ${d.denom} total`).join("; ");
+  return `${perAsset} \u2014 grand total: ${grand}`;
 }
 function describeChallenge(challenge) {
   const first = challenge.accepts[0];
@@ -4248,9 +4746,11 @@ Branch on \`code\` (always reliable). Key cases:
   once (enable the exact scheme); report it, don't retry the same call blindly.
 
 ## Knowing your leash \u2014 call piprail_budget
-piprail_budget tells you how much budget and time you have left, per
-(network, asset), plus your spend so far. Read-only; moves no funds. Use it in
-Mode A to self-check before paying.
+piprail_budget tells you how much budget and time you have left: per (network,
+asset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much
+USD you can still spend across every stablecoin and chain), the payment-count
+leash, the session time envelope, your spend so far, and the configured policy
+read back. Read-only; moves no funds. Use it in Mode A to self-check before paying.
 
 ## Two modes
 - Mode A (headless, default): you run FREE inside a pre-set budget + time
@@ -4261,10 +4761,15 @@ Mode A to self-check before paying.
   do NOT retry it as if it were a transient error.
 
 ## Hard facts
-- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014
-  budgets aren't summed across tokens (no price oracle).
-- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart
-  (a convenience, not a durable ledger).
+- Per-payment + per-(network, asset) caps always apply. A cross-token GRAND TOTAL per
+  denomination (maxTotalPerDenom, e.g. "$20 across every USD stablecoin + chain") is
+  OPTIONAL \u2014 it sums tokens declared as one unit, each 1:1; it is NOT a price oracle and
+  never prices a volatile native coin. Payment-COUNT caps (maxPayments / per-window) also
+  span every chain + token.
+- The time envelope lives IN-MEMORY for THIS process (resets on restart). The money + count
+  totals also reset on restart UNLESS a durable spend store is configured \u2014 then they resume.
+- A refusal arrives as declined:true with a reasonCode; 'BUDGET' covers the lifetime, denom,
+  and count caps; 'OUTSIDE_WINDOW' covers both the rolling money and rolling count windows.
 `;
 function agentGuide() {
   return PIPRAIL_AGENT_GUIDE;
@@ -4579,11 +5084,11 @@ function paymentTools(client) {
     },
     {
       name: "piprail_budget",
-      description: "Read how much of your spend budget and time leash is left \u2014 per (network, asset) remaining, the session time envelope, and your spend so far. Use it in Mode A (headless) to self-check BEFORE paying, so you never discover the leash by hitting a decline. Read-only; moves no funds. NOTE: totals and the time envelope are in-memory for THIS process and reset on restart.",
+      description: "Read how much of your spend budget and time leash is left \u2014 per (network, asset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much USD you can still spend across every stablecoin and chain), the payment-count leash, the session time envelope, and your spend so far. Use it in Mode A (headless) to self-check BEFORE paying, so you never discover the leash by hitting a decline. Read-only; moves no funds. NOTE: the time envelope is in-memory for THIS process; the money/count totals persist only if a spend store is configured.",
       annotations: {
         title: "Check remaining budget",
         readOnlyHint: true,
-        // reads the in-memory ledger + policy; never pays
+        // reads the ledger + policy; never pays
         idempotentHint: true
         // a pure read
       },
@@ -4596,7 +5101,13 @@ function paymentTools(client) {
           return {
             spent,
             remaining: budget.byAsset,
+            grandTotal: budget.byDenom,
+            // cross-token spend cap per denomination (USD/EUR/…)
+            counts: budget.counts,
+            // payment-count leash (settled + lifetime/window caps)
             session: budget.session,
+            policy: client.policy() ?? null,
+            // the configured leash, read back
             report: formatSpendReport(spent)
           };
         } catch (err) {
@@ -5901,8 +6412,10 @@ async function deliverReceipt(receipt, options) {
 }
 export {
   BRAND,
+  BUILTIN_DENOMS,
   CHAINS,
   ConfirmationTimeoutError,
+  DENOM_PRECISION,
   DIRECTORY_INFO,
   EIP3009_TYPES,
   EXACT_NETWORK_SLUGS,
@@ -5932,6 +6445,7 @@ export {
   REGISTER_ATTRIBUTION,
   RecipientNotReadyError,
   SettlementError,
+  SpendLedger,
   UnknownTokenError,
   UnsupportedNetworkError,
   UnsupportedSchemeError,
@@ -5959,6 +6473,7 @@ export {
   createPaymentGate,
   decorateOutcome,
   deliverReceipt,
+  denomOf,
   describeChallenge,
   discoveryHeaders,
   eip3009Abi,
@@ -5972,6 +6487,7 @@ export {
   getDirectoryInfo,
   isPermit2ProxyChain,
   knownFacilitatorsFor,
+  memorySpendStore,
   normalizeNetwork,
   parseChallenge,
   parseExactPaymentHeader,