@absol-labs/agent 0.10.0 → 0.11.0

package/src/x402/verified-delivery-facilitator.ts

@@ -0,0 +1,744 @@
+import { getAddress } from "viem";
+import {
+  PaymentPayloadSchema,
+  PaymentRequirementsSchema,
+  type PaymentPayload,
+  type PaymentRequirements,
+  type SettleResponse,
+  type VerifyResponse,
+} from "x402/types";
+
+import type {
+  DeliveryAssessment,
+  DeliveryVerdict,
+  DeliveryVerdictReason,
+  MetrikDeliveryOracle,
+} from "./delivery-oracle.js";
+import type { MetrikResourceIndex } from "./resource-index.js";
+import {
+  X402_NETWORK_BY_CHAIN_ID,
+  X402_USDC_BY_CHAIN_ID,
+  X402_VERSION,
+} from "./payment-requirements.js";
+
+/**
+ * Metrik's x402 facilitator: a fully conformant `exact` facilitator that ALSO
+ * refuses to settle payment for a service its own oracle says is not delivering.
+ *
+ * ## Why this is spec-legal
+ *
+ * `VerifyResponse` is `{ isValid: boolean, invalidReason?, payer? }`. Nothing in
+ * the x402 specification constrains WHY a facilitator answers `false`. A
+ * facilitator is the party a resource server delegates its "should this payment
+ * go through" decision to; Metrik simply knows one more thing than every other
+ * facilitator, because it runs a prober.
+ *
+ * ## What this is NOT
+ *
+ * **This is strictly weaker buyer protection than a Metrik escrow stream.** A
+ * stream holds the buyer's money and releases it only for intervals that
+ * verified, so money already spent on a service that stopped delivering is
+ * recoverable. This gate holds nothing. It can only prevent a payment that has
+ * not happened yet; it can never recover one that has. An `exact` payment that
+ * Metrik lets through is gone, exactly as it would be through any other
+ * facilitator.
+ *
+ * And `isValid: true` from this facilitator is NOT an endorsement. It means only
+ * "the payment is well-formed and Metrik has no fresh evidence that this service
+ * is failing". The gate subtracts; it never adds.
+ *
+ * ## Scope: only services Metrik actually tracks
+ *
+ * A resource that maps to no Metrik listing gets the ordinary facilitator
+ * answer, unchanged. Refusing payments for services Metrik has no opinion about
+ * would not be caution, it would be a broken facilitator.
+ */
+
+/** What the delivery gate did to a payment. */
+export type MetrikGateOutcome =
+  /** The resource is not a Metrik listing — ordinary facilitator behaviour. */
+  | "not-applicable"
+  /** Fresh evidence the service is delivering; payment allowed to proceed. */
+  | "passed"
+  /** Fresh evidence the service is failing; payment refused. */
+  | "refused"
+  /** No fresh evidence; `indeterminatePolicy` decided. */
+  | "indeterminate"
+  /** The resource's payee is not the operator who signed the listing. */
+  | "payee-mismatch"
+  /** Metrik could not tell whether the resource is one of its listings. */
+  | "registry-unavailable";
+
+/** The delivery gate's own verdict, before settlement policy is applied. */
+export interface MetrikGateVerdict {
+  readonly gate: MetrikGateOutcome;
+  /** Human-readable explanation. See "Where the explanation goes" below. */
+  readonly detail: string;
+  readonly serviceRef?: string;
+  readonly deliveryVerdict?: DeliveryVerdict;
+  readonly deliveryReason?: DeliveryVerdictReason;
+  readonly lastCheckedAt?: number | null;
+  readonly verdictAgeSeconds?: number | null;
+  readonly freshnessWindowSeconds?: number;
+}
+
+export interface MetrikGateAnnotation extends MetrikGateVerdict {
+  /**
+   * Whether THIS facilitator would broadcast this payment if asked.
+   *
+   * Distinct from `isValid`, and deliberately reported on `/verify`: a payment
+   * can be perfectly valid and still be one this relayer will not spend its own
+   * gas on (see {@link SettlementRefusalReason}). Reporting it up front lets a
+   * resource server refuse BEFORE it executes the request, instead of doing the
+   * work and then failing to get paid for it.
+   */
+  readonly settleable: boolean;
+  /** Why `settleable` is false. Absent when it is true. */
+  readonly settlementRefusal?: SettlementRefusalReason;
+}
+
+export const SETTLEMENT_REFUSAL_DETAIL: Readonly<
+  Record<SettlementRefusalReason, string>
+> = Object.freeze({
+  "asset-not-allowed":
+    "the settlement asset is not on this facilitator's allowlist. The relayer signs a call to " +
+    "`asset`, so an unrestricted asset would let a caller choose which contract the operator's " +
+    "key calls and pays gas for.",
+  "network-mismatch":
+    "the payload or the requirements name a chain this facilitator does not settle on",
+  "zero-amount":
+    "a zero-value settlement moves nothing and would only burn the relayer's gas",
+  "resource-not-tracked":
+    "this relayer only pays gas for resources Metrik tracks, and this resource did not resolve " +
+    "to exactly one signed Metrik listing. The payment is not refused — any other facilitator " +
+    "can settle it; Metrik is declining to spend its own gas on it.",
+});
+
+/**
+ * A `VerifyResponse` with Metrik's reasoning attached.
+ *
+ * ### Where the explanation goes
+ *
+ * `invalidReason` is a CLOSED enum in the x402 spec and there is no member for
+ * "this service is not delivering". Inventing one would break every conformant
+ * client that parses the field. So the enum carries the closest honest member
+ * (see {@link DELIVERY_REFUSAL_REASON}) and the real explanation travels in a
+ * `metrik` object alongside it.
+ *
+ * `VerifyResponseSchema` is a `strip` (not `strict`) Zod object, so this extra
+ * key is spec-tolerated: a conformant client parses the response successfully
+ * and simply drops `metrik`. A client that wants the reason can read it off the
+ * raw body. Nothing about the standard fields changes.
+ */
+export type MetrikVerifyResponse = VerifyResponse & {
+  readonly metrik: MetrikGateAnnotation;
+};
+
+export type MetrikSettleResponse = SettleResponse & {
+  readonly metrik: MetrikGateAnnotation;
+};
+
+/**
+ * Why this facilitator will not BROADCAST a payment, independent of whether the
+ * payment is valid.
+ *
+ * `/settle` makes the operator's relayer sign and broadcast a call to
+ * `paymentRequirements.asset` and pay the gas for it. Every field of
+ * `PaymentRequirements` arrives in the request body, and `PaymentRequirementsSchema`
+ * accepts ANY `asset` address, ANY `payTo`, `maxAmountRequired: "0"`, and any
+ * valid-URL `resource`. The library's `verify` only checks the payload against
+ * those same caller-supplied requirements — signature recovers to
+ * `authorization.from`, `to === payTo`, window valid, and
+ * `balanceOf(from) >= maxAmountRequired` **on the caller-supplied asset**. An
+ * attacker signing from their own key to their own address satisfies all of it.
+ *
+ * Without the checks below, `/settle` is a permissionless "make the relayer
+ * broadcast a call to a contract of my choosing" endpoint: deploy something
+ * whose `balanceOf` returns a huge number and whose `transferWithAuthorization`
+ * burns gas, and drain the relayer until legitimate settlement stops. No funds
+ * are stolen — but it is the operator's money, and it induces the operator's key
+ * to sign transactions to contracts they never chose.
+ *
+ * The asset allowlist is the one that removes the arbitrary-contract-call
+ * primitive outright; the rest are defence in depth.
+ */
+export type SettlementRefusalReason =
+  /** `asset` is not an operator-approved settlement token. */
+  | "asset-not-allowed"
+  /** The payload or the requirements name a chain this facilitator does not settle. */
+  | "network-mismatch"
+  /** A zero-value settlement moves nothing and only burns the relayer's gas. */
+  | "zero-amount"
+  /** The relayer only pays gas for resources Metrik actually tracks. */
+  | "resource-not-tracked";
+
+/**
+ * Which resources this facilitator will spend the relayer's gas on.
+ *
+ * `tracked-resources` (default) is a deliberate ASYMMETRY with the delivery
+ * gate's allow-by-default policy, and the asymmetry is the point: an OPINION
+ * about a service costs nothing and should be given freely, so `/verify` stays
+ * universal and fails open. BROADCASTING costs the operator real gas, so
+ * `/settle` fails closed and is scoped to Metrik's own marketplace.
+ *
+ * This is not a censorship lever. Metrik declining to spend its own gas does
+ * not stop anyone being paid — any other facilitator (or the payer's own
+ * relayer) can settle the same payment.
+ *
+ * `any-resource` is for an operator deliberately running a general-purpose
+ * facilitator on a relayer they are content to fund for anyone's traffic. The
+ * asset allowlist still applies.
+ */
+export type SettlementScope = "tracked-resources" | "any-resource";
+
+export const DEFAULT_SETTLEMENT_SCOPE: SettlementScope = "tracked-resources";
+
+/**
+ * The `invalidReason` used when the delivery gate refuses.
+ *
+ * The enum has no member for "the resource is not delivering", so the choice is
+ * between members that are all imperfect. Every payer-side member
+ * (`invalid_payload`, `invalid_exact_evm_payload_signature`,
+ * `insufficient_funds`) would be an active lie: it sends the developer to debug
+ * a wallet that is working correctly. `unexpected_verify_error` is also false —
+ * this refusal is deliberate and expected, not an error.
+ *
+ * `invalid_payment_requirements` is the only member that points at the
+ * REQUIREMENTS side of the exchange, which is exactly where the problem is:
+ * Metrik will not settle a payment quoted for THIS resource to THIS payee right
+ * now. It is the honest member, and the `metrik.detail` string carries the rest.
+ */
+export const DELIVERY_REFUSAL_REASON = "invalid_payment_requirements" as const;
+
+/** What to do when Metrik has no fresh delivery evidence. */
+export type IndeterminatePolicy = "allow" | "deny";
+
+/**
+ * Default: `allow`.
+ *
+ * The standing Metrik rule is buyer-favouring, and it still is — but it applies
+ * where Metrik HOLDS the buyer's money and must decide whether to release it.
+ * Here Metrik holds nothing, so refusing does not protect a buyer's funds; it
+ * only denies them a service they asked to buy, on a rail that works fine
+ * without Metrik. Four things make `allow` the right default:
+ *
+ * 1. **Absent evidence is the normal case, not the exception.** The oracle's
+ *    `/services` projection is built from ACTIVE STREAMS. A service with no live
+ *    Metrik stream has no row at all — on the live oracle today that is every
+ *    service. Failing closed would refuse 100% of payments, which is a broken
+ *    facilitator rather than a careful one.
+ * 2. **Fail-closed is a censorship lever.** If "oracle down" meant "no payments",
+ *    anyone who could degrade Metrik's oracle could block payments to a
+ *    competitor listed on it. `allow` removes that lever entirely.
+ * 3. **The harms are asymmetric.** A wrong refusal denies a service outright. A
+ *    wrong allowance passes one `exact` payment, at a price the buyer already
+ *    agreed to, which by construction is one call's worth.
+ * 4. **A pass never claims anything.** `isValid: true` with
+ *    `gate: "indeterminate"` says "no fresh evidence", and the annotation says
+ *    so in the response. Nobody has to infer an endorsement that was not made.
+ *
+ * Set `indeterminatePolicy: "deny"` for a deployment that would rather refuse
+ * than proceed without positive fresh evidence. That is a real, supported
+ * choice — it is just not a safe default.
+ */
+export const DEFAULT_INDETERMINATE_POLICY: IndeterminatePolicy = "allow";
+
+/** The payment-validity half of the facilitator (signature, amount, funds, window). */
+export interface PaymentVerifier {
+  verify(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ): Promise<VerifyResponse>;
+}
+
+/** The broadcast half. Requires a funded relayer wallet. */
+export interface PaymentSettler {
+  settle(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ): Promise<SettleResponse>;
+}
+
+export class RelayerNotConfiguredError extends Error {
+  constructor() {
+    super(
+      "this facilitator has no settlement relayer configured, so /settle cannot broadcast. " +
+        "Set METRIK_X402_RELAYER_PRIVATE_KEY (and METRIK_X402_RPC_URL) to enable settlement. " +
+        "Refusing rather than silently returning a fake success.",
+    );
+    this.name = "RelayerNotConfiguredError";
+  }
+}
+
+export interface MetrikVerifiedDeliveryFacilitatorOptions {
+  readonly paymentVerifier: PaymentVerifier;
+  /** Omit to run a verify-only facilitator: `/settle` then fails loudly. */
+  readonly paymentSettler?: PaymentSettler;
+  readonly resourceIndex: MetrikResourceIndex;
+  readonly deliveryOracle: MetrikDeliveryOracle;
+  /** Default {@link DEFAULT_INDETERMINATE_POLICY}. */
+  readonly indeterminatePolicy?: IndeterminatePolicy;
+  /** Chain this facilitator settles on. Default `84532` (Base Sepolia). */
+  readonly chainId?: number;
+  /**
+   * Token contracts the relayer may be asked to call. Defaults to the single
+   * canonical USDC for `chainId`. An empty array is rejected: a settling
+   * facilitator with no allowed asset can never settle anything, and silently
+   * accepting that would hide a misconfiguration.
+   *
+   * THIS IS THE CONTROL that stops `/settle` being an arbitrary-contract-call
+   * primitive. See {@link SettlementRefusalReason}.
+   */
+  readonly settlementAssetAllowlist?: readonly string[];
+  /** Default {@link DEFAULT_SETTLEMENT_SCOPE}. */
+  readonly settlementScope?: SettlementScope;
+}
+
+export interface FacilitatorSupported {
+  readonly x402Version: number;
+  readonly kind: readonly {
+    readonly scheme: string;
+    readonly networkId: string;
+    readonly extra: object;
+  }[];
+}
+
+export class MetrikVerifiedDeliveryFacilitator {
+  private readonly paymentVerifier: PaymentVerifier;
+  private readonly paymentSettler: PaymentSettler | undefined;
+  private readonly resourceIndex: MetrikResourceIndex;
+  private readonly deliveryOracle: MetrikDeliveryOracle;
+  private readonly indeterminatePolicy: IndeterminatePolicy;
+  private readonly network: string;
+  private readonly settlementAssets: ReadonlySet<string>;
+  private readonly settlementScope: SettlementScope;
+
+  constructor(options: MetrikVerifiedDeliveryFacilitatorOptions) {
+    const chainId = options.chainId ?? 84532;
+    const network = X402_NETWORK_BY_CHAIN_ID[chainId];
+    if (network === undefined) {
+      throw new Error(
+        `x402 v1 has no network name for chain ${chainId} (Metrik settles on Base: 8453, 84532)`,
+      );
+    }
+    this.paymentVerifier = options.paymentVerifier;
+    this.paymentSettler = options.paymentSettler;
+    this.resourceIndex = options.resourceIndex;
+    this.deliveryOracle = options.deliveryOracle;
+    this.indeterminatePolicy =
+      options.indeterminatePolicy ?? DEFAULT_INDETERMINATE_POLICY;
+    this.network = network;
+
+    const defaultAsset = X402_USDC_BY_CHAIN_ID[chainId]?.address;
+    const allowlist: readonly string[] =
+      options.settlementAssetAllowlist ??
+      (defaultAsset === undefined ? [] : [defaultAsset]);
+    if (allowlist.length === 0) {
+      throw new Error(
+        `no settlement asset allowlist for chain ${chainId} and none supplied. ` +
+          "Refusing to construct a facilitator that would either settle nothing or, " +
+          "worse, broadcast to a caller-chosen contract.",
+      );
+    }
+    const normalized = new Set<string>();
+    for (const candidate of allowlist) {
+      let checksummed: string;
+      try {
+        checksummed = getAddress(candidate as `0x${string}`);
+      } catch {
+        throw new Error(
+          `settlementAssetAllowlist entry is not an EVM address: ${candidate}`,
+        );
+      }
+      normalized.add(checksummed);
+    }
+    this.settlementAssets = normalized;
+    this.settlementScope = options.settlementScope ?? DEFAULT_SETTLEMENT_SCOPE;
+  }
+
+  /** The assets this relayer may be asked to call, for logging at startup. */
+  get allowedSettlementAssets(): readonly string[] {
+    return [...this.settlementAssets];
+  }
+
+  supported(): FacilitatorSupported {
+    return {
+      x402Version: X402_VERSION,
+      kind: [{ scheme: "exact", networkId: this.network, extra: {} }],
+    };
+  }
+
+  /** `POST /verify`. Takes an unvalidated body; never throws on bad input. */
+  async verify(body: unknown): Promise<MetrikVerifyResponse> {
+    const parsed = parseFacilitatorRequest(body);
+    if (parsed === undefined) {
+      return {
+        isValid: false,
+        invalidReason: "invalid_payload",
+        metrik: {
+          gate: "not-applicable",
+          settleable: false,
+          detail:
+            "request body is not a valid x402 {paymentPayload, paymentRequirements} pair",
+        },
+      };
+    }
+    return this.evaluate(parsed.paymentPayload, parsed.paymentRequirements);
+  }
+
+  /**
+   * `POST /settle`. Re-runs the full gate before broadcasting: a facilitator
+   * must never settle something it would not verify, and `/settle` is reachable
+   * without `/verify` ever having been called.
+   */
+  async settle(body: unknown): Promise<MetrikSettleResponse> {
+    const parsed = parseFacilitatorRequest(body);
+    if (parsed === undefined) {
+      return {
+        success: false,
+        errorReason: "invalid_payload",
+        transaction: "",
+        network: this.network as SettleResponse["network"],
+        metrik: {
+          gate: "not-applicable",
+          settleable: false,
+          detail:
+            "request body is not a valid x402 {paymentPayload, paymentRequirements} pair",
+        },
+      };
+    }
+
+    // Settlement constraints that need no network round trip run FIRST, so a
+    // hostile body never reaches the RPC, the registry or the oracle — let
+    // alone the relayer.
+    const preflight = this.settlementPreflight(
+      parsed.paymentPayload,
+      parsed.paymentRequirements,
+    );
+    if (preflight !== undefined) {
+      return this.refuseSettlement(parsed.paymentPayload, preflight, undefined);
+    }
+
+    const gate = await this.evaluate(
+      parsed.paymentPayload,
+      parsed.paymentRequirements,
+    );
+    if (!gate.isValid) {
+      return {
+        success: false,
+        ...(gate.invalidReason === undefined
+          ? {}
+          : { errorReason: gate.invalidReason }),
+        transaction: "",
+        network: parsed.paymentPayload.network,
+        ...(gate.payer === undefined ? {} : { payer: gate.payer }),
+        metrik: gate.metrik,
+      };
+    }
+
+    if (!gate.metrik.settleable) {
+      return this.refuseSettlement(
+        parsed.paymentPayload,
+        gate.metrik.settlementRefusal ?? "resource-not-tracked",
+        gate.metrik,
+      );
+    }
+
+    if (this.paymentSettler === undefined) {
+      throw new RelayerNotConfiguredError();
+    }
+    const settled = await this.paymentSettler.settle(
+      parsed.paymentPayload,
+      parsed.paymentRequirements,
+    );
+    return { ...settled, metrik: gate.metrik };
+  }
+
+  /**
+   * Settlement constraints checkable from the request alone — no RPC, no
+   * registry, no oracle. Returns the refusal, or `undefined` if the request
+   * clears them.
+   */
+  private settlementPreflight(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ): SettlementRefusalReason | undefined {
+    if (
+      payload.network !== this.network ||
+      requirements.network !== this.network
+    ) {
+      return "network-mismatch";
+    }
+    // THE control. Without it the relayer signs a call to whatever contract
+    // address the caller puts here. See `SettlementRefusalReason`.
+    let asset: string;
+    try {
+      asset = getAddress(requirements.asset);
+    } catch {
+      return "asset-not-allowed";
+    }
+    if (!this.settlementAssets.has(asset)) {
+      return "asset-not-allowed";
+    }
+    let amount: bigint;
+    try {
+      amount = BigInt(requirements.maxAmountRequired);
+    } catch {
+      return "zero-amount";
+    }
+    if (amount <= 0n) {
+      return "zero-amount";
+    }
+    return undefined;
+  }
+
+  /** Builds the standard-shaped refusal for a settlement the relayer declines. */
+  private refuseSettlement(
+    payload: PaymentPayload,
+    reason: SettlementRefusalReason,
+    gate: MetrikGateVerdict | undefined,
+  ): MetrikSettleResponse {
+    return {
+      success: false,
+      errorReason:
+        reason === "network-mismatch"
+          ? "invalid_network"
+          : "invalid_payment_requirements",
+      transaction: "",
+      network: this.network as SettleResponse["network"],
+      metrik: {
+        ...(gate ?? { gate: "not-applicable" as const, detail: "" }),
+        settleable: false,
+        settlementRefusal: reason,
+        detail: SETTLEMENT_REFUSAL_DETAIL[reason],
+      },
+    };
+  }
+
+  private async evaluate(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ): Promise<MetrikVerifyResponse> {
+    const evaluated = await this.evaluateGate(payload, requirements);
+    // `settleable` is computed once, here, from the same facts `/settle`
+    // enforces — so a resource server reading `/verify` learns BEFORE it does
+    // any work whether this relayer will actually broadcast.
+    const refusal =
+      this.settlementPreflight(payload, requirements) ??
+      (evaluated.isValid
+        ? this.scopeRefusal(evaluated.metrik.gate)
+        : "resource-not-tracked");
+    return {
+      ...evaluated,
+      metrik: {
+        ...evaluated.metrik,
+        settleable: refusal === undefined,
+        ...(refusal === undefined ? {} : { settlementRefusal: refusal }),
+      },
+    };
+  }
+
+  /** Does this gate outcome name a resource the relayer will pay gas for? */
+  private scopeRefusal(
+    gate: MetrikGateOutcome,
+  ): SettlementRefusalReason | undefined {
+    if (this.settlementScope === "any-resource") {
+      return undefined;
+    }
+    // Only an origin that resolved to exactly one signed listing counts.
+    // "not-applicable" (not ours), "ambiguous" (two claimants) and
+    // "registry-unavailable" (cannot tell) are all "we do not know this is
+    // ours", and the relayer does not spend gas on that.
+    return gate === "passed" ||
+      gate === "indeterminate" ||
+      gate === "refused" ||
+      gate === "payee-mismatch"
+      ? undefined
+      : "resource-not-tracked";
+  }
+
+  private async evaluateGate(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ): Promise<VerifyResponse & { readonly metrik: MetrikGateVerdict }> {
+    // 1. Ordinary payment validity first. A malformed or unfunded payment is
+    //    rejected on its own merits, and never reaches — or leaks — the
+    //    delivery record of a service.
+    const payment = await this.paymentVerifier.verify(payload, requirements);
+    if (!payment.isValid) {
+      return {
+        ...payment,
+        metrik: {
+          gate: "not-applicable",
+          detail:
+            "payment rejected on ordinary x402 grounds; the Metrik delivery gate did not run",
+        },
+      };
+    }
+
+    // 2. Is this resource one of ours? Resolved from Metrik's own verified
+    //    registry view, keyed on the resource URL's origin.
+    const lookup = await this.resourceIndex.lookup(requirements.resource);
+    if (lookup.status === "registry-unavailable") {
+      return this.applyIndeterminate(payment, {
+        gate: "registry-unavailable",
+        detail:
+          "Metrik could not read its service registry, so it cannot tell whether this resource is one it tracks",
+      });
+    }
+    if (lookup.status !== "resolved" || lookup.resource === undefined) {
+      // Not a Metrik listing. Behave exactly like any other facilitator.
+      return {
+        ...payment,
+        metrik: {
+          gate: "not-applicable",
+          detail:
+            "resource is not a Metrik-listed service; Metrik has no delivery opinion and applied no gate",
+        },
+      };
+    }
+    const resolved = lookup.resource;
+
+    // 3. The payee must be the operator who SIGNED the listing. This is the one
+    //    check that protects the payer rather than the seller: without it,
+    //    anyone could quote a Metrik-listed resource and redirect its payment to
+    //    their own address.
+    if (!addressesEqual(requirements.payTo, resolved.operator)) {
+      return {
+        isValid: false,
+        invalidReason: "invalid_exact_evm_payload_recipient_mismatch",
+        ...(payment.payer === undefined ? {} : { payer: payment.payer }),
+        metrik: {
+          gate: "payee-mismatch",
+          serviceRef: resolved.serviceRef,
+          detail:
+            `payTo ${requirements.payTo} is not the operator ${resolved.operator} who signed the listing ` +
+            `for ${resolved.matchedOrigin}; refusing to settle a payment for a Metrik-listed resource to a different address`,
+        },
+      };
+    }
+
+    // 4. The differentiator.
+    const assessment = await this.deliveryOracle.verdictFor(
+      resolved.serviceRef,
+    );
+    if (assessment.verdict === "failing") {
+      return {
+        isValid: false,
+        invalidReason: DELIVERY_REFUSAL_REASON,
+        ...(payment.payer === undefined ? {} : { payer: payment.payer }),
+        metrik: {
+          gate: "refused",
+          detail:
+            `Metrik's oracle reports this service as FAILING its delivery checks ` +
+            `(verdict recorded ${assessment.ageSeconds ?? "?"}s ago, within the ` +
+            `${assessment.freshnessWindowSeconds}s freshness window). The payment itself is valid; ` +
+            `Metrik is refusing to settle it. This prevents a payment — it does not recover one.`,
+          ...assessmentFields(assessment, resolved.serviceRef),
+        },
+      };
+    }
+    if (assessment.verdict === "indeterminate") {
+      return this.applyIndeterminate(payment, {
+        gate: "indeterminate",
+        detail:
+          `Metrik has no fresh delivery evidence for this service (${assessment.reason}; ` +
+          `freshness window ${assessment.freshnessWindowSeconds}s). ` +
+          `Policy is "${this.indeterminatePolicy}".`,
+        ...assessmentFields(assessment, resolved.serviceRef),
+      });
+    }
+    return {
+      ...payment,
+      metrik: {
+        gate: "passed",
+        detail:
+          `Metrik's oracle recorded a passing delivery check for this service ` +
+          `${assessment.ageSeconds ?? "?"}s ago. This is not an endorsement of output correctness — ` +
+          `Metrik verifies delivery, not correctness.`,
+        ...assessmentFields(assessment, resolved.serviceRef),
+      },
+    };
+  }
+
+  private applyIndeterminate(
+    payment: VerifyResponse,
+    annotation: MetrikGateVerdict,
+  ): VerifyResponse & { readonly metrik: MetrikGateVerdict } {
+    if (this.indeterminatePolicy === "deny") {
+      return {
+        isValid: false,
+        invalidReason: DELIVERY_REFUSAL_REASON,
+        ...(payment.payer === undefined ? {} : { payer: payment.payer }),
+        metrik: {
+          ...annotation,
+          detail: `${annotation.detail} Refusing because this facilitator is configured to require positive fresh evidence.`,
+        },
+      };
+    }
+    return {
+      ...payment,
+      metrik: {
+        ...annotation,
+        detail:
+          `${annotation.detail} Allowing: Metrik holds none of this money, so refusing would deny the ` +
+          `service without protecting anyone. "isValid: true" here asserts only that the payment is ` +
+          `well-formed — it is NOT a statement that the service is delivering.`,
+      },
+    };
+  }
+}
+
+function assessmentFields(
+  assessment: DeliveryAssessment,
+  serviceRef: string,
+): Omit<MetrikGateVerdict, "gate" | "detail"> {
+  return {
+    serviceRef,
+    deliveryVerdict: assessment.verdict,
+    deliveryReason: assessment.reason,
+    lastCheckedAt: assessment.lastCheckedAt,
+    verdictAgeSeconds: assessment.ageSeconds,
+    freshnessWindowSeconds: assessment.freshnessWindowSeconds,
+  };
+}
+
+function addressesEqual(a: string, b: string): boolean {
+  try {
+    return getAddress(a) === getAddress(b);
+  } catch {
+    return false;
+  }
+}
+
+interface ParsedFacilitatorRequest {
+  readonly paymentPayload: PaymentPayload;
+  readonly paymentRequirements: PaymentRequirements;
+}
+
+/**
+ * Parses the facilitator wire body with the REAL x402 schemas. Both `/verify`
+ * and `/settle` take the same `{paymentPayload, paymentRequirements}` pair.
+ */
+export function parseFacilitatorRequest(
+  body: unknown,
+): ParsedFacilitatorRequest | undefined {
+  if (typeof body !== "object" || body === null) {
+    return undefined;
+  }
+  const candidate = body as Record<string, unknown>;
+  const payload = PaymentPayloadSchema.safeParse(candidate.paymentPayload);
+  if (!payload.success) {
+    return undefined;
+  }
+  const requirements = PaymentRequirementsSchema.safeParse(
+    candidate.paymentRequirements,
+  );
+  if (!requirements.success) {
+    return undefined;
+  }
+  return {
+    paymentPayload: payload.data,
+    paymentRequirements: requirements.data,
+  };
+}