@atumlabs/mppx-atum-escrow 0.1.0

package/README.md

@@ -0,0 +1,328 @@
+# @atumlabs/mppx-atum-escrow
+
+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).
+
+- The **payer** funds the payment in any supported source asset and chain (e.g. USDC on Base,
+  USDT on Tron, or USDC on Solana).
+- The **merchant** receives an exact, pinned amount of the asset it chose, on the chain it chose
+  (e.g. USDC on Arbitrum).
+- Atum's escrow, auction, and settlement network bridges the two. Neither side has to hold or
+  move the other's asset.
+
+If you have used MPP with a card or same-chain method before, this is the same integration shape
+— you register a method and MPP does the 402 dance for you — except the money can cross chains.
+
+## What is MPP, in one paragraph
+
+MPP is an "HTTP 402" protocol: a client requests a resource, the server answers `402 Payment
+Required` with a machine-readable description of how to pay, the client pays and retries, and the
+server returns `200` plus a receipt. Unlike some 402 protocols, **MPP has no central "facilitator"
+service** — the logic that validates and settles a payment runs **inside the merchant's own
+process**, as a *payment method* plugged into the `mppx` SDK. This package **is** that method for
+Atum. Its one `verify()` hook both checks the payment and settles it through the Atum Payment
+Gateway.
+
+## How a payment flows
+
+```text
+Payer (client)              Merchant (server)              Atum Payment Gateway
+      |                            |                                |
+      | ─ GET /paid-resource ────> |                                |
+      | <─ 402 + atum-escrow ───── |  (what to pay, where it lands) |
+      |    challenge               |                                |
+      | (registerClient builds &   |                                |
+      |  signs the deposit auth)   |                                |
+      | ─ retry + credential ────> |                                |
+      |                            | (registerServer.verify:        |
+      |                            |  checks signature & terms)     |
+      |                            | ─ submit payment request ────> |
+      |                            | <─ FulfillmentConfirmation ─── |
+      | <─ 200 + resource + ────── |                                |
+      |    receipt                 |                                |
+```
+
+1. The merchant answers a request with a `402` **challenge** describing what it receives
+   (destination asset, chain, exact amount) and the source option a payer may fund from. You build
+   this challenge from a **corridor** with `buildChargeRequest`.
+2. The payer's `registerClient` reads the challenge, builds an Atum payment request, signs the
+   source-chain deposit authorization for that chain, and returns it as an MPP **credential**.
+3. The merchant's `registerServer` **verifies** the credential (recovers the signature, matches
+   every term against the challenge) and **submits** it to the Atum Payment Gateway, blocking until
+   settlement completes. On success it returns a **receipt** carrying the settlement confirmation.
+
+The source-chain authorization is built and signed through the Atum
+[`@atumlabs/payment-gateway-client`](https://www.npmjs.com/package/@atumlabs/payment-gateway-client),
+so **one code path supports EVM, Tron, and Solana sources** — you configure a source
+and the method picks the right signing scheme for its chain.
+
+## Install
+
+```sh
+npm install @atumlabs/mppx-atum-escrow
+```
+
+This package is an `mppx` plugin, so **`mppx` and `zod` are peer dependencies** — it registers into
+*your* `mppx` instance and must share the same `mppx` and `zod` as the rest of your integration.
+Install them if your project doesn't already depend on them:
+
+```sh
+npm install mppx zod
+```
+
+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 |
+| --- | --- |
+| **Corridor** | The merchant's payment configuration: what it receives (destination), and which source chains/tokens it accepts. You define it once. |
+| **Source option** | A source chain (with its escrow and role addresses) and one or more tokens (`assets`) a payer may pay from on it. A corridor may list several; each challenge offers one `(chain, token)`. |
+| **`fulfillmentAmount`** | The exact amount, in the destination token's atomic units, the merchant will receive. USDC/USDT use 6 decimals, so `"10000000"` = 10 USDC. Set per charge. |
+| **Source cap** | The most the payer can spend on the source side: `fulfillmentAmount` + a markup (`markupBps`) to cover the cross-chain spread. The payer signs this cap. |
+| **Escrow** | The source-chain contract the payer's funds lock into until the merchant is paid. |
+| **Deadlines** | Two budgets in seconds: `quoteDeadlineSeconds` (how long the auction runs) and `fulfillmentDeadlineSeconds` (how long settlement may take). Required order: `now < quote < fulfillment`. |
+| **`PaymentSubmitter`** | A small adapter *you* provide that hands a signed payment request to the Atum Payment Gateway and returns the result. |
+| **Receipt** | What `verify()` returns on success: the MPP receipt plus the full settlement confirmation. |
+
+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.
+
+## Quick start — merchant (server)
+
+```ts
+import { Mppx } from "mppx/server";
+import { PaymentGatewayClient } from "@atumlabs/payment-gateway-client";
+import {
+  registerServer,
+  buildChargeRequest,
+  corridorFromDefaults,
+  type AtumEscrowCorridor,
+  type PaymentSubmitter,
+} from "@atumlabs/mppx-atum-escrow/server";
+
+const gateway = new PaymentGatewayClient({ BASE: "https://gateway.example.com" });
+
+// 1. Describe your corridor: you receive 10 USDC on Arbitrum, and accept USDC on Base and
+//    USDT on Tron as sources. `corridorFromDefaults` fills the escrow/role/proxy addresses
+//    from the gateway, so you only specify what you receive, the sources, and your budgets.
+const corridor: AtumEscrowCorridor = await corridorFromDefaults(gateway, {
+  destination: {
+    network: "eip155:42161", // Arbitrum One (CAIP-2)
+    asset: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC on Arbitrum
+    account: "0xYourMerchantReceiveAddress",
+  },
+  sources: [
+    // One entry per source chain; list several tokens in `assets` to accept more than one
+    // on that chain (they share the same escrow/role addresses — no need to duplicate).
+    {
+      network: "eip155:8453", // Base
+      assets: [
+        "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC
+        "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2", // USDT
+      ],
+    },
+    { network: "tron:mainnet", assets: ["TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"] }, // USDT on Tron
+  ],
+  markupBps: 300, // allow up to +3% on the source side to cover the spread
+  quoteDeadlineSeconds: 20,
+  fulfillmentDeadlineSeconds: 300,
+});
+
+// You can also build a corridor by hand if you already hold the addresses — see AtumEscrowCorridor.
+
+// 2. Provide the gateway adapter. The gateway response maps 1:1 onto what the method needs.
+const submitter: PaymentSubmitter = {
+  async submit(request) {
+    const res = await gateway.payments.submitPayment({ requestBody: request });
+    return {
+      payment_id: res.payment_id,
+      fulfillment_confirmation: res.fulfillment_confirmation,
+    };
+  },
+};
+
+// 3. Register the method and create your mppx server. The corridor is NOT part of the server
+//    config — verification trusts the signed challenge, so one registration serves every corridor.
+const method = registerServer({ submitter });
+const mppx = Mppx.create({
+  realm: "api.example.com",
+  secretKey: process.env.MPP_SECRET_KEY, // recommended: binds each challenge to its contents
+  methods: [method],
+});
+
+// 4. Guard a route. buildChargeRequest turns your corridor + a chosen source + the price into
+//    the challenge. Set the price per charge, so one corridor serves any amount.
+app.get("/paid-resource", async (req) => {
+  const request = buildChargeRequest(
+    corridor,
+    { network: "eip155:8453", asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, // offer Base USDC
+    "10000000", // receive exactly 10 USDC
+  );
+  const result = await mppx.compose(["atum-escrow/charge", request])(req);
+  if (result.status === 402) return result.challenge; // not paid yet — ask for payment
+  return result.withReceipt(new Response("here is your resource")); // paid & settled
+});
+```
+
+## Quick start — payer (client)
+
+```ts
+import { Mppx } from "mppx/client";
+import { registerClient } from "@atumlabs/mppx-atum-escrow/client";
+
+// The signer is chain-agnostic: pass private-key options (bound to the challenge's source chain
+// automatically) or a ready-made SenderSigner. `account` is your source-chain address.
+const method = registerClient({
+  signer: { privateKey: process.env.PAYER_PRIVATE_KEY! },
+  account: process.env.PAYER_ADDRESS!,
+});
+const mppx = Mppx.create({ methods: [method] });
+
+// mppx.fetch handles the 402 automatically: it reads the atum-escrow challenge, builds and
+// signs the payment, retries with the credential attached, and returns the final 200 response.
+const res = await mppx.fetch("https://api.example.com/paid-resource");
+const resource = await res.text();
+```
+
+### Approving the source token
+
+On EVM and Tron, the payer must approve the token-transfer contract (Permit2) to move the source
+token before paying, or the escrow deposit reverts at settlement. `ensureSourceApproval` reads the
+current allowance and sends an approval only if it falls short (it is a no-op on Solana, which
+authorizes the transfer in the signed deposit itself):
+
+```ts
+import { Wallet, JsonRpcProvider } from "ethers";
+import { ensureSourceApproval } from "@atumlabs/mppx-atum-escrow/client";
+
+const wallet = new Wallet(process.env.PAYER_PRIVATE_KEY!, new JsonRpcProvider(RPC_URL));
+await ensureSourceApproval({
+  network: "eip155:8453",
+  token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
+  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.
+  requiredAllowance: BigInt(challenge.request.source.amount),
+});
+```
+
+## What the merchant `verify()` guarantees
+
+`verify()` fails fast (no chain I/O) before submitting, and throws if any check fails. The Atum
+Payment Gateway independently re-validates everything on submit; these checks just reject
+obviously-bad input early:
+
+- the source-chain deposit signature **recovers to the payer's own `source.account`** (an EVM/Tron
+  secp256k1 recovery, or a Solana ed25519 verification against the signer's public key);
+- the signed deposit's **token, escrow, and witness roles** match the challenge's source option;
+- `max_source_amount` **does not exceed the source cap**, and the deposit authorizes exactly that;
+- the **destination account, asset, and `fulfillment_amount`** are exactly what the merchant
+  advertised (the deposit signature does not bind the receive side, so the method does);
+- the **settlement-routing fields** — `escrow_contract_address`, `quote_selector`,
+  `fulfillment_proxy`, and `fulfillment_verifier` — match the challenge. These travel in
+  plaintext and aren't covered by the deposit signature, so the method checks them explicitly
+  to stop a payer from redirecting settlement;
+- the deadlines satisfy `now < quote_deadline < fulfillment_deadline`, and do not exceed the
+  challenge's advertised budgets; and (for EVM/Tron) the deposit authorization **does not expire
+  before `fulfillment_deadline`**, so a slow-but-valid settlement never lands on an expired signature.
+
+On success you get an `AtumEscrowReceipt` — the MPP receipt plus the full settlement confirmation:
+
+```ts
+{
+  method: "atum-escrow",
+  status: "success",
+  timestamp: string,               // settlement time (ISO 8601)
+  reference: string,               // destination-chain transaction hash
+  fulfillmentConfirmation: {       // full settlement details
+    payment_id: string,
+    request_id: string,
+    destination_chain_id: string,  // CAIP-2, e.g. "eip155:42161"
+    destination_tx_hash: string,
+    // …
+  }
+}
+```
+
+## Retries and idempotency
+
+Two layers protect a retry, and they protect **different** things:
+
+1. **Build once, resubmit identical bytes — returns the original result.** `mppx.fetch` builds one
+   credential per payment and reuses it across its automatic retries, so the gateway sees identical
+   content, deduplicates, and returns the *original* result (including the receipt). This is the
+   only layer that gives you a graceful retry. Driving the flow manually, do the same — never
+   rebuild for a retry.
+2. **Deterministic nonce — charge-safe, but not retry-graceful.** For EVM and Tron sources the
+   deposit nonce and `request_id` are derived from the challenge id, so even a rebuild for the
+   *same* challenge reuses the same nonce; the escrow consumes a nonce on the first deposit and
+   reverts any second, so **at most one payment ever settles on-chain**. This is only
+   *charge-safety*: a rebuild's deadlines are wall-clock, so its content differs and the gateway
+   does not recognize it as the original — use layer 1 to get the original receipt back. Solana
+   sources use a replay-window nonce and rely on the gateway's content-keyed dedup (the request id,
+   and thus the payment id, are still derived deterministically from the challenge id).
+
+Layer 2 holds only if the challenge id is **stable across retries of one payment intent and unique
+across distinct intents**, and the merchant controls that. With `Mppx.create({ secretKey })` the
+challenge id is an HMAC over the challenge contents — including `opaque` and `expires` — so:
+
+- set **`opaque` to a per-intent identifier** (e.g. your order or invoice id), reused if that same
+  intent is retried; and
+- keep **`expires` stable or absent** per intent — a floating `now() + TTL` changes the id on every
+  `402` and defeats the anchor.
+
+Anchoring on a per-intent `opaque` (rather than the payment *terms*) is deliberate: two legitimate
+identical purchases must get **different** nonces, which distinct order ids provide. Without a
+`secretKey`, or with a per-request-random challenge id, only layer 1 protects you — so build once.
+
+## Scope
+
+This version supports the **`charge`** intent with **EVM, Tron, and Solana** source chains and a
+merchant-configured destination chain, with **synchronous** settlement (the request is held open
+until settlement completes, so your client and server timeouts must exceed the corridor's deadline
+budgets). One source option is offered per challenge; a corridor may list several and offer a
+different one per `402`.
+
+> **Solana deadline constraint:** a Solana deposit authorization expires within the escrow's fixed
+> on-chain replay window (~2 minutes), independent of the corridor budget. So a corridor that
+> includes a Solana source must keep `fulfillmentDeadlineSeconds` within that window —
+> `validateCorridor` (run by `buildChargeRequest`) enforces this and rejects a longer budget. If you
+> need a longer budget for EVM/Tron sources, put the Solana source in its own corridor.
+
+## API
+
+Import everything from the root, or from the role-specific entry points (which expose only what
+each side needs):
+
+- `@atumlabs/mppx-atum-escrow` — everything below
+- `@atumlabs/mppx-atum-escrow/client` — `registerClient`, `ensureSourceApproval` + payer types
+- `@atumlabs/mppx-atum-escrow/server` — `registerServer`, `buildChargeRequest`,
+  `validateCorridor`, `corridorFromDefaults` + merchant types
+
+| Export | Description |
+| --- | --- |
+| `registerClient(config)` | Payer-side method. `config`: `{ signer, account, now?, solanaClockReader? }`. |
+| `registerServer(config)` | Merchant-side method. `config`: `{ submitter, now? }`. |
+| `buildChargeRequest(corridor, select, fulfillmentAmount)` | Builds the `charge` challenge request for one source option, at a per-charge price. Throws if `select` matches no configured source. |
+| `validateCorridor(corridor)` | Validates a corridor's shape and per-source addresses (run automatically by `buildChargeRequest`). |
+| `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). |
+| `atumEscrowChargeMethod` | The base `mppx` method (advanced/custom wiring). |
+| `ChargeRequestSchema`, `CredentialPayloadSchema` | The `zod` wire schemas. |
+| `METHOD_NAME` (`"atum-escrow"`), `INTENT` (`"charge"`) | The method/intent identifiers. |
+
+Key types: `AtumEscrowCorridor`, `AtumEscrowSource`, `SenderSigner`, `SenderSignerOptions`,
+`PaymentSubmitter`, `AtumEscrowClientConfig`, `AtumEscrowServerConfig`, `ChainDefaultsSource`,
+`EnsureApprovalResult`, `AtumEscrowChallenge`, `AtumEscrowCredential`, `AtumEscrowReceipt`,
+`ChargeRequest`, `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.

package/dist/chunk-V2SJ747H.js

@@ -0,0 +1,131 @@
+import { createRequire as __atumCreateRequire } from 'module'; const require = __atumCreateRequire(import.meta.url);
+import {
+  __toESM,
+  assetIdentifier,
+  atumEscrowChargeMethod,
+  chainDefaultsFromExtra,
+  namespaceOf,
+  require_dist,
+  require_dist2
+} from "./chunk-WWSNMK7N.js";
+
+// src/client.ts
+var import_evm_escrow_encoding = __toESM(require_dist(), 1);
+var import_payment_gateway_client = __toESM(require_dist2(), 1);
+import { keccak256, toUtf8Bytes, Contract, MaxUint256 } from "ethers";
+import { Credential, Method } from "mppx";
+function registerClient(config) {
+  const now = config.now ?? (() => Date.now());
+  const gateway = new import_payment_gateway_client.PaymentGatewayClient();
+  return Method.toClient(atumEscrowChargeMethod, {
+    async createCredential({ challenge }) {
+      const { source, extra } = challenge.request;
+      const namespace = namespaceOf(source.network);
+      const account = config.account;
+      const nowMs = now();
+      if (!(extra.quoteDeadlineSeconds > 0 && extra.quoteDeadlineSeconds < extra.fulfillmentDeadlineSeconds)) {
+        throw new Error(
+          `atum-escrow: deadline ordering violated (now < quote_deadline < fulfillment_deadline); quoteDeadlineSeconds=${extra.quoteDeadlineSeconds}, fulfillmentDeadlineSeconds=${extra.fulfillmentDeadlineSeconds}`
+        );
+      }
+      const anchorAccount = namespace === "eip155" ? account.toLowerCase() : account;
+      const idempotencyAnchor = keccak256(
+        toUtf8Bytes(`atum-escrow:${challenge.id}:${anchorAccount}`)
+      );
+      const requestId = `req_mpp_${idempotencyAnchor.slice(2, 26)}`;
+      const sourceDefaults = chainDefaultsFromExtra(extra, source.network);
+      const sourceAssetId = assetIdentifier(source.network, source.asset);
+      const isSolana = namespace === "solana";
+      const paymentRequestGw = await gateway.preparePaymentRequest({
+        depositor: account,
+        fulfillmentAmount: extra.fulfillmentAmount,
+        sourceAsset: sourceAssetId,
+        destinationAccount: extra.destination.account,
+        destinationAsset: assetIdentifier(extra.destination.network, extra.destination.asset),
+        // Sign the full advertised cap. The payer MAY sign a lower value, but that only
+        // lowers its own escrow lock and risks the auction not clearing; the full cap is
+        // the safe default and never affects the receive side.
+        maxSourceAmount: source.amount,
+        requestId,
+        quoteDeadlineSeconds: extra.quoteDeadlineSeconds,
+        fulfillmentDeadlineSeconds: extra.fulfillmentDeadlineSeconds,
+        now: () => nowMs,
+        resolvedDefaults: {
+          source: sourceDefaults,
+          destination: { fulfillmentProxy: extra.fulfillmentProxy }
+        },
+        // EVM/Tron: thread the deterministic nonce, and keep the deposit deadline at least
+        // as late as the fulfillment deadline. The adapter floors the relative deadline, so
+        // +1s guards against truncating below fulfillment_deadline.
+        ...isSolana ? {
+          // Solana stamps issued_at from the (injectable) clock and derives its own
+          // replay-window deadline; the offline build reads the client clock.
+          solanaRpcUrl: "atum-escrow:offline",
+          solanaClockReader: config.solanaClockReader ?? (async () => BigInt(Math.floor(nowMs / 1e3)))
+        } : {
+          nonce: BigInt(idempotencyAnchor),
+          // Keep the deposit deadline at least as late as fulfillment. The adapter
+          // floors its relative deadline, so round the budget up and add a second to
+          // guard against truncating below fulfillment_deadline (and to keep an
+          // integer, since the adapter derives a bigint from it).
+          deadlineSeconds: Math.ceil(extra.fulfillmentDeadlineSeconds) + 1
+        }
+      });
+      const signer = buildSenderSigner(source.network, config.signer, account);
+      await (0, import_payment_gateway_client.signPaymentRequest)(paymentRequestGw, signer);
+      const paymentRequest = paymentRequestGw;
+      return Credential.serialize({
+        challenge,
+        payload: { paymentRequest },
+        source: `did:pkh:${source.network}:${anchorAccount}`
+      });
+    }
+  });
+}
+function isSenderSigner(signer) {
+  return typeof signer.sign === "function";
+}
+function buildSenderSigner(network, signer, account) {
+  if (isSenderSigner(signer)) {
+    return signer;
+  }
+  if (signer.provider === "turnkey") {
+    throw new Error(
+      "atum-escrow: construct a Turnkey SenderSigner with the payment-gateway client and pass it as `signer`"
+    );
+  }
+  return (0, import_payment_gateway_client.createSenderSigner)(network, {
+    provider: "raw",
+    privateKey: signer.privateKey,
+    pinnedAddress: signer.pinnedAddress ?? account
+  });
+}
+var ERC20_ALLOWANCE_ABI = [
+  "function allowance(address owner, address spender) view returns (uint256)",
+  "function approve(address spender, uint256 amount) returns (bool)"
+];
+async function ensureSourceApproval(params) {
+  if (namespaceOf(params.network) === "solana") {
+    return { alreadySufficient: true };
+  }
+  const spender = params.spender ?? (namespaceOf(params.network) === "eip155" ? import_evm_escrow_encoding.PERMIT2_CONTRACT_ADDRESS : void 0);
+  if (!spender) {
+    throw new Error(
+      `atum-escrow: a spender (Permit2 address) is required to approve on ${params.network}`
+    );
+  }
+  const erc20 = new Contract(params.token, ERC20_ALLOWANCE_ABI, params.signer);
+  const current = await erc20.allowance(params.owner, spender);
+  const sufficient = params.requiredAllowance !== void 0 ? current >= params.requiredAllowance : current >= MaxUint256;
+  if (sufficient) {
+    return { alreadySufficient: true };
+  }
+  const tx = await erc20.approve(spender, MaxUint256);
+  await tx.wait?.();
+  return { alreadySufficient: false, txHash: tx.hash };
+}
+
+export {
+  registerClient,
+  ensureSourceApproval
+};