@atumlabs/payment-gateway-client 3.0.0 → 3.0.1

package/dist/index.js

@@ -1,8 +1,6 @@
 /*
- * Copyright (c) 2026 Atum Labs, Inc. All rights reserved.
- * Proprietary and confidential.
- * Access and use are governed by the LICENSE file distributed with this package.
- * Do not remove, alter, or obscure this notice.
+ * Copyright 2026 Atum Labs, Inc.
+ * SPDX-License-Identifier: Apache-2.0
  */
 "use strict";
 var __create = Object.create;
@@ -11,11 +9,20 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -2105,7 +2112,7 @@ var require_errors2 = __commonJS({
   "../contracts/svm/escrow-encoding/typescript/dist/errors.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.DestinationTooLongError = exports2.EmptyDestinationError = exports2.ZeroSourceAmountError = exports2.ZeroQuoteHashError = exports2.InvalidHexError = exports2.InvalidBase58Error = exports2.InvalidPubkeyLengthError = exports2.ZeroDepositHashError = exports2.ZeroRecipientError = exports2.ZeroReleaserError = exports2.ZeroReserverError = exports2.ZeroAmountError = exports2.ZeroMintError = exports2.ZeroDepositorError = exports2.ZeroDepositRequestHashError = exports2.EncodingError = void 0;
+    exports2.InvalidEscrowDomainError = exports2.DestinationTooLongError = exports2.EmptyDestinationError = exports2.ZeroSourceAmountError = exports2.ZeroQuoteHashError = exports2.InvalidHexError = exports2.InvalidBase58Error = exports2.InvalidPubkeyLengthError = exports2.ZeroDepositHashError = exports2.ZeroRecipientError = exports2.ZeroReleaserError = exports2.ZeroReserverError = exports2.ZeroAmountError = exports2.ZeroMintError = exports2.ZeroDepositorError = exports2.ZeroDepositRequestHashError = exports2.EncodingError = void 0;
     var EncodingError = class extends Error {
       constructor(message) {
         super(message);
@@ -2218,6 +2225,13 @@ var require_errors2 = __commonJS({
       }
     };
     exports2.DestinationTooLongError = DestinationTooLongError;
+    var InvalidEscrowDomainError = class extends EncodingError {
+      constructor(message) {
+        super(message);
+        this.name = "InvalidEscrowDomainError";
+      }
+    };
+    exports2.InvalidEscrowDomainError = InvalidEscrowDomainError;
   }
 });
 
@@ -2926,12 +2940,17 @@ var require_escrow_domain = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.escrowDomainPrefixBytes = escrowDomainPrefixBytes;
+    exports2.newEscrowDomain = newEscrowDomain;
+    var errors_1 = require_errors2();
     function escrowDomainPrefixBytes(domain) {
       if (domain.clusterId.length !== 32) {
-        throw new Error(`EscrowDomain.clusterId must be 32 bytes, got ${domain.clusterId.length}`);
+        throw new errors_1.InvalidEscrowDomainError(`EscrowDomain.clusterId must be 32 bytes, got ${domain.clusterId.length}`);
+      }
+      if (domain.programId.isZero()) {
+        throw new errors_1.InvalidEscrowDomainError("EscrowDomain.programId cannot be zero");
       }
       if (!Number.isInteger(domain.signatureDomainVersion) || domain.signatureDomainVersion < 1 || domain.signatureDomainVersion > 255) {
-        throw new Error(`EscrowDomain.signatureDomainVersion must be an integer in 1..=255, got ${domain.signatureDomainVersion}`);
+        throw new errors_1.InvalidEscrowDomainError(`EscrowDomain.signatureDomainVersion must be an integer in 1..=255, got ${domain.signatureDomainVersion}`);
       }
       return [
         new TextEncoder().encode("escrow"),
@@ -2940,6 +2959,25 @@ var require_escrow_domain = __commonJS({
         domain.programId.toBytes()
       ];
     }
+    function newEscrowDomain(clusterName, signatureDomainVersion, programId) {
+      const trimmed = clusterName.trim();
+      if (trimmed.length === 0) {
+        throw new errors_1.InvalidEscrowDomainError("EscrowDomain cluster name cannot be empty");
+      }
+      const encoded = new TextEncoder().encode(trimmed);
+      if (encoded.length > 32) {
+        throw new errors_1.InvalidEscrowDomainError(`EscrowDomain cluster name "${trimmed}" exceeds 32 bytes`);
+      }
+      if (!Number.isInteger(signatureDomainVersion) || signatureDomainVersion < 1 || signatureDomainVersion > 255) {
+        throw new errors_1.InvalidEscrowDomainError(`EscrowDomain.signatureDomainVersion must be an integer in 1..=255, got ${signatureDomainVersion}`);
+      }
+      if (programId.isZero()) {
+        throw new errors_1.InvalidEscrowDomainError("EscrowDomain.programId cannot be zero");
+      }
+      const clusterId = new Uint8Array(32);
+      clusterId.set(encoded);
+      return { clusterId, signatureDomainVersion, programId };
+    }
   }
 });
 
@@ -3138,7 +3176,7 @@ var require_dist4 = __commonJS({
   "../contracts/svm/escrow-encoding/typescript/dist/index.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.DEPOSIT_COMPUTE_UNIT_LIMIT = exports2.REPLAY_BUCKETS = exports2.MAX_VALID_SLOT = exports2.REPLAY_SLOTS = exports2.generateNonce = exports2.computeRefundHashV2 = exports2.computeRefundHash = exports2.computeReleaseHashV2 = exports2.computeReleaseHash = exports2.computeReserveHashV3 = exports2.computeReserveHashV2 = exports2.computeReserveHash = exports2.MAX_DESTINATION_LEN = exports2.computeDestinationHash = exports2.computeDepositHashV2 = exports2.computeDepositHash = exports2.InvalidHexError = exports2.InvalidBase58Error = exports2.InvalidPubkeyLengthError = exports2.ZeroDepositHashError = exports2.ZeroRecipientError = exports2.ZeroReleaserError = exports2.ZeroReserverError = exports2.ZeroAmountError = exports2.ZeroMintError = exports2.ZeroDepositorError = exports2.DestinationTooLongError = exports2.EmptyDestinationError = exports2.ZeroQuoteHashError = exports2.ZeroDepositRequestHashError = exports2.EncodingError = exports2.escrowDomainPrefixBytes = exports2.isZeroBytes32 = exports2.stringToBytes = exports2.keccak256 = exports2.encodeU64LE = exports2.Pubkey = void 0;
+    exports2.DEPOSIT_COMPUTE_UNIT_LIMIT = exports2.REPLAY_BUCKETS = exports2.MAX_VALID_SLOT = exports2.REPLAY_SLOTS = exports2.generateNonce = exports2.computeRefundHashV2 = exports2.computeRefundHash = exports2.computeReleaseHashV2 = exports2.computeReleaseHash = exports2.computeReserveHashV3 = exports2.computeReserveHashV2 = exports2.computeReserveHash = exports2.MAX_DESTINATION_LEN = exports2.computeDestinationHash = exports2.computeDepositHashV2 = exports2.computeDepositHash = exports2.InvalidHexError = exports2.InvalidBase58Error = exports2.InvalidPubkeyLengthError = exports2.InvalidEscrowDomainError = exports2.ZeroSourceAmountError = exports2.ZeroDepositHashError = exports2.ZeroRecipientError = exports2.ZeroReleaserError = exports2.ZeroReserverError = exports2.ZeroAmountError = exports2.ZeroMintError = exports2.ZeroDepositorError = exports2.DestinationTooLongError = exports2.EmptyDestinationError = exports2.ZeroQuoteHashError = exports2.ZeroDepositRequestHashError = exports2.EncodingError = exports2.newEscrowDomain = exports2.escrowDomainPrefixBytes = exports2.isZeroBytes32 = exports2.stringToBytes = exports2.keccak256 = exports2.encodeU64LE = exports2.Pubkey = void 0;
     var pubkey_1 = require_pubkey();
     Object.defineProperty(exports2, "Pubkey", { enumerable: true, get: function() {
       return pubkey_1.Pubkey;
@@ -3160,6 +3198,9 @@ var require_dist4 = __commonJS({
     Object.defineProperty(exports2, "escrowDomainPrefixBytes", { enumerable: true, get: function() {
       return escrow_domain_1.escrowDomainPrefixBytes;
     } });
+    Object.defineProperty(exports2, "newEscrowDomain", { enumerable: true, get: function() {
+      return escrow_domain_1.newEscrowDomain;
+    } });
     var errors_1 = require_errors2();
     Object.defineProperty(exports2, "EncodingError", { enumerable: true, get: function() {
       return errors_1.EncodingError;
@@ -3197,6 +3238,12 @@ var require_dist4 = __commonJS({
     Object.defineProperty(exports2, "ZeroDepositHashError", { enumerable: true, get: function() {
       return errors_1.ZeroDepositHashError;
     } });
+    Object.defineProperty(exports2, "ZeroSourceAmountError", { enumerable: true, get: function() {
+      return errors_1.ZeroSourceAmountError;
+    } });
+    Object.defineProperty(exports2, "InvalidEscrowDomainError", { enumerable: true, get: function() {
+      return errors_1.InvalidEscrowDomainError;
+    } });
     Object.defineProperty(exports2, "InvalidPubkeyLengthError", { enumerable: true, get: function() {
       return errors_1.InvalidPubkeyLengthError;
     } });
@@ -5477,6 +5524,7 @@ var require_policies = __commonJS({
     exports2.buildDenyApproveToNonAllowedSpenderTron = buildDenyApproveToNonAllowedSpenderTron;
     exports2.listPolicies = listPolicies;
     exports2.deletePolicy = deletePolicy;
+    exports2.planPolicyChanges = planPolicyChanges;
     exports2.applyPolicies = applyPolicies;
     function derivePoliciesFromAllowlist(policy, chain, context) {
       const policies = [];
@@ -5664,26 +5712,54 @@ var require_policies = __commonJS({
         policyId
       });
     }
+    function planPolicyChanges(existing, policies) {
+      const existingByName = new Map(existing.map((p) => [p.policyName, p]));
+      const drifted = [];
+      for (const p of policies) {
+        const prev = existingByName.get(p.policyName);
+        if (!prev)
+          continue;
+        const matches = prev.effect === p.effect && prev.condition === p.condition && (prev.consensus ?? "") === (p.consensus ?? "");
+        if (!matches)
+          drifted.push({ name: p.policyName, diff: formatPolicyDiff(prev, p) });
+      }
+      const emittedNames = new Set(policies.map((p) => p.policyName));
+      const stale = existing.filter((p) => !emittedNames.has(p.policyName));
+      const seen = /* @__PURE__ */ new Set();
+      const duplicateNames = [
+        ...new Set(existing.filter((p) => !(seen.size === seen.add(p.policyName).size)).map((p) => p.policyName))
+      ];
+      return { drifted, stale, duplicateNames };
+    }
     async function applyPolicies(client, policies, options) {
       const existing = await listPolicies(client, options.organizationId);
       const existingByName = new Map(existing.map((p) => [p.policyName, p]));
       const created = [];
       const skippedUnchanged = [];
-      const drifted = [];
       const replaced = [];
+      const pruned = [];
+      const { drifted, stale } = planPolicyChanges(existing, policies);
+      if (stale.length > 0 && !options.prune) {
+        const detail = stale.map((p) => `  - ${p.policyName} [${p.effect}] (${p.policyId})`).join("\n");
+        throw new Error(`${stale.length} live polic${stale.length === 1 ? "y is" : "ies are"} absent from the emitted set:
+${detail}
+
+A retired ALLOW left live keeps granting what it always granted, so a narrower replacement does not take effect until it is gone. Re-run with --prune to delete them, or reconcile the config if they are policies this set should still emit.`);
+      }
+      if (drifted.length > 0 && !options.update) {
+        const detail = drifted.map((d) => `  - ${d.name}:
+${indent(d.diff, "      ")}`).join("\n");
+        throw new Error(`Content drift detected on ${drifted.length} polic${drifted.length === 1 ? "y" : "ies"}. Re-run with --update to delete-and-recreate, or fix the existing policy in the Turnkey console.
+${detail}`);
+      }
+      const driftedNames = new Set(drifted.map((d) => d.name));
       for (const p of policies) {
         const prev = existingByName.get(p.policyName);
         if (prev) {
-          const matches = prev.effect === p.effect && prev.condition === p.condition && (prev.consensus ?? "") === (p.consensus ?? "");
-          if (matches) {
+          if (!driftedNames.has(p.policyName)) {
             skippedUnchanged.push(p.policyName);
             continue;
           }
-          const diff = formatPolicyDiff(prev, p);
-          if (!options.update) {
-            drifted.push({ name: p.policyName, diff });
-            continue;
-          }
           await deletePolicy(client, prev.policyId);
           const newId = await createPolicyRaw(client, p);
           replaced.push({ name: p.policyName, oldPolicyId: prev.policyId, newPolicyId: newId });
@@ -5693,13 +5769,11 @@ var require_policies = __commonJS({
         const id = await createPolicyRaw(client, p);
         created.push(id);
       }
-      if (drifted.length > 0) {
-        const detail = drifted.map((d) => `  - ${d.name}:
-${indent(d.diff, "      ")}`).join("\n");
-        throw new Error(`Content drift detected on ${drifted.length} polic${drifted.length === 1 ? "y" : "ies"}. Re-run with --update to delete-and-recreate, or fix the existing policy in the Turnkey console.
-${detail}`);
+      for (const p of stale) {
+        await deletePolicy(client, p.policyId);
+        pruned.push({ name: p.policyName, policyId: p.policyId });
       }
-      return { created, skippedUnchanged, replaced };
+      return { created, skippedUnchanged, replaced, pruned };
     }
     async function createPolicyRaw(client, p) {
       const result = await client.executeActivity("ACTIVITY_TYPE_CREATE_POLICY_V3", "create_policy", {
@@ -5745,6 +5819,8 @@ var require_sender_policies = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.TRON_PERMIT2 = exports2.EVM_PERMIT2 = void 0;
+    exports2.tronTip712ChainId = tronTip712ChainId;
+    exports2.toTronEvmHex = toTronEvmHex;
     exports2.buildSenderPolicies = buildSenderPolicies;
     exports2.tronBase58ToEvmHex = tronBase58ToEvmHex;
     var node_crypto_1 = require("crypto");
@@ -5754,6 +5830,57 @@ var require_sender_policies = __commonJS({
       shasta: "TPUqJPASUn1zLvbLBgRZ5pBYrx7WSe5ahp"
     };
     var APPROVE_SELECTOR = "0x095ea7b3";
+    var PERMIT2_PRIMARY_TYPE = "PermitWitnessTransferFrom";
+    var PERMIT2_DOMAIN_NAME = "Permit2";
+    var TRON_TIP712_CHAIN_IDS = {
+      mainnet: 728126428,
+      shasta: 2494104990
+    };
+    function tronTip712ChainId(caip2) {
+      const cluster = caip2.split(":")[1] ?? "";
+      const id = Object.hasOwn(TRON_TIP712_CHAIN_IDS, cluster) ? TRON_TIP712_CHAIN_IDS[cluster] : void 0;
+      if (id === void 0) {
+        throw new Error(`Sender extras: unsupported Tron network "${caip2}". Known clusters: ${Object.keys(TRON_TIP712_CHAIN_IDS).join(", ")}.`);
+      }
+      return (id & 4294967295) >>> 0;
+    }
+    function evmNumericChainId(caip2) {
+      const id = Number.parseInt(caip2.split(":")[1] ?? "", 10);
+      if (!Number.isSafeInteger(id) || id <= 0) {
+        throw new Error(`Sender extras: chain id "${caip2}" is not a usable eip155 CAIP-2 identifier.`);
+      }
+      return id;
+    }
+    var lower = (a) => a.toLowerCase();
+    function assertEvmAddress(address, chainKey) {
+      if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+        throw new Error(`Sender extras: ${JSON.stringify(address)} on chain "${chainKey}" is not a 20-byte 0x hex address. A malformed literal matches nothing, which denies every payment on this chain.`);
+      }
+      return address;
+    }
+    function toTronEvmHex(address) {
+      if (address.startsWith("T"))
+        return `0x${tronBase58ToEvmHex(address)}`;
+      if (/^0x[0-9a-fA-F]{40}$/.test(address))
+        return lower(address);
+      throw new Error(`Sender extras: Tron address ${JSON.stringify(address)} is neither a base58 (T\u2026) address nor a 20-byte 0x hex address, so its TIP-712 message form cannot be derived.`);
+    }
+    var quotedLower = (xs) => xs.map((x) => `'${lower(x)}'`).join(", ");
+    function quotedExact(xs, chainKey) {
+      for (const x of xs) {
+        if (x.includes("'") || x.includes("\\")) {
+          throw new Error(`Sender extras: destination ${JSON.stringify(x)} on chain "${chainKey}" contains a quote or backslash, which cannot appear in a policy condition literal.`);
+        }
+        if (x.length === 0 || !x.includes("@")) {
+          throw new Error(`Sender extras: destination ${JSON.stringify(x)} on chain "${chainKey}" is not a composed destination (<caip19-asset>@<account>). Build it with buildEscrowDestination.`);
+        }
+        if (Buffer.byteLength(x, "utf8") > MAX_DESTINATION_BYTES) {
+          throw new Error(`Sender extras: destination ${JSON.stringify(x)} on chain "${chainKey}" is longer than ${MAX_DESTINATION_BYTES} bytes, which the escrow rejects as DestinationTooLong, so no deposit could ever carry it.`);
+        }
+      }
+      return xs.map((x) => `'${x}'`).join(", ");
+    }
+    var MAX_DESTINATION_BYTES = 256;
     var SOLANA_STANDARD_PROGRAMS = [
       "11111111111111111111111111111111",
       // System
@@ -5783,12 +5910,20 @@ var require_sender_policies = __commonJS({
     }
     function buildSenderPolicies(extras, chains) {
       const policies = [];
-      policies.push({
-        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 Permit2 EIP-712 (secp256k1 KECCAK256) and Solana inner-signature (ed25519) signing."
-      });
+      const permit2Evm = lower(extras.permit2 ?? exports2.EVM_PERMIT2);
+      for (const chain of chains) {
+        if (chain.kind !== "evm" && chain.kind !== "tron")
+          continue;
+        policies.push(permit2TypedDataAllow(chain, extras, permit2Evm));
+      }
+      if (chains.some((c) => c.kind === "solana")) {
+        policies.push({
+          policyName: "allowEd25519RawPayload",
+          effect: "EFFECT_ALLOW",
+          condition: `activity.type == 'ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2' && activity.params.encoding in ['PAYLOAD_ENCODING_HEXADECIMAL', 'PAYLOAD_ENCODING_TEXT_UTF8'] && activity.params.hash_function == 'HASH_FUNCTION_NOT_APPLICABLE'`,
+          notes: "Solana deposit inner signature (ed25519 over the deposit digest). Legal on secp256k1 only with EIP712, which the API enforces, so this stays an ed25519-only path."
+        });
+      }
       for (const chain of chains) {
         if (chain.kind === "evm") {
           const evmChainId = parseInt(chain.chainId.split(":")[1], 10);
@@ -5797,7 +5932,7 @@ var require_sender_policies = __commonJS({
             throw new Error(`Sender extras: chain "${chain.key}" has no allowedTokens. Add at least one ERC-20 contract address the sender's wallet is permitted to approve, or remove this chain.`);
           }
           const tokenList = tokens.map((t) => `'${t}'`).join(", ");
-          const permit2Lower = exports2.EVM_PERMIT2.replace(/^0x/, "");
+          const permit2Lower = permit2Evm.replace(/^0x/, "");
           policies.push({
             policyName: `allowApproveToPermit2 (${chain.chainId})`,
             effect: "EFFECT_ALLOW",
@@ -5887,13 +6022,70 @@ var require_sender_policies = __commonJS({
         }
       }
       policies.push({
-        policyName: "denyNoOpHash",
+        policyName: "denyNonTypedDataHashFunctions",
+        effect: "EFFECT_DENY",
+        condition: `activity.type in ['ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2', 'ACTIVITY_TYPE_SIGN_RAW_PAYLOADS'] && activity.params.hash_function in ['HASH_FUNCTION_NO_OP', 'HASH_FUNCTION_SHA256', 'HASH_FUNCTION_KECCAK256']`,
+        notes: "NO_OP signs a caller-chosen digest as-is; KECCAK256 signs a caller-chosen preimage, which reproduces any EIP-712 digest and bypasses every typed-data condition."
+      });
+      policies.push({
+        policyName: "denyAccountDelegationEncoding",
         effect: "EFFECT_DENY",
-        condition: `activity.type in ['ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2', 'ACTIVITY_TYPE_SIGN_RAW_PAYLOADS'] && activity.params.hash_function == 'HASH_FUNCTION_NO_OP'`,
-        notes: "Sender never uses NO_OP; NOT_APPLICABLE is the only allowed raw-payload hash mode."
+        condition: `activity.type in ['ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2', 'ACTIVITY_TYPE_SIGN_RAW_PAYLOADS'] && activity.params.encoding == 'PAYLOAD_ENCODING_EIP7702_AUTHORIZATION'`,
+        notes: "One signature would delegate the sender EOA to an attacker contract."
+      });
+      policies.push({
+        policyName: "denyBatchRawPayloads",
+        effect: "EFFECT_DENY",
+        condition: `activity.type == 'ACTIVITY_TYPE_SIGN_RAW_PAYLOADS'`,
+        notes: "Message conditions bind one payload of a batch, so a second could ride along unbound."
       });
       return policies;
     }
+    function permit2TypedDataAllow(chain, extras, permit2Evm) {
+      const escrowsRaw = extras.escrows?.[chain.key] ?? [];
+      if (escrowsRaw.length === 0) {
+        throw new Error(`Sender extras: chain "${chain.key}" has no escrows. Permit2 leaves the transfer recipient out of the signed struct, so the escrow named as \`spender\` IS the funds destination \u2014 without it a stolen key can authorize a pull to anywhere. Read it from payment-gw /v1/defaults?chain_id=${chain.chainId} (escrow_contract).`);
+      }
+      const isTron = chain.kind === "tron";
+      const tronCluster = isTron ? chain.chainId.split(":")[1] ?? "" : "";
+      if (isTron) {
+        const expected = extras.network === "mainnet" ? "mainnet" : "shasta";
+        if (tronCluster !== expected) {
+          throw new Error(`Sender extras: network "${extras.network}" selects the ${expected} Permit2 deployment, but chain "${chain.key}" is "${chain.chainId}". The domain would carry one cluster's Permit2 with another's chain id, which matches no signature the runtime produces.`);
+        }
+      }
+      const permit2 = isTron ? `0x${tronBase58ToEvmHex(exports2.TRON_PERMIT2[tronCluster])}` : permit2Evm;
+      const chainIdValue = isTron ? tronTip712ChainId(chain.chainId) : evmNumericChainId(chain.chainId);
+      const addr = (xs) => quotedLower(xs.map((x) => isTron ? toTronEvmHex(x) : assertEvmAddress(x, chain.key)));
+      const tokens = extras.allowedTokens[chain.key] ?? [];
+      if (tokens.length === 0) {
+        throw new Error(`Sender extras: chain "${chain.key}" has no allowedTokens, so the typed-data allow would not bind which token the permit moves.`);
+      }
+      const tokenClause = ` && eth.eip_712.message['permitted']['token'] in [${addr(tokens)}]`;
+      const reservers = extras.reservers?.[chain.key] ?? [];
+      const releasers = extras.releasers?.[chain.key] ?? [];
+      for (const [role, vals, field] of [
+        ["reservers", reservers, "quote_selector"],
+        ["releasers", releasers, "fulfillment_verifier.account"]
+      ]) {
+        if (vals.length === 0) {
+          throw new Error(`Sender extras: chain "${chain.key}" has no ${role}. Either witness role can divert funds at settlement and the payer pins neither client-side, so leaving this unset is a hole this policy set is meant to close. Read it from payment-gw /v1/defaults?chain_id=${chain.chainId} (${field}).`);
+        }
+      }
+      const reserverClause = ` && eth.eip_712.message['witness']['reserver'] in [${addr(reservers)}]`;
+      const releaserClause = ` && eth.eip_712.message['witness']['releaser'] in [${addr(releasers)}]`;
+      const destinations = extras.allowedDestinations?.[chain.key] ?? [];
+      if (destinations.length === 0) {
+        throw new Error(`Sender extras: chain "${chain.key}" has no allowedDestinations. Without them a stolen key can authorize a deposit whose payout instruction names the attacker, which is the hole this policy set exists to close. Compose each entry with buildEscrowDestination, or remove the chain.`);
+      }
+      const destinationClause = ` && eth.eip_712.message['witness']['destination'] in [${quotedExact(destinations, chain.key)}]`;
+      return {
+        policyName: `allowPermit2DepositTypedData (${chain.chainId})`,
+        effect: "EFFECT_ALLOW",
+        condition: `activity.type == 'ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2' && activity.params.encoding == 'PAYLOAD_ENCODING_EIP712' && activity.params.hash_function == 'HASH_FUNCTION_NOT_APPLICABLE' && eth.eip_712.primary_type == '${PERMIT2_PRIMARY_TYPE}' && eth.eip_712.domain.name == '${PERMIT2_DOMAIN_NAME}' && eth.eip_712.domain.verifying_contract == '${permit2}' && eth.eip_712.domain.chain_id == ${chainIdValue} && eth.eip_712.message['spender'] in [${addr(escrowsRaw)}]` + tokenClause + reserverClause + releaserClause + destinationClause,
+        notes: "The sender's only fund-moving signature: a Permit2 deposit authorization into an allowlisted escrow, for an allowlisted token, committing to an allowlisted destination."
+      };
+    }
     function tronBase58ToEvmHex(b58) {
       const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
       let bn = 0n;
@@ -6197,7 +6389,7 @@ var require_admin = __commonJS({
   "../key-management/providers/turnkey/typescript/dist/admin/index.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.validateExtras = exports2.buildExtrasPolicies = exports2.tronBase58ToEvmHex = exports2.TRON_PERMIT2 = exports2.EVM_PERMIT2 = exports2.buildSenderPolicies = exports2.listPolicies = exports2.derivePoliciesFromAllowlist = exports2.deletePolicy = exports2.buildDenyApproveToNonAllowedSpenderTron = exports2.buildDenyApproveToNonAllowedSpenderEvm = exports2.buildAllowSignRawPayloadPolicy = exports2.applyPolicies = exports2.createWalletWithChainAccounts = exports2.planRevocation = exports2.listUsers = exports2.isExpiredApiKey = exports2.isDurableApiKey = exports2.getUser = exports2.findApiKeyByPublicKey = exports2.deleteApiKeys = exports2.addApiKeys = exports2.UnsafeRevocationError = exports2.MAX_API_KEYS_PER_USER = exports2.listPendingActivities = exports2.getRootQuorum = exports2.getActivity = exports2.approvedVoterIds = exports2.approveActivity = exports2.provisionAgentUser = exports2.deleteSubOrganization = exports2.listSubOrganizations = exports2.createSubOrganization = void 0;
+    exports2.validateExtras = exports2.buildExtrasPolicies = exports2.tronTip712ChainId = exports2.tronBase58ToEvmHex = exports2.toTronEvmHex = exports2.TRON_PERMIT2 = exports2.EVM_PERMIT2 = exports2.buildSenderPolicies = exports2.planPolicyChanges = exports2.listPolicies = exports2.derivePoliciesFromAllowlist = exports2.deletePolicy = exports2.buildDenyApproveToNonAllowedSpenderTron = exports2.buildDenyApproveToNonAllowedSpenderEvm = exports2.buildAllowSignRawPayloadPolicy = exports2.applyPolicies = exports2.createWalletWithChainAccounts = exports2.planRevocation = exports2.listUsers = exports2.isExpiredApiKey = exports2.isDurableApiKey = exports2.getUser = exports2.findApiKeyByPublicKey = exports2.deleteApiKeys = exports2.addApiKeys = exports2.UnsafeRevocationError = exports2.MAX_API_KEYS_PER_USER = exports2.listPendingActivities = exports2.getRootQuorum = exports2.getActivity = exports2.approvedVoterIds = exports2.approveActivity = exports2.provisionAgentUser = exports2.deleteSubOrganization = exports2.listSubOrganizations = exports2.createSubOrganization = void 0;
     var sub_organizations_1 = require_sub_organizations();
     Object.defineProperty(exports2, "createSubOrganization", { enumerable: true, get: function() {
       return sub_organizations_1.createSubOrganization;
@@ -6287,6 +6479,9 @@ var require_admin = __commonJS({
     Object.defineProperty(exports2, "listPolicies", { enumerable: true, get: function() {
       return policies_1.listPolicies;
     } });
+    Object.defineProperty(exports2, "planPolicyChanges", { enumerable: true, get: function() {
+      return policies_1.planPolicyChanges;
+    } });
     var sender_policies_1 = require_sender_policies();
     Object.defineProperty(exports2, "buildSenderPolicies", { enumerable: true, get: function() {
       return sender_policies_1.buildSenderPolicies;
@@ -6297,9 +6492,15 @@ var require_admin = __commonJS({
     Object.defineProperty(exports2, "TRON_PERMIT2", { enumerable: true, get: function() {
       return sender_policies_1.TRON_PERMIT2;
     } });
+    Object.defineProperty(exports2, "toTronEvmHex", { enumerable: true, get: function() {
+      return sender_policies_1.toTronEvmHex;
+    } });
     Object.defineProperty(exports2, "tronBase58ToEvmHex", { enumerable: true, get: function() {
       return sender_policies_1.tronBase58ToEvmHex;
     } });
+    Object.defineProperty(exports2, "tronTip712ChainId", { enumerable: true, get: function() {
+      return sender_policies_1.tronTip712ChainId;
+    } });
     var extras_policies_1 = require_extras_policies();
     Object.defineProperty(exports2, "buildExtrasPolicies", { enumerable: true, get: function() {
       return extras_policies_1.buildExtrasPolicies;
@@ -6543,11 +6744,14 @@ __export(index_exports, {
   $GetPaymentStatusResponse: () => $GetPaymentStatusResponse,
   $OwnedAsset: () => $OwnedAsset,
   $PaymentBlockchainContext: () => $PaymentBlockchainContext,
-  $PaymentError: () => $PaymentError,
+  $PaymentFailure: () => $PaymentFailure,
   $PaymentRequest: () => $PaymentRequest,
   $PaymentResponse: () => $PaymentResponse,
+  $PaymentStatus: () => $PaymentStatus,
   $PaymentSummary: () => $PaymentSummary,
   $PaymentTimelineResponse: () => $PaymentTimelineResponse,
+  $PaymentTransaction: () => $PaymentTransaction,
+  $PaymentTransactions: () => $PaymentTransactions,
   $PreparePaymentRequest: () => $PreparePaymentRequest,
   $PreparePaymentResponse: () => $PreparePaymentResponse,
   $Quote: () => $Quote,
@@ -6558,7 +6762,6 @@ __export(index_exports, {
   $SenderAuth: () => $SenderAuth,
   $SenderAuthMessageScheme: () => $SenderAuthMessageScheme,
   $SignedMessage: () => $SignedMessage,
-  $TimelineError: () => $TimelineError,
   $TimelineStep: () => $TimelineStep,
   $VerifiableCredential: () => $VerifiableCredential,
   $VerifiableCredentialAuth: () => $VerifiableCredentialAuth,
@@ -7501,6 +7704,9 @@ var PaymentGatewayClient = class {
   }
 };
 
+// src/timeout-http-request.ts
+var import_axios2 = __toESM(require("axios"));
+
 // src/errors.ts
 var GatewayTimeoutError = class extends Error {
   constructor(baseUrl, timeoutMs) {
@@ -7574,6 +7780,12 @@ function isAxiosTimeout(error) {
   if (failure.code === "ECONNABORTED" || failure.code === "ETIMEDOUT") return true;
   return failure.code === "ERR_BAD_RESPONSE" && /stream has been aborted/i.test(failure.message ?? "");
 }
+function dropPartialResponseOnTimeout(error) {
+  if (isAxiosTimeout(error) && error !== null && typeof error === "object" && "response" in error) {
+    delete error.response;
+  }
+  return error;
+}
 function translateTimeout(error, baseUrl, fallbackTimeoutMs) {
   if (!isAxiosTimeout(error)) return error;
   const configured = error.config?.timeout;
@@ -7581,6 +7793,11 @@ function translateTimeout(error, baseUrl, fallbackTimeoutMs) {
 }
 
 // src/timeout-http-request.ts
+var timeoutAxios = import_axios2.default.create();
+timeoutAxios.interceptors.response.use(
+  void 0,
+  (error) => Promise.reject(dropPartialResponseOnTimeout(error))
+);
 function withRequestTimeout(config, timeouts) {
   const request2 = new Interceptors();
   for (const fn of config?.interceptors?.request?._fns ?? []) request2.use(fn);
@@ -7596,7 +7813,7 @@ var TimeoutHttpRequest = class extends AxiosHttpRequest {
   }
   request(options) {
     return new CancelablePromise((resolve2, reject, onCancel) => {
-      const pending = super.request(options);
+      const pending = request(this.config, options, timeoutAxios);
       onCancel(() => pending.cancel());
       pending.then(resolve2, (error) => {
         const request2 = { method: options.method, url: options.url, wait: options.query?.wait };
@@ -8046,7 +8263,7 @@ a past value is rejected with 400.`,
       type: "string",
       format: "date-time",
       description: `Required. The final deadline for completing the payment. If not completed by this time the
-payment is cancelled and eligible for a refund. The gateway injects no default and validates
+payment fails and is eligible for a refund. The gateway injects no default and validates
 the value is in the future. The originator must supply it, and a request that omits it or
 supplies a past value is rejected with 400.`,
       example: "2024-12-25T11:00:00Z"
@@ -8394,6 +8611,104 @@ var $VerifiableCredential = {
     }
   }
 };
+var $PaymentStatus = {
+  type: "string",
+  description: `Where your payment is in its lifecycle. One payment reads the same however you ask
+about it.
+
+- \`pending\`: accepted and in progress. Nothing has reached the recipient yet.
+- \`finalizing\`: the transaction paying your recipient is on chain and is accruing
+  the confirmations its chain requires. NOT FINAL, see below.
+- \`completed\`: delivered, with the required confirmations behind it.
+- \`failed\`: did not complete. Any funds held in escrow are returned, and \`error\`
+  describes what went wrong.
+
+\`completed\` and \`failed\` are final and will not change afterwards. \`pending\` and
+\`finalizing\` will.
+
+**Do not treat \`finalizing\` as delivered.** It says the payment has been made on
+chain but is not yet irreversible, much as a card authorization is not yet a
+settlement. It normally becomes \`completed\`, and it can still become \`failed\` if
+the transaction never reaches the confirmation depth its chain requires. Acting on
+\`finalizing\` \u2014 releasing goods, crediting an account \u2014 means accepting that risk
+deliberately, at whatever threshold suits you rather than the one we wait for.
+
+\`finalizing\` is about paying the recipient. While your own funds are still being
+committed on the source chain the payment is \`pending\`, because nothing has reached
+the recipient yet.
+`,
+  enum: ["pending", "finalizing", "completed", "failed"],
+  example: "pending"
+};
+var $PaymentTransaction = {
+  type: "object",
+  description: `One on-chain transaction belonging to a payment: which chain, which transaction, and
+which block it landed in.
+
+Whether the payment has actually happened is answered by \`status\`, not here. Read this
+to look the transaction up on chain and to verify it yourself.
+`,
+  required: ["transaction_hash", "chain_id"],
+  properties: {
+    transaction_hash: {
+      type: "string",
+      description: `The transaction's hash on its chain. Hex hashes carry the \`0x\` prefix, including on
+Tron, whose own tooling omits it.
+`,
+      pattern: "^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{32,88})$",
+      example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
+    },
+    chain_id: {
+      type: "string",
+      description: "CAIP-2 identifier of the chain the transaction is on.",
+      pattern: "^[a-z0-9]+:[a-zA-Z0-9_-]+$",
+      example: "eip155:42161"
+    },
+    block_number: {
+      type: "integer",
+      description: `The block the transaction landed in. Absent until it has been mined.
+
+Provisional while \`status\` is \`finalizing\`: on a chain that settles against another,
+a reorganization there can move the transaction to a different block. Settled once
+\`status\` is \`completed\` \u2014 keep it as a final record only from then.
+`,
+      example: 61234567
+    }
+  }
+};
+var $PaymentTransactions = {
+  type: "object",
+  description: `The transactions a payment has produced, one entry per stage, added as each becomes
+known. A stage absent here has produced no transaction yet.
+
+These are the two movements that decide whether your payment happened: your funds
+being committed, and your recipient being paid. Present on every outcome, so a
+payment that did not complete can still be traced on chain.
+\`fulfillment_confirmation\` is not a substitute: it is written only once a payment
+completes, and describes the finished delivery rather than progress towards it.
+
+Where a stage is attempted more than once, the entry describes the attempt that
+counts \u2014 the one that succeeded, or the last one if none did.
+`,
+  properties: {
+    deposit: {
+      allOf: [
+        {
+          "$ref": "#/components/schemas/PaymentTransaction"
+        }
+      ],
+      description: "Committing your funds on the source chain."
+    },
+    fulfillment: {
+      allOf: [
+        {
+          "$ref": "#/components/schemas/PaymentTransaction"
+        }
+      ],
+      description: "Paying your recipient on the destination chain."
+    }
+  }
+};
 var $PaymentResponse = {
   type: "object",
   description: `Response from submitting a payment request. If settlement completes inside the
@@ -8401,9 +8716,9 @@ gateway's synchronous window, the response includes a fulfillment_confirmation w
 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
+Read \`status\` before deciding what to do next: a \`pending\` or \`finalizing\` payment is
+in flight and must NOT be re-submitted under a new request_id (that would be a second
+payment), whereas a \`failed\` 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.
 
@@ -8413,6 +8728,10 @@ settlement lands inside the window you get \`status: completed\`, a full
 \`quote_id\` and \`fulfillment_quote\`. The fast path therefore needs no follow-up call to
 verify: recompute \`quote_hash\` over the returned quote and compare it against the on-chain
 commitment from this response alone.
+
+\`status\` is present on every response. \`completed\` is always accompanied by
+fulfillment_confirmation; \`failed\` is accompanied by \`error\` where a reason has been
+recorded.
 `,
   required: ["payment_id", "status", "idempotent_replay"],
   properties: {
@@ -8423,19 +8742,10 @@ commitment from this response alone.
       example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f"
     },
     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.
-`
+      "$ref": "#/components/schemas/PaymentStatus"
+    },
+    transactions: {
+      "$ref": "#/components/schemas/PaymentTransactions"
     },
     idempotent_replay: {
       type: "boolean",
@@ -8498,7 +8808,7 @@ the status endpoint rather than treat the payment as unverified.
       "$ref": "#/components/schemas/FulfillmentConfirmation"
     },
     error: {
-      "$ref": "#/components/schemas/PaymentError"
+      "$ref": "#/components/schemas/PaymentFailure"
     }
   }
 };
@@ -8512,14 +8822,10 @@ var $GetPaymentStatusResponse = {
       example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f"
     },
     status: {
-      type: "string",
-      enum: ["pending", "completed", "failed", "cancelled"],
-      description: `Current status of your payment:
-- \`pending\`: Payment is being processed
-- \`completed\`: Payment successfully delivered
-- \`failed\`: Payment failed (funds returned if escrowed)
-- \`cancelled\`: Payment was cancelled before completion
-`
+      "$ref": "#/components/schemas/PaymentStatus"
+    },
+    transactions: {
+      "$ref": "#/components/schemas/PaymentTransactions"
     },
     updated_at: {
       type: "string",
@@ -8562,7 +8868,7 @@ JSON passthrough.
       "$ref": "#/components/schemas/FulfillmentConfirmation"
     },
     error: {
-      "$ref": "#/components/schemas/PaymentError"
+      "$ref": "#/components/schemas/PaymentFailure"
     },
     requested_count: {
       type: "integer",
@@ -8589,37 +8895,51 @@ As on the quote-request endpoints, the free-form decline detail is never relayed
     }
   }
 };
-var $PaymentError = {
+var $PaymentFailure = {
   type: "object",
-  description: `Error details when payment status is "failed".
-Only present when the payment has failed. Contains a machine-readable
-code for programmatic handling and a human-readable message for debugging.
+  description: `Why a payment failed. Present only when \`status\` is \`failed\`, and identical
+however you ask about the payment.
+
+\`code\` is the stable, machine-readable identity of the failure \u2014 branch on it
+rather than on \`message\`, which is written for a person and may be reworded.
+\`docs_url\` points at the page describing that code.
 `,
   required: ["code", "message"],
   properties: {
     code: {
       type: "string",
-      description: `Public error category in SCREAMING_SNAKE_CASE.
-Common codes:
-- \`SETTLEMENT_FAILED\`: The settlement could not be completed
-- \`NO_QUOTES_RECEIVED\`: No quotes arrived within the auction window
-- \`INTERNAL_ERROR\`: An unexpected error occurred
+      description: `Public error category in SCREAMING_SNAKE_CASE. Common codes:
+- \`SETTLEMENT_FAILED\`: the settlement could not be completed
+- \`NO_QUOTES_RECEIVED\`: no quotes arrived within the auction window
+- \`INTERNAL_ERROR\`: an unexpected error occurred
 `,
       example: "SETTLEMENT_FAILED"
     },
     message: {
       type: "string",
-      description: `Human-readable error description with additional context.
+      description: `Human-readable description of the failure, for a person reading it. Do not
+branch on this text.
 `,
       example: "No quotes received within the auction window"
     },
     domain: {
       type: "string",
-      description: `Service domain where the error originated.
+      description: `Which part of the system reported the failure.
 `,
       enum: ["PAYMENT_GATEWAY", "SETTLER_GATEWAY", "SETTLER_AGENT", "WALLET_ORCHESTRATION", "VERIFICATION_SERVICE", "BLOCKCHAIN", "EXTERNAL_SERVICE"],
       example: "PAYMENT_GATEWAY"
     },
+    docs_url: {
+      type: "string",
+      format: "uri",
+      description: "Link to the documentation page for this public code."
+    },
+    retry_classification: {
+      type: "string",
+      description: `What the caller should do next. Absent means the condition has not been classified, which is not the same as safe to retry.
+Re-sending the same \`request_id\` is an idempotent replay and always safe. This value is about submitting a new one, which starts a new payment. See https://docs.atum.xyz/errors for the value set.`,
+      example: "RECONCILE_THEN_DECIDE"
+    },
     blockchain_context: {
       "$ref": "#/components/schemas/PaymentBlockchainContext"
     }
@@ -8627,46 +8947,46 @@ Common codes:
 };
 var $PaymentBlockchainContext = {
   type: "object",
-  description: `Blockchain-specific error context. Only present when the error
-originated from an on-chain operation (e.g., escrow revert,
-fulfillment failure).
-`,
+  description: `Where on chain a failed payment failed. Present only when the failure happened
+on chain \u2014 an escrow revert, or a fulfillment that could not be delivered \u2014 so a
+payment that failed before any transaction was sent carries no context here.`,
   properties: {
     chain_id: {
       type: "string",
       description: "CAIP-2 chain identifier",
-      example: "eip155:42161"
+      pattern: "^[a-z0-9]+:[a-zA-Z0-9_-]+$"
     },
-    tx_hash: {
+    transaction_hash: {
       type: "string",
       description: "Failed transaction hash",
-      example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
+      pattern: "^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{32,88})$"
     },
     block_number: {
       type: "integer",
-      description: "Block number where error occurred",
-      example: 12345678
+      description: "Block number where error occurred"
     },
     contract_address: {
       type: "string",
-      description: "Contract address involved in the error",
-      example: "0x1234567890abcdef1234567890abcdef12345678"
+      description: "Contract that caused the error",
+      pattern: "^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$"
     },
     revert_reason: {
       type: "string",
-      description: "Smart contract revert reason",
-      example: "Insufficient balance"
+      description: "Smart contract revert reason"
     },
     gas_used: {
       type: "string",
-      description: "Gas consumed before failure",
-      example: "21000"
+      description: "Gas consumed before failure"
     },
     estimated_gas_needed: {
       type: "string",
-      description: "Estimated gas needed for success",
-      example: "50000"
+      description: "Estimated gas needed for success"
     }
+  },
+  "x-go-type": "atumerror.BlockchainContext",
+  "x-go-type-import": {
+    name: "atumerror",
+    path: "github.com/atum-labs/protocol/schemas/apis/error/v1/bindings/go"
   }
 };
 var $PreparePaymentRequest = {
@@ -8796,15 +9116,10 @@ structured error describing where and why.
       example: "0x8b73c3c69bb8fe3d512ecc4cf759cc79239f7b179b0ffacaa9a75d522b39400f"
     },
     status: {
-      type: "string",
-      enum: ["pending", "settling", "completed", "failed", "cancelled"],
-      description: `High-level status:
-- \`pending\`: Bidding, awarded, or early in settlement
-- \`settling\`: Settlement in progress (on-chain steps executing)
-- \`completed\`: Payment successfully delivered
-- \`failed\`: Payment failed
-- \`cancelled\`: Payment was cancelled
-`
+      "$ref": "#/components/schemas/PaymentStatus"
+    },
+    transactions: {
+      "$ref": "#/components/schemas/PaymentTransactions"
     },
     created_at: {
       type: "string",
@@ -8823,7 +9138,7 @@ structured error describing where and why.
       "$ref": "#/components/schemas/PaymentSummary"
     },
     error: {
-      "$ref": "#/components/schemas/TimelineError"
+      "$ref": "#/components/schemas/PaymentFailure"
     },
     steps: {
       type: "array",
@@ -8877,40 +9192,6 @@ Only set when the source asset's decimals are known via the token registry.
     }
   }
 };
-var $TimelineError = {
-  type: "object",
-  description: "Structured error details when a payment has failed",
-  required: ["code", "message"],
-  properties: {
-    code: {
-      type: "string",
-      description: "Machine-readable error code",
-      example: "ESCROW_DEPOSIT_FAILED"
-    },
-    message: {
-      type: "string",
-      description: "Human-readable error description"
-    },
-    domain: {
-      type: "string",
-      description: "Which component reported the error",
-      example: "SETTLER_AGENT"
-    },
-    chain_id: {
-      type: "string",
-      description: "CAIP-2 chain where the error occurred (if on-chain)",
-      example: "eip155:1"
-    },
-    tx_hash: {
-      type: "string",
-      description: "Transaction hash of the failed on-chain attempt (if applicable)"
-    },
-    revert_reason: {
-      type: "string",
-      description: "Smart-contract revert reason (if the error was an on-chain revert)"
-    }
-  }
-};
 var $TimelineStep = {
   type: "object",
   required: ["name", "label", "status"],
@@ -8951,7 +9232,7 @@ var $TimelineStep = {
       description: "CAIP-2 chain this step happened on (if on-chain)",
       example: "eip155:1"
     },
-    tx_hash: {
+    transaction_hash: {
       type: "string",
       description: "Transaction hash associated with this step (if on-chain)"
     },
@@ -9071,7 +9352,7 @@ the future. Must be strictly earlier than fulfillment_deadline.
     fulfillment_deadline: {
       type: "string",
       format: "date-time",
-      description: `Required. Final deadline for completing the payment. Past it the payment is cancelled and
+      description: `Required. Final deadline for completing the payment. Past it the payment fails and
 eligible for refund. The gateway injects no default and never mutates the
 originator-supplied body, so the value is carried through verbatim to the award call. It
 must be supplied and must be in the future. Must be strictly later than quote_deadline.
@@ -9579,9 +9860,9 @@ agent appears under one reason only.
     },
     retry_classification: {
       type: "string",
-      description: `What would have to change for a settler giving this reason to bid, drawn from the same
-closed set as the \`retry_classification\` on an error response so a caller reads one
-vocabulary.
+      description: `What would have to change for a settler giving this reason to submit a price quote,
+drawn from the same closed set as the \`retry_classification\` on an error response so
+a caller reads one vocabulary.
 
 It describes the decline only. The authoritative instruction for the payment is the
 \`retry_classification\` on its own error response: a payment can fail for a reason no
@@ -9591,6 +9872,14 @@ Optional, and a pattern-constrained string for the same reason \`DeclineReason\`
 `,
       pattern: "^[A-Z][A-Z0-9_]*$",
       example: "RETRY_AFTER_DELAY"
+    },
+    docs_url: {
+      type: "string",
+      format: "uri",
+      description: `Link to the documentation for this reason. Absent rather than empty when no page is
+published, so a reader never follows a link to the site root.
+`,
+      example: "https://docs.atum.xyz/decline-reasons#insufficient-liquidity"
     }
   }
 };
@@ -9864,7 +10153,7 @@ var $ChainDefaultsByChain = {
 
 // src/payment-tracking.ts
 function isTerminalStatus(status) {
-  return status === "completed" || status === "failed" || status === "cancelled";
+  return status === "completed" || status === "failed";
 }
 var DEFAULT_WAIT_SECONDS = 60;
 var DEFAULT_WAIT_BUDGET_MS = DEFAULT_WAIT_SECONDS * 1e3;
@@ -9983,7 +10272,7 @@ function createSolanaDepositPrehash(paymentId, params) {
 }
 function hashSolanaDeposit(_prehash) {
   throw new Error(
-    'hashSolanaDeposit computes the pre-domain-separation Solana deposit hash (199-byte preimage, no "escrow"/version/cluster_id/program_id prefix and no destination_hash). No deployed escrow program accepts it \u2014 on-chain verification rejects it with InvalidData on every cluster \u2014 so it cannot be used to build a deposit. Use the shared sender_auth adapter instead: getChainAdapter(chainId).buildAuthMessage({ ... }), which picks the preimage that matches the escrow domain version and is what the facilitator verifies against.'
+    'hashSolanaDeposit computes the pre-domain-separation Solana deposit hash (199-byte preimage, no "escrow"/version/cluster_id/program_id prefix and no destination_hash). No deployed escrow program accepts it \u2014 on-chain verification rejects it with DepositHashMismatch on every cluster \u2014 so it cannot be used to build a deposit. Use the shared sender_auth adapter instead: getChainAdapter(chainId).buildAuthMessage({ ... }), which picks the preimage that matches the escrow domain version and is what the facilitator verifies against.'
   );
 }
 function generateSolanaNonce() {
@@ -10314,8 +10603,8 @@ var PaymentGatewayClient2 = class extends PaymentGatewayClient {
       // reasonable against that type - would otherwise build an EIP-712 domain around a
       // null verifyingContract.
       permit2Contract: data.permit2_contract ?? void 0,
-      // Which deposit witness the escrow on this chain pins (CORE-2033). Absent means the
-      // four-member CORE-2120 witness — see ChainDefaults.depositWitnessVersion for why
+      // Which deposit witness the escrow on this chain pins. Absent means the
+      // four-member witness — see ChainDefaults.depositWitnessVersion for why
       // absence is the permissive default. EVM/Tron only; Solana uses the svm_* fields below.
       depositWitnessVersion: data.deposit_witness_version ?? void 0,
       // V3 Solana escrow domain separation. Present only for Solana
@@ -10520,11 +10809,14 @@ var PaymentGatewayClient2 = class extends PaymentGatewayClient {
   $GetPaymentStatusResponse,
   $OwnedAsset,
   $PaymentBlockchainContext,
-  $PaymentError,
+  $PaymentFailure,
   $PaymentRequest,
   $PaymentResponse,
+  $PaymentStatus,
   $PaymentSummary,
   $PaymentTimelineResponse,
+  $PaymentTransaction,
+  $PaymentTransactions,
   $PreparePaymentRequest,
   $PreparePaymentResponse,
   $Quote,
@@ -10535,7 +10827,6 @@ var PaymentGatewayClient2 = class extends PaymentGatewayClient {
   $SenderAuth,
   $SenderAuthMessageScheme,
   $SignedMessage,
-  $TimelineError,
   $TimelineStep,
   $VerifiableCredential,
   $VerifiableCredentialAuth,