@atumlabs/mppx-atum-escrow 0.2.2 → 0.4.0

package/dist/index.js

@@ -6,31 +6,52 @@
  */
 import { createRequire as __atumCreateRequire } from 'module'; const require = __atumCreateRequire(import.meta.url);
 import {
-  ensureSourceApproval,
+  import_payment_request_token_approval,
   registerClient
-} from "./chunk-IPZJXELQ.js";
+} from "./chunk-KRSFEITH.js";
 import {
+  PaymentRejectedError,
+  SettlementFailedError,
+  SettlementPendingError,
+  buildChargeChallenge,
   buildChargeRequest,
   corridorFromDefaults,
+  isPaymentRejected,
+  isSettlementFailed,
+  isSettlementPending,
   registerServer,
   validateCorridor
-} from "./chunk-NEM3HEZW.js";
+} from "./chunk-TPLD2L6B.js";
 import {
   ChargeRequestSchema,
   CredentialPayloadSchema,
   INTENT,
+  INTENT_ID_META_KEY,
   METHOD_NAME,
   atumEscrowChargeMethod
-} from "./chunk-4P34CLTO.js";
+} from "./chunk-OEEC5P3E.js";
+var export_ensureSourceApproval = import_payment_request_token_approval.ensureSourceApproval;
+var export_isUnconfirmed = import_payment_request_token_approval.isUnconfirmed;
+var export_needsSourceApproval = import_payment_request_token_approval.needsSourceApproval;
 export {
   ChargeRequestSchema,
   CredentialPayloadSchema,
   INTENT,
+  INTENT_ID_META_KEY,
   METHOD_NAME,
+  PaymentRejectedError,
+  SettlementFailedError,
+  SettlementPendingError,
   atumEscrowChargeMethod,
+  buildChargeChallenge,
   buildChargeRequest,
   corridorFromDefaults,
-  ensureSourceApproval,
+  export_ensureSourceApproval as ensureSourceApproval,
+  isPaymentRejected,
+  isSettlementFailed,
+  isSettlementPending,
+  export_isUnconfirmed as isUnconfirmed,
+  export_needsSourceApproval as needsSourceApproval,
   registerClient,
   registerServer,
   validateCorridor

package/dist/{internal-DzEGXm14.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;
 }
 
 /**
@@ -245,6 +325,24 @@ interface AtumEscrowExtra {
 declare const METHOD_NAME = "atum-escrow";
 /** The MPP intent this method implements. */
 declare const INTENT = "charge";
+/**
+ * Challenge-metadata key carrying the merchant's per-intent payment identifier.
+ *
+ * The payer derives the payment's `request_id` from this value, and the gateway
+ * de-duplicates on that `request_id`. So the key's lifetime defines what counts as "the same
+ * payment": one value per thing being bought, reused on every retry of that purchase, never
+ * shared between two purchases.
+ *
+ * It rides in challenge metadata rather than in the charge request because it identifies the
+ * purchase, not its terms — two sequential orders for the same item have identical terms and
+ * must still be two payments. Metadata is covered by the challenge-id HMAC, so a payer cannot
+ * substitute another intent's identifier to have a second purchase resolve onto an
+ * already-settled payment.
+ *
+ * Prefixed to keep it distinct from a merchant's own metadata and from the framework's
+ * reserved keys.
+ */
+declare const INTENT_ID_META_KEY = "atumIntentId";
 /**
  * Schema for the `charge` challenge request — the method-specific data a merchant
  * publishes in an MPP `402` challenge. It describes what the merchant receives and the
@@ -286,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. */
@@ -300,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>;
 /**
@@ -344,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, type SenderSignerOptions as f, atumEscrowChargeMethod as g, type SolanaClusterUnixTimeReader as h, type ChainDefaults as i };
+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 { i as ChainDefaults, c as ChargeRequest } from './internal-DzEGXm14.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-DzEGXm14.js';
-import { Receipt, Method } from 'mppx';
+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.
@@ -53,6 +52,151 @@ interface FulfillmentConfirmation {
     destination_block_number?: number;
 }
 
+/**
+ * Settlement outcomes that are not a receipt.
+ *
+ * MPP models a completed payment and nothing else: a receipt's status is the literal
+ * `"success"`, so a payment that has not settled cannot be expressed as one and has to leave
+ * `verify()` as a throw. What matters is that the two non-success outcomes stay
+ * distinguishable, because they call for opposite responses:
+ *
+ * - {@link SettlementPendingError} — the payment is still settling. Retrying the SAME purchase
+ *   is safe and is how the payer collects the result: the identifier it derives from resolves to
+ *   this same payment, so the gateway returns the original rather than charging again.
+ * - {@link SettlementFailedError} — the payment reached a terminal failure. Retrying the same
+ *   purchase resolves to the dead payment forever, so recovering means starting a NEW purchase
+ *   under a new identifier.
+ *
+ * Both carry the gateway's payment id when one was issued, so a merchant can reconcile the
+ * attempt against the gateway without parsing a message.
+ *
+ * Both extend the framework's error types, so a merchant that does not distinguish them still
+ * gets the standard `402` + problem-details response.
+ *
+ * @packageDocumentation
+ */
+
+/** Fields shared by both settlement outcomes. */
+interface SettlementErrorDetails {
+    /** The gateway's payment id, when the payment was accepted and given one. */
+    readonly paymentId: string | undefined;
+}
+/** True if the payment is still settling — a retry of the same purchase is safe. */
+declare function isSettlementPending(err: unknown): err is SettlementPendingError;
+/** True if the payment reached a terminal failure — the same purchase can never settle. */
+declare function isSettlementFailed(err: unknown): err is SettlementFailedError;
+/** True if the gateway refused the request outright — nothing was charged. */
+declare function isPaymentRejected(err: unknown): err is PaymentRejectedError;
+/**
+ * The payment was accepted but had not settled when the merchant's synchronous window closed.
+ *
+ * Not a failure: the payment is in flight. Re-attempting the same purchase is safe — it resolves to
+ * this payment and returns its result once settled.
+ *
+ * **What re-attempting means.** Run the purchase again: request a fresh challenge and sign it again,
+ * keeping the same intent id. The intent id is what makes the re-attempt resolve onto the payment
+ * already in flight rather than taking a second one, so it must not change — while everything
+ * time-bound about the authorization must, because the deadlines are absolute timestamps fixed when
+ * it was signed. A stored credential therefore cannot simply be presented a second time; once its
+ * quote window has closed it is refused, and on Solana the deposit authorization carries its own
+ * replay window that expires with it.
+ *
+ * A payment-enabled `fetch` does this for the caller, since each attempt fetches a new challenge.
+ * Code that drives the client directly has to rebuild.
+ */
+declare class SettlementPendingError extends Errors.PaymentActionRequiredError implements SettlementErrorDetails {
+    /** Discriminant; test it with {@link isSettlementPending}. */
+    readonly isSettlementPending: true;
+    readonly paymentId: string | undefined;
+    constructor(options?: {
+        paymentId?: string | undefined;
+    });
+    /**
+     * 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?: string): Errors.PaymentError.ProblemDetails & {
+        paymentId?: string;
+    };
+}
+/**
+ * The payment reached a terminal failure state and will not settle.
+ *
+ * A retry of the same purchase cannot recover it: that purchase's identifier now resolves to
+ * this failed payment. Recovering means a new purchase under a new identifier.
+ */
+declare class SettlementFailedError extends Errors.VerificationFailedError implements SettlementErrorDetails {
+    /** Discriminant; test it with {@link isSettlementFailed}. */
+    readonly isSettlementFailed: true;
+    readonly paymentId: string | undefined;
+    /** The terminal state the gateway reported. */
+    readonly state: string;
+    constructor(options: {
+        paymentId?: string | undefined;
+        state: string;
+    });
+    /**
+     * 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?: string): Errors.PaymentError.ProblemDetails & {
+        paymentId?: string;
+        state: string;
+    };
+}
+/**
+ * The gateway refused the payment outright — it never entered settlement.
+ *
+ * Distinct from {@link SettlementFailedError}: nothing was charged and nothing is in flight, so
+ * the fault is in the request and fixing it makes the same purchase payable. The most common
+ * cause is reusing one purchase identifier for two different sets of terms, which the gateway
+ * rejects rather than silently resolving to the first payment.
+ *
+ * Thrown by a {@link ../server!PaymentSubmitter | PaymentSubmitter} — the submitter owns the
+ * gateway call, so it is the only place that can tell a refusal (the request was rejected) from
+ * a transport or server failure (the outcome is unknown, and reporting it as a refusal would
+ * invite a second payment). Classify on the response status rather than on the body, so an
+ * intermediary that rewrites the error payload cannot turn a refusal into an unknown outcome.
+ * Raising it preserves the gateway's error code through to the payer instead of flattening every
+ * cause into one generic verification failure.
+ */
+declare class PaymentRejectedError extends Errors.BadRequestError {
+    /** Discriminant; test it with {@link isPaymentRejected}. */
+    readonly isPaymentRejected: true;
+    /** The gateway's error code, for programmatic handling. */
+    readonly code: string;
+    constructor(options: {
+        code: string;
+        detail: string;
+    });
+}
+
+/**
+ * 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>`). */
@@ -95,15 +239,37 @@ interface AtumEscrowCorridor {
     /** Accepted source options; selected per charge by `(network, asset)`. */
     sources: AtumEscrowSource[];
 }
+/** Lifecycle state the gateway reports for a payment. */
+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. */
+    payment_id?: string;
+    /**
+     * The payment's state. When absent, an unsettled payment is treated as still in flight —
+     * the conservative reading, since calling an in-flight payment failed would tell the payer to
+     * start a second one.
+     */
+    status?: PaymentSettlementStatus;
+    /** The settlement confirmation, present once the payment has completed. */
+    fulfillment_confirmation?: FulfillmentConfirmation;
+}
 /**
  * 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`.
+ *
+ * Submit and return what the gateway said; do not poll for completion inside the submitter.
+ * A payment that outlives the gateway's synchronous window surfaces to the payer as
+ * {@link SettlementPendingError}, and the payer's retry of the same purchase is what collects the
+ * result — the gateway resolves that retry to the same payment. Polling inside the submitter
+ * instead holds the merchant's request open for the full settlement window and hides the pending
+ * state that makes the retry safe.
+ *
+ * Throw {@link PaymentRejectedError} when the gateway refuses the request, so the refusal keeps
+ * its code. Any other throw is treated as an unknown outcome.
  */
 interface PaymentSubmitter {
-    submit(request: PaymentRequest): Promise<{
-        payment_id?: string;
-        fulfillment_confirmation?: FulfillmentConfirmation;
-    }>;
+    submit(request: PaymentRequest): Promise<PaymentSubmitResult>;
 }
 /** Configuration for the merchant side of the method. */
 interface AtumEscrowServerConfig {
@@ -122,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.
  *
@@ -137,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.
@@ -182,10 +325,16 @@ declare function registerServer(config: AtumEscrowServerConfig): Method.Server<{
  */
 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.
+ * Build the `charge` challenge request for a specific source option from a corridor — the
+ * payment terms alone. 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.
+ *
+ * Prefer {@link buildChargeChallenge}, which pairs these terms with the per-purchase identifier
+ * the payer requires. A challenge built from this function alone carries no such identifier and
+ * the payer's client refuses it — at signing time, not at build time, so code that calls this
+ * directly and worked before only surfaces the problem when a real payer's client refuses the
+ * payment. Reach for it directly only when supplying the per-purchase metadata by hand.
  *
  * @param corridor - the corridor to serve.
  * @param select - which configured source to fund from, by `(network, asset)`.
@@ -205,6 +354,62 @@ declare function buildChargeRequest(corridor: AtumEscrowCorridor, select: {
 }, fulfillmentAmount: string, options?: {
     issuedAt?: string;
 }): ChargeRequest;
+/**
+ * A charge challenge's two halves, ready to hand to the framework.
+ *
+ * They are separate because the framework keeps them separate: `request` is the
+ * method-specific payment terms, `meta` is challenge metadata. Both are covered by the
+ * challenge-id HMAC, but nesting the metadata inside the request would bury the purchase
+ * identifier in the terms blob where the payer does not look for it — so this type keeps them in
+ * the shape the framework expects.
+ */
+interface ChargeChallenge {
+    /** The method-specific charge request (the payment terms). */
+    request: ChargeRequest;
+    /** Challenge metadata carrying the per-intent identifier. */
+    meta: Record<string, string>;
+}
+/**
+ * Build a charge challenge for a specific source option from a corridor.
+ *
+ * This is the entry point a merchant should use: it pairs the payment terms with the per-purchase
+ * identifier the payer needs to make the payment retry-safe. A challenge built without that
+ * identifier is refused by the payer's client rather than paid unsafely.
+ *
+ * Pass the result straight through to the framework:
+ *
+ * ```ts
+ * const { request, meta } = buildChargeChallenge(corridor, source, amount, { intentId: order.id })
+ *
+ * // Route-handler style:
+ * mppx.compose(['atum-escrow/charge', { ...request, meta }])(input)
+ *
+ * // Or building the challenge directly:
+ * Challenge.fromMethod(atumEscrowChargeMethod, { request, meta, realm, secretKey })
+ * ```
+ *
+ * @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.
+ * @param options.intentId - identifies the thing being bought. Use the merchant's own order,
+ *   invoice, or cart identifier: one value per purchase, the SAME value every time that purchase
+ *   is re-offered or retried, and never shared between two purchases. The payer derives the
+ *   payment's identity from it and the gateway de-duplicates on that, so its lifetime is what
+ *   decides whether a retry is recognized (a value that changes per attempt causes a second
+ *   charge) and whether two purchases stay distinct (a value shared between them leaves the
+ *   second unpaid). Do not derive it from the terms: two orders for the same item have identical
+ *   terms.
+ * @param options.issuedAt - Solana-source only; see {@link buildChargeRequest}.
+ * @throws if `intentId` is empty, or the corridor/source selection is invalid.
+ */
+declare function buildChargeChallenge(corridor: AtumEscrowCorridor, select: {
+    network: string;
+    asset: string;
+}, fulfillmentAmount: string, options: {
+    intentId: string;
+    issuedAt?: string;
+}): ChargeChallenge;
 /** The minimal defaults source `corridorFromDefaults` needs; satisfied by the gateway client. */
 interface ChainDefaultsSource {
     fetchChainDefaults(chainId: string): Promise<ChainDefaults>;
@@ -235,4 +440,4 @@ declare function corridorFromDefaults(defaults: ChainDefaultsSource, params: {
     fulfillmentDeadlineSeconds: number;
 }): Promise<AtumEscrowCorridor>;
 
-export { type AtumEscrowCorridor, type AtumEscrowReceipt, type AtumEscrowServerConfig, type AtumEscrowSource, type ChainDefaultsSource, ChargeRequest, type FulfillmentConfirmation, type PaymentSubmitter, buildChargeRequest, corridorFromDefaults, 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 };