@absol-labs/agent 0.11.0 → 0.12.0-rc.1

package/dist/gateway/x402-opener-mode.d.ts

@@ -0,0 +1,215 @@
+import { x402HTTPResourceServer, type FacilitatorClient } from "@x402/core/server";
+import type { Network } from "@x402/core/types";
+import { type Address, type PublicClient } from "viem";
+import { type OperatorSignedListingResolver } from "../x402-opener/listing-resolver.js";
+import { type OpenerTerms, type X402SchemaDeclaration } from "../x402-opener/terms.js";
+/**
+ * The gateway's x402 v2 mode (metrik-agent#116): answer an uncapabilitied
+ * request with a standard x402 v2 `402` whose `payTo` is the listing's
+ * `X402StreamOpener` address, and settle every accepted payment INTO a
+ * `StreamEscrowV2` stream through the Metrik opener facilitator.
+ *
+ * The wire format is the official `@x402/core` resource server's, not a
+ * re-implementation: `x402HTTPResourceServer` builds `PAYMENT-REQUIRED`,
+ * matches `PAYMENT-SIGNATURE`, verifies and settles through the facilitator and
+ * builds `PAYMENT-RESPONSE`.
+ *
+ * ## The opener payTo must ONLY ever be settled by the Metrik opener facilitator
+ *
+ * A stock x402 `exact` facilitator settles by calling
+ * `USDC.transferWithAuthorization(to = payTo)` directly. Pointed at an opener,
+ * that strands 100% of the payer's funds in the opener permanently (there is,
+ * deliberately, no sweep). So this mode:
+ *
+ * - refuses to START unless the configured facilitator's `GET /supported`
+ *   advertises the opener marker for exactly this factory, escrow, token and
+ *   chain; and re-checks that marker on a timer, failing CLOSED (503, no
+ *   `payTo` quoted, nothing verified or settled) whenever it cannot;
+ * - uses exactly one facilitator client, never a fallback list;
+ * - registers no discovery (Bazaar) extension and never submits the route to
+ *   any catalog. When (and only when) the operator configures an input/output
+ *   schema, it is DECLARED in the 402 in the standard `extensions.bazaar`
+ *   shape so a client can read what to send; only the Metrik opener
+ *   facilitator ever sees the payment, and it catalogs nothing;
+ * - states plainly in the 402 `description` what is bought (the stream
+ *   window, rate, that the seller earns only verified seconds, and that
+ *   unearned money is refundable without ETH through the facilitator's
+ *   refund relay) and refuses to start unless that facilitator advertises
+ *   the relay (`refundRelay: true` in its marker) — the 402 never promises a
+ *   refund path that is not there. Refunds are not automatic;
+ * - authenticates the opener only as `factory.predict(terms)` — never by code
+ *   or codehash, which a clone outside the factory can reproduce;
+ * - serves one EIP-3009 authorization at most once: a `PAYMENT-SIGNATURE`
+ *   whose authorization is in flight or already settled gets `409` WITHOUT an
+ *   upstream call (in-memory, per gateway instance). A retry after
+ *   `settlement_pending` is let through so it can reconcile;
+ * - refuses to start if its price is below the facilitator's advertised
+ *   minimum, or if its facilitator timeout would not outlast the facilitator's
+ *   receipt wait.
+ */
+/** How long a successful `/supported` marker check is trusted, seconds. */
+export declare const DEFAULT_FACILITATOR_MARKER_TTL_SECONDS = 300;
+/** Default per-request facilitator HTTP timeout. Must outlast its receipt wait. */
+export declare const DEFAULT_FACILITATOR_TIMEOUT_MS = 120000;
+export interface GatewayX402OpenerModeConfig {
+    /** Base URL of the Metrik opener facilitator (e.g. `https://facilitator.example`). */
+    readonly facilitatorUrl: string;
+    /** Bearer token the facilitator requires on `/settle`. */
+    readonly facilitatorToken: string;
+    /** CAIP-2 network (`eip155:<chainId>`), as the registry gives it. */
+    readonly network: Network;
+    readonly factoryAddress: Address;
+    /** The escrow this gateway checks streams against; the factory must point at it. */
+    readonly escrowAddress: Address;
+    /** Settlement token; must equal the factory's. */
+    readonly asset: Address;
+    /** EIP-712 domain of the token (Circle USDC: `USDC` / `2`). */
+    readonly assetName: string;
+    readonly assetVersion: string;
+    /** Opener terms. `operator` + `serviceRef` must resolve to one operator-signed listing. */
+    readonly terms: OpenerTerms;
+    /** Price per paid request in token base units. Becomes the stream deposit. */
+    readonly price: bigint;
+    /** Authorization validity the client signs for. Default 300s. */
+    readonly maxTimeoutSeconds?: number;
+    /** Public origin clients reach this gateway at, for the 402 `resource.url`. */
+    readonly resourceBaseUrl?: string;
+    /**
+     * What the service does, in one sentence. Prefixed to the fixed disclosure
+     * of what the payment buys ({@link describeOpenerPurchase}); it can never
+     * replace that disclosure.
+     */
+    readonly description?: string;
+    /**
+     * Public base URL of the facilitator's refund relay (`/streams/:streamId`).
+     * Default `facilitatorUrl`. When different, its `/supported` must advertise
+     * the same opener marker with `refundRelay: true` (checked at startup).
+     */
+    readonly refundBaseUrl?: string;
+    /** Docs link carried in the 402. Default {@link DEFAULT_OPENER_DOCS_URL}. */
+    readonly docsUrl?: string;
+    /** Token decimals for the human-readable amounts in the description. Default 6 (USDC). */
+    readonly assetDecimals?: number;
+    /**
+     * Optional input/output schema, declared in the 402 as
+     * `extensions.bazaar` (`{info: {input, output}, schema}`). Declared only;
+     * never registered with any discovery catalog.
+     */
+    readonly schemaDeclaration?: X402SchemaDeclaration;
+    /** Registry used to prove the listing at startup. Default the public registry. */
+    readonly registryUrl?: string;
+    readonly markerTtlSeconds?: number;
+    /**
+     * Per-request facilitator HTTP timeout, ms. Default
+     * {@link DEFAULT_FACILITATOR_TIMEOUT_MS}. Must exceed the facilitator's
+     * advertised receipt timeout by 30 s, so the gateway never gives up on a
+     * settlement the facilitator is still waiting for.
+     */
+    readonly facilitatorTimeoutMs?: number;
+}
+/**
+ * The plain statement of what one payment buys, used as the 402 resource
+ * `description`. It names the window, the rate, that the seller earns only for
+ * seconds Metrik's verifier confirms, and where unearned money is refundable
+ * without ETH. It says that refunds are not automatic, because they are not:
+ * someone has to call the refund relay.
+ */
+export declare function describeOpenerPurchase(input: {
+    readonly terms: OpenerTerms;
+    readonly price: bigint;
+    readonly assetDecimals: number;
+    readonly assetSymbol: string;
+    /** Refund URL template containing `{streamId}`. */
+    readonly refundUrlTemplate: string;
+    readonly docsUrl: string;
+    readonly serviceDescription?: string;
+}): string;
+export interface GatewayX402OpenerModeDeps {
+    /** Read client for the factory. Default built from `rpcUrl`. */
+    readonly publicClient?: PublicClient;
+    readonly rpcUrl?: string;
+    readonly listingResolver?: OperatorSignedListingResolver;
+    /** Override the facilitator transport (tests). Default {@link HTTPFacilitatorClient}. */
+    readonly facilitatorClient?: FacilitatorClient;
+    readonly now?: () => number;
+    /** HTTP client for checking a separate `refundBaseUrl`. Default global fetch. */
+    readonly fetch?: typeof fetch;
+}
+export interface GatewayX402OpenerMode {
+    /** The predicted opener address quoted as `payTo`. */
+    readonly payTo: Address;
+    readonly network: Network;
+    readonly terms: OpenerTerms;
+    readonly price: bigint;
+    readonly resourceBaseUrl: string | undefined;
+    /** The 402 `description` (what the payment buys). */
+    readonly description: string;
+    /** Refund relay base; a stream's refund page is `${refundBaseUrl}/streams/:streamId`. */
+    readonly refundBaseUrl: string;
+    readonly httpServer: x402HTTPResourceServer;
+    /** One-use accounting of authorizations this gateway has seen. */
+    readonly authorizations: GatewayAuthorizationLedger;
+    /**
+     * Resolves once the facilitator is proven to be the Metrik opener
+     * facilitator for this factory (cached for the marker TTL) and the resource
+     * server is initialized. Rejects otherwise — callers must fail closed.
+     */
+    ready(): Promise<void>;
+    /** Serves one x402-mode request over the supplied transport. Never throws. */
+    handle(io: X402GatewayRequestIO): Promise<void>;
+}
+/** JSON reasons the x402 path can answer with, beyond the gateway's own. */
+export type X402GatewayResponseReason = "x402-facilitator-unavailable" | "x402-settlement-failed" | "internal-error" | "upstream-unavailable" | "x402-payment-already-used";
+export interface X402UpstreamResult {
+    readonly status: number;
+    readonly headers: Record<string, string>;
+    readonly body: Buffer;
+}
+/** The transport the HTTP server hands the x402 path. */
+export interface X402GatewayRequestIO {
+    readonly requestUrl: URL;
+    readonly method: string;
+    /** Lower-cased request headers. */
+    readonly headers: Readonly<Record<string, string | undefined>>;
+    /** Proxies the request upstream (payment headers stripped) and buffers the response. */
+    callUpstream(): Promise<X402UpstreamResult>;
+    writeJson(status: number, reason: X402GatewayResponseReason): void;
+    write(status: number, headers: Record<string, string>, body: Buffer | string): void;
+    logError(context: string, error: unknown): void;
+}
+/**
+ * Per-gateway, in-memory record of EIP-3009 authorizations (chain + asset +
+ * payer + nonce): `in-flight` while a request is being verified/served/
+ * settled, `pending` after a `settlement_pending` (a retry may reconcile), and
+ * `settled` once a success was delivered. In-flight and settled
+ * authorizations are refused before the upstream is ever called. Entries are
+ * dropped once the authorization's `validBefore` has passed (plus a grace).
+ */
+export declare class GatewayAuthorizationLedger {
+    private readonly now;
+    private readonly maxEntries;
+    private readonly entries;
+    constructor(now: () => number, maxEntries?: number);
+    /** Claims the authorization for one request; false if it is in flight or settled. */
+    claim(key: string, validBefore: bigint): boolean;
+    release(key: string): void;
+    markPending(key: string, validBefore: bigint): void;
+    markSettled(key: string, validBefore: bigint): void;
+    private prune;
+}
+export declare class X402OpenerModeConfigError extends Error {
+    constructor(message: string);
+}
+export declare class X402OpenerFacilitatorUnverifiedError extends Error {
+    constructor(message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+/**
+ * Builds the x402 mode and proves, before returning, every fact it will quote:
+ * valid terms and price, one operator-signed listing for the terms, the
+ * factory's escrow and token, the predicted `payTo`, and the facilitator's
+ * opener marker. Throws on any doubt; the gateway then refuses to start.
+ */
+export declare function buildGatewayX402OpenerMode(config: GatewayX402OpenerModeConfig, deps?: GatewayX402OpenerModeDeps): Promise<GatewayX402OpenerMode>;
+//# sourceMappingURL=x402-opener-mode.d.ts.map

package/dist/gateway/x402-opener-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-opener-mode.d.ts","sourceRoot":"","sources":["../../src/gateway/x402-opener-mode.ts"],"names":[],"mappings":"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"}