@atumlabs/payment-gateway-client 2.1.0 → 2.2.0

package/dist/cli/send-payment.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,
@@ -5068,8 +5149,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
@@ -5086,6 +5185,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"
@@ -5972,7 +6076,74 @@ function parseSeconds(optionName) {
 }
 
 // src/version.ts
-var PACKAGE_VERSION = true ? "2.1.0" : "0.0.0-dev";
+var PACKAGE_VERSION = true ? "2.2.0" : "0.0.0-dev";
+
+// src/cli/payment-outcome.ts
+var EXIT_COMPLETED = 0;
+var EXIT_ERROR = 1;
+var EXIT_PENDING = 2;
+var EXIT_TERMINAL_FAILURE = 3;
+function isTerminalStatus(status) {
+  return status === "completed" || status === "failed" || status === "cancelled";
+}
+function describePaymentOutcome(input) {
+  const { status, paymentId, requestId, idempotentReplay, errorCode } = input;
+  const payment = paymentId ? `payment ${paymentId}` : "the payment";
+  const replay = idempotentReplay ? " This is the payment your earlier attempt created \u2014 nothing additional was charged." : "";
+  if (status === "completed") {
+    return {
+      exitCode: EXIT_COMPLETED,
+      summary: `completed: ${payment} settled.${replay}`
+    };
+  }
+  if (status === "failed" || status === "cancelled") {
+    const reason = errorCode ? ` (${errorCode})` : "";
+    return {
+      exitCode: EXIT_TERMINAL_FAILURE,
+      summary: `${status}: ${payment} ended without settling${reason}. This is final \u2014 re-submitting ${requestId ? `request id ${requestId}` : "the same request id"} returns this same failed payment, so a fresh attempt needs a NEW request id.`
+    };
+  }
+  const resubmit = requestId ? `request id ${requestId}` : "the same request id";
+  return {
+    exitCode: EXIT_PENDING,
+    summary: `pending: ${payment} was accepted and is still settling.${replay} To collect the result, keep checking its status, or re-submit ${resubmit}. Do not start a new payment under a different request id \u2014 that would pay twice.`
+  };
+}
+
+// src/cli/wait-for-terminal.ts
+var DEFAULT_WAIT_SECONDS = 60;
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+async function waitForTerminalStatus(params) {
+  const {
+    fetchStatus,
+    budgetMs,
+    intervalMs = DEFAULT_POLL_INTERVAL_MS,
+    now = () => Date.now(),
+    sleep = defaultSleep,
+    onError
+  } = params;
+  const deadline = now() + budgetMs;
+  let snapshot;
+  let errorCount = 0;
+  while (now() < deadline) {
+    const remaining = deadline - now();
+    await sleep(Math.min(intervalMs, remaining));
+    try {
+      snapshot = await fetchStatus();
+    } catch (error) {
+      errorCount += 1;
+      onError?.(error);
+      continue;
+    }
+    if (isTerminalStatus(snapshot.status)) {
+      return { snapshot, timedOut: false, errorCount };
+    }
+  }
+  return { snapshot, timedOut: true, errorCount };
+}
+function defaultSleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
 
 // src/cli/send-payment.ts
 var readline = __toESM(require("readline"));
@@ -6004,7 +6175,7 @@ function loadTurnkeyConfigFromEnv() {
   };
 }
 var program = new import_commander.Command();
-program.name("send-payment").description("Send a cross-chain payment through Atum Payment Gateway").version(PACKAGE_VERSION).argument("<sender>", "Depositor address (e.g., 0xF0D0...)").argument("<amount>", "Amount to send (in smallest units, e.g., 100000 for 0.10 USDC)").argument("<sourceAsset>", "Source asset in CAIP-19 format").argument("<receiver>", "Destination account address").argument("<destinationAsset>", "Destination asset in CAIP-19 format").option("--gateway <url>", "Payment gateway URL (overrides GATEWAY_URL env; default: production-testnet)").option("--request-id <id>", "Idempotency key; seeds the on-chain deposit nonce. Reuse the same id to retry a payment safely. Omit to auto-generate a one-shot id.").option("--request-id-prefix <prefix>", "Custom request ID prefix (default: pmt-gw-cli)").option("--quote-deadline-seconds <n>", `Quote collection window in seconds (default: ${DEFAULT_PAYMENT_QUOTE_DEADLINE_SECONDS})`, parseSeconds("--quote-deadline-seconds")).option("--fulfillment-deadline-seconds <n>", `Settlement horizon in seconds (default: ${DEFAULT_FULFILLMENT_DEADLINE_SECONDS})`, parseSeconds("--fulfillment-deadline-seconds")).option("--whitelistSettler <did>", "Settler DID to whitelist (can be specified multiple times)", collect, []).option("--provider <raw|turnkey>", "Sender signing provider", "raw").option("--solana-rpc-url <url>", "Solana RPC used to read the cluster clock for issued_at (falls back to the SOLANA_RPC_URL env var, then the public endpoint for the cluster)").addHelpText("after", `
+program.name("send-payment").description("Send a cross-chain payment through Atum Payment Gateway").version(PACKAGE_VERSION).argument("<sender>", "Depositor address (e.g., 0xF0D0...)").argument("<amount>", "Amount to send (in smallest units, e.g., 100000 for 0.10 USDC)").argument("<sourceAsset>", "Source asset in CAIP-19 format").argument("<receiver>", "Destination account address").argument("<destinationAsset>", "Destination asset in CAIP-19 format").option("--gateway <url>", "Payment gateway URL (overrides GATEWAY_URL env; default: production-testnet)").option("--request-id <id>", "Idempotency key; seeds the on-chain deposit nonce. Re-run with the SAME id to re-attempt one payment \u2014 it resolves to the original instead of paying twice. Omitted, an id is generated and printed, which makes every bare re-run a SEPARATE payment (a second charge).").option("--request-id-prefix <prefix>", "Custom request ID prefix (default: pmt-gw-cli)").option("--quote-deadline-seconds <n>", `Quote collection window in seconds (default: ${DEFAULT_PAYMENT_QUOTE_DEADLINE_SECONDS})`, parseSeconds("--quote-deadline-seconds")).option("--fulfillment-deadline-seconds <n>", `Settlement horizon in seconds (default: ${DEFAULT_FULFILLMENT_DEADLINE_SECONDS})`, parseSeconds("--fulfillment-deadline-seconds")).option("--whitelistSettler <did>", "Settler DID to whitelist (can be specified multiple times)", collect, []).option("--provider <raw|turnkey>", "Sender signing provider", "raw").option("--wait", "After submitting, keep checking the payment until it settles or fails instead of reporting it as still pending").option("--wait-seconds <n>", `How long --wait keeps checking (default: ${DEFAULT_WAIT_SECONDS}). A convenience bound only \u2014 giving up does not affect the payment`, parseSeconds("--wait-seconds")).option("--solana-rpc-url <url>", "Solana RPC used to read the cluster clock for issued_at (falls back to the SOLANA_RPC_URL env var, then the public endpoint for the cluster)").addHelpText("after", `
 CAIP-19 Examples:
   EVM ERC20:   eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831
   Tron TRC20:  tron:shasta/trc20:TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs
@@ -6019,6 +6190,23 @@ Signing (default --provider raw):
 Output:
   PaymentRequest JSON  \u2192 stderr (for debugging/logging)
   PaymentResponse JSON \u2192 stdout (for parsing/automation)
+  Outcome summary      \u2192 stderr
+
+With --wait the JSON is printed once the wait ends, reporting the payment's state
+as of the last check rather than as of the submit.
+
+Exit codes:
+  0  completed \u2014 settled
+  2  pending   \u2014 accepted, no result yet; follow it with payment-status <payment_id>,
+                 or use --wait
+  3  failed    \u2014 terminal; a fresh attempt needs a NEW --request-id
+  1  no outcome obtained (rejected, unreachable gateway, bad arguments)
+
+So \`send-payment ... && <next step>\` runs the next step only for a settled payment.
+
+Exit 1 means unknown, not "nothing happened" \u2014 a request that timed out may still
+have been accepted, and you may have no payment_id to look up. Re-run with the same
+--request-id, which resolves to the payment if one was created and creates it if not.
 
 After submission, you can check payment status at eg http://PAYMENT_GW/v1/payments/PAYMENT_ID/status
 
@@ -6073,8 +6261,37 @@ TPUqJPASUn1zLvbLBgRZ5pBYrx7WSe5ahp on Shasta)`).action(async (sender, amount, so
     const response = await client.payments.submitPayment({
       requestBody: paymentRequest
     });
-    console.log(JSON.stringify(response, null, 2));
-    process.exit(0);
+    let reported = response;
+    if (options.wait && response.payment_id && !isTerminalStatus(response.status)) {
+      const waitSeconds = options.waitSeconds ?? DEFAULT_WAIT_SECONDS;
+      console.error(`waiting up to ${waitSeconds}s for ${response.payment_id} to settle...`);
+      const paymentId = response.payment_id;
+      const waited = await waitForTerminalStatus({
+        budgetMs: waitSeconds * 1e3,
+        fetchStatus: () => client.payments.getPaymentStatus({ paymentId }),
+        // A blip mid-settlement is the worst moment to give up, so report and keep checking.
+        onError: (err) => console.error(`status check failed, still waiting: ${err instanceof Error ? err.message : String(err)}`)
+      });
+      if (waited.snapshot) {
+        reported = { ...reported, ...waited.snapshot };
+      }
+      if (waited.timedOut) {
+        console.error(`still not settled after ${waitSeconds}s \u2014 reporting it as pending.`);
+      }
+    }
+    console.log(JSON.stringify(reported, null, 2));
+    const outcome = {
+      status: reported.status,
+      paymentId: reported.payment_id,
+      requestId,
+      idempotentReplay: reported.idempotent_replay,
+      // Present when the gateway has recorded a reason — which includes the case where this
+      // submission was deduplicated onto a payment that had already failed.
+      errorCode: reported.error?.code
+    };
+    const { exitCode, summary } = describePaymentOutcome(outcome);
+    console.error(summary);
+    process.exit(exitCode);
   } catch (error) {
     if (error instanceof ApiError && error.body) {
       console.log(JSON.stringify(error.body, null, 2));
@@ -6088,7 +6305,7 @@ TPUqJPASUn1zLvbLBgRZ5pBYrx7WSe5ahp on Shasta)`).action(async (sender, amount, so
     if (requestId) {
       console.error(`request_id: ${requestId}  (re-run with --request-id ${requestId} to retry this same payment)`);
     }
-    process.exit(1);
+    process.exit(EXIT_ERROR);
   }
 });
 async function promptPrivateKey() {