@piprail/sdk 1.3.1 → 1.5.0

package/dist/index.cjs

@@ -20,7 +20,7 @@
 
 
 
-var _chunkYJPWIK5Lcjs = require('./chunk-YJPWIK5L.cjs');
+var _chunkIQGT65WScjs = require('./chunk-IQGT65WS.cjs');
 
 // src/drivers/registry.ts
 var byFamily = /* @__PURE__ */ new Map();
@@ -40,6 +40,7 @@ function familyForChain(chain) {
     if (chain.startsWith("sui")) return "sui";
     if (chain.startsWith("near")) return "near";
     if (chain.startsWith("aptos")) return "aptos";
+    if (chain.startsWith("algorand")) return "algorand";
     return "evm";
   }
   return "evm";
@@ -48,13 +49,13 @@ function resolveNetwork(opts) {
   const family = familyForChain(opts.chain);
   const driver = byFamily.get(family);
   if (!driver) {
-    throw new (0, _chunkYJPWIK5Lcjs.UnsupportedNetworkError)(
+    throw new (0, _chunkIQGT65WScjs.UnsupportedNetworkError)(
       `No driver registered for the "${family}" family \u2014 it may not be mounted yet (use the async resolveNetwork()).`
     );
   }
   const net = driver.resolve(opts);
   if (!net) {
-    throw new (0, _chunkYJPWIK5Lcjs.UnsupportedNetworkError)(
+    throw new (0, _chunkIQGT65WScjs.UnsupportedNetworkError)(
       `The ${family} driver didn't recognise this chain input.`
     );
   }
@@ -298,12 +299,12 @@ function createWalletAdapter(config, resolved) {
   }
   const wc = config.walletClient;
   if (!wc.account) {
-    throw new (0, _chunkYJPWIK5Lcjs.WrongFamilyError)(
+    throw new (0, _chunkIQGT65WScjs.WrongFamilyError)(
       "chain is EVM; the provided walletClient has no attached account. Use `createWalletClient({ account, chain, transport })`, or pass { privateKey }."
     );
   }
   if (wc.chain && wc.chain.id !== resolved.chainId) {
-    throw new (0, _chunkYJPWIK5Lcjs.WrongChainError)(
+    throw new (0, _chunkIQGT65WScjs.WrongChainError)(
       `PipRailClient: walletClient is on chain ${wc.chain.id} but the SDK was configured with chain ${resolved.chainId}. They must match.`
     );
   }
@@ -606,15 +607,15 @@ function makeEvmNetwork(resolved) {
         const info = resolved.tokens[token.toUpperCase()];
         if (!info) {
           const known = Object.keys(resolved.tokens).join(", ") || "(none built in)";
-          throw new (0, _chunkYJPWIK5Lcjs.UnknownTokenError)(
+          throw new (0, _chunkIQGT65WScjs.UnknownTokenError)(
             `token "${token}" isn't built in for ${resolved.chain.name} (known: ${known}). Pass { address, decimals } instead, or use 'native'.`
           );
         }
         return { asset: info.address, decimals: info.decimals, symbol: info.symbol };
       }
-      _chunkYJPWIK5Lcjs.rejectForeignToken.call(void 0, token, "evm", network);
+      _chunkIQGT65WScjs.rejectForeignToken.call(void 0, token, "evm", network);
       if (!("address" in token)) {
-        throw new (0, _chunkYJPWIK5Lcjs.WrongFamilyError)(
+        throw new (0, _chunkIQGT65WScjs.WrongFamilyError)(
           `chain ${network} is EVM; a custom token must be { address, decimals }.`
         );
       }
@@ -646,14 +647,14 @@ function makeEvmNetwork(resolved) {
     },
     assertValidPayTo(payTo) {
       if (!_viem.isAddress.call(void 0, payTo)) {
-        throw new (0, _chunkYJPWIK5Lcjs.WrongFamilyError)(
+        throw new (0, _chunkIQGT65WScjs.WrongFamilyError)(
           `chain ${network} is EVM, but payTo "${payTo}" is not a valid 0x address.`
         );
       }
     },
     bindWallet(wallet) {
       if (typeof wallet !== "object" || wallet === null || !("privateKey" in wallet) && !("walletClient" in wallet)) {
-        throw new (0, _chunkYJPWIK5Lcjs.WrongFamilyError)(
+        throw new (0, _chunkIQGT65WScjs.WrongFamilyError)(
           `chain ${network} is EVM; wallet must be { privateKey } or { walletClient }.`
         );
       }
@@ -670,12 +671,12 @@ function makeEvmNetwork(resolved) {
         });
       } catch (err) {
         if (isViemInsufficientFunds(err)) {
-          throw new (0, _chunkYJPWIK5Lcjs.InsufficientFundsError)(
+          throw new (0, _chunkIQGT65WScjs.InsufficientFundsError)(
             err instanceof Error ? err.message : "Insufficient funds for payment.",
             { cause: err }
           );
         }
-        throw _nullishCoalesce(_chunkYJPWIK5Lcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+        throw _nullishCoalesce(_chunkIQGT65WScjs.toInsufficientFundsError.call(void 0, err), () => ( err));
       }
     },
     async confirm(ref, minConfirmations) {
@@ -686,7 +687,7 @@ function makeEvmNetwork(resolved) {
         });
         return { height: receipt.blockNumber.toString() };
       } catch (err) {
-        throw new (0, _chunkYJPWIK5Lcjs.ConfirmationTimeoutError)(
+        throw new (0, _chunkIQGT65WScjs.ConfirmationTimeoutError)(
           `EVM tx ${ref} did not reach ${minConfirmations} confirmation(s) in time.`,
           { cause: err }
         );
@@ -697,7 +698,7 @@ function makeEvmNetwork(resolved) {
       const gasLimit = accept.asset === "native" ? 21000n : 65000n;
       try {
         const gasPrice = await publicClient.getGasPrice();
-        return _chunkYJPWIK5Lcjs.nativeCost.call(void 0, {
+        return _chunkIQGT65WScjs.nativeCost.call(void 0, {
           symbol,
           decimals,
           fee: gasPrice * gasLimit,
@@ -706,7 +707,7 @@ function makeEvmNetwork(resolved) {
         });
       } catch (e10) {
         const gasPrice = 5000000000n;
-        return _chunkYJPWIK5Lcjs.nativeCost.call(void 0, {
+        return _chunkIQGT65WScjs.nativeCost.call(void 0, {
           symbol,
           decimals,
           fee: gasPrice * gasLimit,
@@ -715,6 +716,27 @@ function makeEvmNetwork(resolved) {
         });
       }
     },
+    async balanceOf(wallet, asset) {
+      const owner = wallet._native.account.address;
+      const native = await publicClient.getBalance({ address: owner }).catch(() => null);
+      if (asset === "native") return { token: native, native };
+      let token = null;
+      try {
+        token = await publicClient.readContract({
+          address: _viem.getAddress.call(void 0, asset),
+          abi: _viem.erc20Abi,
+          functionName: "balanceOf",
+          args: [owner]
+        });
+      } catch (e11) {
+        token = null;
+      }
+      return { token, native };
+    },
+    // EVM has no receive prerequisite — any 0x address receives native or ERC-20 immediately.
+    async recipientReady() {
+      return { ready: "n/a" };
+    },
     async verify(ref, accept) {
       return verifyEvm({
         publicClient,
@@ -738,9 +760,9 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./solana-RJPNEFSN.cjs")));
+      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./solana-W24TCJV4.cjs")));
     } catch (cause) {
-      throw new (0, _chunkYJPWIK5Lcjs.MissingDriverError)(
+      throw new (0, _chunkIQGT65WScjs.MissingDriverError)(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
         { cause }
       );
@@ -750,9 +772,9 @@ var loaders = {
   ton: async () => {
     let mod;
     try {
-      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./ton-C4KTFXDL.cjs")));
+      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./ton-FIQGV2LC.cjs")));
     } catch (cause) {
-      throw new (0, _chunkYJPWIK5Lcjs.MissingDriverError)(
+      throw new (0, _chunkIQGT65WScjs.MissingDriverError)(
         `TON selected, but its packages aren't installed. Run: npm install @ton/ton @ton/core @ton/crypto`,
         { cause }
       );
@@ -762,9 +784,9 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./stellar-SUGNX52Z.cjs")));
+      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./stellar-YMY3K2YB.cjs")));
     } catch (cause) {
-      throw new (0, _chunkYJPWIK5Lcjs.MissingDriverError)(
+      throw new (0, _chunkIQGT65WScjs.MissingDriverError)(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
         { cause }
       );
@@ -774,9 +796,9 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./xrpl-N6ZAJRGC.cjs")));
+      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./xrpl-2PKP7HOI.cjs")));
     } catch (cause) {
-      throw new (0, _chunkYJPWIK5Lcjs.MissingDriverError)(
+      throw new (0, _chunkIQGT65WScjs.MissingDriverError)(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
         { cause }
       );
@@ -786,9 +808,9 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./tron-DTU7NPEM.cjs")));
+      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./tron-ZSXAPZ2C.cjs")));
     } catch (cause) {
-      throw new (0, _chunkYJPWIK5Lcjs.MissingDriverError)(
+      throw new (0, _chunkIQGT65WScjs.MissingDriverError)(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
         { cause }
       );
@@ -798,9 +820,9 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./sui-HZWPHVU4.cjs")));
+      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./sui-32KVESR5.cjs")));
     } catch (cause) {
-      throw new (0, _chunkYJPWIK5Lcjs.MissingDriverError)(
+      throw new (0, _chunkIQGT65WScjs.MissingDriverError)(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
         { cause }
       );
@@ -810,9 +832,9 @@ var loaders = {
   near: async () => {
     let mod;
     try {
-      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./near-DISWUB7Y.cjs")));
+      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./near-GGUHLXAF.cjs")));
     } catch (cause) {
-      throw new (0, _chunkYJPWIK5Lcjs.MissingDriverError)(
+      throw new (0, _chunkIQGT65WScjs.MissingDriverError)(
         `NEAR selected, but its package isn't installed. Run: npm install near-api-js`,
         { cause }
       );
@@ -822,14 +844,26 @@ var loaders = {
   aptos: async () => {
     let mod;
     try {
-      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./aptos-MKZ5MAGL.cjs")));
+      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./aptos-X3G2UBYW.cjs")));
     } catch (cause) {
-      throw new (0, _chunkYJPWIK5Lcjs.MissingDriverError)(
+      throw new (0, _chunkIQGT65WScjs.MissingDriverError)(
         `Aptos selected, but its package isn't installed. Run: npm install @aptos-labs/ts-sdk`,
         { cause }
       );
     }
     registerDriver(mod.aptosDriver);
+  },
+  algorand: async () => {
+    let mod;
+    try {
+      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./algorand-IJJKE35X.cjs")));
+    } catch (cause) {
+      throw new (0, _chunkIQGT65WScjs.MissingDriverError)(
+        `Algorand selected, but its package isn't installed. Run: npm install algosdk`,
+        { cause }
+      );
+    }
+    registerDriver(mod.algorandDriver);
   }
 };
 var inFlight = /* @__PURE__ */ new Map();
@@ -896,7 +930,7 @@ function evaluatePolicy(intent, policy, spentForAssetBase) {
     }
   }
   if (policy.maxAmount !== void 0) {
-    const cap = _chunkYJPWIK5Lcjs.floorUnits.call(void 0, policy.maxAmount, intent.decimals);
+    const cap = _chunkIQGT65WScjs.floorUnits.call(void 0, policy.maxAmount, intent.decimals);
     if (intent.amountBase > cap) {
       return deny(
         `payment of ${intent.amountBase} base units exceeds policy.maxAmount ` + `(${policy.maxAmount} ${_nullishCoalesce(intent.symbol, () => ( ""))}).`.trimEnd()
@@ -904,7 +938,7 @@ function evaluatePolicy(intent, policy, spentForAssetBase) {
     }
   }
   if (policy.maxTotal !== void 0) {
-    const cap = _chunkYJPWIK5Lcjs.floorUnits.call(void 0, policy.maxTotal, intent.decimals);
+    const cap = _chunkIQGT65WScjs.floorUnits.call(void 0, policy.maxTotal, intent.decimals);
     if (spentForAssetBase + intent.amountBase > cap) {
       return deny(
         `this payment would push spend on ${_nullishCoalesce(intent.symbol, () => ( intent.asset))} past policy.maxTotal (${policy.maxTotal}); already spent ${spentForAssetBase} base units.`
@@ -954,7 +988,7 @@ var SpendLedger = (_class = class {constructor() { _class.prototype.__init.call(
         symbol: b.symbol,
         decimals: b.decimals,
         totalBase: b.total.toString(),
-        totalFormatted: _chunkYJPWIK5Lcjs.formatUnits.call(void 0, b.total, b.decimals),
+        totalFormatted: _chunkIQGT65WScjs.formatUnits.call(void 0, b.total, b.decimals),
         count: b.count
       })),
       records: [...this.records]
@@ -963,6 +997,12 @@ var SpendLedger = (_class = class {constructor() { _class.prototype.__init.call(
 }, _class);
 
 // src/client.ts
+var RECIPIENT_FIX = {
+  NO_TRUSTLINE: "the recipient needs a one-time trustline for this asset before it can receive",
+  NOT_REGISTERED: "the recipient must be storage_deposit-registered on this token (NEP-145, one-time)",
+  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 PipRailClient = (_class2 = class {
   
   
@@ -985,7 +1025,7 @@ var PipRailClient = (_class2 = class {
   safeEmit(event) {
     try {
       this.onEvent(event);
-    } catch (e11) {
+    } catch (e12) {
     }
   }
   /** Auto-mount the chain's driver, resolve the network, and bind the wallet — once. */
@@ -1071,6 +1111,44 @@ var PipRailClient = (_class2 = class {
   spent() {
     return this.ledger.summary();
   }
+  /**
+   * Plan a payment for a gated URL — WITHOUT paying. The read-only completion of
+   * the `quote()` → `estimateCost()` → **`planPayment()`** trio: it surveys every
+   * rail the 402 offers on this client's chain against the wallet's OWN holdings —
+   * token balance, native-coin gas, and recipient-readiness (trustline / ATA /
+   * storage_deposit / ASA opt-in) — and returns, crystal-clear:
+   *   - `payable` + `best`   — the cheapest rail the wallet can actually settle
+   *   - `options[]`          — every rail with typed `blockers` + soft `warnings`
+   *   - `fundingHint`        — one human sentence on exactly what to top up
+   *
+   * NEVER throws for a read problem (a transient/RPC failure surfaces as a rail in
+   * `state: 'unknown'` + a warning, never a false "unaffordable"); returns `null`
+   * when the URL isn't payment-gated (no 402); and when the 402 offers no rail on
+   * this client's chain it EXPLAINS that (status `blocked` + a hint), rather than
+   * throwing. Throws `InvalidEnvelopeError` only on an unparseable challenge.
+   *
+   * Then pay the chosen rail with `fetch(url, { autoRoute: true })`, or branch on
+   * the plan yourself. No funds move.
+   */
+  async planPayment(url, init) {
+    const res = await fetch(url, { ..._nullishCoalesce(init, () => ( {})), method: _nullishCoalesce(_optionalChain([init, 'optionalAccess', _9 => _9.method]), () => ( "GET")) });
+    if (res.status !== 402) return null;
+    const challenge = await parseChallenge(res);
+    if (!challenge) {
+      throw new (0, _chunkIQGT65WScjs.InvalidEnvelopeError)("402 response did not include a parseable x402 challenge.");
+    }
+    const { net, wallet } = await this.ensure();
+    return this.planFromChallenge(net, wallet, challenge, url);
+  }
+  /**
+   * Convenience over {@link planPayment}: can the wallet settle this URL right now?
+   * `true` when at least one rail is payable — or when the URL isn't gated (a free
+   * resource is trivially "affordable"). No funds move.
+   */
+  async canAfford(url, init) {
+    const plan = await this.planPayment(url, init);
+    return plan == null ? true : plan.payable;
+  }
   /**
    * Lower-level: drive any HTTP method through the 402 flow.
    *
@@ -1079,18 +1157,27 @@ var PipRailClient = (_class2 = class {
    * streams throw `NonReplayableBodyError`.
    */
   async fetch(url, init) {
-    const body = _optionalChain([init, 'optionalAccess', _9 => _9.body]);
+    const body = _optionalChain([init, 'optionalAccess', _10 => _10.body]);
     if (body !== void 0 && body !== null && !isReplayableBodyInit(body)) {
-      throw new (0, _chunkYJPWIK5Lcjs.NonReplayableBodyError)(
+      throw new (0, _chunkIQGT65WScjs.NonReplayableBodyError)(
         "fetch(): init.body is not replayable. Pass a string, FormData, URLSearchParams, ArrayBuffer, or Blob \u2014 not a ReadableStream."
       );
     }
     const firstResponse = await fetch(url, init);
     if (firstResponse.status !== 402) return firstResponse;
-    const { net, wallet, accept, challenge, quote } = await this.resolveChallenge(
-      url,
-      firstResponse
-    );
+    const resolved = await this.resolveChallenge(url, firstResponse);
+    const { net, wallet, challenge } = resolved;
+    let accept = resolved.accept;
+    let quote = resolved.quote;
+    const autoRoute = _nullishCoalesce(_nullishCoalesce(_optionalChain([init, 'optionalAccess', _11 => _11.autoRoute]), () => ( this.opts.autoRoute)), () => ( false));
+    if (autoRoute) {
+      const plan = await this.planFromChallenge(net, wallet, challenge, url);
+      if (!plan.best) {
+        throw new (0, _chunkIQGT65WScjs.PaymentDeclinedError)(_nullishCoalesce(plan.fundingHint, () => ( "No rail is settleable for this payment.")));
+      }
+      accept = plan.best.accept;
+      quote = plan.best.quote;
+    }
     this.safeEmit({ kind: "payment-required", challenge, accept });
     await this.authorize(quote);
     const { ref, confirmed } = await this.payAndConfirm(net, wallet, accept);
@@ -1107,17 +1194,15 @@ var PipRailClient = (_class2 = class {
   async resolveChallenge(url, response) {
     const challenge = await parseChallenge(response);
     if (!challenge) {
-      throw new (0, _chunkYJPWIK5Lcjs.InvalidEnvelopeError)(
+      throw new (0, _chunkIQGT65WScjs.InvalidEnvelopeError)(
         "402 response did not include a parseable x402 challenge."
       );
     }
     const { net, wallet } = await this.ensure();
-    const candidates = challenge.accepts.filter(
-      (a) => a.scheme === "onchain-proof" && net.supports(a.network)
-    );
+    const candidates = this.gatherCandidates(net, challenge);
     if (candidates.length === 0) {
       const networks = challenge.accepts.map((a) => a.network).join(", ");
-      throw new (0, _chunkYJPWIK5Lcjs.NoCompatibleAcceptError)(
+      throw new (0, _chunkIQGT65WScjs.NoCompatibleAcceptError)(
         `No accepts[] entry for ${net.network} (challenge offered: ${networks || "none"}).`
       );
     }
@@ -1128,19 +1213,124 @@ var PipRailClient = (_class2 = class {
     const chosen = _nullishCoalesce(priced.find((p) => p.quote.withinPolicy), () => ( priced[0]));
     return { net, wallet, accept: chosen.accept, challenge, quote: chosen.quote };
   }
+  /** The candidate accepts this client could pay: our scheme, on the bound network. */
+  gatherCandidates(net, challenge) {
+    return challenge.accepts.filter(
+      (a) => a.scheme === "onchain-proof" && net.supports(a.network)
+    );
+  }
+  /** Build the full {@link PaymentPlan} from an already-parsed challenge + bound
+   *  net/wallet. Shared by `planPayment` (read-only) and `fetch`'s autoRoute. */
+  async planFromChallenge(net, wallet, challenge, url) {
+    const chainLabel = typeof this.opts.chain === "string" ? this.opts.chain : net.network;
+    const candidates = this.gatherCandidates(net, challenge);
+    if (candidates.length === 0) {
+      const offered = [...new Set(challenge.accepts.map((a) => a.network))].join(", ") || "none";
+      return {
+        url,
+        network: net.network,
+        status: "blocked",
+        payable: false,
+        best: null,
+        options: [],
+        fundingHint: `This 402 isn't offered on your chain (${chainLabel}); it's payable on: ${offered}.`
+      };
+    }
+    const analysed = await Promise.all(
+      candidates.map(
+        (accept) => this.analyzeRail(net, wallet, accept, url, challenge.resource.description)
+      )
+    );
+    const options = rankOptions(analysed);
+    const best = _nullishCoalesce(options.find((o) => o.state === "payable"), () => ( null));
+    const status = best ? "ready" : options.some((o) => o.state === "unknown") ? "unknown" : "blocked";
+    return {
+      url,
+      network: net.network,
+      status,
+      payable: best !== null,
+      best,
+      options,
+      fundingHint: best ? null : buildFundingHint(options, chainLabel)
+    };
+  }
+  /** Analyse ONE rail against the wallet's holdings — quote (existing) + gas
+   *  (estimateCost, existing) + balanceOf + recipientReady → a {@link PayOption}. */
+  async analyzeRail(net, wallet, accept, url, description) {
+    const quote = this.buildQuote(net, accept, url, description);
+    const cost = await net.estimateCost(accept);
+    const bal = await net.balanceOf(wallet, accept.asset).catch(() => ({ token: null, native: null }));
+    const rr = await net.recipientReady(accept.payTo, accept.asset).catch(() => ({ ready: "unknown" }));
+    const amount = BigInt(accept.amount);
+    const fee = safeBig(cost.fee);
+    const isNative = accept.asset === "native";
+    const blockers = [];
+    const warnings = [];
+    const shortfall = {};
+    if (!quote.withinPolicy) blockers.push("OUTSIDE_POLICY");
+    if (quote.symbolMismatch) warnings.push("SYMBOL_MISMATCH");
+    if (cost.basis === "heuristic") warnings.push("GAS_HEURISTIC");
+    const tokenKnown = bal.token != null;
+    const nativeKnown = bal.native != null;
+    if (!tokenKnown || !nativeKnown) warnings.push("BALANCE_UNREADABLE");
+    if (isNative) {
+      if (nativeKnown && bal.native < amount + fee) {
+        blockers.push("INSUFFICIENT_TOKEN");
+        shortfall.token = _chunkIQGT65WScjs.formatUnits.call(void 0, amount + fee - bal.native, quote.decimals);
+      }
+    } else {
+      if (tokenKnown && bal.token < amount) {
+        blockers.push("INSUFFICIENT_TOKEN");
+        shortfall.token = _chunkIQGT65WScjs.formatUnits.call(void 0, amount - bal.token, quote.decimals);
+      }
+      if (nativeKnown && bal.native < fee) {
+        blockers.push("INSUFFICIENT_GAS");
+        shortfall.native = _chunkIQGT65WScjs.formatUnits.call(void 0, fee - bal.native, cost.feeDecimals);
+      } else if (nativeKnown && fee > 0n && bal.native < fee * 3n / 2n) {
+        warnings.push("THIN_GAS_MARGIN");
+      }
+    }
+    let recipient;
+    if (rr.ready === false) {
+      blockers.push("RECIPIENT_NOT_READY");
+      recipient = rr.reason ? { ready: false, reason: rr.reason, fix: RECIPIENT_FIX[rr.reason] } : { ready: false };
+    } else if (rr.ready === "unknown") {
+      warnings.push("RECIPIENT_READINESS_UNKNOWN");
+      recipient = { ready: "unknown" };
+    } else {
+      recipient = { ready: rr.ready };
+    }
+    const unreadable = isNative ? !nativeKnown : !tokenKnown || !nativeKnown;
+    const state = blockers.length ? "blocked" : unreadable || rr.ready === "unknown" ? "unknown" : "payable";
+    return {
+      accept,
+      quote,
+      cost,
+      state,
+      blockers,
+      warnings,
+      balance: {
+        token: bal.token != null ? _chunkIQGT65WScjs.formatUnits.call(void 0, bal.token, quote.decimals) : null,
+        native: bal.native != null ? _chunkIQGT65WScjs.formatUnits.call(void 0, bal.native, cost.feeDecimals) : null
+      },
+      need: { token: quote.amountFormatted, native: cost.feeFormatted },
+      ...shortfall.token || shortfall.native ? { shortfall } : {},
+      recipient
+    };
+  }
   /** Build the agent-facing quote for an accept: TRUE decimals/symbol (via the
    *  driver's describeAsset) + the policy verdict + a symbol-mismatch flag. */
   buildQuote(net, accept, url, description) {
     if (!/^\d+$/.test(accept.amount)) {
-      throw new (0, _chunkYJPWIK5Lcjs.InvalidEnvelopeError)(
+      throw new (0, _chunkIQGT65WScjs.InvalidEnvelopeError)(
         `challenge amount "${accept.amount}" is not a base-unit integer.`
       );
     }
     const amountBase = BigInt(accept.amount);
     const described = net.describeAsset(accept.asset);
-    const decimals = _nullishCoalesce(_optionalChain([described, 'optionalAccess', _10 => _10.decimals]), () => ( accept.extra.decimals));
-    const symbol = _nullishCoalesce(_optionalChain([described, 'optionalAccess', _11 => _11.symbol]), () => ( accept.extra.symbol));
-    const amountFormatted = _chunkYJPWIK5Lcjs.formatUnits.call(void 0, amountBase, decimals);
+    const decimals = _nullishCoalesce(_optionalChain([described, 'optionalAccess', _12 => _12.decimals]), () => ( accept.extra.decimals));
+    const symbol = _nullishCoalesce(_optionalChain([described, 'optionalAccess', _13 => _13.symbol]), () => ( accept.extra.symbol));
+    const amountFormatted = _chunkIQGT65WScjs.formatUnits.call(void 0, amountBase, decimals);
     const intent = {
       host: hostOf(url),
       chain: this.opts.chain,
@@ -1180,7 +1370,7 @@ var PipRailClient = (_class2 = class {
    *  throwing PaymentDeclinedError, before any funds move. */
   async authorize(quote) {
     if (!quote.withinPolicy) {
-      throw new (0, _chunkYJPWIK5Lcjs.PaymentDeclinedError)(
+      throw new (0, _chunkIQGT65WScjs.PaymentDeclinedError)(
         `Payment refused by policy: ${_nullishCoalesce(quote.policyReason, () => ( "not allowed"))}`
       );
     }
@@ -1190,12 +1380,12 @@ var PipRailClient = (_class2 = class {
     try {
       approved = await hook(quote);
     } catch (err) {
-      throw new (0, _chunkYJPWIK5Lcjs.PaymentDeclinedError)("onBeforePay threw \u2014 refusing to pay.", {
+      throw new (0, _chunkIQGT65WScjs.PaymentDeclinedError)("onBeforePay threw \u2014 refusing to pay.", {
         cause: err
       });
     }
     if (!approved) {
-      throw new (0, _chunkYJPWIK5Lcjs.PaymentDeclinedError)(
+      throw new (0, _chunkIQGT65WScjs.PaymentDeclinedError)(
         `onBeforePay declined ${quote.amountFormatted} ${_nullishCoalesce(quote.symbol, () => ( ""))}`.trimEnd() + ` on ${quote.network}.`
       );
     }
@@ -1219,7 +1409,7 @@ var PipRailClient = (_class2 = class {
   }
   async payAndConfirm(net, wallet, accept) {
     if (!net.supports(accept.network)) {
-      throw new (0, _chunkYJPWIK5Lcjs.WrongChainError)(
+      throw new (0, _chunkIQGT65WScjs.WrongChainError)(
         `Challenge expects ${accept.network} but client is on ${net.network}.`
       );
     }
@@ -1248,7 +1438,7 @@ var PipRailClient = (_class2 = class {
       accepted: accept,
       payload: { nonce: accept.extra.nonce, txHash: ref }
     };
-    const headers = new Headers(_optionalChain([originalInit, 'optionalAccess', _12 => _12.headers]));
+    const headers = new Headers(_optionalChain([originalInit, 'optionalAccess', _14 => _14.headers]));
     headers.set(HEADER_SIGNATURE, buildSignatureHeader(signature));
     let lastResponse = null;
     let lastReason = null;
@@ -1263,7 +1453,7 @@ var PipRailClient = (_class2 = class {
         () => timeoutController.abort(),
         this.retryTimeoutMs
       );
-      const signal = _optionalChain([originalInit, 'optionalAccess', _13 => _13.signal]) && typeof AbortSignal.any === "function" ? AbortSignal.any([timeoutController.signal, originalInit.signal]) : timeoutController.signal;
+      const signal = _optionalChain([originalInit, 'optionalAccess', _15 => _15.signal]) && typeof AbortSignal.any === "function" ? AbortSignal.any([timeoutController.signal, originalInit.signal]) : timeoutController.signal;
       try {
         lastResponse = await fetch(url, {
           ..._nullishCoalesce(originalInit, () => ( {})),
@@ -1272,7 +1462,7 @@ var PipRailClient = (_class2 = class {
         });
       } catch (err) {
         if (timeoutController.signal.aborted) {
-          throw new (0, _chunkYJPWIK5Lcjs.PaymentTimeoutError)(
+          throw new (0, _chunkIQGT65WScjs.PaymentTimeoutError)(
             `Server did not respond within ${this.retryTimeoutMs}ms after broadcasting payment ${ref}. Re-verify or re-submit ref=${ref} \u2014 do NOT re-pay.`,
             { cause: err, ref }
           );
@@ -1294,16 +1484,78 @@ var PipRailClient = (_class2 = class {
       kind: "payment-failed",
       reason: `server returned 402 after broadcasting payment ${ref}${unconfirmedNote} (${why})`
     });
-    throw new (0, _chunkYJPWIK5Lcjs.MaxRetriesExceededError)(
+    throw new (0, _chunkIQGT65WScjs.MaxRetriesExceededError)(
       `Server still returned 402 after ${attempts} attempt(s) with on-chain proof ref=${ref}${unconfirmedNote}. Last server rejection: ${why}. Re-verify or re-submit ref=${ref} before retrying \u2014 never re-pay (it would double-spend).`,
       { ref }
     );
   }
 }, _class2);
+function safeBig(s) {
+  try {
+    return BigInt(s);
+  } catch (e13) {
+    return 0n;
+  }
+}
+function shortAddr(a) {
+  return a.length > 14 ? `${a.slice(0, 8)}\u2026${a.slice(-4)}` : a;
+}
+function rankOptions(options) {
+  const rank = { payable: 0, unknown: 1, blocked: 2 };
+  return [...options].sort((a, b) => {
+    if (rank[a.state] !== rank[b.state]) return rank[a.state] - rank[b.state];
+    if (a.state === "payable") {
+      const fa = safeBig(a.cost.fee);
+      const fb = safeBig(b.cost.fee);
+      if (fa !== fb) return fa < fb ? -1 : 1;
+    }
+    return 0;
+  });
+}
+function buildFundingHint(options, chainLabel) {
+  if (options.length === 0) return null;
+  const target = [...options].sort((a, b) => a.blockers.length - b.blockers.length)[0];
+  const sym = _nullishCoalesce(target.quote.symbol, () => ( "the token"));
+  if (target.blockers.includes("RECIPIENT_NOT_READY")) {
+    return `Recipient ${shortAddr(target.accept.payTo)} can't receive on ${chainLabel} yet \u2014 ${_nullishCoalesce(target.recipient.fix, () => ( "recipient not ready"))}.`;
+  }
+  if (target.blockers.includes("OUTSIDE_POLICY")) {
+    return `Refused by spend policy: ${_nullishCoalesce(target.quote.policyReason, () => ( "not allowed"))}.`;
+  }
+  if (target.state === "unknown") {
+    return `Couldn't fully read your wallet on ${chainLabel} (RPC throttled) \u2014 retry; you may already be able to pay ${target.quote.amountFormatted} ${sym}.`;
+  }
+  const parts = [];
+  if (target.blockers.includes("INSUFFICIENT_TOKEN") && _optionalChain([target, 'access', _16 => _16.shortfall, 'optionalAccess', _17 => _17.token])) {
+    parts.push(`top up ${target.shortfall.token} ${sym}`);
+  }
+  if (target.blockers.includes("INSUFFICIENT_GAS") && _optionalChain([target, 'access', _18 => _18.shortfall, 'optionalAccess', _19 => _19.native])) {
+    parts.push(`add ~${target.shortfall.native} ${target.cost.feeSymbol} for gas`);
+  }
+  return parts.length ? `Can't settle on ${chainLabel}: ${parts.join(" and ")} (to pay ${target.quote.amountFormatted} ${sym}).` : `Can't settle on ${chainLabel} for ${target.quote.amountFormatted} ${sym}.`;
+}
+async function planAcross(clients, url, init) {
+  const plans = await Promise.all(clients.map((c) => c.planPayment(url, init).catch(() => null)));
+  const live = plans.filter((p) => p != null);
+  if (live.length === 0) return null;
+  const options = rankOptions(live.flatMap((p) => p.options));
+  const best = _nullishCoalesce(options.find((o) => o.state === "payable"), () => ( null));
+  const status = best ? "ready" : options.some((o) => o.state === "unknown") ? "unknown" : "blocked";
+  return {
+    url,
+    network: _nullishCoalesce(_optionalChain([best, 'optionalAccess', _20 => _20.accept, 'access', _21 => _21.network]), () => ( live[0].network)),
+    status,
+    payable: best !== null,
+    best,
+    options,
+    // First non-null hint across clients — each already names its chain.
+    fundingHint: best ? null : _nullishCoalesce(live.map((p) => p.fundingHint).find(Boolean), () => ( null))
+  };
+}
 function hostOf(url) {
   try {
     return new URL(url).hostname;
-  } catch (e12) {
+  } catch (e14) {
     return url;
   }
 }
@@ -1326,7 +1578,7 @@ async function readInvalidReason(response) {
         detail: typeof body.detail === "string" ? body.detail : ""
       };
     }
-  } catch (e13) {
+  } catch (e15) {
   }
   return null;
 }
@@ -1337,7 +1589,7 @@ async function readBody(res) {
   if (!text) return null;
   try {
     return JSON.parse(text);
-  } catch (e14) {
+  } catch (e16) {
     return text;
   }
 }
@@ -1359,6 +1611,44 @@ function paymentTools(client) {
         return quote ? { gated: true, ...quote } : { gated: false, url: String(args.url) };
       }
     },
+    {
+      name: "piprail_plan_payment",
+      description: "Check whether you CAN pay an x402-gated URL before paying. Reads your wallet balance, native gas, and whether the recipient can receive \u2014 across every rail the URL offers on your chain \u2014 and returns { gated, payable, best, options, fundingHint }. payable:false means do NOT attempt the payment; fundingHint says exactly what to top up. Call this before piprail_pay_request so you never commit to a payment you cannot finish. Returns { gated: false } when no payment is needed.",
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "Full URL of the gated resource." }
+        },
+        required: ["url"],
+        additionalProperties: false
+      },
+      invoke: async (args) => {
+        const plan = await client.planPayment(String(args.url));
+        if (plan == null) return { gated: false, url: String(args.url) };
+        return {
+          gated: true,
+          payable: plan.payable,
+          status: plan.status,
+          fundingHint: plan.fundingHint,
+          best: plan.best ? {
+            network: plan.best.accept.network,
+            symbol: plan.best.quote.symbol,
+            amount: plan.best.quote.amountFormatted,
+            gasCoin: plan.best.cost.feeSymbol,
+            gas: plan.best.cost.feeFormatted
+          } : null,
+          options: plan.options.map((o) => ({
+            network: o.accept.network,
+            symbol: o.quote.symbol,
+            amount: o.quote.amountFormatted,
+            state: o.state,
+            blockers: o.blockers,
+            warnings: o.warnings,
+            recipientReady: o.recipient.ready
+          }))
+        };
+      }
+    },
     {
       name: "piprail_pay_request",
       description: "Fetch an x402 payment-gated URL, automatically paying the required on-chain payment if needed (subject to the spend policy + approval hook). Returns the HTTP status, the response body, and a payment receipt if one settled. If the payment is refused by policy or the approval hook, returns { declined: true, reason } \u2014 no funds moved.",
@@ -1402,7 +1692,7 @@ function paymentTools(client) {
             receipt: parseReceipt(res)
           };
         } catch (err) {
-          if (err instanceof _chunkYJPWIK5Lcjs.PaymentDeclinedError) {
+          if (err instanceof _chunkIQGT65WScjs.PaymentDeclinedError) {
             return { declined: true, reason: err.message };
           }
           throw err;
@@ -1451,7 +1741,7 @@ function createPaymentGate(options) {
           }
           net.assertValidPayTo(payTo);
           const { asset, decimals, symbol } = net.resolveToken(a.token);
-          const amountBase = _chunkYJPWIK5Lcjs.parseUnits.call(void 0, a.amount, decimals);
+          const amountBase = _chunkIQGT65WScjs.parseUnits.call(void 0, a.amount, decimals);
           return { net, asset, decimals, symbol, amountBase, amountFormatted: a.amount, payTo };
         })
       );
@@ -1552,7 +1842,7 @@ function createPaymentGate(options) {
     if (options.onPaid) {
       try {
         options.onPaid(result.receipt);
-      } catch (e15) {
+      } catch (e17) {
       }
     }
     return {
@@ -1659,8 +1949,8 @@ async function buildExactAuthorization(params) {
   };
   const signature = await account.signTypedData({
     domain: {
-      name: _nullishCoalesce(_optionalChain([accept, 'access', _14 => _14.extra, 'optionalAccess', _15 => _15.name]), () => ( "USD Coin")),
-      version: _nullishCoalesce(_optionalChain([accept, 'access', _16 => _16.extra, 'optionalAccess', _17 => _17.version]), () => ( "2")),
+      name: _nullishCoalesce(_optionalChain([accept, 'access', _22 => _22.extra, 'optionalAccess', _23 => _23.name]), () => ( "USD Coin")),
+      version: _nullishCoalesce(_optionalChain([accept, 'access', _24 => _24.extra, 'optionalAccess', _25 => _25.version]), () => ( "2")),
       chainId,
       verifyingContract: accept.asset
     },
@@ -1730,4 +2020,5 @@ function encodeXPaymentHeader(input) {
 
 
 
-exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkYJPWIK5Lcjs.ConfirmationTimeoutError; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.InsufficientFundsError = _chunkYJPWIK5Lcjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkYJPWIK5Lcjs.InvalidEnvelopeError; exports.MaxRetriesExceededError = _chunkYJPWIK5Lcjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkYJPWIK5Lcjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkYJPWIK5Lcjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkYJPWIK5Lcjs.NonReplayableBodyError; exports.PaymentDeclinedError = _chunkYJPWIK5Lcjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkYJPWIK5Lcjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkYJPWIK5Lcjs.PipRailError; exports.RecipientNotReadyError = _chunkYJPWIK5Lcjs.RecipientNotReadyError; exports.UnknownTokenError = _chunkYJPWIK5Lcjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkYJPWIK5Lcjs.UnsupportedNetworkError; exports.WrongChainError = _chunkYJPWIK5Lcjs.WrongChainError; exports.WrongFamilyError = _chunkYJPWIK5Lcjs.WrongFamilyError; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSignatureHeader = buildSignatureHeader; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.createPaymentGate = createPaymentGate; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.parseChallenge = parseChallenge; exports.parseExactRequirements = parseExactRequirements; exports.parseReceipt = parseReceipt; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.registerDriver = registerDriver; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.toInsufficientFundsError = _chunkYJPWIK5Lcjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody;
+
+exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkIQGT65WScjs.ConfirmationTimeoutError; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.InsufficientFundsError = _chunkIQGT65WScjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkIQGT65WScjs.InvalidEnvelopeError; exports.MaxRetriesExceededError = _chunkIQGT65WScjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkIQGT65WScjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkIQGT65WScjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkIQGT65WScjs.NonReplayableBodyError; exports.PaymentDeclinedError = _chunkIQGT65WScjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkIQGT65WScjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkIQGT65WScjs.PipRailError; exports.RecipientNotReadyError = _chunkIQGT65WScjs.RecipientNotReadyError; exports.UnknownTokenError = _chunkIQGT65WScjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkIQGT65WScjs.UnsupportedNetworkError; exports.WrongChainError = _chunkIQGT65WScjs.WrongChainError; exports.WrongFamilyError = _chunkIQGT65WScjs.WrongFamilyError; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSignatureHeader = buildSignatureHeader; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.createPaymentGate = createPaymentGate; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.parseChallenge = parseChallenge; exports.parseExactRequirements = parseExactRequirements; exports.parseReceipt = parseReceipt; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.registerDriver = registerDriver; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.toInsufficientFundsError = _chunkIQGT65WScjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody;