@integraledger/lcp-binding-evm-mpp 0.9.0

package/src/adapter.ts

@@ -0,0 +1,192 @@
+/**
+ * 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,
+  LifecycleTransition,
+  Outcome,
+  Refusal,
+  SettlementRef,
+  VerifierPorts,
+  WeldAdapter,
+} from "@integraledger/lcp-binding-core";
+import {
+  assetWasTransferred,
+  readAuthorizationUsed,
+  refOf,
+} from "@integraledger/lcp-binding-evm-common";
+import type { Log } from "viem";
+import { notAuthorizationCredentialType } from "./credential-type.js";
+import {
+  bindAtrHash,
+  checkCandidate,
+  type MppEvmCandidateConfirmation,
+  type MppEvmChallengeBinding,
+  notRecoverableByConstruction,
+} from "./id-reuse.js";
+import { MPP_EVM_MANIFEST } from "./manifest.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 function createMppEvmAdapter(
+  config: MppEvmAdapterConfig,
+): MppEvmAdapter {
+  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: SettlementRef,
+    ports: VerifierPorts,
+  ): Promise<{
+    logs: Log[];
+    events: { nonce: `0x${string}`; logIndex: number | null }[];
+  }> {
+    const logs = (await ports.chain.getTransactionLogs(ref)) as Log[];
+    return { logs, events: readAuthorizationUsed(logs, config.asset) };
+  }
+
+  return {
+    manifest: MPP_EVM_MANIFEST,
+
+    async propose(
+      atrHash: `0x${string}`,
+    ): Promise<Outcome<MppEvmChallengeBinding>> {
+      // 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: string,
+      ref: SettlementRef,
+      ports: VerifierPorts,
+    ): Promise<Outcome<MppEvmCandidateConfirmation>> {
+      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: SettlementRef,
+      ports: VerifierPorts,
+    ): Promise<Outcome<LifecycleTransition[]>> {
+      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(): Promise<Refusal> {
+      return notRecoverableByConstruction();
+    },
+  };
+}

package/src/credential-type.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 function notAuthorizationCredentialType(asset: string): Refusal {
+  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`,
+  };
+}

package/src/id-reuse.ts

@@ -0,0 +1,210 @@
+/**
+ * MPP-EVM Id-Reuse (LCP §8.3.5): the host's derivation rule, the weld it produces, and the *only* kind of
+ * check the resulting on-chain value permits.
+ *
+ * **THE HOST RULE, quoted.** `draft-evm-charge-00` §5.3.1 (paymentauth.org, read 2026-07-30):
+ *
+ *     nonce = keccak256(abi.encodePacked(challenge.id, challenge.realm))
+ *
+ * — with the accompanying sentence "This specification requires the nonce to be set to the `challengeHash`".
+ * The nonce is therefore a *derivation*, not a slot: there is nothing here for LCP to occupy. What LCP does
+ * instead is supply an input — the seller sets `challenge.id = atrHash` — so the host's own required
+ * derivation carries the record into the settlement transaction.
+ *
+ * **WHAT MAKES THAT SOUND IS NOT UNIQUENESS, AND AN EARLIER DOCBLOCK SAID IT WAS.** It argued that MPP's
+ * "Unique challenge identifier" requirement (`draft-httpauth-payment` §5.1.1) was satisfied by making each
+ * ATR unique per transaction. Every citation in it was exact; the sufficiency was not. LCP v1.38 §C.1
+ * (:1282-1289):
+ *
+ * > **It is not simply available, and §8.3.5's uniqueness advice is not sufficient for it.** MPP requires
+ * > the server to bind the challenge `id` *to the challenge parameters* … expressly to prevent a client
+ * > altering the challenge it presents. **Making each ATR unique per transaction satisfies uniqueness but
+ * > not that binding.** A per-transaction ATR that itself states the transaction parameters (Section 6.1)
+ * > satisfies both, because the parameters are then inside the hashed document; a terms document made
+ * > unique by a timestamp alone does not.
+ *
+ * **THE REQUIREMENT IS ON THE ATR, AND THE TREE ALREADY VERIFIES IT.** This binding holds a hash, never the
+ * document, so it cannot inspect what the ATR says — and it should not: where the ATR lives is the seller's
+ * and buyer's business, and a rail binding that needed the document would assert a custody LCP does not
+ * require. The property §C.1 asks for is **OFR**: the ATR's offer slot is bound, meaning the transaction
+ * parameters are inside the hashed document. `verify` implements it as `offerBoundStep`
+ * (`verify/src/composition.ts`) and requires it at **TC-4** (`verify/src/required.ts`). So a record whose
+ * class is TC-4 has had this checked by the layer that holds the document; a record below TC-4 has not, and
+ * the §8.3.5 discharge on this rail is only as good as that rung.
+ *
+ * The host is internally inconsistent here and the split is kept visible deliberately: the core draft
+ * states the challenge-parameter binding as a **MUST** in the `id` field description and as a **SHOULD** in
+ * its challenge-binding section. §C.1 names that inconsistency rather than resolving it, and so does this.
+ *
+ * **Zero-party-recoverable on-chain binding on this rail still requires an Overlay Contract per §8.3.2**
+ * (§C.1:1289). Nothing here recovers an atrHash, and nothing may be added that does — see the closing note.
+ *
+ * **`abi.encodePacked` over two strings is raw UTF-8 concatenation** — no length prefix, no padding. That was
+ * confirmed against Foundry's own encoder rather than assumed, and every oracle in
+ * `vectors/binding/mpp-evm-id-reuse.json` was produced by two independent keccak-256 implementations,
+ * neither of them the one used here.
+ *
+ * **The atrHash's SPELLING is part of the preimage.** The derivation hashes the id *as a string*, so
+ * `0x7f83…` and `7f83…` are different challenge ids with different nonces. This module therefore canonicalizes
+ * to LCP's own spelling — lowercase, `0x`-prefixed, 32 bytes — before deriving OR comparing, on both the
+ * candidate and the observed nonce. An uppercase-hex spelling of the same bytes is a legal input that reaches
+ * the same nonce, not a second wire convention: it is normalized, and the vectors pin that both ways round.
+ * What is REJECTED is a value that is not 32 hex bytes at all — a missing `0x`, a wrong length, a non-hex
+ * digit. Those are different challenge ids rather than spellings of this one, and there is no canonical form
+ * to map them to.
+ *
+ * **Packed concatenation is undelimited, and the fixed length is what makes that safe.** `('ab','c')` and
+ * `('a','bc')` pack identically; the vectors pin that as an observed property of the host rule. It is
+ * unreachable for this binding because `challenge.id` is always exactly 66 characters, so no other split of
+ * the preimage produces a legal id. The length check below is therefore load-bearing, not defensive noise.
+ *
+ * **NOTHING HERE RECOVERS AN atrHash, and no future edit may add such a path.** keccak-256 has no inverse:
+ * the honest surface is confirmation of a candidate the auditor already holds. Re-deriving from a stored
+ * challenge would be service-record recovery wearing the name of zero-party recovery, and would falsify
+ * `zeroPartyRecoverable: false` in the manifest.
+ */
+
+import type { Outcome, Refusal } from "@integraledger/lcp-binding-core";
+import { canonicalAtrHash } from "@integraledger/lcp-kernel";
+import { concat, type Hex, keccak256, stringToBytes } from "viem";
+
+/** A 32-byte value in the canonical lowercase-`0x` spelling this binding hashes and compares. */
+const BYTES32 = /^0x[0-9a-fA-F]{64}$/;
+
+/** The challenge the seller emits, and the nonce the buyer's authorization will therefore carry. */
+export interface MppEvmChallengeBinding {
+  /** `challenge.id` — the atrHash itself, in LCP's canonical lowercase `0x` spelling. */
+  readonly challengeId: Hex;
+  /** `challenge.realm` — MPP's protection space, the second half of the preimage. */
+  readonly realm: string;
+  /** The EIP-3009 nonce `keccak256(abi.encodePacked(id, realm))` requires. DERIVED, never chosen. */
+  readonly nonce: Hex;
+}
+
+/** A candidate atrHash confirmed against a settlement's on-chain nonce. Confirmation, never recovery. */
+export interface MppEvmCandidateConfirmation {
+  readonly confirmed: true;
+  /** The candidate that reproduced the on-chain nonce, canonicalized. */
+  readonly atrHash: Hex;
+  /** The protection space the derivation was performed under — the confirmation is scoped to it. */
+  readonly realm: string;
+  /** The on-chain nonce the candidate reproduced. */
+  readonly nonce: Hex;
+}
+
+/**
+ * MPP's derivation, exactly as its EVM method specifies it: `keccak256(abi.encodePacked(id, realm))`.
+ *
+ * Total over any two non-empty strings, because it implements MPP's rule and not an LCP-specific one — an
+ * ordinary opaque challenge id derives here too, which is what makes this the host's function rather than
+ * ours. THROWS on an empty id or realm: MPP requires both on every challenge (`realm` is a MUST per
+ * §5.1.1), so an empty one is a wiring defect in the caller, not a value to hash.
+ */
+export function deriveChallengeHash(challengeId: string, realm: string): Hex {
+  if (challengeId === "")
+    throw new Error(
+      "MPP challenge id must be non-empty — it is half the nonce preimage",
+    );
+  if (realm === "")
+    throw new Error(
+      "MPP realm must be non-empty — the core scheme makes realm a MUST on every challenge, and it is half the nonce preimage",
+    );
+  return keccak256(concat([stringToBytes(challengeId), stringToBytes(realm)]));
+}
+
+/**
+ * The Id-Reuse weld at PROPOSAL time: `challenge.id = atrHash`, and the nonce that follows from it.
+ *
+ * THROWS on a malformed atrHash, via `canonicalAtrHash` — a seller welding a hash that is not 32 bytes is a
+ * wiring defect, and the guard is also what keeps the fixed-length argument above true of the code.
+ *
+ * **Do not reach for `binding-evm-common`'s `assertBytes32` here.** It enforces the same 32 bytes but
+ * explains them as the value that will "ride as the EIP-3009 nonce" — true on x402, false on this rail, and
+ * precisely the cross-rail misreading `binding-evm-x402`'s KNOWN-BAD note exists to stop. On MPP-EVM the
+ * atrHash rides `challenge.id` and the nonce is DERIVED from it, never occupied by it. `canonicalAtrHash`
+ * states the shape requirement and nothing about where the value rides, which is why it is the right guard:
+ * the rail-specific reasoning belongs in this docblock and in the manifest, not in an error string.
+ */
+export function bindAtrHash(
+  atrHash: string,
+  realm: string,
+): MppEvmChallengeBinding {
+  const challengeId = canonicalAtrHash(
+    atrHash,
+    "bindAtrHash",
+    "on this rail it rides challenge.id and the EIP-3009 nonce is DERIVED from it (draft-evm-charge-00 §5.3.1), never occupied by it",
+  ) as Hex;
+  return { challengeId, realm, nonce: deriveChallengeHash(challengeId, realm) };
+}
+
+/**
+ * Confirm a candidate atrHash against the `AuthorizationUsed` nonces ONE settlement emitted.
+ *
+ * The auditor brings the atrHash (from the record, or from `legal-context.json`); the chain confirms it.
+ * Refusals rather than throws, because both the candidate and the observed nonces are data under audit —
+ * the realm is not: it is the verifier's own configuration, so an empty one throws.
+ *
+ * Every observed nonce is validated BEFORE any is matched: a malformed entry refuses loudly instead of being
+ * skipped past, because silently narrowing a settlement view could turn "this transaction is not what you
+ * think" into "no match found".
+ */
+export function checkCandidate(
+  atrHash: string,
+  realm: string,
+  observedNonces: readonly string[],
+): Outcome<MppEvmCandidateConfirmation> {
+  if (!BYTES32.test(atrHash))
+    return {
+      refused: true,
+      haltClass: "verification-failure",
+      code: "mpp-evm/candidate-malformed",
+      detail: `a candidate atrHash must be a 0x-prefixed 32-byte value to be a legal MPP challenge id, got "${atrHash}"`,
+    };
+  for (const observed of observedNonces)
+    if (!BYTES32.test(observed))
+      return {
+        refused: true,
+        haltClass: "verification-failure",
+        code: "mpp-evm/nonce-malformed",
+        detail: `an observed EIP-3009 nonce must be a 0x-prefixed 32-byte value, got "${observed}"`,
+      };
+  if (observedNonces.length === 0)
+    return {
+      refused: true,
+      haltClass: "verification-failure",
+      code: "mpp-evm/no-settlement-event",
+      detail:
+        "no EIP-3009 AuthorizationUsed nonce was observed for this settlement — there is nothing to verify against",
+    };
+  const candidate = canonicalAtrHash(atrHash, "checkCandidate") as Hex;
+  const nonce = deriveChallengeHash(candidate, realm);
+  const matched = observedNonces.find((o) => o.toLowerCase() === nonce);
+  if (matched === undefined)
+    return {
+      refused: true,
+      haltClass: "verification-failure",
+      code: "mpp-evm/candidate-mismatch",
+      detail: `no observed nonce equals keccak256(packed("${candidate}", "${realm}")) = ${nonce}`,
+    };
+  return {
+    ok: true,
+    value: { confirmed: true, atrHash: candidate, realm, nonce },
+  };
+}
+
+/**
+ * The refusal recovery always returns, stated in one place so the reason travels with the code.
+ *
+ * Not a "not implemented yet" and not a gap to be filled: the on-chain value is a hash over the atrHash, so
+ * there is no function from settlement to atrHash to write. A caller wanting the record must bring the
+ * candidate and use `verifyCandidate`.
+ */
+export function notRecoverableByConstruction(): Refusal {
+  return {
+    refused: true,
+    haltClass: "verification-failure",
+    code: "mpp-evm/not-recoverable-by-construction",
+    detail:
+      "MPP-EVM is an Id-Reuse binding (LCP §8.3.5): the on-chain EIP-3009 nonce is keccak256 over the atrHash and the realm, so no atrHash can be recovered from a settlement — bring the candidate atrHash and use verifyCandidate",
+  };
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export {
+  createMppEvmAdapter,
+  type MppEvmAdapter,
+  type MppEvmAdapterConfig,
+} from "./adapter.js";
+// `assetWasTransferred` and `ERC20_TRANSFER_TOPIC0` moved to `@integraledger/lcp-binding-evm-common` when
+// binding-evm-x402 needed the same predicate. They are NOT re-exported from here: a symbol with two homes
+// is how the two copies drift, which is the thing the move was for.
+export { notAuthorizationCredentialType } from "./credential-type.js";
+export {
+  bindAtrHash,
+  checkCandidate,
+  deriveChallengeHash,
+  type MppEvmCandidateConfirmation,
+  type MppEvmChallengeBinding,
+  notRecoverableByConstruction,
+} from "./id-reuse.js";
+export { MPP_EVM_MANIFEST } from "./manifest.js";

package/src/manifest.ts

@@ -0,0 +1,84 @@
+import type { BindingManifest } from "@integraledger/lcp-binding-core";
+
+/**
+ * The MPP-EVM Id-Reuse binding manifest (published as `mpp-evm-derived-v1`).
+ *
+ * **pattern = "id-reuse"** (LCP §8.3.5), and this is the one member of the family that differs *at the
+ * weld*. On MPP's EVM charge method the EIP-3009 nonce is not ours to occupy: `draft-evm-charge-00` §5.3.1
+ * REQUIRES `nonce = keccak256(abi.encodePacked(challenge.id, challenge.realm))`, and §5.2.3 fixes the
+ * Permit2 witness type string with a MUST ("Implementations MUST use the exact type string above"). There is
+ * no free field on this path. What remains available is Id-Reuse: the seller sets `challenge.id = atrHash`,
+ * so the host's own derivation carries the record into the settlement transaction.
+ *
+ * **Do NOT reconcile this manifest against `binding-evm-x402`'s.** That package's docblock records an
+ * archived declaration marked KNOWN-BAD for reading MPP-EVM's derivation-MUST onto the x402 path, where no
+ * derivation exists. This is where that reading is correct, and the two manifests legitimately differ: x402
+ * is off-canonical Native Field on the same nonce field, MPP-EVM is Id-Reuse over a derivation. "Fixing" one
+ * to look like the other reintroduces the bug the archive comment exists to stop.
+ *
+ * **`nativeField` is absent, and its absence is substantive** — not merely the schema's `iff`. Nothing of
+ * ours occupies a protocol field here; the atrHash rides an identifier the host protocol already requires.
+ *
+ * **SCOPE — this manifest declares ONE of MPP's four credential types, and the scope is load-bearing.**
+ * `draft-evm-charge-00` defines four ways a client may present payment, and the derived `challengeHash`
+ * reaches the chain in exactly one of them:
+ * - **§5.3 `authorization`** — the derived value IS the EIP-3009 nonce, so it is committed on-chain. Opt-in
+ *   and token-conditional: §4.2.2 "Servers MUST only include `"authorization"` when the `currency` token is
+ *   known to implement EIP-3009", and §5.3.2 the same rule as a prohibition ("Servers MUST NOT advertise
+ *   `"authorization"` in `credentialTypes` unless the `currency` token is known to implement EIP-3009").
+ *   **This is the credential type this binding covers, and the only one it can.**
+ * - **§5.2 `permit2`** — "The RECOMMENDED credential type", and it carries the SAME derived `challengeHash`
+ *   inside the EIP-712 `PaymentWitness` struct, which the client signs but which never appears in calldata or
+ *   an event log; §10.4 places it "in the EIP-712 witness data (Permit2)". Signature-committed, off-chain,
+ *   unreadable from a settlement.
+ * - **§5.4 `transaction`** and **§5.5 `hash`** — plain ERC-20 transfers. No challengeHash anywhere; §10.4
+ *   says so outright ("weaker challenge binding than Permit2 credentials").
+ *
+ * So `weldGrades` is keyed by MPP's own credential-type name rather than by a coinage like `derived`: the key
+ * IS the scope, machine-readably, and `finality.note` repeats it in prose for whoever reads only the published
+ * profile JSON. A grade for `permit2` would be declared from the specification rather than from this binding —
+ * the package constructs no witness — and `transaction`/`hash` have no weld to grade. Generalizing the
+ * strongest leg to the whole rail is the failure this scoping exists to prevent, and the adapter enforces the
+ * same scope at runtime: a settlement that moved the token without an `AuthorizationUsed` beside it is refused
+ * by credential type, never reported as an absence of settlement.
+ *
+ * **The WLD-3 triple, under that scope:**
+ * - `onChain: true` — the derived value is the EIP-3009 nonce, emitted as an indexed topic of
+ *   `AuthorizationUsed(address indexed authorizer, bytes32 indexed nonce)` and consumed on-chain by the
+ *   token contract (§8: "The nonce is consumed on-chain by the token contract itself"). **Read from the host
+ *   specification and from the adapter's own behaviour on synthetic logs; NOT yet from a live MPP-EVM
+ *   settlement** — the repository's opt-in on-chain integration suite discharges that against a real transaction, and until
+ *   it runs, this member is the one still owed a live proof.
+ * - `zeroPartyRecoverable: false` — keccak-256 has no inverse. An auditor holding only the transaction hash
+ *   reads the nonce and cannot obtain the atrHash from it. Verification of a *candidate* is the whole of
+ *   what this rail offers, which is why the adapter exposes `verifyCandidate` and why `recover` refuses.
+ *   Observed of the code: no member maps a settlement to an atrHash, and `recover` takes no arguments.
+ * - `forwardIndexable: false` — §8.3's criterion is enumeration "bound to a given `atrHash`", and §8.3.5
+ *   states it directly: "Not forward-indexable by `atrHash` alone — the on-chain value is a hash over
+ *   `atrHash` and other inputs." Knowing the realm as well, one *could* derive the nonce and topic-filter it,
+ *   but that is realm-scoped, and it is degenerate besides: §8.3.5's uniqueness satisfaction makes each ATR
+ *   unique per transaction, so there is at most one settlement per atrHash to enumerate. Hence `indexing:
+ *   "none"` and no `enumerate` member. Observed of the code: no `enumerate` exists to call.
+ *
+ * `weldGrades.authorization = "signature"`: the payer's EIP-3009 typed-data message covers the `nonce` field,
+ * so the buyer's signature — not merely an inclusion in a transaction — commits the derived value.
+ */
+export const MPP_EVM_MANIFEST: BindingManifest = {
+  rail: "evm:mpp",
+  protocol: "mpp",
+  pattern: "id-reuse",
+  recovery: {
+    onChain: true,
+    zeroPartyRecoverable: false,
+    forwardIndexable: false,
+  },
+  assetBinding: "filtered", // candidate verification filters the configured token's own log (AuthorizationUsed / assetWasTransferred)
+  successGate: "structural", // a reverted tx emits no logs, so the weld event cannot exist
+  indexing: "none",
+  finality: {
+    reversible: false,
+    note: "scoped to MPP's `authorization` credential type (§5.3), the only one of the four whose challengeHash reaches the chain — under the RECOMMENDED `permit2` type (§5.2) the same derived value is signature-committed in an off-chain EIP-712 witness, and `transaction`/`hash` (§5.4/§5.5) bind no challenge at all. Within that scope: final on settlement — the EIP-3009 authorization is consumed on-chain and there is no on-rail reversal; the weld is derivation-bound (nonce = keccak256(abi.encodePacked(challenge.id, challenge.realm)), draft-evm-charge-00 §5.3.1), so a candidate atrHash is VERIFIED against the on-chain nonce and never recovered from it; recourse is the record's elected forum (PAY-3/RCS-5), never dispute resolution. The §8.3.5 discharge rests on the ATR STATING the transaction parameters (LCP §6.1), not on ATR uniqueness: MPP binds the challenge id to the challenge parameters, and uniqueness alone does not satisfy that (§C.1). The tree checks it as OFR — `offerBoundStep`, required at TC-4 — so this weld is only as strong as the record's class. Zero-party-recoverable on-chain binding on this rail still requires an Overlay Contract per §8.3.2",
+  },
+  weldGrades: { authorization: "signature" },
+  lifecycleStates: ["proposed", "settled"],
+};