@atumlabs/mppx-atum-escrow 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,126 @@
+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 { Method } from 'mppx';
+
+/** Configuration for the payer side of the method. */
+interface AtumEscrowClientConfig {
+    /**
+     * How to sign the source-chain deposit authorization. Either a ready-made
+     * {@link SenderSigner}, or options selecting the built-in private-key or Turnkey
+     * provider ({@link SenderSignerOptions}), which are bound to the challenge's source
+     * chain automatically.
+     */
+    signer: SenderSigner | SenderSignerOptions;
+    /**
+     * The payer's source-chain account (the depositor). Its chain-native form must match
+     * the signing key; the server rejects a credential whose signature does not recover to it.
+     */
+    account: string;
+    /** 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.
+     */
+    solanaClockReader?: SolanaClusterUnixTimeReader;
+}
+/**
+ * Configure the payer side of the method.
+ *
+ * The returned method builds and signs an Atum payment request from an incoming
+ * challenge and serializes it into an MPP credential. The source-chain authorization is
+ * built through the payment-gateway client's request builder, so the same call handles
+ * EVM, Tron, and Solana sources.
+ *
+ * Idempotency: for EVM and Tron sources the deposit nonce (and the `request_id`) are
+ * derived deterministically from the challenge id, so even if a caller rebuilds the
+ * credential for the same challenge the escrow admits at most one deposit — the reused
+ * nonce reverts the second on-chain. This holds only when the merchant issues a stable,
+ * per-intent challenge id: set `opaque` to a per-payment identifier (e.g. an order id),
+ * reused on retry of that intent, and keep `expires` stable or absent per intent (both feed
+ * the challenge-id HMAC). Solana sources use a replay-window nonce rather than a
+ * deterministic one and rely on the gateway's content-keyed dedup (the request id, and
+ * thus the payment id, are still derived deterministically from the challenge id).
+ * Building once and resubmitting the identical bytes remains the simplest safe pattern.
+ *
+ * @param config - the payer's signer, source account, and options.
+ */
+declare function registerClient(config: AtumEscrowClientConfig): Method.Client<{
+    readonly name: "atum-escrow";
+    readonly intent: "charge";
+    readonly schema: {
+        readonly request: z.ZodMiniObject<{
+            source: z.ZodMiniObject<{
+                network: z.ZodMiniString<string>;
+                asset: z.ZodMiniString<string>;
+                amount: z.ZodMiniString<string>;
+            }, zod_v4_core.$strip>;
+            extra: z.ZodMiniObject<{
+                destination: z.ZodMiniObject<{
+                    network: z.ZodMiniString<string>;
+                    asset: z.ZodMiniString<string>;
+                    account: z.ZodMiniString<string>;
+                }, zod_v4_core.$strip>;
+                fulfillmentAmount: z.ZodMiniString<string>;
+                escrow: z.ZodMiniString<string>;
+                fulfillmentProxy: z.ZodMiniString<string>;
+                reserver: z.ZodMiniString<string>;
+                releaser: z.ZodMiniString<string>;
+                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>>;
+            }, zod_v4_core.$strip>;
+        }, zod_v4_core.$strip>;
+        readonly credential: {
+            readonly payload: z.ZodMiniObject<{
+                paymentRequest: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>;
+            }, zod_v4_core.$strip>;
+        };
+    };
+}, undefined>;
+/** Result of an {@link ensureSourceApproval} call. */
+interface EnsureApprovalResult {
+    /** The existing allowance already covered the required amount; no transaction was sent. */
+    alreadySufficient: boolean;
+    /** The approval transaction hash, when one was sent. */
+    txHash?: string;
+}
+/**
+ * Ensure the payer has approved the token-transfer contract (Permit2) to move the source
+ * token, so the escrow deposit does not revert at settlement. Reads the current allowance
+ * and sends an approval only if it falls short.
+ *
+ * Applies to EVM and Tron sources (which use a Permit2-style allowance); Solana sources
+ * authorize the transfer in the signed deposit itself, so this is a no-op there.
+ *
+ * @param params.network - CAIP-2 source chain id.
+ * @param params.token - source token address.
+ * @param params.owner - the payer's account.
+ * @param params.signer - an ethers signer able to send the approval on `network`.
+ * @param params.spender - the contract to approve; defaults to the canonical EVM Permit2.
+ *   Required for Tron (its Permit2 address is chain-specific).
+ * @param params.requiredAllowance - the minimum allowance this charge needs (pass the
+ *   source cap, `challenge.request.source.amount`). When omitted, the function ensures an
+ *   unlimited approval — a smaller leftover allowance is NOT treated as sufficient, so a
+ *   later larger charge cannot slip through and revert on-chain.
+ *
+ * Not concurrency-safe: two overlapping calls for the same `(owner, token, spender)` may
+ * both read a short allowance and both send an approval. They target the same value, so
+ * this only wastes gas; serialize calls per token if that matters.
+ */
+declare function ensureSourceApproval(params: {
+    network: string;
+    token: string;
+    owner: string;
+    signer: Signer;
+    spender?: string;
+    requiredAllowance?: bigint;
+}): Promise<EnsureApprovalResult>;
+
+export { type AtumEscrowClientConfig, type EnsureApprovalResult, SenderSigner, SenderSignerOptions, ensureSourceApproval, registerClient };

package/dist/client.js

@@ -0,0 +1,21 @@
+import { createRequire as __atumCreateRequire } from 'module'; const require = __atumCreateRequire(import.meta.url);
+import {
+  ensureSourceApproval,
+  registerClient
+} from "./chunk-V2SJ747H.js";
+import {
+  ChargeRequestSchema,
+  CredentialPayloadSchema,
+  INTENT,
+  METHOD_NAME,
+  atumEscrowChargeMethod
+} from "./chunk-WWSNMK7N.js";
+export {
+  ChargeRequestSchema,
+  CredentialPayloadSchema,
+  INTENT,
+  METHOD_NAME,
+  atumEscrowChargeMethod,
+  ensureSourceApproval,
+  registerClient
+};

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+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 { AtumEscrowClientConfig, EnsureApprovalResult, ensureSourceApproval, registerClient } from './client.js';
+export { AtumEscrowCorridor, AtumEscrowReceipt, AtumEscrowServerConfig, AtumEscrowSource, ChainDefaultsSource, FulfillmentConfirmation, PaymentSubmitter, buildChargeRequest, corridorFromDefaults, registerServer, validateCorridor } from './server.js';
+import 'zod/mini';
+import 'mppx';
+import 'zod/v4/core';
+import 'ethers';
+
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * 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.
+ */
+interface AtumEscrowExtra {
+    /**
+     * Where the merchant receives (CAIP-2 chain, token, account).
+     */
+    destination: {
+        /**
+         * CAIP-2 destination chain id (e.g. eip155:42161).
+         */
+        network: string;
+        /**
+         * Destination token address (EVM hex or base58).
+         */
+        asset: string;
+        /**
+         * Merchant receive account (EVM hex or base58).
+         */
+        account: string;
+    };
+    /**
+     * Exact amount the merchant receives, in atomic token units.
+     */
+    fulfillmentAmount: string;
+    /**
+     * Source-chain escrow contract (the x402 payTo).
+     */
+    escrow: string;
+    /**
+     * Destination-chain fulfillment proxy contract.
+     */
+    fulfillmentProxy: string;
+    /**
+     * Reserver role address (escrow deposit witness).
+     */
+    reserver: string;
+    /**
+     * Releaser role address (escrow deposit witness).
+     */
+    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.
+     */
+    fulfillmentVerifierEndpoint: string;
+    /**
+     * Recommended quote-deadline budget in seconds, relative to signing time.
+     */
+    quoteDeadlineSeconds: number;
+    /**
+     * Recommended fulfillment-deadline budget in seconds, relative to signing time.
+     */
+    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.
+     */
+    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.
+     */
+    svmSignatureDomainVersion?: number;
+}
+
+export type { AtumEscrowExtra };

package/dist/index.js

@@ -0,0 +1,31 @@
+import { createRequire as __atumCreateRequire } from 'module'; const require = __atumCreateRequire(import.meta.url);
+import {
+  ensureSourceApproval,
+  registerClient
+} from "./chunk-V2SJ747H.js";
+import {
+  buildChargeRequest,
+  corridorFromDefaults,
+  registerServer,
+  validateCorridor
+} from "./chunk-XDYCJ36Z.js";
+import {
+  ChargeRequestSchema,
+  CredentialPayloadSchema,
+  INTENT,
+  METHOD_NAME,
+  atumEscrowChargeMethod
+} from "./chunk-WWSNMK7N.js";
+export {
+  ChargeRequestSchema,
+  CredentialPayloadSchema,
+  INTENT,
+  METHOD_NAME,
+  atumEscrowChargeMethod,
+  buildChargeRequest,
+  corridorFromDefaults,
+  ensureSourceApproval,
+  registerClient,
+  registerServer,
+  validateCorridor
+};