@piprail/sdk 1.13.1 → 1.15.0

package/CHAINS.md

@@ -13,7 +13,7 @@ read those sections before you ship them.
 
 | Chain(s) | Pay in native coin? | Built-in stablecoins | Receiver needs setup? | Wallet input |
 |---|:--:|---|---|---|
-| **EVM** (Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, Mantle, Sonic, Linea, Scroll, Celo, zkSync, Unichain, World Chain, Sei, Injective, HyperEVM, Monad, Kaia, + any EVM chain) | ✅ ETH/BNB/POL/… | USDC (all **except Kaia**) · USDT (all **except Base, World Chain, Sei, HyperEVM, Monad**) | No | `{ privateKey }` |
+| **EVM** (Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, Mantle, Sonic, Linea, Scroll, Celo, zkSync, Unichain, World Chain, Sei, Injective, HyperEVM, Monad, Kaia, + any EVM chain) | ✅ ETH/BNB/POL/… | USDC (all **except Kaia**) · USDT (all **except Base, World Chain, Sei, HyperEVM, Monad**) · **EURC** (Ethereum, Base, Avalanche) | No | `{ privateKey }` |
 | **Solana** | ✅ SOL | USDC · USDT | No (payer creates the recipient's token account) | `{ secretKey }` |
 | **Sui** | ✅ SUI | USDC (no USDT) | No | `{ privateKey }` (`suiprivkey1…`) |
 | **Aptos** | ✅ APT | USDC · USDT | No (primary FA store auto-creates) | `{ privateKey }` (`ed25519-priv-0x…`) |
@@ -44,8 +44,9 @@ read those sections before you ship them.
 ## Chains with no caveats
 
 ### EVM — Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, …
-- **Pay in:** native coin (`'native'`), `'USDC'`, `'USDT'`, or a custom `{ address, decimals }`.
+- **Pay in:** native coin (`'native'`), `'USDC'`, `'USDT'`, `'EURC'` (where issued), or a custom `{ address, decimals }`.
 - **USDT gap:** built in on every preset **except Base, World Chain, Sei, HyperEVM, and Monad** (USDC only there). **Kaia** is the inverse — **USD₮ only** (no Circle-native USDC on Kaia).
+- **EURC:** Circle's euro stablecoin is built in on **Ethereum, Base, and Avalanche** (EIP-3009, 6-dp, addresses verified on-chain). Its EIP-712 domain name differs per deployment (`"Euro Coin"` on Ethereum/Avalanche, `"EURC"` on Base) — the SDK reads it on-chain, so `exact` payments are correct everywhere. Like USDC, it's `exact`-payable.
 - **Decimals:** on **BNB Chain**, Binance-Peg USDC/USDT are **18 decimals**, not 6 (the SDK handles it; don't hardcode 6).
 - **Stablecoin provenance — issuer-native vs bridged (every shipped address verified on-chain 2026-06-08, incl. bridge markers).** Every address is the correct, canonical, 1:1-redeemable dollar token on its chain; what varies is *who issues it*. You request it as `'USDC'` / `'USDT'` either way — provenance matters only if you specifically require issuer-native settlement.
   - **USDC** is **Circle-native** on every preset **except** **BNB** (Binance-Peg, 18-dp), **Mantle** (OP canonical-bridge), and **Scroll** (Bridged-USDC-Standard) — the last two are backed 1:1 by Circle USDC on Ethereum but are **not** Circle-issued on that chain (absent from Circle's native-USDC list).

package/CHANGELOG.md

@@ -4,6 +4,73 @@ 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/).
 
+## [1.15.0] — 2026-06-10 — the trusted agent wallet (budget-bound, time-boxed, asks-first)
+
+A minor, fully additive layer — defaults byte-identical, no new error code, protocol
+layer stays viem-free.
+
+### Added — a TIME dimension on `PaymentPolicy` (Mode A)
+- Four opt-in fields make the spend leash a *clock* too: `ttlSeconds` / `expiresAt` (a
+  session deadline — past it EVERY pay is refused with `reasonCode:'SESSION_EXPIRED'`,
+  TERMINAL) and `windowTotal` + `windowSeconds` (an optional rolling rate-limit, per
+  `(network, asset)`). All default off → behaviour unchanged. A half-armed window
+  (`windowTotal` without `windowSeconds`) or an unsafe `ttlSeconds` throws at construction.
+- `client.budget(): SessionBudget` and `PaymentPlan.session` surface the remaining money +
+  time leash so a headless agent can SEE it before paying. `client.remaining(): SpendRemaining[]`
+  gives the per-asset cap, ledger-scoped. All read-only, never throw, process-scoped (reset on restart).
+- `PolicyDecision` gains a typed `code` (`PolicyDenyCode`); `PayBlocker` gains `OUTSIDE_WINDOW`.
+
+### Added — agent ergonomics (the model-facing contract)
+- `PaymentDeclinedError.reasonCode` (`'POLICY' | 'BUDGET' | 'OUTSIDE_WINDOW' | 'SESSION_EXPIRED'
+  | 'APPROVAL'`) — a typed discriminator so an agent branches on the cause (and spots a TERMINAL
+  decline) without parsing prose. No new `.code`.
+- The `piprail_pay_request` tool now funnels EVERY `PipRailError` into a structured
+  `{ ok:false, code, reason, explain, ref?, reasonCode?, declined? }` — never an uncaught crash, so a
+  broadcast-but-unconfirmed timeout reaches the agent with its `.ref` and the never-re-pay rule.
+- New pure exports: `summarizePlan` / `explainDecline` / `formatSpendReport` (NL renderers, wired into
+  the tool outputs), `classifyChallenge` + `ChallengeTriage` (scheme/chain triage), and
+  `PIPRAIL_AGENT_GUIDE` / `agentGuide` (the cross-tool contract).
+- `paymentTools()` now returns **7** tools — the original 5, plus read-only `piprail_budget` and
+  `piprail_guide` appended last (the first five are byte-identical in name + order).
+
+## [1.14.0] — 2026-06-10
+
+### Added — pay the standard `exact` rail (opt-in, EVM + EIP-3009)
+- **`PipRailClient` can now PAY standard x402 `exact` rails**, not just PipRail's native
+  `onchain-proof` — so an agent can transact with ANY standard v2 x402 server (the dominant
+  `exact`-on-Base-via-CDP web), while PipRail's own gates stay backendless. **Opt-in** via a new
+  `schemes` option (default `['onchain-proof']` — the zero-config path is byte-identical):
+  `new PipRailClient({ chain: 'base', wallet, schemes: ['onchain-proof', 'exact'] })`, with a per-call
+  override `fetch(url, { schemes: ['exact'] })`. EVM + EIP-3009 only (USDC/EURC); silently ignored on
+  non-EVM chains, for USDT/native, or for a token the SDK can't price (those keep `onchain-proof`).
+- The buyer signs an EIP-3009 authorization with **its own** wallet and the server / merchant-chosen
+  facilitator broadcasts it — the buyer pays ~0 gas and PipRail hosts/settles nothing. `quote()`,
+  `planPayment()`, `estimateCost()`, `canAfford()`, `autoRoute`, and `planAcross()` are now truthful
+  across both schemes (an exact rail is priced gasless: `cost.fee === '0'`, never an `INSUFFICIENT_GAS`
+  blocker). The EIP-712 domain is **re-derived on-chain** (`name()`/`version()`), never trusted from
+  the server's `extra`. The same `policy` + `onBeforePay` gate it BEFORE any signature.
+  **Verify against your target facilitator before production.**
+- **EURC is now a built-in EVM preset token** on Ethereum, Base, and Avalanche (on-chain-verified;
+  EIP-3009, 6 decimals) — so the `exact` buyer recognises it and the "USDC/EURC" coverage is real, not
+  aspirational. (Its EIP-712 domain name differs per deployment — `"Euro Coin"` on Ethereum/Avalanche,
+  `"EURC"` on Base — which the buyer re-derives on-chain; the symbol is display-only.)
+- `X402ExactAcceptEntry.extra.name`/`version` are now OPTIONAL (the exact-EVM scheme only requires
+  `assetTransferMethod`) — matching the spec; the buyer ignores them (it re-derives on-chain), the gate
+  still populates them from its own on-chain read. The `payment-settled` event now also carries the
+  conformant `settle?: SettleOutcome` (a third-party facilitator's lean SettleResponse, when there's no
+  rich receipt).
+- New exports: `buildExactSignatureHeader`, `parseSettleResponse` (+ the `SettleOutcome` type), the
+  `PaymentScheme` type, and the `UnsupportedSchemeError` (`code: 'UNSUPPORTED_SCHEME'`). New driver SPI
+  method `payExact?` (optional, EVM-only). `@piprail/mcp` adds the `PIPRAIL_SCHEMES` env (unset ⇒ the
+  SDK default, so the MCP's zero-config posture is unchanged).
+
+### Changed (additive — minor, but type-affecting)
+- `PayOption.accept` and the `payment-required` event's `accept` are now `X402AnyAccept` (was
+  `X402AcceptEntry`). A consumer that reads `accept.extra.nonce`/`minConfirmations` without a `scheme`
+  guard should narrow on `accept.scheme === 'onchain-proof'` first.
+- The buyer emits **v2 only** for `exact` (`PAYMENT-SIGNATURE` + the `accepted`-envelope). v1-only
+  servers (which never parse as a v2 challenge here) are out of scope for this milestone.
+
 ## [1.13.1] — 2026-06-10
 
 ### Fixed
@@ -624,6 +691,8 @@ straight into your wallet. The API is small and self-contained.
   to your wallet; PipRail never holds funds.
 - `viem ^2.21` is a peer dependency. Node 20+ or a modern browser.
 
+[1.15.0]: https://www.npmjs.com/package/@piprail/sdk
+[1.14.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.13.1]: https://www.npmjs.com/package/@piprail/sdk
 [1.13.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.12.0]: https://www.npmjs.com/package/@piprail/sdk

package/ERRORS.md

@@ -56,7 +56,8 @@ Base class [`PipRailError`](src/errors.ts) (abstract; `.name` = the subclass nam
 | `MAX_RETRIES_EXCEEDED` | `MaxRetriesExceededError` | server kept returning 402 after broadcast — **message embeds the last server `error — detail`, and carries `.ref`** | client |
 | `PAYMENT_DECLINED` | `PaymentDeclinedError` | the client refused to pay BEFORE any send — over the spend `policy` (amount/total/chain/token/host), or an `onBeforePay` hook returned false / threw | client |
 | `INVALID_ENVELOPE` | `InvalidEnvelopeError` | a 402 had no parseable x402 challenge | client |
-| `NO_COMPATIBLE_ACCEPT` | `NoCompatibleAcceptError` | the challenge offered no `accepts[]` entry for the client's network | client |
+| `NO_COMPATIBLE_ACCEPT` | `NoCompatibleAcceptError` | the challenge offered no `accepts[]` entry the client can pay on its network + enabled `schemes` (message names the enabled schemes) | client |
+| `UNSUPPORTED_SCHEME` | `UnsupportedSchemeError` | asked to pay a scheme the bound family/asset/signer can't settle, with no fallback: `exact` on a non-EVM family, a non-EIP-3009 token (USDT/native/plain ERC-20), or a contract / EIP-1271 / EIP-7702 signer | client / EVM `exact` (`payExact`) |
 | `NON_REPLAYABLE_BODY` | `NonReplayableBodyError` | `init.body` isn't replayable (e.g. a one-shot stream) | client |
 | `MISSING_DRIVER` | `MissingDriverError` | a family's **optional peer deps aren't installed** (the lazy `import()` failed) — message names the exact `npm install` and sets `{ cause }` | registry loaders |
 | `UNSUPPORTED_NETWORK` | `UnsupportedNetworkError` | no driver for the family, or the driver's `resolve()` returned `null` (unrecognised `chain`) | registry |
@@ -113,9 +114,23 @@ the code. A consumer building a custom client may branch on it.
   `error — detail` (e.g. `… Last server rejection: amount_too_low — Paid 40000, required
   500000.`), and a `payment-failed` event carrying the same reason.
 - **Client refused to pay →** `PaymentDeclinedError` thrown *before* any on-chain send — the
-  quote exceeded the client's `policy`, or an `onBeforePay` hook returned false. Nothing moved.
+  quote exceeded the client's `policy` (amount/total/chain/token/host, or the session's **time
+  envelope**), or an `onBeforePay` hook returned false. Nothing moved. It carries an optional typed
+  `reasonCode` (`'POLICY' | 'BUDGET' | 'OUTSIDE_WINDOW' | 'SESSION_EXPIRED' | 'APPROVAL'`) so an agent
+  branches on the cause — and recognises a **TERMINAL** `SESSION_EXPIRED` / `APPROVAL` it must not
+  retry — without parsing the message. The session TTL (`SESSION_EXPIRED`) and rolling window
+  (`OUTSIDE_WINDOW`) reuse this EXISTING `PaymentDeclinedError` (`.code` stays `'PAYMENT_DECLINED'`):
+  **no new error class, no new `VerifyErrorCode`** — only the closed `PayBlocker` union gains `OUTSIDE_WINDOW`.
 - **Config / flow / wallet problem →** a thrown `PipRailError` with a stable `.code`.
 
+> **The agent toolkit funnels all of this.** The `piprail_pay_request` tool catches **every**
+> `PipRailError` and returns a structured `{ ok:false, code, reason, explain, ref?, reasonCode?,
+> declined? }` instead of letting it crash the agent loop — so a broadcast-but-unconfirmed
+> `PAYMENT_TIMEOUT`/`MAX_RETRIES_EXCEEDED`/`CONFIRMATION_TIMEOUT` reaches the model with its `.ref` and
+> the never-re-pay rule (via `explainDecline`). Only a genuine non-`PipRailError` bug rethrows.
+> The pure renderers (`render.ts`) and `classifyChallenge` (`classify.ts`) are viem-free protocol-layer
+> modules; `render.ts`'s VALUE import of `errors.ts` is allowed (errors.ts is chain-agnostic).
+
 Observability hooks never change control flow: the gate wraps `onPaid`, and the client routes
 every event through a private `safeEmit()` that swallows handler throws — a logging bug can't
 abort a payment.

package/README.md

@@ -59,6 +59,22 @@ exact: { settle: { facilitator: 'https://x402.org/facilitator' } }
 
 EVM + EIP-3009 tokens only (USDC, EURC — not USDT, not native; those stay `onchain-proof`). Omit `exact` and the gate is byte-identical to today. Proven end-to-end: a real `@x402/fetch` reference client settles against a PipRail gate on Base mainnet.
 
+### Pay *any* x402 server — the `exact` rail, buyer side
+
+The mirror image: let your **`PipRailClient` pay** standard x402 servers (the dominant `exact`-on-Base-via-CDP web), not just PipRail's own gates. Opt in with `schemes` — default `['onchain-proof']`, so the zero-config client is byte-identical:
+
+```ts
+const client = new PipRailClient({
+  chain: 'base',
+  wallet: { privateKey: process.env.AGENT_KEY },
+  schemes: ['onchain-proof', 'exact'],     // also pay standard exact rails
+})
+await client.fetch('https://api.somevendor.com/paid')   // pays whichever rail it offers
+// or per call: client.fetch(url, { schemes: ['exact'] })
+```
+
+On an `exact` rail the client signs an EIP-3009 authorization with **its own** wallet and the server / merchant-chosen facilitator broadcasts it — so the **buyer pays ~0 gas** and PipRail hosts/settles nothing. The EIP-712 token domain is **re-derived on-chain** (never trusted from the challenge), the same `policy` + `onBeforePay` gate it **before any signature**, and `quote()`/`planPayment()`/`estimateCost()` are truthful across both schemes (an exact rail prices gasless). EVM + EIP-3009 only (USDC/EURC); silently ignored on non-EVM chains, for USDT/native, or for a token the SDK can't price — those stay `onchain-proof`. **Verify against your target facilitator before production.**
+
 ## Built for agents — spend safely
 
 A funded key loose on the internet needs guardrails. Opt in to a `policy` and the client refuses anything outside it **before any on-chain send** — plus learn a price without paying it, approve each payment, and read back exactly what you spent. All opt-in, all local, no backend; omit it and the client behaves exactly as before.
@@ -132,17 +148,53 @@ For **every rail the 402 offers on your chain**, the plan reads **token balance
 
 ```ts
 import { paymentTools } from '@piprail/sdk'
-const tools = paymentTools(client) // → [piprail_discover, piprail_quote_payment, piprail_plan_payment, piprail_pay_request, piprail_register]
+const tools = paymentTools(client)
+// → [piprail_discover, piprail_quote_payment, piprail_plan_payment,
+//    piprail_pay_request, piprail_register, piprail_budget, piprail_guide]
 ```
 
 Each descriptor also carries advisory **`annotations`** (MCP-style `ToolAnnotations` — `title`,
-`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`): the three reads are flagged
+`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`): the reads are flagged
 **read-only**, `piprail_pay_request` is flagged **value-moving** (the one tool that spends), and
 `piprail_register` is non-destructive — so an MCP client can render the right consent. They're hints,
 not the boundary; the spend policy is. `@piprail/mcp` advertises them on the wire.
 
 See [`examples/agent-tools.mjs`](../examples/agent-tools.mjs) for MCP / AI-SDK wiring.
 
+### A budget that's also a clock — the time envelope (Mode A)
+
+The spend policy already caps *amount* and *total*; it can also bound *time*, so a headless agent
+runs free **inside** a budget **and** time envelope and the policy *is* the consent — no per-pay ask.
+All opt-in; omit them and behaviour is byte-identical.
+
+```ts
+const client = new PipRailClient({
+  chain: 'base', wallet,
+  policy: {
+    maxAmount: '0.10', maxTotal: '5.00', tokens: ['USDC'],
+    ttlSeconds: 3600,             // the whole session expires in 1h — then EVERY pay is refused
+    windowTotal: '1.00', windowSeconds: 600,  // …and ≤ $1 of USDC in any rolling 10-minute window
+  },
+})
+
+client.budget()    // → { session: { expiresAt, secondsRemaining }, byAsset: [...] } — read the leash before paying
+client.remaining() // → per-(network,asset) remaining cap (ledger-scoped)
+```
+
+A pay past the deadline throws `PaymentDeclinedError` with **`reasonCode: 'SESSION_EXPIRED'`** (TERMINAL
+— don't retry); a window breach is `'OUTSIDE_WINDOW'`. The window needs **both** `windowTotal` and
+`windowSeconds` (one alone throws at construction — a leash can't be half-armed). State is in-memory and
+**resets on restart** (the session *is* the process); durable limits are the caller's pluggable concern.
+
+### Legible to the model — the decline contract + the guide
+
+`piprail_pay_request` funnels **every** failure into a structured `{ ok:false, code, reason, explain,
+ref?, reasonCode?, declined? }` — never an uncaught crash — so a broadcast-but-unconfirmed timeout
+reaches the agent with its `.ref` and the **never-re-pay** rule, not a double-spend. Pure helpers make
+the rest legible: `summarizePlan` / `explainDecline` / `formatSpendReport` (one-line English),
+`classifyChallenge` (wrong-chain vs unpayable-scheme), and `PIPRAIL_AGENT_GUIDE` (the whole contract,
+distilled for an LLM). `piprail_budget` lets the agent self-check its leash; `piprail_guide` returns the contract.
+
 ## Be discoverable — find and be found ($0, no backend)
 
 A 402 endpoint is payable, but nobody can *find* it. PipRail closes that gap by building on the
@@ -253,7 +305,8 @@ For an LLM/MCP these are two more tools — **`piprail_discover`** (find) and **
 
 > **Two honest caveats.** The open indexes assume the mainstream `exact` scheme, so to be *usefully*
 > listed also offer a standard `exact` USDC rail on Base/Solana (`discover()` results are
-> cross-scheme; `fetch()` pays only PipRail `onchain-proof` rails directly). And **x402scan indexes
+> cross-scheme; `fetch()` pays PipRail `onchain-proof` rails by default, and standard `exact` rails too
+> once you opt in with `schemes: ['onchain-proof', 'exact']` — EVM/EIP-3009). And **x402scan indexes
 > Base/Solana only** — 402 Index has no such limit, so it's the default register target. There is no
 > single ratified discovery standard yet; OpenAPI-first is an emerging multi-vendor convention.
 
@@ -758,7 +811,7 @@ Methods: `fetch` · `get` · `post` (return the gated `Response` after settlemen
 
 **Bring your own chain family:** the SDK is built on a tiny `PaymentDriver` contract — `resolve(chain)` returns a bound network with `resolveToken` / `describeAsset` / `assertValidPayTo` / `bindWallet` / `send` / `confirm` / `estimateCost` / `balanceOf` / `recipientReady` / `verify`. Register your own with `registerDriver(...)`; the protocol layer never changes (see [Architecture](#architecture-under-the-hood)).
 
-**Universal x402 (experimental):** building blocks to pay servers on the mainstream x402 `exact` scheme (EIP-3009 + facilitator) — `parseExactRequirements`, `buildExactAuthorization`, `encodeXPaymentHeader`. EVM-only; validate against your target facilitator before production.
+**Universal x402 (`exact` scheme):** the supported way to pay any standard x402 server is `new PipRailClient({ …, schemes: ['onchain-proof', 'exact'] })` (see [Pay *any* x402 server](#pay-any-x402-server--the-exact-rail-buyer-side)) — the client signs the EIP-3009 authorization on-chain-derived-domain and the server/facilitator settles. The low-level codecs `parseExactRequirements` / `buildExactAuthorization` (`@deprecated` — trusts the server-supplied domain, local-key only) / `encodeXPaymentHeader` remain for hand-rolled or v1 clients. EVM + EIP-3009 only; validate against your target facilitator before production.
 
 ## Requirements
 

package/STANDARDS.md

@@ -109,6 +109,10 @@ npm test                 # full Vitest suite
 npm run build            # tsup build succeeds
 # lazy-chunk invariant — the EVM bundle pulls in no non-EVM chain lib:
 grep -E "from ?['\"]@(solana|ton|stellar)" dist/index.js   # → expect NO matches
+# viem-free protocol layer — the chain-agnostic core never imports a chain SDK
+# (includes the pure agent-ergonomics modules render/classify/agentGuide; render.ts's
+#  VALUE import of errors.ts is allowed — errors.ts is chain-agnostic, the grep targets viem):
+grep -lE "from ['\"]viem" src/client.ts src/x402.ts src/policy.ts src/ledger.ts src/server.ts src/agent.ts src/render.ts src/classify.ts src/agentGuide.ts  # → expect NO matches
 ```
 
 `prepublishOnly` runs build + test + both typechecks. Never ship with any of these red.

package/dist/{algorand-MXUSKX46.cjs → algorand-EJ3S2V7E.cjs}

@@ -7,7 +7,7 @@
 
 
 
-var _chunkMDLZJGLYcjs = require('./chunk-MDLZJGLY.cjs');
+var _chunkPA6YD3HLcjs = require('./chunk-PA6YD3HL.cjs');
 
 // src/drivers/algorand/index.ts
 var _algosdk = require('algosdk'); var _algosdk2 = _interopRequireDefault(_algosdk);
@@ -55,13 +55,13 @@ async function payAlgorand(params) {
   } catch (err) {
     const mapped = mapAlgorandError(err, accept.payTo);
     if (mapped) throw mapped;
-    throw _nullishCoalesce(_chunkMDLZJGLYcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+    throw _nullishCoalesce(_chunkPA6YD3HLcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
   }
 }
 function mapAlgorandError(err, payTo) {
   const m = err instanceof Error ? err.message : String(err);
   if (/must optin/i.test(m) || /missing from/i.test(m) && m.includes(payTo)) {
-    return new (0, _chunkMDLZJGLYcjs.RecipientNotReadyError)(
+    return new (0, _chunkPA6YD3HLcjs.RecipientNotReadyError)(
       `Algorand recipient ${payTo} hasn't opted into this asset \u2014 it must opt in (a 0-amount asset transfer to itself) before it can receive. (Algorand: ${firstLine(m)})`,
       { cause: err }
     );
@@ -69,7 +69,7 @@ function mapAlgorandError(err, payTo) {
   if (/overspend|below min|min(imum)? balance|tried to spend|balance \d+ below|asset \d+ missing from|insufficient|underflow/i.test(
     m
   )) {
-    return new (0, _chunkMDLZJGLYcjs.InsufficientFundsError)(
+    return new (0, _chunkPA6YD3HLcjs.InsufficientFundsError)(
       `Algorand payment failed: the sender can't cover it \u2014 token balance, ALGO for fees, the 0.1-ALGO minimum balance, or a missing asset opt-in on the sender. (Algorand: ${firstLine(m)})`,
       { cause: err }
     );
@@ -157,22 +157,22 @@ function rpcFailed(nonce) {
 
 function assertAlgorandWallet(wallet, network) {
   if (typeof wallet !== "object" || wallet === null) {
-    throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Algorand; wallet must be { mnemonic } (25 words) or { account }.`
     );
   }
   if ("privateKey" in wallet || "walletClient" in wallet) {
-    throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Algorand; an EVM/Aptos wallet can't be used \u2014 pass { mnemonic } (25 words) or { account }.`
     );
   }
   if ("secretKey" in wallet || "signer" in wallet || "secret" in wallet || "keypair" in wallet || "keyPair" in wallet || "seed" in wallet || "accountId" in wallet) {
-    throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Algorand; that looks like another family's wallet \u2014 pass { mnemonic } (25 words) or { account }.`
     );
   }
   if (!("mnemonic" in wallet) && !("account" in wallet)) {
-    throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Algorand; wallet must be { mnemonic } (25 words) or { account }.`
     );
   }
@@ -187,13 +187,13 @@ function resolveAlgorandWallet(config) {
       const { addr, sk } = _algosdk2.default.mnemonicToSecretKey(config.mnemonic);
       return { addr: addr.toString(), sk };
     } catch (cause) {
-      throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+      throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
         "Algorand wallet { mnemonic } is not a valid 25-word Algorand mnemonic.",
         { cause }
       );
     }
   }
-  throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)("Algorand wallet needs { mnemonic } (25 words) or { account }.");
+  throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)("Algorand wallet needs { mnemonic } (25 words) or { account }.");
 }
 
 // src/drivers/algorand/index.ts
@@ -248,16 +248,16 @@ function makeAlgorandNetwork(preset, algodUrl) {
         const info = preset.tokens[token.toUpperCase()];
         if (!info) {
           const known = Object.keys(preset.tokens).join(", ") || "(none built in)";
-          throw new (0, _chunkMDLZJGLYcjs.UnknownTokenError)(
+          throw new (0, _chunkPA6YD3HLcjs.UnknownTokenError)(
             `token "${token}" isn't built in for Algorand (known: ${known}). Pass { assetId, decimals } for a custom ASA, or use 'native'.`
           );
         }
         return { asset: algorandAssetId(info.assetId), decimals: info.decimals, symbol: info.symbol };
       }
-      _chunkMDLZJGLYcjs.rejectForeignToken.call(void 0, token, "algorand", network);
+      _chunkPA6YD3HLcjs.rejectForeignToken.call(void 0, token, "algorand", network);
       const t = token;
       if (typeof t.assetId !== "number" || typeof t.decimals !== "number") {
-        throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
           `chain ${network} is Algorand; a custom token must be { assetId, decimals }.`
         );
       }
@@ -278,12 +278,12 @@ function makeAlgorandNetwork(preset, algodUrl) {
     },
     assertValidPayTo(payTo) {
       if (payTo.startsWith("0x")) {
-        throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
           `chain ${network} is Algorand, but payTo "${payTo}" looks like an EVM address.`
         );
       }
       if (!_algosdk2.default.isValidAddress(payTo)) {
-        throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
           `chain ${network} is Algorand, but payTo "${payTo}" is not a valid Algorand address.`
         );
       }
@@ -300,13 +300,13 @@ function makeAlgorandNetwork(preset, algodUrl) {
         const info = await _algosdk2.default.waitForConfirmation(algod, ref, 10);
         return { height: String(_nullishCoalesce(info.confirmedRound, () => ( 0))) };
       } catch (err) {
-        throw new (0, _chunkMDLZJGLYcjs.ConfirmationTimeoutError)(`Algorand tx ${ref} did not confirm in time.`, {
+        throw new (0, _chunkPA6YD3HLcjs.ConfirmationTimeoutError)(`Algorand tx ${ref} did not confirm in time.`, {
           cause: err
         });
       }
     },
     async estimateCost() {
-      return _chunkMDLZJGLYcjs.nativeCost.call(void 0, {
+      return _chunkPA6YD3HLcjs.nativeCost.call(void 0, {
         symbol: ALGO_SYMBOL,
         decimals: ALGO_DECIMALS,
         fee: 1000n,

package/dist/{algorand-WGVF4KTU.js → algorand-F3OYB534.js}

@@ -7,7 +7,7 @@ import {
   nativeCost,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-SVMGHASK.js";
+} from "./chunk-ILPABTI2.js";
 
 // src/drivers/algorand/index.ts
 import algosdk2 from "algosdk";

package/dist/{aptos-YT7SXWPF.cjs → aptos-GJGIZHNI.cjs}

@@ -6,7 +6,7 @@
 
 
 
-var _chunkMDLZJGLYcjs = require('./chunk-MDLZJGLY.cjs');
+var _chunkPA6YD3HLcjs = require('./chunk-PA6YD3HL.cjs');
 
 // src/drivers/aptos/index.ts
 var _tssdk = require('@aptos-labs/ts-sdk');
@@ -55,14 +55,14 @@ async function payAptos(params) {
     const res = await client.signSubmit({ signer, transaction });
     return res.hash;
   } catch (err) {
-    if (err instanceof _chunkMDLZJGLYcjs.InsufficientFundsError) throw err;
+    if (err instanceof _chunkPA6YD3HLcjs.InsufficientFundsError) throw err;
     if (isAptosAffordability(err)) {
-      throw new (0, _chunkMDLZJGLYcjs.InsufficientFundsError)(
+      throw new (0, _chunkPA6YD3HLcjs.InsufficientFundsError)(
         err instanceof Error ? err.message : "Insufficient APT/token balance for the payment.",
         { cause: err }
       );
     }
-    throw _nullishCoalesce(_chunkMDLZJGLYcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+    throw _nullishCoalesce(_chunkPA6YD3HLcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
   }
 }
 function isAptosAffordability(err) {
@@ -146,22 +146,22 @@ function txNotFound(hash) {
 
 function assertAptosWallet(wallet, network) {
   if (typeof wallet !== "object" || wallet === null) {
-    throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Aptos; wallet must be { privateKey } (ed25519-priv-0x\u2026) or { account }.`
     );
   }
   if ("walletClient" in wallet) {
-    throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Aptos; a viem { walletClient } can't be used \u2014 pass { privateKey } (ed25519-priv-0x\u2026) or { account }.`
     );
   }
   if ("secretKey" in wallet || "signer" in wallet || "mnemonic" in wallet || "keypair" in wallet || "keyPair" in wallet || "secret" in wallet || "seed" in wallet || "accountId" in wallet) {
-    throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Aptos; that looks like another family's wallet \u2014 pass { privateKey } (ed25519-priv-0x\u2026) or { account }.`
     );
   }
   if (!("privateKey" in wallet) && !("account" in wallet)) {
-    throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Aptos; wallet must be { privateKey } (ed25519-priv-0x\u2026) or { account }.`
     );
   }
@@ -173,13 +173,13 @@ function resolveAptosAccount(config) {
     try {
       return _tssdk.Account.fromPrivateKey({ privateKey: new (0, _tssdk.Ed25519PrivateKey)(config.privateKey) });
     } catch (cause) {
-      throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+      throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
         "Aptos wallet { privateKey } is not a valid ed25519 secret (ed25519-priv-0x\u2026 or 0x\u2026 hex).",
         { cause }
       );
     }
   }
-  throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)("Aptos wallet needs { privateKey } (ed25519-priv-0x\u2026) or { account }.");
+  throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)("Aptos wallet needs { privateKey } (ed25519-priv-0x\u2026) or { account }.");
 }
 
 // src/drivers/aptos/index.ts
@@ -251,16 +251,16 @@ function makeAptosNetwork(preset, rpcUrl) {
         const info = preset.tokens[token.toUpperCase()];
         if (!info) {
           const known = Object.keys(preset.tokens).join(", ") || "(none built in)";
-          throw new (0, _chunkMDLZJGLYcjs.UnknownTokenError)(
+          throw new (0, _chunkPA6YD3HLcjs.UnknownTokenError)(
             `token "${token}" isn't built in for Aptos (known: ${known}). Pass { metadata, decimals } for a custom Fungible Asset, or use 'native'.`
           );
         }
         return { asset: info.metadata, decimals: info.decimals, symbol: info.symbol };
       }
-      _chunkMDLZJGLYcjs.rejectForeignToken.call(void 0, token, "aptos", network);
+      _chunkPA6YD3HLcjs.rejectForeignToken.call(void 0, token, "aptos", network);
       const t = token;
       if (!t.metadata || typeof t.decimals !== "number") {
-        throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
           `chain ${network} is Aptos; a custom token must be { metadata, decimals }.`
         );
       }
@@ -287,7 +287,7 @@ function makeAptosNetwork(preset, rpcUrl) {
         valid = false;
       }
       if (!valid || evmLike) {
-        throw new (0, _chunkMDLZJGLYcjs.WrongFamilyError)(
+        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
           `chain ${network} is Aptos, but payTo "${payTo}" is not a valid Aptos address (0x + 32 bytes).`
         );
       }
@@ -309,11 +309,11 @@ function makeAptosNetwork(preset, rpcUrl) {
         const tx = await aptos.waitForTransaction({ transactionHash: ref });
         return { height: String(_nullishCoalesce(tx.version, () => ( "0"))) };
       } catch (err) {
-        throw new (0, _chunkMDLZJGLYcjs.ConfirmationTimeoutError)(`Aptos tx ${ref} did not finalize in time.`, { cause: err });
+        throw new (0, _chunkPA6YD3HLcjs.ConfirmationTimeoutError)(`Aptos tx ${ref} did not finalize in time.`, { cause: err });
       }
     },
     async estimateCost() {
-      return _chunkMDLZJGLYcjs.nativeCost.call(void 0, {
+      return _chunkPA6YD3HLcjs.nativeCost.call(void 0, {
         symbol: APT_SYMBOL,
         decimals: APT_DECIMALS,
         fee: 100000n,

package/dist/{aptos-LPBLSEIQ.js → aptos-SUXOVP7B.js}

@@ -6,7 +6,7 @@ import {
   nativeCost,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-SVMGHASK.js";
+} from "./chunk-ILPABTI2.js";
 
 // src/drivers/aptos/index.ts
 import { Aptos, AptosConfig, Network, AccountAddress } from "@aptos-labs/ts-sdk";

package/dist/{chunk-SVMGHASK.js → chunk-ILPABTI2.js}

@@ -37,7 +37,14 @@ var PaymentTimeoutError = class extends PipRailError {
 };
 var MaxRetriesExceededError = class extends PipRailError {
   code = "MAX_RETRIES_EXCEEDED";
-  /** The already-broadcast proof ref — recover with it, don't re-pay. */
+  /**
+   * The proof ref — recover with it, don't re-pay. Its meaning depends on the
+   * scheme: for `onchain-proof` it's the already-broadcast transaction ref
+   * (re-verify or re-submit it). For a standard `exact` rail it's the EIP-3009
+   * authorization NONCE (a `0x…` 32-byte value, NOT a tx hash) — re-PRESENT the
+   * same signed authorization, never re-sign a fresh nonce; check the token's
+   * `authorizationState(from, nonce)` before assuming it didn't settle.
+   */
   ref;
   constructor(message, options) {
     super(message, options);
@@ -46,6 +53,12 @@ var MaxRetriesExceededError = class extends PipRailError {
 };
 var PaymentDeclinedError = class extends PipRailError {
   code = "PAYMENT_DECLINED";
+  /** Why it was declined, as a typed enum (a hint; `.code` is the reliable channel). */
+  reasonCode;
+  constructor(message, options) {
+    super(message, options);
+    this.reasonCode = options?.reasonCode;
+  }
 };
 var ConfirmationTimeoutError = class extends PipRailError {
   code = "CONFIRMATION_TIMEOUT";
@@ -59,6 +72,9 @@ var InvalidEnvelopeError = class extends PipRailError {
 var NoCompatibleAcceptError = class extends PipRailError {
   code = "NO_COMPATIBLE_ACCEPT";
 };
+var UnsupportedSchemeError = class extends PipRailError {
+  code = "UNSUPPORTED_SCHEME";
+};
 var NonReplayableBodyError = class extends PipRailError {
   code = "NON_REPLAYABLE_BODY";
 };
@@ -168,6 +184,7 @@ export {
   SettlementError,
   InvalidEnvelopeError,
   NoCompatibleAcceptError,
+  UnsupportedSchemeError,
   NonReplayableBodyError,
   WrongFamilyError,
   UnknownTokenError,