@stellar-agent-services/provider-kit 0.0.0-stage → 0.1.1

package/dist/manifest.d.ts

@@ -0,0 +1,11 @@
+import { type ProviderManifest, type RuleViolation } from "@stellar-agent-services/protocol";
+import type { Service } from "./define-service.js";
+import type { ProviderConfig } from "./provider.js";
+export declare const DEFAULT_MAX_TIMEOUT_SECONDS = 60;
+export declare function buildManifest(config: ProviderConfig, services: readonly Service[]): ProviderManifest;
+/**
+ * Every violation a client or verifier would find in this manifest, served from `manifestUrl`
+ * (§2.4). With `dev`, a loopback http:// provider is checked as if it were served over HTTPS [M6].
+ */
+export declare function checkManifest(manifest: ProviderManifest, manifestUrl: string, dev?: boolean): RuleViolation[];
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAOA,OAAO,EAML,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAEnB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,gBAAgB,CAwBpG;AAyBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,UAAQ,GAAG,aAAa,EAAE,CAqB3G"}

package/dist/manifest.js

@@ -0,0 +1,99 @@
+// Builds the Provider Standard v1 manifest from the provider config, and checks it at startup.
+//
+// The payment option and every URL come from the same config, so the 402 challenge and the manifest
+// can never disagree. createProvider() refuses to start with a manifest that fails the manifest JSON
+// Schema [M9] or checkManifestRules() (§2.4): what a client or verifier would reject is caught before
+// anyone can pay. The router serves it with Cache-Control max-age=300 [M4].
+import { checkManifestRules, PROVIDER_STANDARD, USDC_ASSET, } from "@stellar-agent-services/protocol";
+import schema from "@stellar-agent-services/protocol/manifest.schema.json" with { type: "json" };
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { laneFor } from "./jobs/scheduler.js";
+export const DEFAULT_MAX_TIMEOUT_SECONDS = 60;
+export function buildManifest(config, services) {
+    const maxTimeoutSeconds = config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS;
+    const manifest = {
+        standard: PROVIDER_STANDARD,
+        provider: config.provider,
+        baseUrl: config.baseUrl.replace(/\/+$/, ""),
+        payment: {
+            protocol: "x402",
+            x402Version: 2,
+            accepts: [
+                {
+                    scheme: "exact",
+                    network: config.network,
+                    asset: USDC_ASSET[config.network],
+                    payTo: config.payTo,
+                    maxTimeoutSeconds,
+                    extra: { areFeesSponsored: true },
+                },
+            ],
+        },
+        services: services.map((service) => describe(service, maxTimeoutSeconds)),
+    };
+    if (config.retentionSeconds !== undefined)
+        manifest.jobs = { retentionSeconds: config.retentionSeconds };
+    return manifest;
+}
+function describe(service, maxTimeoutSeconds) {
+    const descriptor = {
+        name: service.name,
+        description: service.description,
+        price: { amount: service.amount },
+        charge: service.charge,
+        inputSchema: service.inputSchema,
+        outputSchema: service.outputSchema,
+    };
+    if (service.title !== undefined)
+        descriptor.title = service.title;
+    if (service.expectedDurationSeconds !== undefined)
+        descriptor.expectedDurationSeconds = service.expectedDurationSeconds;
+    if (service.examples !== undefined)
+        descriptor.examples = service.examples;
+    if (service.tags !== undefined)
+        descriptor.tags = service.tags;
+    if (service.maxInputBytes !== undefined)
+        descriptor.maxInputBytes = service.maxInputBytes;
+    // What the lane enforces, so the hint matches the 503s [Q2].
+    const lane = laneFor(service, maxTimeoutSeconds);
+    descriptor.capacity = { concurrency: lane.concurrency, maxQueueWaitSeconds: lane.maxQueued === 0 ? 0 : lane.maxWaitSeconds };
+    return descriptor;
+}
+const validateSchema = new Ajv2020({ strict: false, allErrors: true, validateFormats: false }).compile(schema);
+const examples = new Ajv2020({ strict: false, validateFormats: false });
+/**
+ * Every violation a client or verifier would find in this manifest, served from `manifestUrl`
+ * (§2.4). With `dev`, a loopback http:// provider is checked as if it were served over HTTPS [M6].
+ */
+export function checkManifest(manifest, manifestUrl, dev = false) {
+    const local = dev && isLoopback(manifestUrl);
+    const https = (url) => (local && url !== undefined && isLoopback(url) ? url.replace(/^http:/, "https:") : url);
+    const checked = structuredClone(manifest);
+    checked.baseUrl = https(checked.baseUrl);
+    for (const field of ["homepage", "termsUrl"]) {
+        const url = https(checked.provider[field]);
+        if (url !== undefined)
+            checked.provider[field] = url;
+    }
+    const violations = [];
+    if (!validateSchema(checked)) {
+        for (const error of validateSchema.errors ?? []) {
+            violations.push({ rule: "M9", pointer: error.instancePath, message: error.message ?? "does not match the manifest JSON Schema" });
+        }
+        return violations;
+    }
+    return checkManifestRules(checked, {
+        manifestUrl: https(manifestUrl),
+        validateExample: (exampleSchema, value) => examples.validate(exampleSchema, value),
+    });
+}
+function isLoopback(url) {
+    try {
+        const { protocol, hostname } = new URL(url);
+        return protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(hostname);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

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

package/dist/payments/chain.d.ts

@@ -0,0 +1,23 @@
+import { type StellarNetwork } from "@stellar-agent-services/protocol";
+import { rpc } from "@stellar/stellar-sdk";
+/** The RPC calls the kit makes: an rpc.Server, or a fake chain in tests. */
+export type ChainReader = Pick<rpc.Server, "getLatestLedger" | "getLedgers" | "getHealth" | "getEvents" | "getTransaction">;
+/**
+ * A Soroban RPC client for `network`: `url`, or the public default. Undefined when there is none, as on
+ * pubnet, where SDF runs no public RPC.
+ */
+export declare function rpcChain(network: StellarNetwork, url?: string, options?: {
+    dev?: boolean;
+}): ChainReader | undefined;
+export interface LedgerClock {
+    /** The latest closed ledger. */
+    latest(): Promise<number>;
+    /** When `ledger` closes, or closed: an estimate, in epoch ms. */
+    closesAt(ledger: number): Promise<number>;
+}
+/**
+ * A clock on `chain`'s ledgers. Readings are cached for a few seconds, and a failed reading rejects
+ * until the next one is due: callers fall back to wall-clock deadlines meanwhile.
+ */
+export declare function ledgerClock(chain: Pick<ChainReader, "getLatestLedger" | "getLedgers">): LedgerClock;
+//# sourceMappingURL=chain.d.ts.map

package/dist/payments/chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.ts","sourceRoot":"","sources":["../../src/payments/chain.ts"],"names":[],"mappings":"AAaA,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACxF,OAAO,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAE3C,4EAA4E;AAC5E,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,gBAAgB,CAAC,CAAC;AAK5H;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,WAAW,GAAG,SAAS,CASxH;AAED,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3C;AAqBD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,iBAAiB,GAAG,YAAY,CAAC,GAAG,WAAW,CAsDnG"}

package/dist/payments/chain.js

@@ -0,0 +1,108 @@
+// Reading the chain: the Soroban RPC calls the kit makes, and a ledger clock.
+//
+// The provider still holds no key and sends nothing; it only reads. Two things need the chain:
+// - Reconciliation (payments/onchain.ts, jobs/reconcile.ts): a payment_uncertain job is decided from
+//   the transactions that did, or did not, use its payment [J13].
+// - The ledger clock. A signed payment is valid up to a ledger, not a time [S2]. The clock turns a
+//   ledger into an estimated time, from the latest ledger's close time and the recent average ledger
+//   duration, so an on-success job's deadline follows its payment however late the client sent it
+//   [Q8], and a sweep can tell for sure that a payment expired.
+//
+// Reads go through Soroban RPC, the same server the facilitator and the payment client use. The URL is
+// HTTPS (http://localhost only in development), like the facilitator's.
+import { SOROBAN_RPC_URL } from "@stellar-agent-services/protocol";
+import { rpc } from "@stellar/stellar-sdk";
+/** An RPC call that takes longer fails, and reconciliation tries again on its next round. */
+const RPC_TIMEOUT_MS = 15_000;
+/**
+ * A Soroban RPC client for `network`: `url`, or the public default. Undefined when there is none, as on
+ * pubnet, where SDF runs no public RPC.
+ */
+export function rpcChain(network, url, options = {}) {
+    const target = url ?? SOROBAN_RPC_URL[network];
+    if (target === undefined)
+        return undefined;
+    const base = new URL(target);
+    const loopback = base.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(base.hostname);
+    if (base.protocol !== "https:" && !(options.dev && loopback)) {
+        throw new TypeError("the Soroban RPC URL must be https:// (http://localhost is allowed with dev: true)");
+    }
+    return new rpc.Server(target, { timeout: RPC_TIMEOUT_MS, allowHttp: loopback });
+}
+/** Ledgers the average duration is measured over: about eight minutes. */
+const SAMPLE_LEDGERS = 100;
+/** Used when no sample can be read, or a sample looks wrong. Stellar closes a ledger about every 5 s. */
+const DEFAULT_LEDGER_MS = 5000;
+/** How long a reading is used before the chain is read again. */
+const CLOCK_CACHE_MS = 5000;
+/**
+ * How long a reading may take. Jobs and paid requests wait for the clock, so a slow RPC makes them
+ * fall back to their claim-time deadlines instead of waiting for it.
+ */
+const CLOCK_TIMEOUT_MS = 3000;
+/**
+ * A clock on `chain`'s ledgers. Readings are cached for a few seconds, and a failed reading rejects
+ * until the next one is due: callers fall back to wall-clock deadlines meanwhile.
+ */
+export function ledgerClock(chain) {
+    let reading;
+    let readAt = 0;
+    let failing = false;
+    const read = async () => {
+        const latest = await chain.getLatestLedger();
+        let sequence = latest.sequence;
+        let closedAt = Number(latest.closeTime) * 1000;
+        let ledgerMs = DEFAULT_LEDGER_MS;
+        try {
+            const sample = await chain.getLedgers({ startLedger: Math.max(1, sequence - SAMPLE_LEDGERS), pagination: { limit: 1 } });
+            const first = sample.ledgers[0];
+            if (first !== undefined && sample.latestLedger > first.sequence) {
+                const measured = ((sample.latestLedgerCloseTime - Number(first.ledgerCloseTime)) * 1000) / (sample.latestLedger - first.sequence);
+                if (measured >= 1000 && measured <= 60_000)
+                    ledgerMs = measured;
+            }
+            sequence = sample.latestLedger;
+            closedAt = sample.latestLedgerCloseTime * 1000;
+        }
+        catch {
+            // The latest ledger alone is enough, with the default duration.
+        }
+        // An RPC that does not report close times: the latest ledger closed within the last few seconds.
+        if (!Number.isFinite(closedAt) || closedAt <= 0)
+            closedAt = Date.now();
+        return { sequence, closedAt, ledgerMs };
+    };
+    const current = () => {
+        if (reading === undefined || Date.now() - readAt >= CLOCK_CACHE_MS) {
+            readAt = Date.now();
+            reading = withTimeout(read(), CLOCK_TIMEOUT_MS).then((value) => {
+                failing = false;
+                return value;
+            }, (error) => {
+                if (!failing)
+                    console.warn(`[provider-kit] the ledger clock can't read the chain; deadlines fall back to claim times: ${error.message}`);
+                failing = true;
+                throw error;
+            });
+            // Callers catch it; this keeps an unobserved rejection from crashing the process.
+            reading.catch(() => undefined);
+        }
+        return reading;
+    };
+    return {
+        latest: async () => (await current()).sequence,
+        async closesAt(ledger) {
+            const { sequence, closedAt, ledgerMs } = await current();
+            return closedAt + (ledger - sequence) * ledgerMs;
+        },
+    };
+}
+function withTimeout(promise, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`no answer in ${ms} ms`)), ms);
+        timer.unref();
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+//# sourceMappingURL=chain.js.map

package/dist/payments/chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.js","sourceRoot":"","sources":["../../src/payments/chain.ts"],"names":[],"mappings":"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"}

package/dist/payments/facilitator.d.ts

@@ -0,0 +1,44 @@
+import type { StellarNetwork } from "@stellar-agent-services/protocol";
+import type { PaymentPayload, PaymentRequirements, SettleResponse } from "@x402/core/types";
+export interface VerifyResult {
+    isValid: boolean;
+    invalidReason?: string;
+    payer?: string;
+}
+export interface SupportedKind {
+    x402Version: number;
+    scheme: string;
+    network: string;
+    extra?: Record<string, unknown>;
+}
+/** The facilitator calls the provider makes. httpFacilitator() implements it; tests pass a fake. */
+export interface Facilitator {
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResult>;
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+    /** GET /supported. A fake may leave it out; the startup check is then skipped. */
+    supported?(): Promise<{
+        kinds: SupportedKind[];
+    }>;
+}
+export interface FacilitatorOptions {
+    /** Allows an http://localhost facilitator, for local development. */
+    dev?: boolean;
+    /** Default 20. */
+    verifyTimeoutSeconds?: number;
+    /** Default: the payment's maxTimeoutSeconds + 30, since settle waits for the transaction's ledger. */
+    settleTimeoutSeconds?: number;
+    /** Sent with every call, for facilitators that want an API key. Never a Stellar secret. */
+    headers?: Record<string, string>;
+}
+export declare class FacilitatorError extends Error {
+    name: string;
+}
+/** How long a settle call may take before the kit treats it as uncertain. */
+export declare function settleTimeoutSeconds(maxTimeoutSeconds: number, options?: FacilitatorOptions): number;
+export declare function httpFacilitator(url: string, options?: FacilitatorOptions): Facilitator;
+/**
+ * Startup check: the facilitator settles x402 v2 `exact` payments on the network, with fees
+ * sponsored as the manifest promises. Throws with the reason otherwise.
+ */
+export declare function checkFacilitator(facilitator: Facilitator, network: StellarNetwork): Promise<void>;
+//# sourceMappingURL=facilitator.d.ts.map

package/dist/payments/facilitator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facilitator.d.ts","sourceRoot":"","sources":["../../src/payments/facilitator.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAG5F,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,oGAAoG;AACpG,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC1F,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5F,kFAAkF;IAClF,SAAS,CAAC,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,kBAAkB;IAClB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sGAAsG;IACtG,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAChC,IAAI,SAAsB;CACpC;AAOD,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,iBAAiB,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,CAExG;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAgF1F;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvG"}

package/dist/payments/facilitator.js

@@ -0,0 +1,125 @@
+// The x402 facilitator: verifies and settles payments for the provider, which holds no secret key.
+//
+// httpFacilitator() is the kit's own client rather than @x402/core's HTTPFacilitatorClient, so that:
+// - the URL is HTTPS (http://localhost only in development) and redirects are refused, so a payment
+//   is never sent anywhere the operator did not configure;
+// - every call has a deadline. settle's waits for the transaction's ledger, so its default deadline is
+//   the payment's maxTimeoutSeconds plus a margin. A settle call that runs out of time is "uncertain",
+//   never "failed" (settlement.ts);
+// - only the fields a facilitator needs are sent, and its answers are size-bounded and shape-checked.
+// Testnet: https://x402.org/facilitator supports stellar:testnet + exact with sponsored fees.
+import { readBounded } from "../http/bounded.js";
+export class FacilitatorError extends Error {
+    name = "FacilitatorError";
+}
+const DEFAULT_VERIFY_TIMEOUT_SECONDS = 20;
+const SETTLE_TIMEOUT_MARGIN_SECONDS = 30;
+const SUPPORTED_TIMEOUT_SECONDS = 15;
+const MAX_RESPONSE_BYTES = 64 * 1024;
+/** How long a settle call may take before the kit treats it as uncertain. */
+export function settleTimeoutSeconds(maxTimeoutSeconds, options = {}) {
+    return options.settleTimeoutSeconds ?? maxTimeoutSeconds + SETTLE_TIMEOUT_MARGIN_SECONDS;
+}
+export function httpFacilitator(url, options = {}) {
+    const base = new URL(url);
+    const loopback = base.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(base.hostname);
+    if (base.protocol !== "https:" && !(options.dev && loopback)) {
+        throw new TypeError("the facilitator URL must be https:// (http://localhost is allowed with dev: true)");
+    }
+    if (base.username !== "" || base.password !== "" || base.search !== "" || base.hash !== "") {
+        throw new TypeError("the facilitator URL must not have user info, a query or a fragment");
+    }
+    const root = base.toString().replace(/\/+$/, "");
+    const call = async (path, init) => {
+        const response = await fetch(`${root}/${path}`, {
+            method: init.method,
+            headers: { Accept: "application/json", ...(init.body === undefined ? {} : { "Content-Type": "application/json" }), ...options.headers },
+            ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+            redirect: "error",
+            signal: AbortSignal.timeout(init.timeoutSeconds * 1000),
+        });
+        const bytes = await readBounded(response.body, MAX_RESPONSE_BYTES);
+        if (bytes === undefined)
+            throw new FacilitatorError(`${path} answered with more than ${MAX_RESPONSE_BYTES} bytes`);
+        const text = new TextDecoder().decode(bytes);
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new FacilitatorError(`${path} answered ${response.status} without JSON`);
+        }
+        return { status: response.status, body: isObject(body) ? body : {} };
+    };
+    // Only what the scheme needs: no resource description, no extensions.
+    const request = (payload, requirements) => ({
+        x402Version: 2,
+        paymentPayload: { x402Version: payload.x402Version, accepted: payload.accepted, payload: payload.payload },
+        paymentRequirements: requirements,
+    });
+    return {
+        async verify(payload, requirements) {
+            const { status, body } = await call("verify", {
+                method: "POST",
+                body: request(payload, requirements),
+                timeoutSeconds: options.verifyTimeoutSeconds ?? DEFAULT_VERIFY_TIMEOUT_SECONDS,
+            });
+            // A facilitator may answer an invalid payment with 400 and a verify body.
+            if (typeof body["isValid"] !== "boolean")
+                throw new FacilitatorError(`verify answered ${status}`);
+            const result = { isValid: body["isValid"] };
+            if (typeof body["invalidReason"] === "string")
+                result.invalidReason = body["invalidReason"];
+            if (typeof body["payer"] === "string")
+                result.payer = body["payer"];
+            return result;
+        },
+        async settle(payload, requirements) {
+            const { status, body } = await call("settle", {
+                method: "POST",
+                body: request(payload, requirements),
+                timeoutSeconds: settleTimeoutSeconds(requirements.maxTimeoutSeconds, options),
+            });
+            if (typeof body["success"] !== "boolean")
+                throw new FacilitatorError(`settle answered ${status}`);
+            const response = {
+                success: body["success"],
+                transaction: typeof body["transaction"] === "string" ? body["transaction"] : "",
+                network: (typeof body["network"] === "string" ? body["network"] : ""),
+            };
+            if (typeof body["payer"] === "string")
+                response.payer = body["payer"];
+            if (typeof body["errorReason"] === "string")
+                response.errorReason = body["errorReason"];
+            return response;
+        },
+        async supported() {
+            const { status, body } = await call("supported", { method: "GET", timeoutSeconds: SUPPORTED_TIMEOUT_SECONDS });
+            // The first call a provider makes, so a missing or wrong API key shows here, before any payment.
+            if (status === 401 || status === 403) {
+                throw new FacilitatorError(`supported answered ${status}: the facilitator wants an API key, such as an Authorization header (facilitatorHeaders in a gateway config), or refused the one sent`);
+            }
+            if (status !== 200 || !Array.isArray(body["kinds"]))
+                throw new FacilitatorError(`supported answered ${status}`);
+            return { kinds: body["kinds"].filter(isObject) };
+        },
+    };
+}
+/**
+ * Startup check: the facilitator settles x402 v2 `exact` payments on the network, with fees
+ * sponsored as the manifest promises. Throws with the reason otherwise.
+ */
+export async function checkFacilitator(facilitator, network) {
+    if (facilitator.supported === undefined)
+        return;
+    const { kinds } = await facilitator.supported();
+    const kind = kinds.find((candidate) => candidate.x402Version === 2 && candidate.scheme === "exact" && candidate.network === network);
+    if (kind === undefined)
+        throw new FacilitatorError(`the facilitator does not support x402 v2 "exact" payments on ${network}`);
+    if (kind.extra?.["areFeesSponsored"] !== true)
+        throw new FacilitatorError(`the facilitator does not sponsor fees on ${network}`);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=facilitator.js.map

package/dist/payments/facilitator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facilitator.js","sourceRoot":"","sources":["../../src/payments/facilitator.ts"],"names":[],"mappings":"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"}

package/dist/payments/onchain.d.ts

@@ -0,0 +1,36 @@
+import type { PaymentReceipt, StellarNetwork } from "@stellar-agent-services/protocol";
+import { rpc } from "@stellar/stellar-sdk";
+import type { PaymentClaim } from "../jobs/store.js";
+import type { ChainReader } from "./chain.js";
+export type PaymentLookup = {
+    outcome: "settled";
+    receipt: PaymentReceipt;
+} | {
+    outcome: "not_settled";
+    reason: string;
+} | {
+    outcome: "undecided";
+    reason: string;
+};
+export interface PaymentSearch {
+    chain: ChainReader;
+    network: StellarNetwork;
+    /** The asset contract the payment is in: the manifest's USDC SAC. */
+    asset: string;
+}
+/**
+ * How far before its expiration ledger a payment can land. The provider (http/router.ts) and the
+ * facilitator both refuse a signature that expires more than maxTimeoutSeconds (at most 300, §4.1) of
+ * ledgers after the payment is verified, counting a ledger as at least one second (they take about
+ * five), and a payment lands after its verification. So this window holds every ledger it could have
+ * landed in, with room to spare.
+ */
+export declare const SEARCH_WINDOW_LEDGERS = 320;
+/** Ledgers beyond the latest that a signature may expire in, on top of maxTimeoutSeconds. */
+export declare const EXPIRATION_TOLERANCE_LEDGERS = 10;
+/**
+ * Looks for the payment `claim` describes. `known` is a transaction the facilitator named. `health` is
+ * a recent getHealth() answer, to share one across many lookups; it is read when not given.
+ */
+export declare function findPayment(claim: PaymentClaim, known: string | undefined, search: PaymentSearch, health?: rpc.Api.GetHealthResponse): Promise<PaymentLookup>;
+//# sourceMappingURL=onchain.d.ts.map

package/dist/payments/onchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onchain.d.ts","sourceRoot":"","sources":["../../src/payments/onchain.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvF,OAAO,EAAW,GAAG,EAA8B,MAAM,sBAAsB,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,MAAM,MAAM,aAAa,GACrB;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GAC/C;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,cAAc,CAAC;IACxB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,6FAA6F;AAC7F,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAK/C;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,EAAE,aAAa,EACrB,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,iBAAiB,GACjC,OAAO,CAAC,aAAa,CAAC,CAqDxB"}