@piprail/sdk 2.8.0 → 2.10.0

package/dist/index.js

@@ -1,7 +1,14 @@
+import {
+  memorySpendStore
+} from "./chunk-SK3CB7UA.js";
+import {
+  signReceiptEvm
+} from "./chunk-3SBTJKAG.js";
 import {
   ConfirmationTimeoutError,
   InsufficientFundsError,
   InvalidEnvelopeError,
+  MAX_DECIMALS,
   MaxRetriesExceededError,
   MissingDriverError,
   NoCompatibleAcceptError,
@@ -24,7 +31,7 @@ import {
   parseUnits,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-W3HOMXOF.js";
+} from "./chunk-SC2ZYDHD.js";
 
 // src/drivers/registry.ts
 var byFamily = /* @__PURE__ */ new Map();
@@ -67,7 +74,7 @@ function resolveNetwork(opts) {
 }
 
 // src/drivers/evm/index.ts
-import { BaseError, createPublicClient, erc20Abi as erc20Abi4, getAddress as getAddress4, http as http2, isAddress } from "viem";
+import { BaseError, createPublicClient, erc20Abi as erc20Abi4, getAddress as getAddress5, http as http2, isAddress } from "viem";
 
 // src/drivers/evm/chains.ts
 import { defineChain } from "viem";
@@ -1353,6 +1360,361 @@ async function verifyAndSettlePermit2Evm(input) {
   };
 }
 
+// src/drivers/evm/upto.ts
+import {
+  getAddress as getAddress4,
+  recoverTypedDataAddress as recoverTypedDataAddress3
+} from "viem";
+var X402_UPTO_PERMIT2_PROXY = "0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002";
+var UPTO_PROXY_CHAIN_IDS = /* @__PURE__ */ new Set([
+  1,
+  // Ethereum
+  8453,
+  // Base
+  42161,
+  // Arbitrum
+  10,
+  // Optimism
+  137,
+  // Polygon
+  56
+  // BNB
+]);
+function isUptoProxyChain(chainId) {
+  return UPTO_PROXY_CHAIN_IDS.has(chainId);
+}
+var PERMIT2_UPTO_WITNESS_TYPES = {
+  PermitWitnessTransferFrom: PERMIT2_WITNESS_TYPES.PermitWitnessTransferFrom,
+  TokenPermissions: PERMIT2_WITNESS_TYPES.TokenPermissions,
+  Witness: [
+    { name: "to", type: "address" },
+    { name: "facilitator", type: "address" },
+    { name: "validAfter", type: "uint256" }
+  ]
+};
+var x402UptoProxyAbi = [
+  {
+    type: "function",
+    name: "settle",
+    stateMutability: "nonpayable",
+    outputs: [],
+    inputs: [
+      {
+        name: "permit",
+        type: "tuple",
+        components: [
+          {
+            name: "permitted",
+            type: "tuple",
+            components: [
+              { name: "token", type: "address" },
+              { name: "amount", type: "uint256" }
+            ]
+          },
+          { name: "nonce", type: "uint256" },
+          { name: "deadline", type: "uint256" }
+        ]
+      },
+      { name: "amount", type: "uint256" },
+      { name: "owner", type: "address" },
+      {
+        name: "witness",
+        type: "tuple",
+        components: [
+          { name: "to", type: "address" },
+          { name: "facilitator", type: "address" },
+          { name: "validAfter", type: "uint256" }
+        ]
+      },
+      { name: "signature", type: "bytes" }
+    ]
+  }
+];
+function shorten3(msg) {
+  const oneLine = msg.replace(/\s+/g, " ").trim();
+  return oneLine.length > 200 ? `${oneLine.slice(0, 200)}\u2026` : oneLine;
+}
+function randomPermit2Nonce2() {
+  const g = globalThis.crypto;
+  if (!g?.getRandomValues) {
+    throw new UnsupportedSchemeError(
+      "this runtime lacks Web Crypto (globalThis.crypto.getRandomValues); the upto rail needs a CSPRNG nonce."
+    );
+  }
+  const raw = new Uint8Array(32);
+  g.getRandomValues(raw);
+  return BigInt(`0x${[...raw].map((b) => b.toString(16).padStart(2, "0")).join("")}`);
+}
+async function payUptoEvm(input) {
+  const { publicClient, walletClient, account, chainId, chain, accept } = input;
+  let code;
+  try {
+    code = await publicClient.getCode({ address: account.address });
+  } catch {
+    code = void 0;
+  }
+  if (code && code !== "0x") {
+    throw new UnsupportedSchemeError(
+      `upto buyer rail requires an EOA signer; ${account.address} is a contract / EIP-1271 / EIP-7702-delegated account. Pay via onchain-proof.`
+    );
+  }
+  const facilitatorAddress = accept.extra?.facilitatorAddress;
+  if (typeof facilitatorAddress !== "string" || facilitatorAddress.length === 0) {
+    throw new UnsupportedSchemeError(
+      `upto: the rail carries no extra.facilitatorAddress to bind into witness.facilitator \u2014 refusing to sign.`
+    );
+  }
+  const token = getAddress4(accept.asset);
+  const payTo = getAddress4(accept.payTo);
+  const facilitator = getAddress4(facilitatorAddress);
+  const value = BigInt(accept.amount);
+  const approvalTx = await ensurePermit2Allowance({
+    publicClient,
+    walletClient,
+    account,
+    chain,
+    token,
+    amount: value
+  });
+  const nonce = randomPermit2Nonce2();
+  const deadline = BigInt(Math.floor(Date.now() / 1e3) + accept.maxTimeoutSeconds);
+  const validAfter = 0n;
+  const spender = getAddress4(X402_UPTO_PERMIT2_PROXY);
+  const from = account.address;
+  const signature = await walletClient.signTypedData({
+    account,
+    domain: { name: "Permit2", chainId, verifyingContract: PERMIT2_ADDRESS },
+    types: PERMIT2_UPTO_WITNESS_TYPES,
+    primaryType: "PermitWitnessTransferFrom",
+    message: {
+      permitted: { token, amount: value },
+      spender,
+      nonce,
+      deadline,
+      witness: { to: payTo, facilitator, validAfter }
+    }
+  });
+  const permit2Authorization = {
+    permitted: { token, amount: value.toString() },
+    from,
+    spender,
+    nonce: nonce.toString(),
+    deadline: deadline.toString(),
+    witness: { to: payTo, facilitator, validAfter: validAfter.toString() }
+  };
+  return {
+    payload: { signature, permit2Authorization },
+    payerFrom: from,
+    nonce: nonce.toString(),
+    ...approvalTx ? { approvalTx } : {}
+  };
+}
+function resolveUptoRailEvm(input) {
+  const { asset, relayerAddress, proxySupported, domain } = input;
+  if (asset === "native") return null;
+  if (!proxySupported()) return null;
+  const extra = { facilitatorAddress: getAddress4(relayerAddress) };
+  if (domain) {
+    extra.name = domain.name;
+    extra.version = domain.version;
+  }
+  return { method: "permit2-upto", extra };
+}
+async function verifyAndSettleUptoEvm(input) {
+  const { publicClient, walletClient, account, chain, payload, accept, settleAmount } = input;
+  const token = getAddress4(accept.asset);
+  const payTo = getAddress4(accept.payTo);
+  const maxAmount = BigInt(accept.amount);
+  const proxy = getAddress4(X402_UPTO_PERMIT2_PROXY);
+  const relayerAddress = getAddress4(account.address);
+  let from;
+  let spender;
+  let permittedToken;
+  let witnessTo;
+  let witnessFacilitator;
+  let permittedAmount;
+  let nonce;
+  let deadline;
+  let validAfter;
+  const signature = payload.signature;
+  try {
+    const pa = payload.permit2Authorization;
+    from = getAddress4(pa.from);
+    spender = getAddress4(pa.spender);
+    permittedToken = getAddress4(pa.permitted.token);
+    witnessTo = getAddress4(pa.witness.to);
+    witnessFacilitator = getAddress4(pa.witness.facilitator);
+    permittedAmount = BigInt(pa.permitted.amount);
+    nonce = BigInt(pa.nonce);
+    deadline = BigInt(pa.deadline);
+    validAfter = BigInt(pa.witness.validAfter);
+    if (!/^0x[0-9a-fA-F]+$/.test(signature)) throw new Error("signature must be hex");
+  } catch (err) {
+    return {
+      ok: false,
+      error: "signature_invalid",
+      detail: `Malformed upto authorization: ${err instanceof Error ? err.message : String(err)}.`
+    };
+  }
+  if (witnessTo !== payTo) {
+    return { ok: false, error: "wrong_recipient", detail: `Authorization pays witness.to ${witnessTo}, not ${payTo}.` };
+  }
+  if (permittedToken !== token) {
+    return { ok: false, error: "signature_invalid", detail: `Authorization permits token ${permittedToken}, not the rail's ${token}.` };
+  }
+  if (spender !== proxy) {
+    return { ok: false, error: "signature_invalid", detail: `Authorization spender ${spender} is not the x402UptoPermit2Proxy ${proxy}; it can't be settled here.` };
+  }
+  if (witnessFacilitator !== relayerAddress) {
+    return { ok: false, error: "signature_invalid", detail: `Authorization binds facilitator ${witnessFacilitator}, not this relayer ${relayerAddress}; only the bound facilitator can settle.` };
+  }
+  if (permittedAmount < maxAmount) {
+    return { ok: false, error: "amount_too_low", detail: `Permitted (signed MAX) ${permittedAmount} is below the rail max ${maxAmount}.` };
+  }
+  if (permittedAmount > maxAmount) {
+    return { ok: false, error: "upto_settle_exceeds_max", detail: `Permitted (signed MAX) ${permittedAmount} exceeds the advertised rail max ${maxAmount}; sign exactly the ceiling.` };
+  }
+  if (settleAmount < 0n) {
+    return { ok: false, error: "upto_settle_exceeds_max", detail: `Settle amount ${settleAmount} is negative.` };
+  }
+  if (settleAmount > permittedAmount) {
+    return { ok: false, error: "upto_settle_exceeds_max", detail: `Settle amount ${settleAmount} exceeds the signed MAX ${permittedAmount}.` };
+  }
+  const now = BigInt(Math.floor(Date.now() / 1e3));
+  if (deadline <= now) {
+    return { ok: false, error: "payment_expired", detail: `Permit2 deadline ${deadline} <= now ${now}.` };
+  }
+  let fromCode;
+  try {
+    fromCode = await publicClient.getCode({ address: from });
+  } catch {
+    return { ok: false, error: "tx_not_found", detail: `Could not read code at ${from} (transient RPC) \u2014 retry.` };
+  }
+  if (!(fromCode && fromCode !== "0x")) {
+    let recovered;
+    try {
+      recovered = await recoverTypedDataAddress3({
+        domain: { name: "Permit2", chainId: chain.id, verifyingContract: PERMIT2_ADDRESS },
+        types: PERMIT2_UPTO_WITNESS_TYPES,
+        primaryType: "PermitWitnessTransferFrom",
+        message: {
+          permitted: { token: permittedToken, amount: permittedAmount },
+          spender,
+          nonce,
+          deadline,
+          witness: { to: witnessTo, facilitator: witnessFacilitator, validAfter }
+        },
+        signature
+      });
+    } catch (err) {
+      return { ok: false, error: "signature_invalid", detail: `Not a valid EIP-712 signature: ${shorten3(err instanceof Error ? err.message : String(err))}.` };
+    }
+    if (recovered !== from) {
+      return { ok: false, error: "signature_invalid", detail: `Signature recovered to ${recovered}, not the authorizer ${from}.` };
+    }
+  }
+  if (settleAmount === 0n) {
+    return {
+      ok: true,
+      receipt: {
+        scheme: "upto",
+        success: true,
+        network: accept.network,
+        transaction: "",
+        asset: accept.asset,
+        amount: "0",
+        payer: from,
+        payTo: accept.payTo,
+        verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    };
+  }
+  try {
+    const word = nonce >> 8n;
+    const bit = nonce & 0xffn;
+    const bitmap = await publicClient.readContract({
+      address: PERMIT2_ADDRESS,
+      abi: permit2NonceBitmapAbi,
+      functionName: "nonceBitmap",
+      args: [from, word]
+    });
+    if ((bitmap >> bit & 1n) === 1n) {
+      return { ok: false, error: "tx_already_used", detail: `Permit2 nonce ${nonce} already used or invalidated for ${from}.` };
+    }
+  } catch {
+    return { ok: false, error: "tx_not_found", detail: "Could not read the Permit2 nonce bitmap (transient RPC) \u2014 retry." };
+  }
+  const settleArgs = [
+    { permitted: { token: permittedToken, amount: permittedAmount }, nonce, deadline },
+    settleAmount,
+    from,
+    { to: witnessTo, facilitator: witnessFacilitator, validAfter },
+    signature
+  ];
+  try {
+    await publicClient.simulateContract({
+      account,
+      address: proxy,
+      abi: x402UptoProxyAbi,
+      functionName: "settle",
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      args: settleArgs
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/nonce|invalidated|used/i.test(msg)) return { ok: false, error: "tx_already_used", detail: "Permit2 nonce is used or invalidated." };
+    if (/expired|deadline|too early|not yet/i.test(msg)) return { ok: false, error: "payment_expired", detail: shorten3(msg) };
+    if (/exceeds.*permitted|AmountExceeds/i.test(msg)) return { ok: false, error: "upto_settle_exceeds_max", detail: shorten3(msg) };
+    if (/facilitator|Unauthorized/i.test(msg)) return { ok: false, error: "signature_invalid", detail: shorten3(msg) };
+    if (/signature/i.test(msg)) return { ok: false, error: "signature_invalid", detail: shorten3(msg) };
+    return { ok: false, error: "tx_reverted", detail: `upto settle would revert: ${shorten3(msg)}` };
+  }
+  let txHash;
+  try {
+    txHash = await walletClient.writeContract({
+      account,
+      chain,
+      address: proxy,
+      abi: x402UptoProxyAbi,
+      functionName: "settle",
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      args: settleArgs
+    });
+  } catch (err) {
+    throw new SettlementError(
+      `upto settle: the merchant relayer failed to broadcast the proxy settle (${shorten3(err instanceof Error ? err.message : String(err))}). The payer's signature is still valid and its nonce unused \u2014 fund/fix the relayer and the payer can retry.`,
+      { cause: err }
+    );
+  }
+  try {
+    const confirmations = accept.extra.minConfirmations ?? 1;
+    const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash, confirmations });
+    if (receipt.status !== "success") {
+      return { ok: false, error: "tx_reverted", detail: `Settlement tx ${txHash} reverted on-chain.` };
+    }
+  } catch (err) {
+    throw new SettlementError(
+      `upto settle: broadcast ${txHash} but couldn't confirm it (${shorten3(err instanceof Error ? err.message : String(err))}).`,
+      { cause: err }
+    );
+  }
+  return {
+    ok: true,
+    receipt: {
+      scheme: "upto",
+      success: true,
+      network: accept.network,
+      transaction: txHash,
+      asset: accept.asset,
+      // The ACTUAL settled amount (≤ max) — what the buyer reads back to record metered spend.
+      amount: settleAmount.toString(),
+      payer: from,
+      payTo: accept.payTo,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+
 // src/x402.ts
 var HEADER_REQUIRED = "payment-required";
 var HEADER_SIGNATURE = "payment-signature";
@@ -1386,6 +1748,9 @@ function fromBase64Json(b64) {
     return null;
   }
 }
+function decodeBase64Json(value) {
+  return fromBase64Json(value);
+}
 function toBase64Json(value) {
   return encodeBase64(JSON.stringify(value));
 }
@@ -1401,8 +1766,15 @@ function chainIdFromNetwork(network) {
 function buildChallengeHeader(challenge) {
   return toBase64Json(challenge);
 }
-function buildReceiptHeader(receipt) {
-  return toBase64Json(receipt);
+function buildReceiptHeader(receipt, extensions) {
+  return toBase64Json(extensions ? { ...receipt, extensions } : receipt);
+}
+var EXT_OFFER_RECEIPT = "offer-receipt";
+function buildReceiptExtension(bundle) {
+  const info = { settlement: bundle.receipt, resource: bundle.resource };
+  if (typeof bundle.decimals === "number") info.decimals = bundle.decimals;
+  if (bundle.attestation) info.receipt = bundle.attestation;
+  return { [EXT_OFFER_RECEIPT]: { info } };
 }
 function buildSignatureHeader(signature) {
   return toBase64Json(signature);
@@ -1410,6 +1782,9 @@ function buildSignatureHeader(signature) {
 function buildExactSignatureHeader(input) {
   return toBase64Json({ x402Version: 2, accepted: input.accepted, payload: input.payload });
 }
+function buildUptoSignatureHeader(input) {
+  return toBase64Json({ x402Version: 2, accepted: input.accepted, payload: input.payload });
+}
 async function parseChallenge(response) {
   const headerValue = response.headers.get(HEADER_REQUIRED);
   if (headerValue) {
@@ -1429,6 +1804,27 @@ function parseReceipt(response) {
   const parsed = fromBase64Json(headerValue);
   return isValidReceipt(parsed) ? parsed : null;
 }
+function parseReceiptExtension(response) {
+  const headerValue = response.headers.get(HEADER_RESPONSE) ?? response.headers.get(HEADER_RESPONSE_V1);
+  if (!headerValue) return null;
+  const parsed = fromBase64Json(headerValue);
+  if (!parsed || typeof parsed !== "object") return null;
+  const ext = parsed.extensions;
+  const block = ext?.[EXT_OFFER_RECEIPT];
+  const info = block?.info;
+  if (!info) return null;
+  const settlement = isValidReceipt(info.settlement) ? info.settlement : isValidReceipt(info.receipt) ? info.receipt : void 0;
+  if (!settlement) return null;
+  const attestation = info.receipt && info.receipt !== settlement ? info.receipt : void 0;
+  const res = info.resource;
+  return {
+    piprail: "1",
+    receipt: settlement,
+    resource: { url: res && typeof res.url === "string" ? res.url : "" },
+    ...typeof info.decimals === "number" ? { decimals: info.decimals } : {},
+    ...attestation ? { attestation } : {}
+  };
+}
 function parseSettleResponse(response) {
   const headerValue = response.headers.get(HEADER_RESPONSE) ?? response.headers.get(HEADER_RESPONSE_V1);
   if (!headerValue) return null;
@@ -1439,11 +1835,13 @@ function parseSettleResponse(response) {
     ...typeof parsed.transaction === "string" ? { transaction: parsed.transaction } : {},
     ...typeof parsed.network === "string" ? { network: parsed.network } : {},
     ...typeof parsed.payer === "string" ? { payer: parsed.payer } : {},
-    ...typeof parsed.errorReason === "string" ? { errorReason: parsed.errorReason } : {}
+    ...typeof parsed.errorReason === "string" ? { errorReason: parsed.errorReason } : {},
+    // The upto SettleResponse's REQUIRED `amount` (actual settled atomic units) — string
+    // passthrough so the upto buyer records ACTUAL, not MAX. Absent on onchain-proof/exact.
+    ...typeof parsed.amount === "string" ? { amount: parsed.amount } : {}
   };
 }
-function parseSignatureHeader(value) {
-  const parsed = fromBase64Json(value);
+function parseSignatureObject(parsed) {
   if (!parsed || typeof parsed !== "object") return null;
   const v = parsed;
   const accepted = v.accepted;
@@ -1455,8 +1853,13 @@ function parseSignatureHeader(value) {
   }
   return parsed;
 }
+function parseSignatureHeader(value) {
+  return parseSignatureObject(fromBase64Json(value));
+}
 function parseExactPaymentHeader(value) {
-  const parsed = fromBase64Json(value);
+  return parseExactObject(fromBase64Json(value));
+}
+function parseExactObject(parsed) {
   if (!parsed || typeof parsed !== "object") return null;
   const v = parsed;
   const accepted = v.accepted ?? null;
@@ -1521,6 +1924,42 @@ function parseExactPaymentHeader(value) {
   }
   return null;
 }
+function parseUptoPaymentHeader(value) {
+  return parseUptoObject(fromBase64Json(value));
+}
+function parseUptoObject(parsed) {
+  if (!parsed || typeof parsed !== "object") return null;
+  const v = parsed;
+  const accepted = v.accepted ?? null;
+  const scheme = accepted?.scheme ?? v.scheme;
+  if (scheme !== "upto") return null;
+  const network = accepted?.network ?? v.network;
+  if (typeof network !== "string") return null;
+  const payload = v.payload;
+  if (!payload || typeof payload !== "object") return null;
+  const signature = payload.signature;
+  if (typeof signature !== "string") return null;
+  const p2 = payload.permit2Authorization;
+  if (!p2 || typeof p2 !== "object") return null;
+  const permitted = p2.permitted;
+  const witness = p2.witness;
+  if (!permitted || typeof permitted !== "object" || !witness || typeof witness !== "object") return null;
+  if (typeof permitted.token !== "string" || typeof permitted.amount !== "string") return null;
+  if (typeof witness.to !== "string" || typeof witness.facilitator !== "string" || typeof witness.validAfter !== "string") {
+    return null;
+  }
+  for (const k of ["from", "spender", "nonce", "deadline"]) {
+    if (typeof p2[k] !== "string") return null;
+  }
+  const x402Version = typeof v.x402Version === "number" ? v.x402Version : 2;
+  const asset = accepted && typeof accepted.asset === "string" ? accepted.asset : void 0;
+  const base2 = { x402Version, network, ...asset ? { asset } : {}, raw: v };
+  return {
+    ...base2,
+    method: "permit2-upto",
+    payload: { signature, permit2Authorization: p2 }
+  };
+}
 function isValidChallenge(value) {
   if (!value || typeof value !== "object") return false;
   const v = value;
@@ -1533,7 +1972,7 @@ function isValidChallenge(value) {
 function isValidReceipt(value) {
   if (!value || typeof value !== "object") return false;
   const v = value;
-  if (v.scheme !== "onchain-proof" && v.scheme !== "exact") return false;
+  if (v.scheme !== "onchain-proof" && v.scheme !== "exact" && v.scheme !== "upto") return false;
   if (typeof v.transaction !== "string" && typeof v.txHash !== "string") return false;
   if (typeof v.payer !== "string") return false;
   return true;
@@ -1611,12 +2050,12 @@ function makeEvmNetwork(resolved) {
       }
       let normalized;
       try {
-        normalized = getAddress4(asset);
+        normalized = getAddress5(asset);
       } catch {
         return null;
       }
       for (const info of Object.values(resolved.tokens)) {
-        if (getAddress4(info.address) === normalized) {
+        if (getAddress5(info.address) === normalized) {
           return { symbol: info.symbol, decimals: info.decimals };
         }
       }
@@ -1716,7 +2155,7 @@ function makeEvmNetwork(resolved) {
       let token = null;
       try {
         token = await publicClient.readContract({
-          address: getAddress4(asset),
+          address: getAddress5(asset),
           abi: erc20Abi4,
           functionName: "balanceOf",
           args: [owner]
@@ -1741,6 +2180,12 @@ function makeEvmNetwork(resolved) {
         signMessage: (message) => a.walletClient.signMessage({ account: a.account, message })
       };
     },
+    // Tier-2 service-delivery attestation (EVM-only) — sign the official offer-receipt
+    // EIP-712 RECEIPT_TYPES with the bound (payTo) wallet. Chain-independent (domain
+    // chainId is hardcoded 1); viem lives in ./receipt.ts (a lazy chunk).
+    signReceipt(wallet, input) {
+      return signReceiptEvm(wallet, input);
+    },
     async verify(ref, accept) {
       return verifyEvm({
         publicClient,
@@ -1824,6 +2269,43 @@ function makeEvmNetwork(resolved) {
         payload,
         accept
       });
+    },
+    // Standard x402 `upto` (metered) rail — EVM-Permit2 ONLY. The metered sibling of the
+    // exact trio. resolveUptoRail advertises (Permit2-only, proxy-gated, relayer = facilitator);
+    // payUpto signs the MAX with witness.facilitator bound; settleUptoSelf self-settles the actual.
+    async resolveUptoRail({ asset, relayer }) {
+      const relayerAddress = relayer._native.account.address;
+      const domain = asset === "native" ? null : await readExactDomain(publicClient, asset).catch(() => null);
+      return resolveUptoRailEvm({
+        asset,
+        relayerAddress,
+        proxySupported: () => isUptoProxyChain(resolved.chainId),
+        domain
+      });
+    },
+    async payUpto(wallet, accept) {
+      const a = wallet._native;
+      const { payload, payerFrom, nonce } = await payUptoEvm({
+        publicClient,
+        walletClient: a.walletClient,
+        account: a.account,
+        chainId: resolved.chainId,
+        chain: resolved.chain,
+        accept
+      });
+      return { payload, accepted: accept, payerFrom, nonce };
+    },
+    async settleUptoSelf({ relayer, payload, accept, settleAmount }) {
+      const a = relayer._native;
+      return verifyAndSettleUptoEvm({
+        publicClient,
+        walletClient: a.walletClient,
+        account: a.account,
+        chain: resolved.chain,
+        payload,
+        accept,
+        settleAmount
+      });
     }
   };
 }
@@ -1840,7 +2322,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-Z34OWXMO.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 +2334,7 @@ var loaders = {
   ton: async () => {
     let mod;
     try {
-      mod = await import("./ton-N7KSPSAR.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 +2346,7 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await import("./stellar-PWC4LETJ.js");
+      mod = await import("./stellar-ASP2THL2.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
@@ -1876,7 +2358,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await import("./xrpl-6B4IYRWI.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 +2370,7 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await import("./tron-WKDUQVZR.js");
+      mod = await import("./tron-BMCWN5SS.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
@@ -1900,7 +2382,7 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await import("./sui-VEOGHBYE.js");
+      mod = await import("./sui-FZIKZNVI.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
@@ -1912,7 +2394,7 @@ var loaders = {
   near: async () => {
     let mod;
     try {
-      mod = await import("./near-QV4IOZNX.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 +2406,7 @@ var loaders = {
   aptos: async () => {
     let mod;
     try {
-      mod = await import("./aptos-WMPFEASY.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 +2418,7 @@ var loaders = {
   algorand: async () => {
     let mod;
     try {
-      mod = await import("./algorand-WJL6VRXW.js");
+      mod = await import("./algorand-AA3WXKW4.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Algorand selected, but its package isn't installed. Run: npm install algosdk`,
@@ -2582,6 +3064,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,
@@ -2665,6 +3194,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) {
@@ -2674,6 +3231,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;
 }
 
@@ -2682,37 +3247,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
@@ -2723,9 +3386,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;
   }
@@ -2745,6 +3408,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 {
@@ -2758,6 +3429,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,24 +3448,41 @@ var RECIPIENT_FIX = {
   NOT_OPTED_IN: "the recipient must opt into this asset once (a 0-amount self-transfer)",
   INACTIVE: "the recipient account doesn't exist yet \u2014 fund it with the chain's base reserve to activate it"
 };
+var RECEIPT_VERIFY_WINDOW_SECONDS = 100 * 365 * 24 * 60 * 60;
 var PipRailClient = class {
   opts;
   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;
+  // The verifiable receipt from the most recent settled fetch (null if the server emitted
+  // none). Captured pure (no chain read) and surfaced via lastReceipt(); the resource URL is
+  // stamped from the URL this client actually fetched (authoritative over the gate's default).
+  lastReceiptValue = null;
   constructor(opts) {
     this.opts = opts;
     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
@@ -2809,6 +3503,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
@@ -2823,11 +3576,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.");
     }
@@ -2839,6 +3598,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). */
@@ -2848,6 +3615,129 @@ var PipRailClient = class {
     } catch {
     }
   }
+  /**
+   * Capture the verifiable receipt from a settled response (pure — no chain read), stamping
+   * the resource URL this client actually fetched (authoritative over the gate's default ''). A
+   * settled fetch with no receipt extension sets it to `null` so {@link lastReceipt} reflects the
+   * latest fetch. Never throws — a malformed header just yields `null`.
+   */
+  captureReceipt(response, url) {
+    try {
+      const parsed = parseReceiptExtension(response);
+      this.lastReceiptValue = parsed ? { ...parsed, resource: { url } } : null;
+    } catch {
+      this.lastReceiptValue = null;
+    }
+  }
+  /**
+   * The verifiable {@link PipRailReceipt} from the most recent settled `fetch` — the
+   * self-contained record the buyer KEEPS and anyone re-verifies against the chain
+   * (see {@link PipRailClient.verifyReceipt}). `null` when the last settled fetch carried
+   * no receipt (the gate's `receipts` option was off) or no payment has settled yet. Pure.
+   */
+  lastReceipt() {
+    return this.lastReceiptValue;
+  }
+  /**
+   * Re-verify ANY {@link PipRailReceipt} against the chain — the anyone-can-run primitive.
+   * Re-reads `receipt.transaction` via the receipt's own network driver and re-derives
+   * `payTo`/`asset`/`payer` from the tx, **never trusting the receipt's claims**: a forged
+   * `payTo`/`asset`/over-stated `amount` makes the driver's `verify()` fail (`ok:false`); a
+   * forged `payer` surfaces as `matchesClaims:false`. Static + WALLET-FREE — a third party
+   * verifies with only a chain + RPC, no PipRail account. **Never throws** (an RPC error or a
+   * malformed receipt → `{ ok:false, error }`). Viem-free here — the chain read happens inside
+   * the lazily-mounted family driver (the protocol layer pulls no chain libs). Durable for
+   * digest-bound families; recency-bounded for the account-watch families (see
+   * {@link ReceiptVerification}).
+   */
+  static async verifyReceipt(receipt, opts) {
+    const r = receipt?.receipt;
+    if (!r || typeof r !== "object") {
+      return { ok: false, onChain: { payTo: "", asset: "", amount: "", payer: "" }, matchesClaims: false, ageSeconds: 0, error: "tx_not_found" };
+    }
+    const claimed = { payTo: r.payTo ?? "", asset: r.asset ?? "", amount: r.amount ?? "", payer: r.payer ?? "" };
+    const ageSeconds = receiptAgeSeconds(r.verifiedAt);
+    try {
+      const chain = chainSelectorForNetwork(r.network, opts?.rpcUrl);
+      const net = await resolveNetwork2({
+        chain,
+        ...opts?.rpcUrl ? { rpcUrl: opts.rpcUrl } : {}
+      });
+      const accept = {
+        scheme: "onchain-proof",
+        network: r.network,
+        amount: r.amount,
+        asset: r.asset,
+        payTo: r.payTo,
+        maxTimeoutSeconds: RECEIPT_VERIFY_WINDOW_SECONDS,
+        extra: {
+          nonce: r.nonce ?? "",
+          // the challenge/memo nonce — REQUIRED for Template-A re-verify
+          decimals: receipt.decimals ?? 6,
+          // B10c — Stellar/XRPL/TON re-scale by it; 6 = USDC fallback
+          minConfirmations: 0,
+          amountFormatted: ""
+        }
+      };
+      const ref = familyForChain(chain) === "near" ? `${r.payer}:${r.transaction}` : r.transaction;
+      const result = await net.verify(ref, accept);
+      if (!result.ok) {
+        return { ok: false, onChain: claimed, matchesClaims: false, ageSeconds, error: result.error };
+      }
+      const oc = result.receipt;
+      const onChain = { payTo: oc.payTo, asset: oc.asset, amount: oc.amount, payer: oc.payer };
+      const matchesClaims = sameAddress(oc.payer, r.payer);
+      return { ok: true, onChain, matchesClaims, ageSeconds };
+    } catch {
+      return { ok: false, onChain: claimed, matchesClaims: false, ageSeconds, error: "tx_not_found" };
+    }
+  }
+  /**
+   * Verify the OPTIONAL Tier-2 service-delivery attestation on a {@link PipRailReceipt}
+   * — the merchant's signed proof that the resource was actually SERVED (the one thing
+   * the chain can't attest). For an EVM EIP-712 attestation this re-recovers the signer
+   * from the signature over the official `offer-receipt` typed data and checks
+   * `recover === receipt.payTo` (spec §4.5.1 / §5.5) — the classic EIP-712 footgun made
+   * safe (`recoverTypedDataAddress` returns a WRONG address rather than throwing on a bad
+   * signature, so the equality check is the real verification). A tampered signature →
+   * `{ ok:false }`, never a throw.
+   *
+   * Static + wallet-free. **Never throws** (a malformed/absent attestation, an unsupported
+   * format, or a recovery fault → `{ ok:false, reason }`). Viem-free HERE — the recover runs
+   * inside the lazily-imported EVM receipt driver (a lazy chunk), so the protocol layer pulls
+   * no chain libs. The JWS format defers to R3 (`{ ok:false, reason:'jws-not-loaded' }`).
+   */
+  static async verifyAttestation(receipt) {
+    const att = receipt?.attestation;
+    if (!att || typeof att !== "object" || typeof att.signature !== "string") {
+      return { ok: false, reason: "no-attestation" };
+    }
+    if (att.format === "jws") {
+      return { ok: false, reason: "jws-not-loaded" };
+    }
+    const r = receipt.receipt;
+    if (!r || typeof r !== "object") return { ok: false, reason: "no-receipt" };
+    const payload = att.payload ?? {};
+    const network = typeof payload.network === "string" ? payload.network : r.network;
+    const resourceUrl = typeof payload.resourceUrl === "string" ? payload.resourceUrl : receipt.resource?.url ?? "";
+    const payer = typeof payload.payer === "string" ? payload.payer : r.payer;
+    const issuedAt = typeof payload.issuedAt === "number" ? payload.issuedAt : receiptIssuedAtSeconds(r.verifiedAt);
+    const transaction = typeof payload.transaction === "string" ? payload.transaction : r.transaction ?? "";
+    try {
+      const { verifyReceiptAttestationEvm } = await import("./receipt-NNEID77X.js");
+      return await verifyReceiptAttestationEvm({
+        payTo: r.payTo,
+        network,
+        resourceUrl,
+        payer,
+        issuedAt,
+        transaction,
+        signature: att.signature
+      });
+    } catch {
+      return { ok: false, reason: "verify-failed" };
+    }
+  }
   /** Auto-mount the chain's driver, resolve the network, and bind the wallet — once. */
   ensure() {
     return this.bound ??= (async () => {
@@ -2927,20 +3817,35 @@ var PipRailClient = class {
   async estimateCost(url, init) {
     const res = await fetch(url, { ...init ?? {}, method: init?.method ?? "GET" });
     if (res.status !== 402) return null;
-    const { net, accept, quote } = await this.resolveChallenge(url, res, this.resolveSchemes());
-    const cost = await net.estimateCost(accept);
-    return { quote, cost };
+    try {
+      const { net, accept, quote } = await this.resolveChallenge(url, res, this.resolveSchemes());
+      const cost = await net.estimateCost(accept);
+      return { quote, cost };
+    } catch (err) {
+      if (err instanceof InvalidEnvelopeError) return null;
+      throw err;
+    }
   }
   /** 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();
@@ -2951,9 +3856,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
@@ -3226,9 +4176,17 @@ var PipRailClient = class {
     }
     this.safeEmit({ kind: "payment-required", challenge, accept });
     await this.authorize(quote);
+    if (accept.scheme === "upto") {
+      return this.payUptoRail(net, wallet, accept, url, init, quote);
+    }
     if (accept.scheme === "exact") {
       return this.payExactRail(net, wallet, accept, url, init, quote);
     }
+    if (accept.scheme !== "onchain-proof") {
+      throw new UnsupportedSchemeError(
+        `internal: unrouted accept scheme '${accept.scheme}' reached the onchain-proof pay path.`
+      );
+    }
     const { ref, confirmed } = await this.payAndConfirm(net, wallet, accept);
     const response = await this.retryWithProof(url, init, accept, ref, confirmed);
     this.recordSpend(quote, ref);
@@ -3315,6 +4273,13 @@ var PipRailClient = class {
         )
       );
     }
+    if (schemes.includes("upto")) {
+      out.push(
+        ...challenge.accepts.filter(
+          (a) => a.scheme === "upto" && this.supportsNetwork(net, a.network) && typeof net.payUpto === "function" && net.describeAsset(a.asset) != null && typeof a.extra?.facilitatorAddress === "string" && a.extra.facilitatorAddress.length > 0 && Number.isInteger(a.maxTimeoutSeconds) && a.maxTimeoutSeconds > 0
+        )
+      );
+    }
     return out;
   }
   /** Build the full {@link PaymentPlan} from an already-parsed challenge + bound
@@ -3336,11 +4301,11 @@ var PipRailClient = class {
         ...session ? { session } : {}
       };
     }
-    const analysed = await Promise.all(
+    const analysed = (await Promise.all(
       candidates.map(
-        (accept) => this.analyzeRail(net, wallet, accept, url, challenge.resource.description)
+        (accept) => this.analyzeRail(net, wallet, accept, url, challenge.resource.description).catch(() => null)
       )
-    );
+    )).filter((o) => o !== null);
     const options = rankOptions(analysed);
     const best = options.find((o) => o.state === "payable") ?? null;
     const status = best ? "ready" : options.some((o) => o.state === "unknown") ? "unknown" : "blocked";
@@ -3364,14 +4329,14 @@ var PipRailClient = class {
     const rr = await net.recipientReady(accept.payTo, accept.asset).catch(() => ({ ready: "unknown" }));
     const amount = BigInt(accept.amount);
     const fee = safeBig(cost.fee);
-    const isExact = accept.scheme === "exact";
+    const isExact = accept.scheme === "exact" || accept.scheme === "upto";
     const isNative = accept.asset === "native";
     const blockers = [];
     const warnings = [];
     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");
@@ -3450,6 +4415,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 = {
@@ -3464,9 +4434,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.
@@ -3474,7 +4449,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,
@@ -3510,9 +4490,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;
@@ -3520,33 +4502,151 @@ 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 });
+    }
+  }
+  /**
+   * 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.
+   *
+   *  `settledAmountBase` is the SINGLE upto ledger-reconciliation seam: the quote (and thus
+   *  the policy/budget) gates on the MAX, and for the metered `upto` rail the budgeted amount
+   *  RECORDED is ALSO the authorized MAX — the only buyer-provable bound. The merchant's
+   *  claimed actual is UNTRUSTED (a malicious merchant can settle the MAX on-chain yet report
+   *  a tiny `SettleOutcome.amount`); recording it would let an under-report silently loosen a
+   *  cumulative cap (`maxTotal`/`maxTotalPerDenom`/`windowTotal`) past the buyer's real on-chain
+   *  spend (POL-1). So the cap-bearing `amountBase` is the MAX; the clamped actual is surfaced
+   *  separately on `settledBase`/`settledFormatted` for transparency (it equals the receipt's
+   *  amount). When absent (onchain-proof/exact) this is byte-identical to before. */
+  recordSpend(quote, ref, settledAmountBase) {
+    const denom = denomOf(quote.symbol, quote.asset, this.opts.policy);
+    const amountBase = quote.amount;
+    const amountFormatted = quote.amountFormatted;
+    let settledBase;
+    let settledFormatted;
+    if (settledAmountBase !== void 0 && /^\d+$/.test(settledAmountBase)) {
+      try {
+        const claimed = BigInt(settledAmountBase);
+        const max = BigInt(quote.amount);
+        const shown = claimed < max ? claimed : max;
+        settledBase = shown.toString();
+        settledFormatted = formatUnits(shown, quote.decimals);
+      } catch {
+      }
+    }
+    const record = {
+      url: quote.url,
+      host: hostOf2(quote.url),
+      network: quote.network,
+      asset: quote.asset,
+      amountBase,
+      amountFormatted,
+      ...settledBase !== void 0 ? { settledBase, settledFormatted } : {},
+      ...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
+      );
     }
   }
-  /** Record a settled payment in the ledger (true decimals for the running total). */
-  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
-    );
-  }
   async payAndConfirm(net, wallet, accept) {
     if (!this.supportsNetwork(net, accept.network)) {
       throw new WrongChainError(
@@ -3613,6 +4713,7 @@ var PipRailClient = class {
       }
       if (lastResponse.status !== 402) {
         const receipt = parseReceipt(lastResponse);
+        this.captureReceipt(lastResponse, url);
         this.safeEmit({ kind: "payment-settled", receipt });
         return lastResponse;
       }
@@ -3697,6 +4798,7 @@ var PipRailClient = class {
       }
       if (response.ok && !(settle && settle.success === false)) {
         const receipt = parseReceipt(response);
+        this.captureReceipt(response, url);
         this.safeEmit({ kind: "payment-settled", receipt, ...settle ? { settle } : {} });
         const ref = settle?.transaction || receipt?.transaction || `eip3009-nonce:${nonce}`;
         this.recordSpend(quote, ref);
@@ -3721,6 +4823,91 @@ var PipRailClient = class {
       { ref: nonce }
     );
   }
+  /**
+   * The standard `upto` (metered) buyer path — a near-clone of {@link payExactRail} with TWO
+   * deltas: (1) it signs a Permit2-upto authorization for the MAX via `payUpto` + frames it
+   * with `buildUptoSignatureHeader`; (2) it records the ACTUAL settled amount (read off the
+   * SettleResponse's required `amount` field, via `recordSpend(quote, ref, settle.amount)`) in
+   * the ledger — the budget gated on the MAX, the ledger records the ACTUAL. A server that omits
+   * `settle.amount` FAILS SAFE to the MAX (over-counts, never under-counts). The buyer SIGNS, the
+   * merchant self-settles — the buyer never broadcasts.
+   */
+  async payUptoRail(net, wallet, accept, url, init, quote) {
+    if (!net.payUpto) {
+      throw new UnsupportedSchemeError(
+        `the ${net.family} family can't pay a standard 'upto' rail (EVM-Permit2 only today).`
+      );
+    }
+    throwIfAborted(init?.signal);
+    const { payload, accepted, payerFrom, nonce } = await net.payUpto(wallet, accept);
+    const headers = new Headers(init?.headers);
+    headers.set(HEADER_SIGNATURE, buildUptoSignatureHeader({ accepted, payload }));
+    const rejectDefinitive = (why2) => {
+      this.safeEmit({ kind: "payment-failed", reason: `upto: facilitator rejected nonce=${nonce} (${why2})`, code: why2 });
+      throw new MaxRetriesExceededError(
+        `upto: the server rejected the payment (${why2}). Fix the cause, then re-present the SAME signed authorization (nonce=${nonce}) \u2014 do NOT re-sign a fresh nonce. ref=${nonce}.`,
+        { ref: nonce }
+      );
+    };
+    const deadline = Date.now() + Math.max(1, Math.floor(accept.maxTimeoutSeconds / 2)) * 1e3;
+    const maxAttempts = Math.min(this.maxRetries, 3);
+    let lastReason = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      if (attempt > 0) {
+        if (Date.now() >= deadline) break;
+        await new Promise((r) => setTimeout(r, Math.min(2e3, 400 * 2 ** (attempt - 1))));
+      }
+      throwIfAborted(init?.signal);
+      const budget = Math.min(this.retryTimeoutMs, deadline - Date.now());
+      if (budget <= 0) break;
+      const timeoutController = new AbortController();
+      const timeoutId = setTimeout(() => timeoutController.abort(), budget);
+      const signal = init?.signal && typeof AbortSignal.any === "function" ? AbortSignal.any([timeoutController.signal, init.signal]) : timeoutController.signal;
+      let response;
+      try {
+        response = await fetch(url, { ...init ?? {}, headers, signal });
+      } catch (err) {
+        throw new PaymentTimeoutError(
+          `upto: no response after submitting the authorization (nonce=${nonce}) to ${hostOf2(url)}. The merchant may have already settled it \u2014 verify on-chain before re-presenting; do NOT re-pay.`,
+          { cause: err, ref: nonce }
+        );
+      } finally {
+        clearTimeout(timeoutId);
+      }
+      const settle = parseSettleResponse(response);
+      if (response.status === 402) {
+        if (settle && settle.success === false) rejectDefinitive(settle.errorReason ?? "the server reported success:false");
+        lastReason = await readInvalidReason(response) ?? lastReason;
+        continue;
+      }
+      if (response.ok && !(settle && settle.success === false)) {
+        const receipt = parseReceipt(response);
+        this.captureReceipt(response, url);
+        this.safeEmit({ kind: "payment-settled", receipt, ...settle ? { settle } : {} });
+        const ref = settle?.transaction || receipt?.transaction || `upto-nonce:${nonce}`;
+        const settledAmount = settle?.amount ?? receipt?.amount;
+        this.recordSpend(quote, ref, settledAmount);
+        return response;
+      }
+      if (response.status >= 500) {
+        this.safeEmit({ kind: "payment-failed", reason: `upto: server ${response.status} \u2014 authorization nonce=${nonce} not settled` });
+        return response;
+      }
+      if (settle && settle.success === false) rejectDefinitive(settle.errorReason ?? "the server reported success:false");
+      this.safeEmit({ kind: "payment-failed", reason: `upto: server ${response.status} \u2014 authorization nonce=${nonce} not settled` });
+      return response;
+    }
+    const why = lastReason ? `${lastReason.error}${lastReason.detail ? ` \u2014 ${lastReason.detail}` : ""}` : "server gave no reason";
+    this.safeEmit({
+      kind: "payment-failed",
+      reason: `upto: 402 after submitting authorization nonce=${nonce} (${why})`,
+      ...lastReason ? { code: lastReason.error, detail: lastReason.detail } : {}
+    });
+    throw new MaxRetriesExceededError(
+      `upto: server still returned 402 after submitting the signed authorization (nonce=${nonce}). Last rejection: ${why}. Re-present the SAME authorization \u2014 do NOT re-sign a fresh nonce. ref=${nonce}.`,
+      { ref: nonce }
+    );
+  }
 };
 function throwIfAborted(signal) {
   if (signal?.aborted) {
@@ -3843,8 +5030,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;
@@ -3898,10 +5088,46 @@ async function readInvalidReason(response) {
   if (settle?.errorReason) return { error: settle.errorReason, detail: "" };
   return null;
 }
+var EVM_PRESET_FOR_CHAINID = {
+  1: "ethereum",
+  8453: "base",
+  137: "polygon",
+  42161: "arbitrum",
+  10: "optimism",
+  43114: "avalanche",
+  56: "bnb"
+};
+function chainSelectorForNetwork(network, rpcUrl) {
+  const chainId = chainIdFromNetwork(network);
+  if (chainId !== null) {
+    const preset = EVM_PRESET_FOR_CHAINID[chainId];
+    if (preset) return preset;
+    return { id: chainId, rpcUrl: rpcUrl ?? "" };
+  }
+  const namespace = network.split(":")[0] ?? "";
+  return namespace === "tvm" ? "ton" : namespace;
+}
+function receiptAgeSeconds(verifiedAt) {
+  const t = Date.parse(verifiedAt);
+  if (Number.isNaN(t)) return 0;
+  return Math.max(0, Math.round((Date.now() - t) / 1e3));
+}
+function receiptIssuedAtSeconds(verifiedAt) {
+  const t = Date.parse(verifiedAt);
+  if (Number.isNaN(t)) return 0;
+  return Math.floor(t / 1e3);
+}
+function sameAddress(a, b) {
+  return typeof a === "string" && typeof b === "string" && a.toLowerCase() === b.toLowerCase();
+}
 
 // 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
@@ -3909,12 +5135,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
@@ -3929,20 +5161,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] } : {},
@@ -3952,7 +5190,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
@@ -4046,28 +5284,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) {
@@ -4092,7 +5352,13 @@ var BRAND = {
 };
 var WHAT = 'This is an x402 "402 Payment Required" endpoint. Pay one of the offered rails to access it.';
 function howFor(scheme) {
-  return scheme === "exact" ? "Standard x402 exact rail \u2014 sign an EIP-3009 / Permit2 / SVM authorization; any stock x402 client (e.g. @x402/fetch) can pay this." : "Pay this amount on-chain to payTo, then resubmit with a payment-signature header carrying the proof ref + nonce. Easiest with @piprail/sdk (see sdk.install).";
+  if (scheme === "exact") {
+    return "Standard x402 exact rail \u2014 sign an EIP-3009 / Permit2 / SVM authorization; any stock x402 client (e.g. @x402/fetch) can pay this.";
+  }
+  if (scheme === "upto") {
+    return "Standard x402 upto (metered) rail \u2014 sign a Permit2 authorization for the MAX amount; the server settles the ACTUAL (\u2264 max) after serving. BUDGET AGAINST THE MAX \u2014 the server MAY fully charge it. EVM-Permit2 only; enable with schemes:['upto'].";
+  }
+  return "Pay this amount on-chain to payTo, then resubmit with a payment-signature header carrying the proof ref + nonce. Easiest with @piprail/sdk (see sdk.install).";
 }
 function railOf(a) {
   const extra = a.extra ?? {};
@@ -4119,6 +5385,7 @@ function buildSelfDescription(input) {
     mcp: { run: BRAND.mcpRun, tool: "piprail_pay_request" },
     docs: { home: BRAND.home, agents: BRAND.docs, pay: BRAND.payDocs },
     discovery: { openapi: "/openapi.json", wellKnown: "/.well-known/x402" },
+    ...input.verifiableReceipts ? { verifiableReceipts: true } : {},
     ...input.instruction ? { instruction: input.instruction } : {}
   };
 }
@@ -4172,9 +5439,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];
@@ -4215,17 +5485,21 @@ and pay with the tools below.
 Always plan before you pay so you never commit to a payment you cannot finish.
 
 ## Gasless \u2014 the exact rail (zero gas for you)
-A 402 may offer up to two rails; you don't choose per payment \u2014 the client does, automatically:
+A 402 may offer up to three rails; you don't choose per payment \u2014 the client does, automatically:
 - onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas
   (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.
 - exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose
   (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It
   works on EVM, Solana + Algorand, and the on-chain method (EIP-3009 / Permit2 / SVM / Algorand
   fee-pooled group) is picked automatically.
+- upto (the metered/variable x402 rail, opt-in, EVM): the amount you see is a MAXIMUM \u2014 you sign
+  a ceiling, the server meters real usage and settles the ACTUAL (<= the max). BUDGET AGAINST THE MAX:
+  the plan/policy treat the ceiling as the spend (a server may charge up to it), so a payable plan
+  means the MAX fits your budget; the settled actual is recorded for reconciliation.
 When the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest
 settleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is
-identical. The exact scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);
-you can't enable it yourself, but you can report when a 402 needs it (see UNSUPPORTED_SCHEME below).
+identical. The exact/upto schemes are OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact,upto);
+you can't enable them yourself, but you can report when a 402 needs one (see UNSUPPORTED_SCHEME below).
 
 ## Reading a refusal \u2014 never crash, never double-spend
 A failed pay returns a STRUCTURED object, never a thrown error you must catch:
@@ -4253,9 +5527,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
@@ -4266,10 +5542,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;
@@ -4501,11 +5782,13 @@ function paymentTools(client) {
             }
             res = await client.fetch(url, { method, headers, body });
           }
+          const verifiable = parseReceiptExtension(res);
           return {
             status: res.status,
             ok: res.ok,
             body: await readBody(res),
-            receipt: parseReceipt(res)
+            receipt: parseReceipt(res),
+            ...verifiable ? { verifiableReceipt: { ...verifiable, resource: { url } } } : {}
           };
         } catch (err) {
           if (err instanceof PipRailError) {
@@ -4584,11 +5867,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
       },
@@ -4601,7 +5884,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) {
@@ -4619,6 +5908,38 @@ function paymentTools(client) {
       },
       parameters: { type: "object", properties: {}, additionalProperties: false },
       invoke: async () => ({ guide: PIPRAIL_AGENT_GUIDE })
+    },
+    {
+      name: "piprail_verify_receipt",
+      description: "Re-verify a PipRail VERIFIABLE RECEIPT against the chain \u2014 confirm a payment REALLY settled (the funds provably moved to payTo for AT LEAST the stated amount) WITHOUT trusting whoever handed you the receipt. Read-only and WALLET-FREE: pass the PipRailReceipt JSON (from a prior piprail_pay_request `verifiableReceipt`, or any third party). Returns { ok, onChain:{payTo,asset,amount,payer}, matchesClaims, ageSeconds, error? }: `ok` = the chain confirms the settlement; `onChain.payer` is RE-DERIVED from the tx and `matchesClaims:false` means the receipt forged the payer; `amount` is a verified lower bound. Pass `rpcUrl` for a chain outside the common presets.",
+      annotations: {
+        title: "Verify a payment receipt",
+        readOnlyHint: true,
+        // re-reads the chain; moves nothing, needs no wallet
+        idempotentHint: true,
+        openWorldHint: true
+        // reads an on-chain tx via RPC
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          receipt: {
+            type: "object",
+            description: "The PipRailReceipt JSON ({ piprail, receipt, resource, decimals? }) to re-verify."
+          },
+          rpcUrl: {
+            type: "string",
+            description: "Optional RPC URL for the receipt's chain (required for chains outside the common presets)."
+          }
+        },
+        required: ["receipt"],
+        additionalProperties: false
+      },
+      invoke: async (args) => {
+        const receipt = args.receipt;
+        const opts = args.rpcUrl ? { rpcUrl: String(args.rpcUrl) } : void 0;
+        return await PipRailClient.verifyReceipt(receipt, opts);
+      }
     }
   ];
 }
@@ -5268,17 +6589,40 @@ function normaliseExactOption(exact) {
   return exact;
 }
 var TRANSIENT_VERIFY_CODES = /* @__PURE__ */ new Set(["tx_not_found", "insufficient_confirmations"]);
+function nowUnixSeconds(verifiedAt) {
+  if (verifiedAt) {
+    const t = Date.parse(verifiedAt);
+    if (!Number.isNaN(t)) return Math.floor(t / 1e3);
+  }
+  return Math.floor(Date.now() / 1e3);
+}
 function createPaymentGate(options) {
   const minConfirmations = options.minConfirmations ?? 1;
   const maxTimeoutSeconds = options.maxTimeoutSeconds ?? 600;
   const genNonce = options.generateNonce ?? (() => globalThis.crypto.randomUUID());
   const exactOption = normaliseExactOption(options.exact);
+  const receiptsOn = options.receipts !== void 0 && options.receipts !== false;
+  const receiptOpt = typeof options.receipts === "object" ? options.receipts : {};
+  const receiptIncludeTxHash = receiptOpt.includeTxHash !== false;
+  const receiptResourceUrl = receiptOpt.resource ?? "";
+  const attestWallet = receiptOpt.attest && "wallet" in receiptOpt.attest ? receiptOpt.attest.wallet : void 0;
+  const attestJws = receiptOpt.attest && "jws" in receiptOpt.attest;
+  let attestWarned = false;
+  function warnAttestDegrade(reason) {
+    if (attestWarned) return;
+    attestWarned = true;
+    try {
+      console.warn(`[piprail] receipts.attest ${reason}; emitting an unsigned Tier-1 receipt instead.`);
+    } catch {
+    }
+  }
   let resolved;
   function ready() {
     if (resolved) return resolved;
     const p = (async () => {
       const accepts = normaliseAccepts(options);
       const exactSkips = [];
+      const uptoSkips = [];
       const specs = await Promise.all(
         accepts.map(async (a) => {
           const net = await resolveNetwork2({ chain: a.chain, rpcUrl: a.rpcUrl ?? options.rpcUrl });
@@ -5297,9 +6641,19 @@ function createPaymentGate(options) {
             if (outcome.rail) spec.exact = outcome.rail;
             else if (outcome.skipReason) exactSkips.push(outcome.skipReason);
           }
+          if (options.upto) {
+            const upto = await resolveUptoRail(net, asset);
+            if (upto) spec.upto = upto;
+            else uptoSkips.push(`${net.network}/${asset}`);
+          }
           return spec;
         })
       );
+      if (options.upto && !specs.some((s) => s.upto)) {
+        throw new Error(
+          `requirePayment: \`upto\` (the metered rail) was requested but none of the offered rails support it (tried: ${uptoSkips.join(", ") || "none"}). The \`upto\` scheme is EVM-Permit2 ONLY \u2014 an ERC-20 on a chain with the x402UptoPermit2Proxy deployed (Ethereum/Base/Arbitrum/Optimism/Polygon/BNB), NOT a native coin, NOT a non-EVM family. (Native coins + non-Permit2 chains can never carry \`upto\`.)`
+        );
+      }
       if (exactOption && !specs.some((s) => s.exact)) {
         const why = exactSkips.length > 0 ? exactSkips.join(" ") : "The standard `exact` rail is EVM ERC-20 (EIP-3009 \u2014 USDC / EURC \u2014 or Permit2, e.g. Binance-Peg USDC on BNB) or a Solana SPL token (SVM) \u2014 NOT native coins, NOT families without a standard `exact` scheme.";
         if (exactOption.settle === "keyless") {
@@ -5379,7 +6733,27 @@ function createPaymentGate(options) {
     };
     return { rail: { method: info.method, ...info.extra ? { extra: info.extra } : {}, mode } };
   }
-  const hasCustomStore = Boolean(options.isUsed || options.markUsed);
+  async function resolveUptoRail(net, asset) {
+    const cfg = options.upto;
+    if (!net.resolveUptoRail) return null;
+    if (cfg.relayer === void 0) {
+      throw new Error(
+        "requirePayment: `upto` needs a `relayer` wallet (the gas-paying key that self-settles the metered actual AND is the bound witness.facilitator), e.g. upto: { relayer: { key }, settleAmount }."
+      );
+    }
+    const relayer = net.bindWallet(cfg.relayer);
+    const info = await net.resolveUptoRail({ asset, relayer });
+    if (!info) return null;
+    return { method: info.method, ...info.extra ? { extra: info.extra } : {}, relayer };
+  }
+  const hasIsUsed = typeof options.isUsed === "function";
+  const hasMarkUsed = typeof options.markUsed === "function";
+  if (hasIsUsed !== hasMarkUsed) {
+    throw new Error(
+      "requirePayment/createPaymentGate: `isUsed` and `markUsed` must be provided TOGETHER \u2014 a custom replay store needs both a read and a write. Supplying only " + (hasIsUsed ? "`isUsed`" : "`markUsed`") + " silently disables replay protection (double-spend). Provide both, or neither (the built-in in-memory store)."
+    );
+  }
+  const hasCustomStore = hasIsUsed && hasMarkUsed;
   const localUsed = /* @__PURE__ */ new Map();
   const replayWindowMs = maxTimeoutSeconds * 1e3;
   function pruneUsed(now) {
@@ -5442,10 +6816,33 @@ function createPaymentGate(options) {
       }
     };
   }
+  function buildUptoAccept(s) {
+    const rail = s.upto;
+    return {
+      scheme: "upto",
+      network: s.net.network,
+      amount: s.amountBase.toString(),
+      // the authorized MAX (base units)
+      asset: s.asset,
+      payTo: s.payTo,
+      maxTimeoutSeconds,
+      extra: {
+        assetTransferMethod: "permit2-upto",
+        // facilitatorAddress comes from rail.extra; the spread below carries it (+ name/version).
+        facilitatorAddress: rail.extra?.facilitatorAddress ?? "",
+        minConfirmations,
+        decimals: s.decimals,
+        amountFormatted: s.amountFormatted,
+        ...s.symbol ? { symbol: s.symbol } : {},
+        ...rail.extra
+      }
+    };
+  }
   function buildAccepts(specs, nonce) {
     const out = [];
     for (const s of specs) {
       if (s.exact) out.push(buildExactAccept(s));
+      if (s.upto) out.push(buildUptoAccept(s));
       out.push(buildAccept(s, nonce));
     }
     return out;
@@ -5463,7 +6860,8 @@ function createPaymentGate(options) {
     const selfDescribe = options.selfDescribe === false ? void 0 : buildSelfDescription({
       accepts,
       instruction: describeChallenge({ x402Version: 2, resource: { url: resourceUrl }, accepts }),
-      ...endpointInfo ? { endpoint: endpointInfo } : {}
+      ...endpointInfo ? { endpoint: endpointInfo } : {},
+      ...receiptsOn ? { verifiableReceipts: true } : {}
     });
     const rejectionExt = opts?.extensions ?? {};
     const rejectionPiprail = rejectionExt.piprail ?? {};
@@ -5552,6 +6950,55 @@ function createPaymentGate(options) {
     if (options.awaitOnPaid) await fireOnPaid(paid);
     else void fireOnPaid(paid);
   }
+  async function buildPaidResult(spec, receipt, nonce) {
+    if (!receiptsOn) {
+      return { kind: "paid", receipt, receiptHeader: buildReceiptHeader(receipt) };
+    }
+    try {
+      const stamped = {
+        ...receipt,
+        ...nonce ? { nonce } : {},
+        // §5.3: a suppressed tx is the empty string on the wire, never a missing key.
+        ...receiptIncludeTxHash ? {} : { transaction: "" }
+      };
+      const attestation = await maybeSignAttestation(spec, stamped);
+      const extensions = buildReceiptExtension({
+        receipt: stamped,
+        resource: { url: receiptResourceUrl },
+        decimals: spec.decimals,
+        ...attestation ? { attestation } : {}
+      });
+      return { kind: "paid", receipt: stamped, receiptHeader: buildReceiptHeader(stamped, extensions) };
+    } catch {
+      return { kind: "paid", receipt, receiptHeader: buildReceiptHeader(receipt) };
+    }
+  }
+  async function maybeSignAttestation(spec, stamped) {
+    if (attestJws) {
+      warnAttestDegrade("JWS attestation is not yet implemented (R3)");
+      return void 0;
+    }
+    if (attestWallet === void 0) return void 0;
+    if (typeof spec.net.signReceipt !== "function") {
+      warnAttestDegrade(`is EVM-only; the ${spec.net.family} rail can't sign an EIP-712 attestation`);
+      return void 0;
+    }
+    try {
+      const wallet = spec.net.bindWallet(attestWallet);
+      return await spec.net.signReceipt(wallet, {
+        payTo: spec.payTo,
+        network: spec.net.network,
+        resourceUrl: receiptResourceUrl,
+        payer: stamped.payer,
+        issuedAt: nowUnixSeconds(stamped.verifiedAt),
+        // §5.3: the signed message carries the empty string for a suppressed tx, never omitted.
+        transaction: receiptIncludeTxHash ? stamped.transaction : ""
+      });
+    } catch {
+      warnAttestDegrade("signing failed");
+      return void 0;
+    }
+  }
   function reportOnFailedError(error, failure) {
     if (!options.onFailedError) return;
     try {
@@ -5578,6 +7025,14 @@ function createPaymentGate(options) {
     if (options.awaitOnFailed) await fireOnFailed(failure);
     else void fireOnFailed(failure);
   }
+  function railExtra(full) {
+    const out = {};
+    for (const k of ["assetTransferMethod", "facilitatorAddress", "name", "version"]) {
+      const v = full[k];
+      if (v !== void 0 && v !== "") out[k] = v;
+    }
+    return Object.keys(out).length > 0 ? { extra: out } : {};
+  }
   async function describe(resourceUrl = "") {
     const specs = await ready();
     const accepts = [];
@@ -5592,7 +7047,8 @@ function createPaymentGate(options) {
         maxTimeoutSeconds,
         ...s.symbol ? { symbol: s.symbol } : {}
       };
-      if (s.exact) accepts.push({ scheme: "exact", ...base2 });
+      if (s.exact) accepts.push({ scheme: "exact", ...base2, ...railExtra(buildExactAccept(s).extra) });
+      if (s.upto) accepts.push({ scheme: "upto", ...base2, ...railExtra(buildUptoAccept(s).extra) });
       accepts.push({ scheme: "onchain-proof", ...base2 });
     }
     return {
@@ -5628,7 +7084,7 @@ function createPaymentGate(options) {
     }
     await settleTx(ref, true);
     await deliverOnPaid(spec, result.receipt);
-    return { kind: "paid", receipt: result.receipt, receiptHeader: buildReceiptHeader(result.receipt) };
+    return await buildPaidResult(spec, result.receipt, sig.payload.nonce);
   }
   async function verifyExact(exact) {
     const specs = await ready();
@@ -5738,27 +7194,122 @@ function createPaymentGate(options) {
     }
     await settleTx(nonce, true);
     await deliverOnPaid(spec, result.receipt);
-    return { kind: "paid", receipt: result.receipt, receiptHeader: buildReceiptHeader(result.receipt) };
+    return await buildPaidResult(spec, result.receipt);
+  }
+  function resolveSettleAmount(raw, maxAmount, decimals) {
+    if (typeof raw === "bigint") return raw < 0n ? null : raw;
+    const s = raw.trim();
+    if (s.length === 0) return null;
+    try {
+      if (s.endsWith("%")) {
+        const pct = s.slice(0, -1).trim();
+        if (!/^\d+(\.\d+)?$/.test(pct)) return null;
+        const pctScaled = floorUnits(pct, 4);
+        return maxAmount * pctScaled / (100n * 10n ** 4n);
+      }
+      if (s.startsWith("$")) {
+        const amt = s.slice(1).trim();
+        return floorUnits(amt, decimals);
+      }
+      if (/^\d+$/.test(s)) return BigInt(s);
+      return floorUnits(s, decimals);
+    } catch {
+      return null;
+    }
+  }
+  async function verifyUpto(upto) {
+    const specs = await ready();
+    const uptoSpecs = specs.filter((s) => s.upto);
+    if (uptoSpecs.length === 0) {
+      return rejection("transfer_not_found", "This resource offers no standard `upto` (metered) rail.");
+    }
+    const isCaip = upto.network.includes(":");
+    let candidates = isCaip ? uptoSpecs.filter((s) => s.net.network === upto.network) : uptoSpecs;
+    if (upto.asset) {
+      candidates = candidates.filter((s) => s.asset.toLowerCase() === upto.asset.toLowerCase());
+    }
+    let spec = candidates[0];
+    if (!isCaip && !upto.asset && uptoSpecs.length > 1) spec = void 0;
+    if (!spec && !isCaip && !upto.asset && uptoSpecs.length === 1) spec = uptoSpecs[0];
+    if (!spec || !spec.upto) {
+      return rejection(
+        "transfer_not_found",
+        `No \`upto\` rail offered for ${upto.network}${upto.asset ? `/${upto.asset}` : ""} (offered: ${uptoSpecs.map((s) => `${s.asset}@${s.net.network}`).join(", ")}).`
+      );
+    }
+    const nonce = upto.payload.permit2Authorization.nonce;
+    if (await claimTx(nonce)) {
+      return rejection("tx_already_used", `Authorization nonce ${nonce} was already redeemed.`);
+    }
+    const accept = buildUptoAccept(spec);
+    const relayer = spec.upto.relayer;
+    let result;
+    try {
+      const rawAmount = await options.upto.settleAmount({
+        maxAmount: spec.amountBase,
+        asset: spec.asset,
+        network: spec.net.network,
+        decimals: spec.decimals,
+        ...upto.raw ? { request: upto.raw } : {}
+      });
+      const settleAmount = resolveSettleAmount(rawAmount, spec.amountBase, spec.decimals);
+      if (settleAmount === null) {
+        await settleTx(nonce, false);
+        return rejection(
+          "upto_settle_exceeds_max",
+          `The settleAmount callback returned an unparseable amount (${String(rawAmount)}). Return a bigint, a raw/"NN%"/"$X" string, or 0.`
+        );
+      }
+      result = await spec.net.settleUptoSelf({ relayer, payload: upto.payload, accept, settleAmount });
+    } catch (err) {
+      await settleTx(nonce, false);
+      if (err instanceof SettlementError) throw err;
+      return rejection(
+        "tx_reverted",
+        `upto: metering/settle failed (${err instanceof Error ? err.message : String(err)}).`
+      );
+    }
+    if (!result.ok) {
+      await settleTx(nonce, false);
+      return rejection(result.error, result.detail);
+    }
+    await settleTx(nonce, true);
+    await deliverOnPaid(spec, result.receipt);
+    return await buildPaidResult(spec, result.receipt);
   }
   async function verify(paymentSignature) {
-    const result = await resolveVerdict(paymentSignature);
+    const raw = normaliseHeader(paymentSignature);
+    const result = await resolveVerdictObject(raw === void 0 ? void 0 : decodeBase64Json(raw));
     if (result.kind === "invalid") await deliverOnFailed(result);
     return result;
   }
-  async function resolveVerdict(paymentSignature) {
-    const raw = normaliseHeader(paymentSignature);
-    if (!raw) return asChallenge();
-    const sig = parseSignatureHeader(raw);
+  async function verifyObject(payload) {
+    const result = await resolveVerdictObject(payload);
+    if (result.kind === "invalid") await deliverOnFailed(result);
+    return result;
+  }
+  async function resolveVerdictObject(obj) {
+    if (obj === void 0 || obj === null) return asChallenge();
+    const sig = parseSignatureObject(obj);
     if (sig && sig.accepted && typeof sig.accepted.network === "string" && typeof sig.accepted.asset === "string") {
       return verifyOnchainProof(sig);
     }
-    const exact = parseExactPaymentHeader(raw);
+    const upto = parseUptoObject(obj);
+    if (upto) return verifyUpto(upto);
+    const exact = parseExactObject(obj);
     if (exact) return verifyExact(exact);
     return asChallenge();
   }
-  return { challenge, verify, describe, landingPage };
+  return { challenge, verify, verifyObject, describe, landingPage };
 }
 function requirePayment(options) {
+  if (options.upto) {
+    throw new class extends PipRailError {
+      code = "UNSUPPORTED_SCHEME";
+    }(
+      "requirePayment: the 'upto' (metered) rail is unsupported through the Express middleware \u2014 it settles before the route handler serves, so metered usage is unknown at settle time. Call gate.verify() directly (createPaymentGate) and meter inside settleAmount; see docs/accepting-payments/upto-rail-seller.md."
+    );
+  }
   const gate = createPaymentGate(options);
   return async (req, res, next) => {
     let result;
@@ -5904,13 +7455,261 @@ async function deliverReceipt(receipt, options) {
     ...lastError ? { error: lastError } : {}
   };
 }
+
+// src/transports/a2a.ts
+var A2A_X402_EXTENSION_URI_V01 = "https://github.com/google-a2a/a2a-x402/v0.1";
+var A2A_X402_EXTENSION_URI_V02 = "https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2";
+var A2A_STATUS_KEY = "x402.payment.status";
+var A2A_REQUIRED_KEY = "x402.payment.required";
+var A2A_PAYLOAD_KEY = "x402.payment.payload";
+var A2A_RECEIPTS_KEY = "x402.payment.receipts";
+var A2A_ERROR_KEY = "x402.payment.error";
+var A2A_EXTENSIONS_HEADER = "X-A2A-Extensions";
+var MAX_TASK_RECEIPTS = 64;
+var VERIFY_CODE_TO_A2A_ERROR = {
+  payment_expired: "EXPIRED_PAYMENT",
+  tx_already_used: "DUPLICATE_NONCE",
+  amount_too_low: "INVALID_AMOUNT",
+  upto_settle_exceeds_max: "INVALID_AMOUNT",
+  signature_invalid: "INVALID_SIGNATURE",
+  transfer_not_found: "INVALID_AMOUNT",
+  wrong_recipient: "INVALID_AMOUNT",
+  tx_reverted: "SETTLEMENT_FAILED",
+  tx_not_found: "EXPIRED_PAYMENT",
+  insufficient_confirmations: "EXPIRED_PAYMENT",
+  no_meta: "INVALID_SIGNATURE",
+  // The settlement-side throw code the handler emits for a SettlementError (the merchant's
+  // relayer/facilitator never moved funds) — maps to the spec's SETTLEMENT_FAILED.
+  settlement_failed: "SETTLEMENT_FAILED"
+};
+function toA2AErrorCode(code) {
+  return VERIFY_CODE_TO_A2A_ERROR[code] ?? code;
+}
+function toA2APaymentRequired(taskId, challenge, parts) {
+  const metadata = {
+    [A2A_STATUS_KEY]: "payment-required",
+    [A2A_REQUIRED_KEY]: challenge
+  };
+  return {
+    kind: "task",
+    id: taskId,
+    status: {
+      state: "input-required",
+      message: { kind: "message", role: "agent", taskId, ...parts ? { parts } : {}, metadata }
+    }
+  };
+}
+function toA2APaymentReceipts(receipts) {
+  return { [A2A_RECEIPTS_KEY]: receipts };
+}
+function toA2APaymentFailed(code, detail, receipts = [], network) {
+  const entry = {
+    success: false,
+    transaction: "",
+    ...network ? { network } : {},
+    errorReason: `${code}: ${detail}`
+  };
+  return {
+    [A2A_STATUS_KEY]: "payment-failed",
+    [A2A_ERROR_KEY]: toA2AErrorCode(code),
+    [A2A_RECEIPTS_KEY]: [...receipts, entry]
+  };
+}
+function fromA2APaymentRequired(task) {
+  const meta = task.status?.message?.metadata;
+  const required = meta?.[A2A_REQUIRED_KEY];
+  if (!required || typeof required !== "object") return null;
+  return required;
+}
+function fromA2APaymentPayload(message) {
+  const raw = message.metadata?.[A2A_PAYLOAD_KEY];
+  if (raw === void 0 || raw === null) return null;
+  return { raw, taskId: message.taskId ?? "" };
+}
+function defaultTaskStore() {
+  const map = /* @__PURE__ */ new Map();
+  function prune(now) {
+    for (const [key, { expiry }] of map) {
+      if (expiry > now) break;
+      map.delete(key);
+    }
+  }
+  return {
+    get(taskId) {
+      const now = Date.now();
+      prune(now);
+      const hit = map.get(taskId);
+      return hit && hit.expiry > now ? hit.record : void 0;
+    },
+    set(taskId, value, ttlMs) {
+      const now = Date.now();
+      prune(now);
+      map.delete(taskId);
+      map.set(taskId, { record: value, expiry: now + ttlMs });
+    }
+  };
+}
+function createA2APaymentHandler(options) {
+  const gate = options.gate ?? createPaymentGate(options);
+  const maxTimeoutSeconds = options.maxTimeoutSeconds ?? 600;
+  const ttlMs = options.taskTtlMs ?? maxTimeoutSeconds * 1e3;
+  const store = options.taskStore ?? defaultTaskStore();
+  function appendReceipt(taskId, entry) {
+    const prior = store.get(taskId)?.receipts ?? [];
+    const isDup = "success" in entry && entry.success === true && prior.some((r) => "transaction" in r && r.transaction === entry.transaction);
+    const next = isDup ? prior : [...prior, entry];
+    const receipts = next.length > MAX_TASK_RECEIPTS ? next.slice(-MAX_TASK_RECEIPTS) : next;
+    store.set(taskId, { receipts }, ttlMs);
+    return receipts;
+  }
+  function completedTask(taskId, receipts, artifacts, status = "payment-completed") {
+    const metadata = { [A2A_STATUS_KEY]: status, ...toA2APaymentReceipts(receipts) };
+    return {
+      kind: "task",
+      id: taskId,
+      status: { state: "completed", message: { kind: "message", role: "agent", taskId, metadata } },
+      ...artifacts.length > 0 ? { artifacts } : {}
+    };
+  }
+  function reChallengeTask(taskId, result, attempted) {
+    if (result.kind !== "invalid") {
+      const metadata2 = {
+        [A2A_STATUS_KEY]: "payment-required",
+        [A2A_REQUIRED_KEY]: result.challenge
+      };
+      return {
+        kind: "task",
+        id: taskId,
+        status: { state: "input-required", message: { kind: "message", role: "agent", taskId, metadata: metadata2 } }
+      };
+    }
+    const network = attempted ?? singleNetworkOf(result.challenge);
+    const receipts = appendReceiptFailed(taskId, result.error, result.detail, network);
+    const metadata = {
+      [A2A_STATUS_KEY]: "payment-rejected",
+      [A2A_ERROR_KEY]: toA2AErrorCode(result.error),
+      [A2A_REQUIRED_KEY]: result.challenge,
+      ...toA2APaymentReceipts(receipts)
+    };
+    return {
+      kind: "task",
+      id: taskId,
+      status: { state: "input-required", message: { kind: "message", role: "agent", taskId, metadata } }
+    };
+  }
+  function failedTask(taskId, code, detail, network) {
+    const receipts = appendReceiptFailed(taskId, code, detail, network);
+    const metadata = {
+      [A2A_STATUS_KEY]: "payment-failed",
+      [A2A_ERROR_KEY]: toA2AErrorCode(code),
+      ...toA2APaymentReceipts(receipts)
+    };
+    return {
+      kind: "task",
+      id: taskId,
+      status: { state: "failed", message: { kind: "message", role: "agent", taskId, metadata } }
+    };
+  }
+  function appendReceiptFailed(taskId, code, detail, network) {
+    return appendReceipt(taskId, {
+      success: false,
+      transaction: "",
+      ...network ? { network } : {},
+      errorReason: `${code}: ${detail}`
+    });
+  }
+  async function handleMessage(message, taskId) {
+    const id = taskId ?? message.taskId ?? newTaskId();
+    const inbound = fromA2APaymentPayload(message);
+    if (!inbound) {
+      const { challenge } = await gate.challenge(resourceUrlFromMessage(message));
+      store.set(id, { receipts: [] }, ttlMs);
+      return toA2APaymentRequired(id, challenge);
+    }
+    const attempted = networkFromPayload(inbound.raw);
+    let result;
+    try {
+      result = await gate.verifyObject(inbound.raw);
+    } catch (err) {
+      if (err instanceof SettlementError) {
+        return failedTask(id, "settlement_failed", err.message, attempted);
+      }
+      const detail = err instanceof Error ? err.message : String(err);
+      return failedTask(id, "tx_reverted", detail, attempted);
+    }
+    switch (result.kind) {
+      case "challenge":
+        return reChallengeTask(id, result, attempted);
+      case "invalid":
+        return reChallengeTask(id, result, attempted);
+      case "paid": {
+        const receipts = appendReceipt(id, result.receipt);
+        let artifacts = [];
+        if (options.fulfill) {
+          try {
+            artifacts = await options.fulfill({ taskId: id, receipt: result.receipt, message }) ?? [];
+          } catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            const annotation = {
+              name: "fulfillment-error",
+              metadata: { "x402.fulfillment.error": detail, "x402.fulfillment.settled": true },
+              parts: [{ kind: "text", text: `Payment settled, but serving the result failed: ${detail}` }]
+            };
+            return completedTask(id, receipts, [annotation]);
+          }
+        }
+        return completedTask(id, receipts, artifacts);
+      }
+    }
+  }
+  function agentCardExtension(opts) {
+    const uri = opts?.version === "v0.2" ? A2A_X402_EXTENSION_URI_V02 : A2A_X402_EXTENSION_URI_V01;
+    return {
+      uri,
+      description: "Supports payments using the x402 protocol for on-chain settlement.",
+      ...opts?.required ? { required: true } : {}
+    };
+  }
+  return { handleMessage, agentCardExtension, gate };
+}
+function singleNetworkOf(challenge) {
+  const nets = new Set((challenge.accepts ?? []).map((a) => a.network).filter(Boolean));
+  return nets.size === 1 ? [...nets][0] : void 0;
+}
+function networkFromPayload(raw) {
+  const v = raw;
+  if (v && typeof v.accepted?.network === "string") return v.accepted.network;
+  if (v && typeof v.network === "string") return v.network;
+  return void 0;
+}
+function newTaskId() {
+  return `task-${globalThis.crypto.randomUUID()}`;
+}
+function resourceUrlFromMessage(message) {
+  for (const part of message.parts ?? []) {
+    const data = part.data;
+    if (data && typeof data.url === "string") return data.url;
+  }
+  return "";
+}
 export {
+  A2A_ERROR_KEY,
+  A2A_EXTENSIONS_HEADER,
+  A2A_PAYLOAD_KEY,
+  A2A_RECEIPTS_KEY,
+  A2A_REQUIRED_KEY,
+  A2A_STATUS_KEY,
+  A2A_X402_EXTENSION_URI_V01,
+  A2A_X402_EXTENSION_URI_V02,
   BRAND,
+  BUILTIN_DENOMS,
   CHAINS,
   ConfirmationTimeoutError,
+  DENOM_PRECISION,
   DIRECTORY_INFO,
   EIP3009_TYPES,
   EXACT_NETWORK_SLUGS,
+  EXT_OFFER_RECEIPT,
   GENERATOR,
   HEADER_REQUIRED,
   HEADER_RESPONSE,
@@ -5927,6 +7726,7 @@ export {
   NonReplayableBodyError,
   PERMIT2_ADDRESS,
   PERMIT2_PROXY_CHAIN_IDS,
+  PERMIT2_UPTO_WITNESS_TYPES,
   PERMIT2_WITNESS_TYPES,
   PIPRAIL_AGENT_GUIDE,
   POWERED_BY,
@@ -5937,13 +7737,17 @@ export {
   REGISTER_ATTRIBUTION,
   RecipientNotReadyError,
   SettlementError,
+  SpendLedger,
+  UPTO_PROXY_CHAIN_IDS,
   UnknownTokenError,
   UnsupportedNetworkError,
   UnsupportedSchemeError,
+  VERIFY_CODE_TO_A2A_ERROR,
   WalletRequiredError,
   WrongChainError,
   WrongFamilyError,
   X402_EXACT_PERMIT2_PROXY,
+  X402_UPTO_PERMIT2_PROXY,
   agentGuide,
   appendAttribution,
   appendKeywords,
@@ -5953,17 +7757,22 @@ export {
   buildExactAuthorization,
   buildExactSignatureHeader,
   buildOpenApi,
+  buildReceiptExtension,
   buildReceiptHeader,
   buildSelfDescription,
   buildSignatureHeader,
+  buildUptoSignatureHeader,
   buildWellKnownX402,
   buildX402DnsTxt,
   chainIdForExactNetwork,
   claim402IndexDomain,
   classifyChallenge,
+  createA2APaymentHandler,
   createPaymentGate,
+  decodeBase64Json,
   decorateOutcome,
   deliverReceipt,
+  denomOf,
   describeChallenge,
   discoveryHeaders,
   eip3009Abi,
@@ -5974,17 +7783,26 @@ export {
   fetchAcross,
   firstKeylessFacilitator,
   formatSpendReport,
+  fromA2APaymentPayload,
+  fromA2APaymentRequired,
   getDirectoryInfo,
   isPermit2ProxyChain,
+  isUptoProxyChain,
   knownFacilitatorsFor,
+  memorySpendStore,
   normalizeNetwork,
   parseChallenge,
+  parseExactObject,
   parseExactPaymentHeader,
   parseExactRequirements,
   parseFacilitatorSupported,
   parseReceipt,
+  parseReceiptExtension,
   parseSettleResponse,
   parseSignatureHeader,
+  parseSignatureObject,
+  parseUptoObject,
+  parseUptoPaymentHeader,
   paymentTools,
   pickAccept,
   planAcross,
@@ -6000,6 +7818,10 @@ export {
   searchOpenIndexes,
   settleViaFacilitator,
   summarizePlan,
+  toA2AErrorCode,
+  toA2APaymentFailed,
+  toA2APaymentReceipts,
+  toA2APaymentRequired,
   toInsufficientFundsError,
   toInvalidBody,
   verify402IndexDomain