@integraledger/lcp-binding-evm-x402 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @integraledger/lcp-binding-evm-x402
+
+## 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,115 @@
+# @integraledger/lcp-binding-evm-x402
+
+Welds an ATR hash into an [x402](https://x402.org) instant settlement on any EVM chain.
+
+```bash
+npm install @integraledger/lcp-binding-evm-x402
+```
+
+| | |
+|---|---|
+| **Chain** | EVM |
+| **Pattern** | `native-field` |
+| **Carrier** | the EIP-3009 `nonce` |
+| **Surface** | `createX402Adapter` 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)'s typed-data and event machinery.
+Installing this package installs **viem**.
+
+```ts
+import { createX402Adapter, getX402Deployment } from "@integraledger/lcp-binding-evm-x402";
+import type { VerifierPorts } from "@integraledger/lcp-binding-core";
+
+declare const atrHash: `0x${string}`;
+declare const from: string;
+declare const payTo: string;
+declare const ports: VerifierPorts; // your viem-backed ChainReader + ArtifactResolver
+declare const txHash: `0x${string}`;
+
+const d = getX402Deployment("base-sepolia-usdc");
+const adapter = createX402Adapter({
+  chainId: d.chainId,
+  asset: d.asset,
+  tokenName: d.tokenName,
+  tokenVersion: d.tokenVersion,
+});
+
+// PAYER — the EIP-3009 authorization plus the EIP-712 payload to sign. `nonce` IS the atrHash.
+const proposed = await adapter.propose(atrHash, {
+  from,
+  payTo,
+  amount: "1000000",
+  validAfter: "0",
+  validBefore: "99999999999",
+});
+
+// VERIFIER — the atrHash back out of the settlement's `AuthorizationUsed` log.
+const recovered = await adapter.recover({ chainId: d.chainId, 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.
+```
+
+## The carrier
+
+The ATR hash rides the EIP-3009 `nonce` — a field that already exists in the authorization the payer
+signs. There is no derivation and no overlay contract: the payer's signature covers the nonce, so it
+covers the ATR hash, and the binding inherits the settlement's own authenticity.
+
+```ts
+import { verifyInboundNonce } from "@integraledger/lcp-binding-evm-x402";
+
+declare const presentedNonce: string;
+declare const advertisedAtrHash: string;
+
+const checked = verifyInboundNonce(presentedNonce, advertisedAtrHash);
+if ("refused" in checked) console.log(checked.code); // "x402/nonce-mismatch" -> re-challenge
+```
+
+Recovery is a scan of `AuthorizationUsed` events on the nonce topic, so a settlement is
+forward-indexable: given the ATR hash, the settlement that carried it can be found without knowing the
+transaction in advance.
+
+## What it refuses rather than guesses
+
+Two settlements this binding will not answer for, because the honest answer is a refusal and the
+convenient one is wrong:
+
+| Refusal | When |
+|---|---|
+| `x402/not-eip3009-settlement` | The token moved and no `AuthorizationUsed` accompanied it. The payment settled — through the Permit2 fallback or another path that carries no payer-controlled nonce — so there is no weld to report. An empty transition list would say the opposite: that nothing settled. |
+| `x402/ambiguous-settlement` | One transaction carries several `AuthorizationUsed` events with *different* nonces and the `SettlementRef` pins no `logIndex`. Answering either one would be a coin flip presented as a recovery. Pin one with `ref.logIndex`. Repeats of the *same* nonce are one weld seen twice, and resolve normally. |
+
+`x402/permit2-fallback` is the propose-side counterpart: an offer requesting a non-EIP-3009 transfer
+method is refused before it is signed, rather than settled unwelded.
+
+## The inbound re-challenge
+
+`verifyInboundNonce` is what makes the weld non-optional in practice. A client that settles with a nonce
+that is not the advertised ATR hash is re-challenged rather than silently served — so an unwelded payment
+does not quietly become a served request.
+
+## 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,42 @@
+/**
+ * The x402 `exact` / EIP-3009 WeldAdapter (LCP `LCP-X402-EVM-NONCE-1`). Built on the live
+ * (`lcp-x402-reference`, 114 tests) onto binding-core's `WeldAdapter` contract, with the typed-data
+ * machinery reused from `binding-evm-common` (viem lives only here and in binding-evm-common).
+ *
+ * - `propose`  — build the EIP-3009 authorization + typed-data with `nonce = atrHash` (after the Permit2
+ *                filter); the payer signs the returned `typedData`.
+ * - `recover`  — read the committed nonce back out of ONE settlement's `AuthorizationUsed` log (= atrHash).
+ * - `observe`  — map a settlement's `AuthorizationUsed` events to `welded-settled` lifecycle transitions.
+ * - `enumerate`— forward-index by the indexed nonce topic (`AuthorizationUsed(_, indexed nonce)`).
+ */
+import type { WeldAdapter } from "@integraledger/lcp-binding-core";
+import { type Eip3009Authorization, type Eip3009TypedData } from "@integraledger/lcp-binding-evm-common";
+/** One chain + token this adapter binds. `tokenName`/`tokenVersion` pin the EIP-712 domain of `asset`. */
+export interface X402AdapterConfig {
+    chainId: number;
+    /** The payment token — the EIP-712 `verifyingContract` and the `AuthorizationUsed` emitter. */
+    asset: `0x${string}`;
+    tokenName: string;
+    tokenVersion: string;
+    /** Enumeration lower bound; defaults to the full history (`earliest`). */
+    fromBlock?: bigint;
+}
+/** The per-payment proposal inputs (the token/chain identity lives in the adapter config). */
+export interface X402ProposalContext {
+    from: string;
+    payTo: string;
+    /** Amount in token base units (decimal string). */
+    amount: string;
+    validAfter: string;
+    validBefore: string;
+    /** The x402 offer's asset-transfer method; anything but `eip3009` is refused (Permit2 filter). */
+    assetTransferMethod?: string;
+}
+/** What `propose` yields: the wire authorization + the typed-data the payer signs. */
+export interface X402Proposal {
+    authorization: Eip3009Authorization;
+    typedData: Eip3009TypedData;
+}
+/** Construct the x402 WeldAdapter for one chain + token. */
+export declare function createX402Adapter(config: X402AdapterConfig): 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;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAKV,WAAW,EACZ,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EAGtB,MAAM,uCAAuC,CAAC;AAM/C,0GAA0G;AAC1G,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,+FAA+F;IAC/F,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,8FAA8F;AAC9F,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,kGAAkG;IAClG,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,oBAAoB,CAAC;IACpC,SAAS,EAAE,gBAAgB,CAAC;CAC7B;AAED,4DAA4D;AAC5D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CA2HxE"}

package/dist/adapter.js

@@ -0,0 +1,124 @@
+/**
+ * The x402 `exact` / EIP-3009 WeldAdapter (LCP `LCP-X402-EVM-NONCE-1`). Built on the live
+ * (`lcp-x402-reference`, 114 tests) onto binding-core's `WeldAdapter` contract, with the typed-data
+ * machinery reused from `binding-evm-common` (viem lives only here and in binding-evm-common).
+ *
+ * - `propose`  — build the EIP-3009 authorization + typed-data with `nonce = atrHash` (after the Permit2
+ *                filter); the payer signs the returned `typedData`.
+ * - `recover`  — read the committed nonce back out of ONE settlement's `AuthorizationUsed` log (= atrHash).
+ * - `observe`  — map a settlement's `AuthorizationUsed` events to `welded-settled` lifecycle transitions.
+ * - `enumerate`— forward-index by the indexed nonce topic (`AuthorizationUsed(_, indexed nonce)`).
+ */
+import { AUTHORIZATION_USED_ABI, assetWasTransferred, buildEip3009TypedData, readAuthorizationUsed, refOf, } from "@integraledger/lcp-binding-evm-common";
+import { canonicalAtrHash } from "@integraledger/lcp-kernel";
+import { filterAssetTransferMethod } from "./asset-transfer-method-filter.js";
+import { X402_MANIFEST } from "./manifest.js";
+/** Construct the x402 WeldAdapter for one chain + token. */
+export function createX402Adapter(config) {
+    return {
+        manifest: X402_MANIFEST,
+        async propose(atrHash, ctx) {
+            const c = ctx;
+            const refusal = filterAssetTransferMethod(c.assetTransferMethod);
+            if (refusal !== null)
+                return refusal;
+            // buildEip3009TypedData throws (fail-fast) on a malformed atrHash — a programming error, not a
+            // policy outcome; the Permit2 refusal above is the only value-level Refusal on this path.
+            const { authorization, typedData } = buildEip3009TypedData({
+                atrHash,
+                from: c.from,
+                to: c.payTo,
+                value: c.amount,
+                validAfter: c.validAfter,
+                validBefore: c.validBefore,
+                chainId: config.chainId,
+                tokenName: config.tokenName,
+                tokenVersion: config.tokenVersion,
+                verifyingContract: config.asset,
+            });
+            return { ok: true, value: { authorization, typedData } };
+        },
+        async recover(ref, ports) {
+            const logs = (await ports.chain.getTransactionLogs(ref));
+            const events = readAuthorizationUsed(logs, config.asset);
+            if (events.length === 0)
+                return {
+                    refused: true,
+                    haltClass: "verification-failure",
+                    code: "x402/no-settlement-event",
+                    detail: `no AuthorizationUsed for asset ${config.asset} in this settlement`,
+                };
+            // Disambiguate by logIndex when the ref pins one — but a pinned index that matches NO event is a
+            // failure, never a silent fallback to events[0] (that could recover a DIFFERENT settlement's
+            // atrHash — a fail-fast violation). events.length > 0 guarantees events[0] is defined.
+            if (ref.logIndex !== undefined) {
+                const match = events.find((e) => e.logIndex === ref.logIndex);
+                if (match === undefined)
+                    return {
+                        refused: true,
+                        haltClass: "verification-failure",
+                        code: "x402/log-index-not-found",
+                        detail: `no AuthorizationUsed at logIndex ${ref.logIndex} for asset ${config.asset}`,
+                    };
+                return { ok: true, value: match.nonce };
+            }
+            // UNPINNED, and more than one DISTINCT nonce in the transaction: the caller has not said which
+            // settlement it is asking about, and this function must not choose for it. It used to answer
+            // `events[0]` — the silent fallback the comment three lines above already calls a fail-fast
+            // violation, committed in the branch that comment did not cover. Distinctness is what makes it an
+            // ambiguity: several `AuthorizationUsed` logs carrying the SAME nonce are one weld observed more
+            // than once, and refusing those would break a legitimate batch. Same shape as tempo-mpp's
+            // `ambiguous-memos`, for the same reason.
+            const distinct = new Set(events.map((e) => e.nonce.toLowerCase()));
+            if (distinct.size > 1)
+                return {
+                    refused: true,
+                    haltClass: "verification-failure",
+                    code: "x402/ambiguous-settlement",
+                    detail: `settlement ${ref.txHash} carries ${distinct.size} AuthorizationUsed events with different nonces for asset ${config.asset} — pin one with ref.logIndex rather than choosing for the caller`,
+                };
+            return { ok: true, value: events[0].nonce };
+        },
+        async observe(ref, ports) {
+            const logs = (await ports.chain.getTransactionLogs(ref));
+            const events = readAuthorizationUsed(logs, config.asset);
+            if (events.length === 0) {
+                // An empty transition list is a POSITIVE claim: this transaction settled nothing of this asset.
+                // That is true only when the token did not move. If it did, the payment settled through a path
+                // this binding cannot read the weld from — in practice x402's Permit2 fallback
+                // (`x402ExactPermit2Proxy`), which exposes no payer-controlled nonce, which is exactly why
+                // `filterAssetTransferMethod` refuses it on the propose side. Answering `[]` here would let the
+                // observe side quietly assert the opposite of what the propose side refuses to allow.
+                if (assetWasTransferred(logs, config.asset))
+                    return {
+                        refused: true,
+                        haltClass: "verification-failure",
+                        code: "x402/not-eip3009-settlement",
+                        detail: `token ${config.asset} was transferred by settlement ${ref.txHash} but it emitted no EIP-3009 AuthorizationUsed — the atrHash weld rides only on the payer-controlled nonce of transferWithAuthorization, so a settlement reached by any other path (the Permit2 fallback among them) carries no on-chain weld this binding can report`,
+                    };
+                return { ok: true, value: [] };
+            }
+            // The only on-chain state x402 exposes is settlement itself (proposed is off-chain, pre-settlement).
+            const at = await ports.chain.blockTime(ref);
+            return {
+                ok: true,
+                value: events.map((e) => ({
+                    state: "welded-settled",
+                    at,
+                    ref: refOf(ref.chainId, ref.txHash, e.logIndex),
+                })),
+            };
+        },
+        async enumerate(atrHash, ports) {
+            const logs = (await ports.chain.getLogs({
+                address: config.asset,
+                event: AUTHORIZATION_USED_ABI[0],
+                args: { nonce: canonicalAtrHash(atrHash, "enumerate") },
+                fromBlock: config.fromBlock ?? "earliest",
+                toBlock: "latest",
+            }));
+            return logs.map((l) => refOf(config.chainId, l.transactionHash ?? undefined, l.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":"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"}

package/dist/asset-transfer-method-filter.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The two mandatory x402 checks.
+ *
+ * 1. **Asset-transfer-method filter.** The atrHash-as-nonce weld rides ONLY on EIP-3009
+ *    `transferWithAuthorization`, whose `nonce` is a payer-controlled 32-byte field committed on-chain in
+ *    `AuthorizationUsed`. x402's `exact` scheme on EVM defines **three** methods, verified at
+ *    `x402-foundation/x402@1fec3aa04e41`:
+ *
+ *      1. `eip3009`  — tokens with native `transferWithAuthorization` (the default when `extra` omits it)
+ *      2. `permit2`  — tokens without it, via a proxy and the canonical Permit2 contract
+ *      3. `erc7710`  — smart accounts with delegation support
+ *
+ *    Only the first exposes a payer-controlled nonce. Under `permit2` the value rides an off-chain EIP-712
+ *    witness, and under `erc7710` the payment is authorized by a delegation the payer's smart account
+ *    granted — in neither case is there a 32-byte field on the settlement for the weld to occupy. An offer
+ *    requesting either would settle a payment that silently DROPS the binding, so this refuses instead.
+ *
+ *    The rule is not Permit2-specific and the naming here is deliberate: it is "the method must be the one
+ *    that carries a payer nonce". A refusal naming only one of the two rejected methods would report a
+ *    correct decision for the wrong reason, which is what an operator then debugs.
+ *
+ *    The settlement-side spender/witness proxy detection is the on-chain extension that lands once a
+ *    harness run closes it; it is NOT fabricated here.
+ *
+ * 2. **Payment-flow filter.** x402 §6.1 defines three flows and reserves `extra.paymentFlow` as a
+ *    protocol key: `authorization` (verify → resource → settle), `upfront` (settle → resource) and
+ *    `escrow` (settle → resource → settle). "When the resolved payment flow is not `authorization`,
+ *    `PaymentRequired` `accepts[].extra.paymentFlow` MUST be present", and "Clients MUST NOT construct a
+ *    payment for a `paymentFlow` they do not recognize."
+ *
+ *    This weld survives `upfront` untouched — one settlement, one EIP-3009 authorization, one nonce.
+ *
+ *    `escrow` settles TWICE, and the scheme's own table marks `eip3009` "One-time use", so a single nonce
+ *    cannot carry both the deposit and the final charge. **That is a statement about THIS carrier, not a
+ *    judgement about the flow.** A two-phase settlement is exactly the case the record is supposed to
+ *    survive, and there is a binding for it: `@integraledger/lcp-binding-evm-escrow` welds
+ *    `PaymentInfo.salt`, which is recoverable from BOTH the authorization and the capture artifact and
+ *    joins them on `paymentInfoHash`. So this answers "not this binding, that one" and names it — it does
+ *    not tell a deployment how to transact, which is not this project's business.
+ *
+ * 3. **Inbound `nonce == atrHash` re-challenge.** The seller-side verification that a presented
+ *    authorization's nonce equals the atrHash it advertised. The primitive lives here; the re-challenge
+ *    orchestration (re-issue the 402 on mismatch) belongs to the seller surface.
+ */
+import type { Outcome, Refusal } from "@integraledger/lcp-binding-core";
+/** The x402 asset-transfer method an offer may request. Only `eip3009` carries the payer nonce. */
+export declare const EIP3009_TRANSFER_METHOD = "eip3009";
+/**
+ * The methods x402's exact-EVM scheme defines, in the scheme's own order. Listed so the refusal can say
+ * whether it met a method the host defines or one nobody does — a typo and an unsupported-but-real method
+ * are different problems for the operator reading the message.
+ */
+export declare const X402_TRANSFER_METHODS: readonly string[];
+/**
+ * Refuse an asset-transfer method that carries no payer nonce. Returns a typed `policy-rejection`
+ * `Refusal` when the method is present and not `eip3009`; `null` when it is absent or `eip3009` (proceed).
+ *
+ * Absent is `null` because x402's scheme says so: "If no `assetTransferMethod` is specified in
+ * `PaymentRequired.extra`, clients should default to `eip3009`."
+ */
+export declare function filterAssetTransferMethod(assetTransferMethod: string | undefined): Refusal | null;
+/** The x402 payment flows, §6.1. `authorization` is the default when `extra.paymentFlow` is omitted. */
+export declare const X402_PAYMENT_FLOWS: readonly string[];
+/**
+ * Report a payment flow this weld cannot ride. `null` means proceed.
+ *
+ * Absent is `null` because §6.1 makes `authorization` the resolved default, and it is also the flow whose
+ * ordering the rest of this package assumes: verify → resource → settle.
+ *
+ * The `escrow` answer is a ROUTING answer, not a policy one. Which settlement shape a party chooses is
+ * theirs; what this project owes them is a record that survives it, and for two-phase settlement that
+ * record is `binding-evm-escrow`'s, not this one's.
+ */
+export declare function filterPaymentFlow(paymentFlow: string | undefined): Refusal | null;
+/**
+ * The inbound re-challenge: does a presented authorization nonce equal the advertised atrHash?
+ * Compared as DECODED BYTES per LCP §2.5, so the two any-case spellings of one hash agree; returns the
+ * lowercased nonce on match, else a `verification-failure`
+ * `Refusal` (the caller re-issues the 402 — never settles an unwelded payment).
+ */
+export declare function verifyInboundNonce(presentedNonce: string, expectedAtrHash: string): Outcome<`0x${string}`>;
+//# sourceMappingURL=asset-transfer-method-filter.d.ts.map

package/dist/asset-transfer-method-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-transfer-method-filter.d.ts","sourceRoot":"","sources":["../src/asset-transfer-method-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAGxE,mGAAmG;AACnG,eAAO,MAAM,uBAAuB,YAAY,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAIlD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,mBAAmB,EAAE,MAAM,GAAG,SAAS,GACtC,OAAO,GAAG,IAAI,CAiBhB;AAED,wGAAwG;AACxG,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAI/C,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,OAAO,GAAG,IAAI,CAchB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAWxB"}