@nano133/nanoterra 0.8.0 → 0.9.0

package/dist/shop/amount.js

@@ -0,0 +1,59 @@
+// Nano amounts for the shop, in raw. 1 XNO is 10^30 raw, more than a JavaScript number holds exactly, so amounts are decimal strings and the math is
+// BigInt. Never use a float for an amount that is paid or compared. (The game starter's src/shared/amount.ts, moved here unchanged.)
+//
+// Every order asks for a CLEAN amount: the price, rounded up to a step of 0.0001 XNO. While another held order has that exact amount, the next order
+// asks for one step more (./orders.ts). So an amount has at most four decimals. Wallets that shorten an amount (Cake Wallet cuts a link's amount to
+// 6 decimals; Natrium and Nautilus send 6 decimals when the payer touches the amount field) still send it exactly, and the payment matches its order.
+export { RAW_PER_XNO, xnoText } from "../admin/amount.js";
+/** One step: 0.0001 XNO. */
+export const STEP_RAW = 10n ** 26n;
+/** Sane bounds for dollars per XNO: outside them a price feed is wrong, not the market. */
+export const MIN_RATE = 0.05;
+export const MAX_RATE = 100;
+/** The highest price a look can have, in US dollars (the looks file allows up to PRICE_MAX_USD, $1000). */
+export const MAX_USD = 10_000;
+/** A raw amount: digits only, no leading zero, not zero, at most 39 digits. */
+export function isRaw(s) {
+    return typeof s === "string" && /^[1-9][0-9]{0,38}$/.test(s);
+}
+/** Whole steps of 0.0001 XNO, so at most four decimals. */
+export function isClean(raw) {
+    return isRaw(raw) && BigInt(raw) % STEP_RAW === 0n;
+}
+/**
+ * The number of 0.0001 XNO steps for `usd` dollars at `rate` dollars per XNO, rounded UP (the creator never gets less than the price), or null when
+ * the price or the rate can't be used.
+ */
+export function stepsFromUsd(usd, rate) {
+    if (!Number.isFinite(usd) || !Number.isFinite(rate) || usd <= 0 || usd > MAX_USD || rate < MIN_RATE || rate > MAX_RATE)
+        return null;
+    // A tiny allowance, so float noise (0.01 / 0.5 * 10000 = 200.00000000000003) doesn't add a whole step.
+    return Math.max(1, Math.ceil((usd / rate) * 10_000 - 1e-6));
+}
+export function rawFromSteps(steps) {
+    const n = BigInt(steps);
+    if (n <= 0n)
+        throw new Error("an amount must be above zero");
+    return (n * STEP_RAW).toString();
+}
+/** The clean price in raw, or null. */
+export function priceRaw(usd, rate) {
+    const steps = stepsFromUsd(usd, rate);
+    return steps === null ? null : rawFromSteps(steps);
+}
+/** A clean amount plus `more` steps. */
+export function plusSteps(raw, more) {
+    if (!isClean(raw))
+        throw new Error("not a clean amount");
+    return (BigInt(raw) + BigInt(more) * STEP_RAW).toString();
+}
+/** -1, 0 or 1. */
+export function compareRaw(a, b) {
+    const x = BigInt(a);
+    const y = BigInt(b);
+    return x < y ? -1 : x > y ? 1 : 0;
+}
+/** The standard payment link: the amount in raw, every digit (docs.nano.org, URI and QR code standards). */
+export function nanoUri(address, raw) {
+    return `nano:${address}?amount=${raw}`;
+}

package/dist/shop/conformance.d.ts

@@ -0,0 +1,13 @@
+import { type ShopStore } from "./store.js";
+export type ShopHarness = {
+    store: ShopStore;
+    /** Every row the store keeps (orders, owned looks, locks, recorded payments) as one text. `forget` must leave the player's id only where the money rules keep it. */
+    dump(): Promise<string>;
+};
+export type ShopConformanceCase = {
+    name: string;
+    run: () => Promise<void>;
+};
+/** A time per case that is plenty for a remote store (a case makes at most about 60 store calls; 25 of them at once in one case). */
+export declare const SHOP_CASE_TIMEOUT_MS = 60000;
+export declare function shopStoreConformance(make: () => Promise<ShopHarness>): ShopConformanceCase[];

package/dist/shop/conformance.js

@@ -0,0 +1,203 @@
+// The conformance suite of the shop's money rules: a game that writes its own store (another database) runs it, and so proves that its store keeps every
+// rule the package's adapters keep. The package runs it on the memory store, D1 (on SQLite) and Firestore.
+//
+//   import { shopStoreConformance, SHOP_CASE_TIMEOUT_MS } from "@nano133/nanoterra/shop/conformance";
+//   for (const c of shopStoreConformance(async () => ({ store: myStore(), dump: () => allMyRowsAsText() }))) it(c.name, c.run, SHOP_CASE_TIMEOUT_MS);
+//
+// Each case gets a NEW, empty store from `make`, and is short (a few store calls): give each its own test, never one test for the whole suite. The times
+// are fixed (no clock), the players are ids the suite can find in any text, and no case needs the network.
+import { CLOCK_SLACK_MS } from "./match.js";
+import { amountsFor, LATE_HOLD_MS, ORDER_TTL_MS, ShopBusy, newOrderId, reserveOrder } from "./orders.js";
+import { priceRaw, xnoText } from "./amount.js";
+import { FORGOTTEN } from "./store.js";
+/** A time per case that is plenty for a remote store (a case makes at most about 60 store calls; 25 of them at once in one case). */
+export const SHOP_CASE_TIMEOUT_MS = 60_000;
+function check(ok, message) {
+    if (!ok)
+        throw new Error(message);
+}
+/** A player id the suite can find in any text. */
+const id = (n) => `shop-player-${n}-3c9d`;
+const ANN = id("ann");
+const BOB = id("bob");
+const CYD = id("cyd");
+const T0 = 1_800_000_000_000;
+const PRICE = priceRaw(0.25, 1); // 0.25 XNO
+let hashes = 0;
+/** A new send hash: 64 hex characters, upper case (as the scan gives it). */
+const hash = () => (++hashes).toString(16).toUpperCase().padStart(8, "0").padEnd(64, "A");
+const order = (store, player = ANN, now = T0, price = PRICE, lookId = "look-a") => reserveOrder(store, { player, lookId, usd: "0.25", rate: 1, price, visitor: `visitor-of-${player}`, now });
+const pay = (store, o, seenMs, now = seenMs, h = hash(), payer = o.player) => store.settle(o, { hash: h, payer, seenMs }, now);
+export function shopStoreConformance(make) {
+    const cases = [];
+    const add = (name, run) => cases.push({ name, run: async () => run(await make()) });
+    add("an order asks for its price, and a second open order of the same price one step (0.0001 XNO) more", async ({ store }) => {
+        const a = await order(store);
+        const b = await order(store, BOB);
+        check(xnoText(a.amount) === "0.25" && xnoText(b.amount) === "0.2501", `amounts: ${xnoText(a.amount)}, ${xnoText(b.amount)}`);
+        const back = await store.order(a.id);
+        check(back !== null && back.amount === a.amount && back.amountLock === a.amount && back.status === "open" && back.player === ANN, `read back: ${JSON.stringify(back)}`);
+        check(back.expiresAt === T0 + ORDER_TTL_MS && back.holdUntil === T0 + ORDER_TTL_MS + LATE_HOLD_MS, "the times are kept");
+    });
+    add("no two held orders ever hold one amount, even when 25 are made at the same instant", async ({ store }) => {
+        const made = await Promise.all(Array.from({ length: 25 }, (_, i) => order(store, id(`p${i}`))));
+        check(new Set(made.map((o) => o.amount)).size === 25, `amounts: ${made.map((o) => xnoText(o.amount)).join(" ")}`);
+        const held = await store.held();
+        check(held.length === 25 && new Set(held.map((o) => o.amountLock)).size === 25, `held: ${held.length}`);
+        const amounts = amountsFor(PRICE);
+        check((await store.heldAmounts(amounts)).size === 25, "heldAmounts names the 25");
+    });
+    add("insert refuses an amount that another order holds, and writes nothing", async ({ store }) => {
+        const a = await order(store);
+        const copy = { ...a, id: newOrderId(), player: BOB };
+        check((await store.insert(copy)) === false, "a second order with a held amount was written");
+        check((await store.order(copy.id)) === null, "the refused order is not there");
+    });
+    add("every amount of a price held: the next order is refused (busy)", async ({ store }) => {
+        const small = priceRaw(0.003, 1); // 30 steps: 3 more allowed, 4 amounts in all
+        for (let i = 0; i < 4; i++)
+            await order(store, id(`s${i}`), T0, small);
+        try {
+            await order(store, id("s4"), T0, small);
+        }
+        catch (e) {
+            check(e instanceof ShopBusy, `expected ShopBusy, got ${String(e)}`);
+            return;
+        }
+        throw new Error("a fifth order got an amount");
+    });
+    add("an expired order keeps its amount until its hold ends; tidy marks it expired, then frees it", async ({ store }) => {
+        const a = await order(store);
+        const b = await order(store, BOB, a.expiresAt + 1000);
+        check(b.amount !== a.amount, "the amount of an order that may still be paid late was given again");
+        check((await store.order(a.id))?.status === "expired", "tidy marks an open order past its time expired");
+        const c = await order(store, CYD, a.holdUntil + 1);
+        check(c.amount === a.amount, "after the hold the amount is free again");
+        const was = await store.order(a.id);
+        check(was?.status === "expired" && was.amountLock === null, `the old order: ${JSON.stringify(was)}`);
+    });
+    add("a paid order gives the look to ITS player once, frees its amount at once, and records the payment", async ({ store }) => {
+        const a = await order(store);
+        const h = hash();
+        check((await pay(store, a, T0 + 1000, T0 + 2000, h, BOB)) === "paid", "an exact payment in time pays");
+        const after = await store.order(a.id);
+        check(after?.status === "paid" && after.hash === h && after.payer === BOB && after.paidAt === T0 + 1000 && after.amountLock === null, `paid order: ${JSON.stringify(after)}`);
+        check((await store.owns(ANN, "look-a")) && JSON.stringify(await store.owned(ANN)) === '["look-a"]', "the order's player owns the look");
+        check(!(await store.owns(BOB, "look-a")) && (await store.owned(BOB)).length === 0, "the payer is not the owner: one owner per order");
+        check((await store.usedHashes([h, hash()])).has(h) && (await store.usedHashes([h])).size === 1, "the payment is recorded");
+        const next = await order(store, CYD, T0 + 3000);
+        check(next.amount === a.amount, "a paid order's amount is free at once");
+    });
+    add("a paid order is never paid twice: the same payment or another one changes nothing", async ({ store }) => {
+        const a = await order(store);
+        const h = hash();
+        await pay(store, a, T0 + 1000, T0 + 1000, h);
+        check((await pay(store, a, T0 + 1000, T0 + 2000, h)) === "taken", "the same payment again");
+        check((await pay(store, a, T0 + 1500, T0 + 2000)) === "taken", "another payment of a paid order");
+        const after = await store.order(a.id);
+        check(after?.hash === h && after.status === "paid", "the first payment stays");
+        check((await store.owned(ANN)).length === 1, "one owned row");
+    });
+    add("one payment never pays a second order, even one that holds the same amount later", async ({ store }) => {
+        const a = await order(store);
+        const h = hash();
+        await pay(store, a, T0 + 1000, T0 + 1000, h);
+        const b = await order(store, BOB, T0 + 2000);
+        check(b.amount === a.amount, "the next order holds the freed amount");
+        check((await pay(store, b, T0 + 3000, T0 + 3000, h)) === "used", "a payment that paid an order pays no other");
+        const after = await store.order(b.id);
+        check(after?.status === "open" && after.amountLock === b.amount && after.hash === null, `the second order: ${JSON.stringify(after)}`);
+        check(!(await store.owns(BOB, "look-a")), "no look for the second order");
+    });
+    add("a payment first seen after the order ended (beyond the clock allowance) is paid late: no look, the amount freed", async ({ store }) => {
+        const a = await order(store);
+        const seen = a.expiresAt + CLOCK_SLACK_MS + 1;
+        check((await pay(store, a, seen, seen + 1000)) === "paid_late", "late");
+        const after = await store.order(a.id);
+        check(after?.status === "paid_late" && after.amountLock === null && after.hash !== null, `late order: ${JSON.stringify(after)}`);
+        check((await store.owned(ANN)).length === 0, "a late payment gives no look");
+    });
+    add("a payment sent in time but recorded after the order expired still pays it", async ({ store }) => {
+        const a = await order(store);
+        await store.tidy(a.expiresAt + 20 * 60_000);
+        check((await store.order(a.id))?.status === "expired", "expired first");
+        check((await pay(store, a, a.expiresAt - 30_000, a.expiresAt + 20 * 60_000)) === "paid", "sent in time");
+        check(await store.owns(ANN, "look-a"), "the look is given");
+    });
+    add("an expired order whose hold has ended cannot be paid: it is not held, and settle refuses it", async ({ store }) => {
+        const a = await order(store);
+        await store.tidy(a.holdUntil + 1);
+        check((await store.held()).length === 0, "nothing is held after the hold");
+        check((await pay(store, a, a.holdUntil, a.holdUntil + 2)) === "taken", "an order whose amount is no longer held");
+        const after = await store.order(a.id);
+        check(after?.status === "expired" && after.hash === null, `the order: ${JSON.stringify(after)}`);
+        check((await store.owned(ANN)).length === 0, "no look");
+    });
+    add("the open orders of a player: the same look's newest, and the count", async ({ store }) => {
+        const a = await order(store, ANN, T0, PRICE, "look-a");
+        await order(store, ANN, T0 + 10, PRICE, "look-b");
+        await order(store, BOB, T0 + 20, PRICE, "look-a");
+        const same = await store.openOrder(ANN, "look-a", T0 + 60_000);
+        check(same?.id === a.id, "the open order for that look");
+        check((await store.openOrder(ANN, "look-a", a.expiresAt)) === null, "an order that ends before `until` is not offered again");
+        check((await store.openOrder(CYD, "look-a", T0)) === null, "another player's order is not theirs");
+        check((await store.countOpen(ANN, T0 + 100)) === 2 && (await store.countOpen(BOB, T0 + 100)) === 1, "the counts");
+        check((await store.countOpen(ANN, a.expiresAt + 11)) === 0, "an order past its time is not counted");
+    });
+    add("amounts are kept as exact text, even with 39 digits", async ({ store }) => {
+        const big = "100000000000000000000000000000000000000"; // 39 digits: 10^38 raw (10^8 XNO), a clean amount
+        const o = { id: newOrderId(), player: ANN, lookId: "look-a", usd: "1.00", rate: 1, amount: big, amountLock: big, status: "open", createdAt: T0, expiresAt: T0 + ORDER_TTL_MS, holdUntil: T0 + ORDER_TTL_MS + LATE_HOLD_MS, hash: null, payer: null, paidAt: null, visitor: null };
+        check(await store.insert(o), "inserted");
+        const back = await store.order(o.id);
+        check(back?.amount === big && back.amountLock === big, `read back: ${back?.amount}`);
+        check((await store.heldAmounts([big])).has(big), "held by its exact text");
+    });
+    add("the scan's claim: one caller in each gap, also at the same instant", async ({ store }) => {
+        const all = await Promise.all(Array.from({ length: 5 }, () => store.claimScan(T0, 4000)));
+        check(all.filter(Boolean).length === 1, `claims at once: ${all.join(",")}`);
+        check(!(await store.claimScan(T0 + 3999, 4000)), "inside the gap");
+        check(await store.claimScan(T0 + 4000, 4000), "after the gap");
+    });
+    add("the kept price comes back as it was saved", async ({ store }) => {
+        check((await store.readRate()) === null, "no price at first");
+        await store.saveRate({ usd: 0.8731, sources: ["CoinGecko", "Kraken"], at: T0 });
+        const r = await store.readRate();
+        check(r?.usd === 0.8731 && r.at === T0 && JSON.stringify(r.sources) === '["CoinGecko","Kraken"]', `rate: ${JSON.stringify(r)}`);
+    });
+    add("forget waits while an order of the player may still be paid, and deletes nothing", async ({ store }) => {
+        const paid = await order(store, ANN, T0, PRICE, "look-a");
+        await pay(store, paid, T0 + 1000);
+        const waiting = await order(store, ANN, T0 + 2000, PRICE, "look-b");
+        const r = await store.forget(ANN, waiting.expiresAt + 1);
+        check(r.waitUntil === waiting.holdUntil && r.deleted === 0 && r.kept === 0, `forget: ${JSON.stringify(r)}`);
+        check(await store.owns(ANN, "look-a"), "nothing was deleted");
+        check((await store.order(paid.id))?.player === ANN, "the paid order still names the player");
+    });
+    add("forget leaves nothing of the player's except a late payment's payer (the creator sends it back)", async ({ store, dump }) => {
+        const paid = await order(store, ANN, T0, PRICE, "look-a");
+        await pay(store, paid, T0 + 1000);
+        const late = await order(store, ANN, T0 + 10, PRICE, "look-b");
+        await pay(store, late, late.expiresAt + CLOCK_SLACK_MS + 10);
+        const never = await order(store, ANN, T0 + 20, PRICE, "look-c");
+        const gift = await order(store, BOB, T0 + 30, PRICE, "look-d");
+        await pay(store, gift, T0 + 1000, T0 + 1000, hash(), ANN);
+        const at = never.holdUntil + 1;
+        const r = await store.forget(ANN, at);
+        check(r.waitUntil === null && r.kept === 2 && r.deleted === 2, `forget: ${JSON.stringify(r)}`);
+        check((await store.owned(ANN)).length === 0 && !(await store.owns(ANN, "look-a")), "the owned looks are gone");
+        check((await store.order(never.id)) === null, "an order that was never paid is gone");
+        const p = await store.order(paid.id);
+        check(p?.player === FORGOTTEN && p.payer === FORGOTTEN && p.visitor === null && p.hash !== null && p.status === "paid", `the paid order stays as a sale: ${JSON.stringify(p)}`);
+        const l = await store.order(late.id);
+        check(l?.player === FORGOTTEN && l.payer === ANN && l.visitor === null && l.status === "paid_late", `the late payment keeps its payer: ${JSON.stringify(l)}`);
+        const g = await store.order(gift.id);
+        check(g?.player === BOB && g.payer === FORGOTTEN && (await store.owns(BOB, "look-d")), `another player's order that ANN paid stays BOB's: ${JSON.stringify(g)}`);
+        const text = await dump();
+        const left = text.split(ANN).length - 1;
+        check(left === 1, `the player's id is left ${left} times in the store (only the late payer may stay): ${text.slice(0, 400)}`);
+        check((await store.usedHashes([p.hash])).size === 1, "the paid order's payment is still recorded (it never counts again)");
+        const again = await store.forget(ANN, at + 1);
+        check(again.deleted === 0 && again.kept === 0 && again.waitUntil === null, `a second forget: ${JSON.stringify(again)}`);
+    });
+    return cases;
+}

package/dist/shop/handler.d.ts

@@ -0,0 +1,76 @@
+import { type Fetch, type NanoNode, type RpcOptions } from "./nodes.js";
+import { type PriceFeed } from "./price.js";
+import { type ScanResult } from "./scan.js";
+import type { OrderStatus, ShopOrder, ShopStore } from "./store.js";
+/** What the pay screen gets. `address` and `uri` are there only outside test mode. */
+export type PayView = {
+    id: string;
+    lookId: string;
+    usd: string;
+    amount: string;
+    status: OrderStatus;
+    createdAt: number;
+    expiresAt: number;
+    xno: string;
+    test: boolean;
+    address?: string;
+    uri?: string;
+    prices: string[];
+};
+export type ShopHandlerOptions = {
+    store: ShopStore;
+    /** The game's looks (looks.json as it was read). They are checked with `checkLooks`: a bad file throws here, before any sale. */
+    catalogue: unknown;
+    /** The creator's Nano address: payments go straight there. Null, the example address or one with a wrong checksum keeps test mode on. */
+    payee: string | null | undefined;
+    /** True keeps test mode on with a real address (the starter's TEST_MODE). */
+    testMode?: boolean;
+    /** The game's signed-in player of this request (its own id: the starter's is the Nano address), or null. Never the admin's login. */
+    player(request: Request): Promise<string | null>;
+    /** Where the routes are. Default "/api/orders". */
+    base?: string;
+    /** The nodes that check payments (`nodesFor`). Default: the public nodes. */
+    nodes?: readonly NanoNode[];
+    /** The price feeds and the `fetch` that reads them. Default: CoinGecko, Kraken and KuCoin, the page's fetch. */
+    rate?: {
+        feeds?: readonly PriceFeed[];
+        fetch?: Fetch;
+    };
+    /** For the scan's node calls (a test gives its own fetch and timeouts). */
+    rpc?: RpcOptions;
+    /** A limiter for new orders: false means "too many". Default: a fixed window in memory, SHOP_LIMITS.order. */
+    limit?: (key: string, limit: number, windowMs: number, now: number) => boolean | Promise<boolean>;
+    /** A keyed hash of the visitor's IP address (never the address), kept on the order and used as the limit's key; null or no hook: the player's id. */
+    visitor?: (request: Request) => Promise<string | null>;
+    /** The person check (Turnstile): true when `token` passes. No hook: no check. The starter's checks `body.turnstile` with Cloudflare. */
+    personCheck?: (token: unknown, request: Request) => Promise<boolean>;
+    /** The time now in ms. Default Date.now. */
+    now?: () => number;
+    /** Told about a fault (a store, a node). The player gets a plain 500 and never sees it. */
+    onError?: (e: unknown) => void;
+};
+export declare const SHOP_LIMITS: {
+    /** New orders of one visitor (the starter's: 10 in 10 minutes). */
+    readonly order: {
+        readonly limit: 10;
+        readonly windowMs: number;
+    };
+    /** The biggest body of a POST. */
+    readonly bodyMax: 8192;
+};
+export type ShopHandler = {
+    base: string;
+    /** The answer for a request under `base`, or null when it is not one of the shop's routes. */
+    handle(request: Request): Promise<Response | null>;
+    /** One payment scan now (the cron's and the admin's "Check payments now"). */
+    scan(at?: number): Promise<ScanResult>;
+    /** The looks a paid order gave this player (the free looks are everyone's and are not listed). */
+    owned(player: string): Promise<string[]>;
+    /** The pay view of an order (for a game's own route). */
+    payView(order: ShopOrder, now?: number): PayView;
+    /** The payee the shop uses (checked), or null. */
+    readonly payee: string | null;
+    /** Whether pay screens are in test mode. */
+    readonly testMode: boolean;
+};
+export declare function createShopHandler(options: ShopHandlerOptions): ShopHandler;

package/dist/shop/handler.js

@@ -0,0 +1,156 @@
+// The routes of the shop, on the Web `Request` and `Response` types (a Worker, Firebase Functions, Node). The same paths and answers as the game
+// starter's Worker, so its page keeps working:
+//
+//   POST {base}               { lookId, turnstile? }  a new order for a look: 201 and the pay view (or 200 and the same open order again)
+//   GET  {base}/{id}          the pay view of the player's own order
+//   POST {base}/{id}/check    scans for payments first (at most one scan for the whole game every 4 s), then the pay view
+//
+// `base` is "/api/orders" (the starter's). The pay view is the order ({ id, lookId, usd, amount, status, createdAt, expiresAt }) with `xno` (the amount as
+// XNO text), `test`, `prices` (the feeds' names) and, ONLY outside test mode, `address` and `uri` (the nano: link with the exact raw amount).
+//
+// The player is the game's own signed-in player (`player(request)`): a visitor who is not signed in gets 401, and another player's order looks like no
+// order at all (404). A POST must come from the game's own page. The server decides every price: the browser sends a look's id and nothing else.
+//
+// TEST MODE: with no payee (none, the example address, or a wrong checksum) or `testMode: true`, the answer carries NO address and NO link, and the page
+// shows "TEST MODE: DO NOT PAY". A payment to an address nobody holds the key for is lost for good.
+import { fail, json, memoryLimiter, readLimited, sameOrigin } from "../admin/http.js";
+import { checkLooks } from "../looks/look.js";
+import { payeeOf } from "./address.js";
+import { nanoUri, priceRaw, xnoText } from "./amount.js";
+import { PUBLIC_NODES } from "./nodes.js";
+import { MAX_OPEN_PER_PLAYER, ORDER_ID_PATTERN, ShopBusy, orderView, reserveOrder } from "./orders.js";
+import { PRICE_FEEDS, usdPerXno } from "./price.js";
+import { scanPayments } from "./scan.js";
+export const SHOP_LIMITS = {
+    /** New orders of one visitor (the starter's: 10 in 10 minutes). */
+    order: { limit: 10, windowMs: 10 * 60_000 },
+    /** The biggest body of a POST. */
+    bodyMax: 8192,
+};
+const sharedLimit = memoryLimiter();
+export function createShopHandler(options) {
+    const base = options.base ?? "/api/orders";
+    if (!base.startsWith("/") || base.length < 2 || base.endsWith("/"))
+        throw new Error('base must start with "/" and not end with "/", like "/api/orders"');
+    const looks = checkLooks(options.catalogue);
+    const lookById = (id) => looks.find((l) => l.id === id);
+    const payee = payeeOf(options.payee);
+    const testMode = payee === null || options.testMode === true;
+    const now = options.now ?? (() => Date.now());
+    const limit = options.limit ?? sharedLimit;
+    const nodes = options.nodes ?? PUBLIC_NODES;
+    const feeds = options.rate?.feeds ?? PRICE_FEEDS;
+    const fetchRate = options.rate?.fetch ?? ((i, init) => fetch(i, init));
+    const store = options.store;
+    const report = (e) => {
+        try {
+            options.onError?.(e);
+        }
+        catch {
+            // nothing more can be done
+        }
+    };
+    const payView = (o, at = now()) => ({
+        ...orderView(o, at),
+        xno: xnoText(o.amount),
+        test: testMode,
+        ...(!testMode && payee ? { address: payee, uri: nanoUri(payee, o.amount) } : {}),
+        prices: feeds.map((f) => f.name),
+    });
+    const scan = (at = now()) => scanPayments(store, { address: payee, nodes, at, rpc: options.rpc });
+    async function readBody(req) {
+        const text = await readLimited(req, SHOP_LIMITS.bodyMax);
+        if (text === null)
+            return null;
+        if (!text)
+            return {};
+        try {
+            const v = JSON.parse(text);
+            return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+        }
+        catch {
+            return null;
+        }
+    }
+    async function createOrder(req, player, at) {
+        const body = await readBody(req);
+        if (!body)
+            return fail(400, "That request is not readable.");
+        const look = lookById(body.lookId);
+        if (!look)
+            return fail(400, "That look does not exist.");
+        if (look.priceUsd === 0)
+            return fail(400, "That look is free: it is already yours.");
+        const visitor = options.visitor ? await options.visitor(req) : null;
+        if (!(await limit(`order|${visitor ?? player}`, SHOP_LIMITS.order.limit, SHOP_LIMITS.order.windowMs, at)))
+            return fail(429, "Too many orders. Wait a few minutes.");
+        if (options.personCheck && !(await options.personCheck(body.turnstile, req)))
+            return fail(403, "The person check failed. Try again.");
+        if (await store.owns(player, look.id))
+            return fail(409, "You already own this look.");
+        // One waiting order per look: the same one comes back, with the same amount.
+        const same = await store.openOrder(player, look.id, at + 60_000);
+        if (same)
+            return json(payView(same, at));
+        if ((await store.countOpen(player, at)) >= MAX_OPEN_PER_PLAYER)
+            return fail(429, "You have orders waiting. Pay one or wait until it ends.");
+        const rate = await usdPerXno(store, fetchRate, at, feeds);
+        if (!rate)
+            return fail(503, "Prices are not available now. Try again later.");
+        const price = priceRaw(look.priceUsd, rate.usd);
+        if (!price)
+            return fail(503, "Prices are not available now. Try again later.");
+        try {
+            const order = await reserveOrder(store, { player, lookId: look.id, usd: look.priceUsd.toFixed(2), rate: rate.usd, price, visitor, now: at });
+            return json(payView(order, at), 201);
+        }
+        catch (e) {
+            if (e instanceof ShopBusy)
+                return fail(503, "Many players are paying this price right now. Try again in a minute.");
+            throw e;
+        }
+    }
+    async function handle(req) {
+        const path = new URL(req.url).pathname;
+        const one = path.startsWith(`${base}/`) ? /^([0-9a-f]{24})(\/check)?$/.exec(path.slice(base.length + 1)) : null;
+        const isNew = path === base && req.method === "POST";
+        if (!isNew && !one)
+            return null;
+        try {
+            // Every call that changes something must come from the game's own pages.
+            if (req.method === "POST" && !sameOrigin(req))
+                return fail(403, "This call must come from the game's own page.");
+            let player;
+            try {
+                player = await options.player(req);
+            }
+            catch (e) {
+                report(e);
+                return fail(503, "The game's server could not check your sign-in. Try again.");
+            }
+            if (typeof player !== "string" || !player)
+                return fail(401, "Sign in first.");
+            const at = now();
+            if (isNew)
+                return await createOrder(req, player, at);
+            const [, id, check] = one;
+            if (check && req.method === "POST") {
+                const r = await scan(at);
+                if (r.error)
+                    report(new Error(`payment scan: ${r.error}`));
+            }
+            else if (check || req.method !== "GET")
+                return fail(405, "Not allowed.");
+            const o = ORDER_ID_PATTERN.test(id) ? await store.order(id) : null;
+            // Another player's order looks the same as no order at all.
+            if (!o || o.player !== player)
+                return fail(404, "No such order.");
+            return json(payView(o, at));
+        }
+        catch (e) {
+            report(e);
+            return fail(500, "Something went wrong. Try again.");
+        }
+    }
+    return { base, handle, scan, owned: (player) => store.owned(player), payView, payee, testMode };
+}

package/dist/shop/index.d.ts

@@ -0,0 +1,19 @@
+export { EXAMPLE_ADDRESS, blake2bShort, payeeOf, validAddress } from "./address.js";
+export { MAX_RATE, MAX_USD, MIN_RATE, RAW_PER_XNO, STEP_RAW, compareRaw, isClean, isRaw, nanoUri, plusSteps, priceRaw, rawFromSteps, stepsFromUsd, xnoText } from "./amount.js";
+export { CLOCK_SLACK_MS, candidates, checkSend } from "./match.js";
+export type { Verdict } from "./match.js";
+export { KEYED_NODE, NodeDown, PUBLIC_NODES, forgetNodeHealth, nodesFor, rpc, settingValue } from "./nodes.js";
+export type { Fetch, NanoNode, RpcOptions } from "./nodes.js";
+export { LATE_HOLD_MS, MAX_EXTRA_PERCENT, MAX_OPEN_PER_PLAYER, MAX_STEPS, ORDER_ID_PATTERN, ORDER_TTL_MS, ShopBusy, amountsFor, newOrderId, orderView, paidStatus, reserveOrder, smallestAmount, statusAt, stepsFor } from "./orders.js";
+export type { ReserveInput } from "./orders.js";
+export { PRICE_FEEDS, RATE_FRESH_MS, RATE_LAST_GOOD_MS, readFeeds, usdPerXno } from "./price.js";
+export type { PriceFeed, Rate } from "./price.js";
+export { SCAN_GAP_MS, forgetBlocks, scanPayments } from "./scan.js";
+export type { ScanOptions, ScanResult } from "./scan.js";
+export { FORGOTTEN } from "./store.js";
+export type { ForgetResult, KeptRate, OrderStatus, Payment, Settled, ShopOrder, ShopStore } from "./store.js";
+export { createMemoryShop } from "./memory.js";
+export type { MemoryShop } from "./memory.js";
+export { SHOP_LIMITS, createShopHandler } from "./handler.js";
+export type { PayView, ShopHandler, ShopHandlerOptions } from "./handler.js";
+export { SHOP_CSP, TURNSTILE_ORIGIN, mergeCsp } from "./security.js";

package/dist/shop/index.js

@@ -0,0 +1,21 @@
+// "@nano133/nanoterra/shop": the shop of a game that sells looks for Nano (XNO), as the game starter sells them. No database, no cookie, no key: the money
+// goes straight from the player's wallet to the creator's address, and the server only READS the ledger to see that a payment came (a unique, clean
+// amount for each order, matched exactly). The game gives its store, its looks, its address and its signed-in player.
+//
+//   createShopHandler     the routes (POST an order, GET it, POST its check), on Request and Response
+//   scanPayments          one look at the creator's address that settles every held order (the cron's and the admin's check)
+//   createMemoryShop      a store in memory, for tests
+//   the rules             amounts (raw text and BigInt), the reservation, the match, the price, the nodes, the address check, the CSP lists
+//   (the adapters are "/shop/d1" and "/shop/firestore", a Worker set up from the starter's settings "/shop/worker", the conformance suite
+//   "/shop/conformance", the browser panel "/shop/panel")
+export { EXAMPLE_ADDRESS, blake2bShort, payeeOf, validAddress } from "./address.js";
+export { MAX_RATE, MAX_USD, MIN_RATE, RAW_PER_XNO, STEP_RAW, compareRaw, isClean, isRaw, nanoUri, plusSteps, priceRaw, rawFromSteps, stepsFromUsd, xnoText } from "./amount.js";
+export { CLOCK_SLACK_MS, candidates, checkSend } from "./match.js";
+export { KEYED_NODE, NodeDown, PUBLIC_NODES, forgetNodeHealth, nodesFor, rpc, settingValue } from "./nodes.js";
+export { LATE_HOLD_MS, MAX_EXTRA_PERCENT, MAX_OPEN_PER_PLAYER, MAX_STEPS, ORDER_ID_PATTERN, ORDER_TTL_MS, ShopBusy, amountsFor, newOrderId, orderView, paidStatus, reserveOrder, smallestAmount, statusAt, stepsFor } from "./orders.js";
+export { PRICE_FEEDS, RATE_FRESH_MS, RATE_LAST_GOOD_MS, readFeeds, usdPerXno } from "./price.js";
+export { SCAN_GAP_MS, forgetBlocks, scanPayments } from "./scan.js";
+export { FORGOTTEN } from "./store.js";
+export { createMemoryShop } from "./memory.js";
+export { SHOP_LIMITS, createShopHandler } from "./handler.js";
+export { SHOP_CSP, TURNSTILE_ORIGIN, mergeCsp } from "./security.js";

package/dist/shop/match.d.ts

@@ -0,0 +1,23 @@
+/** Allowed difference between the Worker's clock and the node's clock. */
+export declare const CLOCK_SLACK_MS = 120000;
+/**
+ * The send hashes in a scan that carry one of `amounts` exactly, with their amount.
+ * `receivable`: the node's answer to `receivable` (source: true, or not). `history`: to `account_history` (raw).
+ */
+export declare function candidates(receivable: unknown, history: unknown, amounts: Set<string>): Map<string, string>;
+export type Verdict = {
+    kind: "paid";
+    payer: string;
+    seenMs: number;
+} | {
+    kind: "pending";
+} | {
+    kind: "early";
+} | {
+    kind: "wrong";
+};
+/**
+ * Whether a send block (the node's `block_info` answer, json_block: true) pays `amount` to `address`, and
+ * was first seen at or after `notBeforeMs` (the order's start, less the clock allowance).
+ */
+export declare function checkSend(info: unknown, address: string, amount: string, notBeforeMs: number): Verdict;

package/dist/shop/match.js

@@ -0,0 +1,58 @@
+// The rules that decide whether a payment arrived (the game starter's src/worker/match.ts, moved here unchanged). No network and no database here, so
+// they are easy to test alone. DO NOT LOOSEN THEM: they are what stops a look from being given away.
+//
+// A payment to the creator's address is in one of two places: still receivable (no wallet took it yet), or
+// received (the creator's wallet took it, and it shows in the address's history). Both are searched for the
+// exact amount of a held order. A hit is only a candidate: the send block itself is then read, and it counts
+// only when it is a confirmed send of exactly that amount to exactly that address, first seen by the node
+// after the order was made.
+/** Allowed difference between the Worker's clock and the node's clock. */
+export const CLOCK_SLACK_MS = 120_000;
+const HASH = /^[0-9A-F]{64}$/i;
+const nanoPrefix = (a) => (typeof a === "string" ? a.replace(/^xrb_/, "nano_") : "");
+/**
+ * The send hashes in a scan that carry one of `amounts` exactly, with their amount.
+ * `receivable`: the node's answer to `receivable` (source: true, or not). `history`: to `account_history` (raw).
+ */
+export function candidates(receivable, history, amounts) {
+    const found = new Map();
+    const blocks = receivable?.blocks;
+    if (blocks && typeof blocks === "object" && !Array.isArray(blocks)) {
+        for (const [hash, entry] of Object.entries(blocks)) {
+            const amount = typeof entry === "string" ? entry : entry?.amount;
+            if (HASH.test(hash) && typeof amount === "string" && amounts.has(amount))
+                found.set(hash.toUpperCase(), amount);
+        }
+    }
+    const list = history?.history;
+    if (Array.isArray(list)) {
+        for (const h of list) {
+            const kind = h?.subtype ?? h?.type;
+            if (kind !== "receive" && kind !== "open")
+                continue;
+            // In a raw history, a receive's `link` is the hash of the send it received.
+            if (typeof h.amount === "string" && typeof h.link === "string" && HASH.test(h.link) && amounts.has(h.amount))
+                found.set(h.link.toUpperCase(), h.amount);
+        }
+    }
+    return found;
+}
+/**
+ * Whether a send block (the node's `block_info` answer, json_block: true) pays `amount` to `address`, and
+ * was first seen at or after `notBeforeMs` (the order's start, less the clock allowance).
+ */
+export function checkSend(info, address, amount, notBeforeMs) {
+    const i = (info ?? {});
+    const contents = (i.contents ?? {});
+    const subtype = i.subtype ?? contents.subtype;
+    if (subtype !== "send" || nanoPrefix(contents.link_as_account) !== address || i.amount !== amount)
+        return { kind: "wrong" };
+    // The node's own time for the send, in seconds. A block with no time cannot be shown to be newer than
+    // the order, so it never counts.
+    const seenMs = Number(i.local_timestamp) * 1000;
+    if (!Number.isFinite(seenMs) || seenMs <= 0 || seenMs < notBeforeMs - CLOCK_SLACK_MS)
+        return { kind: "early" };
+    if (i.confirmed !== "true" && i.confirmed !== true)
+        return { kind: "pending" };
+    return { kind: "paid", payer: nanoPrefix(i.block_account), seenMs };
+}