@devlab.group/agent-commerce 0.1.0-alpha.0 → 1.0.0

package/dist/x402.js

@@ -1,11 +1,49 @@
-import { CommerceError, systemClock, NOOP_LOGGER, PACKAGE_VERSION } from './chunk-CZ6ZDAYD.js';
+import { assertPayToIsNotDevAddress, resolveX402Deployment, assertDevKeyIsLocalOnly, describeDeploymentMode } from './chunk-MEPETSP6.js';
+export { SUPPORTED_NETWORK_IDS } from './chunk-MEPETSP6.js';
+import { CommerceError, systemClock, NOOP_LOGGER, PACKAGE_VERSION } from './chunk-BQNE3A5H.js';
+import { PaymentRequirementsV2Schema, PaymentPayloadV2Schema } from '@x402/core/schemas';
 import { getAddress, toHex, isAddress, createWalletClient, http, publicActions, createPublicClient, HttpRequestError, TimeoutError, WaitForTransactionReceiptTimeoutError, encodeAbiParameters, keccak256, ContractFunctionRevertedError, ContractFunctionExecutionError } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
-import { encodePayment } from 'x402/schemes';
-import { getNetworkId } from 'x402/shared';
-import { PaymentRequirementsSchema, PaymentPayloadSchema } from 'x402/types';
-import { verify, settle } from 'x402/facilitator';
+import { x402Facilitator } from '@x402/core/facilitator';
+import { HTTPFacilitatorClient } from '@x402/core/http';
+import { isEIP3009Payload, toFacilitatorEvmSigner } from '@x402/evm';
+import { registerExactEvmScheme } from '@x402/evm/exact/facilitator';
 
+var LOCAL_CHAIN_ID = 84532;
+function chainIdFromCaip2(network) {
+  const match = /^eip155:(\d+)$/.exec(network);
+  if (!match?.[1]) return void 0;
+  const chainId = Number(match[1]);
+  return Number.isSafeInteger(chainId) && chainId > 0 ? chainId : void 0;
+}
+function buildLocalChain(rpcUrl, chainId = LOCAL_CHAIN_ID) {
+  return {
+    id: chainId,
+    name: "agent-commerce-local",
+    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+    rpcUrls: {
+      default: { http: [rpcUrl] }
+    }
+  };
+}
+function createLocalPublicClient(rpcUrl, timeoutMs, chainId) {
+  return createPublicClient({
+    chain: buildLocalChain(rpcUrl, chainId),
+    transport: http(rpcUrl, { timeout: timeoutMs } )
+  });
+}
+function createLocalFacilitatorClient(rpcUrl, signerPrivateKey) {
+  const chain = buildLocalChain(rpcUrl);
+  const account = privateKeyToAccount(signerPrivateKey);
+  return createWalletClient({
+    account,
+    chain,
+    transport: http(rpcUrl)
+  }).extend(publicActions);
+}
+
+// src/payments/x402/client.ts
+var X402_VERSION = 2;
 var TRANSFER_WITH_AUTHORIZATION_TYPES = {
   TransferWithAuthorization: [
     { name: "from", type: "address" },
@@ -16,23 +54,27 @@ var TRANSFER_WITH_AUTHORIZATION_TYPES = {
     { name: "nonce", type: "bytes32" }
   ]
 };
-var DEFAULT_VALID_AFTER_SKEW_SECONDS = 600;
 async function createPaymentProof(options) {
-  const requirements = PaymentRequirementsSchema.parse(options.accepts);
+  const requirements = PaymentRequirementsV2Schema.parse(options.accepts);
   if (!requirements.extra || typeof requirements.extra["name"] !== "string" || typeof requirements.extra["version"] !== "string") {
     throw new Error(
       "createPaymentProof: payment requirement is missing extra.name/extra.version \u2014 cannot build the EIP-712 domain"
     );
   }
+  const chainId = chainIdFromCaip2(requirements.network);
+  if (chainId === void 0) {
+    throw new Error(
+      `createPaymentProof: network "${requirements.network}" is not a CAIP-2 eip155 identifier \u2014 cannot determine the chain id to sign against`
+    );
+  }
   const account = privateKeyToAccount(options.buyerPrivateKey);
   void options.rpcUrl;
-  const chainId = getNetworkId(requirements.network);
   const nonce = options.overrides?.nonce ?? randomNonce();
   const nowSeconds = Math.floor(Date.now() / 1e3);
-  const validAfter = options.overrides?.validAfter ?? nowSeconds - DEFAULT_VALID_AFTER_SKEW_SECONDS;
+  const validAfter = options.overrides?.validAfter ?? 0;
   const validBefore = options.overrides?.validBefore ?? nowSeconds + requirements.maxTimeoutSeconds;
   const to = getAddress(options.overrides?.payTo ?? requirements.payTo);
-  const value = BigInt(options.overrides?.value ?? requirements.maxAmountRequired);
+  const value = BigInt(options.overrides?.value ?? requirements.amount);
   const signature = await account.signTypedData({
     domain: {
       name: requirements.extra["name"],
@@ -52,9 +94,8 @@ async function createPaymentProof(options) {
     }
   });
   const payload = {
-    x402Version: 1,
-    scheme: "exact",
-    network: requirements.network,
+    x402Version: X402_VERSION,
+    accepted: requirements,
     payload: {
       signature,
       authorization: {
@@ -67,7 +108,7 @@ async function createPaymentProof(options) {
       }
     }
   };
-  return encodePayment(payload);
+  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
 }
 function randomNonce() {
   const bytes = new Uint8Array(32);
@@ -114,109 +155,111 @@ function formatCanonicalAmount(baseUnits, decimals) {
   const sign = negative ? "-" : "";
   return fractionPart.length > 0 ? `${sign}${integerPart}.${fractionPart}` : `${sign}${integerPart}`;
 }
-var LOCAL_CHAIN_ID = 84532;
-function buildLocalChain(rpcUrl) {
+var SETTLEMENT_CONFIRMATION_TIMEOUT_MS = 6e4;
+function createLocalFacilitatorBinding(client, network, isTransportError) {
+  const build = () => {
+    let failed = false;
+    const watch = (promise) => promise.catch((err) => {
+      if (isTransportError(err)) failed = true;
+      throw err;
+    });
+    const signer = {
+      address: client.account.address,
+      readContract: (args) => watch(client.readContract(args)),
+      verifyTypedData: (args) => watch(client.verifyTypedData(args)),
+      writeContract: (args) => watch(client.writeContract(args)),
+      sendTransaction: (args) => watch(client.sendTransaction(args)),
+      waitForTransactionReceipt: (args) => watch(client.waitForTransactionReceipt(args)),
+      getCode: (args) => watch(client.getCode(args))
+    };
+    const facilitator = registerExactEvmScheme(new x402Facilitator(), {
+      signer: toFacilitatorEvmSigner(signer, {
+        confirmationTimeoutMs: SETTLEMENT_CONFIRMATION_TIMEOUT_MS
+      }),
+      networks: network
+    });
+    return { facilitator, failed: () => failed };
+  };
   return {
-    id: LOCAL_CHAIN_ID,
-    name: "agent-commerce-local",
-    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
-    rpcUrls: {
-      default: { http: [rpcUrl] }
+    kind: "local",
+    describe: "local (in-process)",
+    open() {
+      const { facilitator, failed } = build();
+      return {
+        verify: (payload, requirements) => facilitator.verify(payload, requirements),
+        settle: (payload, requirements) => facilitator.settle(payload, requirements),
+        transportFailed: failed
+      };
+    },
+    async supported() {
+      return build().facilitator.getSupported().kinds;
     }
   };
 }
-function createLocalPublicClient(rpcUrl, timeoutMs) {
-  return createPublicClient({
-    chain: buildLocalChain(rpcUrl),
-    transport: http(rpcUrl, timeoutMs !== void 0 ? { timeout: timeoutMs } : void 0)
+function cdpAuthHeaders(apiKeyId, apiKeySecret) {
+  const loading = import('@coinbase/x402').then(
+    (mod) => mod.createCdpAuthHeaders(apiKeyId, apiKeySecret),
+    (cause) => {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        'x402 provider: facilitator.auth.type is "cdp", which needs the optional peer "@coinbase/x402". Install it (npm install @coinbase/x402), or use a facilitator that accepts a static token with auth.type "bearer".',
+        { cause }
+      );
+    }
+  );
+  loading.catch(() => {
   });
+  return async () => {
+    const create = await loading;
+    if (!create) {
+      throw new CommerceError(
+        "PAYMENT_PROVIDER_UNAVAILABLE",
+        "x402 provider: @coinbase/x402 returned no auth-header factory"
+      );
+    }
+    return await create();
+  };
 }
-function createLocalFacilitatorClient(rpcUrl, signerPrivateKey) {
-  const chain = buildLocalChain(rpcUrl);
-  const account = privateKeyToAccount(signerPrivateKey);
-  return createWalletClient({
-    account,
-    chain,
-    transport: http(rpcUrl)
-  }).extend(publicActions);
-}
-
-// src/payments/x402/local-chain/accounts.ts
-var ANVIL_WELL_KNOWN_ACCOUNTS = [
-  {
-    address: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
-    privateKey: "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
-  },
-  {
-    address: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
-    privateKey: "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d"
-  },
-  {
-    address: "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
-    privateKey: "0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a"
-  }
-];
-
-// src/payments/x402/dev-key-guard.ts
-var WELL_KNOWN_DEV_KEYS = new Set(
-  ANVIL_WELL_KNOWN_ACCOUNTS.map((a) => a.privateKey.toLowerCase())
-);
-var WELL_KNOWN_DEV_ADDRESSES = new Set(
-  ANVIL_WELL_KNOWN_ACCOUNTS.map((a) => a.address.toLowerCase())
-);
-var PRIVATE_KEY_SHAPE = /^0x[0-9a-fA-F]{64}$/;
-function isWellKnownDevKey(privateKey) {
-  return WELL_KNOWN_DEV_KEYS.has(privateKey.toLowerCase());
-}
-function isWellKnownDevAddress(address) {
-  return WELL_KNOWN_DEV_ADDRESSES.has(address.toLowerCase());
-}
-function isLikelyLocalOrPrivateHost(hostname) {
-  const h = hostname.toLowerCase().replace(/^\[|\]$/g, "");
-  if (h === "localhost" || h === "127.0.0.1" || h === "::1") return true;
-  if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h)) return true;
-  if (/^10\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h)) return true;
-  if (/^192\.168\.\d{1,3}\.\d{1,3}$/.test(h)) return true;
-  if (/^172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}$/.test(h)) return true;
-  if (!h.includes(".") && !h.includes(":")) return true;
-  return false;
-}
-function parseHostnameOrThrow(rpcUrl) {
-  try {
-    return new URL(rpcUrl).hostname;
-  } catch (cause) {
-    throw new CommerceError(
-      "CONFIG_INVALID",
-      `x402 provider: rpcUrl "${rpcUrl}" is not a valid URL`,
-      { cause }
-    );
-  }
-}
-function assertDevKeyIsLocalOnly(rpcUrl, signerPrivateKey) {
-  if (!PRIVATE_KEY_SHAPE.test(signerPrivateKey)) {
-    throw new CommerceError(
-      "CONFIG_INVALID",
-      'x402 provider: facilitator.signerPrivateKey is not a well-formed private key (expected "0x" followed by exactly 64 hex characters).'
-    );
-  }
-  if (!isWellKnownDevKey(signerPrivateKey)) return;
-  const hostname = parseHostnameOrThrow(rpcUrl);
-  if (!isLikelyLocalOrPrivateHost(hostname)) {
-    throw new CommerceError(
-      "CONFIG_INVALID",
-      `x402 provider: facilitator.signerPrivateKey is a well-known Anvil development key, but rpcUrl "${rpcUrl}" does not look like a local/private chain. A public dev key must never sign against a public network \u2014 it is instantly drainable and can grief real settlements via nonce exhaustion. Use a real facilitator key for any non-local RPC, or point rpcUrl at your local/dev chain.`
-    );
-  }
-}
-function assertPayToIsNotDevAddress(rpcUrl, payTo) {
-  if (!isWellKnownDevAddress(payTo)) return;
-  const hostname = parseHostnameOrThrow(rpcUrl);
-  if (!isLikelyLocalOrPrivateHost(hostname)) {
-    throw new CommerceError(
-      "CONFIG_INVALID",
-      `x402 provider: "payTo" (${payTo}) is a well-known Anvil development address, but rpcUrl "${rpcUrl}" does not look like a local/private chain. The private key behind that address is public knowledge, so any revenue settled to it is immediately spendable by anyone. Set "payTo" to your own merchant wallet for any non-local RPC, or point rpcUrl at your local/dev chain.`
-    );
+function createRemoteFacilitatorBinding(options) {
+  const auth = options.auth;
+  let createAuthHeaders;
+  if (auth.type === "bearer") {
+    createAuthHeaders = async () => {
+      const headers = { Authorization: `Bearer ${auth.token}` };
+      return { verify: headers, settle: headers, supported: headers };
+    };
+  } else if (auth.type === "cdp") {
+    createAuthHeaders = cdpAuthHeaders(auth.apiKeyId, auth.apiKeySecret);
   }
+  const client = new HTTPFacilitatorClient({
+    url: options.url,
+    timeoutMs: options.timeoutMs ?? SETTLEMENT_CONFIRMATION_TIMEOUT_MS,
+    ...createAuthHeaders ? { createAuthHeaders } : {}
+  });
+  return {
+    kind: "remote",
+    describe: `remote ${new URL(options.url).origin} (auth=${auth.type})`,
+    open() {
+      let failed = false;
+      const watch = async (call) => {
+        try {
+          return await call();
+        } catch (err) {
+          failed = true;
+          throw err;
+        }
+      };
+      return {
+        verify: (payload, requirements) => watch(() => client.verify(payload, requirements)),
+        settle: (payload, requirements) => watch(() => client.settle(payload, requirements)),
+        transportFailed: () => failed
+      };
+    },
+    async supported() {
+      const response = await client.getSupported();
+      return response.kinds;
+    }
+  };
 }
 function decodePaymentSubmission(payloadBase64) {
   let json;
@@ -226,11 +269,11 @@ function decodePaymentSubmission(payloadBase64) {
   } catch {
     return void 0;
   }
-  const result = PaymentPayloadSchema.safeParse(json);
+  const result = PaymentPayloadV2Schema.safeParse(json);
   return result.success ? result.data : void 0;
 }
 function isExactEvmPayload(payload) {
-  return payload.scheme === "exact" && typeof payload.payload === "object" && payload.payload !== null && "authorization" in payload.payload && "signature" in payload.payload;
+  return payload.accepted.scheme === "exact" && typeof payload.payload === "object" && payload.payload !== null && isEIP3009Payload(payload.payload) && typeof payload.payload.signature === "string";
 }
 function computeReplayKey(input) {
   const encoded = encodeAbiParameters(
@@ -241,10 +284,20 @@ function computeReplayKey(input) {
 }
 
 // src/payments/x402/provider.ts
-var X402_PROTOCOL_VERSION = "1";
+var X402_VERSION2 = 2;
+var X402_PROTOCOL_VERSION = String(X402_VERSION2);
 var DEFAULT_MAX_TIMEOUT_SECONDS = 60;
 var DEFAULT_MIME_TYPE = "application/json";
 var HEALTH_TIMEOUT_MS = 4e3;
+var SETTLEMENT_PENDING_REASON = "settlement_pending";
+var MAX_REASON_LENGTH = 64;
+var REASON_SHAPE = /^[a-z0-9_.-]+$/i;
+function sanitiseReason(reason, fallback) {
+  if (reason === void 0) return fallback;
+  const trimmed = reason.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_REASON_LENGTH) return fallback;
+  return REASON_SHAPE.test(trimmed) ? trimmed : fallback;
+}
 var DEFAULT_IDS = {
   next: (prefix) => `${prefix ? `${prefix}_` : ""}${crypto.randomUUID()}`
 };
@@ -268,11 +321,23 @@ function createX402PaymentProvider(options) {
       `x402 provider: "assetDecimals" must be a non-negative integer`
     );
   }
-  let facilitatorClient;
+  const { profile, mode } = resolveX402Deployment({
+    network: options.network,
+    payTo: options.payTo,
+    asset: options.asset,
+    assetName: options.assetName,
+    assetVersion: options.assetVersion,
+    facilitator: options.facilitator,
+    ...options.allowMainnet !== void 0 ? { allowMainnet: options.allowMainnet } : {},
+    ...options.allowUnauthenticatedFacilitator !== void 0 ? { allowUnauthenticatedFacilitator: options.allowUnauthenticatedFacilitator } : {}
+  });
+  const network = options.network;
+  let binding;
   if (options.facilitator.mode === "local") {
     assertDevKeyIsLocalOnly(options.rpcUrl, options.facilitator.signerPrivateKey);
+    let client;
     try {
-      facilitatorClient = createLocalFacilitatorClient(
+      client = createLocalFacilitatorClient(
         options.rpcUrl,
         options.facilitator.signerPrivateKey
       );
@@ -283,9 +348,18 @@ function createX402PaymentProvider(options) {
         { cause }
       );
     }
+    binding = createLocalFacilitatorBinding(client, network, isProviderUnavailableError);
+  } else {
+    binding = createRemoteFacilitatorBinding({
+      url: options.facilitator.url,
+      auth: options.facilitator.auth
+    });
   }
-  const publicClient = createLocalPublicClient(options.rpcUrl);
-  const healthPublicClient = createLocalPublicClient(options.rpcUrl, HEALTH_TIMEOUT_MS);
+  const healthPublicClient = createLocalPublicClient(
+    options.rpcUrl,
+    HEALTH_TIMEOUT_MS,
+    profile.chainId
+  );
   const clock = options.clock ?? systemClock;
   const ids = options.ids ?? DEFAULT_IDS;
   const logger = options.logger ?? NOOP_LOGGER;
@@ -294,43 +368,54 @@ function createX402PaymentProvider(options) {
     name: "x402",
     kind: "payment",
     implementationVersion: PACKAGE_VERSION,
-    supportedSpec: "x402@1.2.0 scheme=exact family=evm",
-    capabilities: ["exact-evm", "local-facilitator", "eip-3009"],
+    supportedSpec: `x402/v${X402_VERSION2} scheme=exact family=eip155`,
+    capabilities: [
+      "exact-evm",
+      `${binding.kind}-facilitator`,
+      "eip-3009",
+      "caip-2",
+      `mode=${mode}`
+    ],
     status: "stable",
-    unsupported: ["svm", "deferred scheme", "remote facilitator"]
+    unsupported: [
+      "svm",
+      "permit2",
+      "upto scheme",
+      "per-request signed facilitator credentials (e.g. CDP JWT)"
+    ]
   };
   async function createRequirement(context) {
-    const maxAmountRequired = parseCanonicalAmount(
-      context.amount,
-      options.assetDecimals
-    ).toString();
+    const amount = parseCanonicalAmount(context.amount, options.assetDecimals).toString();
     const requirements = {
       scheme: "exact",
-      // options.network is a canonical free-form string (frozen contract); the
-      // x402 SDK's Network union is checked against the live chain in health()
-      // and by verify()'s own network-mismatch guard.
-      network: options.network,
-      maxAmountRequired,
-      // Descriptive metadata only: `resource` is not part of the EIP-3009
-      // authorisation the buyer signs (`from`/`to`/`value`/`validAfter`/
-      // `validBefore`/`nonce`), nothing verifies against it, and the replay
-      // key is keyed on the authorisation rather than on this string. It is
-      // still what a facilitator, wallet or buyer agent logs and shows, so it
-      // carries `network` and `payTo` — both already public in this same
-      // challenge — to stay unambiguous across the wider x402 ecosystem,
-      // where the `agent-commerce` authority alone is not reserved to us.
-      resource: `resource://agent-commerce/${encodeURIComponent(options.network)}/${options.payTo}/resources/${encodeURIComponent(context.resource.id)}`,
-      description: context.resource.description ?? context.resource.name,
-      mimeType: DEFAULT_MIME_TYPE,
+      network,
+      asset: options.asset,
+      amount,
       payTo: options.payTo,
       maxTimeoutSeconds,
-      asset: options.asset,
-      // REQUIRED.name/version explicitly means
-      // the facilitator never needs an on-chain version() call to build the
-      // EIP-712 domain, so verification stays deterministic even against a
-      // token that has no on-chain version() (it doesn't matter here since
-      // MockUSDC has one, but this is what makes the domain unambiguous).
-      extra: { name: options.assetName, version: options.assetVersion }
+      // `name`/`version` are what let a buyer and the facilitator build the
+      // same EIP-712 domain without an on-chain `version()` call, so
+      // verification stays deterministic against a token that has none.
+      //
+      // `assetTransferMethod` is stated rather than left to default: x402 v2's
+      // `exact`/EVM scheme also has a Permit2 path, and a client that picked it
+      // would produce a payload this provider cannot settle. Declaring the one
+      // supported method turns that into a client-side non-choice instead of a
+      // server-side rejection.
+      extra: {
+        name: options.assetName,
+        version: options.assetVersion,
+        assetTransferMethod: "eip3009"
+      }
+    };
+    const envelope = {
+      x402Version: X402_VERSION2,
+      resource: {
+        url: `resource://agent-commerce/${encodeURIComponent(options.network)}/${options.payTo}/resources/${encodeURIComponent(context.resource.id)}`,
+        description: context.resource.description ?? context.resource.name,
+        mimeType: DEFAULT_MIME_TYPE
+      },
+      accepts: [requirements]
     };
     const expiresAt = new Date(clock.now().getTime() + maxTimeoutSeconds * 1e3).toISOString();
     return {
@@ -347,11 +432,12 @@ function createX402PaymentProvider(options) {
       challenge: {
         provider: "x402",
         version: X402_PROTOCOL_VERSION,
-        accepts: [requirements]
+        accepts: [requirements],
+        envelope
       }
     };
   }
-  async function verify$1(context) {
+  async function verify(context) {
     const { requirement, submission } = context;
     const rejected = (reason) => ({
       status: "rejected",
@@ -379,6 +465,9 @@ function createX402PaymentProvider(options) {
     if (!payload) {
       return rejected("malformed_payment_payload");
     }
+    if (payload.x402Version !== X402_VERSION2) {
+      return rejected("unsupported_x402_version");
+    }
     if (!isExactEvmPayload(payload)) {
       return rejected("unsupported_scheme");
     }
@@ -386,35 +475,32 @@ function createX402PaymentProvider(options) {
     if (!isAddress(authorization.from) || !isAddress(authorization.to)) {
       return rejected("malformed_payment_payload");
     }
-    if (payload.network !== options.network) {
+    if (payload.accepted.network !== options.network) {
       return rejected("wrong_network");
     }
     if (getAddress(authorization.to) !== getAddress(options.payTo)) {
       return rejected("wrong_recipient");
     }
     let authorizedValue;
-    let maxRequired;
+    let required;
     try {
       authorizedValue = BigInt(authorization.value);
-      maxRequired = BigInt(requirements.maxAmountRequired);
+      required = BigInt(requirements.amount);
     } catch {
       return rejected("malformed_payment_payload");
     }
-    if (authorizedValue < maxRequired) {
+    if (authorizedValue !== required) {
       return rejected("wrong_amount");
     }
+    const scope = binding.open();
     let sdkResult;
     try {
-      sdkResult = await verify(
-        publicClient,
-        payload,
-        requirements
-      );
+      sdkResult = await scope.verify(payload, requirements);
     } catch (err) {
-      if (isProviderUnavailableError(err)) {
+      if (isProviderUnavailableError(err) || scope.transportFailed()) {
         throw new CommerceError(
           "PAYMENT_PROVIDER_UNAVAILABLE",
-          "x402 provider: RPC unreachable during verify()",
+          `x402 provider: ${binding.kind} facilitator unreachable during verify()`,
           {
             cause: err
           }
@@ -424,10 +510,27 @@ function createX402PaymentProvider(options) {
       return rejected("unexpected_verify_error");
     }
     if (!sdkResult.isValid) {
-      return rejected(sdkResult.invalidReason ?? "invalid_payment");
+      if (scope.transportFailed()) {
+        throw new CommerceError(
+          "PAYMENT_PROVIDER_UNAVAILABLE",
+          `x402 provider: ${binding.kind} facilitator unreachable during verify()`,
+          { details: { reportedReason: sdkResult.invalidReason ?? "invalid_payment" } }
+        );
+      }
+      if (sdkResult.invalidReason !== void 0) {
+        logger.debug(
+          { reportedReason: sdkResult.invalidReason },
+          "x402 verify(): facilitator rejection reason"
+        );
+      }
+      return rejected(sanitiseReason(sdkResult.invalidReason, "invalid_payment"));
+    }
+    const payloadChainId = chainIdFromCaip2(payload.accepted.network);
+    if (payloadChainId === void 0) {
+      return rejected("wrong_network");
     }
     const replayKey = computeReplayKey({
-      chainId: getNetworkId(payload.network),
+      chainId: payloadChainId,
       asset: getAddress(requirements.asset),
       from: getAddress(authorization.from),
       nonce: authorization.nonce
@@ -439,12 +542,12 @@ function createX402PaymentProvider(options) {
       payee: getAddress(authorization.to),
       amount: formatCanonicalAmount(authorizedValue, options.assetDecimals),
       currency: requirement.currency,
-      network: payload.network,
+      network: payload.accepted.network,
       asset: getAddress(requirements.asset),
       replayKey
     };
   }
-  async function settle$1(context) {
+  async function settle(context) {
     const { requirement, submission, verification } = context;
     if (verification.status !== "verified") {
       throw new CommerceError(
@@ -452,12 +555,6 @@ function createX402PaymentProvider(options) {
         "x402 provider: settle() called without a successful verify()"
       );
     }
-    if (options.facilitator.mode !== "local" || facilitatorClient === void 0) {
-      throw new CommerceError(
-        "PROTOCOL_UNSUPPORTED",
-        'x402 provider: remote facilitator settlement is not implemented in v0.1.0-alpha; only { mode: "local" } is supported'
-      );
-    }
     const requirements = requirement.challenge.accepts[0];
     if (!requirements) {
       throw new CommerceError(
@@ -472,30 +569,26 @@ function createX402PaymentProvider(options) {
         "x402 provider: settle() received an undecodable payment payload"
       );
     }
-    let broadcastTxHash;
-    const settlementClient = {
-      ...facilitatorClient,
-      waitForTransactionReceipt: (args) => {
-        broadcastTxHash = args.hash;
-        return facilitatorClient.waitForTransactionReceipt(args);
-      }
-    };
+    const rejectedSettlement = (rejectionReason) => ({
+      status: "rejected",
+      provider: "x402",
+      amount: verification.amount,
+      currency: requirement.currency,
+      ...verification.network !== void 0 ? { network: verification.network } : {},
+      ...verification.asset !== void 0 ? { asset: verification.asset } : {},
+      ...verification.replayKey !== void 0 ? { replayKey: verification.replayKey } : {},
+      rejectionReason
+    });
+    const scope = binding.open();
     let sdkResult;
     try {
-      sdkResult = await settle(
-        settlementClient,
-        payload,
-        requirements
-      );
+      sdkResult = await scope.settle(payload, requirements);
     } catch (err) {
-      if (isProviderUnavailableError(err)) {
+      if (isProviderUnavailableError(err) || scope.transportFailed()) {
         throw new CommerceError(
           "PAYMENT_PROVIDER_UNAVAILABLE",
-          "x402 provider: RPC unreachable during settle()",
-          {
-            cause: err,
-            ...broadcastTxHash !== void 0 ? { details: { transactionHash: broadcastTxHash } } : {}
-          }
+          `x402 provider: ${binding.kind} facilitator unreachable during settle()`,
+          { cause: err }
         );
       }
       const rejectionReason = isOnChainRevertError(err) ? "transaction_reverted" : "unexpected_settle_error";
@@ -503,28 +596,28 @@ function createX402PaymentProvider(options) {
         { err: describeError(err), rejectionReason },
         "x402 settle(): settlement transaction failed"
       );
-      return {
-        status: "rejected",
-        provider: "x402",
-        amount: verification.amount,
-        currency: requirement.currency,
-        ...verification.network !== void 0 ? { network: verification.network } : {},
-        ...verification.asset !== void 0 ? { asset: verification.asset } : {},
-        ...verification.replayKey !== void 0 ? { replayKey: verification.replayKey } : {},
-        rejectionReason
-      };
+      return rejectedSettlement(rejectionReason);
     }
     if (!sdkResult.success) {
+      if (sdkResult.errorReason === SETTLEMENT_PENDING_REASON || scope.transportFailed()) {
+        throw new CommerceError(
+          "PAYMENT_PROVIDER_UNAVAILABLE",
+          "x402 provider: settlement was broadcast but could not be confirmed",
+          {
+            ...sdkResult.transaction ? { details: { transactionHash: sdkResult.transaction } } : {}
+          }
+        );
+      }
+      if (sdkResult.errorReason !== void 0) {
+        logger.debug(
+          { reportedReason: sdkResult.errorReason },
+          "x402 settle(): facilitator failure reason"
+        );
+      }
       return {
-        status: "rejected",
-        provider: "x402",
-        amount: verification.amount,
-        currency: requirement.currency,
+        ...rejectedSettlement(sanitiseReason(sdkResult.errorReason, "settlement_failed")),
         network: sdkResult.network,
-        ...verification.asset !== void 0 ? { asset: verification.asset } : {},
-        ...sdkResult.payer !== void 0 ? { payer: sdkResult.payer } : {},
-        ...verification.replayKey !== void 0 ? { replayKey: verification.replayKey } : {},
-        rejectionReason: sdkResult.errorReason ?? "settlement_failed"
+        ...sdkResult.payer !== void 0 ? { payer: sdkResult.payer } : {}
       };
     }
     return {
@@ -546,10 +639,10 @@ function createX402PaymentProvider(options) {
     const checkedAt = clock.nowIso();
     try {
       const chainId = await healthPublicClient.getChainId();
-      if (chainId !== LOCAL_CHAIN_ID) {
+      if (chainId !== profile.chainId) {
         return {
           status: "fail",
-          detail: `RPC at ${options.rpcUrl} reports chain id ${chainId}, expected ${LOCAL_CHAIN_ID}`,
+          detail: `RPC at ${options.rpcUrl} reports chain id ${chainId}, expected ${profile.chainId} (${profile.displayName})`,
           checkedAt,
           durationMs: clock.monotonicMs() - startedAt
         };
@@ -563,10 +656,22 @@ function createX402PaymentProvider(options) {
           durationMs: clock.monotonicMs() - startedAt
         };
       }
-      if (options.facilitator.mode === "remote") {
+      if (binding.kind === "remote") {
+        const kinds = await binding.supported();
+        const supportsUs = kinds.some(
+          (kind) => kind.x402Version === X402_VERSION2 && kind.scheme === "exact" && kind.network === options.network
+        );
+        if (!supportsUs) {
+          return {
+            status: "fail",
+            detail: `Facilitator ${binding.describe} does not advertise x402 v${X402_VERSION2} scheme=exact on ${options.network} (${profile.displayName}); no payment on this deployment can settle`,
+            checkedAt,
+            durationMs: clock.monotonicMs() - startedAt
+          };
+        }
         return {
-          status: "warn",
-          detail: "RPC and asset are reachable; remote facilitator mode is not implemented in v0.1.0-alpha",
+          status: "pass",
+          detail: `${describeDeploymentMode(mode)} \u2014 RPC ${options.rpcUrl} reachable, chain id ${profile.chainId} (${profile.displayName}), asset ${options.asset} has code, facilitator ${binding.describe} supports exact/${options.network}`,
           checkedAt,
           durationMs: clock.monotonicMs() - startedAt
         };
@@ -575,14 +680,14 @@ function createX402PaymentProvider(options) {
       if (!isAnvil) {
         return {
           status: "fail",
-          detail: `RPC at ${options.rpcUrl} reports chain id ${LOCAL_CHAIN_ID} but does not answer "anvil_nodeInfo" \u2014 it does not look like a local Anvil dev node. Refusing to treat it as safe for a local-facilitator dev key.`,
+          detail: `RPC at ${options.rpcUrl} reports chain id ${profile.chainId} but does not answer "anvil_nodeInfo" \u2014 it does not look like a local Anvil dev node. Refusing to treat it as safe for a local-facilitator dev key.`,
           checkedAt,
           durationMs: clock.monotonicMs() - startedAt
         };
       }
       return {
         status: "pass",
-        detail: `RPC ${options.rpcUrl} reachable, chain id ${LOCAL_CHAIN_ID}, asset ${options.asset} has code, confirmed Anvil dev node`,
+        detail: `${describeDeploymentMode(mode)} \u2014 RPC ${options.rpcUrl} reachable, chain id ${profile.chainId}, asset ${options.asset} has code, confirmed Anvil dev node`,
         checkedAt,
         durationMs: clock.monotonicMs() - startedAt
       };
@@ -616,8 +721,8 @@ function createX402PaymentProvider(options) {
     name: "x402",
     descriptor,
     createRequirement,
-    verify: verify$1,
-    settle: settle$1,
+    verify,
+    settle,
     health
   };
 }