@atumlabs/mppx-atum-escrow 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.4.0] - 2026-09-16
+
+### Changed
+- Clarified that the approval helpers raise an allowance and never lower one: a wallet already holding more than `approvalAmount` is left as it is and reports `alreadySufficient`. The wording said `approvalAmount` caps what the escrow can ever move, which is only true when no larger allowance already exists. Reducing or revoking an allowance is a separate operation these do not perform.
+- `ensureSourceApproval` refuses to send when the client that would sign is not the `owner` whose allowance it read. An approval only ever applies to the account that sends it, so a mismatched signer approved that account instead, returned a transaction hash that read as success, and left the owner exactly as unable to pay as before — a silent failure that surfaced only as a settlement revert. Read-only `needsSourceApproval` is unaffected: asking whether a payer is ready without holding their keys is a legitimate preflight, and a client that cannot report which account it signs as is not treated as a mismatch.
+- Tron approvals wait for confirmation before returning, so the hash they report means mined rather than broadcast — a payer that deposited immediately afterwards would otherwise race their own approval. The EVM path already waited; what is new there is a bound on how long it will wait (`confirmation.timeoutMs`, one minute by default) instead of waiting forever, and an `onSubmitted` callback that hands you the hash the moment it is broadcast so a stuck approval can still be looked up.
+- On EVM, `ensureSourceApproval` resets an allowance to zero before setting a new one, but only where the token demands it. Some tokens — mainnet USDT most notably — refuse to move an allowance straight from one non-zero value to another, so a payer holding any leftover allowance could not be approved at all and saw a bare on-chain revert. The check is a simulated call that costs nothing and sends nothing, and a wallet with no allowance skips it entirely, so an ordinary approval still takes exactly one transaction. Tron does not do this: an ordinary TRC-20 accepts the change in place, and guessing otherwise would burn an extra transaction at Tron's fee limit — if a Tron token ever does refuse, the error names the manual remedy.
+- The approval helpers are now one implementation shared by this package, the x402 scheme and the payment-gateway client, so the three cannot drift apart on what counts as a sufficient allowance. The exported names and their behaviour are unchanged.
+- `ChargeRequest` declares the Solana `issuedAt` on its `extra` itself, instead of inheriting it
+  from the shared x402 request type. That type dropped the field — an x402 resource server rebuilds
+  its payment requirements on the paid request and compares them against what the payer echoed, and
+  a clock reading cannot survive that comparison. MPP has no such rebuild, so a merchant-stamped
+  issue time stays valid here and `buildChargeRequest` still emits it exactly as before. Type-only:
+  the emitted JavaScript is byte-identical, so nothing changes at runtime and no code needs editing
+  on upgrade.
+- A destination identifier whose CAIP namespaces are not lowercase, such as `SOLANA:` or `SPL:`, is now accepted on Solana. Previously that chain compared the whole identifier byte for byte and refused it. CAIP pins both namespaces lowercase, so this only forgives a spelling the schema already treats as equivalent.
+
+### Added
+- **`isUnconfirmed`**, for telling a broadcast-but-unseen approval apart from one that failed. The wait for a confirmation is bounded, and reaching that bound is not a failure: the transaction may confirm a moment later. The two need opposite responses — a failure needs another approval, an unconfirmed one needs the transaction checked and nothing else — and a caller that treats them alike pays for an allowance they are already getting. Previously the distinction existed only as an undocumented property on the error.
+- **`needsSourceApproval`**, the read-only counterpart to `ensureSourceApproval`. It takes the same arguments and answers the same question, but only reads the allowance: no transaction, no gas. Use it to tell a payer that a one-off approval is due before asking them to sign, instead of letting them find out when one is broadcast.
+- **`ensureSourceApproval` now works on Tron.** It previously documented Tron support it did not have — the implementation reached the chain through ethers, which cannot talk to Tron, so a Tron source failed either for want of a `spender` or somewhere inside ethers. Pass a TronWeb instance as `tronWeb` in place of the ethers `signer`, and the Permit2 address for the network is resolved for you rather than demanded as `spender`. `tronweb` is not a dependency of this package; the caller constructs the instance, exactly as they already construct the ethers signer.
+- **`approvalAmount`**, for granting a bounded approval instead of an unlimited one, capping what the escrow can ever move. On its own the amount is its own requirement, so an allowance still holding the full bound is left alone rather than re-approved — the right answer for a one-off approval. Across repeated payments, pair it with `requiredAllowance`: a bound measured against itself stops covering itself the moment the first charge is decremented from it, and every later call would send another approval. The trade-off to weigh is that Permit2 decrements the allowance on every payment, so a bounded approval is consumed and eventually has to be granted again. Asking to approve less than an explicit `requiredAllowance` is refused outright, since that approval could never satisfy the charge it was granted for.
+- `AtumEscrowServer`, the type `registerServer` returns, for naming the method where it is built in one place and registered in another. Its `verify()` now resolves with an `AtumEscrowReceipt`, so `fulfillmentConfirmation` is available directly on the result: any cast you added to reach it can be removed. Casts already in place continue to compile, so this needs no change on upgrade.
+
+### Fixed
+- **`ensureSourceApproval` no longer sends a fresh approval before every payment after the first.** Permit2 decrements the payer's allowance on each transfer it makes, so an allowance granted as unlimited stops being exactly `MaxUint256` the moment the first payment settles. Sufficiency was measured against that exact value, so from the second payment onward the check never short-circuited again and every charge was preceded by another approval transaction. The payments were correct; the payer was buying an allowance they already held. Sufficiency is now measured against half of `MaxUint256`, which separates an unlimited approval that has been partly spent from one a payer bounded deliberately — crossing that floor would take more token units than any supply contains. Nothing changes for a caller passing `requiredAllowance`: that comparison was already right, and only the unlimited case was wrong.
+- A payer whose `signer` option carries a blank `pinnedAddress` falls back to the payer's own account. Blank covers an empty string, which is how an unset variable arrives, and a whitespace only value, which is how one read from a file or a padded shell variable arrives. It previously passed the value straight through, which the payment-gateway client now refuses instead of reading as "no pin", and the two blank forms took different paths.
+- `verify()` compares the payer's destination asset identifier against the merchant's advertised one part by part, instead of lowercasing the whole string for every chain except Solana. A Tron `trc20:` reference is base58, where capitalisation is part of the value, so the old fold treated two distinct tokens as the same one on a field the deposit signature does not cover. The token reference and a Solana chain reference are now compared the way the neighbouring address comparison already documented, and only the two CAIP namespaces fold.
+
+## [0.3.0] - 2026-07-30
+
+### Added
+- `buildChargeChallenge(corridor, select, fulfillmentAmount, { intentId })` — the merchant-side entry point for building a charge challenge. It pairs the payment terms with a per-purchase identifier (your order or invoice id), which is what makes a retry of that purchase resolve to the original payment instead of becoming a second charge. It travels in challenge metadata under `INTENT_ID_META_KEY`.
+- `SettlementPendingError`, `SettlementFailedError`, and `PaymentRejectedError`, with `isSettlementPending` / `isSettlementFailed` / `isPaymentRejected` guards. A payment that has not settled is no longer reported as a single undifferentiated failure: pending means retrying the same purchase is safe and is how the result is collected, while a terminal failure means that purchase can never settle and recovery requires a new one. Both settlement errors carry the gateway's `paymentId` — as its own field on `toProblemDetails()` (and `SettlementFailedError` also carries `state`), not only interpolated into the message text, so a payer reading the wire response can reconcile the attempt without parsing a sentence.
+- `PaymentSubmitResult.status`, so a submitter can pass the gateway's lifecycle state through. An absent status is read as pending.
+
+### Fixed
+- The payer's `signer` option now accepts Turnkey provider config (`{ provider: "turnkey", ... }`) as documented by its type, instead of throwing and directing you to construct a `TurnkeySenderSigner` yourself and pass it as a ready-made signer. Both paths now behave the same way; the ready-made-signer path still works unchanged.
+- A credential presented after its quote window has closed now fails with a typed `PaymentActionRequiredError` (the same type `SettlementPendingError` carries) instead of a plain `Error`. mppx's request-routing layer replaces any thrown value that is not a recognized payment error with a generic "Payment verification failed." before it reaches the wire, which was silently erasing the "re-attempt with a fresh challenge" guidance for every real HTTP payer — only a merchant calling `verify()` directly in-process ever saw it. The message is unchanged; only its wire-visible type is fixed, so a payer's retry loop can now correctly recognize this as the same "fetch a fresh challenge and continue" outcome as a pending settlement.
+
+### Changed
+- **Breaking:** the payment's identity is now derived from the challenge's per-purchase identifier rather than from the challenge id. The challenge id is an HMAC over the challenge's own contents, so it moved whenever the expiry or the quote moved: under a rolling `expires` every retry derived a fresh identity and was charged as a new payment, and with no `expires` or metadata at all two distinct purchases with identical terms collapsed onto one payment, leaving the second unpaid. Merchants now stamp `intentId` (via `buildChargeChallenge`); a challenge without one is refused by the payer's client rather than paid unsafely.
+  - **If your integration sets `challenge.opaque` yourself** (the pre-0.3.0 way to carry your own correlation data), note that it silently overrides the `meta` this relies on for `intentId` — the mppx framework only serializes `meta` into `opaque` when nothing has already set `opaque`. Move your own data onto extra keys of the same `meta` object `buildChargeChallenge` returns instead. See the README's "Quick start — merchant" section.
+- A `PaymentSubmitter` should submit and return the gateway's response rather than polling for completion — the payer's retry is what collects a pending result. Polling holds the merchant's request open for the whole settlement window and hides the pending state that makes the retry safe.
+- **Re-attempting a purchase is now spelled out**, in `SettlementPendingError`'s own message and in the README: request a fresh challenge and sign it again, keeping the same `intentId`. "Retry the same purchase" was ambiguous, and the reading it invited does not work — `quote_deadline` and `fulfillment_deadline` are absolute timestamps fixed when the challenge is built, so a credential that has already been signed cannot be presented a second time once its quote window has closed. On Solana the deposit authorization additionally carries its own on-chain replay window, which expires with them.
+- An authorization whose quote window has closed is now reported separately from deadlines that are in the wrong order. They were one message, and they need opposite responses: the first is fixed by re-running the purchase, the second is a malformed request that no passage of time will make valid. The stale case now names the remedy, including which field must not change.
+
 ## [0.2.2] - 2026-07-31
 
 ### Changed

package/README.md

@@ -6,6 +6,7 @@
 
 An [`mppx`](https://www.npmjs.com/package/mppx) payment method that lets a merchant accept
 **cross-chain stablecoin payments** through Atum, over the Machine Payments Protocol (MPP).
+Full documentation: [docs.atum.xyz](https://docs.atum.xyz).
 
 - The **payer** funds the payment in any supported source asset and chain (e.g. USDC on Base,
   USDT on Tron, or USDC on Solana).
@@ -48,12 +49,15 @@ Payer (client)              Merchant (server)              Atum Payment Gateway
 
 1. The merchant answers a request with a `402` **challenge** describing what it receives
    (destination asset, chain, exact amount) and the source option a payer may fund from. You build
-   this challenge from a **corridor** with `buildChargeRequest`.
+   this challenge from a **corridor** with `buildChargeChallenge`.
 2. The payer's `registerClient` reads the challenge, builds an Atum payment request, signs the
    source-chain deposit authorization for that chain, and returns it as an MPP **credential**.
 3. The merchant's `registerServer` **verifies** the credential (recovers the signature, matches
-   every term against the challenge) and **submits** it to the Atum Payment Gateway, blocking until
-   settlement completes. On success it returns a **receipt** carrying the settlement confirmation.
+   every term against the challenge) and **submits** it to the Atum Payment Gateway. Once the
+   payment settles it returns a **receipt** carrying the settlement confirmation. A payment that
+   settles more slowly than the gateway's synchronous window reports as *pending*, and the payer's
+   retry of the same purchase collects the result — see
+   [Settlement outcomes](#settlement-outcomes).
 
 The source-chain authorization is built and signed through the Atum
 [`@atumlabs/payment-gateway-client`](https://www.npmjs.com/package/@atumlabs/payment-gateway-client),
@@ -78,9 +82,6 @@ The merchant examples below also use
 [`@atumlabs/payment-gateway-client`](https://www.npmjs.com/package/@atumlabs/payment-gateway-client)
 for the gateway connection and corridor defaults.
 
-> The snippets below are illustrative. For complete, runnable, end-to-end integrations
-> (payer + merchant), see the examples repository: **https://github.com/Atum-Labs/examples**.
-
 ## Key concepts
 
 | Term | What it means |
@@ -92,11 +93,24 @@ for the gateway connection and corridor defaults.
 | **Escrow** | The source-chain contract the payer's funds lock into until the merchant is paid. |
 | **Deadlines** | Two budgets in seconds: `quoteDeadlineSeconds` (how long the auction runs) and `fulfillmentDeadlineSeconds` (how long settlement may take). Required order: `now < quote < fulfillment`. |
 | **`PaymentSubmitter`** | A small adapter *you* provide that hands a signed payment request to the Atum Payment Gateway and returns the result. |
+| **`intentId`** | Identifies the *purchase* (your order or invoice id): one value per purchase, reused on every retry of it. The payment's identity derives from it, so it is what makes a retry safe. |
 | **Receipt** | What `verify()` returns on success: the MPP receipt plus the full settlement confirmation. |
 
 All addresses and amounts are strings; all amounts are **atomic units** (never floats). Addresses
 are in each chain's native form — `0x…` hex for EVM, base58 for Tron and Solana.
 
+### Which chains and assets can a corridor use?
+
+Atum supports many corridors. The identifier for every supported token is listed under
+[supported assets](https://docs.atum.xyz/get-started/reference/supported-assets), and the chain ids
+under [supported networks](https://docs.atum.xyz/get-started/reference/supported-networks). Assets
+are named with [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) identifiers, for example
+`eip155:84532/erc20:0x036CbD53842c5426634e7929541eC2318f3dCF7e` for USDC on Base Sepolia.
+
+Copy identifiers exactly: base58 values, such as Solana token mints and account addresses, are
+case-sensitive. The escrow and role addresses for each chain are filled in by
+`corridorFromDefaults`, so you never paste those by hand.
+
 ## Quick start — merchant (server)
 
 ```ts
@@ -104,7 +118,7 @@ import { Mppx } from "mppx/server";
 import { PaymentGatewayClient } from "@atumlabs/payment-gateway-client";
 import {
   registerServer,
-  buildChargeRequest,
+  buildChargeChallenge,
   corridorFromDefaults,
   type AtumEscrowCorridor,
   type PaymentSubmitter,
@@ -141,11 +155,14 @@ const corridor: AtumEscrowCorridor = await corridorFromDefaults(gateway, {
 // You can also build a corridor by hand if you already hold the addresses — see AtumEscrowCorridor.
 
 // 2. Provide the gateway adapter. The gateway response maps 1:1 onto what the method needs.
+//    Pass `status` through: it is what distinguishes a payment still settling from one that
+//    failed. Submit and return — do not poll for completion (see "Settlement outcomes").
 const submitter: PaymentSubmitter = {
   async submit(request) {
     const res = await gateway.payments.submitPayment({ requestBody: request });
     return {
       payment_id: res.payment_id,
+      status: res.status,
       fulfillment_confirmation: res.fulfillment_confirmation,
     };
   },
@@ -160,20 +177,27 @@ const mppx = Mppx.create({
   methods: [method],
 });
 
-// 4. Guard a route. buildChargeRequest turns your corridor + a chosen source + the price into
+// 4. Guard a route. buildChargeChallenge turns your corridor + a chosen source + the price into
 //    the challenge. Set the price per charge, so one corridor serves any amount.
 app.get("/paid-resource", async (req) => {
-  const request = buildChargeRequest(
+  const { request, meta } = buildChargeChallenge(
     corridor,
     { network: "eip155:8453", asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, // offer Base USDC
     "10000000", // receive exactly 10 USDC
+    // Identifies the purchase, NOT the attempt: the same value every time this order is
+    // re-offered or retried, a different one for a new order. See "Retries and idempotency".
+    { intentId: orderIdFor(req) },
   );
-  const result = await mppx.compose(["atum-escrow/charge", request])(req);
+  const result = await mppx.compose(["atum-escrow/charge", { ...request, meta }])(req);
   if (result.status === 402) return result.challenge; // not paid yet — ask for payment
   return result.withReceipt(new Response("here is your resource")); // paid & settled
 });
 ```
 
+> Before production: `mppx.fetch`/a single `verify()` call is enough for this quickstart, but not
+> for a corridor whose settlement can genuinely take minutes — see
+> [Settlement outcomes](#settlement-outcomes) for handling that without polling.
+
 ## Quick start — payer (client)
 
 ```ts
@@ -182,6 +206,7 @@ import { registerClient } from "@atumlabs/mppx-atum-escrow/client";
 
 // The signer is chain-agnostic: pass private-key options (bound to the challenge's source chain
 // automatically) or a ready-made SenderSigner. `account` is your source-chain address.
+// Use a TESTNET-ONLY wallet for PAYER_PRIVATE_KEY while trying this out — never one holding real funds.
 const method = registerClient({
   signer: { privateKey: process.env.PAYER_PRIVATE_KEY! },
   account: process.env.PAYER_ADDRESS!,
@@ -194,6 +219,10 @@ const res = await mppx.fetch("https://api.example.com/paid-resource");
 const resource = await res.text();
 ```
 
+> Before production: `mppx.fetch` retries only a few times with no delay, which isn't enough for a
+> corridor whose settlement can genuinely take minutes — see
+> [Settlement outcomes](#settlement-outcomes) for the retry pattern that handles it.
+
 ### Approving the source token
 
 On EVM and Tron, the payer must approve the token-transfer contract (Permit2) to move the source
@@ -212,11 +241,66 @@ await ensureSourceApproval({
   owner: wallet.address,
   signer: wallet,
   // Pass the source cap this charge needs (from the challenge). A leftover smaller allowance
-  // then won't be mistaken for enough. Omit it to ensure an unlimited approval instead.
+  // then won't be mistaken for enough.
   requiredAllowance: BigInt(challenge.request.source.amount),
 });
 ```
 
+Paying from Tron takes a TronWeb instance instead of an ethers signer; everything else is the
+same, and the Permit2 address for the network is resolved for you:
+
+```ts
+await ensureSourceApproval({ network: "tron:mainnet", token, owner, tronWeb });
+```
+
+The approval waits to be mined before returning, bounded by `confirmation.timeoutMs` (one minute
+by default); a timeout is reported as unconfirmed rather than failed, since the transaction may
+still land. `onSubmitted` hands you the hash the moment it is broadcast.
+
+`isUnconfirmed(error)` tells the two apart. It matters because the responses are opposite: a
+failed approval needs another one, an unconfirmed approval needs a look at the transaction and
+nothing else. Sending a second one on top of the first only pays for an allowance you are already
+getting.
+
+```ts
+try {
+  await ensureSourceApproval({ network, token, owner, signer });
+} catch (error) {
+  if (isUnconfirmed(error)) {
+    // Broadcast, not yet seen to confirm. Check the hash from onSubmitted; do not re-send.
+  } else {
+    throw error;
+  }
+}
+```
+
+On EVM, tokens that refuse to overwrite a non-zero allowance — mainnet USDT most notably — are
+reset to zero first, automatically and only where the token demands it; the result then carries a
+`resetTxHash` too. Tron does not do this, because an ordinary TRC-20 accepts the change in place.
+
+The approval sent is unlimited, so later charges on the same token need no further transaction.
+To bound the approval that gets sent, pass `approvalAmount`. On its own the amount is treated as
+its own requirement, so an allowance still holding the full bound is left alone rather than
+re-approved — the right answer for a one-off approval. Across repeated payments, pair it with
+`requiredAllowance`: Permit2 decrements the allowance on every payment, so a bound measured
+against itself stops covering itself the moment the first charge lands, and every later call
+would send another approval. Either way a bounded approval is consumed as it is spent and
+eventually has to be granted again.
+
+These helpers raise an allowance to what a payment needs; they never lower one. A wallet already
+holding more than `approvalAmount` is left exactly as it is and reports `alreadySufficient`
+without sending anything. Reducing or revoking an allowance is a separate operation, and not one
+these perform.
+
+`needsSourceApproval(params)` takes the same arguments and answers the same question without
+sending anything, so it is safe to call before every charge:
+
+```ts
+if (await needsSourceApproval({ network, token, owner, signer })) {
+  // tell the payer a one-off approval transaction is coming, before asking them to sign
+}
+```
+
 ## What the merchant `verify()` guarantees
 
 `verify()` fails fast (no chain I/O) before submitting, and throws if any check fails. The Atum
@@ -255,44 +339,187 @@ On success you get an `AtumEscrowReceipt` — the MPP receipt plus the full sett
 }
 ```
 
+`verify()` resolves with this type, so `fulfillmentConfirmation` is available straight off the
+result. `AtumEscrowReceipt` is exported, so you can name it in your own function signatures.
+
 ## Retries and idempotency
 
-Two layers protect a retry, and they protect **different** things:
-
-1. **Build once, resubmit identical bytes — returns the original result.** `mppx.fetch` builds one
-   credential per payment and reuses it across its automatic retries, so the gateway sees identical
-   content, deduplicates, and returns the *original* result (including the receipt). This is the
-   only layer that gives you a graceful retry. Driving the flow manually, do the same — never
-   rebuild for a retry.
-2. **Deterministic nonce — charge-safe, but not retry-graceful.** For EVM and Tron sources the
-   deposit nonce and `request_id` are derived from the challenge id, so even a rebuild for the
-   *same* challenge reuses the same nonce; the escrow consumes a nonce on the first deposit and
-   reverts any second, so **at most one payment ever settles on-chain**. This is only
-   *charge-safety*: a rebuild's deadlines are wall-clock, so its content differs and the gateway
-   does not recognize it as the original — use layer 1 to get the original receipt back. Solana
-   sources use a replay-window nonce and rely on the gateway's content-keyed dedup (the request id,
-   and thus the payment id, are still derived deterministically from the challenge id).
-
-Layer 2 holds only if the challenge id is **stable across retries of one payment intent and unique
-across distinct intents**, and the merchant controls that. With `Mppx.create({ secretKey })` the
-challenge id is an HMAC over the challenge contents — including `opaque` and `expires` — so:
-
-- set **`opaque` to a per-intent identifier** (e.g. your order or invoice id), reused if that same
-  intent is retried; and
-- keep **`expires` stable or absent** per intent — a floating `now() + TTL` changes the id on every
-  `402` and defeats the anchor.
-
-Anchoring on a per-intent `opaque` (rather than the payment *terms*) is deliberate: two legitimate
-identical purchases must get **different** nonces, which distinct order ids provide. Without a
-`secretKey`, or with a per-request-random challenge id, only layer 1 protects you — so build once.
+A retry must never become a second charge, and two different purchases must never collapse into
+one. Both come down to a single value: the **per-purchase identifier** the merchant stamps into the
+challenge.
+
+```ts
+const { request, meta } = buildChargeChallenge(corridor, source, amount, {
+  intentId: order.id, // ← identifies the purchase
+})
+```
+
+The payer derives the payment's `request_id` from `intentId`, and the gateway de-duplicates on that
+`request_id`. So the identifier's lifetime *is* the definition of "the same payment":
+
+- **one value per purchase** — a value shared by two purchases makes the second resolve onto the
+  first and go unpaid (see the merchant-side defence below);
+- **the same value on every retry** of that purchase, including every re-issued `402` for it — a
+  value that changes per attempt makes each retry a fresh charge;
+- **never derived from the terms** — two orders for the same item have identical terms and must
+  still be two payments.
+
+Use the merchant's own order, invoice, or cart id. Notably it is *not* the challenge id: that is an
+HMAC over the challenge's own contents, so it moves whenever the expiry or the quote moves, neither
+of which tracks the purchase.
+
+A challenge carrying no identifier is **refused** by the payer's client rather than paid. There is
+no fallback, deliberately: a per-attempt value would look like an idempotency key while letting
+every retry be charged again.
+
+On top of that, EVM and Tron sources get an on-chain backstop — the deposit nonce is derived from
+the same identifier, and the escrow reverts a second deposit reusing it. Solana's replay nonce only
+guards a short window, so there the gateway's `request_id` de-duplication is the durable protection.
+
+### The merchant-side defence, and why you want it
+
+Nothing can detect an identifier reused across two genuine purchases — the identifier *is* the
+identity, so the second purchase resolves onto the first payment and only one payment is made. As the
+merchant, you can close that on your own side.
+
+Both purchases resolve to the **same payment**, so `verify()` hands you the **same receipt** for
+both — the same `paymentId` and the same destination transaction. Key fulfilment on the receipt
+rather than on the incoming request, and the second purchase is recognised as already-fulfilled
+instead of being shipped a second time against a single payment.
+
+Treat this as your responsibility rather than the network's: `atum-escrow` guarantees you will not be
+paid twice for one identifier, and receipt-keyed fulfilment is how you avoid *delivering* twice for
+one.
+
+### Reusing an identifier with different terms
+
+The gateway rejects a purchase identifier that comes back with different economics — who pays, who
+receives, in which assets, or for how much — instead of silently resolving it to the first payment.
+Surface it as a `PaymentRejectedError` from your submitter and the payer sees the cause; the fix is
+always a distinct identifier per purchase.
+
+## Settlement outcomes
+
+A payment that settles returns a receipt. A payment that does not settle within the gateway's
+synchronous window is **not** a failure, and the two are distinguished because they call for
+opposite responses:
+
+| `verify()` outcome | Meaning | What the payer should do |
+| --- | --- | --- |
+| receipt | settled | nothing — the resource is served |
+| `SettlementPendingError` | accepted, still settling | re-attempt the **same** purchase; it resolves to this payment and returns its result |
+| `SettlementFailedError` | terminal failure | start a **new** purchase under a new identifier — this one can never settle |
+| `PaymentRejectedError` | refused, nothing charged | fix the request and pay the same purchase again |
+
+The pending and failed rows call for **opposite** actions, and the reason is worth stating: a
+terminal failure keeps its identifier. The gateway does not release it, so re-attempting that
+purchase under the same `intentId` resolves to the same dead payment for good — which is exactly what
+you want for a pending payment and exactly what you must not do after a terminal one. Recovering from
+a terminal failure therefore means minting a **new** `intentId`; it is a new purchase as far as the
+network is concerned. Getting these two the wrong way round is how a payer either charges twice or
+waits forever.
+
+### What re-attempting a purchase means
+
+Run the purchase again: request a fresh challenge, sign it again, and keep the **same `intentId`**.
+
+That split — rebuild the authorization, reuse the identifier — is the whole contract, and each half
+matters for a different reason. The `intentId` must not change because the payment's identity derives
+from it; change it and the re-attempt is a second charge rather than a retry. Everything time-bound
+must change because `quote_deadline` and `fulfillment_deadline` are **absolute timestamps**, fixed at
+the moment the challenge was built.
+
+So a credential you have already signed cannot simply be presented a second time. Once its quote
+window has closed, `verify()` refuses it and says so — and on Solana it is worse than a policy
+refusal, because the deposit authorization carries its own on-chain replay window that expires along
+with the deadlines.
+
+A payment-enabled `fetch` handles the rebuild-and-resubmit mechanics for you, since every attempt
+fetches a new challenge — but its own retry loop is a fixed, short number of attempts with no delay
+between them (3, by default; configurable via `maxPaymentRetries`, but that only changes how many
+times it hammers the endpoint, not how long it waits). That is enough when settlement finishes almost
+immediately, but not for a corridor that can genuinely take minutes: raising `maxPaymentRetries`
+turns "retry a few times" into "retry rapidly, still for no longer," which is not the same thing as
+waiting for settlement. For that, drive the retry yourself, with a real interval between attempts.
+
+The example below is a *payer* driving a *merchant* over real HTTP — two separate processes, not two
+functions called back to back — since that is the case `mppx.fetch` does not cover and this package
+provides no shortcut for. `method.createCredential` (payer) and the merchant's own endpoint are on
+opposite ends of the request; nothing here runs the merchant's `verify()` in the payer's process.
+
+```ts
+import { Transport } from "mppx/client";
+import type { AtumEscrowChallenge } from "@atumlabs/mppx-atum-escrow/client";
+
+// `method` is the client from "Quick start — payer" above. The merchant is what keeps `intentId`
+// stable across attempts (it must derive the same value from the order on every request); the
+// payer never supplies or sees it directly, only the challenge that already carries it.
+const transport = Transport.http();
+
+for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+  // 1. Ask for the resource. The merchant answers 402 with a fresh challenge.
+  const firstResponse = await fetch(url);
+  if (!(await transport.isPaymentRequired(firstResponse))) return firstResponse; // free, or already paid
+
+  // 2. Build and sign a payment for THIS challenge. The challenge arrives off the wire, so confirm
+  //    it is this scheme's before signing against it — a bare cast would sign whatever the
+  //    response contained. Each attempt re-signs — a full round trip for a Turnkey/KMS signer — so
+  //    pick an interval below with that cost in mind, not one copied from a lightweight status poller.
+  const offered = await transport.getChallenge(firstResponse);
+  if (offered.method !== "atum-escrow" || offered.intent !== "charge") {
+    throw new Error(`unexpected challenge ${offered.method}.${offered.intent}`);
+  }
+  const challenge = offered as AtumEscrowChallenge;
+  const credential = await method.createCredential({ challenge });
+
+  // 3. Resubmit with the credential attached. `response.ok` (200) is the only success case — a
+  //    non-402 failure (e.g. PaymentRejectedError, a 400) is neither settled nor a fresh challenge
+  //    to retry, so check for it explicitly rather than falling into the pending/failed handling
+  //    below, which assumes a 402.
+  const response = await fetch(url, transport.setCredential({}, credential, { challenge }));
+  if (response.ok) return response; // paid & settled
+  if (!(await transport.isPaymentRequired(response))) {
+    const problem = await response.json();
+    throw new Error(problem.detail ?? `request failed with ${response.status}`);
+  }
+
+  // Pending and failed are BOTH a 402 — the wire-visible discriminator is the problem-details
+  // `type`, which the mppx framework's error classes fix per outcome (see isSettlementPending /
+  // isSettlementFailed below for the merchant-side equivalent check). `paymentId` is its own
+  // field too, not just interpolated into `detail`'s prose, so the payer can log/reconcile it
+  // without parsing a sentence.
+  const problem = await response.json();
+  if (problem.type !== "https://paymentauth.org/problems/payment-action-required") {
+    throw new Error(problem.detail); // terminal — a new purchase needs a new intentId
+  }
+  // `payment-action-required` covers two different causes: a payment genuinely still settling
+  // (paymentId present — it reached the gateway) and this attempt's authorization having gone
+  // stale before it could be submitted (paymentId absent — nothing reached the gateway yet). Log
+  // accordingly rather than always saying "still settling", which is only true of the first.
+  console.log(
+    `attempt ${attempt}: ${problem.paymentId ? `still settling (payment ${problem.paymentId})` : "authorization expired before submission, retrying with a fresh one"}`,
+  );
+  await sleep(interval);
+}
+throw new Error(`purchase never settled after ${maxAttempts} attempts`);
+```
+
+Both settlement errors carry the gateway's `paymentId` for reconciliation — as its own field on
+`toProblemDetails()`, not only interpolated into `detail`'s prose — and both extend the framework's
+error types, so a merchant that does not distinguish them still gets the standard `402` +
+problem-details response. A same-process merchant discriminates with `isSettlementPending` /
+`isSettlementFailed` / `isPaymentRejected` on the thrown error object; a payer, receiving only the
+wire response, discriminates on `type` as shown above.
+
+Because the payer's retry is what collects a pending result, a `PaymentSubmitter` should submit and
+return what the gateway said — **not** poll for completion. Polling holds the merchant's request
+open for the whole settlement window and hides the pending state the retry depends on.
 
 ## Scope
 
 This version supports the **`charge`** intent with **EVM, Tron, and Solana** source chains and a
-merchant-configured destination chain, with **synchronous** settlement (the request is held open
-until settlement completes, so your client and server timeouts must exceed the corridor's deadline
-budgets). One source option is offered per challenge; a corridor may list several and offer a
-different one per `402`.
+merchant-configured destination chain. One source option is offered per challenge; a corridor may
+list several and offer a different one per `402`.
 
 > **Solana deadline constraint:** a Solana deposit authorization expires within the escrow's fixed
 > on-chain replay window (~2 minutes), independent of the corridor budget. So a corridor that
@@ -306,27 +533,41 @@ Import everything from the root, or from the role-specific entry points (which e
 each side needs):
 
 - `@atumlabs/mppx-atum-escrow` — everything below
-- `@atumlabs/mppx-atum-escrow/client` — `registerClient`, `ensureSourceApproval` + payer types
-- `@atumlabs/mppx-atum-escrow/server` — `registerServer`, `buildChargeRequest`,
-  `validateCorridor`, `corridorFromDefaults` + merchant types
+- `@atumlabs/mppx-atum-escrow/client` — `registerClient`, `ensureSourceApproval`, `needsSourceApproval` + payer types
+- `@atumlabs/mppx-atum-escrow/server` — `registerServer`, `buildChargeChallenge`,
+  `buildChargeRequest`, `validateCorridor`, `corridorFromDefaults`, the settlement errors +
+  merchant types
 
 | Export | Description |
 | --- | --- |
 | `registerClient(config)` | Payer-side method. `config`: `{ signer, account, now?, solanaClockReader? }`. |
-| `registerServer(config)` | Merchant-side method. `config`: `{ submitter, now? }`. |
-| `buildChargeRequest(corridor, select, fulfillmentAmount)` | Builds the `charge` challenge request for one source option, at a per-charge price. Throws if `select` matches no configured source. |
-| `validateCorridor(corridor)` | Validates a corridor's shape and per-source addresses (run automatically by `buildChargeRequest`). |
+| `registerServer(config)` | Merchant-side method. `config`: `{ submitter, now? }`. Returns an `AtumEscrowServer`, whose `verify()` resolves with an `AtumEscrowReceipt`. |
+| `buildChargeChallenge(corridor, select, fulfillmentAmount, { intentId, issuedAt? })` | Builds a `charge` challenge — the payment terms plus the per-purchase identifier that makes a retry safe. **Use this.** Returns `{ request, meta }`. |
+| `buildChargeRequest(corridor, select, fulfillmentAmount, options?)` | The payment terms alone, without the identifier. For supplying challenge metadata by hand. |
+| `validateCorridor(corridor)` | Validates a corridor's shape and per-source addresses (run automatically by both builders). |
 | `corridorFromDefaults(defaults, params)` | Builds a corridor by fetching escrow/role/proxy addresses from the gateway `/defaults`. |
-| `ensureSourceApproval(params)` | Ensures the payer has approved Permit2 to move the source token (EVM/Tron; no-op on Solana). |
+| `ensureSourceApproval(params)` | Ensures the payer has approved Permit2 to move the source token. `signer` for EVM, `tronWeb` for Tron; no-op on Solana. |
+| `needsSourceApproval(params)` | Whether `ensureSourceApproval` would send a transaction. Read-only, spends no gas. |
+| `SettlementPendingError`, `SettlementFailedError`, `PaymentRejectedError` | The non-receipt outcomes of `verify()`. See [Settlement outcomes](#settlement-outcomes). |
+| `isSettlementPending`, `isSettlementFailed`, `isPaymentRejected` | Guards for the above. |
 | `atumEscrowChargeMethod` | The base `mppx` method (advanced/custom wiring). |
 | `ChargeRequestSchema`, `CredentialPayloadSchema` | The `zod` wire schemas. |
 | `METHOD_NAME` (`"atum-escrow"`), `INTENT` (`"charge"`) | The method/intent identifiers. |
+| `INTENT_ID_META_KEY` | The challenge-metadata key carrying the per-purchase identifier. |
 
 Key types: `AtumEscrowCorridor`, `AtumEscrowSource`, `SenderSigner`, `SenderSignerOptions`,
-`PaymentSubmitter`, `AtumEscrowClientConfig`, `AtumEscrowServerConfig`, `ChainDefaultsSource`,
-`EnsureApprovalResult`, `AtumEscrowChallenge`, `AtumEscrowCredential`, `AtumEscrowReceipt`,
-`ChargeRequest`, `PaymentRequest`, `FulfillmentConfirmation`.
+`PaymentSubmitter`, `PaymentSubmitResult`, `PaymentSettlementStatus`, `AtumEscrowClientConfig`,
+`AtumEscrowServer`, `AtumEscrowServerConfig`, `ChainDefaultsSource`, `EnsureApprovalResult`,
+`AtumEscrowChallenge`, `AtumEscrowCredential`, `AtumEscrowReceipt`, `ChargeChallenge`, `ChargeRequest`,
+`SettlementErrorDetails`, `PaymentRequest`, `FulfillmentConfirmation`.
 
 > **EVM implementation note:** on EVM the deposit authorization is a Permit2
 > `PermitWitnessTransferFrom` signature; Tron uses the equivalent TIP-712 typed data, and Solana
 > uses an ed25519-signed deposit. The public API is the same across all three.
+
+## Further reading
+
+- [Accepting and making MPP payments with Atum](https://docs.atum.xyz/payment-protocols/mpp/overview)
+- [Supported assets](https://docs.atum.xyz/get-started/reference/supported-assets) and [supported networks](https://docs.atum.xyz/get-started/reference/supported-networks)
+- [MPP](https://mpp.dev)
+- [Atum documentation](https://docs.atum.xyz)

package/THIRD-PARTY-NOTICES.txt

@@ -2,6 +2,13 @@ THIRD-PARTY SOFTWARE NOTICES AND INFORMATION
 ==============================================================================
 @atumlabs/mppx-atum-escrow
 
+@atumlabs/mppx-atum-escrow is proprietary software, governed by the license
+agreement in the package-root LICENSE file. THIS file is not that license. This
+package includes the third-party software identified below; the licenses and
+notices reproduced here apply only to those third-party components. They do not
+modify the proprietary license governing this package or any Atum-authored code,
+and they do not make it open source.
+
 The published artifact of this package (the compiled code under dist/) statically
 bundles the third-party open-source components listed below; their source is
 redistributed within this package, so their license and copyright notices are