@piprail/sdk 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -4,6 +4,68 @@ 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/).
 
+## [2.10.0] — 2026-06-20 — x402 parity: verifiable receipts · the `upto` metered rail · A2A transport
+
+Four ratified-x402 capabilities, all **additive and opt-in** — omit the new options and the 402, the
+200, and the pay path are byte-identical to 2.9.0.
+
+- **feat(receipts): verifiable receipts — chain-grounded (no key) + optional EIP-712 attestation.**
+  `receipts: true` on a gate emits a self-contained `PipRailReceipt` on every settled payment, in a
+  byte-compatible `extensions['offer-receipt'].info` block. **Anyone** re-verifies it against the chain
+  with only an RPC: `PipRailClient.verifyReceipt(receipt)` re-reads the settlement tx and re-derives
+  `payTo`/`asset`/`payer`, **ignoring the receipt's claims** (never throws; `amount` is a verified lower
+  bound; `payer` genuinely re-derived). `client.lastReceipt()` captures it after a paid `fetch`. The new
+  additive wire field is `X402Receipt.nonce?` (required to re-verify the five memo-bound families:
+  Stellar/XRPL/NEAR/Algorand/TON). **Tier 2 (EVM-only):** `receipts: { attest: { wallet } }` also signs
+  the official x402 offer-receipt EIP-712 `RECEIPT_TYPES` with the merchant's existing `payTo` wallet —
+  attesting the one thing the chain can't (that the resource was *served*); verify with
+  `PipRailClient.verifyAttestation`. `includeTxHash` defaults **true** (PipRail-default verifiability — a
+  deliberate, documented divergence from the reference privacy-default; flip to `false` for the §5.3
+  empty-string privacy path). New exports: `buildReceiptExtension`, `parseReceiptExtension`,
+  `PipRailReceipt`, `SignedReceipt`, `ReceiptInput`, `ReceiptOption`, `ReceiptVerification`.
+- **feat(upto): the ratified `upto` (metered / variable-amount) rail — EVM-Permit2, self-settle.** The
+  buyer signs a Permit2 authorization for a **maximum**; the merchant serves, meters, then self-settles
+  the **actual** (`≤ max`) from its own relayer through the on-chain `x402UptoPermit2Proxy` — backendless,
+  no fee. Opt in with `upto: { relayer, settleAmount }` and meter inside `settleAmount` on a direct
+  `gate.verify()` call (`requirePayment` throws for `upto` — it settles before the handler serves). A
+  zero charge settles nothing on-chain. New `X402UptoAcceptEntry` / `Permit2UptoAuthorization` types +
+  `parseUptoPaymentHeader` / `buildUptoSignatureHeader` codecs.
+- **feat(transport): A2A — `gate.verifyObject()` + the A2A seller handler.** `gate.verifyObject(payload)`
+  verifies a raw-JSON payment object (not just a base64 HTTP header), and `createA2APaymentHandler(gate)`
+  maps a gate onto Google's A2A JSON-RPC Task/Message metadata — **sharing one replay set with HTTP**.
+  Backendless, zero `@a2a` dependency. The parser cores `parseSignatureObject`/`parseExactObject` are now
+  exported. *(The A2A buyer, AP2 carriage, and the live-Google-interop emit-version finalization trail.)*
+- **feat(agent/mcp): an 8th tool — `piprail_verify_receipt`** (read-only, key-less) re-verifies a receipt
+  against the chain; `piprail_pay_request` now surfaces the `verifiableReceipt`.
+- **fix:** a batch of correctness hardening from an adversarial multi-agent audit — require the replay
+  store's `isUsed`/`markUsed` as a pair (a lone one silently disabled double-spend protection); the read
+  methods (`planPayment`/`canAfford`/`estimateCost`) degrade instead of throwing on a malformed accept;
+  Sui coin pagination; Stellar custom-asset decimals; Tron native safe-integer; and more.
+- **fix:** a second adversarial multi-agent conformance pass (vs the cloned x402 spec) hardened the new
+  surfaces — **upto cumulative caps are now merchant-proof:** the budget debits the authorized **MAX**
+  (a merchant that under-reports its settled `amount` can no longer loosen `maxTotal`/`maxTotalPerDenom`/
+  `windowTotal`); the metered actual is surfaced on `SpendRecord.settledBase`. The `upto` driver now
+  enforces **strict** `permitted.amount === advertised max` at verify time (an over-permit is rejected —
+  x402 `scheme_upto_evm` §Phase 3). `describe()` now projects the upto rail's mandatory
+  `extra.facilitatorAddress` (+ the exact rail's EIP-712 domain) so a discovered rail is reconstructable.
+  A2A conformance: a rejected proof re-challenges as `payment-rejected` (the spec status that pairs with
+  the retryable `input-required`, not the terminal `payment-failed`) carrying a failure receipt with
+  `network` + `transaction:''`. The agent guide + `paymentTools` JSDoc now document the upto rail and the
+  8th tool.
+- **fix:** a third verification pass (regression-focused) caught two **doc copy-paste bugs** that would
+  brick a user's code — the `upto` seller + Tier-2 receipt examples used the pre-v2 `{ privateKey }`
+  wallet field (which throws `WrongFamilyError`) instead of the unified `{ key }`. Also: the A2A
+  terminal-`failed` receipt now carries the attempted `network`; the A2A `fulfill` doc/example returns a
+  structurally valid artifact (`{ name, parts }`); the MCP config docs + registry `server.json` now list
+  `upto`; and a **regression test** locks the merchant-proof cumulative leash (a sequence of
+  under-reporting `upto` payments is refused by `maxTotal`/`maxTotalPerDenom`/`windowTotal`).
+- **fix:** a fourth, end-to-end pass (every flow traced hop-by-hop + a clean-room standards sign-off,
+  which came back **CONFORMANT on all four wire formats**, and a live MCP-pays-the-`upto`-rail proof)
+  found only doc-accuracy gaps + one low edge case: A2A failure receipts now attribute `network` from
+  the buyer's submitted payload (covering multi-network gates + v1-flat exact payloads), and the whole
+  docs-site is updated to the **8-tool** surface (the new `piprail_verify_receipt`) with the 2.10.0
+  receipts/upto/A2A APIs documented in the reference. No SDK behavior change beyond the A2A edge fix.
+
 ## [2.9.0] — 2026-06-19 — Cross-token grand total · payment-count caps · durable budget · richer spend observability
 
 Spend controls grow up — a single budget across every token and chain, caps on the *number* of

package/README.md

@@ -74,8 +74,9 @@ 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` · the `exact` rail |
+| **[Accepting payments](https://docs.piprail.com/accepting-payments/require-payment-and-gate/)** | `requirePayment` · `createPaymentGate` · the `exact` rail · the `upto` metered rail |
 | **[Making payments](https://docs.piprail.com/making-payments/piprail-client/)** | `PipRailClient` · `quote` · `estimateCost` · `planPayment` · auto-route · `MultiChainPayer` |
+| **[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 |
 | **[Discovery](https://docs.piprail.com/discovery/discover-and-register/)** | Find & be found on the open x402 indexes ($0, no backend) |

package/dist/chunk-3SBTJKAG.js

@@ -0,0 +1,92 @@
+// src/drivers/evm/receipt.ts
+import {
+  recoverTypedDataAddress,
+  getAddress
+} from "viem";
+var RECEIPT_DOMAIN = Object.freeze({
+  name: "x402 receipt",
+  version: "1",
+  chainId: 1
+});
+var RECEIPT_TYPES = Object.freeze({
+  Receipt: [
+    { name: "version", type: "uint256" },
+    { name: "network", type: "string" },
+    { name: "resourceUrl", type: "string" },
+    { name: "payer", type: "string" },
+    { name: "issuedAt", type: "uint256" },
+    { name: "transaction", type: "string" }
+  ]
+});
+var RECEIPT_PRIMARY_TYPE = "Receipt";
+function receiptMessage(input) {
+  return {
+    version: 1n,
+    network: input.network,
+    resourceUrl: input.resourceUrl,
+    payer: input.payer,
+    issuedAt: BigInt(input.issuedAt),
+    // §5.3: unused optional fields are the empty string in the SIGNED message, never omitted.
+    transaction: input.transaction ?? ""
+  };
+}
+async function signReceiptEvm(wallet, input) {
+  const adapter = wallet._native;
+  const account = adapter.account;
+  const walletClient = adapter.walletClient;
+  const signature = await walletClient.signTypedData({
+    account,
+    domain: RECEIPT_DOMAIN,
+    types: RECEIPT_TYPES,
+    primaryType: RECEIPT_PRIMARY_TYPE,
+    message: receiptMessage(input)
+  });
+  return {
+    format: "eip712",
+    signature,
+    // The address that actually produced the signature (the bound wallet). A
+    // verifier re-recovers + checks it equals the trusted `payTo`.
+    signer: account.address,
+    payload: {
+      version: 1,
+      network: input.network,
+      resourceUrl: input.resourceUrl,
+      payer: input.payer,
+      issuedAt: input.issuedAt,
+      transaction: input.transaction ?? ""
+    }
+  };
+}
+async function verifyReceiptAttestationEvm(input) {
+  try {
+    const recovered = await recoverTypedDataAddress({
+      domain: RECEIPT_DOMAIN,
+      types: RECEIPT_TYPES,
+      primaryType: RECEIPT_PRIMARY_TYPE,
+      message: receiptMessage(input),
+      signature: input.signature
+    });
+    let expected;
+    let actual;
+    try {
+      expected = getAddress(input.payTo);
+      actual = getAddress(recovered);
+    } catch {
+      return { ok: false, signer: recovered, reason: "bad-address" };
+    }
+    if (actual !== expected) {
+      return { ok: false, signer: recovered, reason: "signer-mismatch" };
+    }
+    return { ok: true, signer: recovered };
+  } catch {
+    return { ok: false, reason: "invalid-signature" };
+  }
+}
+
+export {
+  RECEIPT_DOMAIN,
+  RECEIPT_TYPES,
+  RECEIPT_PRIMARY_TYPE,
+  signReceiptEvm,
+  verifyReceiptAttestationEvm
+};

package/dist/chunk-CQQI5IJX.cjs

@@ -0,0 +1,92 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }// src/drivers/evm/receipt.ts
+
+
+
+var _viem = require('viem');
+var RECEIPT_DOMAIN = Object.freeze({
+  name: "x402 receipt",
+  version: "1",
+  chainId: 1
+});
+var RECEIPT_TYPES = Object.freeze({
+  Receipt: [
+    { name: "version", type: "uint256" },
+    { name: "network", type: "string" },
+    { name: "resourceUrl", type: "string" },
+    { name: "payer", type: "string" },
+    { name: "issuedAt", type: "uint256" },
+    { name: "transaction", type: "string" }
+  ]
+});
+var RECEIPT_PRIMARY_TYPE = "Receipt";
+function receiptMessage(input) {
+  return {
+    version: 1n,
+    network: input.network,
+    resourceUrl: input.resourceUrl,
+    payer: input.payer,
+    issuedAt: BigInt(input.issuedAt),
+    // §5.3: unused optional fields are the empty string in the SIGNED message, never omitted.
+    transaction: _nullishCoalesce(input.transaction, () => ( ""))
+  };
+}
+async function signReceiptEvm(wallet, input) {
+  const adapter = wallet._native;
+  const account = adapter.account;
+  const walletClient = adapter.walletClient;
+  const signature = await walletClient.signTypedData({
+    account,
+    domain: RECEIPT_DOMAIN,
+    types: RECEIPT_TYPES,
+    primaryType: RECEIPT_PRIMARY_TYPE,
+    message: receiptMessage(input)
+  });
+  return {
+    format: "eip712",
+    signature,
+    // The address that actually produced the signature (the bound wallet). A
+    // verifier re-recovers + checks it equals the trusted `payTo`.
+    signer: account.address,
+    payload: {
+      version: 1,
+      network: input.network,
+      resourceUrl: input.resourceUrl,
+      payer: input.payer,
+      issuedAt: input.issuedAt,
+      transaction: _nullishCoalesce(input.transaction, () => ( ""))
+    }
+  };
+}
+async function verifyReceiptAttestationEvm(input) {
+  try {
+    const recovered = await _viem.recoverTypedDataAddress.call(void 0, {
+      domain: RECEIPT_DOMAIN,
+      types: RECEIPT_TYPES,
+      primaryType: RECEIPT_PRIMARY_TYPE,
+      message: receiptMessage(input),
+      signature: input.signature
+    });
+    let expected;
+    let actual;
+    try {
+      expected = _viem.getAddress.call(void 0, input.payTo);
+      actual = _viem.getAddress.call(void 0, recovered);
+    } catch (e) {
+      return { ok: false, signer: recovered, reason: "bad-address" };
+    }
+    if (actual !== expected) {
+      return { ok: false, signer: recovered, reason: "signer-mismatch" };
+    }
+    return { ok: true, signer: recovered };
+  } catch (e2) {
+    return { ok: false, reason: "invalid-signature" };
+  }
+}
+
+
+
+
+
+
+
+exports.RECEIPT_DOMAIN = RECEIPT_DOMAIN; exports.RECEIPT_TYPES = RECEIPT_TYPES; exports.RECEIPT_PRIMARY_TYPE = RECEIPT_PRIMARY_TYPE; exports.signReceiptEvm = signReceiptEvm; exports.verifyReceiptAttestationEvm = verifyReceiptAttestationEvm;