@integraledger/lcp-binding-evm-escrow 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @integraledger/lcp-binding-evm-escrow
+
+## 0.9.0
+
+First public release.
+
+`0.9.0` is deliberate: this is a release candidate for 1.0, not a preview. The implementation is complete
+against LCP v1.38 and certified by the conformance corpus, and the remaining distance to 1.0 is the
+specification's own — the standard is still moving through its steering committee, and this package will not
+claim a stability its protocol has not yet promised.
+
+Development before this release happened in a private repository and is not reproduced here; no earlier
+version was ever available to install.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,14 @@
+Integra Protocol
+Copyright 2026 Integra Ledger
+
+This product includes software developed by Integra Ledger (https://integraledger.com).
+
+"Integra", "Integra Ledger", and the Integra logo are trademarks of Integra Ledger.
+Trademark use is not granted by the Apache License 2.0 (see Section 6).
+
+The Legal Context Protocol is co-stewarded by Integra Ledger and AAA-ICDR. This repository is a
+reference implementation of the standard's open layer; the specification itself is published at
+https://legalcontextprotocol.org/standard and is not part of this distribution.
+
+The vendored submodule under lib/commerce-payments is Coinbase's AuthCaptureEscrow and carries its own
+MIT licence at lib/commerce-payments/LICENSE.md. It is not covered by the Apache License above.

package/README.md

@@ -0,0 +1,116 @@
+# @integraledger/lcp-binding-evm-escrow
+
+Welds an ATR hash into an authorize-and-capture escrow settlement on EVM chains.
+
+```bash
+npm install @integraledger/lcp-binding-evm-escrow
+```
+
+| | |
+|---|---|
+| **Chain** | EVM |
+| **Pattern** | `native-field` |
+| **Carrier** | `PaymentInfo.salt` |
+| **Surface** | `createEscrowAdapter` returning [`@integraledger/lcp-binding-core`](../binding-core#readme)'s `WeldAdapter` over a `ChainReader` |
+
+
+Built on [`@integraledger/lcp-binding-core`](../binding-core#readme)'s `WeldAdapter` and
+[`@integraledger/lcp-binding-evm-common`](../binding-evm-common#readme). Installing this package installs
+**viem**.
+
+```ts
+import { atrHashFromSalt, createEscrowAdapter } from "@integraledger/lcp-binding-evm-escrow";
+import type { VerifierPorts } from "@integraledger/lcp-binding-core";
+
+declare const atrHash: `0x${string}`;
+declare const ctx: Omit<
+  import("@integraledger/lcp-binding-evm-escrow").PaymentInfo,
+  "salt"
+>;
+declare const ports: VerifierPorts; // your viem-backed ChainReader + ArtifactResolver
+declare const txHash: `0x${string}`;
+
+const adapter = createEscrowAdapter({ chainId: 84532 });
+
+// SERVICE OPERATOR — the PaymentInfo to submit, with `salt` filled from the atrHash.
+const proposed = await adapter.propose(atrHash, ctx);
+
+// VERIFIER — the atrHash back out of the settlement's PaymentAuthorized/PaymentCharged event.
+const recovered = await adapter.recover({ chainId: 84532, txHash }, ports);
+if (!("refused" in recovered)) console.log(recovered.value); // "0x…"
+// Narrow with `"refused" in x` — `Refusal` has no `ok`, so the union cannot discriminate on one.
+
+atrHashFromSalt(0n); // the inverse, for a salt you already hold
+```
+
+## The carrier
+
+The ATR hash rides `PaymentInfo.salt` — an existing field the service already controls. No derivation,
+no overlay contract.
+
+```ts
+import { EVENT_TO_STATE } from "@integraledger/lcp-binding-evm-escrow";
+
+EVENT_TO_STATE.PaymentCharged; // "charged"
+```
+
+## What it refuses rather than guesses
+
+One escrow transaction can authorize or charge several independent payments, each with its own
+`PaymentInfo` and therefore its own ATR hash. `recover` will not choose between them:
+
+| Refusal | When |
+|---|---|
+| `escrow/ambiguous-settlement` | The transaction carries salt-bearing events with *different* salts and the `SettlementRef` pins no `logIndex`. Pin one. The same payment seen through both `PaymentAuthorized` and `PaymentCharged` carries one salt and resolves normally. |
+| `escrow/log-index-not-found` | A pinned `logIndex` matches no salt-bearing event — a failure, never a fall-through to the first one. |
+| `escrow/no-recoverable-event` | No `PaymentAuthorized`/`PaymentCharged` with a cleartext `PaymentInfo` in the settlement. |
+
+Recovery is an **event-data scan**, not a topic filter: `paymentInfoHash` is the only indexed key and it
+is not derivable from an ATR hash alone, so `enumerate` fetches the salt-bearing events over a range and
+filters client-side. The manifest declares `forwardIndexable: false` for exactly that reason.
+
+## Escrow is a mechanism, not our product
+
+This package encodes calls to Coinbase's MIT-licensed `AuthCaptureEscrow` and collects its events. It
+does not supply, operate, or price an escrow. What it contributes is the **record weld across authorize
+and capture** — so that a payment authorized under one set of terms and captured later can still be shown
+to correspond to those terms.
+
+Lifecycle states are a discriminated union rather than a string enum, so an illegal state is not
+constructible instead of being rejected at runtime.
+
+## The drift guard
+
+The constants this package ships — `PAYMENT_INFO_TYPEHASH`, and the `getHashOffchain` / `saltFromAtrHash`
+derivations — are re-derived **weekly against the deployed `AuthCaptureEscrow`** on live Base mainnet and
+Sepolia, in a lane held outside the default test run (per-mutant RPC storms are the reason). So a green
+unit-test run says nothing about contract drift, and the weekly lane is what does.
+
+That matters to you as a consumer because these are values you cannot check by reading: a typehash that
+drifted from the deployed contract produces a well-formed hash that matches nothing on chain. The guard is
+in the source repository rather than in this tarball, which is why the property is stated here rather than
+the file path — you receive the constants and the fact that they are checked, not the checker.
+
+## Requirement ids
+
+This package's source and its messages cite short ids — `ATA-3`, `RCS-5`, `CMP-6` and their kin.
+**They are not LCP clause numbers.** LCP is cited by section (`§8.3.1`, `§C.2`); anything shaped `XXX-n`
+comes from Integra's functional specification of what a complete agent transaction requires, the fourteen
+families below. Nothing in this package's behaviour depends on them, and where an id and an LCP section
+disagree the section governs.
+
+| | | | |
+|---|---|---|---|
+| `IDN` identity | `ASP` authority to spend | `ATA` authority to accept terms | `TRM` the terms record |
+| `RCS` recourse | `PAY` payment and settlement | `WLD` the transactional weld | `OFR` offer integrity |
+| `FRC` fraud, risk, and compliance | `OPS` commercial operations | `DSC` discovery and reputation | `ORC` orchestration |
+| `CMP` composition | `PRS` persistence and verification infrastructure | | |
+
+---
+
+**Requires Node >= 24.** Part of the
+[Legal Context Protocol open layer](https://github.com/IntegraLedger/integra-protocol) — see the
+[documentation](https://github.com/IntegraLedger/integra-protocol/blob/main/docs/developer/index.md)
+and the
+[package index](https://github.com/IntegraLedger/integra-protocol/blob/main/docs/developer/reference.md).
+Apache-2.0.

package/dist/adapter.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 { WeldAdapter } from "@integraledger/lcp-binding-core";
+import { type Abi, type Log } from "viem";
+import { type EscrowEventName } from "./lifecycle.js";
+/** The six escrow lifecycle events. `PaymentAuthorized`/`PaymentCharged` carry the cleartext `PaymentInfo`
+ *  (→ salt → atrHash); the rest join on the indexed `paymentInfoHash`. */
+export declare const ESCROW_EVENTS_ABI: Abi;
+/** `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 declare function saltFromAtrHash(atrHash: `0x${string}`): bigint;
+/** Recover the atrHash from a `PaymentInfo.salt` — the reverse (lowercase 0x, 32 bytes). */
+export declare function atrHashFromSalt(salt: bigint): `0x${string}`;
+/** 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 declare function decodeEscrowLogs(logs: readonly Log[], escrow: string): DecodedEscrowLog[];
+/** Construct the escrow WeldAdapter for one chain. */
+export declare function createEscrowAdapter(config: EscrowAdapterConfig): WeldAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAKV,WAAW,EACZ,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,KAAK,GAAG,EAAkB,KAAK,GAAG,EAAY,MAAM,MAAM,CAAC;AAEpE,OAAO,EAAE,KAAK,eAAe,EAAkB,MAAM,gBAAgB,CAAC;AAMtE;0EAC0E;AAC1E,eAAO,MAAM,iBAAiB,EAAE,GAO9B,CAAC;AAEH,iGAAiG;AACjG,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,KAAK,MAAM,EAAE,CAAC;IACxB,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,KAAK,MAAM,EAAE,CAAC;IACxB,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,OAAO,EAAE,KAAK,MAAM,EAAE,GAAG,MAAM,CAE9D;AACD,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,MAAM,EAAE,CAE3D;AAED,yGAAyG;AACzG,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;AAC9D;;+EAE+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;qFAEqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,eAAe,CAAC;IACtB,2GAA2G;IAC3G,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,KAAK,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IACtB,sEAAsE;IACtE,KAAK,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,KAAK,MAAM,EAAE,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,GAAG,EAAE,EACpB,MAAM,EAAE,MAAM,GACb,gBAAgB,EAAE,CAuCpB;AAED,sDAAsD;AACtD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,WAAW,CAqG5E"}

package/dist/adapter.js

@@ -0,0 +1,152 @@
+import { refOf } from "@integraledger/lcp-binding-evm-common";
+import { decodeEventLog, parseAbi } from "viem";
+import { AUTH_CAPTURE_ESCROW } from "./collectors.js";
+import { 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 = 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)",
+]);
+/** `salt = uint256(atrHash)` — the 32-byte atrHash reinterpreted as a uint256. */
+export function saltFromAtrHash(atrHash) {
+    return BigInt(atrHash);
+}
+/** Recover the atrHash from a `PaymentInfo.salt` — the reverse (lowercase 0x, 32 bytes). */
+export function atrHashFromSalt(salt) {
+    return `0x${salt.toString(16).padStart(64, "0")}`;
+}
+/**
+ * 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, escrow) {
+    const want = escrow.toLowerCase();
+    const out = [];
+    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;
+            out.push({
+                name: decoded.eventName,
+                ...(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) {
+    const escrow = config.escrow ?? AUTH_CAPTURE_ESCROW;
+    return {
+        manifest: ESCROW_MANIFEST,
+        async propose(atrHash, ctx) {
+            const c = ctx;
+            // 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 = { ...c, salt: saltFromAtrHash(atrHash) };
+            return { ok: true, value: { paymentInfo } };
+        },
+        async recover(ref, ports) {
+            const logs = (await ports.chain.getTransactionLogs(ref));
+            // Only PaymentAuthorized/PaymentCharged carry the cleartext PaymentInfo (→ salt → atrHash).
+            const salted = decodeEscrowLogs(logs, escrow).filter((e) => 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].salt),
+            };
+        },
+        async observe(ref, ports) {
+            const logs = (await ports.chain.getTransactionLogs(ref));
+            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, ports) {
+            // 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",
+            }));
+            return decodeEscrowLogs(logs, escrow)
+                .filter((e) => e.salt === want)
+                .map((e) => refOf(config.chainId, e.txHash ?? undefined, e.logIndex));
+        },
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,EAAE,MAAM,uCAAuC,CAAC;AAC9D,OAAO,EAAY,cAAc,EAAY,QAAQ,EAAE,MAAM,MAAM,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAwB,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,QAAQ,GACZ,yOAAyO,CAAC;AAE5O;0EAC0E;AAC1E,MAAM,CAAC,MAAM,iBAAiB,GAAQ,QAAQ,CAAC;IAC7C,4DAA4D,QAAQ,uDAAuD;IAC3H,yDAAyD,QAAQ,2FAA2F;IAC5J,4GAA4G;IAC5G,sEAAsE;IACtE,yEAAyE;IACzE,gGAAgG;CACjG,CAAC,CAAC;AAkBH,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,OAAsB;IACpD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC;AACD,4FAA4F;AAC5F,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,KAAK,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC;AACpD,CAAC;AA6CD;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAoB,EACpB,MAAc;IAEd,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IAClC,MAAM,GAAG,GAAuB,EAAE,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,IAAI;YAAE,SAAS;QACjD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,cAAc,CAAC;gBAC7B,GAAG,EAAE,iBAAiB;gBACtB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,MAAM,EAAE,GAAG,CAAC,MAAM;aACnB,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,OAAO,CAAC,IAQpB,CAAC;YACF,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI,EAAE,OAAO,CAAC,SAAuC;gBACrD,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS;oBAChC,CAAC,CAAC;wBACE,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI;wBAC3B,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,KAAK;wBAC7B,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,KAAK;wBAC7B,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,QAAQ;qBACpC;oBACH,CAAC,CAAC,EAAE,CAAC;gBACP,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,MAAM,EAAE,GAAG,CAAC,eAAe;aAC5B,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,yCAAyC;QAC3C,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,mBAAmB,CAAC,MAA2B;IAC7D,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,mBAAmB,CAAC;IACpD,OAAO;QACL,QAAQ,EAAE,eAAe;QAEzB,KAAK,CAAC,OAAO,CACX,OAAsB,EACtB,GAAY;YAEZ,MAAM,CAAC,GAAG,GAA4B,CAAC;YACvC,iFAAiF;YACjF,6FAA6F;YAC7F,MAAM,WAAW,GAAgB,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,EAAE,CAAC;QAC9C,CAAC;QAED,KAAK,CAAC,OAAO,CACX,GAAkB,EAClB,KAAoB;YAEpB,MAAM,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAU,CAAC;YAClE,4FAA4F;YAC5F,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAClD,CAAC,CAAC,EAAoC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAC9D,CAAC;YACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBACrB,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,SAAS,EAAE,sBAAsB;oBACjC,IAAI,EAAE,6BAA6B;oBACnC,MAAM,EAAE,qFAAqF;iBAC9F,CAAC;YACJ,qGAAqG;YACrG,kGAAkG;YAClG,wDAAwD;YACxD,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC/B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,GAAG,CAAC,QAAQ,CAAC,CAAC;gBAC9D,IAAI,KAAK,KAAK,SAAS;oBACrB,OAAO;wBACL,OAAO,EAAE,IAAI;wBACb,SAAS,EAAE,sBAAsB;wBACjC,IAAI,EAAE,4BAA4B;wBAClC,MAAM,EAAE,4CAA4C,GAAG,CAAC,QAAQ,kBAAkB,GAAG,CAAC,MAAM,EAAE;qBAC/F,CAAC;gBACJ,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1D,CAAC;YACD,kGAAkG;YAClG,uGAAuG;YACvG,qGAAqG;YACrG,mFAAmF;YACnF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YACpD,IAAI,QAAQ,CAAC,IAAI,GAAG,CAAC;gBACnB,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,SAAS,EAAE,sBAAsB;oBACjC,IAAI,EAAE,6BAA6B;oBACnC,MAAM,EAAE,cAAc,GAAG,CAAC,MAAM,YAAY,QAAQ,CAAC,IAAI,gGAAgG;iBAC1J,CAAC;YACJ,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,KAAK,EAAE,eAAe,CAAE,MAAM,CAAC,CAAC,CAA6B,CAAC,IAAI,CAAC;aACpE,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,OAAO,CACX,GAAkB,EAClB,KAAoB;YAEpB,MAAM,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAU,CAAC;YAClE,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC9C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;YACxD,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YAC5C,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACxB,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;oBAC7B,EAAE;oBACF,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC;iBAChD,CAAC,CAAC;aACJ,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,SAAS,CACb,OAAsB,EACtB,KAAoB;YAEpB,mGAAmG;YACnG,mGAAmG;YACnG,gGAAgG;YAChG,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;YACtC,MAAM,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC;gBACtC,OAAO,EAAE,MAAM;gBACf,MAAM,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,oCAAoC;gBAC1F,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,UAAU;gBACzC,OAAO,EAAE,QAAQ;aAClB,CAAC,CAAU,CAAC;YACb,OAAO,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC;iBAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;iBAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC1E,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/calls.d.ts

@@ -0,0 +1,30 @@
+import type { PaymentInfo } from "./adapter.js";
+/** keccak256 of the PaymentInfo typehash STRING (== the deployed PAYMENT_INFO_TYPEHASH, 0xae68…6591). */
+export declare const PAYMENT_INFO_TYPEHASH: `0x${string}`;
+/**
+ * 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 declare function getHashOffchain(params: {
+    chainId: number;
+    escrow?: `0x${string}`;
+    paymentInfo: PaymentInfo;
+}): `0x${string}`;
+/** The settlement key / event `paymentInfoHash` for a PaymentInfo (alias of `getHashOffchain`). */
+export declare function paymentInfoHash(params: {
+    chainId: number;
+    escrow?: `0x${string}`;
+    paymentInfo: PaymentInfo;
+}): `0x${string}`;
+/**
+ * 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 declare function payerAgnosticNonce(params: {
+    chainId: number;
+    escrow?: `0x${string}`;
+    paymentInfo: PaymentInfo;
+}): `0x${string}`;
+//# sourceMappingURL=calls.d.ts.map

package/dist/calls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calls.d.ts","sourceRoot":"","sources":["../src/calls.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAsBhD,yGAAyG;AACzG,eAAO,MAAM,qBAAqB,EAAE,KAAK,MAAM,EAI9C,CAAC;AAIF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,WAAW,CAAC;CAC1B,GAAG,KAAK,MAAM,EAAE,CAchB;AAED,mGAAmG;AACnG,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,WAAW,CAAC;CAC1B,GAAG,KAAK,MAAM,EAAE,CAEhB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,WAAW,CAAC;CAC1B,GAAG,KAAK,MAAM,EAAE,CAKhB"}