xytara 3.1.13 → 3.1.15

package/lib/provider_payout_execution.js

@@ -1,155 +1,155 @@
-"use strict";
-
-// Operator-triggered payout AUTO-EXECUTION via an EXTERNAL signer. The runtime never holds a
-// treasury key: it creates a payout, dispatches it to a configured signer service (which the
-// operator deploys and which holds the key), and confirms it with the on-chain tx the signer
-// returns. Off by default (no XYTARA_PAYOUT_SIGNER_URL => the manual create->send->confirm flow
-// is unchanged). Failure handling is deliberately conservative to avoid double-sends:
-//   - signer responds a definite failure  -> it did NOT send -> cancel (free the reservation).
-//   - signer unreachable / timeout         -> AMBIGUOUS (may have sent) -> leave the payout
-//     PENDING for manual reconciliation; NEVER auto-cancel (that could free funds already sent).
-
-const {
-  createProviderPayout,
-  confirmProviderPayout,
-  cancelProviderPayout,
-  markProviderPayoutDispatch,
-  reinstateCancelledPayoutForReconciliation
-} = require("./provider_registry");
-const { buildFetchOptionsForPurpose } = require("./network_transport");
-
-function normStr(value) {
-  const s = typeof value === "string" ? value.trim() : "";
-  return s || null;
-}
-
-function loadPayoutSignerConfig() {
-  const url = normStr(process.env.XYTARA_PAYOUT_SIGNER_URL);
-  if (!url || !/^https?:\/\//i.test(url)) return null;
-  return {
-    url,
-    bearer: normStr(process.env.XYTARA_PAYOUT_SIGNER_BEARER),
-    timeout_ms: Math.max(1000, Number(process.env.XYTARA_PAYOUT_SIGNER_TIMEOUT_MS || 20000) || 20000)
-  };
-}
-
-// AMOUNT/UNIT CONTRACT with the signer: amount_minor is in `currency` MINOR units (USD_CENTS,
-// i.e. US cents). The signer is responsible for converting that into `asset` (e.g. USDC) base
-// units on `network` before sending. This must be agreed with the signer implementation.
-// onPayoutPersist (optional): awaited AFTER the pending payout is created and BEFORE the send,
-// so the intent is durable and a crash during the signer call can't leave funds sent with no
-// reconciliation record.
-async function dispatchProviderPayout(state, providerId, input, signer, onPayoutPersist) {
-  if (!signer) return { ok: false, status: 400, reason: "payout_signer_not_configured" };
-
-  const created = createProviderPayout(state, providerId, input || {});
-  if (!created.ok) {
-    return { ok: false, status: created.reason === "provider_not_found" ? 404 : 400, reason: created.reason, detail: created };
-  }
-  const payout = created.payout;
-
-  // Mark IN FLIGHT before the send: while the signer call is outstanding the payout cannot be
-  // cancelled (a cancel would free a reservation for funds the signer may already have moved).
-  markProviderPayoutDispatch(state, payout.payout_id, "in_flight");
-
-  // Persist the PENDING (in-flight) record before any send (best-effort: proceed on flush failure).
-  if (typeof onPayoutPersist === "function") {
-    try { await onPayoutPersist(); } catch (_) { /* non-fatal */ }
-  }
-
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), signer.timeout_ms);
-  let response;
-  let text = "";
-  try {
-    response = await fetch(signer.url, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        ...(signer.bearer ? { authorization: `Bearer ${signer.bearer}` } : {})
-      },
-      body: JSON.stringify({
-        payout_id: payout.payout_id,
-        idempotency_key: payout.payout_id,
-        provider_id: payout.provider_id,
-        to_address: payout.payout_address,
-        network: payout.payout_network,
-        asset: payout.payout_asset,
-        amount_minor: payout.amount_minor,
-        currency: payout.currency
-      }),
-      signal: controller.signal,
-      ...buildFetchOptionsForPurpose("settlement")
-    });
-    text = await response.text();
-  } catch (error) {
-    // Transport failure (network/timeout): the signer MAY have sent. Leave the payout PENDING.
-    return {
-      ok: false,
-      status: 502,
-      reason: error && error.name === "AbortError" ? "payout_dispatch_timeout_unconfirmed" : "payout_dispatch_unconfirmed",
-      payout_id: payout.payout_id,
-      remediation: "the payout may or may not have been sent on-chain; reconcile manually — confirm with the tx hash if it was sent, or cancel if it was not"
-    };
-  } finally {
-    clearTimeout(timer);
-    // The signer has answered (or definitively failed to): the in-flight guard lifts. Everything
-    // below runs synchronously, so no cancel can interleave before the outcome is recorded.
-    markProviderPayoutDispatch(state, payout.payout_id, null);
-  }
-
-  let parsed = null;
-  try { parsed = text ? JSON.parse(text) : null; } catch (_) { parsed = null; }
-  const txRef = parsed && parsed.ok === true ? normStr(parsed.tx_ref) : null;
-
-  // DEFINITE SUCCESS: HTTP 2xx + explicit ok:true + a tx_ref -> confirm (credit paid_out once).
-  if (response.ok && txRef) {
-    const confirmed = confirmProviderPayout(state, payout.payout_id, { tx_ref: txRef });
-    if (!confirmed.ok) {
-      // Confirm failed AFTER a likely send (e.g. a buggy signer reusing a tx_ref -> duplicate_tx_ref).
-      // Do NOT cancel — funds may have moved. Leave PENDING and surface the failure.
-      // If the record was somehow cancelled meanwhile (guard expired / legacy state), put it back
-      // to pending with the tx so the reservation is held again and the operator reconciles.
-      if (confirmed.reason === "payout_not_pending" && payout.status === "cancelled") {
-        reinstateCancelledPayoutForReconciliation(state, payout.payout_id, txRef);
-      }
-      return {
-        ok: false,
-        status: 502,
-        reason: "payout_confirm_failed",
-        confirm_reason: confirmed.reason,
-        payout_id: payout.payout_id,
-        tx_ref: txRef,
-        remediation: "the signer reported a tx but the payout could not be confirmed; reconcile manually"
-      };
-    }
-    return { ok: true, dispatched: true, payout: confirmed.payout, payout_state: confirmed.payout_state };
-  }
-
-  // DEFINITE NOT-SENT: HTTP 2xx + a parsed body with explicit ok:false. The ONLY case where it
-  // is safe to cancel and free the reservation.
-  if (response.ok && parsed && parsed.ok === false) {
-    cancelProviderPayout(state, payout.payout_id);
-    return {
-      ok: false,
-      status: 502,
-      reason: "payout_signer_rejected",
-      detail: normStr(parsed.reason) || normStr(parsed.error) || "signer reported failure",
-      payout_id: payout.payout_id
-    };
-  }
-
-  // EVERYTHING ELSE is AMBIGUOUS (non-2xx incl. 5xx-after-send, non-JSON/empty body, ok:true
-  // without a tx_ref, missing ok) -> the signer may have sent -> LEAVE PENDING, NEVER free the
-  // reservation (freeing it would let an operator retry send a second real transfer).
-  return {
-    ok: false,
-    status: 502,
-    reason: "payout_dispatch_unconfirmed",
-    payout_id: payout.payout_id,
-    detail: !response.ok ? `signer HTTP ${response.status}` : "signer response did not confirm a tx",
-    remediation: "the payout may or may not have been sent on-chain; reconcile manually — confirm with the tx hash if it was sent, or cancel if it was not"
-  };
-}
-
-module.exports = { loadPayoutSignerConfig, dispatchProviderPayout };
+"use strict";
+
+// Operator-triggered payout AUTO-EXECUTION via an EXTERNAL signer. The runtime never holds a
+// treasury key: it creates a payout, dispatches it to a configured signer service (which the
+// operator deploys and which holds the key), and confirms it with the on-chain tx the signer
+// returns. Off by default (no XYTARA_PAYOUT_SIGNER_URL => the manual create->send->confirm flow
+// is unchanged). Failure handling is deliberately conservative to avoid double-sends:
+//   - signer responds a definite failure  -> it did NOT send -> cancel (free the reservation).
+//   - signer unreachable / timeout         -> AMBIGUOUS (may have sent) -> leave the payout
+//     PENDING for manual reconciliation; NEVER auto-cancel (that could free funds already sent).
+
+const {
+  createProviderPayout,
+  confirmProviderPayout,
+  cancelProviderPayout,
+  markProviderPayoutDispatch,
+  reinstateCancelledPayoutForReconciliation
+} = require("./provider_registry");
+const { buildFetchOptionsForPurpose } = require("./network_transport");
+
+function normStr(value) {
+  const s = typeof value === "string" ? value.trim() : "";
+  return s || null;
+}
+
+function loadPayoutSignerConfig() {
+  const url = normStr(process.env.XYTARA_PAYOUT_SIGNER_URL);
+  if (!url || !/^https?:\/\//i.test(url)) return null;
+  return {
+    url,
+    bearer: normStr(process.env.XYTARA_PAYOUT_SIGNER_BEARER),
+    timeout_ms: Math.max(1000, Number(process.env.XYTARA_PAYOUT_SIGNER_TIMEOUT_MS || 20000) || 20000)
+  };
+}
+
+// AMOUNT/UNIT CONTRACT with the signer: amount_minor is in `currency` MINOR units (USD_CENTS,
+// i.e. US cents). The signer is responsible for converting that into `asset` (e.g. USDC) base
+// units on `network` before sending. This must be agreed with the signer implementation.
+// onPayoutPersist (optional): awaited AFTER the pending payout is created and BEFORE the send,
+// so the intent is durable and a crash during the signer call can't leave funds sent with no
+// reconciliation record.
+async function dispatchProviderPayout(state, providerId, input, signer, onPayoutPersist) {
+  if (!signer) return { ok: false, status: 400, reason: "payout_signer_not_configured" };
+
+  const created = createProviderPayout(state, providerId, input || {});
+  if (!created.ok) {
+    return { ok: false, status: created.reason === "provider_not_found" ? 404 : 400, reason: created.reason, detail: created };
+  }
+  const payout = created.payout;
+
+  // Mark IN FLIGHT before the send: while the signer call is outstanding the payout cannot be
+  // cancelled (a cancel would free a reservation for funds the signer may already have moved).
+  markProviderPayoutDispatch(state, payout.payout_id, "in_flight");
+
+  // Persist the PENDING (in-flight) record before any send (best-effort: proceed on flush failure).
+  if (typeof onPayoutPersist === "function") {
+    try { await onPayoutPersist(); } catch (_) { /* non-fatal */ }
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), signer.timeout_ms);
+  let response;
+  let text = "";
+  try {
+    response = await fetch(signer.url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...(signer.bearer ? { authorization: `Bearer ${signer.bearer}` } : {})
+      },
+      body: JSON.stringify({
+        payout_id: payout.payout_id,
+        idempotency_key: payout.payout_id,
+        provider_id: payout.provider_id,
+        to_address: payout.payout_address,
+        network: payout.payout_network,
+        asset: payout.payout_asset,
+        amount_minor: payout.amount_minor,
+        currency: payout.currency
+      }),
+      signal: controller.signal,
+      ...buildFetchOptionsForPurpose("settlement")
+    });
+    text = await response.text();
+  } catch (error) {
+    // Transport failure (network/timeout): the signer MAY have sent. Leave the payout PENDING.
+    return {
+      ok: false,
+      status: 502,
+      reason: error && error.name === "AbortError" ? "payout_dispatch_timeout_unconfirmed" : "payout_dispatch_unconfirmed",
+      payout_id: payout.payout_id,
+      remediation: "the payout may or may not have been sent on-chain; reconcile manually — confirm with the tx hash if it was sent, or cancel if it was not"
+    };
+  } finally {
+    clearTimeout(timer);
+    // The signer has answered (or definitively failed to): the in-flight guard lifts. Everything
+    // below runs synchronously, so no cancel can interleave before the outcome is recorded.
+    markProviderPayoutDispatch(state, payout.payout_id, null);
+  }
+
+  let parsed = null;
+  try { parsed = text ? JSON.parse(text) : null; } catch (_) { parsed = null; }
+  const txRef = parsed && parsed.ok === true ? normStr(parsed.tx_ref) : null;
+
+  // DEFINITE SUCCESS: HTTP 2xx + explicit ok:true + a tx_ref -> confirm (credit paid_out once).
+  if (response.ok && txRef) {
+    const confirmed = confirmProviderPayout(state, payout.payout_id, { tx_ref: txRef });
+    if (!confirmed.ok) {
+      // Confirm failed AFTER a likely send (e.g. a buggy signer reusing a tx_ref -> duplicate_tx_ref).
+      // Do NOT cancel — funds may have moved. Leave PENDING and surface the failure.
+      // If the record was somehow cancelled meanwhile (guard expired / legacy state), put it back
+      // to pending with the tx so the reservation is held again and the operator reconciles.
+      if (confirmed.reason === "payout_not_pending" && payout.status === "cancelled") {
+        reinstateCancelledPayoutForReconciliation(state, payout.payout_id, txRef);
+      }
+      return {
+        ok: false,
+        status: 502,
+        reason: "payout_confirm_failed",
+        confirm_reason: confirmed.reason,
+        payout_id: payout.payout_id,
+        tx_ref: txRef,
+        remediation: "the signer reported a tx but the payout could not be confirmed; reconcile manually"
+      };
+    }
+    return { ok: true, dispatched: true, payout: confirmed.payout, payout_state: confirmed.payout_state };
+  }
+
+  // DEFINITE NOT-SENT: HTTP 2xx + a parsed body with explicit ok:false. The ONLY case where it
+  // is safe to cancel and free the reservation.
+  if (response.ok && parsed && parsed.ok === false) {
+    cancelProviderPayout(state, payout.payout_id);
+    return {
+      ok: false,
+      status: 502,
+      reason: "payout_signer_rejected",
+      detail: normStr(parsed.reason) || normStr(parsed.error) || "signer reported failure",
+      payout_id: payout.payout_id
+    };
+  }
+
+  // EVERYTHING ELSE is AMBIGUOUS (non-2xx incl. 5xx-after-send, non-JSON/empty body, ok:true
+  // without a tx_ref, missing ok) -> the signer may have sent -> LEAVE PENDING, NEVER free the
+  // reservation (freeing it would let an operator retry send a second real transfer).
+  return {
+    ok: false,
+    status: 502,
+    reason: "payout_dispatch_unconfirmed",
+    payout_id: payout.payout_id,
+    detail: !response.ok ? `signer HTTP ${response.status}` : "signer response did not confirm a tx",
+    remediation: "the payout may or may not have been sent on-chain; reconcile manually — confirm with the tx hash if it was sent, or cancel if it was not"
+  };
+}
+
+module.exports = { loadPayoutSignerConfig, dispatchProviderPayout };