@atumlabs/payment-gateway-client 3.0.1 → 4.0.0

package/CHANGELOG.md

@@ -7,7 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-10-16
+
+### Added
+- `preparePaymentRequest` signs depositRequestHash v2, the hash of the payment terms, when the source chain's `GET /v1/defaults` entry says so. The new `deposit_request_hash_version` on that response is read into `ChainDefaults.depositRequestHashVersion`; absent is 1, and v1, `keccak256(request_id)`, stays the default. A caller passing `resolvedDefaults.source` sets it there.
+- `verifyPaymentRequestJSON` and `verifyRequestCommitment` read depositRequestHash v2 when asked: `depositRequestHashV2Mode: 'audit' | 'enforce'` on the expectations, or as the new `options` argument of `verifyRequestCommitment`. Either mode accepts a deposit committing v1 or v2; `audit` admits a request the strict reader refuses and reports why in `strictDetail`, `enforce` refuses it as `request_malformed`. Without it, both behave exactly as before. Opted in, `CommitmentResult` carries `depositRequestHashVersion` (`v1` or `v2`) and `expectedDepositRequestHashV2`, and `VerifyResult` carries the check's result as `commitment`.
+- `capFromQuote(sourceAmount, slippageBps)` derives a `max_source_amount` from a settler's quoted `source_amount` plus a slippage tolerance in basis points (0 to 10000). Both amounts are in the source token's smallest units, so no decimals or price are involved, and the result rounds up so it never falls below quote plus tolerance. A non-canonical amount or an out-of-range slippage throws.
+- `preparePaymentRequest` leaves `executor` off unless the caller passes it. Omitted on the wire means settler. Pass `{ deposit, reserve, fulfill }` to split the legs. The request `version` is the declaration bindings constant, `1.3`, because `executor` is a new field.
+
 ### Changed
+- `PaymentStatus` gains `refunding`, `refund_available` and `refunded`, so a caller branching exhaustively on it needs the new values. `GetPaymentStatusResponse.refund_signature` is present only on `refund_available` and lets the originator submit the refund itself, `refund_reason` on the three payment responses says why the settler gave up when it said so, and `PaymentTransactions.refund` is the refund transaction. `isTerminalStatus` treats `refunded` as terminal, so `waitForTerminalStatus` stops on it. `refund_available` is not terminal: the funds are still in escrow until the refund lands or a late delivery is paid. `send-payment` exits 4 on `refund_available` and 3 on `refunded`, and `--wait` does not wait on a payment that is already `refund_available`.
+- **The default quote deadline is now 3 seconds** for both `preparePaymentRequest` (was 10) and `prepareQuoteRequest` (was 5), and so for `send-payment` and `request-quote` as well. Bidding closes at the quote deadline and the gateway always waits until then, so a payment or quote request that relies on the default now spends about 3 seconds at the quote step instead of 5 to 10. `DEFAULT_PAYMENT_QUOTE_DEADLINE_SECONDS` and `DEFAULT_QUOTE_DEADLINE_SECONDS` are both `3`, and the API description's default for `quote_deadline_seconds` on `PreparePaymentRequest` is `3`. The window has to cover signing and submitting the request as well as settlers quoting, and a signed request is submittable only before its quote deadline. Pass a larger `quoteDeadlineSeconds` (`--quote-deadline-seconds` on the command line) when signing takes longer, for example a signer that waits for an approval, when you submit the request later, or when your clock lags the gateway's. Passing the old value restores the old window.
+- **Breaking: the three Atum credential contexts moved to `schemas.atum.xyz`.** A holder credential passed to `buildEnvelope` must name `https://schemas.atum.xyz/credentials/known-to-atum/v1`, `.../kyc/v1` or `.../sender-compliance/v1`. Their terms moved with them, for example to `https://schemas.atum.xyz/credentials/known-to-atum/v1#role`, and those term IRIs are what a credential's signature covers. A credential that still names a `https://schemas.atum.network/credentials/...` URL is refused as an unknown JSON-LD context. One issued under the old vocabulary does not verify even with its URL rewritten, so it has to be re-issued.
+- `FulfillmentAuthorization.authorization` now documents the EIP-3009 shape the settler signs: the transfer is in `message_prehash` as typed-data JSON, `message` is its EIP-712 digest, there is no `payload`, and `validBefore` is the payment's `fulfillment_deadline` in whole seconds. The type is unchanged.
+- **Breaking: `preparePaymentRequest` and `prepareQuoteRequest` refuse a `requestId` outside `^[A-Za-z0-9._-]{1,128}$`**, before anything is built: 1 to 128 ASCII letters, digits, `.`, `_` or `-`. The payment request is now read with the strict reader that computes depositRequestHash v2, whichever version is signed, and that reader, like the gateway once it enforces v2, takes no other `request_id`. Ids the CLI generates already conform; a `--request-id` or `--request-id-prefix` outside the pattern is refused. More generally, any body the strict reader refuses now fails at build, whichever version is signed, not only one with such a `request_id`: for example `settlerRequirements` carrying a member other than `whitelist` and `blacklist`, which the schema allows.
+- `preparePaymentRequest` builds the whole request body before the deposit authorization and signs over exactly that body, then adds `sender_auth` to it. The output for v1 is unchanged.
+- `CommitmentOutcome` gains `quote_request_mismatch`, from the shared SDK's new quote binding. A `Record` or exhaustive `switch` over the outcomes needs a branch for it.
+- `verifyPaymentRequest` is deprecated: it checks a parsed copy of the request and accepts only depositRequestHash v1, and refuses a `depositRequestHashV2Mode`. Use `verifyPaymentRequestJSON` with the request as received.
+- **Breaking for TypeScript callers: `fulfillment_verifier` and `escrow_contract_address` are required on `PaymentRequest` and `CreateQuoteRequest`.** The gateway already refuses a request that omits either. The types said optional with a default the gateway never filled in. Take both from `GET /v1/defaults` for the source chain. `preparePaymentRequest` and `prepareQuoteRequest` already set them, so a caller using the builders is unaffected. The gateway also requires `message_prehash` on every `sender_auth.signed_messages` entry; `SignedMessage` keeps it optional because the award and fulfillment authorization shapes share that type.
+- **Breaking: `preparePaymentRequest` requires `maxSourceAmount`.** It used to default an omitted cap to `fulfillment_amount` plus 2 bps in raw units and sign that into the Permit2, without either token's decimals or price. Across assets with different decimals or value, the signed ceiling could be orders of magnitude above what the payment was worth. The cap is now required in the type and at runtime, must be a positive base-10 integer in the source token's smallest units, and is checked before any network call. Derive it from a settler quote with `capFromQuote`, or state it explicitly. `send-payment` gains `--max-source-amount`, required when building a payment.
+- **`prepareQuoteRequest` no longer invents `max_source_amount`.** An omitted cap used to be derived from `fulfillment_amount` plus 2 bps in raw units, which ignored both tokens' decimals and price: across assets it either filtered nothing or filtered every honest quote. An omitted cap is now left off the request, which the gateway reads as no cap. A supplied cap must be a positive base-10 integer in the source token's smallest units; anything else throws. A caller that relied on the implicit filter should pass `maxSourceAmount` explicitly.
+- **Breaking: the builders for retired escrow shapes are removed.** No deployed escrow accepts what they produce. Removed: `createPermitWitnessTransferFromPrehash`, `PermitWitnessTransferFromParams`, `hashRequestId`, `createTvmPermitWitnessTransferFromPrehash`, `TvmPermitWitnessTransferFromParams`, `createSolanaDepositPrehash`, `hashSolanaDeposit`, `generateSolanaPaymentId`, `SolanaDepositParams`, `SolanaDepositPrehash` and `DEPOSIT_MESSAGE_SIZE`. Build payments with `PaymentGatewayClient.preparePaymentRequest` and sign them with `signPaymentRequest`; `hashPermitWitnessTransferFrom`, `hashTvmPermitWitnessTransferFrom` and the address and nonce helpers remain.
+- **Breaking for TypeScript callers: `destination` and `requestId` are removed from `VerifyPaymentRequestExpectations`.** The payee check they switched on is now always on, and it takes both values from the request itself.
+- **Breaking for TypeScript callers: `depositWitnessVersion` is removed from `ChainDefaults`.** Every deployed escrow uses the four-member deposit witness, which is now the only one built, so the gateway's `deposit_witness_version` is no longer read. Building a Solana payment fails for an `svm_signature_domain_version` below 4.
+- `deposit_witness_version` is removed from the `GET /v1/defaults` response in the API description and the generated wire types. The SDK builds only the four-member witness.
+- A payee-check refusal throws an error whose message names its outcome, for example `sender_auth: destination_mismatch: ...`. `ParsedPermit.destination` and `depositRequestHash` are now set on every chain.
+- New `verifyPaymentRequestJSON` checks a request from its JSON text and also refuses a repeated member name, including names that differ only in letter case, where it is read: any top-level name, or inside `source`, `destination`, `request_id` or `sender_auth`. New `commitmentResultOf` reads the outcome and both copies of the payee from a refusal, and each verified entry carries the same result as `commitment`.
+- Each value a verifier reads has one accepted spelling: `message` is `0x`-prefixed hex on every chain, Tron included; a signature is `0x` followed by 65 bytes of hex (recovery id 0, 1, 27 or 28) on EVM and Tron and `0x` followed by 64 bytes on Solana; and `max_source_amount` is a decimal integer with no sign, prefix, padding or leading zero.
+- New `verifyRequestCommitment` checks the payee and request id a deposit commits to without recovering the signer, so it serves contract-account payers (ERC-1271, such as a Safe). `verifyPaymentRequest` and `verifyPaymentRequestJSON` recover every signer and so accept key-account payers only.
+- A Solana deposit may omit `delegate_signer`; the signature is then checked against `source.account`. When present, it must equal `source.account`.
+- **Breaking for TypeScript callers: `fulfillment_timestamp` is optional on `FulfillmentConfirmation`.** The gateway stopped sending it on 28 August, when settlement moved onto the settler's own report and the path that read the fulfilled event's block time was removed. The settler's report carries no time, so the field is simply absent from every confirmation. The type said `string`, so a caller reading it got a value the compiler promised and the runtime never delivered, and a client generated in a language that enforces required fields failed to deserialize a **completed** payment, after the money had moved. It is now `string | undefined`, which is what arrives. A caller that reads it gets a compile error and has to handle the absence; a caller that ignores it is unaffected. It will become required again when the settler reports the destination block time, and widening it back is not a break.
+- **`request_id_reusable` is new on every error shape**, on `ErrorResponse` and on the asynchronous `PaymentFailure`. `retry_classification` was answering two questions at once: what the caller must change, and whether their own `request_id` survived. A malformed body and an unserved corridor are both `NOT_RETRYABLE_FIX_REQUEST`, and only the first leaves the id free, so the enum could not say both. `true` means no payment was created and the id can be re-sent; `false` means a payment exists and re-sending only replays that outcome. Absent means undetermined, which a caller should read as `false`, since assuming an id is free when it is not is the direction that costs an attempt.
+- **Several public error codes changed value**, so a caller branching on the string needs the new ones. `CONFLICT` split into `ALREADY_SETTLED`, `DUPLICATE_INTENT`, `PAYMENT_IN_PROGRESS` and `REQUEST_ID_TAKEN`, because one code meant four different required actions: read the result, reconcile, poll, or start over with a new id. `INTERNAL_ERROR` split off `SETTLEMENT_OUTCOME_UNKNOWN`, which means settlement had started and money may already have moved, as distinct from a fault where nothing happened. `RATE_LIMITED` and `REQUEST_TIMEOUT` are gone: nothing emitted them. Every one of these keeps its HTTP status and its `retry_classification`, so the code string is the only signal that anything moved. **A caller matching `CONFLICT` keeps compiling and keeps receiving 409, then falls through to its default branch** — and for an already-settled payment that can mean re-submitting one that has been paid.
+- `METHOD_NOT_ALLOWED` is a new public code. A wrong HTTP verb was reported as a missing route, which sends an integrator looking at their URL instead of their method. A 405 now also carries the `Allow` header naming the methods the target does support.
 - **Breaking: `PaymentStatus` is one type across all three payment responses**, with the values `pending`, `finalizing`, `completed` and `failed`. Submitting a payment, polling its status and reading its timeline previously returned three unrelated status types, so a caller could not write one function that handled "a payment status". `settling` is gone — it described how far our own bookkeeping had got, not the payment. `cancelled` is gone too: nothing could produce it, and a payment that ends without being delivered is reported as `failed`. `isTerminalStatus('cancelled')` therefore returns `false` now. A caller with an exhaustive `switch` on status gets a compile error and has to add a `finalizing` branch; a caller testing only for `completed` or `failed` is unaffected.
 - **`finalizing` is new, and is NOT terminal.** It means the transaction paying the recipient is on chain and accruing the confirmations its chain requires — made, but not yet irreversible, much as a card authorization is not a settlement. It normally becomes `completed` and can still become `failed`. Nothing emits it yet; it is declared here so clients are ready before the gateway starts sending it.
 - **Breaking: one failure shape.** `PaymentError` and `TimelineError` are replaced by a single `PaymentFailure` used by all three responses, so a failure reads identically however you ask about the payment. On the timeline that is a real change of shape: `chain_id`, `tx_hash` and `revert_reason` were flat on the error and are now nested under `blockchain_context`, which also carries the four fields that endpoint previously discarded — the block number among them.
@@ -15,8 +47,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `PaymentFailure` now carries `docs_url` and `retry_classification`. Both were already computed for every error code but only ever reached failed *requests*, never failed *payments*.
 - The `payment-outcome` CLI no longer maps `cancelled` to exit code 3 (terminal failure), because the gateway no longer reports it. A status this build does not recognise exits 2 (still pending), which is the safe direction: a script that waits one more round costs a poll, a script that gives up on a live payment can cost a second charge.
 - **New `transactions` object** (`deposit`, `fulfillment`) on all three responses, for looking a payment's on-chain transactions up yourself. Declared but not yet populated.
+- The package moved within the protocol repository, from `payment-gateway-client/` to `schemas/apis/payment-gateway/v1/bindings/payment-gateway-client/`, beside the other payment-gateway bindings. Only the manifest `homepage` and `repository.directory` change; the published name, entry points and behavior do not.
+
+### Fixed
+- `preparePaymentRequest` and `prepareQuoteRequest` stamp the quote and fulfillment deadlines after their own network reads, the chain-defaults fetch and, for a Solana source, the cluster-clock read, so that time no longer comes out of the quote window. Invalid deadline values are still refused before any network call.
 
 ### Security
+- `verifyPaymentRequest` refuses a request whose payee or `request_id` differs from the one the payer signed, on EVM, Tron and Solana. A request's `destination` and `request_id` fields are not covered by the payer's signature; the copies inside the signed deposit are, and the two must now agree. A deposit that commits no destination is refused.
 - The HTTP client is now axios 1.20.0. 1.13.2 had a run of advisories (prototype-pollution gadgets that could tamper with requests or responses, proxy-authorization leaks, NO_PROXY SSRF, ReDoS). A caller that pins axios independently should take 1.18.0 or newer. A timeout that fires after headers have arrived still surfaces as `GatewayTimeoutError`: axios 1.20 attaches the partial response, and the client drops it so a stalled error body is not reported as a completed HTTP status.
 
 ## [3.0.1] - 2026-09-18

package/README.md

@@ -83,6 +83,7 @@ send-payment --submit <file> [options]
 - `--gateway <url>` - Payment gateway URL (default: testnet)
 - `--request-id <id>` - Idempotency key; seeds the on-chain deposit nonce. Re-run with the same id to re-attempt one payment. Omitted, an id is generated and printed, which makes every bare re-run a separate payment (see [Idempotency and retries](#idempotency-and-retries))
 - `--request-id-prefix <prefix>` - Prefix for the auto-generated request id (default: `pmt-gw-cli`)
+- `--max-source-amount <amount>` - Required to build a payment: the most the payer authorizes from source, in the source token's smallest units, signed into the Permit2. Never derived for you; the quoted `source_amount` from `request-quote` plus a slippage margin is the usual basis (the SDK's `capFromQuote` computes it). Not accepted with `--submit`
 - `--prepare-only` - Build and sign the request, print it to stdout, and stop without submitting. For inspecting an authorization, or for review before paying; send it later with `--submit` (see [Preparing a payment for review](#preparing-a-payment-for-review)). Cannot be combined with `--wait`
 - `--submit <file>` - Send a request built earlier by `--prepare-only`, instead of building one. Signs nothing and needs no private key; `-` reads stdin. Takes no corridor arguments
 - `--wait` - After submitting, keep checking until the payment settles or fails instead of reporting it as still pending
@@ -97,8 +98,9 @@ runs the next step only for a settled payment:
 | Code | Meaning                                                                     |
 | ---- | --------------------------------------------------------------------------- |
 | `0`  | `completed` — settled                                                       |
-| `2`  | `pending` — accepted, no result yet                                          |
-| `3`  | `failed` — terminal; a fresh attempt needs a new `--request-id`              |
+| `2`  | `pending`, `finalizing` or `refunding` — accepted, no result yet             |
+| `3`  | `failed` or `refunded` — terminal; a fresh attempt needs a new `--request-id` |
+| `4`  | `refund_available` — not delivered, funds still in escrow; submit `refund_signature`, do not pay again |
 | `1`  | no outcome obtained (rejected, gateway unreachable, bad arguments)            |
 
 On `2`, follow the payment with **`payment-status <payment_id>`** — the id is in the
@@ -202,7 +204,8 @@ PRIVATE_KEY=0xabc... send-payment \
   100000 \
   eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831 \
   TRX123... \
-  tron:shasta/trc20:TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs
+  tron:shasta/trc20:TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs \
+  --max-source-amount 101000
 ```
 
 ### Preparing a payment for review
@@ -215,7 +218,7 @@ one that was prepared earlier.
 
 ```bash
 # 1. build and sign, submit nothing
-send-payment --prepare-only --quote-deadline-seconds 30 \
+send-payment --prepare-only --quote-deadline-seconds 30 --max-source-amount 101000 \
   0xF0D0... 100000 \
   eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831 \
   0xMerchant... \
@@ -240,7 +243,7 @@ Four things to know:
   it, so this is not an offline signing mode.
 - **Widen the quote window if you intend to submit later — but only by tens of seconds.**
   A prepared document is submittable only while its quote window is open, and the default
-  is 10 seconds. That window is also the auction: the gateway waits it out before choosing
+  is 3 seconds. That window is also the auction: the gateway waits it out before choosing
   a settler, and settler quotes expire on their own, so an over-long window ends in
   `QUOTES_EXPIRED`. That failure is terminal, and a fresh attempt needs a new request id.
   Give the reviewer enough time and no more.
@@ -378,6 +381,9 @@ async function sendPayment() {
     sourceAsset: 'tron:shasta/trc20:TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs', // USDT on Tron Shasta
     destinationAccount: '0xYourEthereumAddressHere',
     destinationAsset: 'eip155:11142220/erc20:0x456a3D042C0DbD3db53D5489e98dFb038553B0d0', // USDC on Celo Sepolia
+    // Required. The most the payer authorizes from source, in USDT's smallest units, signed into
+    // the Permit2. The SDK never derives it; capFromQuote builds one from a settler quote.
+    maxSourceAmount: '101000',
     // Required. Your stable idempotency key — reuse the SAME value on retry so a
     // retry never becomes a second payment (see "Idempotency and retries" below).
     requestId: 'order-4711',
@@ -420,6 +426,15 @@ async function sendPayment() {
         // Terminal, and this request_id stays bound to it. A fresh attempt needs a NEW id.
         console.error('Failed:', response.error?.code, response.error?.message);
         break;
+      case 'refunded':
+        // Terminal and not delivered, so a fresh attempt needs a NEW id.
+        console.error('Refunded:', response.payment_id);
+        break;
+      case 'refund_available':
+        // Not delivered and the funds are still in escrow. getPaymentStatus(payment_id) returns
+        // refund_signature, which returns them. Do not pay again: a late delivery can still land.
+        console.error('Refund available:', response.payment_id);
+        break;
       default:
         // Still settling. Do not release goods, and do not pay again under a new id.
         // Follow it with getPaymentStatus(payment_id); re-submitting this same request
@@ -455,8 +470,14 @@ it is what you need to find the payment again.
 | `finalizing` | Paid on chain, collecting confirmations. Not final |
 | `completed` | Delivered |
 | `failed` | Did not settle |
+| `refunding` | Not delivered, the escrowed funds are being returned. Not final |
+| `refund_available` | Not delivered, funds still in escrow. `getPaymentStatus` returns `refund_signature`, which you submit to the source escrow to return them. Not final: it becomes `refunded`, or `completed` if a late delivery is paid first |
+| `refunded` | Not delivered, your funds were returned |
+
+On the three refund statuses `refund_reason` says why the settler gave up, when it said. Act on
+`status`, not on `refund_reason.retry_classification`.
 
-`completed` and `failed` are final. A payment that reaches one of them keeps
+`completed`, `failed` and `refunded` are final. A payment that reaches one of them keeps
 its `request_id` for good, so re-submitting that id returns the same finished payment
 rather than trying again — a genuine new attempt needs a **new** `request_id`. Any status
 this client does not recognise is treated as still in flight. `isTerminalStatus` is exported