@integraledger/lcp-binding-evm-escrow 0.9.0

package/src/adapter.ts

@@ -0,0 +1,255 @@
+/**
+ * The Commerce Payments escrow WeldAdapter: the atrHash rides `PaymentInfo.salt`
+ * (`salt = uint256(atrHash)`), proven on-chain. `recover`/`enumerate`
+ * decode the cleartext `PaymentInfo` in `PaymentAuthorized`/`PaymentCharged` event data (the WLD-3
+ * event-data scan — `paymentInfoHash` is the indexed topic, `salt` is not). viem lives here.
+ */
+import type {
+  LifecycleTransition,
+  Outcome,
+  SettlementRef,
+  VerifierPorts,
+  WeldAdapter,
+} from "@integraledger/lcp-binding-core";
+import { refOf } from "@integraledger/lcp-binding-evm-common";
+import { type Abi, decodeEventLog, type Log, parseAbi } from "viem";
+import { AUTH_CAPTURE_ESCROW } from "./collectors.js";
+import { type EscrowEventName, EVENT_TO_STATE } from "./lifecycle.js";
+import { ESCROW_MANIFEST } from "./manifest.js";
+
+const PI_TUPLE =
+  "(address operator, address payer, address receiver, address token, uint120 maxAmount, uint48 preApprovalExpiry, uint48 authorizationExpiry, uint48 refundExpiry, uint16 minFeeBps, uint16 maxFeeBps, address feeReceiver, uint256 salt)";
+
+/** The six escrow lifecycle events. `PaymentAuthorized`/`PaymentCharged` carry the cleartext `PaymentInfo`
+ *  (→ salt → atrHash); the rest join on the indexed `paymentInfoHash`. */
+export const ESCROW_EVENTS_ABI: Abi = parseAbi([
+  `event PaymentAuthorized(bytes32 indexed paymentInfoHash, ${PI_TUPLE} paymentInfo, uint256 amount, address tokenCollector)`,
+  `event PaymentCharged(bytes32 indexed paymentInfoHash, ${PI_TUPLE} paymentInfo, uint256 amount, address tokenCollector, uint16 feeBps, address feeReceiver)`,
+  "event PaymentCaptured(bytes32 indexed paymentInfoHash, uint256 amount, uint16 feeBps, address feeReceiver)",
+  "event PaymentVoided(bytes32 indexed paymentInfoHash, uint256 amount)",
+  "event PaymentReclaimed(bytes32 indexed paymentInfoHash, uint256 amount)",
+  "event PaymentRefunded(bytes32 indexed paymentInfoHash, uint256 amount, address tokenCollector)",
+]);
+
+/** `AuthCaptureEscrow.PaymentInfo` — the pre-settlement artifact. `salt` carries the atrHash. */
+export interface PaymentInfo {
+  operator: `0x${string}`;
+  payer: `0x${string}`;
+  receiver: `0x${string}`;
+  token: `0x${string}`;
+  maxAmount: bigint;
+  preApprovalExpiry: number;
+  authorizationExpiry: number;
+  refundExpiry: number;
+  minFeeBps: number;
+  maxFeeBps: number;
+  feeReceiver: `0x${string}`;
+  salt: bigint;
+}
+
+/** `salt = uint256(atrHash)` — the 32-byte atrHash reinterpreted as a uint256. */
+export function saltFromAtrHash(atrHash: `0x${string}`): bigint {
+  return BigInt(atrHash);
+}
+/** Recover the atrHash from a `PaymentInfo.salt` — the reverse (lowercase 0x, 32 bytes). */
+export function atrHashFromSalt(salt: bigint): `0x${string}` {
+  return `0x${salt.toString(16).padStart(64, "0")}`;
+}
+
+/** The per-payment proposal inputs (everything but `salt`, which the adapter fills from the atrHash). */
+export type EscrowProposalContext = Omit<PaymentInfo, "salt">;
+/** What `propose` returns: the `PaymentInfo` to submit, with `salt` already set from the atrHash. A
+ *  single-field object rather than a bare `PaymentInfo` so the return can gain siblings without breaking
+ *  callers. This package proposes and reads — it never operates the escrow. */
+export interface EscrowProposal {
+  paymentInfo: PaymentInfo;
+}
+
+/** How to point the adapter at a deployment. `chainId` is required; the other two default — `escrow` to
+ *  the canonical deterministic `AuthCaptureEscrow`, `fromBlock` to the full history. Widen `fromBlock`
+ *  knowingly: enumeration from `earliest` is a full-history scan on a busy chain. */
+export interface EscrowAdapterConfig {
+  chainId: number;
+  /** The `AuthCaptureEscrow` address; defaults to the canonical deterministic deployment. */
+  escrow?: `0x${string}`;
+  /** Enumeration lower bound; defaults to the full history (`earliest`). */
+  fromBlock?: bigint;
+}
+
+/**
+ * One decoded escrow lifecycle event, INCLUDING the asset the payment moved.
+ *
+ * The asset fields are carried rather than dropped, and that is what makes `assetBinding: "carried"` a
+ * true claim: the axis asks whether a CONSUMER can reach the asset the weld is attached to, not merely
+ * whether the chain recorded it. Decoding `salt` and `amount` while discarding the rest of `PaymentInfo`
+ * would leave the manifest declaring an asset binding nobody could check.
+ */
+export interface DecodedEscrowLog {
+  name: EscrowEventName;
+  /** The atrHash weld, as the raw `PaymentInfo.salt` uint256. Absent on events carrying no `PaymentInfo`. */
+  salt?: bigint;
+  amount: bigint;
+  /** ERC-20 the payment moved. Absent on events carrying no `PaymentInfo`. */
+  token?: `0x${string}`;
+  /** The paying account. Absent on events carrying no `PaymentInfo`. */
+  payer?: `0x${string}`;
+  /** The receiving account. Absent on events carrying no `PaymentInfo`. */
+  receiver?: `0x${string}`;
+  logIndex: number | null;
+  txHash: `0x${string}` | null;
+}
+
+/**
+ * Decode every escrow lifecycle event in a log set (ignoring anything that is not one).
+ *
+ * Exported because it is the only way a consumer reaches the asset behind the weld: `observe` returns
+ * `LifecycleTransition[]`, a shape fixed by `binding-core` that has no room for `token`/`payer`/`receiver`.
+ * A caller checking that a settlement moved the asset its record names calls this directly.
+ */
+export function decodeEscrowLogs(
+  logs: readonly Log[],
+  escrow: string,
+): DecodedEscrowLog[] {
+  const want = escrow.toLowerCase();
+  const out: DecodedEscrowLog[] = [];
+  for (const log of logs) {
+    if (log.address.toLowerCase() !== want) continue;
+    try {
+      const decoded = decodeEventLog({
+        abi: ESCROW_EVENTS_ABI,
+        data: log.data,
+        topics: log.topics,
+      });
+      const args = decoded.args as unknown as {
+        paymentInfo?: {
+          salt: bigint;
+          token: `0x${string}`;
+          payer: `0x${string}`;
+          receiver: `0x${string}`;
+        };
+        amount: bigint;
+      };
+      out.push({
+        name: decoded.eventName as unknown as EscrowEventName,
+        ...(args.paymentInfo !== undefined
+          ? {
+              salt: args.paymentInfo.salt,
+              token: args.paymentInfo.token,
+              payer: args.paymentInfo.payer,
+              receiver: args.paymentInfo.receiver,
+            }
+          : {}),
+        amount: args.amount,
+        logIndex: log.logIndex,
+        txHash: log.transactionHash,
+      });
+    } catch {
+      // not an escrow lifecycle event — ignore
+    }
+  }
+  return out;
+}
+
+/** Construct the escrow WeldAdapter for one chain. */
+export function createEscrowAdapter(config: EscrowAdapterConfig): WeldAdapter {
+  const escrow = config.escrow ?? AUTH_CAPTURE_ESCROW;
+  return {
+    manifest: ESCROW_MANIFEST,
+
+    async propose(
+      atrHash: `0x${string}`,
+      ctx: unknown,
+    ): Promise<Outcome<EscrowProposal>> {
+      const c = ctx as EscrowProposalContext;
+      // The salt is filled from the atrHash — never re-derived. No value-level Refusal
+      // on this path; a malformed atrHash is a programming error surfaced by BigInt() (fail-fast).
+      const paymentInfo: PaymentInfo = { ...c, salt: saltFromAtrHash(atrHash) };
+      return { ok: true, value: { paymentInfo } };
+    },
+
+    async recover(
+      ref: SettlementRef,
+      ports: VerifierPorts,
+    ): Promise<Outcome<`0x${string}`>> {
+      const logs = (await ports.chain.getTransactionLogs(ref)) as Log[];
+      // Only PaymentAuthorized/PaymentCharged carry the cleartext PaymentInfo (→ salt → atrHash).
+      const salted = decodeEscrowLogs(logs, escrow).filter(
+        (e): e is typeof e & { salt: bigint } => e.salt !== undefined,
+      );
+      if (salted.length === 0)
+        return {
+          refused: true,
+          haltClass: "verification-failure",
+          code: "escrow/no-recoverable-event",
+          detail: `no PaymentAuthorized/PaymentCharged with a cleartext PaymentInfo in this settlement`,
+        };
+      // Disambiguate by logIndex when the ref pins one — and a pinned index matching NO salt-bearing event
+      // is a failure, never a fall-through to the first. One escrow transaction can authorize or charge
+      // several independent payments, each with its own salt.
+      if (ref.logIndex !== undefined) {
+        const match = salted.find((e) => e.logIndex === ref.logIndex);
+        if (match === undefined)
+          return {
+            refused: true,
+            haltClass: "verification-failure",
+            code: "escrow/log-index-not-found",
+            detail: `no salt-bearing escrow event at logIndex ${ref.logIndex} in settlement ${ref.txHash}`,
+          };
+        return { ok: true, value: atrHashFromSalt(match.salt) };
+      }
+      // Unpinned. This used to take the FIRST salt-bearing event, which silently answered one payment's
+      // atrHash for a transaction that welded several — the same first-wins defect x402's `recover` carried,
+      // and the one tempo-mpp refuses by name. Distinctness is the test: the same payment observed through
+      // both PaymentAuthorized and PaymentCharged carries one salt and is not ambiguous.
+      const distinct = new Set(salted.map((e) => e.salt));
+      if (distinct.size > 1)
+        return {
+          refused: true,
+          haltClass: "verification-failure",
+          code: "escrow/ambiguous-settlement",
+          detail: `settlement ${ref.txHash} carries ${distinct.size} payments with different salts — pin one with ref.logIndex rather than choosing for the caller`,
+        };
+      return {
+        ok: true,
+        value: atrHashFromSalt((salted[0] as (typeof salted)[number]).salt),
+      };
+    },
+
+    async observe(
+      ref: SettlementRef,
+      ports: VerifierPorts,
+    ): Promise<Outcome<LifecycleTransition[]>> {
+      const logs = (await ports.chain.getTransactionLogs(ref)) as Log[];
+      const events = decodeEscrowLogs(logs, escrow);
+      if (events.length === 0) return { ok: true, value: [] };
+      const at = await ports.chain.blockTime(ref);
+      return {
+        ok: true,
+        value: events.map((e) => ({
+          state: EVENT_TO_STATE[e.name],
+          at,
+          ref: refOf(ref.chainId, ref.txHash, e.logIndex),
+        })),
+      };
+    },
+
+    async enumerate(
+      atrHash: `0x${string}`,
+      ports: VerifierPorts,
+    ): Promise<SettlementRef[]> {
+      // Event-data scan (salt is NOT an indexed topic): fetch the salt-bearing events over the range and
+      // filter by decoded salt == uint256(atrHash). paymentInfoHash is the only indexed key, so there is
+      // no topic filter for salt — this is the manifest's declared "event-data-scan:paymentInfoHash".
+      const want = saltFromAtrHash(atrHash);
+      const logs = (await ports.chain.getLogs({
+        address: escrow,
+        events: [ESCROW_EVENTS_ABI[0], ESCROW_EVENTS_ABI[1]], // PaymentAuthorized, PaymentCharged
+        fromBlock: config.fromBlock ?? "earliest",
+        toBlock: "latest",
+      })) as Log[];
+      return decodeEscrowLogs(logs, escrow)
+        .filter((e) => e.salt === want)
+        .map((e) => refOf(config.chainId, e.txHash ?? undefined, e.logIndex));
+    },
+  };
+}

package/src/calls.ts

@@ -0,0 +1,99 @@
+/**
+ * The escrow KEY derivations — the off-chain `getHash` (== the event's indexed `paymentInfoHash`) and
+ * the payer-agnostic nonce, so a settlement can be keyed and joined without importing viem
+ * downstream — viem stays here. There are no calldata encoders in this module and none anywhere in
+ * this package: escrow is not our product, so this binding reads the mechanism and never drives it.
+ * (This module has no calldata encoders: they were removed
+ * with the escrow-operation retirement and the headline was not.) `encodeAbiParameters` below is
+ * hashing input, not transaction input.
+ *
+ * Every struct field and signature is transcribed from the DEPLOYED `AuthCaptureEscrow` at
+ * base/commerce-payments @ 98b592b (the pinned deployment, NOT repo HEAD — the charge/capture event ABI
+ * drift that shipped a bug earlier came from reading HEAD).
+ *
+ * `getHashOffchain` replicates the on-chain `getHash` byte-identically, so the settlement key is
+ * derivable BEFORE the authorizing tx confirms rather than only from the event. Call it with the real
+ * `payer` for the settlement key; call it with `payer = 0` for the ERC-3009 `ReceiveWithAuthorization`
+ * nonce the buyer signs (the "payer-agnostic" nonce).
+ */
+import { encodeAbiParameters, keccak256, stringToHex } from "viem";
+import type { PaymentInfo } from "./adapter.js";
+import { AUTH_CAPTURE_ESCROW } from "./collectors.js";
+
+/** The PaymentInfo tuple components, in the DEPLOYED struct's field order (98b592b). */
+const PI_COMPONENTS = {
+  type: "tuple",
+  components: [
+    { name: "operator", type: "address" },
+    { name: "payer", type: "address" },
+    { name: "receiver", type: "address" },
+    { name: "token", type: "address" },
+    { name: "maxAmount", type: "uint120" },
+    { name: "preApprovalExpiry", type: "uint48" },
+    { name: "authorizationExpiry", type: "uint48" },
+    { name: "refundExpiry", type: "uint48" },
+    { name: "minFeeBps", type: "uint16" },
+    { name: "maxFeeBps", type: "uint16" },
+    { name: "feeReceiver", type: "address" },
+    { name: "salt", type: "uint256" },
+  ],
+} as const;
+
+/** keccak256 of the PaymentInfo typehash STRING (== the deployed PAYMENT_INFO_TYPEHASH, 0xae68…6591). */
+export const PAYMENT_INFO_TYPEHASH: `0x${string}` = keccak256(
+  stringToHex(
+    "PaymentInfo(address operator,address payer,address receiver,address token,uint120 maxAmount,uint48 preApprovalExpiry,uint48 authorizationExpiry,uint48 refundExpiry,uint16 minFeeBps,uint16 maxFeeBps,address feeReceiver,uint256 salt)",
+  ),
+);
+
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000" as const;
+
+/**
+ * The off-chain `getHash(paymentInfo)` — `keccak256(abi.encode(chainId, escrow, keccak256(abi.encode(
+ * TYPEHASH, paymentInfo))))`. Equals the event's indexed `paymentInfoHash` (the deployed `authorize`/
+ * `charge` emit `getHash(paymentInfo)` as that topic) and the settlement key. This matches
+ * the on-chain view byte-for-byte (incl. the fee-bearing case).
+ */
+export function getHashOffchain(params: {
+  chainId: number;
+  escrow?: `0x${string}`;
+  paymentInfo: PaymentInfo;
+}): `0x${string}` {
+  const escrow = params.escrow ?? AUTH_CAPTURE_ESCROW;
+  const inner = keccak256(
+    encodeAbiParameters(
+      [{ type: "bytes32" }, PI_COMPONENTS],
+      [PAYMENT_INFO_TYPEHASH, params.paymentInfo],
+    ),
+  );
+  return keccak256(
+    encodeAbiParameters(
+      [{ type: "uint256" }, { type: "address" }, { type: "bytes32" }],
+      [BigInt(params.chainId), escrow, inner],
+    ),
+  );
+}
+
+/** The settlement key / event `paymentInfoHash` for a PaymentInfo (alias of `getHashOffchain`). */
+export function paymentInfoHash(params: {
+  chainId: number;
+  escrow?: `0x${string}`;
+  paymentInfo: PaymentInfo;
+}): `0x${string}` {
+  return getHashOffchain(params);
+}
+
+/**
+ * The ERC-3009 `ReceiveWithAuthorization` nonce the buyer signs — `getHash(paymentInfo with payer = 0)`
+ * (the "payer-agnostic" hash; the collector fills the real payer from the recovered signature).
+ */
+export function payerAgnosticNonce(params: {
+  chainId: number;
+  escrow?: `0x${string}`;
+  paymentInfo: PaymentInfo;
+}): `0x${string}` {
+  return getHashOffchain({
+    ...params,
+    paymentInfo: { ...params.paymentInfo, payer: ZERO_ADDRESS },
+  });
+}

package/src/collectors.ts

@@ -0,0 +1,96 @@
+/**
+ * The Commerce Payments token collectors — the modular payer-authorization methods `authorize`/`charge`
+ * pull funds through. Addresses are the deterministic base/commerce-payments deployments (identical on
+ * Base Mainnet and Base Sepolia). Each carries its **weld grade** (per the manifest) and whether that
+ * grade is **on-chain-proven** vs characterized-from-source.
+ *
+ * The ERC3009 collector's `collectorData` IS the payer's signature (the collector runs it through
+ * `_handleERC6492Signature`, so a smart-wallet ERC-6492 sig works too) over the USDC
+ * `ReceiveWithAuthorization` with `to = <the collector>`, `value = maxAmount`, `nonce =
+ * getHash(paymentInfo with payer = 0)`. The signing itself is the money-path runtime's job
+ * this package declares the collectors, their grades, and the policy.
+ */
+import type { Refusal, WeldGrade } from "@integraledger/lcp-binding-core";
+
+/** The four Commerce Payments collectors — the payer-authorization methods funds are pulled through.
+ *  Naming one is not the same as being able to USE it here: the shipped policy accepts only collectors
+ *  whose weld grade is on-chain-proven, and today that is `ERC3009` alone. */
+export type CollectorName =
+  | "ERC3009"
+  | "Permit2"
+  | "SpendPermission"
+  | "PreApproval";
+
+/** One collector's declaration: where it is deployed, what weld grade it earns, and — separately —
+ *  whether that grade has been PROVEN by an on-chain run rather than read off the pinned source.
+ *  `proven: false` is not a doubt about the code; it records that nobody has watched it happen. */
+export interface EscrowCollector {
+  name: CollectorName;
+  address: `0x${string}`;
+  grade: WeldGrade;
+  /** True iff the grade is proven by an on-chain run (not merely read from the pinned source). */
+  proven: boolean;
+}
+
+/** The base/commerce-payments collector deployments (Base Mainnet == Base Sepolia, deterministic). */
+export const COLLECTORS: Record<CollectorName, EscrowCollector> = {
+  ERC3009: {
+    name: "ERC3009",
+    address: "0x0E3dF9510de65469C4518D7843919c0b8C7A7757",
+    grade: "signature",
+    proven: true,
+  },
+  Permit2: {
+    name: "Permit2",
+    address: "0x992476B9Ee81d52a5BdA0622C333938D0Af0aB26",
+    grade: "signature",
+    proven: false,
+  },
+  SpendPermission: {
+    name: "SpendPermission",
+    address: "0x8d9F34934dc9619e5DC3Df27D0A40b4A744E7eAa",
+    grade: "signature",
+    proven: false,
+  },
+  PreApproval: {
+    name: "PreApproval",
+    address: "0x1b77ABd71FCD21fbe2398AE821Aa27D1E6B94bC6",
+    grade: "tx",
+    proven: false,
+  },
+};
+
+/** The `AuthCaptureEscrow` (Base Mainnet == Base Sepolia). */
+export const AUTH_CAPTURE_ESCROW =
+  "0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff" as const;
+
+/** The declaration for one collector. Total over the union, so it cannot fail — the acceptability check
+ *  is a separate call, and reaching a collector here is not permission to use it. */
+export function getCollector(name: CollectorName): EscrowCollector {
+  return COLLECTORS[name];
+}
+
+/**
+ * Enforce a **signature-grade, on-chain-proven** collector policy (fail-fast, no silent tx-grade
+ * fallback): refuse a `tx`-grade collector where signature-grade is required, and refuse a collector
+ * whose grade is not yet on-chain-proven (only ERC3009 is). Returns a `policy-rejection` Refusal
+ * or `null` when the collector is acceptable.
+ */
+export function assertSignatureGrade(name: CollectorName): Refusal | null {
+  const c = COLLECTORS[name];
+  if (c.grade !== "signature")
+    return {
+      refused: true,
+      haltClass: "policy-rejection",
+      code: "escrow/tx-grade-collector",
+      detail: `collector ${name} is ${c.grade}-grade; a signature-grade weld is required (no silent tx-grade fallback)`,
+    };
+  if (!c.proven)
+    return {
+      refused: true,
+      haltClass: "policy-rejection",
+      code: "escrow/unproven-collector",
+      detail: `collector ${name}'s grade is characterized-from-source but not on-chain-proven — prove it on-chain before use`,
+    };
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+export {
+  atrHashFromSalt,
+  createEscrowAdapter,
+  type DecodedEscrowLog,
+  decodeEscrowLogs,
+  ESCROW_EVENTS_ABI,
+  type EscrowAdapterConfig,
+  type EscrowProposal,
+  type EscrowProposalContext,
+  type PaymentInfo,
+  saltFromAtrHash,
+} from "./adapter.js";
+export {
+  getHashOffchain,
+  PAYMENT_INFO_TYPEHASH,
+  payerAgnosticNonce,
+  paymentInfoHash,
+} from "./calls.js";
+export {
+  AUTH_CAPTURE_ESCROW,
+  assertSignatureGrade,
+  COLLECTORS,
+  type CollectorName,
+  type EscrowCollector,
+  getCollector,
+} from "./collectors.js";
+export {
+  type EscrowEventName,
+  type EscrowState,
+  EVENT_TO_STATE,
+  stateFor,
+} from "./lifecycle.js";
+export { ESCROW_MANIFEST } from "./manifest.js";

package/src/lifecycle.ts

@@ -0,0 +1,53 @@
+/**
+ * The escrow lifecycle as a discriminated union — illegal states are not constructible. The
+ * `charged` state is terminal for COLLECTION (the one-step charge path — no authorize/capture follows),
+ * but `refunded` stays reachable within `refundExpiry`, which is exactly the manifest's
+ * `finality: { reversible: true }`: an on-rail refund, not a capture reversal — the two answer different
+ * questions and both hold. Transitions join on the indexed `paymentInfoHash`.
+ */
+export type EscrowState =
+  | { s: "proposed" }
+  | { s: "authorized"; amount: bigint }
+  | { s: "captured"; amount: bigint }
+  | { s: "charged"; amount: bigint }
+  | { s: "voided" }
+  | { s: "reclaimed" }
+  | { s: "refunded"; amount: bigint };
+
+/** The six on-chain escrow events (`AuthCaptureEscrow`) that drive lifecycle transitions. */
+export type EscrowEventName =
+  | "PaymentAuthorized"
+  | "PaymentCaptured"
+  | "PaymentCharged"
+  | "PaymentVoided"
+  | "PaymentReclaimed"
+  | "PaymentRefunded";
+
+/** The lifecycle state name each event lands in (the manifest's `lifecycleStates`, minus the off-chain
+ *  `proposed`). Used to label `observe`'s transitions. */
+export const EVENT_TO_STATE: Record<EscrowEventName, EscrowState["s"]> = {
+  PaymentAuthorized: "authorized",
+  PaymentCaptured: "captured",
+  PaymentCharged: "charged",
+  PaymentVoided: "voided",
+  PaymentReclaimed: "reclaimed",
+  PaymentRefunded: "refunded",
+};
+
+/** Build the discriminated `EscrowState` for an event + its amount (amount ignored for void/reclaim). */
+export function stateFor(event: EscrowEventName, amount: bigint): EscrowState {
+  switch (event) {
+    case "PaymentAuthorized":
+      return { s: "authorized", amount };
+    case "PaymentCaptured":
+      return { s: "captured", amount };
+    case "PaymentCharged":
+      return { s: "charged", amount };
+    case "PaymentVoided":
+      return { s: "voided" };
+    case "PaymentReclaimed":
+      return { s: "reclaimed" };
+    case "PaymentRefunded":
+      return { s: "refunded", amount };
+  }
+}

package/src/manifest.ts

@@ -0,0 +1,83 @@
+import type { BindingManifest } from "@integraledger/lcp-binding-core";
+
+/**
+ * The Commerce Payments escrow binding manifest (`AuthCaptureEscrow`, authorize→capture).
+ *
+ * **pattern = "native-field"** — the atrHash rides `PaymentInfo.salt`, an EXISTING protocol field the
+ * service already controls (LCP §8.3.1); no derivation, no overlay. **WLD-3 recovery is an event-data scan,
+ * not a topic filter:** the indexed topic is `paymentInfoHash`; `salt` rides the cleartext `PaymentInfo`
+ * in `PaymentAuthorized`/`PaymentCharged` event data, so `recover`/`enumerate` decode the event and read
+ * `salt` (proven on-chain).
+ *
+ * **recovery.forwardIndexable = false** — the criterion is enumeration bound to a GIVEN atrHash, and this
+ * rail cannot do it. `paymentInfoHash` is the only indexed topic, and it is a hash of the whole
+ * `PaymentInfo` struct: a caller holding the complete struct could topic-filter, but a caller holding only
+ * an atrHash cannot derive it. So `enumerate` fetches the salt-bearing events over a range and filters
+ * client-side on the decoded `salt` — an O(range) scan, which is exactly what `indexing:
+ * "event-data-scan:paymentInfoHash"` says and what `adapter.ts` does. Six siblings declare `false` for
+ * mechanically equivalent scans; the three that declare `true` (cardano, tempo-mpp, evm-x402) each rest on
+ * a real index keyed on the atrHash itself.
+ *
+ * **weldGrades are TRANSCRIBED from an on-chain proof, never authored here**: `ERC3009 =
+ * "signature"` is **proven on-chain** (the payer's USDC `ReceiveWithAuthorization` drives
+ * `authorize`); `Permit2`/`SpendPermission` = `"signature"` and `PreApproval` = `"tx"` are
+ * **characterized from the pinned source** (`collectors/*.sol`) and NOT yet on-chain-proven — an adapter
+ * refuses a collector until its grade is proven the same way (`collectors.ts`). If a run ever falsifies a
+ * collector, this manifest changes with it — the on-chain proof stays the authority on what may be declared.
+ *
+ * **THE atrHash MUST BE PER-TRANSACTION, AND THIS IS THE FIRST PLACE IT IS WRITTEN DOWN.** The carrier is
+ * `PaymentInfo.salt`, whose own specification calls it "a source of entropy to ensure unique hashes across
+ * different payments". An atrHash carries no entropy: it is deterministic, server-side, and identical for
+ * every payment made under one terms document. The consequence is on-chain and immediate — the escrow
+ * rejects a `PaymentInfo` it has already seen, so a repeat purchase under one ATR with the same payer,
+ * caps and expiries reverts. Nothing in this package can detect that, because the collision is between two
+ * transactions it never sees together; a deployment reusing one ATR across purchases is the failure mode,
+ * and the fix is a per-transaction ATR, which LCP §6.1 wants anyway.
+ *
+ * **NO `protocol`, and the silence is now examined rather than default.** x402 publishes an `auth-capture`
+ * scheme over this SAME contract stack (`base/commerce-payments`, `AuthCaptureEscrow`), read 2026-08-08 —
+ * but x402 building on a contract this binding also builds on does not make this binding x402's. There is
+ * no `extra` block here, no facilitator, no payload envelope: this package constructs `PaymentInfo`
+ * directly and settles against the contract. Declaring `protocol: "x402"` would claim conformance to a
+ * wire format it does not implement.
+ *
+ * The scheme is still worth reading, because it sharpens the salt requirement above. Under x402
+ * auth-capture the signature nonce is the **payer-agnostic** `PaymentInfo` hash — "Payer is zeroed" — and
+ * freshness rests entirely on the salt: "each signing call generates a fresh `bytes32` salt, so two payers
+ * signing concurrently produce distinct nonces with no collision risk." A deterministic salt removes the
+ * only thing keeping two DIFFERENT payers apart there. So a deployment that settles through an x402
+ * auth-capture facilitator must not weld this way at all, where a bare deployment only has to keep the ATR
+ * per-transaction.
+ */
+export const ESCROW_MANIFEST: BindingManifest = {
+  rail: "evm:escrow",
+  pattern: "native-field",
+  nativeField: "PaymentInfo.salt",
+  recovery: {
+    onChain: true,
+    zeroPartyRecoverable: true,
+    forwardIndexable: false,
+  },
+  assetBinding: "carried", // PaymentInfo.token rides the cleartext event data — the record itself names the asset
+  successGate: "structural", // a reverted tx emits no logs, so the escrow weld event cannot exist
+  indexing: "event-data-scan:paymentInfoHash",
+  finality: {
+    reversible: true,
+    note: 'on-rail void/refund within refundExpiry — not dispute resolution (RCS-5); capture is not reversed, refund is a fresh on-rail remedy The atrHash welded into PaymentInfo.salt MUST be per-transaction: salt is specified as the struct\'s entropy source ("a source of entropy to ensure unique hashes across different payments") and an atrHash carries none, so a repeat purchase under one ATR with the same payer, caps and expiries produces a PaymentInfo the escrow has already seen and reverts.',
+  },
+  weldGrades: {
+    ERC3009: "signature",
+    Permit2: "signature",
+    SpendPermission: "signature",
+    PreApproval: "tx",
+  },
+  lifecycleStates: [
+    "proposed",
+    "authorized",
+    "captured",
+    "charged",
+    "voided",
+    "reclaimed",
+    "refunded",
+  ],
+};