@atumlabs/mppx-atum-escrow 0.1.1 → 0.3.0

package/dist/chunk-4YD6566T.js

@@ -0,0 +1,371 @@
+import { createRequire as __atumCreateRequire } from 'module'; const require = __atumCreateRequire(import.meta.url);
+import {
+  INTENT_ID_META_KEY,
+  METHOD_NAME,
+  __toESM,
+  assetIdentifier,
+  atumEscrowChargeMethod,
+  chargeRequestId,
+  contractOverridesFromExtra,
+  import_payment_request_sender_auth,
+  intentIdOf,
+  namespaceOf,
+  require_dist2 as require_dist,
+  sameAddress
+} from "./chunk-Z3AUNEU5.js";
+
+// src/server.ts
+var import_payment_request_sender_auth2 = __toESM(require_dist(), 1);
+import { Errors as Errors2, Method } from "mppx";
+
+// src/errors.ts
+import { Errors } from "mppx";
+function hasMarker(err, marker) {
+  return typeof err === "object" && err !== null && err[marker] === true;
+}
+function isSettlementPending(err) {
+  return hasMarker(err, "isSettlementPending");
+}
+function isSettlementFailed(err) {
+  return hasMarker(err, "isSettlementFailed");
+}
+function isPaymentRejected(err) {
+  return hasMarker(err, "isPaymentRejected");
+}
+var SettlementPendingError = class extends Errors.PaymentActionRequiredError {
+  /** Discriminant; test it with {@link isSettlementPending}. */
+  isSettlementPending = true;
+  paymentId;
+  constructor(options = {}) {
+    super({
+      reason: "the payment is still settling" + (options.paymentId ? ` (payment ${options.paymentId})` : "") + "; re-attempt the purchase to collect the result \u2014 request a fresh challenge and sign it again, keeping the SAME intent id, and it resolves onto this payment rather than charging again. Do not re-present the credential already signed: its deadlines are fixed"
+    });
+    this.paymentId = options.paymentId;
+  }
+  /**
+   * Adds `paymentId` as its own field, not just interpolated into `detail`'s prose. A merchant
+   * catching this in-process already has `.paymentId`; a real cross-network payer only ever
+   * sees this JSON body, and without a dedicated field would have to parse it out of a sentence
+   * to reconcile the attempt against the gateway. The return type is declared (not left to
+   * inference) so a TypeScript merchant that re-serializes through the base type still sees
+   * `paymentId` in intellisense.
+   */
+  toProblemDetails(challengeId) {
+    return {
+      ...super.toProblemDetails(challengeId),
+      ...this.paymentId !== void 0 ? { paymentId: this.paymentId } : {}
+    };
+  }
+};
+var SettlementFailedError = class extends Errors.VerificationFailedError {
+  /** Discriminant; test it with {@link isSettlementFailed}. */
+  isSettlementFailed = true;
+  paymentId;
+  /** The terminal state the gateway reported. */
+  state;
+  constructor(options) {
+    super({
+      reason: `the payment ${options.state}` + (options.paymentId ? ` (payment ${options.paymentId})` : "") + "; retrying this purchase resolves to the same failed payment, so recovering requires a new purchase under a new identifier"
+    });
+    this.paymentId = options.paymentId;
+    this.state = options.state;
+  }
+  /**
+   * Adds `paymentId` and `state` as their own fields, not just interpolated into `detail`'s
+   * prose — see {@link SettlementPendingError.toProblemDetails} for why a payer needs this on
+   * the wire, not only a same-process merchant. Return type declared for the same reason: so a
+   * TypeScript merchant sees `paymentId`/`state` in intellisense, not only at runtime.
+   */
+  toProblemDetails(challengeId) {
+    return {
+      ...super.toProblemDetails(challengeId),
+      ...this.paymentId !== void 0 ? { paymentId: this.paymentId } : {},
+      state: this.state
+    };
+  }
+};
+var PaymentRejectedError = class extends Errors.BadRequestError {
+  /** Discriminant; test it with {@link isPaymentRejected}. */
+  isPaymentRejected = true;
+  /** The gateway's error code, for programmatic handling. */
+  code;
+  constructor(options) {
+    super({ reason: `${options.detail} (${options.code})` });
+    this.code = options.code;
+  }
+};
+
+// src/server.ts
+var DEADLINE_SKEW_TOLERANCE_MS = 6e4;
+var SOLANA_MAX_FULFILLMENT_DEADLINE_SECONDS = import_payment_request_sender_auth2.REPLAY_HORIZON_SECS - 10;
+function registerServer(config) {
+  const now = config.now ?? (() => Date.now());
+  return Method.toServer(atumEscrowChargeMethod, {
+    async verify({ credential, request }) {
+      const pr = credential.payload.paymentRequest;
+      const { source, extra } = request;
+      const namespace = namespaceOf(source.network);
+      const senderAuth = pr.sender_auth;
+      if (!senderAuth || senderAuth.signed_messages.length === 0) {
+        throw new Error("atum-escrow: credential is missing sender_auth");
+      }
+      const signed = senderAuth.signed_messages[0];
+      if (!signed.message_prehash) {
+        throw new Error("atum-escrow: sender_auth is missing message_prehash");
+      }
+      if (!pr.source) {
+        throw new Error("atum-escrow: credential is missing a source");
+      }
+      const maxSourceStr = pr.max_source_amount ?? "0";
+      const cap = BigInt(source.amount);
+      if (BigInt(maxSourceStr) > cap) {
+        throw new Error("atum-escrow: max_source_amount exceeds the source cap");
+      }
+      const authTerms = (0, import_payment_request_sender_auth2.getChainAdapter)(source.network).recoverAndVerify(
+        signed,
+        { network: source.network, asset: source.asset, account: pr.source.account },
+        {
+          maxSourceAmount: maxSourceStr,
+          escrowContract: extra.escrow,
+          reserver: extra.reserver,
+          releaser: extra.releaser,
+          svmSignatureClusterId: extra.svmSignatureClusterId,
+          svmSignatureDomainVersion: extra.svmSignatureDomainVersion,
+          // Check permit freshness against the merchant's own clock (the same `now` used for
+          // deadline ordering/budgets), not the SDK's wall clock — so freshness is consistent
+          // with the rest of verify and deterministic under an injected clock.
+          nowSec: Math.floor(now() / 1e3)
+        }
+      );
+      const intentId = intentIdOf(credential.challenge);
+      if (intentId === void 0) {
+        throw new Error(
+          `atum-escrow: the challenge carries no '${INTENT_ID_META_KEY}' metadata, so this payment cannot be de-duplicated and is refused`
+        );
+      }
+      if (pr.request_id !== chargeRequestId(intentId, pr.source.account)) {
+        throw new Error(
+          "atum-escrow: request_id is not derived from the challenge's purchase identifier, so a retry of this payment would not de-duplicate"
+        );
+      }
+      const dest = pr.destination?.[0];
+      if (!dest) {
+        throw new Error("atum-escrow: credential is missing a destination");
+      }
+      if (!sameAddress(dest.account, extra.destination.address)) {
+        throw new Error("atum-escrow: destination account does not match the challenge");
+      }
+      const expectedDestAsset = assetIdentifier(extra.destination.network, extra.destination.asset);
+      const destAssetMatches = namespaceOf(extra.destination.network) === "solana" ? dest.asset_identifier === expectedDestAsset : dest.asset_identifier.toLowerCase() === expectedDestAsset.toLowerCase();
+      if (!destAssetMatches) {
+        throw new Error("atum-escrow: destination asset does not match the challenge");
+      }
+      if (pr.fulfillment_amount !== extra.fulfillmentAmount) {
+        throw new Error("atum-escrow: fulfillment_amount does not match the challenge");
+      }
+      const overrides = contractOverridesFromExtra(source.network, extra);
+      const expectedQuoteSelector = overrides?.quote_selector ?? extra.reserver;
+      const expectedVerifier = overrides?.fulfillment_verifier ?? {
+        account: extra.releaser,
+        endpoint: extra.fulfillmentVerifierEndpoint
+      };
+      if (!sameAddress(pr.escrow_contract_address ?? "", extra.escrow)) {
+        throw new Error("atum-escrow: escrow_contract_address does not match the challenge");
+      }
+      if (!sameAddress(pr.quote_selector ?? "", expectedQuoteSelector)) {
+        throw new Error("atum-escrow: quote_selector does not match the challenge reserver");
+      }
+      if (!sameAddress(pr.fulfillment_proxy ?? "", extra.fulfillmentProxy)) {
+        throw new Error("atum-escrow: fulfillment_proxy does not match the challenge");
+      }
+      if (!sameAddress(pr.fulfillment_verifier?.account ?? "", expectedVerifier.account)) {
+        throw new Error("atum-escrow: fulfillment_verifier.account does not match the challenge releaser");
+      }
+      if ((pr.fulfillment_verifier?.endpoint ?? "") !== expectedVerifier.endpoint) {
+        throw new Error("atum-escrow: fulfillment_verifier.endpoint does not match the challenge");
+      }
+      const nowMs = now();
+      const quote = Date.parse(pr.quote_deadline);
+      const fulfillment = Date.parse(pr.fulfillment_deadline);
+      if (!(quote < fulfillment)) {
+        throw new Error(
+          "atum-escrow: quote_deadline must be before fulfillment_deadline (quote collection has to close before settlement is due)"
+        );
+      }
+      if (!(nowMs < quote)) {
+        throw new Errors2.PaymentActionRequiredError({
+          reason: "this authorization's quote window has already closed (quote_deadline is in the past), so it cannot start a payment. To re-attempt a purchase, request a fresh challenge and sign it again, keeping the SAME intent id \u2014 the re-attempt then resolves onto the payment already in flight instead of taking a second one. A stored credential cannot be re-presented: its deadlines are fixed at the moment it was signed"
+        });
+      }
+      if (quote > nowMs + extra.quoteDeadlineSeconds * 1e3 + DEADLINE_SKEW_TOLERANCE_MS) {
+        throw new Error("atum-escrow: quote_deadline exceeds the advertised budget");
+      }
+      if (fulfillment > nowMs + extra.fulfillmentDeadlineSeconds * 1e3 + DEADLINE_SKEW_TOLERANCE_MS) {
+        throw new Error("atum-escrow: fulfillment_deadline exceeds the advertised budget");
+      }
+      if (namespace !== "solana" && authTerms.deadlineSec * 1e3 < fulfillment) {
+        throw new Error("atum-escrow: permit deadline expires before fulfillment_deadline");
+      }
+      const result = await config.submitter.submit(pr);
+      const fc = result.fulfillment_confirmation;
+      if (!fc) {
+        const terminal = result.status === "failed" || result.status === "cancelled";
+        if (terminal) {
+          throw new SettlementFailedError({ paymentId: result.payment_id, state: result.status });
+        }
+        throw new SettlementPendingError({ paymentId: result.payment_id });
+      }
+      return {
+        method: METHOD_NAME,
+        status: "success",
+        timestamp: fc.fulfillment_timestamp ?? new Date(nowMs).toISOString(),
+        reference: fc.destination_tx_hash,
+        fulfillmentConfirmation: fc
+      };
+    }
+  });
+}
+function applyMarkupBps(amount, bps) {
+  return (BigInt(amount) * BigInt(1e4 + bps) / 10000n).toString();
+}
+function validateCorridor(corridor) {
+  if (!Number.isFinite(corridor.quoteDeadlineSeconds) || corridor.quoteDeadlineSeconds <= 0) {
+    throw new Error("atum-escrow: quoteDeadlineSeconds must be a positive number of seconds");
+  }
+  if (!Number.isFinite(corridor.fulfillmentDeadlineSeconds) || corridor.fulfillmentDeadlineSeconds <= 0) {
+    throw new Error("atum-escrow: fulfillmentDeadlineSeconds must be a positive number of seconds");
+  }
+  if (corridor.quoteDeadlineSeconds >= corridor.fulfillmentDeadlineSeconds) {
+    throw new Error(
+      "atum-escrow: quoteDeadlineSeconds must be strictly less than fulfillmentDeadlineSeconds"
+    );
+  }
+  if (!Number.isFinite(corridor.markupBps) || corridor.markupBps < 0) {
+    throw new Error("atum-escrow: markupBps must be a non-negative number of basis points");
+  }
+  if (!corridor.sources || corridor.sources.length === 0) {
+    throw new Error("atum-escrow: corridor must configure at least one source");
+  }
+  for (const src of corridor.sources) {
+    for (const field of ["network", "escrow", "reserver", "releaser", "fulfillmentVerifierEndpoint"]) {
+      if (!src[field]) {
+        throw new Error(`atum-escrow: source ${src.network ?? "?"} is missing '${field}'`);
+      }
+    }
+    if (!src.assets || src.assets.length === 0 || src.assets.some((a) => !a)) {
+      throw new Error(`atum-escrow: source ${src.network} must list at least one non-empty asset in 'assets'`);
+    }
+    if (namespaceOf(src.network) === "tron") {
+      (0, import_payment_request_sender_auth.resolveTronPermit2)(src.network);
+    }
+    if (namespaceOf(src.network) === "solana") {
+      if (!src.svmSignatureClusterId || src.svmSignatureDomainVersion == null) {
+        throw new Error(
+          `atum-escrow: Solana source ${src.network} requires svmSignatureClusterId and svmSignatureDomainVersion`
+        );
+      }
+      if (corridor.fulfillmentDeadlineSeconds > SOLANA_MAX_FULFILLMENT_DEADLINE_SECONDS) {
+        throw new Error(
+          `atum-escrow: a corridor with a Solana source must set fulfillmentDeadlineSeconds <= ${SOLANA_MAX_FULFILLMENT_DEADLINE_SECONDS} (Solana deposits expire within the escrow replay window); got ${corridor.fulfillmentDeadlineSeconds}`
+        );
+      }
+    }
+  }
+}
+function buildChargeRequest(corridor, select, fulfillmentAmount, options) {
+  validateCorridor(corridor);
+  const src = corridor.sources.find(
+    (s) => s.network === select.network && s.assets.some((a) => sameAddress(a, select.asset))
+  );
+  if (!src) {
+    throw new Error(
+      `atum-escrow: no source option configured for ${select.network} / ${select.asset}`
+    );
+  }
+  const selectedAsset = src.assets.find((a) => sameAddress(a, select.asset));
+  const isSolana = namespaceOf(src.network) === "solana";
+  if (isSolana && options?.issuedAt !== void 0 && !/^[0-9]+$/.test(options.issuedAt)) {
+    throw new Error(
+      `atum-escrow: issuedAt must be epoch seconds (digits only), got '${options.issuedAt}'`
+    );
+  }
+  return {
+    source: {
+      network: src.network,
+      asset: selectedAsset,
+      amount: applyMarkupBps(fulfillmentAmount, corridor.markupBps)
+    },
+    extra: {
+      // The corridor config carries the receive side as `account`; the wire `extra` names it
+      // `address` (the x402 scheme field), so map it here.
+      destination: {
+        network: corridor.destination.network,
+        asset: corridor.destination.asset,
+        address: corridor.destination.account
+      },
+      fulfillmentAmount,
+      escrow: src.escrow,
+      fulfillmentProxy: corridor.fulfillmentProxy,
+      reserver: src.reserver,
+      releaser: src.releaser,
+      fulfillmentVerifierEndpoint: src.fulfillmentVerifierEndpoint,
+      quoteDeadlineSeconds: corridor.quoteDeadlineSeconds,
+      fulfillmentDeadlineSeconds: corridor.fulfillmentDeadlineSeconds,
+      ...src.svmSignatureClusterId ? { svmSignatureClusterId: src.svmSignatureClusterId } : {},
+      ...src.svmSignatureDomainVersion != null ? { svmSignatureDomainVersion: src.svmSignatureDomainVersion } : {},
+      ...isSolana && options?.issuedAt ? { issuedAt: options.issuedAt } : {}
+    }
+  };
+}
+function buildChargeChallenge(corridor, select, fulfillmentAmount, options) {
+  if (typeof options.intentId !== "string" || options.intentId === "") {
+    throw new Error(
+      "atum-escrow: intentId must be a non-empty per-purchase identifier (e.g. an order id); the payer derives the payment's identity from it, so without one a retry would be charged as a second payment"
+    );
+  }
+  return {
+    request: buildChargeRequest(corridor, select, fulfillmentAmount, options),
+    meta: { [INTENT_ID_META_KEY]: options.intentId }
+  };
+}
+async function corridorFromDefaults(defaults, params) {
+  const [destDefaults, ...sourceDefaults] = await Promise.all([
+    defaults.fetchChainDefaults(params.destination.network),
+    ...params.sources.map((s) => defaults.fetchChainDefaults(s.network))
+  ]);
+  const sources = params.sources.map((s, i) => {
+    const d = sourceDefaults[i];
+    return {
+      network: s.network,
+      assets: s.assets,
+      escrow: d.escrowContract,
+      reserver: d.quoteSelector,
+      releaser: d.fulfillmentVerifierAccount,
+      fulfillmentVerifierEndpoint: d.fulfillmentVerifierEndpoint,
+      ...d.svmSignatureClusterId ? { svmSignatureClusterId: d.svmSignatureClusterId } : {},
+      ...d.svmSignatureDomainVersion != null ? { svmSignatureDomainVersion: d.svmSignatureDomainVersion } : {}
+    };
+  });
+  return {
+    destination: params.destination,
+    fulfillmentProxy: destDefaults.fulfillmentProxy,
+    markupBps: params.markupBps,
+    quoteDeadlineSeconds: params.quoteDeadlineSeconds,
+    fulfillmentDeadlineSeconds: params.fulfillmentDeadlineSeconds,
+    sources
+  };
+}
+
+export {
+  isSettlementPending,
+  isSettlementFailed,
+  isPaymentRejected,
+  SettlementPendingError,
+  SettlementFailedError,
+  PaymentRejectedError,
+  registerServer,
+  validateCorridor,
+  buildChargeRequest,
+  buildChargeChallenge,
+  corridorFromDefaults
+};