@atumlabs/mppx-atum-escrow 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,230 @@
+import * as zod_v4_core from 'zod/v4/core';
+import * as z from 'zod/mini';
+import { P as PaymentRequest, i as ChainDefaults, c as ChargeRequest } from './internal-CjcEyEsm.js';
+export { A as AtumEscrowChallenge, a as AtumEscrowCredential, C as ChargeCredentialPayload, d as ChargeRequestSchema, e as CredentialPayloadSchema, I as INTENT, M as METHOD_NAME, g as atumEscrowChargeMethod } from './internal-CjcEyEsm.js';
+import { Receipt, Method } from 'mppx';
+
+/**
+ * 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.
+ */
+/**
+ * Confirmation details after a payment has been successfully delivered. Contains proof of delivery and transaction details for both source and destination chains.
+ */
+interface FulfillmentConfirmation {
+    /**
+     * Unique identifier for this payment transaction. Use this to track the payment across all systems.
+     */
+    payment_id: string;
+    /**
+     * Your original request ID that was provided when creating the payment. Helps match confirmations to your internal systems.
+     */
+    request_id: string;
+    /**
+     * Timestamp when the fulfillment was completed
+     */
+    fulfillment_timestamp?: string;
+    /**
+     * The blockchain where funds were locked in escrow, using CAIP-2 format. CAIP-2 is a standard way to identify blockchains: {namespace}:{reference}. Examples: 'eip155:1' for Ethereum mainnet, 'eip155:42161' for Arbitrum, 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp' for Solana, 'tron:mainnet' for Tron
+     */
+    source_chain_id: string;
+    /**
+     * The blockchain where the payment was delivered, using CAIP-2 format. CAIP-2 is a standard way to identify blockchains: {namespace}:{reference}. Examples: 'eip155:1' for Ethereum mainnet, 'eip155:42161' for Arbitrum, 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp' for Solana, 'tron:mainnet' for Tron
+     */
+    destination_chain_id: string;
+    /**
+     * Transaction hash of the escrow reservation on the source chain
+     */
+    source_tx_hash: string;
+    /**
+     * Transaction hash of the fulfillment on the destination chain
+     */
+    destination_tx_hash: string;
+    /**
+     * Block number where the source transaction was confirmed
+     */
+    source_block_number?: number;
+    /**
+     * Block number where the destination transaction was confirmed
+     */
+    destination_block_number?: number;
+}
+
+/** One source chain/token the merchant accepts payment from. */
+interface AtumEscrowSource {
+    /** CAIP-2 source chain id (e.g. `eip155:8453`, `tron:mainnet`, `solana:<genesis>`). */
+    network: string;
+    /**
+     * Source token addresses the payer may fund with on this network. All tokens on the
+     * same chain share the escrow/role/verifier fields below, so accepting several tokens on
+     * one chain is a single source with multiple `assets` — no need to duplicate the entry.
+     */
+    assets: string[];
+    /** Source-chain escrow contract; the payer's funds lock here. */
+    escrow: string;
+    /** Source-chain role address that witnesses the escrow deposit on reservation. */
+    reserver: string;
+    /** Source-chain role address that witnesses the escrow release on fulfillment. */
+    releaser: string;
+    /** Source-chain endpoint used to verify fulfillment. */
+    fulfillmentVerifierEndpoint: string;
+    /** Tron-only: the Permit2 contract the deposit is signed against. Defaults to the known address for the cluster when omitted. */
+    permit2?: string;
+    /** Solana-only: cluster id that domain-separates the deposit authorization. */
+    svmSignatureClusterId?: string;
+    /** Solana-only: signature domain version that domain-separates the deposit authorization. */
+    svmSignatureDomainVersion?: number;
+}
+/** Corridor configuration: what the merchant receives and which sources it accepts. */
+interface AtumEscrowCorridor {
+    /** Where the merchant receives: CAIP-2 chain, token, and receive account. */
+    destination: {
+        network: string;
+        asset: string;
+        account: string;
+    };
+    /** Destination-chain fulfillment-proxy contract. */
+    fulfillmentProxy: string;
+    /** Markup over `fulfillmentAmount` to derive each source cap, in basis points (e.g. `300` = 3%). */
+    markupBps: number;
+    /** Quote-deadline budget in seconds, relative to signing time. */
+    quoteDeadlineSeconds: number;
+    /** Fulfillment-deadline budget in seconds, relative to signing time. */
+    fulfillmentDeadlineSeconds: number;
+    /** Accepted source options; selected per charge by `(network, asset)`. */
+    sources: AtumEscrowSource[];
+}
+/**
+ * Submits a signed payment request to the Atum Payment Gateway and resolves with the
+ * settlement result. Satisfied by an adapter over `@atum-labs/payment-gateway-client`.
+ */
+interface PaymentSubmitter {
+    submit(request: PaymentRequest): Promise<{
+        payment_id?: string;
+        fulfillment_confirmation?: FulfillmentConfirmation;
+    }>;
+}
+/** Configuration for the merchant side of the method. */
+interface AtumEscrowServerConfig {
+    /** The gateway settlement is submitted through. */
+    submitter: PaymentSubmitter;
+    /** Clock (epoch ms) used to validate deadline ordering and budgets. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * The receipt returned once a payment settles, extending the MPP receipt with the Atum
+ * settlement details. `reference` carries the destination-chain transaction hash, and
+ * `fulfillmentConfirmation` carries the full settlement confirmation (payment id,
+ * destination chain, request id, and transaction hashes).
+ */
+type AtumEscrowReceipt = Receipt.Receipt & {
+    /** The full settlement confirmation. */
+    fulfillmentConfirmation: FulfillmentConfirmation;
+};
+/**
+ * Configure the merchant side of the method.
+ *
+ * The returned method verifies an incoming credential and settles it through the Atum
+ * Payment Gateway, resolving with an {@link AtumEscrowReceipt} once the payment
+ * completes. Verification throws if the credential is invalid or the payment does not
+ * settle. The inbound request is held open for the duration of settlement, so client
+ * and server timeouts must exceed the corridor's deadline budgets.
+ *
+ * The corridor is not part of the server configuration: verification trusts the
+ * HMAC-bound challenge (carried in `request`) as the source of truth for the payment
+ * terms, so one registration serves every corridor the merchant advertises.
+ *
+ * @param config - the gateway submitter and options.
+ */
+declare function registerServer(config: AtumEscrowServerConfig): Method.Server<{
+    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, {}, undefined>;
+/**
+ * Validate a corridor's shape and per-source addresses. Run automatically by
+ * {@link buildChargeRequest}; call it directly to fail fast at merchant startup.
+ *
+ * @throws if the deadline budgets are non-positive or out of order, the markup is
+ *   negative, there are no sources, or a source is missing a required field.
+ */
+declare function validateCorridor(corridor: AtumEscrowCorridor): void;
+/**
+ * Build the `charge` challenge request for a specific source option from a corridor. The
+ * merchant uses this to construct the 402 challenge; the source cap is
+ * `fulfillmentAmount + markup`, quoted in the source token. The corridor is validated
+ * first, so a misconfiguration fails here rather than at signing time.
+ *
+ * @param corridor - the corridor to serve.
+ * @param select - which configured source to fund from, by `(network, asset)`.
+ * @param fulfillmentAmount - exact amount the merchant receives, atomic units of the
+ *   destination token. Set per charge so one registration serves any price.
+ * @throws if no source option matches `select`, or the corridor is invalid.
+ */
+declare function buildChargeRequest(corridor: AtumEscrowCorridor, select: {
+    network: string;
+    asset: string;
+}, fulfillmentAmount: string): ChargeRequest;
+/** The minimal defaults source `corridorFromDefaults` needs; satisfied by the gateway client. */
+interface ChainDefaultsSource {
+    fetchChainDefaults(chainId: string): Promise<ChainDefaults>;
+}
+/**
+ * Build a corridor by fetching the escrow/role/proxy addresses from the payment gateway's
+ * `/defaults` endpoint, so the merchant does not hand-author protocol addresses. Fetches
+ * the destination chain's fulfillment proxy and each source chain's escrow, reserver,
+ * releaser, verifier endpoint (and Solana domain fields) in parallel.
+ *
+ * @param defaults - a defaults source (e.g. a `PaymentGatewayClient`).
+ * @param params - the destination receive-side, the source chains and their accepted
+ *   token `assets`, the markup, and the deadline budgets. One entry per source chain;
+ *   list several tokens in `assets` to accept more than one on that chain.
+ */
+declare function corridorFromDefaults(defaults: ChainDefaultsSource, params: {
+    destination: {
+        network: string;
+        asset: string;
+        account: string;
+    };
+    sources: Array<{
+        network: string;
+        assets: string[];
+    }>;
+    markupBps: number;
+    quoteDeadlineSeconds: number;
+    fulfillmentDeadlineSeconds: number;
+}): Promise<AtumEscrowCorridor>;
+
+export { type AtumEscrowCorridor, type AtumEscrowReceipt, type AtumEscrowServerConfig, type AtumEscrowSource, type ChainDefaultsSource, ChargeRequest, type FulfillmentConfirmation, PaymentRequest, type PaymentSubmitter, buildChargeRequest, corridorFromDefaults, registerServer, validateCorridor };

package/dist/server.js

@@ -0,0 +1,25 @@
+import { createRequire as __atumCreateRequire } from 'module'; const require = __atumCreateRequire(import.meta.url);
+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,
+  registerServer,
+  validateCorridor
+};

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@atumlabs/mppx-atum-escrow",
+  "version": "0.1.0",
+  "description": "Atum cross-chain escrow payment method for the Machine Payments Protocol (MPP).",
+  "author": "Atum Labs, Inc.",
+  "license": "UNLICENSED",
+  "homepage": "https://github.com/Atum-Labs/protocol/tree/main/mppx-atum-escrow#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Atum-Labs/protocol.git",
+    "directory": "mppx-atum-escrow"
+  },
+  "bugs": {
+    "url": "https://github.com/Atum-Labs/protocol/issues"
+  },
+  "keywords": [
+    "atum",
+    "mpp",
+    "machine-payments-protocol",
+    "payment-method",
+    "cross-chain",
+    "stablecoin",
+    "escrow",
+    "permit2"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "scripts": {
+    "prebuild:deps": "node -e \"const {existsSync}=require('fs');for(const p of ['../contracts/evm/escrow-encoding/typescript/tsconfig.json','../contracts/tvm/escrow-encoding/typescript/tsconfig.json','../contracts/svm/escrow-encoding/typescript/tsconfig.json','../schemas/apis/atum-escrow/v1/bindings/typescript/tsconfig.json','../schemas/apis/fulfillment-confirmation/v1/bindings/typescript/tsconfig.json']){if(!existsSync(p)){console.error('bundled sibling not found at '+p+'. Is this checked out inside the protocol monorepo?');process.exit(1)}}if(!existsSync('../payment-gateway-client/dist/index.js')){console.error('@atum-labs/payment-gateway-client is not built. Run its build first (pnpm --filter @atum-labs/payment-gateway-client build).');process.exit(1)}\"",
+    "build:deps": "tsc -p ../contracts/evm/escrow-encoding/typescript/tsconfig.json && tsc -p ../contracts/tvm/escrow-encoding/typescript/tsconfig.json && tsc -p ../contracts/svm/escrow-encoding/typescript/tsconfig.json && tsc -p ../schemas/apis/atum-escrow/v1/bindings/typescript/tsconfig.json && tsc -p ../schemas/apis/fulfillment-confirmation/v1/bindings/typescript/tsconfig.json",
+    "build": "pnpm run build:deps && tsup",
+    "typecheck": "pnpm run build:deps && tsc --noEmit",
+    "pretest": "pnpm run build:deps",
+    "test": "vitest run",
+    "clean": "rm -rf dist ../contracts/evm/escrow-encoding/typescript/dist ../contracts/tvm/escrow-encoding/typescript/dist ../contracts/svm/escrow-encoding/typescript/dist ../schemas/apis/atum-escrow/v1/bindings/typescript/dist ../schemas/apis/fulfillment-confirmation/v1/bindings/typescript/dist",
+    "check:publishable": "node scripts/check-publishable.mjs",
+    "prepare": "pnpm run build",
+    "prepublishOnly": "pnpm run build && pnpm run check:publishable"
+  },
+  "dependencies": {
+    "bs58": "^6.0.0",
+    "ethers": "^6.13.0",
+    "tweetnacl": "^1.0.3"
+  },
+  "peerDependencies": {
+    "mppx": ">=0.8.12 <0.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@atum-labs/atum-escrow": "workspace:*",
+    "@atum-labs/evm-escrow-encoding": "workspace:*",
+    "@atum-labs/fulfillment-confirmation": "workspace:*",
+    "@atum-labs/payment-gateway-client": "workspace:*",
+    "@atum-labs/schema-declarations": "workspace:*",
+    "@atum-labs/solana-escrow-encoding": "workspace:*",
+    "@atum-labs/tvm-escrow-encoding": "workspace:*",
+    "@types/node": "^20.0.0",
+    "mppx": "^0.8.12",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.9",
+    "zod": "^4.4.3"
+  }
+}