@atumlabs/mppx-atum-escrow 0.3.0 → 0.4.1

package/README.md

@@ -1,11 +1,13 @@
 # @atumlabs/mppx-atum-escrow
 
-> **Proprietary software - not open source.**
+> Copyright 2026 Atum Labs, Inc.
 >
-> Copyright (c) 2026 Atum Labs, Inc. All rights reserved. Access to and use of `@atumlabs/mppx-atum-escrow` are limited to entities expressly authorized by Atum and are governed by the Atum MPP Escrow SDK Proprietary License Agreement in the LICENSE file included with this package. Do not redistribute, publish, mirror, sublicense, or provide this package to any unauthorized person. By accessing, installing, copying, or using the package, you agree to the license terms.
+> Licensed under the Apache License, Version 2.0. See the `LICENSE` file
+> distributed with this package.
 
 An [`mppx`](https://www.npmjs.com/package/mppx) payment method that lets a merchant accept
 **cross-chain stablecoin payments** through Atum, over the Machine Payments Protocol (MPP).
+Full documentation: [docs.atum.xyz](https://docs.atum.xyz).
 
 - The **payer** funds the payment in any supported source asset and chain (e.g. USDC on Base,
   USDT on Tron, or USDC on Solana).
@@ -81,9 +83,6 @@ The merchant examples below also use
 [`@atumlabs/payment-gateway-client`](https://www.npmjs.com/package/@atumlabs/payment-gateway-client)
 for the gateway connection and corridor defaults.
 
-> The snippets below are illustrative. For complete, runnable, end-to-end integrations
-> (payer + merchant), see the examples repository: **https://github.com/Atum-Labs/examples**.
-
 ## Key concepts
 
 | Term | What it means |
@@ -101,6 +100,18 @@ for the gateway connection and corridor defaults.
 All addresses and amounts are strings; all amounts are **atomic units** (never floats). Addresses
 are in each chain's native form — `0x…` hex for EVM, base58 for Tron and Solana.
 
+### Which chains and assets can a corridor use?
+
+Atum supports many corridors. The identifier for every supported token is listed under
+[supported assets](https://docs.atum.xyz/get-started/reference/supported-assets), and the chain ids
+under [supported networks](https://docs.atum.xyz/get-started/reference/supported-networks). Assets
+are named with [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) identifiers, for example
+`eip155:84532/erc20:0x036CbD53842c5426634e7929541eC2318f3dCF7e` for USDC on Base Sepolia.
+
+Copy identifiers exactly: base58 values, such as Solana token mints and account addresses, are
+case-sensitive. The escrow and role addresses for each chain are filled in by
+`corridorFromDefaults`, so you never paste those by hand.
+
 ## Quick start — merchant (server)
 
 ```ts
@@ -231,11 +242,66 @@ await ensureSourceApproval({
   owner: wallet.address,
   signer: wallet,
   // Pass the source cap this charge needs (from the challenge). A leftover smaller allowance
-  // then won't be mistaken for enough. Omit it to ensure an unlimited approval instead.
+  // then won't be mistaken for enough.
   requiredAllowance: BigInt(challenge.request.source.amount),
 });
 ```
 
+Paying from Tron takes a TronWeb instance instead of an ethers signer; everything else is the
+same, and the Permit2 address for the network is resolved for you:
+
+```ts
+await ensureSourceApproval({ network: "tron:mainnet", token, owner, tronWeb });
+```
+
+The approval waits to be mined before returning, bounded by `confirmation.timeoutMs` (one minute
+by default); a timeout is reported as unconfirmed rather than failed, since the transaction may
+still land. `onSubmitted` hands you the hash the moment it is broadcast.
+
+`isUnconfirmed(error)` tells the two apart. It matters because the responses are opposite: a
+failed approval needs another one, an unconfirmed approval needs a look at the transaction and
+nothing else. Sending a second one on top of the first only pays for an allowance you are already
+getting.
+
+```ts
+try {
+  await ensureSourceApproval({ network, token, owner, signer });
+} catch (error) {
+  if (isUnconfirmed(error)) {
+    // Broadcast, not yet seen to confirm. Check the hash from onSubmitted; do not re-send.
+  } else {
+    throw error;
+  }
+}
+```
+
+On EVM, tokens that refuse to overwrite a non-zero allowance — mainnet USDT most notably — are
+reset to zero first, automatically and only where the token demands it; the result then carries a
+`resetTxHash` too. Tron does not do this, because an ordinary TRC-20 accepts the change in place.
+
+The approval sent is unlimited, so later charges on the same token need no further transaction.
+To bound the approval that gets sent, pass `approvalAmount`. On its own the amount is treated as
+its own requirement, so an allowance still holding the full bound is left alone rather than
+re-approved — the right answer for a one-off approval. Across repeated payments, pair it with
+`requiredAllowance`: Permit2 decrements the allowance on every payment, so a bound measured
+against itself stops covering itself the moment the first charge lands, and every later call
+would send another approval. Either way a bounded approval is consumed as it is spent and
+eventually has to be granted again.
+
+These helpers raise an allowance to what a payment needs; they never lower one. A wallet already
+holding more than `approvalAmount` is left exactly as it is and reports `alreadySufficient`
+without sending anything. Reducing or revoking an allowance is a separate operation, and not one
+these perform.
+
+`needsSourceApproval(params)` takes the same arguments and answers the same question without
+sending anything, so it is safe to call before every charge:
+
+```ts
+if (await needsSourceApproval({ network, token, owner, signer })) {
+  // tell the payer a one-off approval transaction is coming, before asking them to sign
+}
+```
+
 ## What the merchant `verify()` guarantees
 
 `verify()` fails fast (no chain I/O) before submitting, and throws if any check fails. The Atum
@@ -274,6 +340,9 @@ On success you get an `AtumEscrowReceipt` — the MPP receipt plus the full sett
 }
 ```
 
+`verify()` resolves with this type, so `fulfillmentConfirmation` is available straight off the
+result. `AtumEscrowReceipt` is exported, so you can name it in your own function signatures.
+
 ## Retries and idempotency
 
 A retry must never become a second charge, and two different purchases must never collapse into
@@ -465,7 +534,7 @@ Import everything from the root, or from the role-specific entry points (which e
 each side needs):
 
 - `@atumlabs/mppx-atum-escrow` — everything below
-- `@atumlabs/mppx-atum-escrow/client` — `registerClient`, `ensureSourceApproval` + payer types
+- `@atumlabs/mppx-atum-escrow/client` — `registerClient`, `ensureSourceApproval`, `needsSourceApproval` + payer types
 - `@atumlabs/mppx-atum-escrow/server` — `registerServer`, `buildChargeChallenge`,
   `buildChargeRequest`, `validateCorridor`, `corridorFromDefaults`, the settlement errors +
   merchant types
@@ -473,12 +542,13 @@ each side needs):
 | Export | Description |
 | --- | --- |
 | `registerClient(config)` | Payer-side method. `config`: `{ signer, account, now?, solanaClockReader? }`. |
-| `registerServer(config)` | Merchant-side method. `config`: `{ submitter, now? }`. |
+| `registerServer(config)` | Merchant-side method. `config`: `{ submitter, now? }`. Returns an `AtumEscrowServer`, whose `verify()` resolves with an `AtumEscrowReceipt`. |
 | `buildChargeChallenge(corridor, select, fulfillmentAmount, { intentId, issuedAt? })` | Builds a `charge` challenge — the payment terms plus the per-purchase identifier that makes a retry safe. **Use this.** Returns `{ request, meta }`. |
 | `buildChargeRequest(corridor, select, fulfillmentAmount, options?)` | The payment terms alone, without the identifier. For supplying challenge metadata by hand. |
 | `validateCorridor(corridor)` | Validates a corridor's shape and per-source addresses (run automatically by both builders). |
 | `corridorFromDefaults(defaults, params)` | Builds a corridor by fetching escrow/role/proxy addresses from the gateway `/defaults`. |
-| `ensureSourceApproval(params)` | Ensures the payer has approved Permit2 to move the source token (EVM/Tron; no-op on Solana). |
+| `ensureSourceApproval(params)` | Ensures the payer has approved Permit2 to move the source token. `signer` for EVM, `tronWeb` for Tron; no-op on Solana. |
+| `needsSourceApproval(params)` | Whether `ensureSourceApproval` would send a transaction. Read-only, spends no gas. |
 | `SettlementPendingError`, `SettlementFailedError`, `PaymentRejectedError` | The non-receipt outcomes of `verify()`. See [Settlement outcomes](#settlement-outcomes). |
 | `isSettlementPending`, `isSettlementFailed`, `isPaymentRejected` | Guards for the above. |
 | `atumEscrowChargeMethod` | The base `mppx` method (advanced/custom wiring). |
@@ -488,10 +558,17 @@ each side needs):
 
 Key types: `AtumEscrowCorridor`, `AtumEscrowSource`, `SenderSigner`, `SenderSignerOptions`,
 `PaymentSubmitter`, `PaymentSubmitResult`, `PaymentSettlementStatus`, `AtumEscrowClientConfig`,
-`AtumEscrowServerConfig`, `ChainDefaultsSource`, `EnsureApprovalResult`, `AtumEscrowChallenge`,
-`AtumEscrowCredential`, `AtumEscrowReceipt`, `ChargeChallenge`, `ChargeRequest`,
+`AtumEscrowServer`, `AtumEscrowServerConfig`, `ChainDefaultsSource`, `EnsureApprovalResult`,
+`AtumEscrowChallenge`, `AtumEscrowCredential`, `AtumEscrowReceipt`, `ChargeChallenge`, `ChargeRequest`,
 `SettlementErrorDetails`, `PaymentRequest`, `FulfillmentConfirmation`.
 
 > **EVM implementation note:** on EVM the deposit authorization is a Permit2
 > `PermitWitnessTransferFrom` signature; Tron uses the equivalent TIP-712 typed data, and Solana
 > uses an ed25519-signed deposit. The public API is the same across all three.
+
+## Further reading
+
+- [Accepting and making MPP payments with Atum](https://docs.atum.xyz/payment-protocols/mpp/overview)
+- [Supported assets](https://docs.atum.xyz/get-started/reference/supported-assets) and [supported networks](https://docs.atum.xyz/get-started/reference/supported-networks)
+- [MPP](https://mpp.dev)
+- [Atum documentation](https://docs.atum.xyz)

package/THIRD-PARTY-NOTICES.txt

@@ -2,6 +2,12 @@ THIRD-PARTY SOFTWARE NOTICES AND INFORMATION
 ==============================================================================
 @atumlabs/mppx-atum-escrow
 
+@atumlabs/mppx-atum-escrow is licensed under the Apache License, Version 2.0, as stated
+in the package-root LICENSE file. THIS file is not that license. This
+package includes the third-party software identified below; the licenses and
+notices reproduced here apply only to those third-party components. They do not
+modify the Apache-2.0 license governing this package or any Atum-authored code.
+
 The published artifact of this package (the compiled code under dist/) statically
 bundles the third-party open-source components listed below; their source is
 redistributed within this package, so their license and copyright notices are
@@ -11,9 +17,9 @@ as (peer)dependencies of this package (for example @solana/web3.js, ethers, bs58
 tweetnacl, zod, and mppx) — those ship under their own licenses and are not
 redistributed here.
 
-LICENSE SUMMARY (27 components)
+LICENSE SUMMARY (28 components)
 ------------------------------------------------------------------------------
-   27  MIT
+   28  MIT
 ==============================================================================
 
 ------------------------------------------------------------------------------
@@ -43,6 +49,13 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 
+------------------------------------------------------------------------------
+agent-base  6.0.2   (MIT)
+Author: Nathan Rajlich <nathan@tootallnate.net> (http://n8.io/)
+------------------------------------------------------------------------------
+
+[No license file is distributed inside this package. Declared license: MIT; author: Nathan Rajlich <nathan@tootallnate.net> (http://n8.io/).]
+
 ------------------------------------------------------------------------------
 asynckit  0.4.0   (MIT)
 Author: Alex Indigo <iam@alexindigo.com>
@@ -71,7 +84,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 ------------------------------------------------------------------------------
-axios  1.13.2   (MIT)
+axios  1.20.0   (MIT)
 Author: Matt Zabriskie
 ------------------------------------------------------------------------------
 
@@ -556,6 +569,13 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+------------------------------------------------------------------------------
+https-proxy-agent  5.0.1   (MIT)
+Author: Nathan Rajlich <nathan@tootallnate.net> (http://n8.io/)
+------------------------------------------------------------------------------
+
+[No license file is distributed inside this package. Declared license: MIT; author: Nathan Rajlich <nathan@tootallnate.net> (http://n8.io/).]
+
 ------------------------------------------------------------------------------
 math-intrinsics  1.1.0   (MIT)
 Author: Jordan Harband <ljharb@gmail.com>
@@ -665,32 +685,6 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-------------------------------------------------------------------------------
-proxy-from-env  1.1.0   (MIT)
-Author: Rob Wu <rob@robwu.nl> (https://robwu.nl/)
-------------------------------------------------------------------------------
-
-The MIT License
-
-Copyright (C) 2016-2018 Rob Wu <rob@robwu.nl>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
-of the Software, and to permit persons to whom the Software is furnished to do
-so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
 ------------------------------------------------------------------------------
 supports-color  10.2.2   (MIT)
 Author: Sindre Sorhus <sindresorhus@gmail.com>

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

@@ -11,8 +11,9 @@ import {
   intentIdOf,
   namespaceOf,
   require_dist2 as require_dist,
-  sameAddress
-} from "./chunk-Z3AUNEU5.js";
+  sameAddress,
+  sameAssetIdentifier
+} from "./chunk-LAWFMGYD.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");
@@ -209,7 +211,7 @@ function registerServer(config) {
       const result = await config.submitter.submit(pr);
       const fc = result.fulfillment_confirmation;
       if (!fc) {
-        const terminal = result.status === "failed" || result.status === "cancelled";
+        const terminal = result.status === "failed";
         if (terminal) {
           throw new SettlementFailedError({ paymentId: result.payment_id, state: result.status });
         }
@@ -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);