@atumlabs/mppx-atum-escrow 0.1.1 → 0.2.2

package/dist/chunk-NEM3HEZW.js

@@ -0,0 +1,253 @@
+import { createRequire as __atumCreateRequire } from 'module'; const require = __atumCreateRequire(import.meta.url);
+import {
+  METHOD_NAME,
+  __toESM,
+  assetIdentifier,
+  atumEscrowChargeMethod,
+  contractOverridesFromExtra,
+  import_payment_request_sender_auth,
+  namespaceOf,
+  require_dist2 as require_dist,
+  sameAddress
+} from "./chunk-4P34CLTO.js";
+
+// src/server.ts
+var import_payment_request_sender_auth2 = __toESM(require_dist(), 1);
+import { Method } from "mppx";
+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 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 (!(nowMs < quote && quote < fulfillment)) {
+        throw new Error(
+          "atum-escrow: deadline ordering violated (now < quote_deadline < fulfillment_deadline)"
+        );
+      }
+      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) {
+        throw new Error(
+          "atum-escrow: settlement did not complete within the synchronous window (no FulfillmentConfirmation)"
+        );
+      }
+      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 } : {}
+    }
+  };
+}
+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 {
+  registerServer,
+  validateCorridor,
+  buildChargeRequest,
+  corridorFromDefaults
+};

package/dist/client.d.ts

@@ -1,9 +1,10 @@
 import * as zod_v4_core from 'zod/v4/core';
 import * as z from 'zod/mini';
 import { Signer } from 'ethers';
-import { S as SenderSigner, f as SenderSignerOptions, h as SolanaClusterUnixTimeReader } from './internal-CjcEyEsm.js';
-export { A as AtumEscrowChallenge, a as AtumEscrowCredential, C as ChargeCredentialPayload, c as ChargeRequest, d as ChargeRequestSchema, e as CredentialPayloadSchema, I as INTENT, M as METHOD_NAME, P as PaymentRequest, g as atumEscrowChargeMethod } from './internal-CjcEyEsm.js';
+import { S as SenderSigner, f as SenderSignerOptions, h as SolanaClusterUnixTimeReader } from './internal-DzEGXm14.js';
+export { A as AtumEscrowChallenge, a as AtumEscrowCredential, C as ChargeCredentialPayload, c as ChargeRequest, d as ChargeRequestSchema, e as CredentialPayloadSchema, I as INTENT, M as METHOD_NAME, g as atumEscrowChargeMethod } from './internal-DzEGXm14.js';
 import { Method } from 'mppx';
+export { PaymentRequest } from './generated/index.js';
 
 /** Configuration for the payer side of the method. */
 interface AtumEscrowClientConfig {
@@ -22,8 +23,10 @@ interface AtumEscrowClientConfig {
     /** Clock (epoch ms) used to derive absolute deadlines from the challenge budgets. Defaults to `Date.now`. */
     now?: () => number;
     /**
-     * Solana-only test seam: supplies the `issued_at` a Solana deposit is stamped with,
-     * keeping the build fully offline. Defaults to the client clock. Ignored for EVM/Tron.
+     * Solana-only: supplies the `issued_at` a Solana deposit is stamped with, keeping the
+     * build fully offline. Used only when the challenge does not carry a merchant-stamped
+     * `extra.issuedAt` (which takes precedence); if neither is present, the client clock is
+     * used. Ignored for EVM/Tron.
      */
     solanaClockReader?: SolanaClusterUnixTimeReader;
 }
@@ -62,7 +65,7 @@ declare function registerClient(config: AtumEscrowClientConfig): Method.Client<{
                 destination: z.ZodMiniObject<{
                     network: z.ZodMiniString<string>;
                     asset: z.ZodMiniString<string>;
-                    account: z.ZodMiniString<string>;
+                    address: z.ZodMiniString<string>;
                 }, zod_v4_core.$strip>;
                 fulfillmentAmount: z.ZodMiniString<string>;
                 escrow: z.ZodMiniString<string>;
@@ -72,9 +75,9 @@ declare function registerClient(config: AtumEscrowClientConfig): Method.Client<{
                 fulfillmentVerifierEndpoint: z.ZodMiniString<string>;
                 quoteDeadlineSeconds: z.ZodMiniNumber<number>;
                 fulfillmentDeadlineSeconds: z.ZodMiniNumber<number>;
-                permit2: z.ZodMiniOptional<z.ZodMiniString<string>>;
                 svmSignatureClusterId: z.ZodMiniOptional<z.ZodMiniString<string>>;
                 svmSignatureDomainVersion: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+                issuedAt: z.ZodMiniOptional<z.ZodMiniString<string>>;
             }, zod_v4_core.$strip>;
         }, zod_v4_core.$strip>;
         readonly credential: {

package/dist/client.js

@@ -8,14 +8,14 @@ import { createRequire as __atumCreateRequire } from 'module'; const require = _
 import {
   ensureSourceApproval,
   registerClient
-} from "./chunk-L62WG2VU.js";
+} from "./chunk-IPZJXELQ.js";
 import {
   ChargeRequestSchema,
   CredentialPayloadSchema,
   INTENT,
   METHOD_NAME,
   atumEscrowChargeMethod
-} from "./chunk-2MWWLU75.js";
+} from "./chunk-4P34CLTO.js";
 export {
   ChargeRequestSchema,
   CredentialPayloadSchema,

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export { A as AtumEscrowChallenge, a as AtumEscrowCredential, b as AtumEscrowRequest, C as ChargeCredentialPayload, c as ChargeRequest, d as ChargeRequestSchema, e as CredentialPayloadSchema, I as INTENT, M as METHOD_NAME, P as PaymentRequest, S as SenderSigner, f as SenderSignerOptions, g as atumEscrowChargeMethod } from './internal-CjcEyEsm.js';
+export { A as AtumEscrowChallenge, a as AtumEscrowCredential, b as AtumEscrowRequest, C as ChargeCredentialPayload, c as ChargeRequest, d as ChargeRequestSchema, e as CredentialPayloadSchema, I as INTENT, M as METHOD_NAME, S as SenderSigner, f as SenderSignerOptions, g as atumEscrowChargeMethod } from './internal-DzEGXm14.js';
 export { AtumEscrowClientConfig, EnsureApprovalResult, ensureSourceApproval, registerClient } from './client.js';
 export { AtumEscrowCorridor, AtumEscrowReceipt, AtumEscrowServerConfig, AtumEscrowSource, ChainDefaultsSource, FulfillmentConfirmation, PaymentSubmitter, buildChargeRequest, corridorFromDefaults, registerServer, validateCorridor } from './server.js';
+export { PaymentRequest } from './generated/index.js';
 import 'zod/mini';
 import 'mppx';
 import 'zod/v4/core';
@@ -12,11 +13,11 @@ import 'ethers';
  * and run json-schema-to-typescript to regenerate this file.
  */
 /**
- * The `extra.atum` object carried inside an atum-escrow x402 PaymentRequirements entry (accepts[]): the merchant's receive-side plus the contract/role addresses and deadline budgets. Scheme-specific data the standard x402 `extra` bag treats as opaque, so it is owned here and shared by all role mechanisms. Addresses are chain-general: an EVM `0x`-prefixed hex address, or a Tron/Solana base58 address, depending on the source/destination chain.
+ * The `extra.atum` object carried inside an atum-escrow x402 PaymentRequirements entry (accepts[]): the merchant's receive-side plus the contract/role addresses and deadline budgets. Scheme-specific data the standard x402 `extra` bag treats as opaque, so it is owned here and shared by all role mechanisms. Addresses are chain-general: an EVM `0x`-hex address (20 bytes) or a base58-encoded address (Solana/Tron), per the field's CAIP-2 chain.
  */
 interface AtumEscrowExtra {
     /**
-     * Where the merchant receives (CAIP-2 chain, token, account).
+     * Where the merchant receives (CAIP-2 chain, token, address).
      */
     destination: {
         /**
@@ -24,36 +25,36 @@ interface AtumEscrowExtra {
          */
         network: string;
         /**
-         * Destination token address (EVM hex or base58).
+         * Destination token contract address (EVM hex or base58, per the destination chain).
          */
         asset: string;
         /**
-         * Merchant receive account (EVM hex or base58).
+         * Merchant receive address (EVM hex or base58, per the destination chain).
          */
-        account: string;
+        address: string;
     };
     /**
      * Exact amount the merchant receives, in atomic token units.
      */
     fulfillmentAmount: string;
     /**
-     * Source-chain escrow contract (the x402 payTo).
+     * Source-chain escrow contract (the x402 payTo); EVM hex or base58, per the source chain.
      */
     escrow: string;
     /**
-     * Destination-chain fulfillment proxy contract.
+     * Destination-chain fulfillment proxy contract (EVM hex or base58, per the destination chain).
      */
     fulfillmentProxy: string;
     /**
-     * Reserver role address (escrow deposit witness).
+     * Atum reserver role address (escrow deposit witness); EVM hex or base58, per the source chain.
      */
     reserver: string;
     /**
-     * Releaser role address (escrow deposit witness).
+     * Atum releaser role address (escrow deposit witness); EVM hex or base58, per the source chain.
      */
     releaser: string;
     /**
-     * Source-chain fulfillment-verifier endpoint the payment request carries. The verifier account and the quote selector are the releaser and reserver respectively, so only the endpoint is not otherwise present in this object.
+     * Source-chain fulfillment-verifier endpoint the payment request carries. The verifier account and the quote_selector are the releaser and reserver respectively (the network derives the deposit witness roles from them), so only the endpoint is not otherwise present in this object.
      */
     fulfillmentVerifierEndpoint: string;
     /**
@@ -65,17 +66,17 @@ interface AtumEscrowExtra {
      */
     fulfillmentDeadlineSeconds: number;
     /**
-     * Tron-only: the Permit2 contract address the deposit authorization is signed against (the TIP-712 verifying contract). Present only when the source chain is Tron; on EVM the canonical Permit2 address is well-known, and Solana does not use Permit2.
-     */
-    permit2?: string;
-    /**
-     * Solana-only: cluster identifier used to domain-separate the deposit authorization. Present only when the source chain is Solana; omitted for EVM/Tron.
+     * Solana source only: cluster name used to build the 32-byte cluster_id in the V3 escrow signature domain. Optional; the facilitator requires it for a Solana source.
      */
     svmSignatureClusterId?: string;
     /**
-     * Solana-only: signature domain version used to domain-separate the deposit authorization. Present only when the source chain is Solana; omitted for EVM/Tron.
+     * Solana source only: escrow signature-domain version (V3 domain separation). Optional; required for a Solana source.
      */
     svmSignatureDomainVersion?: number;
+    /**
+     * Solana source only: merchant-stamped issue time in epoch seconds. The merchant reads the cluster clock so the client makes no RPC and the 402 stays self-contained. Optional; required for a Solana source.
+     */
+    issuedAt?: string;
 }
 
 export type { AtumEscrowExtra };

package/dist/index.js

@@ -8,20 +8,20 @@ import { createRequire as __atumCreateRequire } from 'module'; const require = _
 import {
   ensureSourceApproval,
   registerClient
-} from "./chunk-L62WG2VU.js";
+} from "./chunk-IPZJXELQ.js";
 import {
   buildChargeRequest,
   corridorFromDefaults,
   registerServer,
   validateCorridor
-} from "./chunk-W6D2D767.js";
+} from "./chunk-NEM3HEZW.js";
 import {
   ChargeRequestSchema,
   CredentialPayloadSchema,
   INTENT,
   METHOD_NAME,
   atumEscrowChargeMethod
-} from "./chunk-2MWWLU75.js";
+} from "./chunk-4P34CLTO.js";
 export {
   ChargeRequestSchema,
   CredentialPayloadSchema,