@piprail/sdk 3.1.0 → 3.1.2

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [3.1.2] — 2026-09-09 — a balance says what it means
+
+### Fixed
+
+- **Three descriptions of a balance still said HOLDS after 3.1.0 made it SPENDABLE.** 3.1.0
+  changed the drivers to deduct a chain's retained minimum (Solana rent, XRPL/Stellar/Algorand
+  reserves) from the native figure, and documented that precisely on `WalletBalance.token` — but
+  every layer above it kept the old wording. `PipRailClient.balanceOf`'s TSDoc, the interface it
+  implements, and the `piprail_wallet` tool description a MODEL reads all still promised "what you
+  hold". They now say what they mean, and name the gap as locked rather than lost.
+
+  The wording mattered most in the tool description, because an agent comparing its own balance
+  against a block explorer sees a smaller number and has to decide whether it is being lied to. On
+  a live Stellar account holding 1.5398 XLM with three subentries, `balanceOf` reports 0.0398: the
+  1.5 XLM difference is the base reserve. Text only; no behaviour changes.
+
+## [3.1.1] — 2026-09-09 — XRPL payments work again
+
+### Fixed
+
+- **A facilitator's payload rejection answered 5xx instead of 402.** Every non-200 from a
+  facilitator's `/verify` was treated as a transport failure, so a **400** — a forged or
+  malformed authorization — made the gate return a server error. That tells the buyer "our
+  fault, try again" about a payment that can never succeed, and shows in the merchant's metrics
+  as an outage they do not have. Now only `400`/`422` (the payload is bad, and only the buyer
+  can fix it) reject with the facilitator's own reason; `401`/`403` (our credentials),
+  `404` (our URL), `429` and `5xx` stay `SettlementError`, because a buyer can do nothing about
+  any of them. Found by tampering with a real authorization on Base.
+
+- 🔴 **Every XRPL payment failed.** `ledger_current` is documented to return
+  `ledger_current_index`, and rippled does, but the public clusters in front of it answer with
+  `ledger_index`. Reading only the documented name returned `undefined`, `undefined + 20` became
+  `NaN`, and the transaction died in xrpl.js's serializer. Both names are now accepted, and a
+  response carrying neither is refused with a message that says nothing was signed.
+
+  Latent since XRPL shipped and intermittent by nature: it depends on which backend the cluster
+  routes to, which is why the same wallet settled all morning and then could not settle at all.
+  Caught by a post-release live sweep against the published package — the pre-flight guard added
+  in 3.1.0 is what turned an unreadable serializer error into a sentence naming the field.
+
 ## [3.1.0] — 2026-09-09 — spendable is not held, and a swap refused for no reason
 
 ### Fixed
@@ -2642,6 +2682,8 @@ straight into your wallet. The API is small and self-contained.
 [1.5.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.4.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.3.1]: https://www.npmjs.com/package/@piprail/sdk
+[3.1.2]: https://www.npmjs.com/package/@piprail/sdk
+[3.1.1]: https://www.npmjs.com/package/@piprail/sdk
 [3.1.0]: https://www.npmjs.com/package/@piprail/sdk
 [3.0.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.3.0]: https://www.npmjs.com/package/@piprail/sdk

package/dist/index.cjs

@@ -2498,7 +2498,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./xrpl-G2FKFXRI.cjs")));
+      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./xrpl-YUGDNI2R.cjs")));
     } catch (cause) {
       throw new (0, _chunk6XTNI2OQcjs.MissingDriverError)(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
@@ -3800,7 +3800,16 @@ var PipRailClient = (_class2 = class {
     return this.opts.chain;
   }
   /**
-   * What this wallet actually HOLDS, per asset — the balance sheet, not the leash.
+   * What this wallet can actually SPEND, per asset — the balance sheet, not the leash.
+   *
+   * 🔴 For a NATIVE asset this is not always what the chain says the account holds. Solana
+   * (rent exemption), XRPL (base + owner reserve), Stellar (base reserve per subentry) and
+   * Algorand (minimum balance) all require an account to retain a minimum it can never send,
+   * and since 3.1.0 the drivers report that reserve DEDUCTED, because affordability measured
+   * against the raw balance calls a payment affordable right up until the chain refuses it.
+   * Live example: a Stellar account holding 1.5398 XLM with three subentries reports 0.0398,
+   * the 1.5 XLM difference being the reserve. That is the number to spend against; it is not
+   * missing money. `estimateCost()` judges gas against the TRUE balance separately.
    *
    * `budget()` answers "how much of my allowance is left", a different question and the only
    * one an agent could previously ask. An agent that OWNS a wallet has to answer "what do I
@@ -6238,6 +6247,14 @@ async function settleViaFacilitator(input) {
     );
   }
   if (verify.status !== 200) {
+    if (verify.status === 400 || verify.status === 422) {
+      const vr4 = _nullishCoalesce(verify.json, () => ( {}));
+      return {
+        ok: false,
+        error: mapReason(vr4.invalidReason),
+        detail: `Facilitator rejected the payment payload (HTTP ${verify.status})${vr4.invalidReason ? `: ${vr4.invalidReason}` : ""}${vr4.invalidMessage ? ` \u2014 ${vr4.invalidMessage}` : ""}.`
+      };
+    }
     throw new (0, _chunk6XTNI2OQcjs.SettlementError)(
       `exact settle (facilitator ${base2}): /verify returned HTTP ${verify.status} (transport/auth error).`
     );
@@ -8303,7 +8320,7 @@ function paymentTools(client) {
     },
     {
       name: "piprail_wallet",
-      description: "What YOU hold, and where you get paid \u2014 your balance sheet, which is a different question from piprail_budget (that is how much of your allowance is left). Returns your own address per chain plus the amount of each asset you actually hold. Use it before deciding to sell, swap or ask to be topped up, and give the address to anyone who needs to send you funds. A null amount means the read was UNAVAILABLE, not zero: do NOT treat it as being broke. Read-only; moves nothing and needs no approval.",
+      description: "What YOU can SPEND, and where you get paid \u2014 your balance sheet, which is a different question from piprail_budget (that is how much of your allowance is left). Returns your own address per chain plus the spendable amount of each asset. Use it before deciding to sell, swap or ask to be topped up, and give the address to anyone who needs to send you funds. On some chains a native amount is LOWER than the figure a block explorer shows, because the chain makes an account retain a minimum it can never send (Solana, XRPL, Stellar, Algorand). That gap is locked, not lost, and this number is the one you can actually pay with. A null amount means the read was UNAVAILABLE, not zero: do NOT treat it as being broke. Read-only; moves nothing and needs no approval.",
       annotations: {
         title: "Your wallet",
         readOnlyHint: true,

package/dist/index.d.cts

@@ -5974,7 +5974,9 @@ interface PayingClient {
     canAgentSell?(): boolean;
     /** The chain this client is configured for — the default an offer is priced on. */
     chain?(): ChainSelector;
-    /** What this wallet HOLDS, per asset — the balance sheet, distinct from the budget leash. */
+    /** What this wallet can SPEND, per asset — the balance sheet, distinct from the budget
+     *  leash. On a chain with a retained minimum (Solana rent, XRPL/Stellar/Algorand
+     *  reserves) a native balance reports the reserve DEDUCTED. See {@link WalletBalance}. */
     balanceOf?(assets?: readonly string[]): Promise<WalletAssetBalance[]>;
 }
 /**
@@ -6214,7 +6216,16 @@ declare class PipRailClient {
      *  defaults to it, so an agent prices on the chain it actually holds funds on. */
     chain(): ChainSelector;
     /**
-     * What this wallet actually HOLDS, per asset — the balance sheet, not the leash.
+     * What this wallet can actually SPEND, per asset — the balance sheet, not the leash.
+     *
+     * 🔴 For a NATIVE asset this is not always what the chain says the account holds. Solana
+     * (rent exemption), XRPL (base + owner reserve), Stellar (base reserve per subentry) and
+     * Algorand (minimum balance) all require an account to retain a minimum it can never send,
+     * and since 3.1.0 the drivers report that reserve DEDUCTED, because affordability measured
+     * against the raw balance calls a payment affordable right up until the chain refuses it.
+     * Live example: a Stellar account holding 1.5398 XLM with three subentries reports 0.0398,
+     * the 1.5 XLM difference being the reserve. That is the number to spend against; it is not
+     * missing money. `estimateCost()` judges gas against the TRUE balance separately.
      *
      * `budget()` answers "how much of my allowance is left", a different question and the only
      * one an agent could previously ask. An agent that OWNS a wallet has to answer "what do I

package/dist/index.d.ts

@@ -5974,7 +5974,9 @@ interface PayingClient {
     canAgentSell?(): boolean;
     /** The chain this client is configured for — the default an offer is priced on. */
     chain?(): ChainSelector;
-    /** What this wallet HOLDS, per asset — the balance sheet, distinct from the budget leash. */
+    /** What this wallet can SPEND, per asset — the balance sheet, distinct from the budget
+     *  leash. On a chain with a retained minimum (Solana rent, XRPL/Stellar/Algorand
+     *  reserves) a native balance reports the reserve DEDUCTED. See {@link WalletBalance}. */
     balanceOf?(assets?: readonly string[]): Promise<WalletAssetBalance[]>;
 }
 /**
@@ -6214,7 +6216,16 @@ declare class PipRailClient {
      *  defaults to it, so an agent prices on the chain it actually holds funds on. */
     chain(): ChainSelector;
     /**
-     * What this wallet actually HOLDS, per asset — the balance sheet, not the leash.
+     * What this wallet can actually SPEND, per asset — the balance sheet, not the leash.
+     *
+     * 🔴 For a NATIVE asset this is not always what the chain says the account holds. Solana
+     * (rent exemption), XRPL (base + owner reserve), Stellar (base reserve per subentry) and
+     * Algorand (minimum balance) all require an account to retain a minimum it can never send,
+     * and since 3.1.0 the drivers report that reserve DEDUCTED, because affordability measured
+     * against the raw balance calls a payment affordable right up until the chain refuses it.
+     * Live example: a Stellar account holding 1.5398 XLM with three subentries reports 0.0398,
+     * the 1.5 XLM difference being the reserve. That is the number to spend against; it is not
+     * missing money. `estimateCost()` judges gas against the TRUE balance separately.
      *
      * `budget()` answers "how much of my allowance is left", a different question and the only
      * one an agent could previously ask. An agent that OWNS a wallet has to answer "what do I

package/dist/index.js

@@ -2498,7 +2498,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await import("./xrpl-5K444RGX.js");
+      mod = await import("./xrpl-WIDRV2XY.js");
     } catch (cause) {
       throw new MissingDriverError(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
@@ -3800,7 +3800,16 @@ var PipRailClient = class {
     return this.opts.chain;
   }
   /**
-   * What this wallet actually HOLDS, per asset — the balance sheet, not the leash.
+   * What this wallet can actually SPEND, per asset — the balance sheet, not the leash.
+   *
+   * 🔴 For a NATIVE asset this is not always what the chain says the account holds. Solana
+   * (rent exemption), XRPL (base + owner reserve), Stellar (base reserve per subentry) and
+   * Algorand (minimum balance) all require an account to retain a minimum it can never send,
+   * and since 3.1.0 the drivers report that reserve DEDUCTED, because affordability measured
+   * against the raw balance calls a payment affordable right up until the chain refuses it.
+   * Live example: a Stellar account holding 1.5398 XLM with three subentries reports 0.0398,
+   * the 1.5 XLM difference being the reserve. That is the number to spend against; it is not
+   * missing money. `estimateCost()` judges gas against the TRUE balance separately.
    *
    * `budget()` answers "how much of my allowance is left", a different question and the only
    * one an agent could previously ask. An agent that OWNS a wallet has to answer "what do I
@@ -6238,6 +6247,14 @@ async function settleViaFacilitator(input) {
     );
   }
   if (verify.status !== 200) {
+    if (verify.status === 400 || verify.status === 422) {
+      const vr4 = verify.json ?? {};
+      return {
+        ok: false,
+        error: mapReason(vr4.invalidReason),
+        detail: `Facilitator rejected the payment payload (HTTP ${verify.status})${vr4.invalidReason ? `: ${vr4.invalidReason}` : ""}${vr4.invalidMessage ? ` \u2014 ${vr4.invalidMessage}` : ""}.`
+      };
+    }
     throw new SettlementError(
       `exact settle (facilitator ${base2}): /verify returned HTTP ${verify.status} (transport/auth error).`
     );
@@ -8303,7 +8320,7 @@ function paymentTools(client) {
     },
     {
       name: "piprail_wallet",
-      description: "What YOU hold, and where you get paid \u2014 your balance sheet, which is a different question from piprail_budget (that is how much of your allowance is left). Returns your own address per chain plus the amount of each asset you actually hold. Use it before deciding to sell, swap or ask to be topped up, and give the address to anyone who needs to send you funds. A null amount means the read was UNAVAILABLE, not zero: do NOT treat it as being broke. Read-only; moves nothing and needs no approval.",
+      description: "What YOU can SPEND, and where you get paid \u2014 your balance sheet, which is a different question from piprail_budget (that is how much of your allowance is left). Returns your own address per chain plus the spendable amount of each asset. Use it before deciding to sell, swap or ask to be topped up, and give the address to anyone who needs to send you funds. On some chains a native amount is LOWER than the figure a block explorer shows, because the chain makes an account retain a minimum it can never send (Solana, XRPL, Stellar, Algorand). That gap is locked, not lost, and this number is the one you can actually pay with. A null amount means the read was UNAVAILABLE, not zero: do NOT treat it as being broke. Read-only; moves nothing and needs no approval.",
       annotations: {
         title: "Your wallet",
         readOnlyHint: true,

package/dist/{xrpl-5K444RGX.js → xrpl-WIDRV2XY.js}

@@ -745,7 +745,13 @@ function makeXrplNetwork(preset, rpcUrl) {
     },
     async currentLedgerIndex() {
       const r = await rpc("ledger_current", {});
-      return r.ledger_current_index;
+      const index = r.ledger_current_index ?? r.ledger_index;
+      if (typeof index !== "number") {
+        throw new Error(
+          `XRPL: ledger_current returned neither ledger_current_index nor ledger_index (got ${JSON.stringify(Object.keys(r ?? {}))}). Nothing was signed or submitted.`
+        );
+      }
+      return index;
     },
     async submit(txBlob) {
       return rpc("submit", { tx_blob: txBlob });

package/dist/{xrpl-G2FKFXRI.cjs → xrpl-YUGDNI2R.cjs}

@@ -745,7 +745,13 @@ function makeXrplNetwork(preset, rpcUrl) {
     },
     async currentLedgerIndex() {
       const r = await rpc("ledger_current", {});
-      return r.ledger_current_index;
+      const index = _nullishCoalesce(r.ledger_current_index, () => ( r.ledger_index));
+      if (typeof index !== "number") {
+        throw new Error(
+          `XRPL: ledger_current returned neither ledger_current_index nor ledger_index (got ${JSON.stringify(Object.keys(_nullishCoalesce(r, () => ( {}))))}). Nothing was signed or submitted.`
+        );
+      }
+      return index;
     },
     async submit(txBlob) {
       return rpc("submit", { tx_blob: txBlob });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "Accept x402 crypto payments across 30 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",