local402-facilitator 1.0.0 → 1.0.1

package/README.md

@@ -1,44 +1,44 @@
-# 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
+# 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/config.d.ts

@@ -23,6 +23,11 @@ export interface FacilitatorConfig {
     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>;
 /**

package/dist/config.js

@@ -84,6 +84,9 @@ export function facilitatorConfig(env = process.env) {
     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,
@@ -97,5 +100,6 @@ export function facilitatorConfig(env = process.env) {
         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.js

@@ -69,8 +69,22 @@ export function refusal(body, config) {
 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.
+    // 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);
@@ -88,15 +102,25 @@ export function createFacilitator(config, options = {}) {
         if (!discovered)
             return;
         const { resourceUrl, x402Version, discoveryInfo, ...metadata } = discovered;
-        const accepts = (catalog.get(resourceUrl)?.accepts ?? []).filter((a) => a.scheme !== requirements.scheme);
-        catalog.set(resourceUrl, {
+        // 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);
@@ -123,8 +147,17 @@ export function createFacilitator(config, options = {}) {
     app.get("/supported", (_req, res) => {
         res.json(facilitator.getSupported());
     });
-    app.get("/discovery/resources", (req, res) => {
-        const items = [...catalog.values()].filter((item) => !req.query.type || item.type === req.query.type);
+    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 } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local402-facilitator",
-  "version": "1.0.0",
+  "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",
@@ -35,8 +35,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "local402-fx": "^1.0.0",
-    "@stellar/stellar-sdk": "16.3.0",
+    "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",