@atumlabs/payment-gateway-client 2.0.0 → 2.2.0

package/docs/idempotency.md

@@ -0,0 +1,142 @@
+# Payment idempotency
+
+Submit the same payment twice — a retry, a timeout, a network blip — and you
+should end up with **one** payment, not two, and receive the **same** answer both
+times. The key to both properties is the `request_id` you send with each payment.
+
+## Using the SDK
+
+With `@atumlabs/payment-gateway-client` this is automatic. Pass a stable
+`request_id` and reuse it on retry. `request_id` is required on the payment path
+(`preparePaymentRequest`); the SDK derives the on-chain deposit nonce
+deterministically from it, so both guarantees below line up on their own. You
+never manage nonces — `request_id` is the only value you control.
+
+Reuse the same `request_id` across attempts of the same logical payment. Use a
+fresh `request_id` only for a genuinely new payment.
+
+## The two guarantees
+
+### 1. Gateway dedup — enforced for every caller
+
+The gateway records your `request_id` (scoped to your source account and signing
+identity). If the same `request_id` arrives again for the same payment, the
+gateway returns the original payment — same `payment_id`, same status and receipt
+— and never creates a second payment or broadcasts a second deposit. This holds
+whether you use the SDK or call the API directly, as long as you send a stable
+`request_id` and reuse it on retry.
+
+"For the same payment" is the one condition: an id re-used for *different*
+economics is rejected rather than replayed. See
+[Reusing an id for different terms is rejected](#reusing-an-id-for-different-terms-is-rejected).
+
+### 2. On-chain single-settlement — enforced by the blockchain
+
+Each deposit authorization carries a nonce, and the chain guarantees a given
+nonce can settle at most once. This ties your retries together on-chain **only
+if** each retry carries the **same** nonce. The SDK derives that nonce from your
+`request_id`, so retries reuse it automatically. A direct caller sets the nonce
+themselves in the signed permit.
+
+A changing `request_id` defeats both guarantees, because each attempt is then
+treated as a different payment — keep it stable and reuse it on retry.
+
+## Reusing an id for different terms is rejected
+
+One `request_id` identifies one payment, so it cannot be pointed at different
+economics. Re-submit an id you have already used with a changed amount, token,
+account or destination and the gateway answers **`409`** with
+`IDEMPOTENCY_TERMS_MISMATCH` rather than paying, and rather than quietly serving
+you the original payment.
+
+What counts as "different economics" is who pays, who receives, in which assets,
+and for how much — the terms that decide where the money goes. Change any of them
+and you get the `409`; the error's `message` names the category that differed. A
+genuinely different payment needs a new `request_id`, which is what the error is
+telling you.
+
+Anything outside that list is taken from the payment that already exists, and the
+value you sent is not applied. So a re-submission is not a way to amend a payment
+in flight; it is a way to ask for the one you already made.
+
+### Deadlines and the signature are exempt
+
+Two things you may freely change on a re-submission, because neither identifies
+the payment:
+
+- **Deadlines.** Re-send the original bytes unchanged and the deadlines will
+  usually have expired by then: `quote_deadline` bounds the auction and is short,
+  and `POST /v1/payments` can hold a submission for longer than that. An expired
+  deadline on a re-submission is **not** an error — the request resolves onto the
+  payment that already exists, so nothing is scheduled against it.
+- **The signature.** Re-signing is fine. So is re-sending the original signature.
+
+Which means both retry styles work: keep the exact bytes from the first attempt,
+or rebuild and re-sign the same payment. What must not change is the
+`request_id`.
+
+## Telling a retry from a first attempt
+
+`PaymentResponse.idempotent_replay` is `true` when you have been handed a payment
+that already existed, and `false` when this request created one. Read it if you
+need to distinguish "the payment went through just now" from "the payment was
+already there" — for logging, for reconciliation, or to avoid double-counting a
+conversion.
+
+## Reading the outcome
+
+`status` is on every response, and the three endings mean different things for a
+retry:
+
+| `status`               | What it means                     | What to do                                             |
+| ---------------------- | --------------------------------- | ------------------------------------------------------ |
+| `completed`            | Settled.                          | Nothing. `fulfillment_confirmation` carries the proof. |
+| `pending`              | Accepted, still settling.         | Re-submit the **same** `request_id`, or read the status endpoint. Do not start a new payment. |
+| `failed` / `cancelled` | Terminal — it can never complete. | A fresh attempt needs a **new** `request_id`.          |
+
+`pending` is not success. Cross-chain settlement can outrun the gateway's
+synchronous window, so a payment that has been accepted may still have no result
+when you get your response.
+
+A terminal failure **keeps** its `request_id`. Re-submitting that id returns the
+same failed payment for good, which is why recovering from one means minting a
+new id — the opposite of what a pending payment needs. Getting these two the
+wrong way round is how a caller either pays twice or waits for something that
+will never happen.
+
+### How to learn the outcome
+
+Either works, and you can mix them:
+
+- **Poll `GET /v1/payments/{payment_id}/status`** — cheapest once you hold a
+  `payment_id`. This is what the `payment-status` CLI does, and what
+  `send-payment --wait` does after submitting.
+- **Re-submit the same request** — idempotent, and it returns the payment's
+  current state. Useful when you would rather not track `payment_id`, or when the
+  first attempt failed before you learned one.
+
+If you are building a *merchant* that mediates someone else's HTTP request,
+prefer having the payer re-attempt over polling inside that request: polling
+holds the connection open for the whole settlement window. That constraint is
+specific to sitting in the middle of someone else's request, and does not apply
+to a backend calling this SDK directly.
+
+## Chain-specific behavior
+
+The SDK gives you the same guarantee on every chain; the on-chain half works
+slightly differently underneath:
+
+- **EVM / Tron:** the on-chain nonce is spent permanently, so guarantee 2 lasts
+  indefinitely.
+- **Solana:** the on-chain guard covers only a short, bounded window (roughly two
+  minutes). Beyond that window the durable protection is guarantee 1 (the
+  gateway's `request_id` record). The SDK keeps a rebuild inside the window by
+  pinning `issued_at` through its Solana clock reader, so you do not have to.
+
+Either way, a stable `request_id` keeps you safe on every chain.
+
+## A note on addresses
+
+EVM `0x` addresses are case-insensitive, so casing never affects your payment.
+Solana and Tron base58 addresses **are** case-sensitive — pass them exactly as
+issued.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atumlabs/payment-gateway-client",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "TypeScript client for Atum Payment Gateway API",
   "author": "Atum Labs, Inc.",
   "homepage": "https://github.com/Atum-Labs/protocol/tree/main/payment-gateway-client#readme",
@@ -41,11 +41,12 @@
     "generate": "openapi-ts --input ../schemas/apis/payment-gateway/v1/openapi.yaml --output ./src/generated --client axios --name PaymentGatewayClient --useOptions",
     "prebuild:deps": "node -e \"if(!require('fs').existsSync('../key-management/common/typescript/tsconfig.json')){console.error('protocol key-management packages not found at ../key-management. Is this checked out inside the protocol monorepo?');process.exit(1)}\"",
     "build:deps": "tsc -p ../key-management/common/typescript/tsconfig.json && tsc -p ../key-management/providers/turnkey/typescript/tsconfig.json && tsc -p ../contracts/svm/escrow-encoding/typescript/tsconfig.json && tsc -p ../contracts/evm/escrow-encoding/typescript/tsconfig.json && tsc -p ../contracts/tvm/escrow-encoding/typescript/tsconfig.json && tsc -p ../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/tsconfig.json",
-    "build": "pnpm run build:deps && tsup && chmod +x dist/cli/*.js",
+    "build": "pnpm run build:deps && tsup && chmod +x dist/cli/*.js && node scripts/stamp-entry-headers.mjs",
     "pretest": "pnpm run build:deps",
     "test": "jest",
     "clean": "rm -rf dist ../key-management/common/typescript/dist ../key-management/providers/turnkey/typescript/dist ../contracts/svm/escrow-encoding/typescript/dist ../contracts/evm/escrow-encoding/typescript/dist ../contracts/tvm/escrow-encoding/typescript/dist ../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/dist",
     "check:publishable": "node scripts/check-publishable.mjs",
+    "gen:notices": "node scripts/gen-third-party-notices.mjs",
     "prepare": "pnpm run build",
     "prepublishOnly": "pnpm run build && pnpm run check:publishable"
   },
@@ -54,6 +55,7 @@
     "axios": "1.13.2",
     "bs58": "^6.0.0",
     "commander": "^12.0.0",
+    "dotenv": "^16.6.1",
     "ethers": "^6.11.0",
     "tweetnacl": "^1.0.3",
     "zod": "^3.25.0"
@@ -62,6 +64,7 @@
     "@atum-labs/evm-escrow-encoding": "workspace:*",
     "@atum-labs/km-core": "workspace:*",
     "@atum-labs/payment-request-sender-auth": "workspace:*",
+    "@atum-labs/publish-guard": "workspace:*",
     "@atum-labs/solana-escrow-encoding": "workspace:*",
     "@atum-labs/turnkey-signer": "workspace:*",
     "@atum-labs/tvm-escrow-encoding": "workspace:*",
@@ -76,7 +79,14 @@
   },
   "files": [
     "dist/**/*",
-    "CHANGELOG.md"
+    "README.md",
+    "CHANGELOG.md",
+    "docs/**",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.txt"
   ],
-  "license": "UNLICENSED"
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "restricted"
+  }
 }