@atumlabs/mppx-atum-escrow 0.4.0 → 0.5.0

package/dist/client.d.ts

@@ -1,10 +1,170 @@
 import * as zod_v4_core from 'zod/v4/core';
 import * as z from 'zod/mini';
-import { S as SenderSigner, h as SenderSignerOptions, k as SolanaClusterUnixTimeReader } from './internal-CJEu9yUF.js';
-export { A as AtumEscrowChallenge, a as AtumEscrowCredential, C as ChargeCredentialPayload, d as ChargeRequest, e as ChargeRequestSchema, f as CredentialPayloadSchema, I as INTENT, g as INTENT_ID_META_KEY, M as METHOD_NAME, i as atumEscrowChargeMethod } from './internal-CJEu9yUF.js';
+import { S as SenderSigner, h as SenderSignerOptions, k as SolanaClusterUnixTimeReader } from './internal-DwRZPk7k.js';
+export { A as AtumEscrowChallenge, a as AtumEscrowCredential, C as ChargeCredentialPayload, d as ChargeRequest, e as ChargeRequestSchema, f as CredentialPayloadSchema, I as INTENT, g as INTENT_ID_META_KEY, M as METHOD_NAME, i as atumEscrowChargeMethod } from './internal-DwRZPk7k.js';
 import { Method } from 'mppx';
 import { Signer } from 'ethers';
 export { PaymentRequest } from './generated/index.js';
+import './sender-auth-verify-BbTnhw79.js';
+
+/**
+ * The payer's trust source for atum-escrow corridors.
+ *
+ * An MPP challenge names the escrow, the fulfillment proxy, the reserver and the releaser the
+ * payer is about to sign into its deposit authorization. The merchant writes those values, but the
+ * reserver decides who is paid and how much of the cap, and the releaser decides when the escrow
+ * opens, so they are the payer's trust points to choose. The client therefore checks each one
+ * against a source the payer controls before signing anything; the challenge is a claim, not an
+ * authority.
+ */
+/**
+ * A token a trust source vouches for on one chain. `decimals` is what lets the client compare a
+ * source-token cap with a destination-token price.
+ *
+ * @public
+ */
+interface TrustedToken {
+    symbol: string;
+    address: string;
+    decimals: number;
+}
+/**
+ * The addresses a trust source vouches for on one chain.
+ *
+ * The keys match the corridor defaults the signing library takes, so a trusted set can be compared
+ * field by field with what a challenge asks the payer to sign.
+ *
+ * @public
+ */
+interface TrustedRoles {
+    /** The source escrow contract: the Permit2 spender a deposit authorizes. */
+    escrowContract: string;
+    /** The account that signs reserve witnesses (the challenge's `reserver`). */
+    quoteSelector: string;
+    /** The account that signs release and refund witnesses (the challenge's `releaser`). */
+    fulfillmentVerifierAccount: string;
+    /** The fulfillment proxy, compared on the chain the payment is delivered on. */
+    fulfillmentProxy: string;
+    /** The tokens payable on this chain; a payment in any other token is refused. */
+    tokens: ReadonlyArray<TrustedToken>;
+}
+/**
+ * Answers which addresses the payer trusts on a chain, given its CAIP-2 id.
+ *
+ * Rejects with {@link AtumEscrowTrustError} `CHAIN_NOT_TRUSTED` when it vouches for nothing on the
+ * chain, and `TRUST_SOURCE_UNAVAILABLE` when it cannot find out. Any other rejection is reported by
+ * the client as `TRUST_SOURCE_UNAVAILABLE`.
+ *
+ * @public
+ */
+type TrustResolver = (network: string) => Promise<TrustedRoles>;
+/**
+ * Why a payment was refused before signing.
+ *
+ * @public
+ */
+type AtumEscrowTrustErrorCode = 'UNTRUSTED_ESCROW' | 'UNTRUSTED_RESERVER' | 'UNTRUSTED_RELEASER' | 'UNTRUSTED_FULFILLMENT_PROXY' | 'UNTRUSTED_ASSET' | 'ASSETS_NOT_COMPARABLE' | 'MARKUP_EXCEEDED' | 'CHAIN_NOT_TRUSTED' | 'TRUST_SOURCE_UNAVAILABLE';
+/**
+ * A payment the client refused to sign because its corridor is not one the payer trusts.
+ *
+ * `code` is the stable thing to branch on. For the `UNTRUSTED_*` codes and `MARKUP_EXCEEDED`,
+ * `field` names the challenge member that failed and `actual` the value the challenge asked for;
+ * `expected`, when set, is the trusted value or, for `MARKUP_EXCEEDED`, the largest amount
+ * allowed. Values are reported as written.
+ *
+ * @public
+ */
+declare class AtumEscrowTrustError extends Error {
+    readonly code: AtumEscrowTrustErrorCode;
+    readonly network: string;
+    readonly field?: string;
+    readonly expected?: string;
+    readonly actual?: string;
+    constructor(init: {
+        code: AtumEscrowTrustErrorCode;
+        network: string;
+        message: string;
+        field?: string;
+        expected?: string;
+        actual?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * The payment gateways the client asks when the payer supplies no trust source: Atum's production
+ * mainnet and production testnet deployments. Their chain ids never overlap, so at most one serves
+ * a given chain.
+ *
+ * @public
+ */
+declare const ATUM_DEFAULT_TRUST_GATEWAYS: readonly string[];
+/**
+ * Options for {@link atumGatewayTrust}.
+ *
+ * @public
+ */
+interface AtumGatewayTrustOptions {
+    /**
+     * Gateway base URLs to ask. Defaults to {@link ATUM_DEFAULT_TRUST_GATEWAYS}.
+     *
+     * Each chain must be served by at most one gateway in the list: the first trusted answer is
+     * used, so two gateways vouching for different roles on one chain would make the outcome depend
+     * on which answers first.
+     *
+     * Trailing slashes are removed; an entry with nothing left after that (`''`, `'/'`) is refused
+     * when the resolver is built. An empty list trusts no chain.
+     */
+    gateways?: readonly string[];
+    /** The `fetch` to use. Defaults to the global one, read at call time. */
+    fetch?: typeof fetch;
+    /** Clock for cache expiry, in epoch milliseconds. Defaults to `Date.now`. */
+    now?: () => number;
+    /** How long a trusted answer is reused, in milliseconds. Defaults to 300000. */
+    ttlMs?: number;
+    /** How long one gateway may take to answer, in milliseconds. Defaults to 5000. */
+    timeoutMs?: number;
+}
+/**
+ * A trust source backed by payment gateways' `GET /v1/defaults`.
+ *
+ * Every gateway is asked. The first well-formed answer for the chain is trusted. Only when every
+ * gateway answers 404 is the chain reported as not trusted: a gateway that failed might have been
+ * the one serving it, so any failure without a usable answer is reported as unavailable instead.
+ * Trusted answers are cached per chain, and concurrent lookups for a chain share one round of
+ * requests; failures are never cached, so recovery needs no wait.
+ *
+ * @throws `Error` when a configured gateway is empty once its trailing slashes are removed.
+ *
+ * @public
+ */
+declare function atumGatewayTrust(options?: AtumGatewayTrustOptions): TrustResolver;
+
+/**
+ * The payer's bound on the spend cap.
+ *
+ * The cap (`source.amount`) is the most the escrow may ever pull from the payer. An honest auction
+ * charges less, but a thin auction, a compromised quote selector or a bug can charge up to the cap,
+ * so the payer refuses a cap further above the price than it allows. The price is
+ * `fulfillmentAmount`, in the destination token; the cap is in the source token, so both are
+ * compared in one unit, and only between tokens the payer treats as the same money.
+ */
+
+/**
+ * The markup over `fulfillmentAmount`, in basis points, the client accepts when the payer sets
+ * none: room above the 3% the merchant SDK documents, while bounding the payer's extra exposure.
+ *
+ * @public
+ */
+declare const DEFAULT_MAX_MARKUP_BPS = 500;
+/**
+ * Tokens the client treats as interchangeable 1:1 when the payer sets none: the US-dollar
+ * stablecoins on the network's allowlists. The allowlist records only symbol, address and
+ * decimals, so this list is the peg assumption itself. A token outside every group is comparable
+ * only with itself.
+ *
+ * @public
+ */
+declare const DEFAULT_PEG_GROUPS: ReadonlyArray<ReadonlyArray<string>>;
 
 /**
  * Result of an {@link ensureSourceApproval} call.
@@ -205,6 +365,30 @@ interface AtumEscrowClientConfig {
      * used. Ignored for EVM/Tron.
      */
     solanaClockReader?: SolanaClusterUnixTimeReader;
+    /**
+     * Where the payer learns which escrow, fulfillment proxy, reserver and releaser it trusts on a
+     * chain. Every challenge is checked against it before anything is signed, and a challenge naming
+     * any other address is refused.
+     *
+     * @remarks
+     * Optional. Without it, the client asks Atum's production gateways (see
+     * {@link atumGatewayTrust} and {@link ATUM_DEFAULT_TRUST_GATEWAYS}). Pass your own resolver to
+     * trust another deployment — staging, a local devnet (which reuses mainnet chain ids), or another
+     * operator — or a fixed set of addresses. The check itself cannot be turned off.
+     */
+    trust?: TrustResolver;
+    /**
+     * The most the cap (`source.amount`) may exceed `fulfillmentAmount`, in basis points, after both
+     * are put in one unit. A larger cap is refused before signing. Defaults to
+     * {@link DEFAULT_MAX_MARKUP_BPS}.
+     */
+    maxMarkupBps?: number;
+    /**
+     * Groups of token symbols the payer treats as the same money, so a cap in one can be priced
+     * against a fulfillment in another. Replaces {@link DEFAULT_PEG_GROUPS}; a token outside every
+     * group is comparable only with itself.
+     */
+    pegGroups?: ReadonlyArray<ReadonlyArray<string>>;
 }
 /**
  * Configure the payer side of the method.
@@ -266,4 +450,4 @@ declare function registerClient(config: AtumEscrowClientConfig): Method.Client<{
     };
 }, undefined>;
 
-export { type ApprovalParams, type AtumEscrowClientConfig, type ConfirmationOptions, type EnsureApprovalResult, SenderSigner, SenderSignerOptions, type TronWebLike, ensureSourceApproval, isUnconfirmed, needsSourceApproval, registerClient };
+export { ATUM_DEFAULT_TRUST_GATEWAYS, type ApprovalParams, type AtumEscrowClientConfig, AtumEscrowTrustError, type AtumEscrowTrustErrorCode, type AtumGatewayTrustOptions, type ConfirmationOptions, DEFAULT_MAX_MARKUP_BPS, DEFAULT_PEG_GROUPS, type EnsureApprovalResult, SenderSigner, SenderSignerOptions, type TronWebLike, type TrustResolver, type TrustedRoles, type TrustedToken, atumGatewayTrust, ensureSourceApproval, isUnconfirmed, needsSourceApproval, registerClient };

package/dist/client.js

@@ -1,14 +1,17 @@
 /*
- * Copyright (c) 2026 Atum Labs, Inc. All rights reserved.
- * Proprietary and confidential.
- * Access and use are governed by the LICENSE file distributed with this package.
- * Do not remove, alter, or obscure this notice.
+ * Copyright 2026 Atum Labs, Inc.
+ * SPDX-License-Identifier: Apache-2.0
  */
 import { createRequire as __atumCreateRequire } from 'module'; const require = __atumCreateRequire(import.meta.url);
 import {
+  ATUM_DEFAULT_TRUST_GATEWAYS,
+  AtumEscrowTrustError,
+  DEFAULT_MAX_MARKUP_BPS,
+  DEFAULT_PEG_GROUPS,
+  atumGatewayTrust,
   import_payment_request_token_approval,
   registerClient
-} from "./chunk-KRSFEITH.js";
+} from "./chunk-NVPGDBFS.js";
 import {
   ChargeRequestSchema,
   CredentialPayloadSchema,
@@ -16,17 +19,22 @@ import {
   INTENT_ID_META_KEY,
   METHOD_NAME,
   atumEscrowChargeMethod
-} from "./chunk-OEEC5P3E.js";
+} from "./chunk-F3H73WI3.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 {
+  ATUM_DEFAULT_TRUST_GATEWAYS,
+  AtumEscrowTrustError,
   ChargeRequestSchema,
   CredentialPayloadSchema,
+  DEFAULT_MAX_MARKUP_BPS,
+  DEFAULT_PEG_GROUPS,
   INTENT,
   INTENT_ID_META_KEY,
   METHOD_NAME,
   atumEscrowChargeMethod,
+  atumGatewayTrust,
   export_ensureSourceApproval as ensureSourceApproval,
   export_isUnconfirmed as isUnconfirmed,
   export_needsSourceApproval as needsSourceApproval,

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { A as AtumEscrowChallenge, a as AtumEscrowCredential, b as AtumEscrowExtra, c as AtumEscrowRequest, C as ChargeCredentialPayload, d as ChargeRequest, e as ChargeRequestSchema, f as CredentialPayloadSchema, I as INTENT, g as INTENT_ID_META_KEY, M as METHOD_NAME, S as SenderSigner, h as SenderSignerOptions, i as atumEscrowChargeMethod } from './internal-CJEu9yUF.js';
-export { ApprovalParams, AtumEscrowClientConfig, ConfirmationOptions, EnsureApprovalResult, TronWebLike, ensureSourceApproval, isUnconfirmed, needsSourceApproval, registerClient } from './client.js';
-export { AtumEscrowCorridor, AtumEscrowReceipt, AtumEscrowServer, AtumEscrowServerConfig, AtumEscrowSource, ChainDefaultsSource, ChargeChallenge, FulfillmentConfirmation, PaymentRejectedError, PaymentSettlementStatus, PaymentSubmitResult, PaymentSubmitter, SettlementErrorDetails, SettlementFailedError, SettlementPendingError, buildChargeChallenge, buildChargeRequest, corridorFromDefaults, isPaymentRejected, isSettlementFailed, isSettlementPending, registerServer, validateCorridor } from './server.js';
+export { A as AtumEscrowChallenge, a as AtumEscrowCredential, b as AtumEscrowExtra, c as AtumEscrowRequest, C as ChargeCredentialPayload, d as ChargeRequest, e as ChargeRequestSchema, f as CredentialPayloadSchema, I as INTENT, g as INTENT_ID_META_KEY, M as METHOD_NAME, S as SenderSigner, h as SenderSignerOptions, i as atumEscrowChargeMethod } from './internal-DwRZPk7k.js';
+export { ATUM_DEFAULT_TRUST_GATEWAYS, ApprovalParams, AtumEscrowClientConfig, AtumEscrowTrustError, AtumEscrowTrustErrorCode, AtumGatewayTrustOptions, ConfirmationOptions, DEFAULT_MAX_MARKUP_BPS, DEFAULT_PEG_GROUPS, EnsureApprovalResult, TronWebLike, TrustResolver, TrustedRoles, TrustedToken, atumGatewayTrust, ensureSourceApproval, isUnconfirmed, needsSourceApproval, registerClient } from './client.js';
+export { AtumEscrowCorridor, AtumEscrowReceipt, AtumEscrowServer, AtumEscrowServerConfig, AtumEscrowSource, ChainDefaultsSource, ChargeChallenge, CommitmentOutcome, CommitmentResult, FulfillmentConfirmation, PaymentRejectedError, PaymentSettlementStatus, PaymentSubmitResult, PaymentSubmitter, SettlementErrorDetails, SettlementFailedError, SettlementPendingError, buildChargeChallenge, buildChargeRequest, corridorFromDefaults, isPaymentRejected, isSettlementFailed, isSettlementPending, registerServer, validateCorridor } from './server.js';
 export { PaymentRequest } from './generated/index.js';
+import './sender-auth-verify-BbTnhw79.js';
 import 'zod/mini';
 import 'mppx';
 import 'zod/v4/core';

package/dist/index.js

@@ -1,14 +1,17 @@
 /*
- * Copyright (c) 2026 Atum Labs, Inc. All rights reserved.
- * Proprietary and confidential.
- * Access and use are governed by the LICENSE file distributed with this package.
- * Do not remove, alter, or obscure this notice.
+ * Copyright 2026 Atum Labs, Inc.
+ * SPDX-License-Identifier: Apache-2.0
  */
 import { createRequire as __atumCreateRequire } from 'module'; const require = __atumCreateRequire(import.meta.url);
 import {
+  ATUM_DEFAULT_TRUST_GATEWAYS,
+  AtumEscrowTrustError,
+  DEFAULT_MAX_MARKUP_BPS,
+  DEFAULT_PEG_GROUPS,
+  atumGatewayTrust,
   import_payment_request_token_approval,
   registerClient
-} from "./chunk-KRSFEITH.js";
+} from "./chunk-NVPGDBFS.js";
 import {
   PaymentRejectedError,
   SettlementFailedError,
@@ -21,7 +24,7 @@ import {
   isSettlementPending,
   registerServer,
   validateCorridor
-} from "./chunk-TPLD2L6B.js";
+} from "./chunk-5IQDNGVU.js";
 import {
   ChargeRequestSchema,
   CredentialPayloadSchema,
@@ -29,13 +32,17 @@ import {
   INTENT_ID_META_KEY,
   METHOD_NAME,
   atumEscrowChargeMethod
-} from "./chunk-OEEC5P3E.js";
+} from "./chunk-F3H73WI3.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 {
+  ATUM_DEFAULT_TRUST_GATEWAYS,
+  AtumEscrowTrustError,
   ChargeRequestSchema,
   CredentialPayloadSchema,
+  DEFAULT_MAX_MARKUP_BPS,
+  DEFAULT_PEG_GROUPS,
   INTENT,
   INTENT_ID_META_KEY,
   METHOD_NAME,
@@ -43,6 +50,7 @@ export {
   SettlementFailedError,
   SettlementPendingError,
   atumEscrowChargeMethod,
+  atumGatewayTrust,
   buildChargeChallenge,
   buildChargeRequest,
   corridorFromDefaults,

package/dist/{internal-CJEu9yUF.d.ts → internal-DwRZPk7k.d.ts}

@@ -1,34 +1,8 @@
+import { B } from './sender-auth-verify-BbTnhw79.js';
 import * as z from 'zod/mini';
 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.
- */
-type SignedMessage = {
-    /**
-     * The data that was signed. Format depends on the blockchain:
-     * - EVM: Hex-encoded message hash (with 0x prefix)
-     * - 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.
-     */
-    message_prehash?: string;
-    /**
-     * 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 /v1/defaults endpoint.
  */
@@ -40,22 +14,8 @@ interface ChainDefaults {
     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
-     * `/v1/defaults` for Solana source chains. Used to build the EscrowDomain that the
-     * V3 deposit hash binds to. Absent for EVM/Tron.
+     * Solana escrow domain-separation fields, used to build the EscrowDomain the deposit hash
+     * binds to. Absent for EVM/Tron.
      */
     svmSignatureClusterId?: string;
     svmSignatureDomainVersion?: number;
@@ -116,7 +76,7 @@ interface SenderSignature {
 }
 /** Signs a single sender_auth signed message for a payment request. */
 interface SenderSigner {
-    sign(signedMessage: SignedMessage): Promise<SenderSignature>;
+    sign(signedMessage: B): Promise<SenderSignature>;
 }
 /** Turnkey provider configuration (shared by the SDK and the CLI env loader). */
 interface TurnkeyConfig {

package/dist/server.d.ts

@@ -1,10 +1,41 @@
-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 { i as atumEscrowChargeMethod, j as ChainDefaults, d as ChargeRequest } from './internal-DwRZPk7k.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-DwRZPk7k.js';
+import { Errors, Receipt, Method } from 'mppx';
+import './sender-auth-verify-BbTnhw79.js';
 import 'zod/mini';
 
+/** Verdict of a destination-commitment check. Only `verified` admits a payment. */
+type CommitmentOutcome = 'verified'
+/** The source chain is unsupported, or message_scheme cannot authorise a payment from it. */
+ | 'scheme_mismatch'
+/** The signed deposit commits no destination or no request hash. */
+ | 'commitment_absent'
+/** message_prehash is unreadable, ambiguous, or not the document behind the signed digest. */
+ | 'prehash_mismatch'
+/** The deposit is not signed by, or not made out to, the payment's source account. */
+ | 'signer_mismatch'
+/** The signed destination is not the payment's destination. */
+ | 'destination_mismatch'
+/** The signed depositRequestHash is not keccak256 of the payment's request_id. */
+ | 'request_hash_mismatch'
+/** The payment request document is unreadable or ambiguous. */
+ | 'request_malformed'
+/** The verifier did not supply what the check needs. */
+ | 'verifier_misconfigured';
+/** The outcome of a check plus the values it compared, for admissions and refusals alike. */
+interface CommitmentResult {
+    outcome: CommitmentOutcome;
+    detail: string;
+    namespace: string;
+    scheme: string;
+    signedDestination: string;
+    expectedDestination: string;
+    signedDepositRequestHash: string;
+    expectedDepositRequestHash: string;
+}
+
 /**
  * This file was automatically generated by json-schema-to-typescript.
  * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
@@ -239,8 +270,14 @@ 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';
+/**
+ * Lifecycle state the gateway reports for a payment.
+ *
+ * `finalizing` means the payment is on chain but has not yet reached the confirmation depth its
+ * chain requires. It is NOT terminal: a payer must keep waiting on the same idempotency key, never
+ * start a second payment for it.
+ */
+type PaymentSettlementStatus = 'pending' | 'finalizing' | 'completed' | 'failed';
 /** What a {@link PaymentSubmitter} resolves with. */
 interface PaymentSubmitResult {
     /** The gateway's payment id. Present whenever the payment was accepted. */
@@ -260,10 +297,8 @@ interface PaymentSubmitResult {
  *
  * 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.
+ * {@link SettlementPendingError}, and the payer's retry of the same purchase resolves to the same
+ * payment and collects the result.
  *
  * Throw {@link PaymentRejectedError} when the gateway refuses the request, so the refusal keeps
  * its code. Any other throw is treated as an unknown outcome.
@@ -277,7 +312,15 @@ interface AtumEscrowServerConfig {
     submitter: PaymentSubmitter;
     /** Clock (epoch ms) used to validate deadline ordering and budgets. Defaults to `Date.now`. */
     now?: () => number;
+    /**
+     * Called with the result of every payee check, admissions and refusals alike, so you can count
+     * payments by `logFields.sender_auth_result` and log each refusal with all of `logFields`. A
+     * refused payment still throws; an exception from this callback on an admission refuses the
+     * payment with a fixed message.
+     */
+    onCommitmentResult?: (result: CommitmentResult, logFields: Record<string, string>) => void;
 }
+
 /**
  * The receipt returned once a payment settles, extending the MPP receipt with the Atum
  * settlement details. `reference` carries the destination-chain transaction hash, and
@@ -331,10 +374,9 @@ declare function validateCorridor(corridor: AtumEscrowCorridor): void;
  * 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.
+ * the payer requires. A challenge built from this function alone carries no such identifier, and
+ * the payer's client refuses it at signing time. Use it directly only when supplying the
+ * per-purchase metadata yourself.
  *
  * @param corridor - the corridor to serve.
  * @param select - which configured source to fund from, by `(network, asset)`.
@@ -342,9 +384,8 @@ declare function validateCorridor(corridor: AtumEscrowCorridor): void;
  *   destination token. Set per charge so one registration serves any price.
  * @param options.issuedAt - Solana-source only: the merchant's cluster-clock reading (epoch
  *   seconds) to stamp into `extra.issuedAt`, so the payer's client builds the deposit fully
- *   offline (no RPC). Omit to let the client stamp `issued_at` from its own clock at signing
- *   time — which keeps the full replay window; a merchant-stamped value anchors the window
- *   earlier (at 402-build time), so only set it when the client genuinely cannot read a clock.
+ *   offline (no RPC). Omit to let the client stamp `issued_at` at signing time, which keeps the
+ *   full replay window; a merchant-stamped value starts the window at 402-build time.
  *   Ignored for EVM/Tron sources.
  * @throws if no source option matches `select`, or the corridor is invalid.
  */
@@ -357,11 +398,8 @@ declare function buildChargeRequest(corridor: AtumEscrowCorridor, select: {
 /**
  * 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.
+ * `request` is the method-specific payment terms and `meta` is challenge metadata, matching the
+ * framework's shape. Both are covered by the challenge-id HMAC.
  */
 interface ChargeChallenge {
     /** The method-specific charge request (the payment terms). */
@@ -440,4 +478,4 @@ declare function corridorFromDefaults(defaults: ChainDefaultsSource, params: {
     fulfillmentDeadlineSeconds: number;
 }): Promise<AtumEscrowCorridor>;
 
-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 };
+export { type AtumEscrowCorridor, type AtumEscrowReceipt, type AtumEscrowServer, type AtumEscrowServerConfig, type AtumEscrowSource, type ChainDefaultsSource, type ChargeChallenge, ChargeRequest, type CommitmentOutcome, type CommitmentResult, 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

@@ -1,8 +1,6 @@
 /*
- * Copyright (c) 2026 Atum Labs, Inc. All rights reserved.
- * Proprietary and confidential.
- * Access and use are governed by the LICENSE file distributed with this package.
- * Do not remove, alter, or obscure this notice.
+ * Copyright 2026 Atum Labs, Inc.
+ * SPDX-License-Identifier: Apache-2.0
  */
 import { createRequire as __atumCreateRequire } from 'module'; const require = __atumCreateRequire(import.meta.url);
 import {
@@ -17,7 +15,7 @@ import {
   isSettlementPending,
   registerServer,
   validateCorridor
-} from "./chunk-TPLD2L6B.js";
+} from "./chunk-5IQDNGVU.js";
 import {
   ChargeRequestSchema,
   CredentialPayloadSchema,
@@ -25,7 +23,7 @@ import {
   INTENT_ID_META_KEY,
   METHOD_NAME,
   atumEscrowChargeMethod
-} from "./chunk-OEEC5P3E.js";
+} from "./chunk-F3H73WI3.js";
 export {
   ChargeRequestSchema,
   CredentialPayloadSchema,

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@atumlabs/mppx-atum-escrow",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Atum cross-chain escrow payment method for the Machine Payments Protocol (MPP).",
   "author": "Atum Labs, Inc.",
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "Apache-2.0",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "homepage": "https://github.com/Atum-Labs/protocol/tree/main/mppx-atum-escrow#readme",
+  "homepage": "https://github.com/Atum-Labs/protocol/tree/main/schemas/apis/payment-gateway/v1/bindings/mppx-atum-escrow#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Atum-Labs/protocol.git",
-    "directory": "mppx-atum-escrow"
+    "directory": "schemas/apis/payment-gateway/v1/bindings/mppx-atum-escrow"
   },
   "bugs": {
     "url": "https://github.com/Atum-Labs/protocol/issues"
@@ -51,10 +51,11 @@
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
+    "NOTICE",
     "THIRD-PARTY-NOTICES.txt"
   ],
   "scripts": {
-    "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)}\"",
+    "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",
@@ -92,7 +93,7 @@
     "mppx": "^0.8.12",
     "tsup": "^8.5.1",
     "typescript": "^5.6.3",
-    "vitest": "^2.1.9",
+    "vitest": "^4.1.11",
     "zod": "^4.4.3"
   }
 }