@integraledger/lcp-binding-evm-x402 0.9.0

package/src/asset-transfer-method-filter.ts

@@ -0,0 +1,146 @@
+/**
+ * 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";
+import { atrHashEquals } from "@integraledger/lcp-kernel";
+
+/** The x402 asset-transfer method an offer may request. Only `eip3009` carries the payer nonce. */
+export 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 const X402_TRANSFER_METHODS: readonly string[] = [
+  "eip3009",
+  "permit2",
+  "erc7710",
+];
+
+/**
+ * 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 function filterAssetTransferMethod(
+  assetTransferMethod: string | undefined,
+): Refusal | null {
+  if (
+    assetTransferMethod === undefined ||
+    assetTransferMethod === EIP3009_TRANSFER_METHOD
+  )
+    return null;
+  const known = X402_TRANSFER_METHODS.includes(assetTransferMethod);
+  return {
+    refused: true,
+    haltClass: "policy-rejection",
+    code: "x402/asset-transfer-method-unsupported",
+    detail: `the atrHash weld requires the eip3009 asset-transfer method, whose payer-controlled nonce carries it; got "${assetTransferMethod}"${
+      known
+        ? " — a method x402 defines, but one that exposes no 32-byte payer field for the weld"
+        : " — not a method x402's exact-EVM scheme defines (eip3009, permit2, erc7710)"
+    }. Refusing rather than settling unwelded.`,
+  };
+}
+
+/** The x402 payment flows, §6.1. `authorization` is the default when `extra.paymentFlow` is omitted. */
+export const X402_PAYMENT_FLOWS: readonly string[] = [
+  "authorization",
+  "upfront",
+  "escrow",
+];
+
+/**
+ * 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 function filterPaymentFlow(
+  paymentFlow: string | undefined,
+): Refusal | null {
+  if (paymentFlow === undefined || paymentFlow === "authorization") return null;
+  if (paymentFlow === "upfront") return null;
+  const known = X402_PAYMENT_FLOWS.includes(paymentFlow);
+  return {
+    refused: true,
+    haltClass: "policy-rejection",
+    code: known
+      ? "x402/weld-not-carried-by-this-binding"
+      : "x402/payment-flow-unrecognized",
+    detail: known
+      ? `the escrow payment flow settles twice (settle -> resource -> settle) and x402 marks eip3009 "One-time use", so this binding's nonce can carry only one of the two. Use @integraledger/lcp-binding-evm-escrow for a two-phase settlement: it welds PaymentInfo.salt, which is recoverable from BOTH the authorization and the capture artifact and joins them on paymentInfoHash. Which settlement shape you use is your choice; this is about which binding carries the record across it.`
+      : `unrecognized x402 paymentFlow "${paymentFlow}" — §6.1 defines ${X402_PAYMENT_FLOWS.join(", ")}, and clients MUST NOT construct a payment for a flow they do not recognize`,
+  };
+}
+
+/**
+ * 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 function verifyInboundNonce(
+  presentedNonce: string,
+  expectedAtrHash: string,
+): Outcome<`0x${string}`> {
+  // Decoded-byte comparison per LCP §2.5. Fails CLOSED: a presented nonce that is not a well-formed
+  // atrHash is refused rather than case-folded into a string match against a malformed expectation.
+  if (!atrHashEquals(presentedNonce, expectedAtrHash))
+    return {
+      refused: true,
+      haltClass: "verification-failure",
+      code: "x402/nonce-mismatch",
+      detail: `presented nonce ${presentedNonce} does not equal the advertised atrHash ${expectedAtrHash}`,
+    };
+  return { ok: true, value: presentedNonce.toLowerCase() as `0x${string}` };
+}

package/src/constants.ts

@@ -0,0 +1,107 @@
+/**
+ * Verified per-deployment `X402AdapterConfig` values for the LCP canonical EVM binding
+ * `LCP-X402-EVM-NONCE-1`.
+ *
+ * **Why this file exists.** `tokenName` and `tokenVersion` are the EIP-712 domain of the USDC contract the
+ * authorization is signed against, and they are NOT constant across Circle's deployments: Base Sepolia and
+ * Monad report `name() = "USDC"`, while Base mainnet and Avalanche report `name() = "USD Coin"`. A config
+ * copied from one chain to another therefore produces a WRONG domain separator, and every authorization
+ * signed under it fails verification at the token — silently, from the seller's point of view, because the
+ * signature is well-formed and simply does not recover to the payer. That is the exact failure this file
+ * removes: each entry below was read from its own deployed contract, never inherited from a sibling.
+ *
+ * Every value here is reproducible in one call, and the pinned domain separators in
+ * the repository's pinned domain-separator tests are what hold them honest:
+ *
+ *   cast call <asset> "name()(string)"        --rpc-url <rpc>
+ *   cast call <asset> "version()(string)"     --rpc-url <rpc>
+ *   cast call <asset> "DOMAIN_SEPARATOR()(bytes32)" --rpc-url <rpc>
+ *
+ * **AN UPSTREAM MISMATCH, RECORDED HERE BECAUSE IT IS THE KIND THAT FAILS SILENTLY.** x402's own Go
+ * implementation disagrees with the chain about Monad. Verified 2026-08-08 at
+ * `x402-foundation/x402@1fec3aa04e41`, `go/mechanisms/evm/constants.go`: the `"eip155:143"` entry names
+ * the SAME asset address as the `monad` entry below — `0x754704Bc059F8C67012fEd69BC8A327a5aafb603` — and
+ * gives it EIP-712 domain `Name: "USD Coin"`. The deployed contract's `name()` returns `"USDC"`, which is
+ * what the entry below carries and what the pinned `DOMAIN_SEPARATOR()` assertion in this repository holds
+ * it to.
+ *
+ * The chain is the authority: the domain separator is computed by the token contract, so a signer using
+ * "USD Coin" against a contract reporting "USDC" produces an authorization that simply does not recover to
+ * the payer. That is the silent failure this whole file exists to prevent, and here it is upstream.
+ *
+ * **REPORTED UPSTREAM 2026-08-08:** x402-foundation/x402#3102, with the `cast call` reproduction and the
+ * observation that USDC deployments are not uniform on this — Base Sepolia and Monad report "USDC" while
+ * Base mainnet and Avalanche report "USD Coin", so a value copied between chains yields a wrong domain
+ * separator rather than an obvious error. Our entry stays as measured whatever upstream does: the token
+ * contract computes the separator, so the chain is the authority.
+ *
+ * **What this file is not.** It is not an endorsement of a rail, an allowlist, or a supported-chain list.
+ * `createX402Adapter` takes any `X402AdapterConfig`, and a deployment absent here is not thereby refused —
+ * it simply has not been read off-chain by us. Adding a chain means adding a verified row, nothing more.
+ */
+import type { X402AdapterConfig } from "./adapter.js";
+
+/** The deployments whose EIP-712 domain values have been read from their own USDC contract. */
+export type X402DeploymentName =
+  | "base"
+  | "base-sepolia"
+  | "avalanche"
+  | "monad";
+
+/**
+ * Verified 2026-07-30. `fromBlock` is deliberately absent: an enumeration lower bound is an operational
+ * choice per deployment, not a property of the token, and defaulting one here would silently narrow a
+ * caller's history scan.
+ */
+const DEPLOYMENTS: Record<X402DeploymentName, X402AdapterConfig> = {
+  base: {
+    chainId: 8453,
+    asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    tokenName: "USD Coin",
+    tokenVersion: "2",
+  },
+  // The chain the x402 weld is live-proven on. Note the name differs from Base MAINNET above — the two
+  // Base deployments do not share an EIP-712 domain, which is the sharpest form of this file's hazard.
+  "base-sepolia": {
+    chainId: 84532,
+    asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    tokenName: "USDC",
+    tokenVersion: "2",
+  },
+  avalanche: {
+    chainId: 43114,
+    asset: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
+    tokenName: "USD Coin",
+    tokenVersion: "2",
+  },
+  monad: {
+    chainId: 143,
+    asset: "0x754704Bc059F8C67012fEd69BC8A327a5aafb603",
+    tokenName: "USDC",
+    tokenVersion: "2",
+  },
+};
+
+/**
+ * The verified config for a known deployment. Throws on an unknown name (fail-fast): there is no sane
+ * default, and guessing a domain would produce signatures that verify nowhere.
+ */
+export function getX402Deployment(name: string): X402AdapterConfig {
+  // The guard is folded INTO the lookup rather than sitting in front of it: a separate `hasOwn` early
+  // return would make the `=== undefined` check below unreachable, i.e. dead code.
+  const config = Object.hasOwn(DEPLOYMENTS, name)
+    ? DEPLOYMENTS[name as X402DeploymentName]
+    : undefined;
+  if (config === undefined)
+    throw new Error(
+      `unknown x402 deployment "${name}" — known: ${Object.keys(DEPLOYMENTS).join(", ")}. ` +
+        "A deployment's tokenName/tokenVersion must be read from its own USDC contract (name()/version()); " +
+        "inheriting another chain's values yields a wrong EIP-712 domain and unverifiable signatures.",
+    );
+  return config;
+}
+
+/** The known deployment names, for callers that enumerate rather than look up. */
+export function x402DeploymentNames(): X402DeploymentName[] {
+  return Object.keys(DEPLOYMENTS) as X402DeploymentName[];
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export {
+  createX402Adapter,
+  type X402AdapterConfig,
+  type X402Proposal,
+  type X402ProposalContext,
+} from "./adapter.js";
+export {
+  EIP3009_TRANSFER_METHOD,
+  filterAssetTransferMethod,
+  filterPaymentFlow,
+  verifyInboundNonce,
+  X402_PAYMENT_FLOWS,
+  X402_TRANSFER_METHODS,
+} from "./asset-transfer-method-filter.js";
+export {
+  getX402Deployment,
+  type X402DeploymentName,
+  x402DeploymentNames,
+} from "./constants.js";
+export { X402_MANIFEST } from "./manifest.js";

package/src/manifest.ts

@@ -0,0 +1,37 @@
+import type { BindingManifest } from "@integraledger/lcp-binding-core";
+
+/**
+ * The x402 `exact` / EIP-3009 binding manifest (LCP `LCP-X402-EVM-NONCE-1`).
+ *
+ * **pattern = "native-field"** — the atrHash rides the EIP-3009 `nonce`, an EXISTING protocol field
+ * the payer signs over; there is no derivation and no overlay contract. Off-canonical Native Field per
+ * LCP §8.3.1 / Appendix B.1. This is authored fresh and correct — an archived
+ * declaration says `id-reuse` / non-recoverable / non-indexable, a KNOWN-BAD artifact: it read MPP-EVM's
+ * Appendix-C.1 derivation-MUST (a property of MPP's method spec) onto the x402 path, where no derivation
+ * exists. Do NOT reconcile these values against that archive — "fixing" them reintroduces the bug.
+ */
+export const X402_MANIFEST: BindingManifest = {
+  rail: "evm:x402",
+  protocol: "x402",
+  pattern: "native-field",
+  nativeField: "eip3009.nonce",
+  recovery: {
+    onChain: true,
+    zeroPartyRecoverable: true,
+    forwardIndexable: true,
+  },
+  assetBinding: "filtered", // recover reads the token's own AuthorizationUsed log — the record proves THIS asset moved
+  successGate: "structural", // a reverted tx emits no logs, so the AuthorizationUsed weld event cannot exist
+  indexing: "nonce-topic:AuthorizationUsed",
+  finality: {
+    reversible: false,
+    note: "instant, final settlement (EIP-3009) — no on-rail reversal; recourse is the record's elected forum, and finality is never represented as dispute resolution (PAY-3/RCS-5) The atrHash welded as the EIP-3009 nonce MUST be per-transaction: an EIP-3009 nonce is one-time use, so one payer paying twice under the same ATR reproduces the same authorization and the token rejects the second with no LCP-level diagnostic. LCP §6.1 wants a per-transaction ATR anyway.",
+  },
+  // The payer's EIP-3009 signature commits to the nonce (= atrHash): signature-grade weld.
+  weldGrades: { ERC3009: "signature" },
+  offCanonical: { profile: "integra-x402-nonce-v1" }, // named profile
+  // "welded-settled", not "settled": on this rail the two are one event. The nonce IS the atrHash, so the
+  // settlement that fires `AuthorizationUsed` welds in the same log — there is no settled-but-unwelded
+  // state to name. Other rails say "settled" because their weld is a payload a settlement can lack.
+  lifecycleStates: ["proposed", "welded-settled"],
+};