@atumlabs/mppx-atum-escrow 0.3.0 → 0.4.0

package/dist/{internal-9tB7y-A7.d.ts → internal-CJEu9yUF.d.ts}

@@ -3,35 +3,34 @@ import { PaymentRequest } from './generated/index.js';
 import { Challenge, Credential } from 'mppx';
 
 /**
- * A message that has been cryptographically signed to prove authorization.
- * The signature proves you control the wallet that's sending funds.
- *
+ * A message that has been cryptographically signed to prove authorization. The signature proves you control the wallet that's sending funds.
  */
 type SignedMessage = {
     /**
      * The data that was signed. Format depends on the blockchain:
      * - EVM: Hex-encoded message hash (with 0x prefix)
-     * - Solana: Base64 encoded message
+     * - Solana: Hex-encoded message hash (with 0x prefix)
      * - Tron: Hex-encoded message hash (possibly without 0x prefix)
-     *
      */
     message: string;
     /**
-     * Optional: If 'message' contains a hash, this field contains the original data
-     * before it was hashed. Useful for verification and debugging.
-     *
+     * Optional: If 'message' contains a hash, this field contains the original data before it was hashed. Useful for verification and debugging.
      */
     message_prehash?: string;
     /**
-     * The cryptographic signature proving you authorized this message.
-     * Format varies by blockchain (hex for EVM/Tron, base58 for Solana).
-     *
+     * The cryptographic signature proving you authorized this message. Hex-encoded with a 0x prefix on every supported chain. The signer's own public key is base58 on Solana, but the signature itself is not.
      */
     signature: string;
+    /**
+     * Optional chain-specific payload containing additional signing context (e.g., delegate_signer for Solana). Preserved through the pipeline for downstream consumers.
+     */
+    payload?: {
+        [key: string]: unknown;
+    };
 };
 
 /**
- * Chain defaults returned by the payment gateway /defaults endpoint.
+ * Chain defaults returned by the payment gateway /v1/defaults endpoint.
  */
 interface ChainDefaults {
     escrowContract: string;
@@ -40,9 +39,22 @@ interface ChainDefaults {
     fulfillmentVerifierEndpoint: string;
     fulfillmentProxy: string;
     permit2Contract?: string;
+    /**
+     * Which deposit witness the escrow deployed on this chain pins, surfaced by payment-gw
+     * `/v1/defaults` as `deposit_witness_version` (CORE-2033). EVM/Tron only — Solana carries the
+     * same fact in `svmSignatureDomainVersion` below.
+     *
+     * `4` and above select the CORE-2120 four-member witness
+     * (`depositRequestHash`, `destination`, `reserver`, `releaser`); `3` selects the two-member
+     * witness a not-yet-redeployed escrow pins. ABSENT means four — see the sender-auth package's
+     * `ChainDefaults.depositWitnessVersion` for why absence is the permissive default.
+     *
+     * Passed through to the sender_auth adapter verbatim; this type only has to carry it.
+     */
+    depositWitnessVersion?: number;
     /**
      * V3 Solana escrow domain-separation fields, surfaced by payment-gw
-     * `/defaults` for Solana source chains. Used to build the EscrowDomain that the
+     * `/v1/defaults` for Solana source chains. Used to build the EscrowDomain that the
      * V3 deposit hash binds to. Absent for EVM/Tron.
      */
     svmSignatureClusterId?: string;
@@ -115,7 +127,8 @@ interface TurnkeyConfig {
     /**
      * Chain-native address the signer is expected to resolve to. Verified against
      * the address Turnkey returns at initialize(); a mismatch fails fast rather
-     * than signing as the wrong depositor.
+     * than signing as the wrong depositor. Omit it to skip the check; an empty
+     * value is rejected rather than treated as omitted.
      */
     pinnedAddress?: string;
     /**
@@ -125,7 +138,10 @@ interface TurnkeyConfig {
     logger?: Logger;
     meter?: Meter;
 }
-/** Options selecting a sender-signing provider. Defaults to the private-key provider. */
+/**
+ * Options selecting a sender-signing provider. Defaults to the private-key provider.
+ * `pinnedAddress` behaves the same on both: omitted skips the sender check, empty is rejected.
+ */
 type SenderSignerOptions = {
     provider?: 'raw';
     privateKey: string;
@@ -134,6 +150,74 @@ type SenderSignerOptions = {
     provider: 'turnkey';
 } & TurnkeyConfig);
 
+/**
+ * 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`-hex address (20 bytes) or a base58-encoded address (Solana/Tron), per the field's CAIP-2 chain.
+ */
+interface AtumEscrowExtra$1 {
+    /**
+     * Where the merchant receives (CAIP-2 chain, token, address).
+     */
+    destination: {
+        /**
+         * CAIP-2 destination chain id (e.g. eip155:42161).
+         */
+        network: string;
+        /**
+         * Destination token contract address (EVM hex or base58, per the destination chain).
+         */
+        asset: string;
+        /**
+         * Merchant receive address (EVM hex or base58, per the destination chain).
+         */
+        address: string;
+    };
+    /**
+     * Exact amount the merchant receives, in atomic token units.
+     */
+    fulfillmentAmount: string;
+    /**
+     * Source-chain escrow contract (the x402 payTo); EVM hex or base58, per the source chain.
+     */
+    escrow: string;
+    /**
+     * Destination-chain fulfillment proxy contract (EVM hex or base58, per the destination chain).
+     */
+    fulfillmentProxy: string;
+    /**
+     * Atum reserver role address (escrow deposit witness); EVM hex or base58, per the source chain.
+     */
+    reserver: string;
+    /**
+     * 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 (the network derives the deposit witness roles from them), 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;
+    /**
+     * 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 source only: escrow signature-domain version (V3 domain separation). Optional; required for a Solana source.
+     */
+    svmSignatureDomainVersion?: number;
+}
+
 /**
  * This file was automatically generated by json-schema-to-typescript.
  * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
@@ -223,10 +307,6 @@ interface AtumEscrowExtra {
      * 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;
 }
 
 /**
@@ -304,10 +384,19 @@ declare const CredentialPayloadSchema: z.ZodMiniObject<{
 }, z.core.$strip>;
 /**
  * The `charge` challenge request — the canonical `AtumEscrowRequest` shape (source option
- * + the destination/corridor `extra`). The runtime schema above is verified against this
- * type at compile time (below), so the validator and the canonical schema cannot drift.
+ * + the destination/corridor `extra`), plus the Solana issue time this scheme stamps.
+ *
+ * `issuedAt` is declared here rather than borrowed, because the shared x402 `extra` contract
+ * does not carry it: an x402 resource server rebuilds its requirements on the paid request and
+ * compares them against what the payer echoed, which no clock reading survives. MPP has no such
+ * rebuild, so a merchant-stamped issue time remains coherent here — and is declared where it is
+ * emitted ({@link buildChargeRequest}) rather than inherited from a contract that dropped it.
  */
-type ChargeRequest = AtumEscrowRequest;
+type ChargeRequest = Omit<AtumEscrowRequest, 'extra'> & {
+    extra: AtumEscrowExtra$1 & {
+        issuedAt?: string;
+    };
+};
 /** The `charge` credential payload, carrying the signed Atum payment request. */
 interface ChargeCredentialPayload {
     /** The signed Atum payment request: source/destination, amounts, and authorizations. */
@@ -318,7 +407,7 @@ interface ChargeCredentialPayload {
  * (equal to {@link ChargeRequest} by the compile-time guard above, and compatible with
  * the framework's `Record<string, unknown>` request constraint).
  */
-type AtumEscrowChallenge = Challenge.Challenge<z.infer<typeof ChargeRequestSchema>, "charge", "atum-escrow">;
+type AtumEscrowChallenge = Challenge.Challenge<z.infer<typeof ChargeRequestSchema>, 'charge', 'atum-escrow'>;
 /** The MPP credential for this method. */
 type AtumEscrowCredential = Credential.Credential<ChargeCredentialPayload, AtumEscrowChallenge>;
 /**
@@ -362,4 +451,4 @@ declare const atumEscrowChargeMethod: {
     };
 };
 
-export { type AtumEscrowChallenge as A, type ChargeCredentialPayload as C, INTENT as I, METHOD_NAME as M, type SenderSigner as S, type AtumEscrowCredential as a, type AtumEscrowRequest as b, type ChargeRequest as c, ChargeRequestSchema as d, CredentialPayloadSchema as e, INTENT_ID_META_KEY as f, type SenderSignerOptions as g, atumEscrowChargeMethod as h, type SolanaClusterUnixTimeReader as i, type ChainDefaults as j };
+export { type AtumEscrowChallenge as A, type ChargeCredentialPayload as C, INTENT as I, METHOD_NAME as M, type SenderSigner as S, type AtumEscrowCredential as a, type AtumEscrowExtra$1 as b, type AtumEscrowRequest as c, type ChargeRequest as d, ChargeRequestSchema as e, CredentialPayloadSchema as f, INTENT_ID_META_KEY as g, type SenderSignerOptions as h, atumEscrowChargeMethod as i, type ChainDefaults as j, type SolanaClusterUnixTimeReader as k };

package/dist/server.d.ts

@@ -1,10 +1,9 @@
-import * as zod_v4_core from 'zod/v4/core';
-import * as z from 'zod/mini';
-import { j as ChainDefaults, c as ChargeRequest } from './internal-9tB7y-A7.js';
-export { A as AtumEscrowChallenge, a as AtumEscrowCredential, C as ChargeCredentialPayload, d as ChargeRequestSchema, e as CredentialPayloadSchema, I as INTENT, f as INTENT_ID_META_KEY, M as METHOD_NAME, h as atumEscrowChargeMethod } from './internal-9tB7y-A7.js';
+import { i as atumEscrowChargeMethod, j as ChainDefaults, d as ChargeRequest } from './internal-CJEu9yUF.js';
+export { A as AtumEscrowChallenge, a as AtumEscrowCredential, C as ChargeCredentialPayload, e as ChargeRequestSchema, f as CredentialPayloadSchema, I as INTENT, g as INTENT_ID_META_KEY, M as METHOD_NAME } from './internal-CJEu9yUF.js';
 import { Errors, Receipt, Method } from 'mppx';
 import { PaymentRequest } from './generated/index.js';
 export { PaymentRequest } from './generated/index.js';
+import 'zod/mini';
 
 /**
  * This file was automatically generated by json-schema-to-typescript.
@@ -178,6 +177,26 @@ declare class PaymentRejectedError extends Errors.BadRequestError {
     });
 }
 
+/**
+ * Merchant-side entry point for the Atum escrow MPP payment method.
+ *
+ * Register the returned method into your `mppx` server to accept `atum-escrow`
+ * payments, and use {@link buildChargeRequest} / {@link corridorFromDefaults} to construct
+ * the `402` challenges. Verification recovers the source-chain deposit authorization per
+ * chain (EVM, Tron, Solana) and settles through the Atum Payment Gateway.
+ *
+ * @example
+ * ```ts
+ * import { Mppx } from 'mppx/server'
+ * import { registerServer } from '@atumlabs/mppx-atum-escrow/server'
+ *
+ * const method = registerServer({ submitter })
+ * const mppx = Mppx.create({ realm: 'api.example.com', secretKey, methods: [method] })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 /** One source chain/token the merchant accepts payment from. */
 interface AtumEscrowSource {
     /** CAIP-2 source chain id (e.g. `eip155:8453`, `tron:mainnet`, `solana:<genesis>`). */
@@ -221,7 +240,7 @@ interface AtumEscrowCorridor {
     sources: AtumEscrowSource[];
 }
 /** Lifecycle state the gateway reports for a payment. */
-type PaymentSettlementStatus = "pending" | "completed" | "failed" | "cancelled";
+type PaymentSettlementStatus = 'pending' | 'completed' | 'failed' | 'cancelled';
 /** What a {@link PaymentSubmitter} resolves with. */
 interface PaymentSubmitResult {
     /** The gateway's payment id. Present whenever the payment was accepted. */
@@ -269,6 +288,18 @@ type AtumEscrowReceipt = Receipt.Receipt & {
     /** The full settlement confirmation. */
     fulfillmentConfirmation: FulfillmentConfirmation;
 };
+/**
+ * The merchant-side method {@link registerServer} returns, ready to register into an
+ * `mppx` server via `Mppx.create({ methods: [method] })`.
+ *
+ * Name this type when the method is built in one place and registered in another — for
+ * example a factory that assembles the corridor and submitter for your environment. Its
+ * `verify()` resolves with an {@link AtumEscrowReceipt}, so the settlement confirmation is
+ * available directly on the result.
+ */
+type AtumEscrowServer = Omit<Method.Server<typeof atumEscrowChargeMethod, {}, undefined, {}, undefined>, 'verify'> & {
+    verify: (parameters: Method.VerifyContext<typeof atumEscrowChargeMethod>) => Promise<AtumEscrowReceipt>;
+};
 /**
  * Configure the merchant side of the method.
  *
@@ -284,42 +315,7 @@ type AtumEscrowReceipt = Receipt.Receipt & {
  *
  * @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>;
-                    address: 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>;
-                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: {
-            readonly payload: z.ZodMiniObject<{
-                paymentRequest: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>;
-            }, zod_v4_core.$strip>;
-        };
-    };
-}, {}, undefined, {}, undefined>;
+declare function registerServer(config: AtumEscrowServerConfig): AtumEscrowServer;
 /**
  * Validate a corridor's shape and per-source addresses. Run automatically by
  * {@link buildChargeRequest}; call it directly to fail fast at merchant startup.
@@ -444,4 +440,4 @@ declare function corridorFromDefaults(defaults: ChainDefaultsSource, params: {
     fulfillmentDeadlineSeconds: number;
 }): Promise<AtumEscrowCorridor>;
 
-export { type AtumEscrowCorridor, type AtumEscrowReceipt, type AtumEscrowServerConfig, type AtumEscrowSource, type ChainDefaultsSource, type ChargeChallenge, ChargeRequest, type FulfillmentConfirmation, PaymentRejectedError, type PaymentSettlementStatus, type PaymentSubmitResult, type PaymentSubmitter, type SettlementErrorDetails, SettlementFailedError, SettlementPendingError, buildChargeChallenge, buildChargeRequest, corridorFromDefaults, isPaymentRejected, isSettlementFailed, isSettlementPending, registerServer, validateCorridor };
+export { type AtumEscrowCorridor, type AtumEscrowReceipt, type AtumEscrowServer, type AtumEscrowServerConfig, type AtumEscrowSource, type ChainDefaultsSource, type ChargeChallenge, ChargeRequest, type FulfillmentConfirmation, PaymentRejectedError, type PaymentSettlementStatus, type PaymentSubmitResult, type PaymentSubmitter, type SettlementErrorDetails, SettlementFailedError, SettlementPendingError, atumEscrowChargeMethod, buildChargeChallenge, buildChargeRequest, corridorFromDefaults, isPaymentRejected, isSettlementFailed, isSettlementPending, registerServer, validateCorridor };

package/dist/server.js

@@ -17,7 +17,7 @@ import {
   isSettlementPending,
   registerServer,
   validateCorridor
-} from "./chunk-4YD6566T.js";
+} from "./chunk-TPLD2L6B.js";
 import {
   ChargeRequestSchema,
   CredentialPayloadSchema,
@@ -25,7 +25,7 @@ import {
   INTENT_ID_META_KEY,
   METHOD_NAME,
   atumEscrowChargeMethod
-} from "./chunk-Z3AUNEU5.js";
+} from "./chunk-OEEC5P3E.js";
 export {
   ChargeRequestSchema,
   CredentialPayloadSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atumlabs/mppx-atum-escrow",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Atum cross-chain escrow payment method for the Machine Payments Protocol (MPP).",
   "author": "Atum Labs, Inc.",
   "license": "SEE LICENSE IN LICENSE",
@@ -54,13 +54,14 @@
     "THIRD-PARTY-NOTICES.txt"
   ],
   "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/x402/v1/bindings/typescript/tsconfig.json','../schemas/apis/fulfillment-confirmation/v1/bindings/typescript/tsconfig.json','../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/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/x402/v1/bindings/typescript/tsconfig.json && tsc -p ../schemas/apis/fulfillment-confirmation/v1/bindings/typescript/tsconfig.json && tsc -p ../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/tsconfig.json",
-    "build": "pnpm run build:deps && tsup && node scripts/stamp-entry-headers.mjs",
-    "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/x402/v1/bindings/typescript/dist ../schemas/apis/fulfillment-confirmation/v1/bindings/typescript/dist ../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/dist",
+    "prebuild:deps": "node -e \"if(!require('fs').existsSync('../pnpm-workspace.yaml')){console.error('protocol workspace not found at ../pnpm-workspace.yaml. Is this checked out inside the protocol monorepo?');process.exit(1)}\"",
+    "build:deps": "pnpm --filter \"@atum-labs/mppx-atum-escrow^...\" run build",
+    "build": "tsup && node scripts/stamp-entry-headers.mjs",
+    "lint": "eslint . --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.test.json",
+    "test": "pnpm run typecheck:tests && vitest run",
+    "clean": "rm -rf dist && pnpm --filter \"@atum-labs/mppx-atum-escrow^...\" run clean",
     "check:publishable": "node scripts/check-publishable.mjs",
     "gen:notices": "node scripts/gen-third-party-notices.mjs",
     "prepare": "pnpm run build",
@@ -82,6 +83,7 @@
     "@atum-labs/fulfillment-confirmation": "workspace:*",
     "@atum-labs/payment-gateway-client": "workspace:*",
     "@atum-labs/payment-request-sender-auth": "workspace:*",
+    "@atum-labs/payment-request-token-approval": "workspace:*",
     "@atum-labs/publish-guard": "workspace:*",
     "@atum-labs/schema-declarations": "workspace:*",
     "@atum-labs/solana-escrow-encoding": "workspace:*",