@integraledger/lcp-binding-evm-mpp 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @integraledger/lcp-binding-evm-mpp
+
+## 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,198 @@
+# @integraledger/lcp-binding-evm-mpp
+
+Welds an LCP record to an [MPP](https://paymentauth.org) settlement on EVM, by **Id-Reuse** (LCP §8.3.5): the seller
+sets `challenge.id = atrHash`, and MPP's own required derivation carries it into the transaction.
+
+**This is the one binding in the family that differs at the weld.** On MPP's EVM charge method there is no
+field for us to occupy — the EIP-3009 nonce is a derivation MUST and the Permit2 witness type string is
+fixed. So nothing is placed; an input is supplied, and the host protocol does the binding.
+
+```bash
+npm install @integraledger/lcp-binding-evm-mpp
+```
+
+| | |
+|---|---|
+| **Rail** | `evm:mpp` |
+| **Protocol** | `mpp` |
+| **Pattern** | `id-reuse` (LCP §8.3.5, Tier A) |
+| **Weld** | `nonce = keccak256(abi.encodePacked(challenge.id, challenge.realm))`, with `challenge.id = atrHash` |
+| **Credential-type scope** | MPP's **`authorization`** type only (§5.3) — see below; the other three are out of scope by construction |
+| **On-chain artifact** | `AuthorizationUsed(address indexed authorizer, bytes32 indexed nonce)` |
+| **Recovery triple** | *within that scope* — on-chain **yes**; zero-party recoverable **no**; forward-indexable **no** |
+| **Weld grade** | `weldGrades: { authorization: "signature" }` — the payer's EIP-3009 message covers the nonce |
+| **Surface** | `createMppEvmAdapter` returning [`@integraledger/lcp-binding-core`](../binding-core#readme)'s `WeldAdapter` over a `ChainReader`, built on [`@integraledger/lcp-binding-evm-common`](../binding-evm-common#readme) |
+| **Spec** | `draft-evm-charge-00` + the core `Payment` scheme, gate discharged **2026-07-30** |
+
+## Use
+
+```ts
+import { createMppEvmAdapter } from "@integraledger/lcp-binding-evm-mpp";
+import type { VerifierPorts } from "@integraledger/lcp-binding-core";
+
+declare const USDC: `0x${string}`;    // the settlement token address on this chain
+declare const atrHash: `0x${string}`; // the record's atrHash
+declare const txHash: `0x${string}`;  // the settlement transaction
+declare const ports: VerifierPorts;   // caller-supplied chain access
+
+const adapter = createMppEvmAdapter({ chainId: 84532, asset: USDC, realm: "api.example.com" });
+
+// SELLER, at proposal: challenge.id IS the atrHash; the nonce follows by MPP's rule.
+// `propose` returns an Outcome — a refusal is a RETURNED VALUE, never a thrown exception, which is this
+// family's central contract. Narrow before reading; destructuring `.value` straight off the union is the
+// one handling of this type that does not compile.
+const proposed = await adapter.propose(atrHash);
+if ("refused" in proposed) throw new Error(proposed.detail); // or route on proposed.code
+const binding = proposed.value;                     // { challengeId, realm, nonce }
+
+// AUDITOR, after settlement: bring the atrHash, the chain confirms it.
+await adapter.verifyCandidate(atrHash, { chainId: 84532, txHash }, ports);
+```
+
+## Specification provenance — verified against the live host, 2026-07-30
+
+Read against the host protocol's own live specifications, not LCP's Appendix C.
+
+**EVM charge method — `draft-evm-charge-00` (paymentauth.org, read 2026-07-30).**
+
+1. **§5.3.1 — the derivation.** `nonce = keccak256(abi.encodePacked(challenge.id, challenge.realm))`, with
+   "This specification requires the nonce to be set to the `challengeHash`" and "This provides cryptographic
+   challenge binding equivalent to the Permit2 witness mechanism." The nonce is a **derivation, not a slot**.
+2. **§5.2.3 — Permit2 is closed too.** The witness type string is given literally
+   (`PaymentWitness witness)PaymentWitness(bytes32 challengeHash, string externalId)…`) with
+   "Implementations MUST use the exact type string above when constructing the EIP-712 typed data." There is
+   no room for an LCP field on the Permit2 path either.
+3. **§4.2 / Table 2 — `methodDetails` is constrained**, not an open map: `chainId` and `permit2Address`
+   REQUIRED, `credentialTypes`, `decimals` and `splits` OPTIONAL, and the document states no allowance for
+   arbitrary keys. This is why the EVM method gets a *binding* and the open-map placement lives in
+   `placement-mpp` instead.
+4. **§8 — replay protection is the token's.** "The nonce is consumed on-chain by the token contract itself";
+   a consumed nonce cannot be reused. Our binding adds no replay machinery and must not appear to.
+
+**Core scheme — the `Payment` HTTP authentication scheme (read 2026-07-30).**
+
+5. **§5.1.1 — `id` is required to be unique** ("Unique challenge identifier. Servers MUST bind this value to
+   the challenge parameters… Clients MUST include this value unchanged in the credential"), and `realm` is a
+   MUST ("Protection space identifier per [RFC9110]"). The uniqueness requirement is satisfied the way
+   LCP §8.3.5 prescribes: each ATR is unique per transaction, so each `challenge.id` is too.
+6. **§5.1.1 — `id` has no declared format.** Its examples are opaque strings (`"aB3cDeF4gHiJkLmN"`), so an
+   `0x`-prefixed 32-byte atrHash is a conformant id. Nothing about Id-Reuse asks MPP to accommodate us.
+7. **§5.1.2.1.1 Table 2 — the seven-slot canonicalization** is `realm, method, intent, request, expires,
+   digest, opaque`. `id` is *not* a slot; it is bound by the server per §5.1.1 and by the EVM method's
+   derivation, which is what makes the weld hold without touching the canonicalization.
+
+**Two drifts found, recorded rather than smoothed over.**
+
+- **The core draft's identifier.** LCP v1.37 §C.1 and the completion plan both cite
+  `draft-ryan-httpauth-payment-01` (the IETF individual submission). paymentauth.org's own document index
+  publishes the core scheme as **`draft-httpauth-payment-00.html`**. Both were read for this gate; they agree
+  on §5.1.1 and on the seven slots. Treat the paymentauth.org copy as the live one — it is the family's own
+  publication point — and the datatracker submission as its IETF mirror.
+- **`challenge.id` uniqueness is a CORE requirement, not an EVM-method one.** `draft-evm-charge-00` states no
+  uniqueness rule of its own; §8's replay protection is the token contract's. An implementer reading only the
+  method spec would not find the constraint that makes Id-Reuse safe.
+
+**Per-method scope.** MPP is a specification *family*, and this gate covers the **EVM** charge method only.
+Tempo's TIP-20 memo is a different and much stronger realization and gets its own package and its own gate.
+
+## Credential-type scope — read this before trusting `recovery.onChain`
+
+MPP's EVM method defines **four** credential types (§5), and the derived `challengeHash` reaches the chain in
+**exactly one** of them. Everything this profile declares is scoped to that one, and both the machine-readable
+declaration and the runtime behaviour say so.
+
+| Credential type | Where the `challengeHash` lives | Readable from a settlement? |
+|---|---|---|
+| **`authorization`** (§5.3) — opt-in, EIP-3009 tokens only | the **on-chain** EIP-3009 nonce (§5.3.1) | **yes** — this binding's whole surface |
+| `permit2` (§5.2) — **RECOMMENDED** | the EIP-712 `PaymentWitness` the client signs (§5.2.3, §10.4) | no — signed, never in calldata or a log |
+| `transaction` (§5.4) | nowhere — no challenge binding (§10.4) | no |
+| `hash` (§5.5) | nowhere — no challenge binding (§10.4) | no |
+
+Two consequences, both deliberate:
+
+- **`weldGrades` is keyed by MPP's own credential-type name** — `{ authorization: "signature" }`, not a coinage
+  like `derived`. The key *is* the scope, machine-readably, and `finality.note` repeats it in prose for a
+  consumer who reads only the published profile JSON. Grading `permit2` would be declaring from the
+  specification rather than from this binding: the package constructs no witness. `transaction` and `hash` have
+  no weld to grade at all.
+- **The adapter enforces the same scope at runtime.** A settlement that moved the configured token but emitted
+  no `AuthorizationUsed` really did settle — under one of the other three types — so `verifyCandidate` and
+  `observe` both refuse `mpp-evm/not-authorization-credential-type` rather than report an absence. Reporting
+  `{ ok: true, value: [] }` there would be a silent wrong answer at a verification boundary. Only when the
+  token did not move either is the honest answer "this transaction settled none of this asset"
+  (`mpp-evm/no-settlement-event` / an empty transition list, reached without reading a block).
+
+**`recovery.onChain: true` is still declared from the specification, not yet from a live settlement.** Two of
+the triple's three members are observable without a chain — `zeroPartyRecoverable: false` because no code path
+maps a settlement to an atrHash (`recover` refuses and takes no arguments), `forwardIndexable: false` because no
+`enumerate` exists — but the on-chain member needs a real `AuthorizationUsed`. `test/integration.onchain.test.ts`
+reads exactly that and is **skipped until `MPP_EVM_SETTLEMENT_TX` names one**. Until it runs, treat that single
+member as owed.
+
+## The weld, and the only check it permits
+
+`verifyCandidate` is the primary surface, and it is a **confirmation**, not a lookup. The on-chain value is
+keccak-256 over the atrHash and the realm, so:
+
+- **`recover` refuses, always**, with `mpp-evm/not-recoverable-by-construction`. It is present because a
+  generic `WeldAdapter` consumer will reach for it and must be told loudly; it is typed `Promise<Refusal>` so
+  the impossibility is visible before the call, and it takes **no arguments** because there is no input a
+  recovery could read.
+- **There is no `enumerate`.** Absence is the declaration, matching `forwardIndexable: false`.
+- **Re-deriving from a stored challenge would be a defect, not a feature.** That is the service's own records
+  re-labelled; it would falsify `zeroPartyRecoverable: false`, and it is the one edit this package must never
+  accept.
+
+### Why `forwardIndexable: false` when the nonce is an indexed topic
+
+§8.3's criterion is enumeration of every settlement bound to **a given `atrHash`**, and §8.3.5 answers it
+directly: "Not forward-indexable by `atrHash` alone — the on-chain value is a hash over `atrHash` and other
+inputs." An auditor who *also* knows the realm can derive the nonce and topic-filter it — but that is
+realm-scoped, and it is degenerate anyway: §8.3.5's uniqueness satisfaction makes each ATR unique per
+transaction, so there is at most one settlement per atrHash to find. Hence `indexing: "none"`.
+
+## Do not reconcile this manifest with `binding-evm-x402`'s
+
+They bind the *same* EIP-3009 nonce field and they legitimately disagree. x402 leaves the nonce unconstrained,
+so the atrHash rides it directly — off-canonical Native Field, zero-party recoverable. MPP-EVM *derives* the
+nonce, so the same field carries a hash of the atrHash — Id-Reuse, confirmation only. `binding-evm-x402`'s
+manifest carries a KNOWN-BAD note about an archived declaration that read MPP's derivation-MUST onto the x402
+path; **this package is where that reading is correct.** Making either manifest resemble the other
+reintroduces the bug.
+
+The same rule holds down to the error messages. `binding-evm-common`'s `assertBytes32` enforces the right 32
+bytes but explains them as the value that will "ride as the EIP-3009 nonce" — true on x402, false here — so
+`bindAtrHash` carries **its own guard**: on this rail the atrHash rides `challenge.id`, and the nonce is derived
+from it, never occupied by it.
+
+## Provenance
+
+Cut against `draft-evm-charge-00` and the core `Payment` scheme at paymentauth.org, gate discharged
+2026-07-30, and reconciled against LCP v1.37 §C.1 and §8.3.5 the same day. The derivation oracles in
+`vectors/binding/mpp-evm-id-reuse.json` were produced by two independent keccak-256 implementations
+(pycryptodome and Foundry `cast keccak`), and `abi.encodePacked`'s string semantics were confirmed against
+Foundry's own encoder — neither of them the implementation under test.
+
+## 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,59 @@
+/**
+ * The MPP-EVM Id-Reuse WeldAdapter — the one member of the ten that differs at the weld.
+ *
+ * - `propose`         — `challenge.id = atrHash`, and the EIP-3009 nonce MPP's derivation then requires.
+ * - `verifyCandidate` — THE PRIMARY VERIFY SURFACE: confirm a KNOWN atrHash against one settlement's
+ *                       on-chain nonce. You bring the hash; the chain confirms it.
+ * - `observe`         — a settlement's `AuthorizationUsed` events → `settled` lifecycle transitions.
+ *
+ * **Both read paths are scoped to MPP's `authorization` credential type, and both say so when they are out of
+ * scope.** Only §5.3 puts the derived `challengeHash` on-chain; the RECOMMENDED `permit2` type signs the same
+ * value into an off-chain EIP-712 witness and `transaction`/`hash` bind no challenge at all. A settlement in
+ * any of those three moves the token and emits no `AuthorizationUsed`, so answering "no transitions" about it
+ * would be a wrong answer, not an absence — see `credential-type.ts` for the specification reading and the
+ * refusal both members return instead.
+ * - `recover`         — REFUSES, always, `mpp-evm/not-recoverable-by-construction`. Present because a
+ *                       generic `WeldAdapter` consumer will reach for it and must be told, loudly, that this
+ *                       rail has no recovery; typed `Promise<Refusal>` so the impossibility is visible before
+ *                       the call. It takes no arguments: there is no input a recovery could read.
+ * - `enumerate`       — ABSENT. The port makes it optional and the manifest declares
+ *                       `forwardIndexable: false`; absence is the declaration.
+ *
+ * **Why `verifyCandidate` and not a `recover` that re-derives.** A stored challenge would let this package
+ * look up an atrHash by settlement and call the answer recovery. That is the service's own records
+ * re-labelled, it would falsify `zeroPartyRecoverable: false`, and it is the single edit this package must
+ * never accept. Verification needs no such store: the auditor supplies the candidate.
+ *
+ * viem appears here only through the `Log[]` the injected `ChainReader` hands back and the shared
+ * `AuthorizationUsed` decoder in `binding-evm-common` — the same seam `binding-evm-x402` uses, so the event
+ * ABI is known in exactly one place.
+ */
+import type { BindingManifest, Outcome, Refusal, SettlementRef, VerifierPorts, WeldAdapter } from "@integraledger/lcp-binding-core";
+import { type MppEvmCandidateConfirmation, type MppEvmChallengeBinding } from "./id-reuse.js";
+/** One chain + token + protection space this adapter binds. */
+export interface MppEvmAdapterConfig {
+    chainId: number;
+    /** The payment token — the `AuthorizationUsed` emitter whose nonce carries the derivation. */
+    asset: `0x${string}`;
+    /**
+     * `challenge.realm`, MPP's protection space. Not optional and not inferable: it is half the nonce
+     * preimage, so an adapter without it cannot derive or confirm anything.
+     */
+    realm: string;
+}
+/**
+ * The MPP-EVM surface. It IS a `WeldAdapter` on the EVM-shaped port — the rail is EVM and the types fit —
+ * with two members narrowed to say what this rail can and cannot do, and `enumerate` left off.
+ */
+export interface MppEvmAdapter extends WeldAdapter {
+    readonly manifest: BindingManifest;
+    /** `ctx` is accepted for port compatibility and unused: the realm lives in the adapter config. */
+    propose(atrHash: `0x${string}`, ctx?: unknown): Promise<Outcome<MppEvmChallengeBinding>>;
+    /** Confirm a candidate atrHash against ONE settlement's on-chain nonce. */
+    verifyCandidate(atrHash: string, ref: SettlementRef, ports: VerifierPorts): Promise<Outcome<MppEvmCandidateConfirmation>>;
+    /** Always a refusal — see the module docblock. */
+    recover(): Promise<Refusal>;
+}
+/** Construct the MPP-EVM adapter for one chain, token and realm. */
+export declare function createMppEvmAdapter(config: MppEvmAdapterConfig): MppEvmAdapter;
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EACV,eAAe,EAEf,OAAO,EACP,OAAO,EACP,aAAa,EACb,aAAa,EACb,WAAW,EACZ,MAAM,iCAAiC,CAAC;AAQzC,OAAO,EAGL,KAAK,2BAA2B,EAChC,KAAK,sBAAsB,EAE5B,MAAM,eAAe,CAAC;AAGvB,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;IACrB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,kGAAkG;IAClG,OAAO,CACL,OAAO,EAAE,KAAK,MAAM,EAAE,EACtB,GAAG,CAAC,EAAE,OAAO,GACZ,OAAO,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAC,CAAC;IAC5C,2EAA2E;IAC3E,eAAe,CACb,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAAC,CAAC;IACjD,kDAAkD;IAClD,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7B;AAED,oEAAoE;AACpE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,mBAAmB,GAC1B,aAAa,CAoGf"}

package/dist/adapter.js

@@ -0,0 +1,76 @@
+import { assetWasTransferred, readAuthorizationUsed, refOf, } from "@integraledger/lcp-binding-evm-common";
+import { notAuthorizationCredentialType } from "./credential-type.js";
+import { bindAtrHash, checkCandidate, notRecoverableByConstruction, } from "./id-reuse.js";
+import { MPP_EVM_MANIFEST } from "./manifest.js";
+/** Construct the MPP-EVM adapter for one chain, token and realm. */
+export function createMppEvmAdapter(config) {
+    if (config.realm === "")
+        throw new Error("MppEvmAdapterConfig.realm must be non-empty — challenge.realm is half the EIP-3009 nonce preimage (draft-evm-charge-00 §5.3.1)");
+    /**
+     * One settlement's logs, and the `AuthorizationUsed` events the configured token emitted among them.
+     *
+     * The raw logs travel alongside the decoded events because an EMPTY event set is ambiguous on this rail:
+     * only the logs distinguish "this transaction moved none of the asset" from "it settled under a credential
+     * type whose challengeHash is not on-chain". Both read members need that distinction, so both read it here.
+     */
+    async function settlement(ref, ports) {
+        const logs = (await ports.chain.getTransactionLogs(ref));
+        return { logs, events: readAuthorizationUsed(logs, config.asset) };
+    }
+    return {
+        manifest: MPP_EVM_MANIFEST,
+        async propose(atrHash) {
+            // bindAtrHash throws (fail-fast) on a malformed atrHash — a seller-side wiring defect, not a policy
+            // outcome. There is no value-level refusal on this path: MPP constrains nothing we are choosing here.
+            return { ok: true, value: bindAtrHash(atrHash, config.realm) };
+        },
+        async verifyCandidate(atrHash, ref, ports) {
+            const { logs, events } = await settlement(ref, ports);
+            // Out of scope BEFORE out of luck: a settlement that moved the token under any of MPP's other three
+            // credential types is answered by naming that type, never by the pinned-index or absence refusals below.
+            if (events.length === 0 && assetWasTransferred(logs, config.asset))
+                return notAuthorizationCredentialType(config.asset);
+            // An empty set reaches checkCandidate, which owns the `no-settlement-event` refusal — one place, so a
+            // caller holding nonces from its own indexer gets the identical answer.
+            if (ref.logIndex === undefined || events.length === 0)
+                return checkCandidate(atrHash, config.realm, events.map((e) => e.nonce));
+            // A pinned logIndex that matches NO event is a failure, never a silent fall back to another event in
+            // the same transaction — that could confirm a candidate against a different settlement leg.
+            const pinned = events.filter((e) => e.logIndex === ref.logIndex);
+            if (pinned.length === 0)
+                return {
+                    refused: true,
+                    haltClass: "verification-failure",
+                    code: "mpp-evm/log-index-not-found",
+                    detail: `no AuthorizationUsed at logIndex ${ref.logIndex} for asset ${config.asset}`,
+                };
+            return checkCandidate(atrHash, config.realm, pinned.map((e) => e.nonce));
+        },
+        async observe(ref, ports) {
+            const { logs, events } = await settlement(ref, ports);
+            // Settlement is the only on-chain state MPP-EVM exposes; `proposed` is off-chain and pre-settlement.
+            if (events.length === 0) {
+                // The token moved and no authorization accompanied it: the transaction DID settle, under a credential
+                // type this binding cannot read. An empty transition list would assert the opposite.
+                if (assetWasTransferred(logs, config.asset))
+                    return notAuthorizationCredentialType(config.asset);
+                // The token did not move either, so there is no settlement of this asset to report — an answer, not
+                // a refusal, and one reached without reading a block.
+                return { ok: true, value: [] };
+            }
+            const at = await ports.chain.blockTime(ref);
+            return {
+                ok: true,
+                value: events.map((e) => ({
+                    state: "settled",
+                    at,
+                    ref: refOf(ref.chainId, ref.txHash, e.logIndex),
+                })),
+            };
+        },
+        async recover() {
+            return notRecoverableByConstruction();
+        },
+    };
+}
+//# 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/credential-type.d.ts

@@ -0,0 +1,42 @@
+/**
+ * MPP's EVM method offers FOUR credential types, and this binding can read exactly one of them off a chain.
+ * That asymmetry is what this module exists to say out loud, because the alternative is a wrong answer.
+ *
+ * `draft-evm-charge-00` (paymentauth.org, read 2026-07-30), §5:
+ *
+ * - **§5.3 `authorization`** — the client signs an EIP-3009 `transferWithAuthorization` message whose `nonce`
+ *   §5.3.1 REQUIRES to be the `challengeHash`. The derived value is therefore *on-chain*: the token emits
+ *   `AuthorizationUsed(authorizer, indexed nonce)` and §8 consumes it ("The nonce is consumed on-chain by the
+ *   token contract itself"). **This is the only credential type this binding can confirm against.**
+ * - **§5.2 `permit2`** — the RECOMMENDED type (§5.2: "The RECOMMENDED credential type"). It carries the SAME
+ *   `challengeHash`, but inside the EIP-712 `PaymentWitness` struct the client signs; §10.4 places it "in the
+ *   EIP-712 witness data (Permit2)". It never reaches calldata or a log, so a verifier holding only the
+ *   transaction cannot read it. Settlement goes through Permit2's `permitWitnessTransferFrom`, which moves the
+ *   token — an ERC-20 `Transfer` and no `AuthorizationUsed`.
+ * - **§5.4 `transaction`** and **§5.5 `hash`** — plain ERC-20 transfers with no challenge binding at all;
+ *   §10.4 says they "provide weaker challenge binding than Permit2 credentials" and that the server "cannot
+ *   prove the payment was created for a specific challenge instance". Again a `Transfer`, no `AuthorizationUsed`.
+ *
+ * **So the absence of `AuthorizationUsed` has two possible meanings, and they are not the same answer.** If
+ * the configured token did not move either, the transaction settled none of this asset — a true and useful
+ * report. If the token DID move, the transaction settled and this binding simply cannot read its credential
+ * binding; reporting that as an absence would be a silent wrong answer at a verification boundary. Hence the
+ * refusal below, which names the credential type rather than the missing event.
+ *
+ * The `did the asset move` predicate itself is NOT here — it is `assetWasTransferred` in
+ * `binding-evm-common`, because binding-evm-x402 asks the identical question about its own unreadable path
+ * (the Permit2 fallback) and two copies of one predicate is how the two rails drift apart. What stays here
+ * is the part that is genuinely MPP's: which of MPP's four credential types the caller is looking at, and
+ * the refusal that says so.
+ */
+import type { Refusal } from "@integraledger/lcp-binding-core";
+/**
+ * The refusal for a settlement this binding cannot read: the token moved, and no EIP-3009 authorization
+ * accompanied it.
+ *
+ * Stated as a refusal rather than a throw because it is a fact about data under audit, not a wiring defect —
+ * a seller choosing MPP's RECOMMENDED credential type has done nothing wrong, and the verifier needs to be
+ * told which of MPP's four modes it is looking at, not handed an exception.
+ */
+export declare function notAuthorizationCredentialType(asset: string): Refusal;
+//# sourceMappingURL=credential-type.d.ts.map

package/dist/credential-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-type.d.ts","sourceRoot":"","sources":["../src/credential-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAE/D;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOrE"}

package/dist/credential-type.js

@@ -0,0 +1,17 @@
+/**
+ * The refusal for a settlement this binding cannot read: the token moved, and no EIP-3009 authorization
+ * accompanied it.
+ *
+ * Stated as a refusal rather than a throw because it is a fact about data under audit, not a wiring defect —
+ * a seller choosing MPP's RECOMMENDED credential type has done nothing wrong, and the verifier needs to be
+ * told which of MPP's four modes it is looking at, not handed an exception.
+ */
+export function notAuthorizationCredentialType(asset) {
+    return {
+        refused: true,
+        haltClass: "verification-failure",
+        code: "mpp-evm/not-authorization-credential-type",
+        detail: `token ${asset} was transferred by this settlement but it emitted no EIP-3009 AuthorizationUsed — MPP's permit2 (§5.2, the RECOMMENDED type), transaction (§5.4) and hash (§5.5) credential types keep the challengeHash off-chain or bind no challenge at all, and only the opt-in authorization type (§5.3) puts it in the on-chain nonce, so this settlement carries no on-chain value a candidate atrHash could be confirmed against`,
+    };
+}
+//# sourceMappingURL=credential-type.js.map