@metalntwx/metal-pay 0.2.0 → 0.3.1

package/src/mandates/verify.ts

@@ -0,0 +1,625 @@
+// Verifying a mandate and its payments from the chain, with no Metal service:
+// the mandate's binding on the principal's account; the credential in hand
+// against what was bound, and its signatures under the issuer the chain
+// recorded; and each payment or refusal under the mandate as the agent key's
+// per-payment mandate, rebuilt byte for byte from the transaction that
+// carried it. Any JSON-RPC node serves the reads, with no historical state:
+// the account's code is read at the latest block, and a clone's code never
+// changes, so what it is now it was when it bound and paid. What a verifier
+// cannot rebuild (the budget's running total, the nonce's single use) is read
+// as the contract recorded it in the event and checked against the limits.
+
+import {
+  type Address,
+  type Hash,
+  type Hex,
+  type ParseEventLogsReturnType,
+  type PublicClient,
+  type RpcLog,
+  decodeFunctionData,
+  formatLog,
+  getAbiItem,
+  getAddress,
+  hexToBigInt,
+  isAddressEqual,
+  numberToHex,
+  erc20Abi,
+  parseAbi,
+  parseEventLogs,
+  slice,
+  toEventSelector,
+  toFunctionSelector,
+} from "viem";
+import {
+  type AgentKey,
+  type Constraints,
+  type L3aFields,
+  type Pull,
+  REASONS,
+  REFUSALS,
+  type ReasonName,
+  type Terms,
+  decodeAgentKey,
+  encodeAgentKey,
+  mandateBindingAbi,
+  mandateReference,
+  reasonName,
+  sameAgentKey,
+} from "./binding.js";
+import { accountFactoryFor, metalNetwork } from "../networks.js";
+import { assertMetalAccount, metalAccountCode, metalAccountFactoryAbi } from "./account.js";
+import { publicMessage } from "./chain.js";
+import { checkoutHash, readL3b, verifyCheckoutMandate, x402Offer, lineItemOf } from "./checkout.js";
+import { type Json, jcs } from "./jcs.js";
+import { buildL3a, mandateNonce, serializeL3a, transactionIdOf, verifyL3aSignature } from "./l3a.js";
+import { type Credential, type TrustedIssuer, extractTerms, hashCredential, issuerKeyId, verifyCredential } from "./vi/credential.js";
+
+interface LogPosition { block: bigint; transactionIndex: number; logIndex: number }
+function before(a: LogPosition, b: LogPosition): boolean {
+  return a.block < b.block || (a.block === b.block && (a.transactionIndex < b.transactionIndex || (a.transactionIndex === b.transactionIndex && a.logIndex < b.logIndex)));
+}
+function position(log: { blockNumber: bigint | null; transactionIndex: number | null; logIndex: number | null }): LogPosition {
+  if (log.blockNumber === null || log.transactionIndex === null || log.logIndex === null) throw new Error("pending mandate event");
+  return { block: log.blockNumber, transactionIndex: log.transactionIndex, logIndex: log.logIndex };
+}
+
+export interface VerifyStep {
+  step: 1 | 2 | 3 | 4;
+  title: string;
+  outcome: "pass" | "fail" | "skipped";
+  detail: string;
+}
+
+export const STEP_TITLES = {
+  1: "The mandate is bound on the principal's account: hash(C), the limits, the payees, the mandate key and the issuer key are on chain",
+  2: "The credential in hand hashes to the bound hash(C) and states the bound limits, payees and mandate key",
+  3: "The credential's signatures: the issuer's under a trusted key that is the one recorded at binding, the owner's under the key the issuer bound",
+  4: "Each payment and refusal is the mandate key's per-payment mandate, rebuilt from its transaction, inside the mandate at its block",
+} as const;
+
+/** A mandate as its `MandateBound` event records it. */
+export interface BoundMandate {
+  ref: Hex;
+  principal: Address;
+  block: bigint;
+  txHash: Hash;
+  hashC: Hex;
+  issuerKey: Hex;
+  agentKey: AgentKey;
+  constraints: Constraints;
+  terms: Terms;
+  /** The block of its revocation, when it was revoked (a replacement revokes too). */
+  revokedBlock?: bigint;
+  revokedPosition?: LogPosition;
+  /** The mandate that replaced it. */
+  successor?: Hex;
+}
+
+export interface VerifiedPayment {
+  kind: "payment" | "refusal";
+  txHash: Hash;
+  block: bigint;
+  to: Address;
+  amount: bigint;
+  /** The ERC-3009 nonce the token recorded; a seller's `/settlements` row carries it for a payment the facilitator settled. */
+  nonce?: Hex;
+  reason?: ReasonName;
+  /** The L3a SD-JWT, as the VI reference serialises it, when the transaction carried one. */
+  perPaymentMandate?: string;
+  problems: string[];
+}
+
+export interface MandateVerification {
+  ok: boolean;
+  steps: VerifyStep[];
+  mandate?: BoundMandate;
+  payments: VerifiedPayment[];
+}
+
+export interface VerifyMandateOptions {
+  /** The MetalAccountFactory whose clones are trusted, chosen by the verifier, never by the payer; the one `@metalntwx/metal-pay` names for the chain unless given. */
+  accountFactory?: Address;
+  /** The credential the mandate was bound from; without it steps 2 and 3 are skipped. */
+  credential?: Credential;
+  /** The issuers whose signature on the credential is accepted; without them step 3 is skipped. */
+  trustedIssuers?: readonly TrustedIssuer[];
+  /** The seller's x402 payment requirements, to check that the one payment verified was signed over them. */
+  requirements?: Json;
+  /** The agent's signed offer for the one payment verified, which must be the one its per-payment mandate names. */
+  checkoutMandate?: string;
+  /** The mandate to verify in a transaction that settles payments under several, for a verifier with no credential; the credential names it otherwise. */
+  ref?: Hex;
+}
+
+const short = (hex: Hex) => `${hex.slice(0, 10)}…`;
+/** A reason as the facilitator names it to a payer. */
+const named = (reason: ReasonName) => (reason === "None" ? "none" : REFUSALS[reason].reason);
+const message = publicMessage;
+
+/** Terms as JSON for comparison: integers as decimal strings, hex lowercase. */
+function toJson(value: unknown): Json {
+  return JSON.parse(JSON.stringify(value, (_k, v: unknown) => (typeof v === "bigint" ? v.toString() : typeof v === "string" && /^0x[0-9a-fA-F]*$/.test(v) ? v.toLowerCase() : v))) as Json;
+}
+
+/**
+ * Why `reason` (`None` for a payment) contradicts what the transfer, the
+ * bound terms and the block decide, or undefined. Mandate Binding's checks a
+ * verifier can decide, in its order: revocation, expiry, the window, the
+ * payee set, the per-payment cap and the recurrence dates. The budget, the
+ * occurrences and the nonce's single use depend on the running state the
+ * event records, and are checked from it by the caller.
+ */
+function reasonContradiction(reason: ReasonName, pull: Pick<Pull, "to" | "value" | "validAfter" | "validBefore">, m: BoundMandate, at: LogPosition & { timestamp: bigint }): string | undefined {
+  const c = m.constraints;
+  const t = at.timestamp;
+  const decided: [ReasonName, boolean][] = [
+    ["Revoked", m.revokedPosition !== undefined && before(m.revokedPosition, at)],
+    ["Expired", t > c.expiry],
+    ["OutsideWindow", t <= pull.validAfter || t >= pull.validBefore],
+    ["PayeeNotAllowed", hexToBigInt(m.terms.openSdHash) === 0n && !m.terms.payees.some((p) => isAddressEqual(p.account, pull.to))],
+    ["OverPerPaymentCap", pull.value > c.perPaymentCap],
+    ["OutsideRecurrence", t < c.recurrenceStart || t > c.recurrenceEnd],
+  ];
+  const first = decided.find(([, holds]) => holds)?.[0];
+  const own = decided.find(([r]) => r === reason);
+  if (own !== undefined) {
+    if (!own[1]) return `${named(reason)} does not hold for it`;
+    return first === undefined || first === reason ? undefined : `${named(first)} holds, and Mandate Binding checks it before ${named(reason)}`;
+  }
+  if (first === undefined) return undefined;
+  if (reason === "None") return `it breaks the mandate: ${named(first)}`;
+  return REASONS.indexOf(first) < REASONS.indexOf(reason) ? `${named(first)} holds, and Mandate Binding checks it before ${named(reason)}` : undefined;
+}
+
+interface Carried { pull: Pull; fields: L3aFields }
+
+/** The selector a payment's calldata carries: `pull` on the principal, whoever submitted it. */
+const PULL_SELECTOR = toFunctionSelector(getAbiItem({ abi: mandateBindingAbi, name: "pull" }));
+
+/**
+ * Every pull that `input` carries: at the top level, or inside whatever
+ * wrapped the call (a multicall, a sponsor's batch, the quorum's own
+ * execute). Each occurrence of the selector in the calldata is tried as a
+ * call's start; the one the event's digest names is the payment's, and a
+ * forged candidate rebuilds to another digest.
+ */
+function carriedL3as(input: Hex): Carried[] {
+  const found: Carried[] = [];
+  const body = input.slice(2);
+  for (let at = body.indexOf(PULL_SELECTOR.slice(2)); at !== -1; at = body.indexOf(PULL_SELECTOR.slice(2), at + 2)) {
+    if (at % 2 !== 0) continue;
+    try {
+      const call = decodeFunctionData({ abi: mandateBindingAbi, data: `0x${body.slice(at)}` });
+      if (call.functionName !== "pull") continue;
+      const [pull, fields] = call.args;
+      found.push({ pull: { ...pull }, fields: { ...fields } });
+    } catch {
+      // Not a call that starts here.
+    }
+  }
+  return found;
+}
+
+/**
+ * The candidate that is the outcome the event records: it rebuilds to the
+ * recorded digest, moves the mandate's token, and its nonce commits to the
+ * mandate and that digest (the L3a hashes neither the token nor the nonce,
+ * so a copy with either changed is not it); among those, one signed by the
+ * agent key comes first, so unrelated calldata with the same L3a (a copy
+ * under another signature) cannot stand in for the payment. One another
+ * mandate's terms cannot rebuild is not a candidate.
+ */
+function carriedL3a(input: Hex, chainId: number, m: BoundMandate, o: Pick<Outcome, "l3aDigest">): Carried {
+  const rank = (c: Carried): number => {
+    try {
+      const l3a = buildL3a(chainId, m.terms, c.pull, c.fields);
+      if (slice(l3a.digest, 0, 20).toLowerCase() !== o.l3aDigest.toLowerCase()) return 0;
+      if (!isAddressEqual(c.pull.token, m.constraints.token) || mandateNonce(m.ref, l3a.digest) !== c.pull.nonce.toLowerCase()) return 0;
+      return 1 + (verifyL3aSignature(m.agentKey, l3a.digest, c.fields.r, c.fields.s) ? 1 : 0);
+    } catch {
+      return 0;
+    }
+  };
+  const candidates = carriedL3as(input);
+  let carried: Carried | undefined;
+  let best = 0;
+  for (const c of candidates) {
+    const r = rank(c);
+    if (r > best) [carried, best] = [c, r];
+  }
+  if (carried === undefined) throw new Error(candidates.length === 0 ? "the transaction carries no pull on the principal" : "no pull the transaction carries rebuilds to the per-payment mandate the event records");
+  return carried;
+}
+
+type MandateEvent = ParseEventLogsReturnType<typeof mandateBindingAbi, undefined, true>[number];
+
+const MANDATE_EVENTS = new Set(mandateBindingAbi.filter((item) => item.type === "event").map((item) => toEventSelector(item)));
+
+/** The events a MetalAccount emits besides Mandate Binding's: its quorum, scheduling, sessions and OpenZeppelin bases. */
+const ACCOUNT_EVENTS = new Set([
+  ...MANDATE_EVENTS,
+  ...parseAbi([
+    "event EIP712DomainChanged()",
+    "event ERC7579TryExecuteFail(uint256 batchExecutionIndex, bytes returndata)",
+    "event ERC7913SignerAdded(bytes indexed signers)",
+    "event ERC7913SignerRemoved(bytes indexed signers)",
+    "event ERC7913SignerWeightChanged(bytes indexed signer, uint64 weight)",
+    "event ERC7913ThresholdSet(uint64 threshold)",
+    "event Executed(uint256 indexed nonce)",
+    "event Initialized(uint64 version)",
+    "event ScheduleCanceled(bytes32 indexed operationId)",
+    "event ScheduleConfigured(uint64 threshold, uint32 delay)",
+    "event Scheduled(bytes32 indexed operationId, uint256 indexed nonce, bytes32 mode, bytes executionData, uint48 readyAt)",
+    "event ScheduledExecuted(bytes32 indexed operationId)",
+    "event SessionGranted(address indexed agent, address indexed token, uint64 expiresAt, uint256 perTransferCap, uint256 periodBudget, uint32 period)",
+    "event SessionRevoked(address indexed agent, address indexed token)",
+    "event SessionTransfer(address indexed agent, address indexed token, address indexed to, uint256 amount)",
+  ]).map((item) => toEventSelector(item)),
+]);
+
+/** What a verifier that cannot decode an account's events says: a deployed account of another version than the SDK's can emit them. */
+const OTHER_VERSIONS = "the SDK and the deployed account may be different versions";
+
+/** A log's place in the chain: its transaction and its index there. */
+const placeOf = (log: { transactionHash: Hash | null; logIndex: number | null }): string => `${log.transactionHash}:${log.logIndex}`;
+
+/**
+ * The account's events under `ref` that Mandate Binding's ABI does not
+ * decode, by topic. Each puts the reference in its first topic, so an
+ * account of another version emits its outcomes there under another topic,
+ * or under the same topic in another layout, and a scan that dropped them
+ * would see a mandate with no payments. Each log is matched to its decoding
+ * by its place.
+ */
+function undecoded(principal: Address, ref: Hex, logs: readonly RpcLog[], decoded: readonly MandateEvent[]): string[] {
+  const read = new Set(decoded.map(placeOf));
+  const counts = new Map<Hex, number>();
+  for (const log of logs.map((raw) => formatLog(raw))) {
+    const topic = log.topics[0];
+    if (topic !== undefined && !read.has(placeOf(log))) counts.set(topic, (counts.get(topic) ?? 0) + 1);
+  }
+  return [...counts].map(([topic, count]) => `the account ${getAddress(principal)} emitted ${count} event${count === 1 ? "" : "s"} under ${short(ref)} that this SDK does not decode, under topic ${topic}; ${OTHER_VERSIONS}`);
+}
+
+/**
+ * The mandate's events on the principal between two blocks, oldest first: one
+ * `eth_getLogs` for every event kind, since each puts the reference in its
+ * first topic. A node caps the range one request may span, each by its own
+ * rule and in its own words, so a refused range is halved until the node
+ * answers; an error that holds for a single block is the node's.
+ */
+async function mandateEvents(client: PublicClient, principal: Address, ref: Hex, fromBlock: bigint, toBlock: bigint): Promise<{ events: MandateEvent[]; unknown: string[] }> {
+  const out: MandateEvent[] = [];
+  const raw: RpcLog[] = [];
+  let span = toBlock - fromBlock + 1n;
+  for (let start = fromBlock; start <= toBlock;) {
+    const end = start + span - 1n > toBlock ? toBlock : start + span - 1n;
+    try {
+      const logs = (await client.request({ method: "eth_getLogs", params: [{ address: principal, fromBlock: numberToHex(start), toBlock: numberToHex(end), topics: [null, ref] }] })) as RpcLog[];
+      raw.push(...logs);
+      out.push(...parseEventLogs({ abi: mandateBindingAbi, logs: logs.map((log) => formatLog(log)), strict: true }));
+      start = end + 1n;
+    } catch (error) {
+      if (span <= 1n) throw error;
+      span /= 2n;
+    }
+  }
+  return { events: out, unknown: undecoded(principal, ref, raw, out) };
+}
+
+/**
+ * The mandate `ref` as the principal's account bound it: its state names the
+ * block, so the scan for its events starts there and never at genesis.
+ * `toBlock` bounds the scan when only the events up to one block matter.
+ */
+async function boundMandate(client: PublicClient, principal: Address, ref: Hex, factory: Address, toBlock?: bigint): Promise<Found> {
+  const state = await client.readContract({ address: principal, abi: mandateBindingAbi, functionName: "mandates", args: [ref] });
+  if (!isAddressEqual(state.principal, principal)) return { events: [], unknown: [], problems: [`no mandate ${short(ref)} is bound on ${principal}`] };
+  const from = state.boundBlock;
+  const to = toBlock ?? (await client.getBlockNumber());
+  const { events, unknown } = await mandateEvents(client, principal, ref, from, to);
+  const bound = events.filter((e) => e.eventName === "MandateBound");
+  if (bound.length !== 1) return { events, unknown, problems: [bound.length === 0 ? `no MandateBound for ${short(ref)} on ${principal} in block ${from}, where its state says it was bound` : `${bound.length} MandateBound events for ${short(ref)}`] };
+  const [log] = bound;
+  if (log === undefined || log.eventName !== "MandateBound" || log.blockNumber === null || log.transactionHash === null) return { events, unknown, problems: ["the MandateBound event is pending"] };
+  try { await assertMetalAccount(client, principal, factory); }
+  catch (error) { return { events, unknown, problems: [message(error)] }; }
+  const agentKey = decodeAgentKey(log.args.agentKey);
+  const problems: string[] = [];
+  if (mandateReference(principal, agentKey, log.args.hashC).toLowerCase() !== ref.toLowerCase()) problems.push("the reference does not derive from the principal, the mandate key and hash(C)");
+  const revoked = events.find((e) => e.eventName === "MandateRevoked");
+  const replaced = events.find((e) => e.eventName === "MandateReplaced");
+  const revokedBlock = revoked?.blockNumber ?? undefined;
+  const successor = replaced?.eventName === "MandateReplaced" ? replaced.args.successor : undefined;
+  return {
+    mandate: {
+      ref: ref.toLowerCase() as Hex,
+      principal,
+      block: log.blockNumber,
+      txHash: log.transactionHash,
+      hashC: log.args.hashC,
+      issuerKey: log.args.issuerKey,
+      agentKey,
+      constraints: { ...log.args.constraints },
+      terms: { ...log.args.terms, payees: log.args.terms.payees.map((p) => ({ ...p })) },
+      ...(revokedBlock === undefined || revoked === undefined ? {} : { revokedBlock, revokedPosition: position(revoked) }),
+      ...(successor === undefined ? {} : { successor }),
+    },
+    events,
+    unknown,
+    problems,
+  };
+}
+
+interface Outcome extends LogPosition {
+  kind: "payment" | "refusal";
+  txHash: Hash;
+  block: bigint;
+  to: Address;
+  amount: bigint;
+  l3aDigest: Hex;
+  agentKey: Hex;
+  spent?: bigint;
+  occurrences?: bigint;
+  reason?: ReasonName;
+}
+
+/** The payments and refusals among `events`, oldest first; with `only`, those one transaction carried. */
+function outcomesOf(events: readonly MandateEvent[], only: Hash | undefined): Outcome[] {
+  const outcomes: Outcome[] = [];
+  for (const log of events) {
+    if (log.blockNumber === null || log.transactionHash === null) continue;
+    if (log.eventName === "MandatePayment") {
+      const { to, amount, l3aDigest, agentKey, spent, occurrences } = log.args;
+      outcomes.push({ ...position(log), kind: "payment", txHash: log.transactionHash, block: log.blockNumber, to, amount, l3aDigest, agentKey, spent, occurrences });
+    } else if (log.eventName === "MandateRefused") {
+      const { to, amount, l3aDigest, agentKey, reason } = log.args;
+      outcomes.push({ ...position(log), kind: "refusal", txHash: log.transactionHash, block: log.blockNumber, to, amount, l3aDigest, agentKey, reason: reasonName(reason) });
+    }
+  }
+  outcomes.sort((a, b) => before(a, b) ? -1 : before(b, a) ? 1 : 0);
+  return only === undefined ? outcomes : outcomes.filter((o) => o.txHash.toLowerCase() === only.toLowerCase());
+}
+
+async function verifyOutcome(client: PublicClient, chainId: number, m: BoundMandate, o: Outcome, one: { requirements?: Json; checkoutMandate?: string; checkoutSdHash?: Hex }): Promise<VerifiedPayment> {
+  const verified: VerifiedPayment = { kind: o.kind, txHash: o.txHash, block: o.block, to: o.to, amount: o.amount, ...(o.reason === undefined ? {} : { reason: o.reason }), problems: [] };
+  const found = verified.problems;
+  const agentKey = decodeAgentKey(o.agentKey);
+  if (!sameAgentKey(agentKey, m.agentKey)) found.push("not the bound mandate key");
+  try {
+    const [tx, block] = await Promise.all([client.getTransaction({ hash: o.txHash }), client.getBlock({ blockNumber: o.block })]);
+    const { pull, fields } = carriedL3a(tx.input, chainId, m, o);
+    if (!isAddressEqual(pull.token, m.constraints.token)) found.push("another token than the mandate's");
+    const receipt = await client.getTransactionReceipt({ hash: o.txHash });
+    if (receipt.status !== "success" || receipt.blockNumber !== o.block) found.push("no successful receipt at the recorded block");
+    if (o.kind === "payment") {
+      const transfers = parseEventLogs({ abi: erc20Abi, logs: receipt.logs, eventName: "Transfer", strict: true });
+      if (!transfers.some(t => isAddressEqual(t.address, m.constraints.token) && isAddressEqual(t.args.from, m.principal) && isAddressEqual(t.args.to, pull.to) && t.args.value === pull.value && t.logIndex < o.logIndex)) found.push("no matching token transfer before the payment event");
+    }
+    const l3a = buildL3a(chainId, m.terms, pull, fields);
+    verified.perPaymentMandate = serializeL3a(l3a, fields.r, fields.s);
+    if (slice(l3a.digest, 0, 20).toLowerCase() !== o.l3aDigest.toLowerCase()) found.push("its digest is not the one the event records");
+    verified.nonce = pull.nonce;
+    if (mandateNonce(m.ref, l3a.digest) !== pull.nonce.toLowerCase()) found.push("its nonce does not commit to the mandate and the per-payment mandate");
+    if (!verifyL3aSignature(m.agentKey, l3a.digest, fields.r, fields.s)) found.push("not the bound mandate key's signature");
+    if (!isAddressEqual(pull.to, o.to)) found.push("another payee than the event records");
+    if (pull.value !== o.amount) found.push("another amount than the event records");
+    const other = one.checkoutMandate === undefined ? undefined : othersOrder(one.checkoutMandate, fields.transactionId, pull);
+    if (other !== undefined) {
+      // Its other checks would only list how that other payment differs.
+      found.push(`the checkout mandate belongs to another payment: ${other}`);
+    } else if (one.checkoutMandate !== undefined) {
+      // The offer served, when the verifier served it; the signed order's own otherwise.
+      const offer = one.requirements !== null && typeof one.requirements === "object" && !Array.isArray(one.requirements) ? x402Offer(one.requirements) : undefined;
+      found.push(...verifyCheckoutMandate(one.checkoutMandate, {
+        agent: m.agentKey,
+        kid: m.terms.kid,
+        payee: pull.to,
+        ...(offer === undefined ? {} : { offer, lineItemId: lineItemOf(offer) }),
+        window: pull,
+        transactionId: fields.transactionId,
+        amount: pull.value,
+        ...(one.checkoutSdHash === undefined ? {} : { checkoutSdHash: one.checkoutSdHash }),
+      }).problems);
+    } else if (one.requirements !== undefined && transactionIdOf(one.requirements).toLowerCase() !== fields.transactionId.toLowerCase()) {
+      found.push("not signed over the requirements given");
+    }
+    if (one.requirements !== undefined) {
+      const r = one.requirements;
+      if (r === null || typeof r !== "object" || Array.isArray(r)
+        || typeof r.asset !== "string" || r.asset.toLowerCase() !== pull.token.toLowerCase()
+        || typeof r.payTo !== "string" || r.payTo.toLowerCase() !== pull.to.toLowerCase()
+        || r.amount !== pull.value.toString() || r.network !== `eip155:${chainId}`) found.push("the transfer does not satisfy the requirements given");
+    }
+    const at = { ...o, timestamp: block.timestamp };
+    if (o.kind === "payment") {
+      const broken = reasonContradiction("None", pull, m, at);
+      if (broken !== undefined) found.push(broken);
+      if (o.spent !== undefined && o.spent > m.constraints.budget) found.push("over the budget");
+      if (o.occurrences !== undefined && o.occurrences > m.constraints.maxOccurrences) found.push("over the occurrence cap");
+    } else if (o.reason !== undefined) {
+      const contradiction = reasonContradiction(o.reason, pull, m, at);
+      if (contradiction !== undefined) found.push(`refused for ${named(o.reason)}: ${contradiction}`);
+    }
+  } catch (error) {
+    found.push(message(error));
+  }
+  return verified;
+}
+
+/**
+ * How a checkout mandate that parses is another payment's: a checkout hash
+ * other than the per-payment mandate's `transaction_id`, or another window,
+ * as both are signed together for one payment. Undefined when it is this
+ * payment's, or does not parse, which its own check names.
+ */
+function othersOrder(checkoutMandate: string, transactionId: Hex, pull: Pull): string | undefined {
+  try {
+    const l3b = readL3b(checkoutMandate);
+    if (!Number.isSafeInteger(l3b.iat) || !Number.isSafeInteger(l3b.exp)) return undefined;
+    const differs = [
+      ...(checkoutHash(l3b.checkoutJwt) === transactionId.toLowerCase() ? [] : ["its checkout hash is not the transaction_id this payment's per-payment mandate signed"]),
+      ...(BigInt(l3b.iat as number) === pull.validAfter && BigInt(l3b.exp as number) === pull.validBefore ? [] : ["its window is not this payment's"]),
+    ];
+    return differs.length === 0 ? undefined : differs.join(", and ");
+  } catch {
+    return undefined;
+  }
+}
+
+/** The mandate's binding and events, with what the binding's checks found and, apart, the events under it that did not decode. */
+type Found = { mandate?: BoundMandate; events: readonly MandateEvent[]; unknown: string[]; problems: string[] };
+
+async function verify(client: PublicClient, found: Found, opts: VerifyMandateOptions & { accountFactory: Address }, only: { tx: Hash; events: readonly MandateEvent[] } | undefined): Promise<MandateVerification> {
+  const steps: VerifyStep[] = [];
+  const record = (step: VerifyStep["step"], problems: string[], passed: string) =>
+    steps.push({ step, title: STEP_TITLES[step], outcome: problems.length > 0 ? "fail" : "pass", detail: problems.length > 0 ? problems.join("; ") : passed });
+  const skip = (step: VerifyStep["step"], why: string) => steps.push({ step, title: STEP_TITLES[step], outcome: "skipped", detail: why });
+
+  const m = found.mandate;
+  if (m === undefined) {
+    record(1, [...found.problems, ...found.unknown], "");
+    skip(2, "no binding to check against");
+    skip(3, "no binding to check against");
+    skip(4, "no binding to check against");
+    return { ok: false, steps, payments: [] };
+  }
+  record(
+    1,
+    found.problems,
+    `${short(m.ref)} bound in block ${m.block} by ${m.principal}: hash(C) ${m.hashC}, issuer key ${m.issuerKey}, mandate key ${short(encodeAgentKey(m.agentKey))}, ${m.terms.payees.length} payee(s)` +
+      `${m.revokedBlock === undefined ? "" : `, revoked in block ${m.revokedBlock}`}${m.successor === undefined ? "" : `, replaced by ${short(m.successor)}`}`,
+  );
+
+  const c = opts.credential;
+  let credentialIsBound = false;
+  if (c === undefined) {
+    skip(2, "no credential in hand");
+  } else {
+    const problems: string[] = [];
+    if (hashCredential(c).toLowerCase() !== m.hashC.toLowerCase()) problems.push("hash(C) of the credential in hand is not the bound hash");
+    else {
+      try {
+        const stated = extractTerms(c);
+        const differs = [
+          ["principal", isAddressEqual(stated.principal, m.principal)],
+          ["mandate key", sameAgentKey(stated.agentKey, m.agentKey)],
+          ["limits", jcs(toJson(stated.constraints)) === jcs(toJson(m.constraints))],
+          ["payees", jcs(toJson(stated.terms)) === jcs(toJson(m.terms))],
+        ].filter(([, same]) => !same);
+        if (differs.length > 0) problems.push(`the bound ${differs.map(([name]) => name).join(", ")} differ from the credential's`);
+      } catch (error) {
+        problems.push(message(error));
+      }
+    }
+    credentialIsBound = problems.length === 0;
+    record(2, problems, "the credential hashes to the bound hash(C), and binds exactly the limits, payees and mandate key it states");
+  }
+
+  if (c === undefined || !credentialIsBound) skip(3, c === undefined ? "no credential in hand" : "the credential in hand is not the bound one");
+  else if (opts.trustedIssuers === undefined || opts.trustedIssuers.length === 0) skip(3, "no trusted issuer given");
+  else {
+    const problems: string[] = [];
+    try {
+      const boundAt = await client.getBlock({ blockNumber: m.block });
+      const { issuer } = await verifyCredential(c, { trustedIssuers: opts.trustedIssuers, account: m.principal, now: Number(boundAt.timestamp) });
+      if (issuerKeyId(issuer.jwk).toLowerCase() !== m.issuerKey.toLowerCase()) problems.push("the trusted issuer's key is not the issuer key recorded at binding");
+    } catch (error) {
+      problems.push(message(error));
+    }
+    record(3, problems, "the issuer's signature verifies under the trusted key the chain recorded, the owner's under the key the issuer bound, and the credential was valid when bound");
+  }
+
+  const chainId = await client.getChainId();
+  const outcomes = outcomesOf(only === undefined ? found.events : only.events, only?.tx);
+  const payments: VerifiedPayment[] = [];
+  const checkoutSdHash = c !== undefined && credentialIsBound ? extractTerms(c).checkoutSdHash : undefined;
+  const one = outcomes.length === 1 ? { ...opts, ...(checkoutSdHash === undefined ? {} : { checkoutSdHash }) } : {};
+  for (const o of outcomes) payments.push(await verifyOutcome(client, chainId, m, o, one));
+  const problems = [...found.unknown, ...payments.filter((p) => p.problems.length > 0).map((p) => `${p.kind} in ${short(p.txHash)}: ${p.problems.join(", ")}`)];
+  if (only !== undefined && outcomes.length === 0) problems.push(`transaction ${only.tx} carries no payment or refusal under ${short(m.ref)}`);
+  if ((opts.requirements !== undefined || opts.checkoutMandate !== undefined) && outcomes.length > 1) problems.push("requirements or a signed offer given, but more than one payment to check them against");
+  const paid = payments.filter((p) => p.kind === "payment").length;
+  // One payment's check says whether it covered the signed order.
+  const order = only === undefined ? "" : opts.checkoutMandate === undefined ? "; no checkout mandate was given, so the order was not checked" : "; the checkout mandate is this payment's signed order";
+  record(4, problems, `${paid} payment(s) and ${payments.length - paid} refusal(s), each the bound mandate key's per-payment mandate rebuilt byte for byte from its transaction, inside the mandate at its block${order}`);
+
+  return { ok: steps.every((s) => s.outcome !== "fail"), steps, mandate: m, payments };
+}
+
+/** The factory the verifier trusts on `client`'s chain: the caller's, else the one the network table names. */
+async function trustedFactory(client: PublicClient, override: Address | undefined): Promise<Address> {
+  if (override !== undefined) return override;
+  const chainId = await client.getChainId();
+  const network = metalNetwork(`eip155:${chainId}`);
+  if (network === undefined) throw new Error(`chain ${chainId} is not a Metal network; pass accountFactory`);
+  return accountFactoryFor(network, undefined, "pass accountFactory");
+}
+
+/**
+ * The four steps over a credential and the chain: the mandate the credential
+ * describes, bound on the account it names, and every payment and refusal
+ * under it.
+ */
+
+export async function verifyMandate(client: PublicClient, opts: VerifyMandateOptions & { credential: Credential }): Promise<MandateVerification> {
+  const terms = extractTerms(opts.credential);
+  const ref = mandateReference(terms.principal, terms.agentKey, hashCredential(opts.credential));
+  const accountFactory = await trustedFactory(client, opts.accountFactory);
+  return verify(client, await boundMandate(client, terms.principal, ref, accountFactory), { ...opts, accountFactory }, undefined);
+}
+
+/**
+ * The four steps over one transaction: the mandate its payment or refusal
+ * names, found from the event the principal's account emitted, and that one
+ * outcome. A seller holds no credential, so steps 2 and 3 are skipped unless
+ * one is given; with the x402 `requirements` it served, the payment is
+ * checked to have been signed over them.
+ */
+export async function verifyMandatePayment(client: PublicClient, opts: VerifyMandateOptions & { tx: Hash }): Promise<MandateVerification> {
+  const receipt = await client.getTransactionReceipt({ hash: opts.tx });
+  const accountFactory = await trustedFactory(client, opts.accountFactory);
+  const logs = parseEventLogs({ abi: mandateBindingAbi, logs: receipt.logs, eventName: ["MandatePayment", "MandateRefused"], strict: true });
+  // Only an account the trusted factory made emits a mandate's outcome; any
+  // other contract in the transaction may copy the event's shape. A read
+  // that fails is not an answer: it propagates, so a verification never
+  // passes on part of a transaction's outcomes.
+  const clone = metalAccountCode(await client.readContract({ address: accountFactory, abi: metalAccountFactoryAbi, functionName: "implementation" }));
+  const emitters = new Map<string, boolean>();
+  const trusted = async (address: string): Promise<boolean> => {
+    if (!emitters.has(address)) emitters.set(address, (await client.getCode({ address: address as Address }))?.toLowerCase() === clone);
+    return emitters.get(address) === true;
+  };
+  for (const address of new Set(logs.map((log) => log.address.toLowerCase()))) await trusted(address);
+  const carried = logs.filter((log) => emitters.get(log.address.toLowerCase()) === true);
+  if (carried.length === 0) {
+    // An account of another version than the SDK's emits its outcomes under
+    // topics the ABI does not decode, or under its topics in another layout.
+    const read = new Set(parseEventLogs({ abi: mandateBindingAbi, logs: receipt.logs, strict: true }).map(placeOf));
+    for (const log of receipt.logs) {
+      const topic = log.topics[0]?.toLowerCase() as Hex | undefined;
+      if (topic === undefined || (MANDATE_EVENTS.has(topic) ? read.has(placeOf(log)) : ACCOUNT_EVENTS.has(topic)) || !(await trusted(log.address.toLowerCase()))) continue;
+      throw new Error(`transaction ${opts.tx} carries no payment or refusal this SDK decodes: the account ${getAddress(log.address)} emitted an event under topic ${topic}, which this SDK does not decode; ${OTHER_VERSIONS}`);
+    }
+    throw new Error(logs.length === 0 ? `transaction ${opts.tx} carries no payment or refusal under a mandate` : `transaction ${opts.tx} carries mandate outcomes only from ${[...new Set(logs.map((log) => log.address.toLowerCase()))].join(", ")}, no account of the trusted factory ${accountFactory}`);
+  }
+  // One transaction may settle payments under several mandates (a sponsor's
+  // batch). `ref` or the credential in hand names the one to verify; a
+  // credential that names none of them is still checked against a single
+  // mandate, and fails there; without either, several are ambiguous.
+  const named = (log: (typeof carried)[number]) => `${log.address.toLowerCase()}:${log.args.ref.toLowerCase()}`;
+  const mandates = [...new Set(carried.map(named))];
+  const listed = mandates.map((k) => short(k.split(":")[1] as Hex)).join(", ");
+  const wanted = opts.ref !== undefined ? opts.ref : opts.credential !== undefined ? mandateReference(extractTerms(opts.credential).principal, extractTerms(opts.credential).agentKey, hashCredential(opts.credential)) : undefined;
+  let chosen = wanted === undefined ? undefined : mandates.find((k) => k.endsWith(`:${wanted.toLowerCase()}`));
+  if (chosen === undefined) {
+    if (opts.ref !== undefined) throw new Error(`transaction ${opts.tx} carries no payment or refusal under ${short(opts.ref)}; it carries outcomes under ${listed}`);
+    if (mandates.length > 1) throw new Error(`transaction ${opts.tx} carries outcomes under ${mandates.length} mandates (${listed})${opts.credential === undefined ? "; pass the credential, or the ref, of the one to verify" : ", none the credential's"}`);
+    chosen = mandates[0]!;
+  }
+  const [principal, ref] = chosen.split(":") as [Address, Hex];
+  // The mandate's events up to this payment's block decide whether it was revoked by then; the outcome itself is in the receipt.
+  const found = await boundMandate(client, principal, ref, accountFactory, receipt.blockNumber);
+  const events = carried.filter((log) => named(log) === chosen) as unknown as MandateEvent[];
+  return verify(client, found, { ...opts, accountFactory }, { tx: opts.tx, events });
+}