@piprail/sdk 2.16.1 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,373 @@ 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.0.0] — 2026-09-09 — agent modes: a wallet an agent can EARN with, not only spend from
+
+### BREAKING
+
+- **`ResolvedNetwork` gains a required `addressOf(wallet)`.** Only affects code that implements
+  a CUSTOM driver via `registerDriver`; every built-in family already has it. The migration is one
+  method: return the bound wallet's own address, derived from the key, with no RPC read. Nothing
+  else in the public API changed, and no existing call site needs touching.
+
+### Added
+
+- **Agent modes: capability follows AUTHORITY, and `sovereign` gives an agent BOTH halves of a
+  wallet.** A new `mode` option on `PipRailClient` (`'supervised' | 'budgeted' | 'sovereign'`,
+  default `'budgeted'`) and `PIPRAIL_MODE` on the MCP server. **The default is unchanged**: omit
+  it and `paymentTools()` returns exactly the same eight tools, in the same order, so nothing
+  moves for anyone who does not opt in.
+
+  Before this, whether a model could swap depended on which PACKAGE it imported: a model driving
+  `@piprail/mcp` never could, while the same wallet driven through the SDK always could. That is
+  the wrong axis. `mode` moves the decision onto the only question that matters, which is who is
+  answerable for the wallet, and it is set by whoever provisions the key. A model can never set
+  it: `mode()` reads, nothing writes, and no tool takes a `mode` argument.
+
+  ⭐ **`'sovereign'` is the whole wallet, not a bigger allowance.** A budget only ever lets an
+  agent SPEND, however large the cap. Sovereign appends five tools: `piprail_quote_swap` and
+  `piprail_swap`, plus the seller tools **`piprail_sell`**, **`piprail_collect`** and
+  **`piprail_earnings`**, so an agent can be PAID as well as pay. `piprail_sell` prices something
+  and returns an x402 challenge; because a challenge is only data, the agent hands it to a buyer
+  over any channel it already has, with **no web server and no open port anywhere**.
+  `piprail_collect` verifies the returned proof against the chain, and only `paid: true` clears
+  delivery. Each proof is single-use, so a replay is never a second sale.
+
+  **Two properties make selling safe to grant a model where spending is not.** The receiving side
+  holds **no private key at all** (`payTo` is a public address), so the earning half cannot spend
+  and cannot be drained even if the host is taken. And `payTo` defaults to the agent's **own**
+  address, which it otherwise has no way to learn, so it is never told to trust one a buyer sent.
+
+  Swapping is bounded by a separate instrument, because the payment caps cannot bound it: a swap
+  moves the holder's own funds between denominations, so `maxAmount`, `maxTotal`, the count caps
+  and the session TTL all pass over it untouched. `swapPolicy` adds a ceiling per swap, a slippage
+  ceiling and an optional destination allowlist, and the ceiling binds on the quote's on-chain
+  `maxSpend`, never the estimate. The MCP server **refuses to boot** on
+  `PIPRAIL_MODE=sovereign` without `PIPRAIL_MAX_PER_SWAP`, so an operator finds out while reading
+  their own config rather than mid-spend. Selling needs no ceiling, because it takes money rather
+  than spending it.
+
+- **`client.balanceOf(assets)` + the `piprail_wallet` tool: an agent can finally see its own
+  balance sheet.** A sovereign agent had thirteen tools and could not answer *"what do I have?"* —
+  `budget()` reports how much of an allowance is left, which is a different question, and
+  `planPayment()` answers it only for one URL at a time. Owning finances starts with seeing them.
+  An unavailable read reports `null`, **never `0`**: an agent told it holds nothing when the RPC
+  merely failed would fire-sale to recover from a loss that never happened. On a `MultiChainPayer`
+  the holdings span every chain, because reporting only the primary would call an agent broke
+  while it held funds one client along.
+
+- **`ResolvedNetwork.addressOf(wallet)` and `client.address()`: a wallet can finally report where
+  it gets PAID.** Every driver already derived this internally for `balanceOf`; nothing exposed
+  it. Without it an agent handed a key it never chose has no way to learn its own address, so it
+  could pay for anything and be paid for nothing. Implemented across all ten families. Pure:
+  derived from the key, no RPC read, nothing moved. Also `client.chain()`, and `canAgentSell()`
+  alongside the existing `canAgentSwap()`. `MultiChainPayer` delegates all of them to the primary
+  client, without which sovereign mode would be unreachable through the MCP, which always wraps
+  its accounts in one.
+
+### Fixed
+
+- **An agent paying twice in a row collided with itself on EVM.** Found live on Base: the first
+  payment settled and the next two were refused by the node with "nonce lower than the current
+  nonce of the account", because viem asks the RPC for the nonce on every send and two payments
+  issued back to back both read the same value before either was mined. It failed SAFELY (nothing
+  broadcast, nothing recorded as spent, `send` called exactly once with no retry), so it never
+  risked a double payment, but paying several times in quick succession is the ordinary behaviour
+  of an autonomous agent rather than an edge case. A raw `{ key }` is now bound through viem's
+  `nonceManager`, which assigns nonces locally per (chain, account) and reconciles with the chain.
+  A caller who brings their own `walletClient` keeps their own nonce policy, untouched. The same
+  three back-to-back Base payments now all settle.
+
+- **TON reported a BOUNCEABLE address as "where I get paid".** `addressOf` was added to all ten
+  families at once, and checking each against the address recorded in its funded test wallet came
+  back 9/10: TON derived `EQ…` where the wallet file (and every TON wallet UI) says `UQ…`, the
+  same account in the other encoding. A bounceable address returns funds to the sender when the
+  destination contract is not yet initialised, and a wallet contract stays uninitialised until it
+  has sent its first transaction, so a freshly generated agent advertising `EQ…` would have
+  bounced the first payment it was ever sent. Verification was never affected (both forms parse to
+  one account); what was wrong is the address an agent hands out. Now 10/10 against ground truth.
+
+- **🔴 One payment could collect TWO offers.** Found by attacking the seller tools. Each offer
+  owns its own gate, and a gate's replay set is scoped to itself, which is right for
+  `requirePayment` (one gate, one resource) and wrong for a store of offers: two offers priced the
+  same to the same address are indistinguishable to any driver, because a driver can only ask "did
+  this settlement move at least X to this address?". A buyer could pay for a haiku and collect the
+  expensive listing with the same money. Two bindings now close it, both mutation-proven and
+  re-verified on mainnet: `collect` refuses a proof minted for a different offer
+  (`code: 'wrong_offer'`) before the chain is consulted, and the used-proof set belongs to the
+  SELLER rather than to each gate, so one settlement is dead everywhere once redeemed.
+
+- **`mode: 'supervised'` supervised nothing, and `PIPRAIL_MODE=supervised` wired nothing.** The
+  mode↔confirm inference ran ONE WAY: `PIPRAIL_CONFIRM=1` meant supervised, but naming the mode
+  did not turn confirmation on. An operator who asked for a human in the loop got an agent that
+  paid without asking anybody, with the banner, the docs and the mode name all agreeing it was
+  supervised. Both directions now agree; a config that says both things at once is refused rather
+  than quietly resolved; and the SDK refuses `mode: 'supervised'` with no `onBeforePay` to perform
+  it. `sovereign` + confirmation is not a contradiction and stays allowed.
+
+- **A SWAP was invisible to the approver.** `onBeforePay` never sees a swap, because a swap is not
+  a payment, which is the whole reason `swapPolicy` bounds it instead. But an operator who wired
+  an approver did not mean "ask me before payments and let value move silently any other way", so
+  a supervised sovereign agent could swap its whole balance without one prompt. New
+  **`onBeforeSwap`**, same fail-safe contract, wired automatically by `@piprail/mcp` whenever
+  confirmation is on. Proven against the bug: a refusing approver was never called and the swap
+  executed.
+
+- **The SDK let `'sovereign'` hand a model the swap tools with NO ceiling.** `@piprail/mcp`
+  already refused to boot in that state, so the safer surface could be sidestepped by importing
+  the other one. Proven before the fix: a 99,999-unit swap executed with nothing refusing it.
+  `mode: 'sovereign'` now requires `swapPolicy.maxPerSwap` in the SDK too.
+
+- **The MCP banner under-reported what the agent could do.** It printed a hardcoded eight tools
+  even in sovereign mode, where the model actually holds thirteen. It is now handed the real list
+  at startup, so an operator can see the capability they granted.
+
+- **Docs claimed the MCP has no swap tool "and there will not be one".** True when written and
+  false since modes shipped, in `mcp/README.md` and the tools reference. Both now describe the
+  mode-dependent contract, and a sync rule pins it so the claim cannot rot again.
+
+- **Swapping reaches every family: Aptos, TON and Tron close the last three gaps.** Seven routes
+  became **ten, across 18 chains, with 21 mainnet proofs**. Nothing about the existing routes
+  changed, and swapping stays opt-in.
+
+  **Aptos via Hyperion** and **Tron via SunSwap V2** need **no API at all**: the quote is an
+  on-chain read and the swap is a contract call the user's own key signs. There is no host to go
+  down, no key to rotate and no vendor in the middle. That was deliberate on Tron, whose own front
+  end talks to an undocumented, obfuscated hostname a payments SDK should not depend on. **TON via
+  STON.fi** uses a keyless REST simulation and one message the wallet signs.
+
+  ⭐ **Three of them are exact-output natively**, which no earlier route was. Hyperion's
+  `exact_output_swap_entry`, SunSwap's `swapTokensForExactTokens` and STON.fi's `reverse_swap`
+  all take the invoice amount and cap the input **on-chain**, so an x402 invoice is priced from
+  its output rather than sized from a probe. Proven to the unit on Aptos: four swaps delivered
+  exactly 0.05 USDT, 0.04 USDC, 0.03 USDC and 0.02 APT. On TON the guarantee is a floor rather
+  than a point: STON.fi's `reverse_swap` fixes the ask side, and PipRail pads the request so the
+  router's on-chain `min_ask_units` is at or above the invoice. Slightly more can arrive; less is
+  refused by the router.
+
+  **Live-proven on mainnet**: four Aptos swaps (both stable directions plus native APT in and out)
+  and two TON swaps (native in, jetton in, which the simulation routed through two *different*
+  router versions). **Tron ships WITHOUT a proof and says so on the site and in the docs**: the
+  quote is verified live and the swap executes cleanly in simulation, but Tron charges about
+  230,629 ENERGY per swap, which without staked energy is roughly 23 TRX (~$7.79) *regardless of
+  trade size*, and the test wallets hold 8.1 TRX. A new `unproven` field carries that reason, and
+  a guard test fails if a route ever ships with neither a proof nor a stated reason.
+
+  Adds two OPTIONAL peer dependencies for TON only (`@ston-fi/sdk`, `@ston-fi/api`, both MIT and
+  lazily imported); the lazy-chunk invariant still holds, so a pure-EVM install downloads neither.
+  Aptos and Tron needed no new dependency at all.
+
+  **Four more bugs found the same way as always, by spending real money.** Aptos aborted with
+  `ESQRT_PRICE_LIMIT_UNAVAILABLE` because a concentrated-liquidity swap needs a directional price
+  bound and `0` is not one; the bounds are now read off the chain rather than copied from another
+  DEX. The entry function's two amount slots are "what leaves, what arrives", **not** "the exact
+  one, the limit", and having them backwards aborts with `EINSUFFICIENT_BALANCE`, which reads like
+  a funding problem and is not one. A pool's `token0` field comes back as all-zeros for native-APT
+  pools, so the direction is now derived by comparing addresses. And pricing every fee tier blindly
+  burned the public node's anonymous compute quota (40k units per 300s), after which good routes
+  came back as "no route" — the quote now cheap-filters empty pools before paying to price them.
+
+- **Robinhood Chain (`chain: 'robinhood'`, eip155:4663) — the 30th chain, and the first with a
+  Paxos-issued stablecoin.** The tokenized-equity Arbitrum Orbit L2, mainnet since 2026-07-01,
+  running 100ms blocks and settling to Ethereum. viem ships no preset and it is absent from
+  chainid.network, so the chain is defined inline from the values Robinhood publishes.
+
+  **One stablecoin on purpose: USDG**, the Paxos Global Dollar, which is what the chain's own
+  markets quote against. Its address was agreed by four independent sources before shipping —
+  Paxos's published list, our own on-chain read (`Global Dollar`, 6dp), and both facilitators'
+  `/supported`. **Circle issues no native USDC here** (checked against Circle's own contract
+  list), so no USDC or USDT preset ships: a bridged one would break the issuer-native token rule.
+  Native ETH is a payment asset as on every EVM chain.
+
+  **Gasless from day one, proven twice.** USDG is EIP-3009 **and** EIP-2612, verified by calling
+  the contract rather than by scanning bytecode — a bytecode scan said neither was present, and
+  was wrong. Its EIP-712 domain is `name: "Global Dollar", version: "1"`, which we confirmed by
+  recomputing the on-chain `DOMAIN_SEPARATOR`. Two keyless facilitators already settle there and
+  **both were live-settled by us**, with buyer *and* merchant paying zero ETH:
+  Ultravioleta DAO (tx `0x35361e57…`) and Dexter (tx `0x1ba66e3d…`, permit2, ~$0.0066 floor).
+  A self-settled EIP-3009 round trip also passed end to end (tx `0xe6d35460…`): 402 → sign →
+  settle → 200, replay rejected as `tx_already_used`, payer ETH delta exactly zero.
+
+  **Swapping works there too**, through the existing KyberSwap route — native ETH → 0.360518 USDG,
+  tx `0x424299e6…`. Worth knowing: at 100ms blocks a route goes stale fast, and the default
+  0.5% slippage reverted before 3% cleared. Reaching the chain at all is a bridge; Relay moved
+  ETH from Base in about three seconds for roughly $0.04, and Across and LI.FI both list it.
+
+- **`quoteSwap()` / `swap()`: an optional helper for when you hold the wrong token.** A 402 names a
+  token, a wallet holds what it holds, and when those disagree `planPayment()` reported
+  `INSUFFICIENT_TOKEN` and stopped. This turns that dead end into an option the caller may take or
+  ignore.
+
+  **It is opt-in and it stays that way.** Paying never swaps, planning never swaps, and there is
+  deliberately no `autoSwap` flag: converting one asset into another is a priced, irreversible act,
+  and a payment library should not do it on your behalf because it noticed you were short. A test
+  asserts the byte-identical default (STANDARDS §0), so "not using it costs you nothing" is machine
+  checked rather than promised in prose.
+
+  Ships in **two tiers, kept apart by the type system**. Tier 1 (`source.kind: 'protocol'`) is
+  Stellar (`PathPaymentStrictReceive` to your own account) and the XRP Ledger (a cross-currency
+  `Payment` to your own address, auto-bridged through XRP): the ledger itself swaps, so there is
+  **no third party, no API key, no extra dependency and no integrator fee**. Tier 2
+  (`source.kind: 'provider'`) is **Solana via Jupiter**, **9 live-probed EVM chains via KyberSwap**,
+  **Sui via Aftermath**, **NEAR via Ref Finance**, **Algorand via Vestige**, **Aptos via
+  Hyperion**, **TON via STON.fi** and **Tron via SunSwap V2**, because those chains have no
+  protocol-level swap. **Ten routes across 18 of the 30 chains.** On a chain with no route,
+  `quoteSwap()` answers `null` and `swap()` throws `UnsupportedNetworkError` naming every venue
+  that does exist, read from the registry rather than typed into the message.
+
+  NEAR uses **Ref Finance rather than NEAR Intents**, deliberately: Intents puts a solver in
+  possession of the funds mid-flight, which is the intermediary this project exists to remove. Ref
+  is one `ft_transfer_call` receipt chain inside a single transaction the user signs.
+
+  The **swap coverage map is data** (`SWAP_PROVIDERS`), shaped like `KNOWN_FACILITATORS` and
+  carrying the same admission rule. The website table is generated from it, a sync rule and a guard
+  test hold the logos, site data and docs to it, and a new `swaps` domain documents the update order.
+
+  **Providers had to earn their place.** Each was probed live from a plain keyless server request:
+  KyberSwap 200 ✅, Jupiter 200 with `platformFee: null` ✅, while 0x (401), 1inch (401), Odos (530),
+  OpenOcean (403), Squid (400), Rango (401) and thirdweb Bridge (401) all failed and were rejected.
+  PipRail never sets a platform or integrator fee field on any provider.
+
+  **Proven with 21 real mainnet swaps across 9 chains**, both tiers, both directions on every
+  chain that has two, each verified by reading the transaction back from a public node, and
+  re-verifiable any time with `npm run verify:proofs`. The full table with hashes is in the docs. One known failure is recorded rather than hidden: FDUSD→USDC
+  on BNB reverts with `TRANSFER_FROM_FAILED` despite confirmed balance and allowance, and is
+  documented as unexplained.
+
+  **Live testing found nine real bugs, all fixed**, every one of which passed a typechecker and a
+  unit suite first: some tokens revert on a non-zero to non-zero ERC-20 `approve` (the allowance is
+  now zeroed first); XRPL path steps carry fields xrpl.js cannot always encode (now stripped);
+  XRPL public path finding is intermittent, returning a route then nothing with no error (now
+  retried); XRPL float precision silently discarded valid routes, making a whole direction look
+  unsupported (now parsed with a ceiling); and a malformed Stellar issuer threw out of a
+  never-throw method while one unparseable Horizon candidate could poison a valid quote. Four more
+  came from the new families, and **four of the nine made an entire chain look unsupported when it
+  was not**: setting `accept-encoding` by hand defeated fetch's gzip handling and broke NEAR
+  outright; NEAR pool ids are strings in the indexer and numbers on the contract; Vestige returns
+  `amount_out: 0` for a dust probe rather than an error, so a fixed probe size reported no route on
+  a pair that routes fine; and Sui's public JSON-RPC is being deprecated.
+
+  **The no-fee claim is self-verifying.** Rather than hardcoding it, every quote inspects the
+  provider's own fee fields and the note SAYS SO if one ever appears, instead of repeating a claim
+  that has quietly become false.
+
+  🔴 **PipRail still runs no price oracle** (STANDARDS §7). A swap rate is a price, so every
+  `SwapQuote` carries a `source` naming who produced it: `kind: 'protocol'` when the ledger's own
+  order books priced it (Stellar, XRPL), `kind: 'provider'` when a named venue did. The distinction
+  lives in the type system, not in prose.
+
+  Slippage rides **on-chain** (`sendMax` / `SendMax`, `amountInMax`, `amount_in_max`, TON's
+  `min_ask_units` floor), so a market that moves past your tolerance fails the transaction rather
+  than overspending. Nothing is swapped in that case; chains that charge for a reverted
+  transaction (EVM, Aptos, Tron) still take the gas. Default 0.5%, ceiling 10%, integer maths
+  that rounds in the user's favour, and a malformed `slippageBps` throws `RangeError` before any
+  read happens rather than coming back as a silent `null`.
+
+  New exports: `SwapRequest`, `SwapQuote`, `SwapReceipt`, `SwapSide`, `SwapQuoteSource`,
+  `summarizeSwap`, `resolveSlippageBps`, `applySlippage`, `DEFAULT_SLIPPAGE_BPS`,
+  `MAX_SLIPPAGE_BPS`. Docs: [Swapping tokens](https://docs.piprail.com/making-payments/swapping/).
+
+  Surveyed and deliberately **not** bundled: thirdweb Bridge, LI.FI, Squid, Relay, deBridge,
+  Across, Rango. thirdweb Bridge as the worked example requires an API key at the type level,
+  charges a 0.30% protocol fee an integrator cannot disable, and is EVM-only for cross-chain
+  routing, so nine of PipRail's ten families cannot even be expressed in its API.
+
+### Fixed
+
+- **Tron could not have sold a token at all.** SunSwap V2's router moves the input with
+  `transferFrom` and the driver had no approve step, so native-TRX-in worked while every TRC-20
+  direction would have failed on allowance after the energy was burned. Nothing caught it
+  because the route ships without a mainnet proof. Adding the approve then exposed a second bug:
+  a fresh allowance slot measures **99,764 energy ≈ 9.98 TRX**, and the approve ceiling had been
+  set to 10 TRX because "an approve is cheap". Both paths are simulated against Tether's real
+  Tron contract and pinned by tests; a token-in swap now budgets roughly 33 TRX.
+
+- **Both shipped TON proofs pointed at the gas refund, not the swap.** STON.fi returns unused
+  forward gas to the same wallet a second after the swap, and the driver reported whichever
+  wallet transaction was newest, so the recorded reference was an *incoming* `excesses` message
+  with no outgoing message at all. The swaps were real; the evidence pointed at the wrong leg. The
+  driver now reports the newest transaction the wallet itself signed (`external-in`), the registry
+  carries the corrected hashes, and `verify:proofs` rejects a TON reference of the wrong shape.
+
+- **STON.fi's "reverse" simulation was not exact-output.** Asked for 50000 at 1% tolerance it
+  returns an on-chain floor of 49500, which the router will deliver, short-paying an invoice. The
+  request is now padded so the floor is at or above the invoice, the quote is refused when it is
+  not, and every number the swap later parses is validated in the never-throw quote.
+
+- **Aptos paid the account that quoted, not the one that signed.** The recipient was captured at
+  quote time and reused at swap time; every other family derives it from the signing wallet.
+
+- **`quoteSwap()` swallowed a malformed `slippageBps` into `null` on a read-only client** because
+  validation ran after the wallet check. It now runs first, so a caller's bug throws `RangeError`
+  regardless of what else is wrong.
+
+- **A mined transaction is not a successful swap — `swap()` could report success for a swap that
+  failed.** On EVM, `waitForTransactionReceipt` resolves for a **reverted** transaction exactly as
+  it does for a mined one; the driver returned unconditionally, so a reverted swap handed back a
+  `SwapReceipt` carrying a real transaction hash while nothing had moved. On Solana the same class
+  of hole existed one step earlier: `sendRawTransaction` returns once the RPC accepts the bytes, so
+  a transaction that then failed on-chain was also reported as a completed swap. Both now check and
+  throw `InsufficientFundsError`. This is the worst failure shape available to a payments SDK — an
+  agent believes it holds the token and goes on to pay an invoice it cannot cover — and it affected
+  **every EVM chain and Solana**, not one chain. Found on Robinhood Chain, whose 100ms blocks stale
+  a route often enough to surface it; Sui and NEAR already checked their status correctly.
+
+- **A strict x402 v2 facilitator refused every PipRail settlement, and we read it as a missing
+  chain.** PipRail sent a v2 body carrying only the v1 `paymentRequirements` key. A facilitator
+  that validates the v2 envelope needs `accepted` and `resource` at the request root, and answered
+  `400 data did not match any variant of untagged enum VerifyRequestEnvelope`. A v2 body now carries
+  both spellings, so the older facilitators keep reading `paymentRequirements` while a strict v2
+  facilitator gets what it requires. `resource` comes from the merchant's own gate config, never the
+  client's echo, and is always sent complete because the field is required rather than optional.
+
+  The cost of the bug was not the 400 itself. It was recorded in `facilitators.ts` for months as
+  "Ultravioleta DAO's NEAR listing is aspirational, not settle-capable" — a conclusion about
+  somebody else's implementation drawn from an error about our own request.
+
+### Added
+
+- **NEAR is live on a keyless facilitator, the first x402 facilitator settlement on `near:mainnet`.**
+  Ultravioleta DAO settles the NEP-141 USDC rail through a NEP-366 meta-transaction with the buyer
+  paying zero NEAR (tx `8pVe4oeykCT2WpCwToNbkxjdgSvwNNtJUrGezDCHKDda`), so `exact: true` is now
+  zero-config gasless on NEAR.
+- **Ultravioleta DAO on Avalanche**, buyer holding zero AVAX
+  (tx `0xe9a88e4fa978a16599b6188444d87ea63d43122e5fad16493568c2a596a79436`).
+- NEAR receipts are now re-verifiable by the facilitator-probe tx checker and link to an explorer on
+  piprail.com. Both tools matched only EVM, Solana and Algorand hash shapes, so a NEAR receipt would
+  have shipped as unlinked, unchecked text.
+
+### Notes
+
+- A sweep of all 21 mainnets Ultravioleta DAO advertises found two more it does **not** settle:
+  Solana (`/verify` returns `isValid: true`, then `/settle` fails `contract_call_failed`) and
+  Algorand (`/verify` cannot deserialize an Algorand `exact` payload). Both are locked by tests so
+  the next sweep does not re-run them. Advertised is not settled — only a receipt is.
+
+## [2.16.2] — 2026-09-06 — every facilitator now carries a verifiable receipt
+
+### Changed
+
+- **All 29 facilitator entries now cite a full, machine-verifiable transaction hash.** Four did
+  not: three kept only a truncated prefix (`tx 4dL8jRKH…`) and one recorded a verification with no
+  hash at all. A prefix cannot be opened on an explorer and cannot be re-checked by
+  `verify-tx.mjs`, so those four entries were claims rather than proofs.
+
+  Rather than reconstruct old hashes, each was **re-proven with a fresh mainnet payment**: PayAI
+  and OpenFacilitator on Solana, PayAI and xpay on Base. Every run asserted the full round trip,
+  the merchant balance moving by exactly the amount, the buyer paying **zero** native, and a
+  replay being rejected.
+
+  `verify-tx.mjs` now reports **30 verified, 0 refuted, 0 skipped**. Previously 4 were skipped as
+  unverifiable.
+
+### Fixed
+
+- **Solana proof hashes never rendered as explorer links on piprail.com.** The site generator
+  matched only EVM (`0x…64`) and Algorand (base32) hash shapes, so base58 Solana signatures fell
+  through to unlinked text while `solscan.io` sat configured and unused in the chain metadata.
+  Every Solana receipt is now a working link. This was invisible because the hash still displayed,
+  just without a link.
+
 ## [2.16.1] — 2026-09-06 — GoPlausible settles Solana, live-proven
 
 ### Added
@@ -2130,6 +2497,7 @@ 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.
 
+[2.16.2]: https://www.npmjs.com/package/@piprail/sdk
 [2.16.1]: https://www.npmjs.com/package/@piprail/sdk
 [2.16.0]: https://www.npmjs.com/package/@piprail/sdk
 [2.15.1]: https://www.npmjs.com/package/@piprail/sdk
@@ -2170,6 +2538,7 @@ 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.0.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.3.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.2.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.1.1]: https://www.npmjs.com/package/@piprail/sdk

package/README.md

@@ -78,6 +78,7 @@ The same app can **take** payments and **make** them. → [Making payments](http
 | **[Getting started](https://docs.piprail.com/getting-started/introduction/)** | Install · quickstart · how it works |
 | **[Accepting payments](https://docs.piprail.com/accepting-payments/require-payment-and-gate/)** | `requirePayment` · `createPaymentGate` · [presets](https://docs.piprail.com/accepting-payments/merchant-presets/) (`createPaywall` / `createTipJar`) · [framework adapters](https://docs.piprail.com/accepting-payments/framework-adapters/) · the `exact` rail · the `upto` metered rail |
 | **[Making payments](https://docs.piprail.com/making-payments/piprail-client/)** | `PipRailClient` · `quote` · `estimateCost` · `planPayment` · auto-route · `MultiChainPayer` |
+| **[Swapping tokens](https://docs.piprail.com/making-payments/swapping/)** | `quoteSwap` · `swap` — OPTIONAL, opt-in, never automatic. Keyless routes only, no fee, no API key |
 | **[Verifiable receipts](https://docs.piprail.com/accepting-payments/verifiable-receipts/)** | Chain-grounded, anyone-verifiable receipts (no key) · optional EIP-712 attestation |
 | **[Spend controls](https://docs.piprail.com/spend-controls/payment-policy/)** | Per-token + cross-token grand total · payment-count caps · time envelope · durable budget · the spend ledger |
 | **[Agent toolkit](https://docs.piprail.com/agent-toolkit/payment-tools/)** | `paymentTools` · the agent guide · NL renderers |

package/dist/{algorand-25FMBCT3.js → algorand-HL57PQHE.js}

@@ -1,6 +1,9 @@
 import {
   ALGORAND_SPEC_CAIP2
-} from "./chunk-2CX7XRZK.js";
+} from "./chunk-TZDVZCTC.js";
+import {
+  applySlippage
+} from "./chunk-GVCGUSTE.js";
 import {
   ConfirmationTimeoutError,
   InsufficientFundsError,
@@ -10,10 +13,11 @@ import {
   UnsupportedSchemeError,
   WrongFamilyError,
   assertNoLegacyWalletKey,
+  formatUnits,
   nativeCost,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-QU25LSVS.js";
+} from "./chunk-5GRBEMCA.js";
 
 // src/drivers/algorand/index.ts
 import algosdk3 from "algosdk";
@@ -86,6 +90,144 @@ function firstLine(message) {
   return message.split("\n")[0].slice(0, 160);
 }
 
+// src/drivers/algorand/swap.ts
+var VESTIGE_API = "https://api.vestigelabs.org";
+var ALGO_ASA = 0;
+function sourceFor(poolFee) {
+  const fee = typeof poolFee === "number" ? `${(poolFee * 100).toFixed(2)}%` : "the pool's own fee";
+  return {
+    kind: "provider",
+    name: "Vestige",
+    note: `Third-party Algorand DEX aggregator (api.vestigelabs.org), used keyless. It returns an UNSIGNED atomic transaction group in which every signer is you: nobody co-signs and nothing is delegated. Pool fee on this route: ${fee}. PipRail adds nothing.`
+  };
+}
+function asaId(t) {
+  if (t.asset === "native") return ALGO_ASA;
+  const n = Number(t.asset);
+  return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+function side(t, amount) {
+  const decimals = t.asset === "native" ? ALGO_DECIMALS : t.decimals;
+  return {
+    asset: t.asset,
+    symbol: t.symbol ?? (t.asset === "native" ? "ALGO" : t.asset),
+    decimals,
+    amount: amount.toString(),
+    amountFormatted: formatUnits(amount, decimals)
+  };
+}
+async function req(url, init) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 15e3);
+  try {
+    const res = await fetch(url, { ...init ?? {}, signal: ctrl.signal });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function quoteAlgorandSwap(p) {
+  if (p.wantAmount <= 0n) return null;
+  const fromAsa = asaId(p.from);
+  const toAsa = asaId(p.to);
+  if (fromAsa === null || toAsa === null || fromAsa === toAsa) return null;
+  const quoteFor = (amountIn) => req(
+    `${VESTIGE_API}/swap/v4?from_asa=${fromAsa}&to_asa=${toAsa}&amount=${amountIn.toString()}&mode=sef&denominating_asset_id=0`
+  );
+  const fromDecimals = p.from.asset === "native" ? ALGO_DECIMALS : p.from.decimals;
+  let probeIn = 10n ** BigInt(Math.max(fromDecimals - 2, 1));
+  let probeOut = 0;
+  for (let step = 0; step < 4; step += 1) {
+    const probe = await quoteFor(probeIn);
+    const out = probe?.amount_out;
+    if (out && out > 0) {
+      probeOut = out;
+      break;
+    }
+    probeIn *= 10n;
+  }
+  if (!probeOut) return null;
+  let needIn = (probeIn * p.wantAmount + BigInt(probeOut) - 1n) / BigInt(probeOut);
+  needIn = applySlippage(needIn, p.slippageBps);
+  const real = await quoteFor(needIn);
+  const realOut = real?.amount_out;
+  if (!realOut) return null;
+  if (BigInt(Math.floor(realOut)) < p.wantAmount) return null;
+  const poolFee = real.single?.transactions?.[0]?.swaps?.[0]?.fee;
+  return {
+    source: sourceFor(poolFee),
+    network: p.network,
+    from: side(p.from, needIn),
+    to: side(p.to, BigInt(Math.floor(realOut))),
+    maxSpend: needIn.toString(),
+    maxSpendFormatted: formatUnits(needIn, fromDecimals),
+    slippageBps: p.slippageBps,
+    // The build endpoint wants the ENTIRE quote response back, unmodified.
+    route: { quote: real }
+  };
+}
+async function swapAlgorand(p) {
+  const route = p.quote.route;
+  if (!route?.quote) {
+    throw new Error("Algorand: swap quote is missing its Vestige routing data \u2014 re-quote before swapping.");
+  }
+  const slippage = p.quote.slippageBps / 1e4;
+  const unsigned = await req(
+    `${VESTIGE_API}/swap/v4/transactions?sender=${p.signer.addr}&slippage=${slippage}`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(route.quote)
+    }
+  );
+  if (!unsigned?.length) {
+    throw new RecipientNotReadyError(
+      "Vestige could not build this swap. The usual cause is that your account is not opted in to the asset you are swapping INTO: opt in first, then re-quote. Nothing was spent."
+    );
+  }
+  for (const t of unsigned) {
+    if (t.signers && t.signers.some((s) => s !== p.signer.addr)) {
+      throw new Error(
+        "Algorand swap refused: the built group asks a third party to co-sign, which this rail must never do. Nothing was signed."
+      );
+    }
+  }
+  try {
+    const signed = unsigned.map((t) => {
+      const decoded = p.algosdk.decodeUnsignedTransaction(Buffer.from(t.txn, "base64"));
+      return decoded.signTxn(p.signer.sk);
+    });
+    const res = await p.algod.sendRawTransaction(signed).do();
+    const txid = res.txid ?? res.txId;
+    if (!txid) throw new Error("Algorand: sendRawTransaction returned no transaction id.");
+    return {
+      transaction: txid,
+      network: p.quote.network,
+      source: p.quote.source,
+      from: p.quote.from,
+      to: p.quote.to
+    };
+  } catch (err) {
+    const msg = String(err?.message ?? err);
+    if (/asset .* missing|not opted in|receiver error/i.test(msg)) {
+      throw new RecipientNotReadyError(
+        `Algorand swap refused: your account must opt in to the asset you are swapping INTO first. (${msg.slice(0, 140)})`,
+        { cause: err }
+      );
+    }
+    if (/overspend|insufficient|below min/i.test(msg)) {
+      throw new InsufficientFundsError(
+        `Algorand swap failed: the account can't cover it (balance, the 0.1 ALGO minimum, or group fees). (${msg.slice(0, 140)})`,
+        { cause: err }
+      );
+    }
+    throw err;
+  }
+}
+
 // src/drivers/algorand/exact.ts
 import algosdk from "algosdk";
 var ZERO_ADDRESS = algosdk.Address.zeroAddress().toString();
@@ -556,6 +698,11 @@ function makeAlgorandNetwork(preset, algodUrl) {
         detail: "min fee 1000 \xB5Algos (1 transaction)"
       });
     },
+    /** The bound wallet's own address — where THIS wallet gets paid. Derived from the key
+     *  material only: no RPC, nothing moved. See {@link ResolvedNetwork.addressOf}. */
+    async addressOf(wallet) {
+      return String(resolveAlgorandWallet(wallet._native).addr);
+    },
     async balanceOf(wallet, asset) {
       let owner;
       try {
@@ -590,6 +737,14 @@ function makeAlgorandNetwork(preset, algodUrl) {
         return { ready: "unknown" };
       }
     },
+    /* ---- swap (OPTIONAL, opt-in): via Vestige, keyless + no integrator fee. See ./swap.ts ---- */
+    async quoteSwap({ from, to, wantAmount, slippageBps }) {
+      return quoteAlgorandSwap({ network, from, to, wantAmount, slippageBps });
+    },
+    async swap(wallet, quote) {
+      const signer = resolveAlgorandWallet(wallet._native);
+      return swapAlgorand({ algosdk: algosdk3, algod, signer, quote });
+    },
     async verify(_ref, accept) {
       return verifyAlgorand({ reader, accept });
     },