@devlab.group/agent-commerce 1.4.1 → 1.6.0

package/dist/runtime-CiYbgGpi.d.ts

@@ -0,0 +1,303 @@
+/**
+ * A JSON Schema document (in practice a draft 2020-12 subset). Deliberately
+ * loose: adapters translate it to their own schema representation. Never treat
+ * it as trusted input without validation.
+ */
+type JsonSchema = Record<string, unknown>;
+/** Protocol surfaces a resource can be exposed through */
+type ProtocolName = 'http' | 'mcp' | 'a2a' | 'acp';
+/**
+ * The same names as a value, for code that checks one at runtime: config
+ * validation and the OpenAPI importer's `--expose`
+ */
+declare const PROTOCOL_NAMES: readonly ProtocolName[];
+/**
+ * Payment rails a resource can accept.
+ *
+ * A resource's list is an ordered candidate list, not a buyer-selected menu.
+ * The pipeline uses the first method with an enabled provider, and a
+ * rejection ends the request instead of trying another rail. Config requires at
+ * least one named rail to be enabled and permits others that are not.
+ */
+type PaymentMethodName = 'x402' | 'mpp';
+/** The same names as a value, for config validation */
+declare const PAYMENT_METHOD_NAMES: readonly PaymentMethodName[];
+/**
+ * Authorization methods a resource can require. Neither a transport nor a
+ * payment rail: it proves the purchase was approved, and sits beside the
+ * payment rather than replacing it.
+ */
+type AuthorizationMethodName = 'ap2';
+/** ISO-8601 timestamp string, always UTC with millisecond precision */
+type IsoTimestamp = string;
+/**
+ * A decimal amount as a string in the currency's display unit (for example
+ * "0.01" USDC), never a float and never base units. Payment providers convert
+ * it to on-chain base units.
+ */
+type DecimalAmount = string;
+/** Health of an individual adapter or subsystem */
+interface AdapterHealth {
+    readonly status: 'pass' | 'warn' | 'fail';
+    readonly detail?: string;
+    readonly checkedAt: IsoTimestamp;
+    readonly durationMs?: number;
+}
+/** Describes an adapter's supported surface for diagnostics */
+interface AdapterDescriptor {
+    readonly name: string;
+    readonly kind: 'protocol' | 'payment' | 'storage' | 'authorization';
+    /** Version of this adapter implementation, independent of the spec */
+    readonly implementationVersion: string;
+    /** Exact pinned specification revision this adapter targets */
+    readonly supportedSpec: string;
+    readonly capabilities: readonly string[];
+    readonly status: 'stable' | 'experimental' | 'planned';
+    /** Capabilities explicitly not implemented, printed by `doctor` */
+    readonly unsupported?: readonly string[];
+}
+
+/** HTTP methods a backend handler may use */
+type BackendMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * How the gateway calls the merchant's existing backend.
+ *
+ * Backend URLs come from operator configuration only, never from users or
+ * agents (docs/security.md, SSRF). Secret header values belong in `${ENV_VAR}`
+ * placeholders resolved by the config loader, not in plaintext configuration.
+ */
+interface BackendHandler {
+    readonly type: 'http';
+    readonly method: BackendMethod;
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Hard upper bound on the backend call. Defaults to `DEFAULT_BACKEND_TIMEOUT_MS` */
+    readonly timeoutMs?: number;
+    /**
+     * Names the top-level input properties carrying each part of the request.
+     *
+     * When absent, `{param}` values come from top-level input and everything left
+     * over becomes the query string (GET/DELETE) or the whole JSON body
+     * (POST/PUT/PATCH). That cannot express an operation with path, query and
+     * body at once, such as `POST /users/{userId}/orders?notify=true`.
+     *
+     * When present, each group comes from its named property, and top-level input
+     * that no binding names is not forwarded.
+     */
+    readonly inputBindings?: {
+        readonly path?: string;
+        readonly query?: string;
+        readonly body?: string;
+    };
+}
+/** Default backend timeout when a resource does not specify one */
+declare const DEFAULT_BACKEND_TIMEOUT_MS = 10000;
+/**
+ * Canonical pricing. `dynamic` exists in the type for forward compatibility;
+ * config validation rejects it and the pipeline refuses it as defense in depth.
+ */
+type Pricing = {
+    readonly type: 'free';
+} | {
+    readonly type: 'fixed';
+    readonly amount: DecimalAmount;
+    readonly currency: string;
+} | {
+    readonly type: 'dynamic';
+    readonly resolver: string;
+};
+/**
+ * A merchant capability exposed to agents. Protocol adapters map it outward and
+ * never define their own parallel notion of a resource.
+ */
+interface CommerceResource {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema?: JsonSchema;
+    readonly outputSchema?: JsonSchema;
+    readonly handler: BackendHandler;
+    readonly pricing: Pricing;
+    readonly exposedVia: readonly ProtocolName[];
+    readonly paymentMethods: readonly PaymentMethodName[];
+    /**
+     * Authorization the buyer must present in addition to payment. Opt-in per
+     * resource. It sits beside `paymentMethods`, not inside it, because an
+     * authorization method is not a payment rail and must never be selectable as
+     * one.
+     */
+    readonly authorization?: {
+        readonly required: readonly AuthorizationMethodName[];
+    };
+}
+/** Read-only view of every configured resource */
+interface ResourceRegistry {
+    get(id: string): CommerceResource | undefined;
+    list(): readonly CommerceResource[];
+    /** Resources exposed through a given protocol surface */
+    listExposedVia(protocol: ProtocolName): readonly CommerceResource[];
+    has(id: string): boolean;
+}
+
+/**
+ * Canonical payment model. FROZEN CONTRACT.
+ *
+ * Core decides that a payment is required and for how much. Payment providers
+ * decide how the challenge is encoded, verified and settled. No x402- or
+ * EVM-specific type may appear in this file.
+ */
+
+/**
+ * Provider-native payment challenge, opaque to core. For x402 the `accepts`
+ * entries are x402 `PaymentRequirements` objects, passed to protocol adapters
+ * verbatim.
+ */
+interface PaymentChallenge {
+    readonly provider: PaymentMethodName;
+    /** Provider protocol version, e.g. the x402 `x402Version` value as a string */
+    readonly version: string;
+    readonly accepts: readonly Readonly<Record<string, unknown>>[];
+    /**
+     * The provider's own challenge document, verbatim: for x402 v2 the
+     * `PaymentRequired` object a buyer's client consumes, for MPP an object
+     * carrying the serialized `WWW-Authenticate` challenge. Opaque to core.
+     *
+     * `accepts` alone is not that document: x402 v2 carries the resource
+     * description and protocol version on the envelope. Adapters with a native
+     * channel for it (x402's `PAYMENT-REQUIRED` header, MPP's `WWW-Authenticate`)
+     * send it there as is, so every surface offers the same challenge.
+     */
+    readonly envelope?: Readonly<Record<string, unknown>>;
+}
+/**
+ * What the buyer must pay, in canonical terms, plus the provider-native
+ * challenge the buyer's client needs to construct a payment
+ */
+interface PaymentRequirement {
+    readonly id: string;
+    readonly requestId: string;
+    readonly resourceId: string;
+    readonly provider: PaymentMethodName;
+    readonly amount: DecimalAmount;
+    readonly currency: string;
+    /** Merchant-controlled settlement destination, never a gateway-owned wallet */
+    readonly destination: string;
+    readonly network?: string;
+    readonly asset?: string;
+    readonly expiresAt?: IsoTimestamp;
+    readonly challenge: PaymentChallenge;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Opaque payment proof supplied by the buyer's client. For x402 over HTTP it is
+ * the base64 `PAYMENT-SIGNATURE` header value; over MCP and A2A it is the same
+ * string in the reserved `_payment` input field.
+ */
+interface PaymentSubmission {
+    readonly method: PaymentMethodName;
+    readonly payload: string;
+}
+/** Outcome of verification or settlement */
+interface PaymentResult {
+    readonly status: 'verified' | 'settled' | 'rejected';
+    readonly provider: PaymentMethodName;
+    /** Settlement reference, e.g. an on-chain transaction hash */
+    readonly externalReference?: string;
+    readonly payer?: string;
+    readonly payee?: string;
+    readonly amount: DecimalAmount;
+    readonly currency: string;
+    readonly network?: string;
+    readonly asset?: string;
+    /**
+     * Stable, provider-computed identity of the payment authorization.
+     *
+     * The pipeline reserves this key before settlement and rejects a second
+     * request presenting it with `PAYMENT_REPLAYED`. Providers must derive it
+     * only from the authorization (payer, nonce, asset, network), so the same
+     * authorization always maps to the same key.
+     */
+    readonly replayKey?: string;
+    /** Machine-readable rejection reason when status is `rejected` */
+    readonly rejectionReason?: string;
+    readonly settledAt?: IsoTimestamp;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Input to {@link PaymentProvider.createRequirement} */
+interface PaymentContext {
+    readonly requestId: string;
+    readonly resource: CommerceResource;
+    readonly amount: DecimalAmount;
+    readonly currency: string;
+    readonly requestedAt: IsoTimestamp;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Input to {@link PaymentProvider.verify} */
+interface PaymentVerificationContext {
+    readonly requestId: string;
+    readonly resource: CommerceResource;
+    readonly requirement: PaymentRequirement;
+    readonly submission: PaymentSubmission;
+}
+/** Input to {@link PaymentProvider.settle} */
+interface PaymentSettlementContext extends PaymentVerificationContext {
+    readonly verification: PaymentResult;
+}
+/**
+ * Contract every payment rail implements. Implementations must be
+ * non-custodial: they orchestrate an external payment protocol and never hold
+ * buyer or merchant production signing keys.
+ */
+interface PaymentProvider {
+    readonly name: PaymentMethodName;
+    readonly descriptor: AdapterDescriptor;
+    /**
+     * Build the requirement and its challenge. The pipeline calls it for every
+     * paid request, including one that already carries a proof to verify.
+     */
+    createRequirement(context: PaymentContext): Promise<PaymentRequirement>;
+    /**
+     * Validate a submitted proof against the requirement. Must return `rejected`
+     * or throw a `CommerceError` rather than an untyped error, and must never
+     * move funds.
+     */
+    verify(context: PaymentVerificationContext): Promise<PaymentResult>;
+    /**
+     * Execute settlement. Called only after `verify` returned `verified` and the
+     * replay key was reserved. A settlement verdict, including a rejection, is a
+     * returned result; the pipeline records any throw as settlement-uncertain.
+     */
+    settle(context: PaymentSettlementContext): Promise<PaymentResult>;
+    health(): Promise<AdapterHealth>;
+}
+
+/**
+ * Minimal structural logger. Core does not depend on pino; the gateway injects
+ * a pino instance that satisfies this shape.
+ *
+ * Never log secrets: private keys, seed phrases, Authorization headers or
+ * payment authorization payloads.
+ */
+interface Logger {
+    debug(obj: Record<string, unknown>, msg?: string): void;
+    info(obj: Record<string, unknown>, msg?: string): void;
+    warn(obj: Record<string, unknown>, msg?: string): void;
+    error(obj: Record<string, unknown>, msg?: string): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+/** A logger that discards everything */
+declare const NOOP_LOGGER: Logger;
+
+interface Clock {
+    now(): Date;
+    nowIso(): IsoTimestamp;
+    /** Milliseconds since an arbitrary origin; use for durations only */
+    monotonicMs(): number;
+}
+interface IdGenerator {
+    /** Opaque, collision-resistant identifier */
+    next(prefix?: string): string;
+}
+declare const systemClock: Clock;
+
+export { type AdapterDescriptor as A, type BackendHandler as B, type Clock as C, type DecimalAmount as D, type IsoTimestamp as I, type JsonSchema as J, type Logger as L, NOOP_LOGGER as N, type PaymentMethodName as P, type ResourceRegistry as R, type CommerceResource as a, type PaymentSubmission as b, type AdapterHealth as c, type PaymentProvider as d, type IdGenerator as e, type AuthorizationMethodName as f, type BackendMethod as g, DEFAULT_BACKEND_TIMEOUT_MS as h, PAYMENT_METHOD_NAMES as i, PROTOCOL_NAMES as j, type PaymentChallenge as k, type PaymentContext as l, type PaymentRequirement as m, type PaymentResult as n, type PaymentSettlementContext as o, type PaymentVerificationContext as p, type Pricing as q, type ProtocolName as r, systemClock as s };

package/dist/{types-CJtwLu1c.d.ts → types-O6lg3Q5V.d.ts}

@@ -7,49 +7,43 @@
  */
 declare const AP2_SPEC_VERSION = "0.2.0";
 /**
- * Autonomous mode needs open mandates, cnf-bound agent keys and constraint
- * evaluation over `checkout.line_items`. Half of that would be worse than a
- * declared Direct-only profile, so it is refused rather than partly served.
+ * Direct only. Autonomous mode needs open mandates, cnf-bound agent keys and
+ * constraint evaluation over `checkout.line_items`, none of which is
+ * implemented, so it is refused rather than partly served.
  */
 declare const AP2_MODES: readonly ["direct"];
 type Ap2Mode = (typeof AP2_MODES)[number];
 /**
- * One entry, so `alg=none` and the HMAC family are excluded by construction
- * rather than by a check that has to remember them
+ * A single algorithm, so `alg=none` and the HMAC family are excluded by
+ * construction rather than by a denylist
  */
 declare const AP2_SIGNING_ALGORITHM = "ES256";
 /**
  * Compared against this literal, never as a prefix. `mandate.checkout.open.1`
- * carries spending constraints this release does not evaluate, so accepting it
- * would tell a buyer their limits were checked when nothing read them.
+ * carries spending constraints nothing here evaluates, so accepting it would
+ * tell a buyer their limits were checked when nothing read them.
  */
 declare const AP2_CHECKOUT_MANDATE_VCT = "mandate.checkout.1";
 /**
- * The checkout profile every merchant checkout JWT must declare.
- *
- * Ours, not AP2's: AP2 leaves the checkout payload outside its scope, so the
- * claims a paid-resource invocation needs had to be specified somewhere.
- *
- * A bare name, matching the gateway's other wire identifiers
- * (`agent-commerce/delivery`, `agent-commerce/v1.0.0`). A profile id is a
- * namespace and is never dereferenced, so a URL would only tie the wire format
- * to a domain. Frozen once released: merchants sign it into every checkout JWT.
+ * Merchant checkout JWTs declare this gateway-specific profile; AP2 leaves
+ * the checkout payload out of scope. The identifier is a namespace that
+ * clients do not dereference. Merchants sign it into each checkout JWT, so
+ * changing the expected value would reject previously signed JWTs.
  */
 declare const AP2_CHECKOUT_PROFILE = "agent-commerce/ap2/checkout/v1";
 /** Seconds of clock skew tolerated on mandate and checkout time claims */
 declare const AP2_DEFAULT_CLOCK_SKEW_SECONDS = 60;
 /**
- * Skew wide enough to cover a mandate's validity window stops `exp` rejecting
- * anything. An operator needing more than five minutes has a clock to fix.
+ * Skew as wide as a mandate's validity window would stop `exp` rejecting
+ * anything. An operator who needs more than five minutes has a clock to fix.
  */
 declare const AP2_MAX_CLOCK_SKEW_SECONDS = 300;
 
 /**
  * AP2 trust configuration and the shape a successful verification produces.
  *
- * Trust types live here, not in `src/config`, so the dependency points the way
- * `X402FacilitatorConfig` does: the subsystem owns its own config shape and
- * the loader imports it.
+ * The subsystem owns its config shape and the config loader imports it, as
+ * with `X402FacilitatorConfig`.
  */
 
 /** One inline public verification key, trusted because an operator wrote it here */
@@ -62,8 +56,8 @@ interface Ap2TrustedKey {
 interface Ap2TrustedIssuer {
     readonly issuer: string;
     /**
-     * Per issuer, not one gateway-wide value: the mandate is addressed to the
-     * merchant and the checkout JWT it binds to the gateway
+     * Per issuer, not gateway-wide: a mandate is addressed to the merchant, while
+     * the checkout JWT it binds is addressed to the gateway
      */
     readonly audience: string;
     readonly keys: readonly Ap2TrustedKey[];

package/dist/x402.d.ts

@@ -1,25 +1,22 @@
-import { X as X402FacilitatorConfig } from './guardrails-Dmwi63KB.js';
-export { F as FacilitatorAuth } from './guardrails-Dmwi63KB.js';
-import { L as Logger, C as Clock, e as IdGenerator, d as PaymentProvider } from './runtime-CKq3d_3K.js';
+import { X as X402FacilitatorConfig } from './guardrails-71XwtXlT.js';
+export { F as FacilitatorAuth } from './guardrails-71XwtXlT.js';
+import { L as Logger, C as Clock, e as IdGenerator, d as PaymentProvider } from './runtime-CiYbgGpi.js';
 
 interface NetworkProfile {
-    /** CAIP-2 identifier, e.g. `eip155:84532`. */
+    /** CAIP-2 identifier, e.g. `eip155:84532` */
     readonly id: string;
-    /** Signed into the buyer's EIP-712 domain. */
+    /** Signed into the buyer's EIP-712 domain */
     readonly chainId: number;
     readonly displayName: string;
     readonly kind: 'testnet' | 'mainnet';
     /**
-     * The USDC deployment this network is expected to settle in, with the EIP-712
-     * domain the token actually reports. Enforced only on mainnet (see
-     * `guardrails.ts`) — a testnet is where a mock token is a legitimate thing to
-     * point at.
+     * The USDC deployment this network settles in, with the EIP-712 domain the
+     * token reports. Enforced on mainnet only, since a testnet may use a mock
+     * token.
      *
-     * `name` is not decorative and is not the symbol: it is signed into every
-     * buyer's EIP-712 domain, and the two USDC deployments disagree. Base Sepolia
-     * reports `"USDC"`; Base mainnet reports `"USD Coin"`. Configure the wrong
-     * one and every payment is refused `invalid_exact_evm_token_name_mismatch`
-     * after the buyer has signed. Read back from the contracts, not assumed.
+     * `name` is the signed EIP-712 domain name, not the symbol, and the two
+     * deployments differ: `"USDC"` on Base Sepolia, `"USD Coin"` on Base. The
+     * values were read back from the contracts.
      */
     readonly canonicalAsset?: {
         readonly symbol: string;
@@ -30,42 +27,30 @@ interface NetworkProfile {
 }
 declare const SUPPORTED_NETWORK_IDS: readonly string[];
 /**
- * What this deployment actually is, as opposed to what it is called.
- *
- * `local` is a property of the *facilitator*, not the network: settling
- * through the in-process facilitator against a dev node is local regardless of
- * the CAIP-2 id that node answers to. This distinction is the whole reason
- * diagnostics can say `eip155:84532` without claiming to be on public Base
- * Sepolia.
+ * What a deployment is, as opposed to the network it names. `local` comes from
+ * the facilitator: the in-process facilitator makes a deployment local whatever
+ * CAIP-2 id it is configured with, which lets diagnostics show `eip155:84532`
+ * without claiming public Base Sepolia.
  */
 type DeploymentMode = 'local' | 'testnet' | 'mainnet';
 
 /**
- * CLIENT-SIDE payment helper.
- *
- * This module is used by the demo buyer agent (`demo/agent`) and by the
- * payment E2E test suite to build and EIP-712-sign an x402 v2 `exact`/EVM
- * payment authorisation, entirely on the buyer's side.
- *
- * The gateway NEVER calls this module and NEVER holds a buyer private key.
- * `buyerPrivateKey` here is always an Anvil well-known
- * development key (LOCAL DEVELOPMENT ONLY — DO NOT FUND) supplied by whoever
- * is driving the demo/test, not something the provider or gateway manages.
+ * Client-side payment helper: builds and EIP-712-signs an x402 v2 `exact`/EVM
+ * authorization on the buyer's side. The demo buyer agent and the test suites
+ * use it, and the `/x402` entry exports it. The gateway never calls it and
+ * never holds a buyer key.
  *
- * It signs the EIP-712 authorisation directly rather than going through the
- * SDK's `x402Client`, for one reason: `overrides`. The negative payment tests
- * need authorisations that are deliberately wrong — wrong recipient, short
- * amount, reused nonce, expired window — and a conforming client will not
- * produce those. Interop with a real SDK client is proved separately, by a
- * test that pays the gateway using `x402Client` itself.
+ * It signs directly rather than through the SDK's `x402Client` because of
+ * `overrides`: negative tests need deliberately wrong authorizations that a
+ * conforming client will not produce. The x402 settlement E2E suite also
+ * settles a payment built by `x402Client` itself to cover interoperability.
  */
 interface CreatePaymentProofOptions {
-    /** Buyer's dev-only private key. LOCAL DEVELOPMENT ONLY — DO NOT FUND. */
+    /** The buyer's private key. It signs locally and is never sent anywhere */
     readonly buyerPrivateKey: `0x${string}`;
-    readonly rpcUrl: string;
-    /** One entry from PaymentRequiredEnvelope.payment.accepts, verbatim. */
+    /** One entry from PaymentRequiredEnvelope.payment.accepts, verbatim */
     readonly accepts: Readonly<Record<string, unknown>>;
-    /** Overrides used only by negative tests (wrong amount/recipient/nonce…). */
+    /** For negative tests only: a wrong amount, recipient, nonce or validity window */
     readonly overrides?: {
         readonly value?: string;
         readonly payTo?: string;
@@ -74,26 +59,17 @@ interface CreatePaymentProofOptions {
         readonly validAfter?: number;
     };
 }
-/** Returns the base64 `PAYMENT-SIGNATURE` value to send back to the gateway. */
+/** Returns the base64 `PAYMENT-SIGNATURE` value to send back to the gateway */
 declare function createPaymentProof(options: CreatePaymentProofOptions): Promise<string>;
 
 /**
- * x402 payment provider — protocol version 2, `exact` scheme, EVM,
- * EIP-3009 `transferWithAuthorization`.
- *
- * Implements the frozen `PaymentProvider` interface (src/core/domain/payment.ts).
- * `verify()` never moves funds; only `settle()` does, and only after a
- * successful `verify()` (enforced by the gateway's execution pipeline, not by
- * this file, but this file never calls settle-like RPCs from verify()).
- *
- * Verification and settlement run through the SDK's own `x402Facilitator`
- * with the `exact`/EVM scheme registered against a single CAIP-2 network. The
- * facilitator is in-process — it is the same code a hosted facilitator runs,
- * pointed at the local dev chain — so there is no network hop and no third
- * party in the settlement path.
+ * x402 payment provider: protocol v2, `exact` scheme, EVM, EIP-3009
+ * `transferWithAuthorization`.
  *
- * The SDK behaviour relied on here is verified, not assumed: see the notes
- * beside each call site below.
+ * `verify()` never moves funds. `settle()` does, and throws unless it is handed
+ * a successful verification. Both run through a facilitator (see
+ * `facilitator.ts`): the SDK's own `x402Facilitator` in this process, or a
+ * remote HTTP facilitator.
  */
 
 interface X402ProviderOptions {
@@ -105,34 +81,26 @@ interface X402ProviderOptions {
     readonly network: string;
     /** RPC endpoint. Local chain: http://127.0.0.1:8545 */
     readonly rpcUrl: string;
-    /** ERC-20 (EIP-3009) asset address used for settlement. */
+    /** ERC-20 (EIP-3009) asset address used for settlement */
     readonly asset: `0x${string}`;
-    /** EIP-712 domain name of the asset, e.g. 'MockUSDC'. */
+    /** EIP-712 domain name of the asset, e.g. 'MockUSDC' */
     readonly assetName: string;
-    /** EIP-712 domain version of the asset, e.g. '2'. */
+    /** EIP-712 domain version of the asset, e.g. '2' */
     readonly assetVersion: string;
     readonly assetDecimals: number;
-    /** Merchant-controlled settlement destination. Never a gateway-owned wallet. */
+    /** Merchant-controlled settlement destination. Never a gateway-owned wallet */
     readonly payTo: `0x${string}`;
     readonly maxTimeoutSeconds?: number;
     /**
-     * Which facilitator verifies and broadcasts.
-     *
-     * `local` runs the facilitator in this process against the dev chain, and
-     * its `signerPrivateKey` must be an Anvil well-known key — LOCAL DEVELOPMENT
-     * ONLY — DO NOT FUND. `remote` calls an HTTP facilitator, and this gateway
-     * then holds no signing key at all.
+     * Which facilitator verifies and broadcasts. `local` runs one in this process
+     * against a dev chain, and its `signerPrivateKey` pays gas there, usually
+     * an Anvil well-known key (LOCAL DEVELOPMENT ONLY - DO NOT FUND). `remote`
+     * calls an HTTP facilitator, and the gateway then holds no signing key.
      */
     readonly facilitator: X402FacilitatorConfig;
-    /**
-     * Required to be `true` before anything settles on a mainnet. Never a
-     * default — see `guardrails.ts`.
-     */
+    /** Must be `true` before anything settles on a mainnet. Never a default */
     readonly allowMainnet?: boolean;
-    /**
-     * Required to be `true` to settle on a mainnet through a facilitator that
-     * takes no credential. Never a default.
-     */
+    /** Required on mainnet when facilitator auth is `none` */
     readonly allowUnauthenticatedFacilitator?: boolean;
     readonly logger?: Logger;
     readonly clock?: Clock;