local402-facilitator 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diego Poveda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# local402-facilitator
+
+An [x402](https://x402.org) facilitator for Stellar that you run yourself. It verifies and settles
+`exact` payments (USDC and any Stellar token) and `exact-fx` payments (the payer spends XLM or EURC, the
+seller receives exact USDC through the FxPay contract), and pays the network fees from its own accounts.
+
+```bash
+npx local402-facilitator keys     # two fresh fee-paying testnet accounts, funded, written to .env
+npx local402-facilitator check    # config, RPC, balances and FxPay: exits 0 when it can settle
+npx local402-facilitator          # listens on :4022
+```
+
+Then point a seller at it: `local402Server("http://localhost:4022")` in `local402-server`, or any x402
+seller that takes a facilitator URL.
+
+Node 20.12 or later. A `Dockerfile` that installs this package from npm is in the
+[repository](https://github.com/DiegoPoveda01/local402/blob/main/packages/facilitator/Dockerfile).
+
+## What a public instance needs
+
+- **A seller allowlist and a minimum amount.** Every settlement spends this instance's XLM.
+  `PAY_TO_ALLOWLIST` limits it to the sellers you name; on `stellar:pubnet` it refuses to start without one.
+- **`TRUST_PROXY` set to the proxies really in front of it** (0 by default), so the limits count real clients.
+- **Separate limits for verify and settle**, per client per minute: verify only simulates, settle spends fees.
+- **Its own fee-paying keys.** Two instances sharing an account collide on its sequence number.
+- **`/health` for liveness and `/ready` for readiness.** `/ready` answers 503, saying which check failed,
+  when the RPC is down, a fee payer is below `MIN_FEE_BALANCE_XLM`, or FxPay is gone from the ledger.
+
+Every variable, the endpoints and the mainnet configuration:
+[docs/facilitator.md](https://github.com/DiegoPoveda01/local402/blob/main/docs/facilitator.md).
+Keys, funding, top-ups and rotation:
+[docs/facilitator-runbook.md](https://github.com/DiegoPoveda01/local402/blob/main/docs/facilitator-runbook.md).
+
+## As a library
+
+```ts
+import { createFacilitator, facilitatorConfig } from "local402-facilitator";
+
+const config = facilitatorConfig(process.env); // throws INVALID_CONFIG naming the variable, never a key
+const { app } = createFacilitator(config);     // an Express app
+app.listen(config.port);
+```
+
+MIT

package/dist/app.d.ts

@@ -0,0 +1 @@
+export declare const app: import("express").Express, feePayers: string[];

package/dist/app.js

@@ -0,0 +1,8 @@
+// The facilitator configured from this process's environment, for the Local402 deployment
+// (scripts/vercel/entry.ts) and the mainnet scripts. Other deployments run the `local402-facilitator` command.
+import { facilitatorConfig } from "./config.js";
+import { createFacilitator, describe } from "./facilitator.js";
+// Behind Vercel's edge: one proxy writes X-Forwarded-For, so the per-client limits see the real address.
+const config = facilitatorConfig({ ...process.env, TRUST_PROXY: process.env.TRUST_PROXY || "1" });
+export const { app, feePayers } = createFacilitator(config);
+console.log(describe(config, feePayers));

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// local402-facilitator: run a Local402 facilitator from environment variables (or a .env file in the
+// current directory). See docs/facilitator.md for every variable.
+//
+//   local402-facilitator                       start it
+//   local402-facilitator check                 check the config and the network, then exit (0 = ready)
+//   local402-facilitator keys [n] [--out f]    make n fee-paying accounts (default 2) into f (default .env),
+//                                              funded with friendbot on testnet. Prints only public keys.
+import { existsSync } from "node:fs";
+import { facilitatorConfig } from "./config.js";
+import { createFacilitator, describe } from "./facilitator.js";
+import { fundOnTestnet, newKeys, writeKeys } from "./keys.js";
+if (existsSync(".env"))
+    process.loadEnvFile(".env");
+const [command = "start", ...args] = process.argv.slice(2);
+function config() {
+    try {
+        return facilitatorConfig();
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+if (command === "start") {
+    const settings = config();
+    const { app, feePayers } = createFacilitator(settings);
+    console.log(describe(settings, feePayers));
+    const server = app.listen(settings.port, (error) => {
+        if (error)
+            throw error;
+        console.log(`Local402 facilitator on http://localhost:${settings.port} (fees paid by ${feePayers.join(", ")})`);
+    });
+    // Hosts stop an instance with SIGTERM: stop taking requests and let settlements in flight finish.
+    process.once("SIGTERM", () => server.close(() => process.exit(0)));
+}
+else if (command === "check") {
+    const settings = config();
+    const { feePayers, ready } = createFacilitator(settings);
+    console.log(describe(settings, feePayers));
+    const result = await ready();
+    const mark = (ok) => (ok ? "ok  " : "FAIL");
+    console.log(`${mark(result.rpc.ok)} RPC${result.rpc.error ? `: ${result.rpc.error}` : ""}`);
+    for (const payer of result.feePayers) {
+        console.log(`${mark(payer.ok)} fee payer ${payer.address}${payer.xlm ? ` ${payer.xlm} XLM` : ""}${payer.error ? `: ${payer.error}` : ""}`);
+    }
+    console.log(`${mark(result.fxContract.ok)} FxPay ${result.fxContract.address}${result.fxContract.error ? `: ${result.fxContract.error}` : ""}`);
+    console.log(result.ready ? "ready" : "not ready");
+    process.exit(result.ready ? 0 : 1);
+}
+else if (command === "keys") {
+    const out = args.includes("--out") ? args[args.indexOf("--out") + 1] : ".env";
+    if (!out || out.startsWith("-")) {
+        console.error("--out needs a file name, e.g. local402-facilitator keys 2 --out .env");
+        process.exit(1);
+    }
+    const count = Number(args.find((arg, i) => /^\d+$/.test(arg) && args[i - 1] !== "--out") ?? 2);
+    const network = process.env.NETWORK?.trim() || "stellar:testnet";
+    try {
+        const keys = newKeys(count);
+        writeKeys(out, keys.map((key) => key.secret()));
+        console.log(`Wrote ${count} fee-paying key(s) to ${out} as FACILITATOR_PRIVATE_KEYS (secrets are not printed).`);
+        for (const key of keys) {
+            if (network === "stellar:testnet") {
+                await fundOnTestnet(key.publicKey());
+                console.log(`${key.publicKey()} funded with friendbot`);
+            }
+            else {
+                console.log(`${key.publicKey()} send it XLM to create it (see the runbook for how much)`);
+            }
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+else {
+    console.error(`Unknown command ${command}. Use start, check or keys.`);
+    process.exit(1);
+}

package/dist/config.d.ts

@@ -0,0 +1,38 @@
+import type { Network } from "@x402/core/types";
+/** Everything a facilitator instance runs on, read once from the environment by `facilitatorConfig`. */
+export interface FacilitatorConfig {
+    network: Network;
+    /** Fee-paying accounts ("channels"), one per concurrent settlement. Never shared with another instance. */
+    secrets: string[];
+    fxContract: string;
+    sendAssets: string[];
+    rpcUrl?: string;
+    port: number;
+    /** Sellers this instance settles for. Empty means any seller, which only testnet allows. */
+    payToAllowlist: string[];
+    /** Tokens (C…) a seller may be paid in. Empty means any token, which only testnet allows. */
+    assetAllowlist: string[];
+    /** Smallest payment it settles, in token units (7 decimals: 100000 is 0.01 USDC). */
+    minAmount: bigint;
+    /** Requests per client per minute. Verify simulates on RPC; settle spends this instance's fees. */
+    limits: {
+        verify: number;
+        settle: number;
+    };
+    /** Below this many XLM a fee payer makes `/ready` fail, so the host stops routing to it before it runs dry. */
+    minFeeBalanceXlm: number;
+    /** Proxies in front of the instance whose `X-Forwarded-For` it believes, for per-client limits. */
+    trustProxy: number;
+    /** Upstash Redis over REST, where the Bazaar catalog survives restarts. Without it the catalog lives in memory. */
+    catalogRedis?: {
+        url: string;
+        token: string;
+    };
+}
+type Env = Record<string, string | undefined>;
+/**
+ * Reads and checks a facilitator's environment. Every mistake throws `INVALID_CONFIG` naming the variable and what
+ * it accepts, so a bad deploy fails at startup instead of on the first payment. Secret keys are never repeated.
+ */
+export declare function facilitatorConfig(env?: Env): FacilitatorConfig;
+export {};

package/dist/config.js

@@ -0,0 +1,105 @@
+import { StrKey } from "@stellar/stellar-sdk";
+import { FX_MAINNET, fxNetwork, Local402Error } from "local402-fx";
+const SECRET_KEY_SHAPE = /^S[A-Z2-7]{55}$/;
+function invalid(message) {
+    throw new Local402Error("INVALID_CONFIG", message);
+}
+/** A value for an error message, never a secret key: these messages end up in logs. */
+const shown = (value) => (SECRET_KEY_SHAPE.test(value) ? "a secret key (not shown)" : value);
+function list(value) {
+    return (value ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+}
+function whole(env, name, fallback, min, max = Number.MAX_SAFE_INTEGER) {
+    const raw = env[name]?.trim();
+    if (!raw)
+        return fallback;
+    const value = Number(raw);
+    if (!/^\d+$/.test(raw) || value < min || value > max) {
+        const range = max === Number.MAX_SAFE_INTEGER ? `at least ${min}` : `from ${min} to ${max}`;
+        invalid(`${name} must be a whole number ${range}, got ${shown(raw)}.`);
+    }
+    return value;
+}
+/**
+ * Reads and checks a facilitator's environment. Every mistake throws `INVALID_CONFIG` naming the variable and what
+ * it accepts, so a bad deploy fails at startup instead of on the first payment. Secret keys are never repeated.
+ */
+export function facilitatorConfig(env = process.env) {
+    const network = (env.NETWORK?.trim() || "stellar:testnet");
+    if (network !== "stellar:testnet" && network !== "stellar:pubnet") {
+        invalid(`NETWORK must be stellar:testnet or stellar:pubnet, got ${shown(network)}.`);
+    }
+    const mainnet = network === "stellar:pubnet";
+    const secrets = list(env.FACILITATOR_PRIVATE_KEYS || env.FACILITATOR_PRIVATE_KEY);
+    if (!secrets.length) {
+        invalid("FACILITATOR_PRIVATE_KEYS is required: one or more fee-paying Stellar secret keys (S…), comma-separated. `local402-facilitator keys` makes them.");
+    }
+    secrets.forEach((secret, i) => {
+        if (!StrKey.isValidEd25519SecretSeed(secret)) {
+            const what = StrKey.isValidEd25519PublicKey(secret) ? "a public key; it needs the secret (S…)" : "not a Stellar secret key (S…)";
+            invalid(`FACILITATOR_PRIVATE_KEYS entry ${i + 1} is ${what}.`);
+        }
+    });
+    if (new Set(secrets).size !== secrets.length) {
+        invalid("FACILITATOR_PRIVATE_KEYS repeats a key: two channels on one account race for its sequence number.");
+    }
+    const fxContract = env.FX_CONTRACT?.trim() || undefined;
+    if (fxContract && !StrKey.isValidContract(fxContract))
+        invalid(`FX_CONTRACT must be a contract address (C…), got ${shown(fxContract)}.`);
+    const fx = fxNetwork(network, fxContract);
+    if (!fx.fxContract) {
+        invalid(`FX_CONTRACT (the FxPay deployment) is required on ${network}: Local402's verified one is CA6Z4E55YN6LZEXBQPFCWUIMUJGAV42RLHYWWZ6SNIP4E73R2I2PUGHD, or deploy your own (docs/facilitator.md).`);
+    }
+    const sendAssets = list(env.SEND_ASSETS);
+    for (const asset of sendAssets) {
+        if (!StrKey.isValidContract(asset))
+            invalid(`SEND_ASSETS must list token contract addresses (C…), got ${shown(asset)}.`);
+    }
+    const rpcUrl = env.RPC_URL?.trim() || fx.rpcUrl;
+    // Not repeated: an RPC URL can carry an API key.
+    if (rpcUrl && !/^https?:\/\/[^\s]+$/.test(rpcUrl))
+        invalid("RPC_URL must be an http(s) URL.");
+    // On mainnet every settlement spends real fees, so this instance only settles for sellers it names.
+    // `PAY_TO` is the demo seller that shares one process with the facilitator on the Local402 deployment.
+    // An empty PAY_TO_ALLOWLIST (as `.env.example` ships it) counts as unset, not as "any seller".
+    const payToAllowlist = list(env.PAY_TO_ALLOWLIST?.trim() || (mainnet ? env.PAY_TO : ""));
+    for (const payTo of payToAllowlist) {
+        if (!StrKey.isValidEd25519PublicKey(payTo) && !StrKey.isValidContract(payTo)) {
+            invalid(`PAY_TO_ALLOWLIST must list seller addresses (G… or C…), got ${shown(payTo)}.`);
+        }
+    }
+    if (mainnet && !payToAllowlist.length) {
+        invalid("PAY_TO_ALLOWLIST is required on stellar:pubnet: every settlement spends this facilitator's XLM, so it only settles for the sellers you list (G…, comma-separated).");
+    }
+    // The caller writes the requirements, token included, so without this list a token anyone can mint for free
+    // would meet MIN_AMOUNT and an allowlisted seller's "payments" in it would spend this instance's fees.
+    const assetAllowlist = list(env.ASSET_ALLOWLIST?.trim() || (mainnet ? [FX_MAINNET.usdc.contract, FX_MAINNET.xlm, FX_MAINNET.eurc.contract].join(",") : ""));
+    for (const asset of assetAllowlist) {
+        if (!StrKey.isValidContract(asset))
+            invalid(`ASSET_ALLOWLIST must list token contract addresses (C…), got ${shown(asset)}.`);
+    }
+    const minAmountRaw = env.MIN_AMOUNT?.trim() || (mainnet ? "100000" : "0");
+    if (!/^\d+$/.test(minAmountRaw))
+        invalid(`MIN_AMOUNT must be a whole number of token units (100000 is 0.01 USDC), got ${shown(minAmountRaw)}.`);
+    const minFeeBalanceXlm = Number(env.MIN_FEE_BALANCE_XLM?.trim() || "2");
+    if (!Number.isFinite(minFeeBalanceXlm) || minFeeBalanceXlm < 0)
+        invalid(`MIN_FEE_BALANCE_XLM must be a number of XLM, got ${shown(env.MIN_FEE_BALANCE_XLM ?? "")}.`);
+    // Vercel's Upstash integration names them KV_REST_API_*; Upstash itself, UPSTASH_REDIS_REST_*.
+    const redisUrl = env.KV_REST_API_URL?.trim() || env.UPSTASH_REDIS_REST_URL?.trim();
+    const redisToken = env.KV_REST_API_TOKEN?.trim() || env.UPSTASH_REDIS_REST_TOKEN?.trim();
+    return {
+        network,
+        secrets,
+        fxContract: fx.fxContract,
+        sendAssets: sendAssets.length ? sendAssets : [fx.xlm, fx.eurc],
+        rpcUrl,
+        port: whole(env, "PORT", 4022, 1, 65_535),
+        payToAllowlist,
+        assetAllowlist,
+        minAmount: BigInt(minAmountRaw),
+        limits: { verify: whole(env, "VERIFY_RATE_LIMIT", 60, 1), settle: whole(env, "SETTLE_RATE_LIMIT", 20, 1) },
+        minFeeBalanceXlm,
+        trustProxy: whole(env, "TRUST_PROXY", 0, 0, 10),
+        catalogRedis: redisUrl && redisToken ? { url: redisUrl, token: redisToken } : undefined,
+    };
+}

package/dist/facilitator.d.ts

@@ -0,0 +1,29 @@
+import { type Express } from "express";
+import type { FacilitatorConfig } from "./config.js";
+import { type Readiness, type ReadinessProbe } from "./ready.js";
+/** Per-client request caps per minute, counted separately for each route. */
+export declare class RateLimiter<Route extends string> {
+    private readonly limits;
+    private readonly now;
+    private readonly windows;
+    constructor(limits: Record<Route, number>, now?: () => number);
+    allow(route: Route, client: string | undefined): boolean;
+}
+/** Why this facilitator refuses to handle the requirements, if it does. */
+export declare function refusal(body: unknown, config: Pick<FacilitatorConfig, "network" | "payToAllowlist" | "assetAllowlist" | "minAmount">): string | undefined;
+export interface Facilitator {
+    app: Express;
+    /** The fee-paying accounts' public keys, in the order of `FACILITATOR_PRIVATE_KEYS`. */
+    feePayers: string[];
+    /** Runs the `/ready` checks now, without the cache. */
+    ready(): Promise<Readiness>;
+}
+/**
+ * The Local402 facilitator as an Express app: `exact` and `exact-fx` on one Stellar network, the x402 Bazaar
+ * catalog, `/health` and `/ready`. Build the config with `facilitatorConfig`; `probe` replaces the RPC in tests.
+ */
+export declare function createFacilitator(config: FacilitatorConfig, options?: {
+    probe?: ReadinessProbe;
+}): Facilitator;
+/** The startup line: what this instance settles, without any key. */
+export declare function describe(config: FacilitatorConfig, feePayers: string[]): string;

package/dist/facilitator.js

@@ -0,0 +1,226 @@
+import express from "express";
+import { x402Facilitator } from "@x402/core/facilitator";
+import { BAZAAR, extractDiscoveryInfo } from "@x402/extensions/bazaar";
+import { createEd25519Signer, getRpcClient } from "@x402/stellar";
+import { ExactStellarScheme } from "@x402/stellar/exact/facilitator";
+import { ChannelPool, ExactFxFacilitatorScheme, feeBumpSigner } from "local402-fx";
+import { readiness, rpcProbe } from "./ready.js";
+/** How long `/ready` reuses its last answer, so a host polling it every few seconds does not hammer the RPC. */
+const READY_CACHE_MS = 15_000;
+/** Per-client request caps per minute, counted separately for each route. */
+export class RateLimiter {
+    limits;
+    now;
+    windows = new Map();
+    constructor(limits, now = Date.now) {
+        this.limits = limits;
+        this.now = now;
+    }
+    allow(route, client) {
+        const minute = Math.floor(this.now() / 60_000);
+        const key = `${route}:${client}`;
+        const window = this.windows.get(key);
+        if (window?.minute === minute) {
+            window.count++;
+            return window.count <= this.limits[route];
+        }
+        // Drop the entries that expired, not the whole map: clearing it handed every client already over the
+        // cap a fresh allowance, which is exactly what an attacker filling the map with fake IPs would want.
+        if (this.windows.size > 1_000) {
+            for (const [other, seen] of this.windows)
+                if (seen.minute !== minute)
+                    this.windows.delete(other);
+        }
+        this.windows.set(key, { minute, count: 1 });
+        return true;
+    }
+}
+/** Why this facilitator refuses to handle the requirements, if it does. */
+export function refusal(body, config) {
+    // `x402Facilitator.verify/settle` does not validate the body's shape, and neither did this: a payload
+    // of the wrong type reached the scheme and came back as an opaque crash instead of a reason.
+    if (!body || typeof body !== "object")
+        return "invalid_request_body";
+    const { paymentPayload, paymentRequirements } = body;
+    if (!paymentPayload || typeof paymentPayload !== "object")
+        return "invalid_payment_payload";
+    if (!paymentRequirements || typeof paymentRequirements !== "object")
+        return "invalid_payment_requirements";
+    const { scheme, network, payTo, asset, amount } = paymentRequirements;
+    if (typeof scheme !== "string" || typeof network !== "string" || typeof payTo !== "string" || typeof asset !== "string") {
+        return "invalid_payment_requirements";
+    }
+    if (network !== config.network)
+        return "unsupported_network";
+    if (config.payToAllowlist.length && !config.payToAllowlist.includes(payTo))
+        return "pay_to_not_allowed";
+    if (config.assetAllowlist.length && !config.assetAllowlist.includes(asset))
+        return "asset_not_allowed";
+    if (!/^\d+$/.test(String(amount)))
+        return "invalid_payment_requirements";
+    if (config.minAmount && BigInt(String(amount)) < config.minAmount)
+        return "amount_below_minimum";
+    return undefined;
+}
+/**
+ * The Local402 facilitator as an Express app: `exact` and `exact-fx` on one Stellar network, the x402 Bazaar
+ * catalog, `/health` and `/ready`. Build the config with `facilitatorConfig`; `probe` replaces the RPC in tests.
+ */
+export function createFacilitator(config, options = {}) {
+    const { network } = config;
+    const rpcConfig = config.rpcUrl ? { url: config.rpcUrl } : undefined;
+    // Bazaar catalog: every resource that settles here and declares discovery info, keyed by URL. Serverless instances
+    // start empty, so with Redis configured the catalog lives there; memory is the fallback.
+    const catalog = new Map();
+    const catalogKey = `local402:bazaar:${network}`;
+    const redisConfig = config.catalogRedis;
+    /** One command over Upstash's REST API. */
+    const redis = async (...command) => {
+        const response = await fetch(redisConfig.url, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${redisConfig.token}` },
+            body: JSON.stringify(command),
+        });
+        if (!response.ok)
+            throw new Error(`Redis ${response.status}`);
+        return (await response.json()).result;
+    };
+    // Several fee-paying accounts ("channels") let settlements run in parallel without sequence number clashes.
+    const signers = config.secrets.map((secret) => createEd25519Signer(secret, network));
+    const feePayers = signers.map((signer) => signer.address);
+    const channels = new ChannelPool(feePayers);
+    const facilitator = new x402Facilitator()
+        .register(network, new ExactStellarScheme(signers, {
+        rpcConfig,
+        selectSigner: channels.select,
+        feeBumpSigner: feeBumpSigner(signers[0], { network, rpcConfig }),
+    }))
+        .register(network, new ExactFxFacilitatorScheme(signers, { fxContract: config.fxContract, sendAssets: config.sendAssets, rpcConfig, selectSigner: channels.select }))
+        .registerExtension(BAZAAR)
+        .onAfterSettle(async ({ paymentPayload, requirements, result }) => {
+        const discovered = result.success && extractDiscoveryInfo(paymentPayload, requirements);
+        if (!discovered)
+            return;
+        const { resourceUrl, x402Version, discoveryInfo, ...metadata } = discovered;
+        // Another instance may have stored the route's other scheme; keep it.
+        let previous = catalog.get(resourceUrl);
+        if (!previous && redisConfig) {
+            previous = await redis("HGET", catalogKey, resourceUrl).then((value) => (typeof value === "string" ? JSON.parse(value) : undefined), () => undefined);
+        }
+        const accepts = (previous?.accepts ?? []).filter((a) => a.scheme !== requirements.scheme);
+        const entry = {
+            ...metadata,
+            resource: resourceUrl,
+            type: discoveryInfo.input.type,
+            x402Version,
+            accepts: [...accepts, requirements],
+            lastUpdated: new Date().toISOString(),
+        };
+        catalog.set(resourceUrl, entry);
+        // The payment has settled by now: a Redis failure only costs the catalog entry, never the result.
+        if (redisConfig) {
+            await redis("HSET", catalogKey, resourceUrl, JSON.stringify(entry)).catch(() => console.warn("bazaar: could not save the catalog entry to Redis"));
+        }
+    });
+    // Verification simulates on RPC and settlement spends fees, so both are bounded, each with its own cap.
+    const limiter = new RateLimiter(config.limits);
+    const probe = options.probe ?? rpcProbe(getRpcClient(network, rpcConfig));
+    const ready = () => readiness(probe, { network, feePayers, fxContract: config.fxContract, minFeeBalanceXlm: config.minFeeBalanceXlm });
+    let lastReady;
+    const app = express();
+    // By default exactly one proxy (Vercel's edge, or a host's load balancer). With `true`, express takes the
+    // leftmost `X-Forwarded-For` entry, which the client writes itself: every caller could pick its own
+    // `req.ip` and get an unlimited number of rate-limit buckets.
+    app.set("trust proxy", config.trustProxy);
+    app.use(express.json({ limit: "64kb" }));
+    // Liveness: the process is up and its configuration was valid. Says nothing about the network.
+    app.get("/health", (_req, res) => {
+        res.json({ status: "ok", network });
+    });
+    // Readiness: this instance can settle now. 503 tells the host to stop routing payments here.
+    app.get("/ready", async (_req, res) => {
+        if (!lastReady || Date.now() - lastReady.at > READY_CACHE_MS)
+            lastReady = { at: Date.now(), result: ready() };
+        const result = await lastReady.result;
+        res.status(result.ready ? 200 : 503).json(result);
+    });
+    app.get("/supported", (_req, res) => {
+        res.json(facilitator.getSupported());
+    });
+    app.get("/discovery/resources", async (req, res) => {
+        let all = [...catalog.values()];
+        if (redisConfig) {
+            try {
+                all = (await redis("HVALS", catalogKey)).map((value) => JSON.parse(value));
+            }
+            catch {
+                console.warn("bazaar: could not read the catalog from Redis, serving this instance's copy");
+            }
+        }
+        const items = all.filter((item) => !req.query.type || item.type === req.query.type);
+        const limit = Number(req.query.limit ?? 100);
+        const offset = Number(req.query.offset ?? 0);
+        res.json({ x402Version: 2, items: items.slice(offset, offset + limit), pagination: { limit, offset, total: items.length } });
+    });
+    app.post("/verify", async (req, res) => {
+        if (!limiter.allow("verify", req.ip)) {
+            res.status(429).json({ isValid: false, invalidReason: "rate_limited" });
+            return;
+        }
+        const { paymentPayload, paymentRequirements } = req.body ?? {};
+        const refused = refusal(req.body, config);
+        if (refused) {
+            res.json({ isValid: false, invalidReason: refused });
+            return;
+        }
+        let result;
+        try {
+            result = await facilitator.verify(paymentPayload, paymentRequirements);
+        }
+        catch (error) {
+            // Same as settle: a reason the seller can log, not Express's HTML error page with a stack trace.
+            res.status(503).json({ isValid: false, invalidReason: String(error) });
+            return;
+        }
+        console.log(`verify ${paymentRequirements?.scheme}: ${result.isValid ? "valid" : result.invalidReason}`);
+        res.json(result);
+    });
+    app.post("/settle", async (req, res) => {
+        const { paymentPayload, paymentRequirements } = req.body ?? {};
+        if (!limiter.allow("settle", req.ip)) {
+            res.status(429).json({ success: false, network: paymentRequirements?.network, transaction: "", errorReason: "rate_limited" });
+            return;
+        }
+        const refused = refusal(req.body, config);
+        if (refused) {
+            res.json({ success: false, network: paymentRequirements?.network, transaction: "", errorReason: refused });
+            return;
+        }
+        const settle = () => channels.run(() => facilitator.settle(paymentPayload, paymentRequirements));
+        let result;
+        try {
+            result = await settle();
+            // Rejected before reaching the ledger (e.g. another server instance used the same account's sequence number):
+            // nothing was spent, and the payer's authorization is still valid, so try once more on the next account.
+            if (!result.success && !result.transaction && /submission_failed/.test(result.errorReason ?? "")) {
+                result = await settle();
+            }
+        }
+        catch (error) {
+            res.status(503).json({ success: false, network: paymentRequirements?.network, transaction: "", errorReason: String(error) });
+            return;
+        }
+        console.log(`settle ${paymentRequirements?.scheme}: ${result.success ? result.transaction : result.errorReason}`);
+        res.json(result);
+    });
+    return { app, feePayers, ready };
+}
+/** The startup line: what this instance settles, without any key. */
+export function describe(config, feePayers) {
+    const { network, payToAllowlist, assetAllowlist, minAmount, limits } = config;
+    return (`facilitator on ${network}: ${feePayers.length} fee payer(s), ` +
+        `payTo ${payToAllowlist.length ? `restricted to ${payToAllowlist.length} seller(s)` : "unrestricted"}, ` +
+        `asset ${assetAllowlist.length ? `restricted to ${assetAllowlist.length} token(s)` : "unrestricted"}, ` +
+        `minimum amount ${minAmount || "none"}, ` +
+        `limits ${limits.verify} verify and ${limits.settle} settle per client per minute`);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { facilitatorConfig, type FacilitatorConfig } from "./config.js";
+export { createFacilitator, describe, RateLimiter, refusal, type Facilitator } from "./facilitator.js";
+export { readiness, rpcProbe, type Check, type Readiness, type ReadinessProbe } from "./ready.js";
+export { fundOnTestnet, newKeys, writeKeys } from "./keys.js";
+export { Local402Error, type Local402ErrorCode } from "local402-fx";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { facilitatorConfig } from "./config.js";
+export { createFacilitator, describe, RateLimiter, refusal } from "./facilitator.js";
+export { readiness, rpcProbe } from "./ready.js";
+export { fundOnTestnet, newKeys, writeKeys } from "./keys.js";
+export { Local402Error } from "local402-fx";

package/dist/keys.d.ts

@@ -0,0 +1,10 @@
+import { Keypair } from "@stellar/stellar-sdk";
+/** `count` fresh fee-paying accounts for one instance. Each instance gets its own: shared keys collide on sequence numbers. */
+export declare function newKeys(count: number): Keypair[];
+/**
+ * Writes `FACILITATOR_PRIVATE_KEYS` into an env file, creating it if needed. It never replaces keys already there,
+ * since they may hold funds; an empty `FACILITATOR_PRIVATE_KEYS=` line (as `.env.example` ships it) is filled in.
+ */
+export declare function writeKeys(file: string, secrets: string[]): void;
+/** Creates and funds `address` on testnet with friendbot's 10,000 test XLM. An account that already exists is fine. */
+export declare function fundOnTestnet(address: string, fetchFn?: typeof fetch): Promise<void>;

package/dist/keys.js

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { Keypair, StrKey } from "@stellar/stellar-sdk";
+import { Local402Error } from "local402-fx";
+/** `count` fresh fee-paying accounts for one instance. Each instance gets its own: shared keys collide on sequence numbers. */
+export function newKeys(count) {
+    if (!Number.isInteger(count) || count < 1 || count > 20) {
+        throw new Local402Error("INVALID_CONFIG", `The number of keys must be a whole number from 1 to 20, got ${count}.`);
+    }
+    return Array.from({ length: count }, () => Keypair.random());
+}
+/**
+ * Writes `FACILITATOR_PRIVATE_KEYS` into an env file, creating it if needed. It never replaces keys already there,
+ * since they may hold funds; an empty `FACILITATOR_PRIVATE_KEYS=` line (as `.env.example` ships it) is filled in.
+ */
+export function writeKeys(file, secrets) {
+    const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+    const existing = /^FACILITATOR_PRIVATE_KEYS?=(.*)$/gm;
+    for (const [, value] of text.matchAll(existing)) {
+        if (value.split(",").some((key) => StrKey.isValidEd25519SecretSeed(key.trim()))) {
+            throw new Local402Error("INVALID_CONFIG", `${file} already has facilitator keys. Move them out first: they may hold funds.`);
+        }
+    }
+    const entry = `FACILITATOR_PRIVATE_KEYS=${secrets.join(",")}`;
+    const line = /^FACILITATOR_PRIVATE_KEYS=.*$/m;
+    const next = line.test(text) ? text.replace(line, entry) : `${text}${text && !text.endsWith("\n") ? "\n" : ""}${entry}\n`;
+    writeFileSync(file, next, { mode: 0o600 });
+}
+/** Creates and funds `address` on testnet with friendbot's 10,000 test XLM. An account that already exists is fine. */
+export async function fundOnTestnet(address, fetchFn = fetch) {
+    const response = await fetchFn(`https://friendbot.stellar.org/?addr=${address}`, { signal: AbortSignal.timeout(30_000) });
+    if (response.ok)
+        return;
+    const body = await response.text();
+    if (/already.?exist/i.test(body))
+        return;
+    throw new Error(`friendbot answered ${response.status} for ${address}`);
+}

package/dist/ready.d.ts

@@ -0,0 +1,35 @@
+import { rpc } from "@stellar/stellar-sdk";
+/** What `/ready` asks the network. `rpcProbe` answers it over Soroban RPC; tests pass their own. */
+export interface ReadinessProbe {
+    rpcHealthy(): Promise<boolean>;
+    /** Native balance in stroops, or undefined when the account does not exist on the network. */
+    balanceStroops(address: string): Promise<bigint | undefined>;
+    contractExists(contract: string): Promise<boolean>;
+}
+export interface Check {
+    ok: boolean;
+    error?: string;
+}
+export interface Readiness {
+    ready: boolean;
+    network: string;
+    rpc: Check;
+    feePayers: (Check & {
+        address: string;
+        xlm?: string;
+    })[];
+    fxContract: Check & {
+        address: string;
+    };
+}
+export declare function rpcProbe(server: rpc.Server): ReadinessProbe;
+/**
+ * Whether this instance can settle right now: the RPC answers, every fee payer exists and holds at least
+ * `minFeeBalanceXlm`, and the FxPay contract is still on the ledger (its instance expires unless its TTL is extended).
+ */
+export declare function readiness(probe: ReadinessProbe, options: {
+    network: string;
+    feePayers: string[];
+    fxContract: string;
+    minFeeBalanceXlm: number;
+}): Promise<Readiness>;

package/dist/ready.js

@@ -0,0 +1,60 @@
+import { rpc, xdr } from "@stellar/stellar-sdk";
+export function rpcProbe(server) {
+    return {
+        rpcHealthy: async () => (await server.getHealth()).status === "healthy",
+        async balanceStroops(address) {
+            try {
+                return BigInt((await server.getAccountEntry(address)).balance().toString());
+            }
+            catch (error) {
+                if (/not found/i.test(String(error)))
+                    return undefined;
+                throw error;
+            }
+        },
+        async contractExists(contract) {
+            try {
+                await server.getContractData(contract, xdr.ScVal.scvLedgerKeyContractInstance(), rpc.Durability.Persistent);
+                return true;
+            }
+            catch (error) {
+                if (/not found/i.test(String(error)))
+                    return false;
+                throw error;
+            }
+        },
+    };
+}
+const STROOPS_PER_XLM = 10000000n;
+const xlm = (stroops) => `${stroops / STROOPS_PER_XLM}.${String(stroops % STROOPS_PER_XLM).padStart(7, "0")}`.replace(/\.?0+$/, "");
+const reason = (error) => (error instanceof Error ? error.message : String(error)).split("\n")[0].slice(0, 200);
+/**
+ * Whether this instance can settle right now: the RPC answers, every fee payer exists and holds at least
+ * `minFeeBalanceXlm`, and the FxPay contract is still on the ledger (its instance expires unless its TTL is extended).
+ */
+export async function readiness(probe, options) {
+    const min = BigInt(Math.round(options.minFeeBalanceXlm * 1e7));
+    const [rpcCheck, feePayers, fxContract] = await Promise.all([
+        probe.rpcHealthy().then((ok) => (ok ? { ok } : { ok, error: "RPC reports it is not healthy" }), (error) => ({ ok: false, error: reason(error) })),
+        Promise.all(options.feePayers.map(async (address) => {
+            try {
+                const balance = await probe.balanceStroops(address);
+                if (balance === undefined)
+                    return { address, ok: false, error: "account does not exist: fund it with XLM" };
+                const ok = balance >= min;
+                return { address, ok, xlm: xlm(balance), ...(ok ? {} : { error: `below the ${options.minFeeBalanceXlm} XLM minimum: top it up` }) };
+            }
+            catch (error) {
+                return { address, ok: false, error: reason(error) };
+            }
+        })),
+        probe.contractExists(options.fxContract).then((ok) => ({ address: options.fxContract, ok, ...(ok ? {} : { error: "FxPay contract not found: wrong FX_CONTRACT or its TTL expired" }) }), (error) => ({ address: options.fxContract, ok: false, error: reason(error) })),
+    ]);
+    return {
+        ready: rpcCheck.ok && feePayers.every((payer) => payer.ok) && fxContract.ok,
+        network: options.network,
+        rpc: rpcCheck,
+        feePayers,
+        fxContract,
+    };
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "local402-facilitator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Deployable x402 facilitator for Stellar: settles exact and exact-fx, with a seller allowlist, separate verify and settle limits, health and readiness",
+  "keywords": [
+    "x402",
+    "stellar",
+    "soroban",
+    "payments",
+    "usdc",
+    "oracle",
+    "mcp"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DiegoPoveda01/local402.git",
+    "directory": "packages/facilitator"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "local402-facilitator": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "local402-fx": "^1.0.1",
+    "@stellar/stellar-sdk": "16.4.1",
+    "@x402/core": "2.25.0",
+    "@x402/extensions": "2.25.0",
+    "@x402/stellar": "2.25.0",
+    "express": "^5.1.0"
+  }
+}