@nano133/nanoterra 0.8.1 → 0.9.3

package/src/shop/price.ts

@@ -0,0 +1,52 @@
+// Dollars per XNO (the game starter's src/worker/price.ts): the median of public price feeds that need no key, so one wrong feed cannot move the price.
+// The answer is kept 5 minutes (in the store: `readRate`, `saveRate`). When every feed fails, the last good price is used for up to 6 hours; after that,
+// new orders wait ("Prices are not available") and nothing is sold at a guessed price.
+//
+// CoinGecko's API terms ask for the words "Powered by CoinGecko": the pay screen shows them.
+
+import { MAX_RATE, MIN_RATE } from "./amount.js";
+import type { Fetch } from "./nodes.js";
+import type { ShopStore } from "./store.js";
+
+export type PriceFeed = { name: string; url: string; read: (j: any) => unknown };
+
+export const PRICE_FEEDS: readonly PriceFeed[] = [
+  { name: "CoinGecko", url: "https://api.coingecko.com/api/v3/simple/price?ids=nano&vs_currencies=usd", read: (j) => j?.nano?.usd },
+  { name: "Kraken", url: "https://api.kraken.com/0/public/Ticker?pair=NANOUSD", read: (j) => (Object.values(j?.result ?? {})[0] as any)?.c?.[0] },
+  { name: "KuCoin", url: "https://api.kucoin.com/api/v1/market/orderbook/level1?symbol=XNO-USDT", read: (j) => j?.data?.price },
+];
+
+export const RATE_FRESH_MS = 5 * 60_000;
+export const RATE_LAST_GOOD_MS = 6 * 60 * 60_000;
+
+export type Rate = { usd: number; at: number; sources: string[]; stale: boolean };
+
+/** Asks every feed at once and returns the median of the believable answers, or null. */
+export async function readFeeds(fetchFn: Fetch, feeds: readonly PriceFeed[] = PRICE_FEEDS, timeoutMs = 4000): Promise<{ usd: number; sources: string[] } | null> {
+  const answers = await Promise.allSettled(
+    feeds.map(async (f) => {
+      const res = await fetchFn(f.url, { headers: { Accept: "application/json", "User-Agent": "nano-game-starter" }, signal: AbortSignal.timeout(timeoutMs) });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return Number(f.read(await res.json()));
+    }),
+  );
+  const good = answers
+    .map((a, i) => ({ name: feeds[i].name, v: a.status === "fulfilled" ? a.value : NaN }))
+    .filter((x) => Number.isFinite(x.v) && x.v >= MIN_RATE && x.v <= MAX_RATE)
+    .sort((a, b) => a.v - b.v);
+  if (!good.length) return null;
+  return { usd: good[Math.floor(good.length / 2)].v, sources: good.map((g) => g.name) };
+}
+
+/** Dollars per XNO now, or null when no believable price is known. */
+export async function usdPerXno(store: Pick<ShopStore, "readRate" | "saveRate">, fetchFn: Fetch, now = Date.now(), feeds: readonly PriceFeed[] = PRICE_FEEDS): Promise<Rate | null> {
+  const last = await store.readRate();
+  if (last && now - last.at < RATE_FRESH_MS) return { usd: last.usd, sources: last.sources, at: last.at, stale: false };
+  const fresh = await readFeeds(fetchFn, feeds);
+  if (fresh) {
+    await store.saveRate({ ...fresh, at: now });
+    return { ...fresh, at: now, stale: false };
+  }
+  if (last && now - last.at < RATE_LAST_GOOD_MS) return { usd: last.usd, sources: last.sources, at: last.at, stale: true };
+  return null;
+}

package/src/shop/scan.ts

@@ -0,0 +1,90 @@
+// The payment scan (the game starter's src/worker/sweep.ts): one look at the creator's address settles every held order at once. It READS the ledger and
+// writes only the store: no key, no send. (The starter calls it "sweep"; it moves no money, unlike @nano133/checkout's sweep.)
+//
+// A player's pay screen asks for it every 5 seconds, the admin page on "Check payments now", and a cron every 10 minutes (for a player who paid and closed
+// the page). Node load stays flat however many players pay: the whole game makes at most one scan every SCAN_GAP_MS, and none when no order is held.
+
+import { candidates, checkSend } from "./match.js";
+import { rpc, type NanoNode, type RpcOptions } from "./nodes.js";
+import { smallestAmount } from "./orders.js";
+import type { ShopOrder, ShopStore } from "./store.js";
+
+export const SCAN_GAP_MS = 4000;
+/** The most entries one RPC read asks for. */
+const COUNT = "50";
+
+export type ScanResult = { scanned: boolean; settled: { id: string; status: string }[]; error?: string };
+
+/** A confirmed send never changes: its answer is kept for an hour (in this copy of the server). */
+const blockCache = new Map<string, { info: Record<string, any>; until: number }>();
+
+async function blockInfo(nodes: readonly NanoNode[], hash: string, o: RpcOptions, now: number) {
+  const hit = blockCache.get(hash);
+  if (hit && hit.until > now) return hit.info;
+  const { answer } = await rpc(nodes, { action: "block_info", hash, json_block: "true" }, o);
+  if (answer && (answer.confirmed === "true" || answer.confirmed === true)) {
+    if (blockCache.size > 500) blockCache.clear();
+    blockCache.set(hash, { info: answer, until: now + 3_600_000 });
+  }
+  return answer;
+}
+
+export type ScanOptions = {
+  /** The creator's address (a checked one: `payeeOf`). Null: no scan. */
+  address: string | null;
+  /** The nodes to ask (`nodesFor`). */
+  nodes: readonly NanoNode[];
+  /** The time now in ms (default Date.now()). */
+  at?: number;
+  rpc?: RpcOptions;
+};
+
+/** Scans the creator's address once and settles the held orders it pays. Fails closed: when the nodes cannot be read, nothing is credited. */
+export async function scanPayments(store: ShopStore, opts: ScanOptions): Promise<ScanResult> {
+  const now = opts.at ?? Date.now();
+  const o: RpcOptions = opts.rpc ?? {};
+  await store.tidy(now);
+  const address = opts.address;
+  if (!address) return { scanned: false, settled: [] };
+  const held = await store.held();
+  if (!held.length) return { scanned: false, settled: [] };
+  if (!(await store.claimScan(now, SCAN_GAP_MS))) return { scanned: false, settled: [] };
+
+  const settled: ScanResult["settled"] = [];
+  try {
+    // Only amounts a held order asks for: small sends ("dust") cannot push a payment out of the list.
+    const threshold = smallestAmount(held)!;
+    const receivable = await rpc(opts.nodes, { action: "receivable", account: address, count: COUNT, threshold, source: "true" }, o);
+    // A new address has no history yet: the node answers "Account not found" (null here).
+    const history = await rpc(opts.nodes, { action: "account_history", account: address, count: COUNT, raw: "true" }, o);
+    const byAmount = new Map<string, ShopOrder>(held.map((h) => [h.amount, h]));
+    const found = candidates(receivable.answer, history.answer, new Set(byAmount.keys()));
+    if (!found.size) return { scanned: true, settled };
+
+    // A payment that already paid (or was recorded for) an order never counts again.
+    const used = await store.usedHashes([...found.keys()]);
+    for (const [hash, amount] of found) {
+      if (used.has(hash)) continue;
+      const order = byAmount.get(amount);
+      if (!order) continue;
+      const info = await blockInfo(opts.nodes, hash, o, now);
+      if (!info) continue;
+      const verdict = checkSend(info, address, order.amount, order.createdAt);
+      if (verdict.kind !== "paid") continue;
+      const result = await store.settle(order, { hash, payer: verdict.payer, seenMs: verdict.seenMs }, now);
+      if (result === "paid" || result === "paid_late") {
+        settled.push({ id: order.id, status: result });
+        byAmount.delete(amount);
+      }
+    }
+    return { scanned: true, settled };
+  } catch (e) {
+    // Fail closed: nothing is credited when the nodes cannot be read. The next scan tries again.
+    return { scanned: false, settled, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/** For tests: forget the kept send blocks. */
+export function forgetBlocks(): void {
+  blockCache.clear();
+}

package/src/shop/security.ts

@@ -0,0 +1,50 @@
+// The shop's needs in a game's Content Security Policy, as LISTS that a game merges into its own policy. Never a whole file: the game keeps every
+// source it has (its own frames, its own scripts), and adds these.
+//
+//   import { SHOP_CSP, mergeCsp } from "@nano133/nanoterra/shop";
+//   const policy = mergeCsp(MY_CSP, SHOP_CSP);
+//
+// The pay sheet draws its QR code on a canvas (no picture from another site), and the wallet key is a plain "nano:" link (a CSP does not limit links).
+// Only Turnstile (the person check, when the game turns it on) needs another origin: its script and its frame.
+
+/** Turnstile (Cloudflare's free check that a visitor is a person) loads from here. */
+export const TURNSTILE_ORIGIN = "https://challenges.cloudflare.com";
+
+/** The sources the shop adds, by directive. */
+export const SHOP_CSP: Readonly<Record<string, readonly string[]>> = {
+  "script-src": [TURNSTILE_ORIGIN],
+  "frame-src": [TURNSTILE_ORIGIN],
+  "connect-src": ["'self'"],
+};
+
+/**
+ * A policy with more sources: `policy` is a CSP text ("default-src 'none'; script-src 'self'") or a map of directives to sources, and each of `more` adds
+ * its sources to the same directive (a directive that is not there yet is added). A source is never written twice. The order of the policy is kept.
+ * A directive that has 'none' and gets a source loses the 'none' (the two cannot stand together).
+ */
+export function mergeCsp(policy: string | Readonly<Record<string, readonly string[]>>, ...more: Readonly<Record<string, readonly string[]>>[]): string {
+  const map = new Map<string, string[]>();
+  const add = (directive: string, sources: readonly string[]) => {
+    const name = directive.trim().toLowerCase();
+    if (!/^[a-z-]+$/.test(name)) throw new Error(`not a CSP directive: ${directive}`);
+    const list = map.get(name) ?? [];
+    for (const s of sources) {
+      if (!s || /[;,\s]/.test(s)) throw new Error(`not a CSP source: ${s}`);
+      if (!list.includes(s)) list.push(s);
+    }
+    map.set(name, list);
+  };
+  if (typeof policy === "string") {
+    for (const part of policy.split(";")) {
+      const [name, ...sources] = part.trim().split(/\s+/).filter(Boolean);
+      if (name) add(name, sources);
+    }
+  } else for (const [k, v] of Object.entries(policy)) add(k, v);
+  for (const m of more) for (const [k, v] of Object.entries(m)) add(k, v);
+  return [...map]
+    .map(([name, sources]) => {
+      const list = sources.length > 1 ? sources.filter((s) => s !== "'none'") : sources;
+      return list.length ? `${name} ${list.join(" ")}` : name;
+    })
+    .join("; ");
+}

package/src/shop/store.ts

@@ -0,0 +1,99 @@
+// The shop's records and the store contract. The package has no database: a game gives a store (memory, D1 or Firestore here, or its own that passes
+// "@nano133/nanoterra/shop/conformance"). The rules of money live in the store's few writes, so each one says exactly what it must do in ONE step.
+
+export type OrderStatus = "open" | "paid" | "expired" | "paid_late";
+
+/** One order: a player asked to buy a look. Amounts are raw, as text; times are ms since 1970. */
+export type ShopOrder = {
+  /** 24 hex characters. */
+  id: string;
+  /** The signed-in player who made it (the game's player id: the starter's is the Nano address). Only this player sees the order. */
+  player: string;
+  lookId: string;
+  /** The price in US dollars when the order was made: "0.25". */
+  usd: string;
+  /** Dollars per XNO that turned the price into XNO. */
+  rate: number;
+  /** The exact amount to pay: a clean amount (at most 4 decimals of XNO). */
+  amount: string;
+  /**
+   * The reservation: equal to `amount` while a payment of it may still be matched to this order, null after. No two orders ever hold the same amount
+   * (the store's unique rule), so one payment can only match one order.
+   */
+  amountLock: string | null;
+  status: OrderStatus;
+  createdAt: number;
+  /** The order takes a payment until then. */
+  expiresAt: number;
+  /** The amount stays reserved until then (a late payment is still seen, and never counts for a newer order). */
+  holdUntil: number;
+  /** The paying send block: one payment pays one order, once (the store's unique rule). */
+  hash: string | null;
+  /** The account that sent it. */
+  payer: string | null;
+  /** When the node first saw that send. */
+  paidAt: number | null;
+  /** A keyed hash of the buyer's IP address, for limits (never the address), or null. */
+  visitor: string | null;
+};
+
+/** What `settle` did. "used": that payment already paid another order. "taken": this order was settled meanwhile (or its amount is no longer held). */
+export type Settled = "paid" | "paid_late" | "used" | "taken";
+
+/** A payment the scan found: the send's hash, its account and when the node first saw it. */
+export type Payment = { hash: string; payer: string; seenMs: number };
+
+/** The price of XNO the shop keeps (the median of the feeds) and when it read it. */
+export type KeptRate = { usd: number; sources: string[]; at: number };
+
+/**
+ * What `forget` did. `waitUntil`: the player has an order whose amount is still held (a payment may still come for it), so NOTHING was deleted; try again
+ * after that time. Else `deleted` rows went (owned looks, and orders that were never paid), and `kept` paid orders stay as the creator's sales record,
+ * with the player (and the payer of a paid order) replaced by FORGOTTEN.
+ */
+export type ForgetResult = { deleted: number; kept: number; waitUntil: number | null };
+
+/** The stand-in for a player who used "Delete my data", in the orders that stay as the creator's sales record. */
+export const FORGOTTEN = "deleted";
+
+/**
+ * The shop's database. An adapter writes ONLY orders, owned looks, the kept price and the scan's claim (and their locks). Each call is ONE step: a
+ * transaction, a batch, or a statement that holds its own check.
+ */
+export interface ShopStore {
+  /** Marks the open orders past `expiresAt` "expired", and frees the amounts whose `holdUntil` is past (the amount lock goes, the order stays). */
+  tidy(now: number): Promise<void>;
+  /** Which of `amounts` an order holds now. */
+  heldAmounts(amounts: readonly string[]): Promise<Set<string>>;
+  /**
+   * Writes a new order that holds its amount (`amountLock` = `amount`). False, and nothing written, when another order holds that amount now: the
+   * unique rule, checked in the same step as the write. Any other failure throws.
+   */
+  insert(order: ShopOrder): Promise<boolean>;
+  order(id: string): Promise<ShopOrder | null>;
+  /** The newest open order of this player for this look that still runs at `until`, or null. */
+  openOrder(player: string, lookId: string, until: number): Promise<ShopOrder | null>;
+  /** How many open orders this player has that still run at `now`. */
+  countOpen(player: string, now: number): Promise<number>;
+  /** Whether a paid order gave this player this look. */
+  owns(player: string, lookId: string): Promise<boolean>;
+  /** The ids of every look that paid orders gave this player (free looks are everyone's and are not stored). */
+  owned(player: string): Promise<string[]>;
+  /** The orders whose amount is held: the only ones a payment can be matched to. */
+  held(): Promise<ShopOrder[]>;
+  /** Which of `hashes` already paid (or were recorded for) an order. */
+  usedHashes(hashes: readonly string[]): Promise<Set<string>>;
+  /**
+   * Records a payment for a held order, exactly once, in ONE step: the order becomes "paid" (sent while it was open: `pay.seenMs` at most
+   * CLOCK_SLACK_MS after `expiresAt`) and the look is given to the ORDER's player (once: one owned row per player and look), or "paid_late" (no look);
+   * either way the hash is recorded and the amount freed. "taken" when the order is not open or expired with its amount held (it was settled meanwhile,
+   * or its hold ended), else "used" when the hash paid another order. Either way nothing changes.
+   */
+  settle(order: ShopOrder, pay: Payment, now: number): Promise<Settled>;
+  /** Claims the next payment scan: true for exactly one caller in each `gapMs`. */
+  claimScan(now: number, gapMs: number): Promise<boolean>;
+  readRate(): Promise<KeptRate | null>;
+  saveRate(rate: KeptRate): Promise<void>;
+  /** "Delete my data" for the shop (see ForgetResult). */
+  forget(player: string, now: number): Promise<ForgetResult>;
+}

package/src/shop/worker.ts

@@ -0,0 +1,107 @@
+// The shop for a Cloudflare Worker with D1, set up from the game starter's own settings (wrangler.jsonc "vars" and secrets). One call gives the routes,
+// the cron's payment scan, what the page and the admin need to know, and the store:
+//
+//   import { createShop } from "@nano133/nanoterra/shop/worker";
+//   import looks from "../../looks.json";
+//   const shop = createShop(env, { catalogue: looks, player: async (req) => (await sessionOf(env.DB, req))?.address ?? null });
+//   const answer = await shop.handle(request);            // null when it is not a shop route
+//   ...
+//   async scheduled(_e, env, ctx) { ctx.waitUntil(createShop(env, opts).scan()); }   // the */10 cron
+//
+// The settings (the starter's names): RECEIVE_ADDRESS (the creator's address; the example or a wrong checksum keeps test mode), TEST_MODE ("on" keeps
+// test mode with a real address), NODE_API_KEY (secret, optional: Nanswap Nodes first), NANO_NODES (optional: the game's own nodes), TURNSTILE_SITE_KEY
+// and the secret TURNSTILE_SECRET (both, or no person check). "none", "skip", "off" and "-" mean "not set". The store is D1 on the starter's tables
+// (`env.DB`; the migration is "@nano133/nanoterra/shop/d1.sql"). The player's sign-in is the game's own (`player`).
+
+import type { D1Like } from "../admin/adapters/d1.js";
+import { createD1Shop, d1Limit, visitorKey, type ShopTables } from "./adapters/d1.js";
+import { createShopHandler, SHOP_LIMITS, type ShopHandler, type ShopHandlerOptions } from "./handler.js";
+import { nodesFor, settingValue, type Fetch } from "./nodes.js";
+import type { ShopStore } from "./store.js";
+
+/** The settings the shop reads. Every one is optional except the database. */
+export type ShopEnv = {
+  DB: D1Like;
+  RECEIVE_ADDRESS?: string;
+  TEST_MODE?: string;
+  NODE_API_KEY?: string;
+  NANO_NODES?: string;
+  TURNSTILE_SITE_KEY?: string;
+  TURNSTILE_SECRET?: string;
+};
+
+export type ShopOptions = Pick<ShopHandlerOptions, "catalogue" | "player" | "base" | "now" | "onError" | "rate" | "rpc"> & {
+  /** The D1 table names (default: the starter's). */
+  tables?: ShopTables;
+  /** The `fetch` for Turnstile's check (a test gives its own). */
+  fetch?: Fetch;
+};
+
+const VERIFY = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+
+/** "on", "true", "1" or "yes" (any case). */
+const isOn = (v?: string) => /^(on|true|1|yes)$/i.test((v ?? "").trim());
+
+/** Whether Turnstile is on: the site key AND the secret are both set. */
+export const turnstileOn = (env: Pick<ShopEnv, "TURNSTILE_SITE_KEY" | "TURNSTILE_SECRET">): boolean => Boolean(settingValue(env.TURNSTILE_SECRET) && settingValue(env.TURNSTILE_SITE_KEY));
+
+/** True when the person check passes, or when Turnstile is off (the starter's turnstile.ts). The secret is sent to Cloudflare only. */
+export async function turnstileCheck(env: Pick<ShopEnv, "TURNSTILE_SITE_KEY" | "TURNSTILE_SECRET">, token: unknown, ip: string | null, fetchFn: Fetch = (i, init) => fetch(i, init)): Promise<boolean> {
+  if (!turnstileOn(env)) return true;
+  if (typeof token !== "string" || !token || token.length > 2048) return false;
+  const form = new FormData();
+  form.append("secret", settingValue(env.TURNSTILE_SECRET)!);
+  form.append("response", token);
+  if (ip) form.append("remoteip", ip);
+  try {
+    const res = await fetchFn(VERIFY, { method: "POST", body: form, signal: AbortSignal.timeout(5000) });
+    const out = (await res.json()) as { success?: boolean };
+    return out.success === true;
+  } catch {
+    return false;
+  }
+}
+
+export type Shop = ShopHandler & {
+  store: ShopStore;
+  /** What the game's page needs (the starter's GET /api/config gives these two): whether pay screens are in test mode, and Turnstile's site key or null. */
+  config(): { testMode: boolean; turnstileSiteKey: string | null };
+  /** For the admin's Status card: the address, test mode, Turnstile, the nodes' names and plain sentences about what is still off. */
+  status(): { address: string | null; testMode: boolean; turnstile: boolean; nodes: string[]; warnings: string[] };
+};
+
+export function createShop(env: ShopEnv, options: ShopOptions): Shop {
+  const store = createD1Shop(env.DB, { tables: options.tables });
+  const nodes = nodesFor(env);
+  const turnstile = turnstileOn(env);
+  const handler = createShopHandler({
+    ...options,
+    store,
+    payee: env.RECEIVE_ADDRESS ?? null,
+    testMode: isOn(env.TEST_MODE),
+    nodes,
+    visitor: (req) => visitorKey(env.DB, req, { meta: options.tables?.meta }),
+    // Two layers, as the starter: the game's router counts every call in memory; this one counts new orders for the whole game, in D1 (`hits`).
+    limit: (key, limit, windowMs, at) => d1Limit(env.DB, key, limit, windowMs, at),
+    personCheck: turnstile ? (token, req) => turnstileCheck(env, token, req.headers.get("CF-Connecting-IP"), options.fetch) : undefined,
+  });
+  return {
+    ...handler,
+    store,
+    config: () => ({ testMode: handler.testMode, turnstileSiteKey: turnstile ? settingValue(env.TURNSTILE_SITE_KEY)! : null }),
+    status() {
+      const warnings: string[] = [];
+      if (handler.testMode) warnings.push(handler.payee ? "Test mode is on (TEST_MODE). Pay screens say TEST MODE: DO NOT PAY." : "Test mode: no receive address is set.");
+      if (!turnstile)
+        warnings.push(
+          settingValue(env.TURNSTILE_SECRET) || settingValue(env.TURNSTILE_SITE_KEY)
+            ? "Turnstile is OFF: set both TURNSTILE_SITE_KEY and the secret TURNSTILE_SECRET."
+            : "Turnstile is OFF: sign-in and orders are not checked for bots. Add a free Turnstile widget (see README).",
+        );
+      if (!settingValue(env.NODE_API_KEY)) warnings.push("No NODE_API_KEY: payments are checked on public Nano nodes only, which promise no uptime.");
+      return { address: handler.payee, testMode: handler.testMode, turnstile, nodes: nodes.map((n) => n.name), warnings };
+    },
+  };
+}
+
+export { SHOP_LIMITS };