@integraledger/lcp-binding-evm-escrow 0.9.0

package/dist/calls.js

@@ -0,0 +1,67 @@
+/**
+ * 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 { 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" },
+    ],
+};
+/** keccak256 of the PaymentInfo typehash STRING (== the deployed PAYMENT_INFO_TYPEHASH, 0xae68…6591). */
+export const PAYMENT_INFO_TYPEHASH = 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";
+/**
+ * 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) {
+    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) {
+    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) {
+    return getHashOffchain({
+        ...params,
+        paymentInfo: { ...params.paymentInfo, payer: ZERO_ADDRESS },
+    });
+}
+//# sourceMappingURL=calls.js.map

package/dist/calls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calls.js","sourceRoot":"","sources":["../src/calls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,MAAM,CAAC;AAEnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,wFAAwF;AACxF,MAAM,aAAa,GAAG;IACpB,IAAI,EAAE,OAAO;IACb,UAAU,EAAE;QACV,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;QACrC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;QAClC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;QACrC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;QAClC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE;QACtC,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC7C,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC/C,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAE;QACxC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE;QACrC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE;QACrC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE;QACxC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE;KAClC;CACO,CAAC;AAEX,yGAAyG;AACzG,MAAM,CAAC,MAAM,qBAAqB,GAAkB,SAAS,CAC3D,WAAW,CACT,yOAAyO,CAC1O,CACF,CAAC;AAEF,MAAM,YAAY,GAAG,4CAAqD,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,MAI/B;IACC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,mBAAmB,CAAC;IACpD,MAAM,KAAK,GAAG,SAAS,CACrB,mBAAmB,CACjB,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,aAAa,CAAC,EACpC,CAAC,qBAAqB,EAAE,MAAM,CAAC,WAAW,CAAC,CAC5C,CACF,CAAC;IACF,OAAO,SAAS,CACd,mBAAmB,CACjB,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAC/D,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CACxC,CACF,CAAC;AACJ,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,eAAe,CAAC,MAI/B;IACC,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAIlC;IACC,OAAO,eAAe,CAAC;QACrB,GAAG,MAAM;QACT,WAAW,EAAE,EAAE,GAAG,MAAM,CAAC,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE;KAC5D,CAAC,CAAC;AACL,CAAC"}

package/dist/collectors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 declare const COLLECTORS: Record<CollectorName, EscrowCollector>;
+/** The `AuthCaptureEscrow` (Base Mainnet == Base Sepolia). */
+export declare const AUTH_CAPTURE_ESCROW: "0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff";
+/** 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 declare function getCollector(name: CollectorName): EscrowCollector;
+/**
+ * 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 declare function assertSignatureGrade(name: CollectorName): Refusal | null;
+//# sourceMappingURL=collectors.d.ts.map

package/dist/collectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectors.d.ts","sourceRoot":"","sources":["../src/collectors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAE1E;;8EAE8E;AAC9E,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,SAAS,GACT,iBAAiB,GACjB,aAAa,CAAC;AAElB;;mGAEmG;AACnG,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,KAAK,EAAE,SAAS,CAAC;IACjB,gGAAgG;IAChG,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,sGAAsG;AACtG,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,aAAa,EAAE,eAAe,CAyB7D,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,EAC9B,4CAAqD,CAAC;AAExD;qFACqF;AACrF,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,GAAG,IAAI,CAiBxE"}

package/dist/collectors.js

@@ -0,0 +1,59 @@
+/** The base/commerce-payments collector deployments (Base Mainnet == Base Sepolia, deterministic). */
+export const COLLECTORS = {
+    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";
+/** 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) {
+    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) {
+    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;
+}
+//# sourceMappingURL=collectors.js.map

package/dist/collectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectors.js","sourceRoot":"","sources":["../src/collectors.ts"],"names":[],"mappings":"AAkCA,sGAAsG;AACtG,MAAM,CAAC,MAAM,UAAU,GAA2C;IAChE,OAAO,EAAE;QACP,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,4CAA4C;QACrD,KAAK,EAAE,WAAW;QAClB,MAAM,EAAE,IAAI;KACb;IACD,OAAO,EAAE;QACP,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,4CAA4C;QACrD,KAAK,EAAE,WAAW;QAClB,MAAM,EAAE,KAAK;KACd;IACD,eAAe,EAAE;QACf,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,4CAA4C;QACrD,KAAK,EAAE,WAAW;QAClB,MAAM,EAAE,KAAK;KACd;IACD,WAAW,EAAE;QACX,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,4CAA4C;QACrD,KAAK,EAAE,IAAI;QACX,MAAM,EAAE,KAAK;KACd;CACF,CAAC;AAEF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,mBAAmB,GAC9B,4CAAqD,CAAC;AAExD;qFACqF;AACrF,MAAM,UAAU,YAAY,CAAC,IAAmB;IAC9C,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAmB;IACtD,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,CAAC,CAAC,KAAK,KAAK,WAAW;QACzB,OAAO;YACL,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,kBAAkB;YAC7B,IAAI,EAAE,2BAA2B;YACjC,MAAM,EAAE,aAAa,IAAI,OAAO,CAAC,CAAC,KAAK,0EAA0E;SAClH,CAAC;IACJ,IAAI,CAAC,CAAC,CAAC,MAAM;QACX,OAAO;YACL,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,kBAAkB;YAC7B,IAAI,EAAE,2BAA2B;YACjC,MAAM,EAAE,aAAa,IAAI,8FAA8F;SACxH,CAAC;IACJ,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EAChB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,UAAU,EACV,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,cAAc,EACd,QAAQ,GACT,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { atrHashFromSalt, createEscrowAdapter, decodeEscrowLogs, ESCROW_EVENTS_ABI, saltFromAtrHash, } from "./adapter.js";
+export { getHashOffchain, PAYMENT_INFO_TYPEHASH, payerAgnosticNonce, paymentInfoHash, } from "./calls.js";
+export { AUTH_CAPTURE_ESCROW, assertSignatureGrade, COLLECTORS, getCollector, } from "./collectors.js";
+export { EVENT_TO_STATE, stateFor, } from "./lifecycle.js";
+export { ESCROW_MANIFEST } from "./manifest.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,mBAAmB,EAEnB,gBAAgB,EAChB,iBAAiB,EAKjB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,UAAU,EAGV,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAGL,cAAc,EACd,QAAQ,GACT,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 declare const EVENT_TO_STATE: Record<EscrowEventName, EscrowState["s"]>;
+/** Build the discriminated `EscrowState` for an event + its amount (amount ignored for void/reclaim). */
+export declare function stateFor(event: EscrowEventName, amount: bigint): EscrowState;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,CAAC,EAAE,UAAU,CAAA;CAAE,GACjB;IAAE,CAAC,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,CAAC,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,CAAC,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,CAAC,EAAE,QAAQ,CAAA;CAAE,GACf;IAAE,CAAC,EAAE,WAAW,CAAA;CAAE,GAClB;IAAE,CAAC,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,6FAA6F;AAC7F,MAAM,MAAM,eAAe,GACvB,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,GAChB,eAAe,GACf,kBAAkB,GAClB,iBAAiB,CAAC;AAEtB;0DAC0D;AAC1D,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,eAAe,EAAE,WAAW,CAAC,GAAG,CAAC,CAOpE,CAAC;AAEF,yGAAyG;AACzG,wBAAgB,QAAQ,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAe5E"}

package/dist/lifecycle.js

@@ -0,0 +1,28 @@
+/** 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 = {
+    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, amount) {
+    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 };
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAyBA;0DAC0D;AAC1D,MAAM,CAAC,MAAM,cAAc,GAA8C;IACvE,iBAAiB,EAAE,YAAY;IAC/B,eAAe,EAAE,UAAU;IAC3B,cAAc,EAAE,SAAS;IACzB,aAAa,EAAE,QAAQ;IACvB,gBAAgB,EAAE,WAAW;IAC7B,eAAe,EAAE,UAAU;CAC5B,CAAC;AAEF,yGAAyG;AACzG,MAAM,UAAU,QAAQ,CAAC,KAAsB,EAAE,MAAc;IAC7D,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,mBAAmB;YACtB,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;QACrC,KAAK,iBAAiB;YACpB,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QACnC,KAAK,gBAAgB;YACnB,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAClC,KAAK,eAAe;YAClB,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC;QACzB,KAAK,kBAAkB;YACrB,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC;QAC5B,KAAK,iBAAiB;YACpB,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrC,CAAC;AACH,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,52 @@
+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 declare const ESCROW_MANIFEST: BindingManifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,eAAe,EAAE,eA+B7B,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,82 @@
+/**
+ * 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 = {
+    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",
+    ],
+};
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,CAAC,MAAM,eAAe,GAAoB;IAC9C,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,cAAc;IACvB,WAAW,EAAE,kBAAkB;IAC/B,QAAQ,EAAE;QACR,OAAO,EAAE,IAAI;QACb,oBAAoB,EAAE,IAAI;QAC1B,gBAAgB,EAAE,KAAK;KACxB;IACD,YAAY,EAAE,SAAS,EAAE,uFAAuF;IAChH,WAAW,EAAE,YAAY,EAAE,qEAAqE;IAChG,QAAQ,EAAE,iCAAiC;IAC3C,QAAQ,EAAE;QACR,UAAU,EAAE,IAAI;QAChB,IAAI,EAAE,0eAA0e;KACjf;IACD,UAAU,EAAE;QACV,OAAO,EAAE,WAAW;QACpB,OAAO,EAAE,WAAW;QACpB,eAAe,EAAE,WAAW;QAC5B,WAAW,EAAE,IAAI;KAClB;IACD,eAAe,EAAE;QACf,UAAU;QACV,YAAY;QACZ,UAAU;QACV,SAAS;QACT,QAAQ;QACR,WAAW;QACX,UAAU;KACX;CACF,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@integraledger/lcp-binding-evm-escrow",
+  "version": "0.9.0",
+  "description": "Welds an ATR hash into an authorize-and-capture escrow settlement on EVM chains.",
+  "keywords": [
+    "lcp",
+    "legal-context-protocol",
+    "legal-terms",
+    "agentic-commerce",
+    "settlement",
+    "atr-hash",
+    "evm",
+    "escrow"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IntegraLedger/integra-protocol.git",
+    "directory": "packages/binding-evm-escrow"
+  },
+  "bugs": {
+    "url": "https://github.com/IntegraLedger/integra-protocol/issues"
+  },
+  "homepage": "https://github.com/IntegraLedger/integra-protocol/tree/main/packages/binding-evm-escrow#readme",
+  "dependencies": {
+    "viem": "2.55.11",
+    "@integraledger/lcp-binding-core": "0.9.0",
+    "@integraledger/lcp-binding-evm-common": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "vitest": "4.1.10",
+    "@integraledger/lcp-kernel": "0.9.0"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "drift": "vitest run --config vitest.drift.config.ts"
+  }
+}