@atumlabs/payment-gateway-client 2.1.0 → 2.2.0

package/dist/index.js

@@ -256,12 +256,14 @@ var require_utils = __commonJS({
   "../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/dist/utils.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.SOLANA_REPLAY_SLOTS = exports2.PERMIT_NONCE_DOMAIN = exports2.REPLAY_HORIZON_SECS = void 0;
+    exports2.REQUEST_ID_DOMAIN = exports2.SOLANA_REPLAY_SLOTS = exports2.PERMIT_NONCE_DOMAIN = exports2.REPLAY_HORIZON_SECS = void 0;
     exports2.resolvePermitDeadline = resolvePermitDeadline;
     exports2.generatePermitNonce = generatePermitNonce;
     exports2.resolvePermitNonce = resolvePermitNonce;
+    exports2.canonicalDepositor = canonicalDepositor;
     exports2.deterministicPermitNonce = deterministicPermitNonce2;
     exports2.deterministicSolanaNonce = deterministicSolanaNonce2;
+    exports2.deterministicRequestId = deterministicRequestId;
     exports2.sameAddress = sameAddress;
     exports2.assertKeyMatchesSender = assertKeyMatchesSender2;
     exports2.assertToken = assertToken;
@@ -306,6 +308,20 @@ var require_utils = __commonJS({
       const bucket = (seed >> 8n) % (1n << SOLANA_BUCKET_BITS);
       return bucket << 32n | slot;
     }
+    exports2.REQUEST_ID_DOMAIN = "atum-request:v1:";
+    function deterministicRequestId(params) {
+      if (!params.anchor) {
+        throw new Error("sender_auth: a per-intent anchor is required to derive a deterministic request_id (a random one would silently break idempotency and let a retry double-charge)");
+      }
+      if (!params.account) {
+        throw new Error("sender_auth: account is required to derive a deterministic request_id");
+      }
+      if (!/^[A-Za-z0-9_-]*$/.test(params.prefix)) {
+        throw new Error(`sender_auth: request_id prefix must contain only letters, digits, '_' or '-' (got ${JSON.stringify(params.prefix)})`);
+      }
+      const digest = (0, ethers_1.keccak256)((0, ethers_1.toUtf8Bytes)(`${exports2.REQUEST_ID_DOMAIN}${params.anchor}:${canonicalDepositor(params.account)}`));
+      return `${params.prefix}${digest.slice(2, 26)}`;
+    }
     function sameAddress(a, b) {
       if (a.startsWith("0x") && b.startsWith("0x")) {
         return a.toLowerCase() === b.toLowerCase();
@@ -897,7 +913,7 @@ var require_evm = __commonJS({
     exports2.evmAdapter = {
       async buildAuthMessage({ sourceAsset, maxSourceAmount, sourceDefaults, deadline, nonce }) {
         if (nonce === void 0) {
-          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. the challenge id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
+          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. an order id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
         }
         if (deadline === void 0) {
           throw new Error("sender_auth: buildAuthMessage requires an explicit permit deadline (absolute Unix seconds) \u2014 the low-level builder does not default it; derive it from the payment's fulfillment/settlement deadline in the calling layer (pgc/mppx)");
@@ -925,6 +941,10 @@ var require_evm = __commonJS({
           throw new Error("EVM adapter sign(): signed_messages[i].message_prehash is required");
         }
         const prehash = JSON.parse(signedMessage.message_prehash);
+        const prehashDigest = (0, evm_escrow_encoding_1.hashPermitWitnessTransferFrom)(prehash);
+        if (prehashDigest.toLowerCase() !== signedMessage.message.toLowerCase()) {
+          throw new Error(`EVM adapter sign(): message_prehash implies digest ${prehashDigest} but message is ${signedMessage.message}`);
+        }
         const wallet = new ethers_1.Wallet(privateKey);
         return wallet.signTypedData(prehash.domain, prehash.types, prehash.message);
       },
@@ -1011,7 +1031,7 @@ var require_tron = __commonJS({
     exports2.tronAdapter = {
       async buildAuthMessage({ sourceAsset, maxSourceAmount, sourceDefaults, deadline, nonce }) {
         if (nonce === void 0) {
-          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. the challenge id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
+          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. an order id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
         }
         if (deadline === void 0) {
           throw new Error("sender_auth: buildAuthMessage requires an explicit permit deadline (absolute Unix seconds) \u2014 the low-level builder does not default it; derive it from the payment's fulfillment/settlement deadline in the calling layer (pgc/mppx)");
@@ -1034,9 +1054,19 @@ var require_tron = __commonJS({
         const messageHash = (0, tvm_escrow_encoding_1.hashTvmPermitWitnessTransferFrom)(messagePrehash);
         return { messageScheme: "EVM_PERMIT2", messageHash, messagePrehash: JSON.stringify(messagePrehash) };
       },
+      // Signs the TIP-712 typed data, not the bare digest, so a signer can inspect the fields it is
+      // authorizing (Turnkey policies read `eth.eip_712.message[...]`).
       async sign(signedMessage, privateKey) {
+        if (!signedMessage.message_prehash) {
+          throw new Error("Tron adapter sign(): signed_messages[i].message_prehash is required");
+        }
+        const prehash = JSON.parse(signedMessage.message_prehash);
+        const prehashDigest = (0, tvm_escrow_encoding_1.hashTvmPermitWitnessTransferFrom)(prehash);
+        if (prehashDigest.toLowerCase() !== signedMessage.message.toLowerCase()) {
+          throw new Error(`Tron adapter sign(): message_prehash implies digest ${prehashDigest} but message is ${signedMessage.message}`);
+        }
         const wallet = new ethers_1.Wallet(privateKey.startsWith("0x") ? privateKey : "0x" + privateKey);
-        return wallet.signingKey.sign(signedMessage.message).serialized;
+        return wallet.signTypedData(prehash.domain, prehash.types, prehash.message);
       },
       recoverSigner(signed, source) {
         let recovered;
@@ -2693,6 +2723,7 @@ var require_client = __commonJS({
       retryCounter;
       backoffHistogram;
       activityPendingCounter;
+      signDurationHistogram;
       // The private API scalar is held only long enough to construct the stamper. After
       // `getStamper()` runs, this is nulled out so the hex string doesn't survive on the heap
       // for the client's lifetime. Web Crypto holds the imported key as an opaque CryptoKey.
@@ -2721,6 +2752,10 @@ var require_client = __commonJS({
         this.activityPendingCounter = meter.createCounter("turnkey.activity_pending_total", {
           description: "Activities that entered async polling (did not complete synchronously in the submit response), labeled by activity type"
         });
+        this.signDurationHistogram = meter.createHistogram("turnkey.sign_duration_ms", {
+          description: "Full Turnkey activity round-trip latency (concurrency-semaphore wait + submit + poll), labeled by activity type and outcome (success|error)",
+          unit: "ms"
+        });
       }
       emitRetry(reason, path) {
         try {
@@ -2740,6 +2775,12 @@ var require_client = __commonJS({
         } catch {
         }
       }
+      emitSignDuration(durationMs, activityType, outcome) {
+        try {
+          this.signDurationHistogram.record(durationMs, { activity_type: activityType, outcome });
+        } catch {
+        }
+      }
       // ── public surface ─────────────────────────────────────────────────────────
       /** Boot-time reachability + auth probe. Throws TURNKEY_AUTH on bad credentials. */
       async whoami() {
@@ -2789,39 +2830,46 @@ var require_client = __commonJS({
       }
       // ── activity submission ────────────────────────────────────────────────────
       async submitActivity(activityType, endpoint, parameters) {
-        const body = {
-          type: activityType,
-          timestampMs: String(Date.now()),
-          organizationId: this.opts.organizationId,
-          parameters
-        };
-        const signWith = typeof parameters.signWith === "string" ? parameters.signWith : void 0;
-        const ctx = `activity=${activityType}${signWith ? ` signWith=${signWith}` : ""}`;
-        const resp = await this.queryPost(`/public/v1/submit/${endpoint}`, body);
-        let activity = resp.activity;
-        const deadline = Date.now() + POLL_TIMEOUT_MS;
-        let pollAttempt = 0;
-        if (activity?.status === "ACTIVITY_STATUS_PENDING") {
-          this.emitActivityPending(activityType);
-        }
-        while (activity?.status === "ACTIVITY_STATUS_PENDING") {
-          if (Date.now() > deadline) {
-            throw (0, km_core_1.signerRetryable)(km_core_1.SignerErrorCode.TURNKEY_SIGNER_UNAVAILABLE, `Turnkey ${ctx} activityId=${activity.id} stayed PENDING past ${POLL_TIMEOUT_MS}ms`);
+        const start = Date.now();
+        let outcome = "error";
+        try {
+          const body = {
+            type: activityType,
+            timestampMs: String(Date.now()),
+            organizationId: this.opts.organizationId,
+            parameters
+          };
+          const signWith = typeof parameters.signWith === "string" ? parameters.signWith : void 0;
+          const ctx = `activity=${activityType}${signWith ? ` signWith=${signWith}` : ""}`;
+          const resp = await this.queryPost(`/public/v1/submit/${endpoint}`, body);
+          let activity = resp.activity;
+          const deadline = Date.now() + POLL_TIMEOUT_MS;
+          let pollAttempt = 0;
+          if (activity?.status === "ACTIVITY_STATUS_PENDING") {
+            this.emitActivityPending(activityType);
           }
-          const sleepIdx = Math.min(pollAttempt, POLL_BACKOFF_MS.length - 1);
-          await (0, promises_1.setTimeout)(POLL_BACKOFF_MS[sleepIdx]);
-          pollAttempt++;
-          const polled = await this.queryPost("/public/v1/query/get_activity", { organizationId: this.opts.organizationId, activityId: activity.id });
-          activity = polled.activity;
-        }
-        if (activity?.status !== "ACTIVITY_STATUS_COMPLETED") {
-          const failure = activity?.failure ?? {};
-          throw (0, km_core_1.signerTerminal)(km_core_1.SignerErrorCode.TURNKEY_ACTIVITY_FAILED, `Turnkey ${ctx} activityId=${activity?.id ?? "?"} status=${activity?.status ?? "unknown"}; ${JSON.stringify(failure)}`);
-        }
-        if (activity.result == null) {
-          throw (0, km_core_1.signerTerminal)(km_core_1.SignerErrorCode.TURNKEY_BAD_RESPONSE, `Turnkey ${ctx} activityId=${activity.id} COMPLETED but result was missing`);
+          while (activity?.status === "ACTIVITY_STATUS_PENDING") {
+            if (Date.now() > deadline) {
+              throw (0, km_core_1.signerRetryable)(km_core_1.SignerErrorCode.TURNKEY_SIGNER_UNAVAILABLE, `Turnkey ${ctx} activityId=${activity.id} stayed PENDING past ${POLL_TIMEOUT_MS}ms`);
+            }
+            const sleepIdx = Math.min(pollAttempt, POLL_BACKOFF_MS.length - 1);
+            await (0, promises_1.setTimeout)(POLL_BACKOFF_MS[sleepIdx]);
+            pollAttempt++;
+            const polled = await this.queryPost("/public/v1/query/get_activity", { organizationId: this.opts.organizationId, activityId: activity.id });
+            activity = polled.activity;
+          }
+          if (activity?.status !== "ACTIVITY_STATUS_COMPLETED") {
+            const failure = activity?.failure ?? {};
+            throw (0, km_core_1.signerTerminal)(km_core_1.SignerErrorCode.TURNKEY_ACTIVITY_FAILED, `Turnkey ${ctx} activityId=${activity?.id ?? "?"} status=${activity?.status ?? "unknown"}; ${JSON.stringify(failure)}`);
+          }
+          if (activity.result == null) {
+            throw (0, km_core_1.signerTerminal)(km_core_1.SignerErrorCode.TURNKEY_BAD_RESPONSE, `Turnkey ${ctx} activityId=${activity.id} COMPLETED but result was missing`);
+          }
+          outcome = "success";
+          return activity.result;
+        } finally {
+          this.emitSignDuration(Date.now() - start, activityType, outcome);
         }
-        return activity.result;
       }
       // ── HTTP layer ────────────────────────────────────────────────────────────
       /**
@@ -3095,17 +3143,33 @@ var require_secp256k1_helpers = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.signSecp256k1PreimageAndVerify = signSecp256k1PreimageAndVerify;
+    exports2.signSecp256k1TypedDataAndVerify = signSecp256k1TypedDataAndVerify;
     exports2.bytesFromHexOrBytes = bytesFromHexOrBytes;
     var ethers_1 = require("ethers");
     var km_core_1 = require_dist5();
+    var EIP712_HASH_FUNCTION = "HASH_FUNCTION_NOT_APPLICABLE";
     async function signSecp256k1PreimageAndVerify(client, signWith, preimage, expectedEvmAddrLower) {
       const preimageHex = (0, ethers_1.hexlify)(preimage).slice(2);
-      const { r, s, v } = await client.signRawPayload({
+      const parts = await client.signRawPayload({
         signWith,
         payload: preimageHex,
         encoding: "PAYLOAD_ENCODING_HEXADECIMAL",
         hashFunction: "HASH_FUNCTION_KECCAK256"
       });
+      return recoverAndVerify(parts, (0, ethers_1.keccak256)(preimage), expectedEvmAddrLower);
+    }
+    async function signSecp256k1TypedDataAndVerify(client, signWith, domain, types, message, expectedEvmAddrLower) {
+      const payload = ethers_1.TypedDataEncoder.getPayload(domain, types, message);
+      const parts = await client.signRawPayload({
+        signWith,
+        payload: JSON.stringify(payload),
+        encoding: "PAYLOAD_ENCODING_EIP712",
+        hashFunction: EIP712_HASH_FUNCTION
+      });
+      const digestHex = ethers_1.TypedDataEncoder.hash(domain, types, message);
+      return recoverAndVerify(parts, digestHex, expectedEvmAddrLower);
+    }
+    function recoverAndVerify({ r, s, v }, digestHex, expectedEvmAddrLower) {
       let sig;
       try {
         sig = ethers_1.Signature.from({
@@ -3116,7 +3180,6 @@ var require_secp256k1_helpers = __commonJS({
       } catch (err) {
         throw (0, km_core_1.signerTerminal)(km_core_1.SignerErrorCode.TURNKEY_BAD_RESPONSE, `Turnkey returned malformed secp256k1 signature parts r=${r} s=${s} v=${v}`, err instanceof Error ? err : void 0);
       }
-      const digestHex = (0, ethers_1.keccak256)(preimage);
       const recovered = (0, ethers_1.recoverAddress)(digestHex, sig).toLowerCase();
       if (recovered !== expectedEvmAddrLower) {
         throw (0, km_core_1.signerTerminal)(km_core_1.SignerErrorCode.TURNKEY_BAD_RESPONSE, `secp256k1 sign-then-recover mismatch: recovered ${recovered}, expected ${expectedEvmAddrLower}`);
@@ -3180,8 +3243,7 @@ ${msgBytes.length}`);
       }
       async signTypedData(domain, types, message) {
         const { signWith, lower } = this.requireAddresses();
-        const preimage = (0, ethers_1.getBytes)(ethers_1.TypedDataEncoder.encode(domain, types, message));
-        return (0, secp256k1_helpers_1.signSecp256k1PreimageAndVerify)(this.client, signWith, preimage, lower);
+        return (0, secp256k1_helpers_1.signSecp256k1TypedDataAndVerify)(this.client, signWith, domain, types, message, lower);
       }
       async signTransaction(tx) {
         const { signWith, lower } = this.requireAddresses();
@@ -3298,6 +3360,7 @@ var require_solana2 = __commonJS({
     };
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.TurnkeySolanaSigner = void 0;
+    exports2.encodePayload = encodePayload;
     var web3_js_1 = require("@solana/web3.js");
     var bs58_1 = __importDefault(require("bs58"));
     var km_core_1 = require_dist5();
@@ -3331,8 +3394,7 @@ var require_solana2 = __commonJS({
         }
         const { r, s } = await this.client.signRawPayload({
           signWith: this.address,
-          payload: Buffer.from(bytes).toString("hex"),
-          encoding: "PAYLOAD_ENCODING_HEXADECIMAL",
+          ...encodePayload(bytes),
           hashFunction: "HASH_FUNCTION_NOT_APPLICABLE"
         });
         const sig = Buffer.concat([Buffer.from(stripHex(r), "hex"), Buffer.from(stripHex(s), "hex")]);
@@ -3373,6 +3435,15 @@ var require_solana2 = __commonJS({
       }
     };
     exports2.TurnkeySolanaSigner = TurnkeySolanaSigner2;
+    function encodePayload(bytes) {
+      const buf = Buffer.from(bytes);
+      const text = buf.toString("utf8");
+      const textual = buf.every((b) => b >= 32 && b <= 126 || b === 9 || b === 10 || b === 13);
+      if (textual && Buffer.from(text, "utf8").equals(buf)) {
+        return { payload: text, encoding: "PAYLOAD_ENCODING_TEXT_UTF8" };
+      }
+      return { payload: buf.toString("hex"), encoding: "PAYLOAD_ENCODING_HEXADECIMAL" };
+    }
     function stripHex(s) {
       return s.startsWith("0x") ? s.slice(2) : s;
     }
@@ -3440,8 +3511,7 @@ ${messageBytes.length}`);
       }
       async signTypedData(domain, types, message) {
         const { address, evmAddr } = this.requireReady();
-        const preimage = (0, ethers_1.getBytes)(ethers_1.TypedDataEncoder.encode(domain, types, message));
-        return (0, secp256k1_helpers_1.signSecp256k1PreimageAndVerify)(this.client, address, preimage, evmAddr);
+        return (0, secp256k1_helpers_1.signSecp256k1TypedDataAndVerify)(this.client, address, domain, types, message, evmAddr);
       }
       async signTransaction(tx) {
         const { address, evmAddr } = this.requireReady();
@@ -3820,7 +3890,7 @@ var require_policies = __commonJS({
         policyName: "allowSignRawPayload",
         effect: "EFFECT_ALLOW",
         condition: `activity.type in ['ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2', 'ACTIVITY_TYPE_SIGN_RAW_PAYLOADS'] && activity.params.hash_function in ['HASH_FUNCTION_KECCAK256', 'HASH_FUNCTION_NOT_APPLICABLE']`,
-        notes: "Allows signRawPayload with the hash functions the agent runtime uses."
+        notes: "Allows signRawPayload with the hash functions the runtime uses: KECCAK256 (EIP-191/TIP-191/W3C proofs) and NOT_APPLICABLE (Solana ed25519 + EIP-712 typed data)."
       };
     }
     function buildDenyApproveToNonAllowedSpenderEvm(args) {
@@ -4465,7 +4535,7 @@ var require_dist6 = __commonJS({
       for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports3, p)) __createBinding(exports3, m, p);
     };
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.bytesFromHexOrBytes = exports2.signSecp256k1PreimageAndVerify = exports2.extractTronSignatureFromTransactionProtobuf = exports2.TurnkeyTronSigner = exports2.TurnkeySolanaSigner = exports2.TurnkeyEvmSigner = exports2.noopMeter = exports2.noopLogger = exports2.TURNKEY_RETRY_BACKOFF_MS = exports2.resolveTurnkeyAccountAddress = exports2.p1363ToDer = exports2.createTurnkeyStamper = exports2.createIsolatedTurnkeyClient = exports2.getOrCreateTurnkeyClient = exports2.TurnkeyClient = void 0;
+    exports2.bytesFromHexOrBytes = exports2.signSecp256k1PreimageAndVerify = exports2.extractTronSignatureFromTransactionProtobuf = exports2.TurnkeyTronSigner = exports2.encodePayload = exports2.TurnkeySolanaSigner = exports2.TurnkeyEvmSigner = exports2.noopMeter = exports2.noopLogger = exports2.TURNKEY_RETRY_BACKOFF_MS = exports2.resolveTurnkeyAccountAddress = exports2.p1363ToDer = exports2.createTurnkeyStamper = exports2.createIsolatedTurnkeyClient = exports2.getOrCreateTurnkeyClient = exports2.TurnkeyClient = void 0;
     var client_1 = require_client();
     Object.defineProperty(exports2, "TurnkeyClient", { enumerable: true, get: function() {
       return client_1.TurnkeyClient;
@@ -4508,6 +4578,9 @@ var require_dist6 = __commonJS({
     Object.defineProperty(exports2, "TurnkeySolanaSigner", { enumerable: true, get: function() {
       return solana_1.TurnkeySolanaSigner;
     } });
+    Object.defineProperty(exports2, "encodePayload", { enumerable: true, get: function() {
+      return solana_1.encodePayload;
+    } });
     var tron_1 = require_tron2();
     Object.defineProperty(exports2, "TurnkeyTronSigner", { enumerable: true, get: function() {
       return tron_1.TurnkeyTronSigner;
@@ -4569,13 +4642,13 @@ async function signWithTurnkeyClient(client, chainPrefix, cfg, message, messageP
   };
   switch (chainPrefix) {
     case "eip155": {
-      const { domain, types, message: typedMessage } = parsePrehash(messagePrehash, "EVM");
+      const { domain, types, message: typedMessage } = parsePrehash(messagePrehash, "EVM", message);
       const signer = new import_turnkey_signer.TurnkeyEvmSigner(client, deps);
       await signer.initialize();
       return { signature: await signer.signTypedData(domain, types, typedMessage) };
     }
     case "tron": {
-      const { domain, types, message: typedMessage } = parsePrehash(messagePrehash, "Tron");
+      const { domain, types, message: typedMessage } = parsePrehash(messagePrehash, "Tron", message);
       const signer = new import_turnkey_signer.TurnkeyTronSigner(client, deps);
       await signer.initialize();
       return { signature: await signer.signTypedData(domain, types, typedMessage) };
@@ -4603,7 +4676,7 @@ function decodeSolanaMessageHex(message) {
   }
   return Uint8Array.from(Buffer.from(hex, "hex"));
 }
-function parsePrehash(messagePrehash, label) {
+function parsePrehash(messagePrehash, label, advertisedDigest) {
   if (!messagePrehash) {
     throw new Error(`Turnkey ${label} signing requires signed_messages[0].message_prehash`);
   }
@@ -4617,13 +4690,21 @@ function parsePrehash(messagePrehash, label) {
   if (!isObject(parsed) || !isObject(parsed.domain) || !isObject(parsed.types) || !isObject(parsed.message)) {
     throw new Error(`Turnkey ${label} signing: message_prehash must be a JSON object with domain, types and message`);
   }
-  return { domain: parsed.domain, types: parsed.types, message: parsed.message };
+  const { EIP712Domain: _derived, ...structTypes } = parsed.types;
+  const prehashDigest = import_ethers5.TypedDataEncoder.hash(parsed.domain, structTypes, parsed.message);
+  if (prehashDigest.toLowerCase() !== advertisedDigest.toLowerCase()) {
+    throw new Error(
+      `Turnkey ${label} signing: message_prehash implies digest ${prehashDigest} but message is ${advertisedDigest}`
+    );
+  }
+  return { domain: parsed.domain, types: structTypes, message: parsed.message };
 }
-var import_turnkey_signer, TURNKEY_API_URL, DEFAULTS;
+var import_turnkey_signer, import_ethers5, TURNKEY_API_URL, DEFAULTS;
 var init_turnkey_impl = __esm({
   "src/signers/turnkey-impl.ts"() {
     "use strict";
     import_turnkey_signer = __toESM(require_dist6());
+    import_ethers5 = require("ethers");
     TURNKEY_API_URL = "https://api.turnkey.com";
     DEFAULTS = {
       concurrencyLimit: 10,
@@ -5146,8 +5227,26 @@ var PaymentsService = class {
    * 2. Find optimal settlement routes across chains/assets
    * 3. Secure funds in escrow
    * 4. Coordinate with settlement agents for execution
-   * 5. Return a real-time result if processing completes within 30 seconds,
-   * otherwise return a payment ID for status polling
+   * 5. Return a real-time result if settlement completes inside the synchronous window,
+   * otherwise return a payment ID and status for polling
+   *
+   * **Idempotency.** `request_id` is the idempotency key, scoped to the source account
+   * and originator. Submitting the same `request_id` again returns the ORIGINAL payment
+   * instead of charging a second time, so a client whose request timed out or failed
+   * in transit can safely re-submit.
+   *
+   * Because a re-submission must be admissible on its own, some fields legitimately
+   * differ between attempts and are excluded from the comparison: `quote_deadline` and
+   * `fulfillment_deadline` (both must be in the future, so a later attempt has to move
+   * them), and the `sender_auth` signature they are signed into.
+   *
+   * What must NOT differ is the payment's economics — source account and asset,
+   * destination accounts and assets, `fulfillment_amount`, and `max_source_amount` (the
+   * payer's own risk cap; lowering it on a retry describes a different payment, not the
+   * same one with less headroom). Re-using one `request_id` for a genuinely different
+   * payment is a client bug that would otherwise be silently collapsed onto the first
+   * payment, so it is rejected with `409` and `IDEMPOTENCY_TERMS_MISMATCH`. Use a
+   * distinct `request_id` per payment.
    *
    * @param data The data for the request.
    * @param data.requestBody
@@ -5164,6 +5263,11 @@ var PaymentsService = class {
         400: "Invalid request",
         401: "Signature or sender authorization could not be verified",
         403: "Payment declined during counterparty authorization",
+        409: `The \`request_id\` has already been used for a payment with different economics
+(\`IDEMPOTENCY_TERMS_MISMATCH\`). Re-submitting one \`request_id\` is how a retry is
+made safe, so it must identify one payment; use a distinct \`request_id\` per
+payment.
+`,
         413: "Payment request too large to process",
         500: "Internal server error",
         503: "A dependency is temporarily unavailable"
@@ -6158,11 +6262,18 @@ var $VerifiableCredential = {
 };
 var $PaymentResponse = {
   type: "object",
-  description: `Response from submitting a payment request. If processing completes within 30 seconds,
-the response will include a fulfillment_confirmation with full settlement details.
-Otherwise, you'll receive a payment_id that you can use to poll the
-/v1/payments/{paymentId}/status endpoint for updates.
+  description: `Response from submitting a payment request. If settlement completes inside the
+gateway's synchronous window, the response includes a fulfillment_confirmation with
+full settlement details. Otherwise you receive a payment_id plus the payment's
+current \`status\`, and can poll /v1/payments/{paymentId}/status for updates.
+
+Read \`status\` before deciding what to do next: a \`pending\` payment is in flight and
+must NOT be re-submitted under a new request_id (that would be a second payment),
+whereas a \`failed\` or \`cancelled\` one is terminal \u2014 re-submitting it under the SAME
+request_id resolves to the same terminal payment, so a genuine re-attempt needs a
+new request_id.
 `,
+  required: ["payment_id", "status", "idempotent_replay"],
   properties: {
     payment_id: {
       type: "string",
@@ -6170,8 +6281,60 @@ Otherwise, you'll receive a payment_id that you can use to poll the
 `,
       example: "550e8400-e29b-41d4-a716-446655440000"
     },
+    status: {
+      type: "string",
+      enum: ["pending", "completed", "failed", "cancelled"],
+      description: `Current status of the payment, with the same meaning as on
+/v1/payments/{paymentId}/status:
+- \`pending\`: accepted and being processed
+- \`completed\`: successfully delivered
+- \`failed\`: failed (funds returned if escrowed)
+- \`cancelled\`: cancelled before completion
+
+Present on every response. \`completed\` is always accompanied by
+fulfillment_confirmation; \`failed\` is accompanied by \`error\` where a reason has
+been recorded.
+`
+    },
+    idempotent_replay: {
+      type: "boolean",
+      description: `Whether this response describes a payment that already existed, rather than one
+created by this request. \`true\` means the request_id had been used before and you
+are being handed the ORIGINAL payment \u2014 no second payment was created and nothing
+additional was charged.
+
+**Re-attempting a payment.** Re-submit the same request and you get the same payment
+back. You may re-send the original bytes unchanged: the deadlines will have expired by
+then \u2014 \`quote_deadline\` bounds the auction and is short, while this endpoint may hold a
+submission for up to 30 seconds \u2014 and an expired deadline on a re-submission is not an
+error, because the request is resolved onto the payment that already exists rather than
+used to create one.
+
+Re-signing with fresh deadlines is equally fine and returns the same payment. What you
+must NOT change is the request_id, and what you must not change under it is the
+payment's economics \u2014 source, destination, fulfillment_amount, max_source_amount \u2014 which
+are rejected with 409 IDEMPOTENCY_TERMS_MISMATCH. Deadlines and the signature are
+exempt precisely so that a re-attempt is possible.
+
+A genuinely new payment needs a NEW request_id. In particular a \`failed\` payment is
+terminal: re-submitting its request_id keeps returning that dead payment, so recovering
+means starting a new one under a new key.
+
+Present on every response, \`false\` for a newly created payment. A response without
+the field is from a gateway predating it, not a newly created payment.
+
+This is the field to read when reconciling a suspected double charge: two
+submissions where the second reports \`true\` are one payment, whereas two both
+reporting \`false\` are two. It says nothing about how far the payment has got \u2014
+read \`status\` for that.
+`,
+      example: false
+    },
     fulfillment_confirmation: {
       "$ref": "#/components/schemas/FulfillmentConfirmation"
+    },
+    error: {
+      "$ref": "#/components/schemas/PaymentError"
     }
   }
 };

package/docs/idempotency.md

@@ -20,11 +20,15 @@ fresh `request_id` only for a genuinely new payment.
 ### 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, 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.
+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
 
@@ -34,12 +38,88 @@ 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.
 
-The caveat runs in both directions. 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. Equally, reusing a `request_id` with different terms
-(a corrected amount, a different token) returns the **original** payment rather
-than an error, so the new terms are silently dropped. A genuinely new payment
-always needs a new id.
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atumlabs/payment-gateway-client",
-  "version": "2.1.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",