@atumlabs/mppx-atum-escrow 0.3.0 → 0.4.0

package/dist/{chunk-4YD6566T.js → chunk-TPLD2L6B.js}

@@ -11,8 +11,9 @@ import {
   intentIdOf,
   namespaceOf,
   require_dist2 as require_dist,
-  sameAddress
-} from "./chunk-Z3AUNEU5.js";
+  sameAddress,
+  sameAssetIdentifier
+} from "./chunk-OEEC5P3E.js";
 
 // src/server.ts
 var import_payment_request_sender_auth2 = __toESM(require_dist(), 1);
@@ -156,8 +157,7 @@ function registerServer(config) {
         throw new Error("atum-escrow: destination account does not match the challenge");
       }
       const expectedDestAsset = assetIdentifier(extra.destination.network, extra.destination.asset);
-      const destAssetMatches = namespaceOf(extra.destination.network) === "solana" ? dest.asset_identifier === expectedDestAsset : dest.asset_identifier.toLowerCase() === expectedDestAsset.toLowerCase();
-      if (!destAssetMatches) {
+      if (!sameAssetIdentifier(dest.asset_identifier, expectedDestAsset)) {
         throw new Error("atum-escrow: destination asset does not match the challenge");
       }
       if (pr.fulfillment_amount !== extra.fulfillmentAmount) {
@@ -179,7 +179,9 @@ function registerServer(config) {
         throw new Error("atum-escrow: fulfillment_proxy does not match the challenge");
       }
       if (!sameAddress(pr.fulfillment_verifier?.account ?? "", expectedVerifier.account)) {
-        throw new Error("atum-escrow: fulfillment_verifier.account does not match the challenge releaser");
+        throw new Error(
+          "atum-escrow: fulfillment_verifier.account does not match the challenge releaser"
+        );
       }
       if ((pr.fulfillment_verifier?.endpoint ?? "") !== expectedVerifier.endpoint) {
         throw new Error("atum-escrow: fulfillment_verifier.endpoint does not match the challenge");
@@ -247,13 +249,21 @@ function validateCorridor(corridor) {
     throw new Error("atum-escrow: corridor must configure at least one source");
   }
   for (const src of corridor.sources) {
-    for (const field of ["network", "escrow", "reserver", "releaser", "fulfillmentVerifierEndpoint"]) {
+    for (const field of [
+      "network",
+      "escrow",
+      "reserver",
+      "releaser",
+      "fulfillmentVerifierEndpoint"
+    ]) {
       if (!src[field]) {
         throw new Error(`atum-escrow: source ${src.network ?? "?"} is missing '${field}'`);
       }
     }
     if (!src.assets || src.assets.length === 0 || src.assets.some((a) => !a)) {
-      throw new Error(`atum-escrow: source ${src.network} must list at least one non-empty asset in 'assets'`);
+      throw new Error(
+        `atum-escrow: source ${src.network} must list at least one non-empty asset in 'assets'`
+      );
     }
     if (namespaceOf(src.network) === "tron") {
       (0, import_payment_request_sender_auth.resolveTronPermit2)(src.network);

package/dist/client.d.ts

@@ -1,11 +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-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 { Method } from 'mppx';
+import { Signer } from 'ethers';
 export { PaymentRequest } from './generated/index.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 +265,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

@@ -6,9 +6,9 @@
  */
 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-KRSFEITH.js";
 import {
   ChargeRequestSchema,
   CredentialPayloadSchema,
@@ -16,7 +16,10 @@ import {
   INTENT_ID_META_KEY,
   METHOD_NAME,
   atumEscrowChargeMethod
-} from "./chunk-Z3AUNEU5.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,
@@ -24,6 +27,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,8 @@
-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-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 { PaymentRequest } from './generated/index.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

@@ -6,9 +6,9 @@
  */
 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-KRSFEITH.js";
 import {
   PaymentRejectedError,
   SettlementFailedError,
@@ -21,7 +21,7 @@ import {
   isSettlementPending,
   registerServer,
   validateCorridor
-} from "./chunk-4YD6566T.js";
+} from "./chunk-TPLD2L6B.js";
 import {
   ChargeRequestSchema,
   CredentialPayloadSchema,
@@ -29,7 +29,10 @@ import {
   INTENT_ID_META_KEY,
   METHOD_NAME,
   atumEscrowChargeMethod
-} from "./chunk-Z3AUNEU5.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,
@@ -43,10 +46,12 @@ export {
   buildChargeChallenge,
   buildChargeRequest,
   corridorFromDefaults,
-  ensureSourceApproval,
+  export_ensureSourceApproval as ensureSourceApproval,
   isPaymentRejected,
   isSettlementFailed,
   isSettlementPending,
+  export_isUnconfirmed as isUnconfirmed,
+  export_needsSourceApproval as needsSourceApproval,
   registerClient,
   registerServer,
   validateCorridor