@atumlabs/mppx-atum-escrow 0.3.0 → 0.4.1

package/dist/client.d.ts

@@ -1,10 +1,187 @@
 import * as zod_v4_core from 'zod/v4/core';
 import * as z from 'zod/mini';
-import { Signer } from 'ethers';
-import { S as SenderSigner, g as SenderSignerOptions, i as SolanaClusterUnixTimeReader } from './internal-9tB7y-A7.js';
-export { A as AtumEscrowChallenge, a as AtumEscrowCredential, C as ChargeCredentialPayload, c as ChargeRequest, 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 { S as SenderSigner, h as SenderSignerOptions, k as SolanaClusterUnixTimeReader } from './internal-BZBJJfaL.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-BZBJJfaL.js';
 import { Method } from 'mppx';
+import { Signer } from 'ethers';
 export { PaymentRequest } from './generated/index.js';
+import './sender-auth-verify-C-Q-zvAO.js';
+
+/**
+ * Result of an {@link ensureSourceApproval} call.
+ */
+interface EnsureApprovalResult {
+    /** The existing allowance already covered the requirement; no transaction was sent. */
+    alreadySufficient: boolean;
+    /** The approval transaction hash, when one was sent. */
+    txHash?: string;
+    /**
+     * Set only when the token refused to overwrite a non-zero allowance and it had to be reset to
+     * zero first: the hash of that reset. Its absence means one transaction was sent, not two.
+     */
+    resetTxHash?: string;
+}
+/** What TronWeb reports about a broadcast transaction. Empty until it is confirmed. */
+interface TronTransactionInfo {
+    receipt?: {
+        result?: string;
+    };
+}
+/**
+ * The slice of a TronWeb instance this package needs.
+ *
+ * Declared structurally rather than imported from `tronweb` on purpose: the package then
+ * type-checks and builds with tronweb absent, and consumers that never pay from Tron do not
+ * carry an 11 MB dependency they cannot reach. The caller constructs the instance and passes
+ * it in, exactly as the EVM path takes a caller-constructed ethers signer.
+ */
+interface TronWebLike {
+    /**
+     * The ABI-and-address form, which builds the handle locally. The `contract().at(address)`
+     * form fetches the ABI from the node instead: a round trip per use, and an interface that
+     * depends on what the chain happens to report for that address.
+     *
+     * Returns `unknown` on purpose. TronWeb types this as a contract whose methods are produced
+     * dynamically from the ABI, so pinning it to {@link TronTokenContract} here would stop a real
+     * TronWeb instance assigning to this interface at all and force every caller to write a cast.
+     * The cast belongs in one place — next to the ABI we passed, which is what makes it true.
+     */
+    contract(abi: unknown, address: string): unknown;
+    trx: {
+        getTransactionInfo(txId: string): Promise<TronTransactionInfo>;
+    };
+    /**
+     * The account this instance signs as. Read to check it against `owner` before broadcasting,
+     * since an approval only ever applies to the account that sends it.
+     *
+     * Optional, and `false` is TronWeb's own "not set": both mean the instance cannot say which
+     * account it would use, and neither is treated as a mismatch.
+     */
+    defaultAddress?: {
+        base58?: string | false;
+    };
+}
+/** How long to wait for a broadcast approval to confirm before giving up, on either chain. */
+interface ConfirmationOptions {
+    /**
+     * Default 60_000. On timeout the approval is reported as unconfirmed rather than failed: it
+     * was broadcast and may still confirm, so the caller is told to check it before sending
+     * another one.
+     */
+    timeoutMs?: number;
+    /** Tron only: how often to poll for the receipt. Default 1_500, under Tron's ~3s block time. */
+    pollIntervalMs?: number;
+    /** Tron only: default 100_000_000 SUN. Tron charges the caller for contract execution. */
+    feeLimit?: number;
+}
+/**
+ * Inputs to {@link ensureSourceApproval} and {@link needsSourceApproval}.
+ *
+ * `signer` and `tronWeb` are both optional here because which one is required is decided by
+ * `network`, a runtime string that no type can constrain. Supplying the wrong one for the
+ * chain fails with a message naming the one that was needed.
+ */
+interface ApprovalParams {
+    /** CAIP-2 source chain id, e.g. `eip155:8453` or `tron:mainnet`. */
+    network: string;
+    /** Source token address. */
+    token: string;
+    /** The payer's account. */
+    owner: string;
+    /**
+     * The contract to approve. Defaults to the canonical Permit2 for the chain: the EVM
+     * deployment on `eip155:*`, and the pinned per-network address on `tron:*`.
+     */
+    spender?: string;
+    /**
+     * The minimum allowance this charge needs. Answers "is what I already have enough?".
+     * When omitted, only an unlimited approval counts as sufficient, so a smaller leftover
+     * allowance cannot be mistaken for enough and revert a larger later charge on-chain.
+     */
+    requiredAllowance?: bigint;
+    /**
+     * How much to approve when an approval IS sent. Defaults to unlimited, so later charges on
+     * the same token need no further transaction.
+     *
+     * On its own, a bounded amount is treated as its own requirement: an allowance still holding
+     * the full bound is left alone rather than re-approved. That is the right answer for a one-off
+     * approval, where nothing else in the call says what a later charge would need.
+     *
+     * Across repeated payments, PAIR IT WITH `requiredAllowance`. Permit2 decrements the allowance
+     * on every payment, so a bound measured against itself stops being sufficient the moment the
+     * first charge lands, and every later call sends another approval. `requiredAllowance` states
+     * what the NEXT charge needs, which is the question a partly spent bound can still answer yes
+     * to.
+     *
+     * Trade-off: a bounded approval limits what the escrow can ever move, but it is consumed as it
+     * is spent and eventually has to be granted again, whichever way it is used.
+     */
+    approvalAmount?: bigint;
+    /** An ethers signer connected to the source chain. Required for `eip155:*`. */
+    signer?: Signer;
+    /** A TronWeb instance configured for the source chain. Required for `tron:*`. */
+    tronWeb?: TronWebLike;
+    /** Broadcast and confirmation tuning. Applies to both chains. */
+    confirmation?: ConfirmationOptions;
+    /**
+     * Called with each transaction hash the moment it is broadcast, before the wait for it to
+     * confirm. Without this a caller has nothing to show for a transaction that is already
+     * spending their gas — and nothing to look up if the wait times out.
+     *
+     * `purpose` distinguishes the approval itself from the zero-reset some tokens demand first,
+     * so two hashes in one call read as one deliberate sequence rather than a double spend.
+     */
+    onSubmitted?: (txHash: string, purpose: "approval" | "reset") => void;
+}
+
+/** Whether an error came from a broadcast transaction that was never seen to confirm. */
+declare function isUnconfirmed(error: unknown): boolean;
+
+/**
+ * Payer-side Permit2 approval for the source token an escrow deposit moves.
+ *
+ * On EVM and Tron the escrow moves the source token through Permit2, so the payer must have
+ * approved Permit2 on that token BEFORE paying. Without it the payment is built, signed and
+ * accepted by the gateway, and then the deposit reverts on-chain at settlement — a late and
+ * misleading failure. Solana authorizes the transfer inside the signed deposit itself, so
+ * there is nothing to approve there.
+ *
+ * Worth arranging before the payment is signed: a deposit that reverts is a terminal
+ * settlement failure, and a terminal failure is bound to the request identifier that produced
+ * it, so re-attempting then needs a NEW identifier. Getting the allowance right up front keeps
+ * the identifier usable.
+ *
+ * This package reads chain state and broadcasts a transaction, which is why it is separate
+ * from the sender-auth SDK next door: that one is pure, offline and byte-parity-tested against
+ * Go. The caller supplies the connected signer, so this package never chooses an RPC endpoint.
+ */
+
+/**
+ * Whether a payment on these terms would need an approval transaction first.
+ *
+ * Read-only: it spends no gas and sends nothing, so it is safe to call on every payment as a
+ * preflight. Returns false on Solana, which needs no approval at all.
+ *
+ * @remarks
+ * Unlike a try-and-see, this reports the answer instead of acting on it — use it to tell a
+ * payer what is about to happen, or to check whether a wallet is ready before asking for a
+ * signature.
+ */
+declare function needsSourceApproval(params: ApprovalParams): Promise<boolean>;
+/**
+ * Ensure the payer has approved Permit2 to move the source token, so the escrow deposit does
+ * not revert at settlement. Reads the current allowance and sends an approval only if it falls
+ * short; the approval it sends is unlimited unless `approvalAmount` bounds it.
+ *
+ * Applies to EVM (`params.signer`) and Tron (`params.tronWeb`). On Solana it reports
+ * `alreadySufficient` without touching the chain.
+ *
+ * @remarks
+ * Not concurrency-safe: two overlapping calls for the same `(owner, token, spender)` may both
+ * read a short allowance and both send an approval. They target the same value, so this only
+ * wastes gas; serialize calls per token if that matters.
+ */
+declare function ensureSourceApproval(params: ApprovalParams): Promise<EnsureApprovalResult>;
 
 /** Configuration for the payer side of the method. */
 interface AtumEscrowClientConfig {
@@ -89,43 +266,5 @@ declare function registerClient(config: AtumEscrowClientConfig): Method.Client<{
         };
     };
 }, undefined>;
-/** Result of an {@link ensureSourceApproval} call. */
-interface EnsureApprovalResult {
-    /** The existing allowance already covered the required amount; no transaction was sent. */
-    alreadySufficient: boolean;
-    /** The approval transaction hash, when one was sent. */
-    txHash?: string;
-}
-/**
- * Ensure the payer has approved the token-transfer contract (Permit2) to move the source
- * token, so the escrow deposit does not revert at settlement. Reads the current allowance
- * and sends an approval only if it falls short.
- *
- * Applies to EVM and Tron sources (which use a Permit2-style allowance); Solana sources
- * authorize the transfer in the signed deposit itself, so this is a no-op there.
- *
- * @param params.network - CAIP-2 source chain id.
- * @param params.token - source token address.
- * @param params.owner - the payer's account.
- * @param params.signer - an ethers signer able to send the approval on `network`.
- * @param params.spender - the contract to approve; defaults to the canonical EVM Permit2.
- *   Required for Tron (its Permit2 address is chain-specific).
- * @param params.requiredAllowance - the minimum allowance this charge needs (pass the
- *   source cap, `challenge.request.source.amount`). When omitted, the function ensures an
- *   unlimited approval — a smaller leftover allowance is NOT treated as sufficient, so a
- *   later larger charge cannot slip through and revert on-chain.
- *
- * Not concurrency-safe: two overlapping calls for the same `(owner, token, spender)` may
- * both read a short allowance and both send an approval. They target the same value, so
- * this only wastes gas; serialize calls per token if that matters.
- */
-declare function ensureSourceApproval(params: {
-    network: string;
-    token: string;
-    owner: string;
-    signer: Signer;
-    spender?: string;
-    requiredAllowance?: bigint;
-}): Promise<EnsureApprovalResult>;
 
-export { type AtumEscrowClientConfig, type EnsureApprovalResult, SenderSigner, SenderSignerOptions, ensureSourceApproval, registerClient };
+export { type ApprovalParams, type AtumEscrowClientConfig, type ConfirmationOptions, type EnsureApprovalResult, SenderSigner, SenderSignerOptions, type TronWebLike, ensureSourceApproval, isUnconfirmed, needsSourceApproval, registerClient };

package/dist/client.js

@@ -1,14 +1,12 @@
 /*
- * 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 {
-  ensureSourceApproval,
+  import_payment_request_token_approval,
   registerClient
-} from "./chunk-ZFA5SSUP.js";
+} from "./chunk-IGTT7XSG.js";
 import {
   ChargeRequestSchema,
   CredentialPayloadSchema,
@@ -16,7 +14,10 @@ import {
   INTENT_ID_META_KEY,
   METHOD_NAME,
   atumEscrowChargeMethod
-} from "./chunk-Z3AUNEU5.js";
+} from "./chunk-LAWFMGYD.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,
@@ -24,6 +25,8 @@ export {
   INTENT_ID_META_KEY,
   METHOD_NAME,
   atumEscrowChargeMethod,
-  ensureSourceApproval,
+  export_ensureSourceApproval as ensureSourceApproval,
+  export_isUnconfirmed as isUnconfirmed,
+  export_needsSourceApproval as needsSourceApproval,
   registerClient
 };

package/dist/index.d.ts

@@ -1,82 +1,9 @@
-export { A as AtumEscrowChallenge, a as AtumEscrowCredential, b as AtumEscrowRequest, C as ChargeCredentialPayload, c as ChargeRequest, d as ChargeRequestSchema, e as CredentialPayloadSchema, I as INTENT, f as INTENT_ID_META_KEY, M as METHOD_NAME, S as SenderSigner, g as SenderSignerOptions, h as atumEscrowChargeMethod } from './internal-9tB7y-A7.js';
-export { AtumEscrowClientConfig, EnsureApprovalResult, ensureSourceApproval, registerClient } from './client.js';
-export { AtumEscrowCorridor, AtumEscrowReceipt, 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-BZBJJfaL.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 { PaymentRequest } from './generated/index.js';
+import './sender-auth-verify-C-Q-zvAO.js';
 import 'zod/mini';
 import 'mppx';
 import 'zod/v4/core';
 import 'ethers';
-
-/**
- * This file was automatically generated by json-schema-to-typescript.
- * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
- * and run json-schema-to-typescript to regenerate this file.
- */
-/**
- * The `extra.atum` object carried inside an atum-escrow x402 PaymentRequirements entry (accepts[]): the merchant's receive-side plus the contract/role addresses and deadline budgets. Scheme-specific data the standard x402 `extra` bag treats as opaque, so it is owned here and shared by all role mechanisms. Addresses are chain-general: an EVM `0x`-hex address (20 bytes) or a base58-encoded address (Solana/Tron), per the field's CAIP-2 chain.
- */
-interface AtumEscrowExtra {
-    /**
-     * 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;
-    /**
-     * 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;
-}
-
-export type { AtumEscrowExtra };

package/dist/index.js

@@ -1,14 +1,12 @@
 /*
- * 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 {
-  ensureSourceApproval,
+  import_payment_request_token_approval,
   registerClient
-} from "./chunk-ZFA5SSUP.js";
+} from "./chunk-IGTT7XSG.js";
 import {
   PaymentRejectedError,
   SettlementFailedError,
@@ -21,7 +19,7 @@ import {
   isSettlementPending,
   registerServer,
   validateCorridor
-} from "./chunk-4YD6566T.js";
+} from "./chunk-EWIOTGMO.js";
 import {
   ChargeRequestSchema,
   CredentialPayloadSchema,
@@ -29,7 +27,10 @@ import {
   INTENT_ID_META_KEY,
   METHOD_NAME,
   atumEscrowChargeMethod
-} from "./chunk-Z3AUNEU5.js";
+} from "./chunk-LAWFMGYD.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,
@@ -43,10 +44,12 @@ export {
   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-9tB7y-A7.d.ts → internal-BZBJJfaL.d.ts}

@@ -1,37 +1,10 @@
+import { t } from './sender-auth-verify-C-Q-zvAO.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: Base64 encoded message
-     * - 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.
-     * Format varies by blockchain (hex for EVM/Tron, base58 for Solana).
-     *
-     */
-    signature: string;
-};
-
-/**
- * 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 +13,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`. EVM/Tron only — Solana carries the
+     * same fact in `svmSignatureDomainVersion` below.
+     *
+     * `4` and above select the 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;
@@ -104,7 +90,7 @@ interface SenderSignature {
 }
 /** Signs a single sender_auth signed message for a payment request. */
 interface SenderSigner {
-    sign(signedMessage: SignedMessage): Promise<SenderSignature>;
+    sign(signedMessage: t): Promise<SenderSignature>;
 }
 /** Turnkey provider configuration (shared by the SDK and the CLI env loader). */
 interface TurnkeyConfig {
@@ -115,7 +101,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 +112,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 +124,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 +281,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 +358,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 +381,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 +425,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 };