@atumlabs/mppx-atum-escrow 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+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).
+
+## [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
+- README: the proprietary-license notice now references the bundled `LICENSE` file by name instead of linking to it, so it no longer points at a repository that is not publicly shared.
+
+## [0.2.1] - 2026-07-27
+
+### Changed
+- Building and signing the payer's deposit authorization now runs entirely through the shared `@atum-labs/payment-request-sender-auth` library (via the updated `@atum-labs/payment-gateway-client`): the deposit nonce is derived deterministically from the charge identity (retry-safe) and the EVM/Tron permit deadline tracks the settlement horizon. No public API changes; the idempotency anchor is byte-identical.
+- Deposit-freshness verification (permit deadline) now uses the merchant's configured clock, consistent with the existing deadline-ordering and budget checks, instead of the wall clock.
+
+## [0.2.0] - 2026-07-24
+
+### Changed
+- Verifying the payer's deposit authorization (`sender_auth`) now delegates to the shared `@atum-labs/payment-request-sender-auth` library instead of an embedded copy of the recover-and-verify logic, keeping the escrow method byte-compatible with the rest of the Atum payment stack.
+
+## [0.1.1] - 2026-07-22
+
+### Changed
+- Packaging for standalone publication: externalized `@solana/web3.js` so the LGPL-licensed `rpc-websockets` (pulled in transitively) is no longer bundled into the published package. Added `THIRD-PARTY-NOTICES.txt` and license materials. No API changes.
+
+## [0.1.0] - 2026-07-21
+
+### Added
+- Initial release: `mppx-atum-escrow`, Atum's cross-chain escrow payment method for the MPP (x402-style) payment flow — build, sign, and verify a source-chain deposit authorization across EVM, Tron, and Solana.

package/README.md

@@ -2,7 +2,7 @@
 
 > **Proprietary software - not open source.**
 >
-> Copyright (c) 2026 Atum Labs, Inc. All rights reserved. Access to and use of `@atumlabs/mppx-atum-escrow` are limited to entities expressly authorized by Atum and are governed by the [Atum MPP Escrow SDK Proprietary License Agreement](./LICENSE). Do not redistribute, publish, mirror, sublicense, or provide this package to any unauthorized person. By accessing, installing, copying, or using the package, you agree to the license terms.
+> Copyright (c) 2026 Atum Labs, Inc. All rights reserved. Access to and use of `@atumlabs/mppx-atum-escrow` are limited to entities expressly authorized by Atum and are governed by the Atum MPP Escrow SDK Proprietary License Agreement in the LICENSE file included with this package. Do not redistribute, publish, mirror, sublicense, or provide this package to any unauthorized person. By accessing, installing, copying, or using the package, you agree to the license terms.
 
 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).
@@ -48,12 +48,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),
@@ -92,6 +95,7 @@ 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
@@ -104,7 +108,7 @@ import { Mppx } from "mppx/server";
 import { PaymentGatewayClient } from "@atumlabs/payment-gateway-client";
 import {
   registerServer,
-  buildChargeRequest,
+  buildChargeChallenge,
   corridorFromDefaults,
   type AtumEscrowCorridor,
   type PaymentSubmitter,
@@ -141,11 +145,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 +167,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 +196,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 +209,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
@@ -257,42 +276,182 @@ On success you get an `AtumEscrowReceipt` — the MPP receipt plus the full sett
 
 ## 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
@@ -307,25 +466,31 @@ 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/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`). |
+| `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). |
+| `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`,
+`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