= {
+ 38172: "cashu announcements",
+ 38173: "fedimint announcements",
+ 38000: "reviews",
+ 0: "profiles (firehose — no authors)",
+ 10002: "relay lists (firehose — no authors)",
+};
+
+/**
+ * The one and only route. No router: a single `/` view dumping everything
+ * Dexie has.
+ *
+ * Boot discipline:
+ * - db + pool + fetcher + scheduler are created exactly once at module
+ * load (outside the component) so React 19 StrictMode's double-invoke
+ * of effects in dev can't produce two schedulers fighting over the
+ * same Dexie. The effect body then does `scheduler.start()` on every
+ * mount and `scheduler.stop()` on every cleanup — the scheduler is
+ * idempotent across those calls (start resets `stopped`, stop drains
+ * in-flight Layer B work), so StrictMode's double-invoke produces
+ * start → stop → start exactly as intended rather than leaving us
+ * stuck after the first cleanup.
+ *
+ * Stats refresh:
+ * - getStats() returns a plain snapshot; we poll it on a 500ms ticker so
+ * the `` at the top advances even when Dexie writes are quiet (the
+ * Dexie-triggered `useLiveQuery` in MintList would otherwise be the
+ * only re-render driver, and it only fires on row changes — not when
+ * `eventsReceived` increments without a write).
+ */
+const db = new BitcoinmintsDB();
+const pool = createPool({ relays: [...SEED_RELAYS] });
+const fetcher = createMintInfoFetcher({ concurrency: 4 });
+/**
+ * Debug logging is a demo/X-ray aid, toggled via `?debug` on the URL (any
+ * presence wins; no value parsing). When enabled, the scheduler logs its
+ * filters/relays on start(), a per-event path line, and a per-Layer-B
+ * verdict line — all through `console.log`/`console.warn` with the
+ * `[scheduler]` prefix. Deliberately URL-toggled (not env-baked) so an
+ * alchemist can flip it on during a live demo without rebuilding.
+ */
+const DEBUG_SCHEDULER =
+ typeof window !== "undefined" && new URLSearchParams(window.location.search).has("debug");
+const scheduler: Scheduler = createScheduler({
+ db,
+ pool,
+ fetcher,
+ relays: SEED_RELAYS,
+ debug: DEBUG_SCHEDULER,
+});
+
+const STATS_POLL_MS = 500;
+
+export function App(): JSX.Element {
+ const [stats, setStats] = useState(scheduler.getStats());
+
+ useEffect(() => {
+ void scheduler.start();
+ const handle = window.setInterval(() => {
+ setStats(scheduler.getStats());
+ }, STATS_POLL_MS);
+ return () => {
+ window.clearInterval(handle);
+ // Fire-and-forget stop(): app unmount means page navigation away or
+ // dev-HMR, either way we want the subscription closed. We don't await
+ // because React's effect-cleanup contract is synchronous.
+ void scheduler.stop();
+ };
+ }, []);
+
+ // Static derivations for the X-ray — computed once per render, but the
+ // inputs are module-constants so React's reconciler is effectively a
+ // no-op on these blocks.
+ const kinds = getSubscribedKinds();
+ // The widest kind label is 5 chars (e.g. "38172"). Pad to align.
+ const filtersBlock = kinds
+ .map((k) => {
+ const label = KIND_LABELS[k] ?? "";
+ const padded = `{ kinds: [${String(k).padEnd(5, " ")}] }`;
+ return ` ${padded} ${label}`;
+ })
+ .join("\n");
+ const relaysBlock = SEED_RELAYS.map((r) => ` ${r}`).join("\n");
+
+ return (
+
+
scheduler stats
+
{JSON.stringify(stats, null, 2)}
+ {/*
+ Counter note: all scheduler stats are monotonically increasing
+ EXCEPT `layerBPending`, which is transient — it goes up on
+ enqueue and back down when Layer B completes. The alchemist
+ observed it "going up then down" during the prior demo; this
+ comment exists so the next viewer doesn't flag it as a bug.
+ */}
+
counters: monotonic, except layerBPending (transient: enqueue↑ / complete↓)
+
+
+
filters in use
+
{filtersBlock}
+
relays
+
{relaysBlock}
+
+
+
validation paths
+
{VALIDATION_PATHS_TABLE}
+
+
+
+
`
+ * blocks. Source of truth: scheduler/index.ts:onEvent switch.
+ *
+ * Hand-aligned fixed-width columns — edit with care. If a column grows
+ * past its width, widen the whole column rather than wrapping mid-row.
+ */
+const VALIDATION_PATHS_TABLE = `
+kind parser Layer A gate Layer B counters
+───── ────── ──────────── ─────── ────────
+38172 cashu parseMintAnnouncement upsertAnnouncement d-tag + spam verifySignerBinding /v1/info × parse-null → drop
+ (needs d + ≥1 u) check pubkey match rejected → rejectedByLayerA
+ accepted → accepted + layerBPending
+
+38173 fedimint parseMintAnnouncement upsertAnnouncement d-tag + spam none same as 38172 minus Layer B
+ (needs d + ≥1 u) check
+
+38000 review parseReview upsertReviewWithAggregate d-tag none parse-null → rejectedByParse
+ check rejected → rejectedByLayerA
+ accepted → accepted
+
+0 profile toProfileRow upsertProfile none null → drop
+ accepted → accepted
+
+10002 relay toRelayListRow upsertRelayList none same as kind 0
+list
+`;
diff --git a/packages/app/src/components/MintList.tsx b/packages/app/src/components/MintList.tsx
new file mode 100644
index 0000000..7d778c5
--- /dev/null
+++ b/packages/app/src/components/MintList.tsx
@@ -0,0 +1,97 @@
+import {
+ type AnnouncementRow,
+ type BitcoinmintsDB,
+ type MintAggregateRow,
+ type MintInfoRow,
+ rankMints,
+} from "@bitcoinmints/core";
+import { useLiveQuery } from "dexie-react-hooks";
+import type { JSX } from "react";
+import { MintRow } from "./MintRow";
+
+/**
+ * The whole list surface for PR #6 — spec is raw field dump per mint,
+ * sorted by `bayesianScore` DESC via `rankMints(db, 50)`.
+ *
+ * Join strategy: one unified `useLiveQuery` at this level pre-joins
+ * aggregate → announcement → mintInfo and hands `` fully-resolved
+ * props. Previously we had a per-row `useLiveQuery` which resolved a
+ * microtask after the aggregate query, causing a ~1s "(no announcement)"
+ * placeholder flash on reload. Single query kills the flash.
+ */
+type Props = {
+ db: BitcoinmintsDB;
+};
+
+type JoinedRow = {
+ aggregate: MintAggregateRow;
+ announcement: AnnouncementRow | undefined;
+ info: MintInfoRow | undefined;
+};
+
+export function MintList({ db }: Props): JSX.Element {
+ // Order: rankMints() returns aggregates sorted by bayesianScore DESC.
+ // A mint with no reviews yet has no aggregate row, so this list can
+ // lag behind `announcements` — that's intentional. PR #7 will decide
+ // whether to render un-reviewed announcements as a tail section; for
+ // the X-ray we follow the ranked-aggregate-as-truth posture.
+ //
+ // Render-filter note: we drop non-Cashu announcements (kind !== 38172)
+ // below so the X-ray matches spec v1 (Cashu-only). The parse layer still
+ // stores k=38173 (Fedimint) rows and `rankMints` still ranks them — PR
+ // #7+ may surface those elsewhere. Keep this filter in the UI; do NOT
+ // push it into `rankMints` (don't mutate core for a UI-only concern).
+ const rows = useLiveQuery(
+ async () => {
+ const aggregates = await rankMints(db, 50);
+ const ds = aggregates.map((a) => a.d);
+ const announcements = await db.announcements.where("d").anyOf(ds).toArray();
+ const infos = await db.mintInfo.bulkGet(ds);
+ // A single `d` CAN map to multiple announcements (different pubkeys).
+ // Map.set keeps whichever appears LAST in `toArray()`; that matches
+ // the previous per-row `.first()` behavior only by luck-of-insert-order.
+ // PR #7 will resolve the ambiguity properly.
+ const annByD = new Map(announcements.map((a) => [a.d, a]));
+ // bulkGet returns an array in the same order as the keys; index align.
+ return aggregates.map((agg, i) => ({
+ aggregate: agg,
+ announcement: annByD.get(agg.d),
+ info: infos[i],
+ }));
+ },
+ [db],
+ [],
+ );
+
+ // Render-only Cashu filter (see note above). Orphan aggregates (no
+ // announcement — shouldn't happen in practice) are also dropped
+ // defensively so we never flash a "(no announcement)" row.
+ const visible = rows.filter((r) => r.announcement !== undefined && r.announcement.kind === 38172);
+
+ // Empty state per spec: stats block still renders (that's in App.tsx),
+ // the `mints` header always renders, and if there's nothing to show the
+ // single line `no mints yet` sits below it.
+ if (visible.length === 0) {
+ return (
+ <>
+ mints
+ no mints yet
+
+ );
+ }
+
+ return (
+ <>
+ mints
+ {visible.map((row, i) => (
+
+ ))}
+
+ );
+}
diff --git a/packages/app/src/components/MintRow.tsx b/packages/app/src/components/MintRow.tsx
new file mode 100644
index 0000000..06ba539
--- /dev/null
+++ b/packages/app/src/components/MintRow.tsx
@@ -0,0 +1,137 @@
+import type { AnnouncementRow, MintAggregateRow, MintInfoRow } from "@bitcoinmints/core";
+import type { JSX } from "react";
+
+/**
+ * Two-tier X-ray render of a single mint.
+ *
+ * Tier 1 — human-readable top matter pulled out of `info.infoJson` (NUT-06):
+ * name, description, version, motd, contact, urls, rating/score/verified.
+ *
+ * Tier 0 — de-emphasized technical identifiers (d, pubkey, kind) pinned below
+ * the top matter for X-ray debugging; deliberately small + faded, not
+ * user-facing content.
+ *
+ * Tier 2 — collapsed blocks for the raw mintInfo, announcement, and
+ * aggregate JSON, so the full shape (including rawTags, sig, etc.) stays
+ * inspectable without drowning the first glance.
+ *
+ * Browser-native disclosure — no dep, no state, no animation.
+ */
+type Props = {
+ aggregate: MintAggregateRow;
+ announcement: AnnouncementRow | undefined;
+ info: MintInfoRow | undefined;
+ /** Final row in the list gets no trailing
. */
+ isLast: boolean;
+};
+
+/**
+ * Render the NUT-06 `contact` field. The spec says it's an array of
+ * `{ method, info }` objects, but mints in the wild have been seen emitting
+ * the older array-of-tuples shape (`[[method, info], ...]`). Handle both
+ * defensively — anything that doesn't match either shape is skipped rather
+ * than crashing the row render.
+ */
+function renderContact(contact: unknown): string[] {
+ if (!Array.isArray(contact)) return [];
+ const lines: string[] = [];
+ for (const entry of contact) {
+ if (Array.isArray(entry) && entry.length >= 2) {
+ // Legacy tuple shape: ["email", "foo@bar"].
+ const [method, value] = entry;
+ if (typeof method === "string" && typeof value === "string") {
+ lines.push(`contact: ${method} ${value}`);
+ }
+ continue;
+ }
+ if (entry && typeof entry === "object") {
+ // NUT-06 object shape: { method, info }.
+ const obj = entry as Record;
+ const method = obj.method;
+ const value = obj.info;
+ if (typeof method === "string" && typeof value === "string") {
+ lines.push(`contact: ${method} ${value}`);
+ }
+ }
+ }
+ return lines;
+}
+
+export function MintRow({ aggregate, announcement, info, isLast }: Props): JSX.Element {
+ const body = info?.infoJson as Record | undefined;
+
+ const name = typeof body?.name === "string" && body.name.length > 0 ? body.name : undefined;
+ const description = typeof body?.description === "string" ? body.description : undefined;
+ const version = typeof body?.version === "string" ? body.version : undefined;
+ const motd = typeof body?.motd === "string" ? body.motd : undefined;
+ const contactLines = renderContact(body?.contact);
+
+ const urls = announcement?.u ?? [];
+
+ const ratedCount = aggregate.ratedCount;
+ const reviewCount = aggregate.reviewCount;
+ const avg = aggregate.avgRating;
+ const ratingLine =
+ avg === null
+ ? `rating: — (${reviewCount} total, 0 rated)`
+ : `rating: ${avg}/5 (${ratedCount} ratings, ${reviewCount} total)`;
+
+ const verifiedLabel = announcement
+ ? announcement.verifiedBySignerBinding === true
+ ? "verified"
+ : announcement.verifiedBySignerBinding === false
+ ? "unverified"
+ : "pending"
+ : "(no announcement)";
+
+ // Tier 0 identifiers — present even if announcement is missing so the
+ // dangling-aggregate state is still visible.
+ const pubkey = announcement?.pubkey ?? "(no announcement)";
+ const d = aggregate.d;
+ const kind = announcement?.kind ?? "(no announcement)";
+
+ return (
+ <>
+ name: {name ?? "(no name)"}
+ {description && description: {description}
}
+ {urls.map((url) => (
+ url: {url}
+ ))}
+ {ratingLine}
+ score: {aggregate.bayesianScore}
+ verified: {verifiedLabel}
+ {version && version: {version}
}
+ {motd && motd: {motd}
}
+ {contactLines.map((line) => (
+ {line}
+ ))}
+
+
+
d: {d}
+
pubkey: {pubkey}
+
kind: {String(kind)}
+
+ raw mintInfo
+ {JSON.stringify(info, null, 2)}
+
+ ) : (
+ mintInfo: (none)
+ )}
+ {announcement && (
+
+ raw announcement
+ {JSON.stringify(announcement, null, 2)}
+
+ )}
+
+ raw aggregate
+ {JSON.stringify(aggregate, null, 2)}
+
+
+ {!isLast &&
}
+
+ );
+}
diff --git a/packages/app/src/index.css b/packages/app/src/index.css
new file mode 100644
index 0000000..b5c61c9
--- /dev/null
+++ b/packages/app/src/index.css
@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
diff --git a/packages/app/src/index.ts b/packages/app/src/index.ts
deleted file mode 100644
index cb0ff5c..0000000
--- a/packages/app/src/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-export {};
diff --git a/packages/app/src/lib/utils.ts b/packages/app/src/lib/utils.ts
new file mode 100644
index 0000000..f1f0551
--- /dev/null
+++ b/packages/app/src/lib/utils.ts
@@ -0,0 +1,11 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * shadcn-style class-name merge helper. Not used in PR #6 (data-dump
+ * X-ray has no designed UI), but committed as part of the shadcn init so
+ * PR #7+ can drop in `shadcn add ` without reshaping imports.
+ */
+export function cn(...inputs: ClassValue[]): string {
+ return twMerge(clsx(inputs));
+}
diff --git a/packages/app/src/main.tsx b/packages/app/src/main.tsx
new file mode 100644
index 0000000..94013d9
--- /dev/null
+++ b/packages/app/src/main.tsx
@@ -0,0 +1,20 @@
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+import "./index.css";
+
+const rootEl = document.getElementById("root");
+if (!rootEl) {
+ throw new Error("root element not found");
+}
+
+// StrictMode is intentionally omitted. The scheduler's idempotency is
+// sequenced around `startReady` so stop() must await the in-progress
+// start() before closing the handle; StrictMode's double-invoke of
+// effects ends up no-opping the second start (the stopped flag latches
+// true after cleanup 1 completes inside start's microtask-chained body)
+// which leaves the app with no active relay subscription in dev. Not a
+// correctness bug in the scheduler — it's doing what its contract says —
+// but the useEffect dance for sync start + async stop under double-invoke
+// is not worth the churn for a data-dump X-ray. Production mounts once.
+// PR #7+ can revisit this if a more robust teardown pattern is needed.
+createRoot(rootEl).render();
diff --git a/packages/app/tailwind.config.js b/packages/app/tailwind.config.js
new file mode 100644
index 0000000..93aa364
--- /dev/null
+++ b/packages/app/tailwind.config.js
@@ -0,0 +1,8 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+ content: ["./index.html", "./src/**/*.{ts,tsx}"],
+ theme: {
+ extend: {},
+ },
+ plugins: [],
+};
diff --git a/packages/app/tsconfig.json b/packages/app/tsconfig.json
index bf5a36d..291db67 100644
--- a/packages/app/tsconfig.json
+++ b/packages/app/tsconfig.json
@@ -1,4 +1,12 @@
{
"extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "jsx": "react-jsx",
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
+ "types": ["vite/client"],
+ "paths": {
+ "@/*": ["./src/*"]
+ }
+ },
"include": ["src/**/*"]
}
diff --git a/packages/app/vite.config.ts b/packages/app/vite.config.ts
new file mode 100644
index 0000000..8696102
--- /dev/null
+++ b/packages/app/vite.config.ts
@@ -0,0 +1,22 @@
+import path from "node:path";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+/**
+ * Vite config for the bitcoinmints X-ray app.
+ *
+ * This PR (#6) is the data-dump verifier — we want Vite + React + the
+ * workspace `@bitcoinmints/core` on the module graph and nothing more.
+ * PR #7+ will layer designed UI on top.
+ *
+ * The `@/*` alias matches shadcn's components.json so future scaffolding
+ * (PR #7+) drops in without reshaping imports.
+ */
+export default defineConfig({
+ plugins: [react()],
+ resolve: {
+ alias: {
+ "@": path.resolve(__dirname, "src"),
+ },
+ },
+});
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 302e547..faba74b 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -3,5 +3,6 @@ export * from "./cashu";
export * from "./nip87";
export * from "./nostr";
export * from "./reviews";
+export * from "./scheduler";
export const VERSION = "0.0.0";
diff --git a/packages/core/src/nostr/pool.test.ts b/packages/core/src/nostr/pool.test.ts
index 5f50ada..9e758af 100644
--- a/packages/core/src/nostr/pool.test.ts
+++ b/packages/core/src/nostr/pool.test.ts
@@ -31,16 +31,22 @@ vi.mock("nostr-tools/pool", () => {
import { createPool, SEED_RELAYS } from "./pool";
describe("SEED_RELAYS", () => {
- it("exports exactly the five-relay default seed pool from the spec", () => {
+ it("exports exactly the seven-relay default seed pool from the spec", () => {
// Top 3 are the ecosystem-consensus NIP-87 implementor defaults
// (damus 6/6, nos.lol 5/6, primal 4/6 across 6 surveyed hardcoders).
- // Last 2 are cashu-branded relays — thin on event count but part of the
- // cashu community's curated NIP-87 surface.
+ // Next 3 are audited secondary relays with real k38172 event counts
+ // (nostr.mom 8, relay.nostr.wirednet.jp 4, relay.nostrplebs.com 2)
+ // — added to widen the Cashu catch past the power-law knee. Last is
+ // relay.cashumints.space (cashu-branded, thin on events but part of
+ // the community's curated NIP-87 surface). relay.8333.space was
+ // dropped per audit: defunct / handshake timeout.
expect(SEED_RELAYS).toEqual([
"wss://nos.lol",
"wss://relay.damus.io",
"wss://relay.primal.net",
- "wss://relay.8333.space",
+ "wss://nostr.mom",
+ "wss://relay.nostr.wirednet.jp",
+ "wss://relay.nostrplebs.com",
"wss://relay.cashumints.space",
]);
});
diff --git a/packages/core/src/nostr/pool.ts b/packages/core/src/nostr/pool.ts
index 28ca6df..6304fb6 100644
--- a/packages/core/src/nostr/pool.ts
+++ b/packages/core/src/nostr/pool.ts
@@ -10,16 +10,25 @@ import { SimplePool } from "nostr-tools/pool";
* nos.lol + damus alone carry 98.4% of all historical NIP-87 events per
* /srv/forge/projects/bitcoinmints/audit/relay-strategy-v1.md.
*
- * relay.8333.space + relay.cashumints.space are cashu-branded relays included
- * for ecosystem citizenship — thin on event count but part of the cashu
- * community's curated NIP-87 surface (8333 is cashu.me's extra default;
- * cashumints.space appears in 2/6 implementor defaults).
+ * Extended with three audited secondary relays (nostr.mom 8 × k38172,
+ * relay.nostr.wirednet.jp 4, relay.nostrplebs.com 2) to widen the Cashu
+ * catch. The alchemist demo against the prior 5-relay seed found only 1
+ * Cashu announcement on the wire — adding these pushes us past the
+ * power-law knee documented in the audit (§3 cumulative table).
+ *
+ * relay.cashumints.space is the sole cashu-branded holdover — thin on event
+ * count (only 4 historical events per audit) but part of the cashu
+ * community's curated NIP-87 surface. relay.8333.space was dropped: the
+ * audit reports a handshake timeout and classifies it as defunct despite
+ * matching the audit.8333 domain.
*/
export const SEED_RELAYS: readonly string[] = [
"wss://nos.lol",
"wss://relay.damus.io",
"wss://relay.primal.net",
- "wss://relay.8333.space",
+ "wss://nostr.mom",
+ "wss://relay.nostr.wirednet.jp",
+ "wss://relay.nostrplebs.com",
"wss://relay.cashumints.space",
];
diff --git a/packages/core/src/scheduler/index.test.ts b/packages/core/src/scheduler/index.test.ts
index 518f335..31ce019 100644
--- a/packages/core/src/scheduler/index.test.ts
+++ b/packages/core/src/scheduler/index.test.ts
@@ -788,3 +788,54 @@ describe("scheduler — backoff cap", () => {
await sched.stop();
});
});
+
+describe("scheduler — debug logging opt-in", () => {
+ // We assert the negative-case contract: debug unset (and debug=false,
+ // exercised via the default) produces ZERO console.log calls from the
+ // scheduler. We don't assert the `debug=true` output verbatim — that
+ // log format is a demo/X-ray aid and asserting exact strings would
+ // brittle the tests against formatting tweaks.
+ it("default (debug unset) produces no scheduler console.log across a full pipeline run", async () => {
+ const db = await freshDB();
+ const { pool, pushEvent } = makeFakePool();
+ const pubkey = "02".padEnd(66, "7");
+ const { fetcher } = makeFetcher({ "https://mint.example.com": pubkey });
+ const sched = createScheduler({ db, pool, fetcher, relays: ["wss://test"] });
+
+ const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+ try {
+ await sched.start();
+ // Exercise each kind's path so any path-level log would fire.
+ await pushEvent(makeAnnouncement({ pubkey, d: pubkey, u: ["https://mint.example.com"] }));
+ await pushEvent({
+ id: "review-debug",
+ kind: 38000,
+ pubkey: "reviewer".padEnd(64, "0"),
+ created_at: 1_700_000_000,
+ tags: [
+ ["k", "38172"],
+ ["d", pubkey],
+ ["rating", "5", "5"],
+ ],
+ content: "[5/5] fine",
+ sig: "fake",
+ });
+ await pushEvent({
+ id: "profile-debug",
+ kind: 0,
+ pubkey: "profile".padEnd(64, "0"),
+ created_at: 1_700_000_001,
+ tags: [],
+ content: "{}",
+ sig: "fake",
+ });
+ await settle();
+ await sched.stop();
+
+ // Zero calls: confirms debug-off is a pure no-op for logging cost.
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ logSpy.mockRestore();
+ }
+ });
+});
diff --git a/packages/core/src/scheduler/index.ts b/packages/core/src/scheduler/index.ts
index 2f8bb62..1e8fc36 100644
--- a/packages/core/src/scheduler/index.ts
+++ b/packages/core/src/scheduler/index.ts
@@ -134,11 +134,39 @@ export type SchedulerConfig = {
relays: readonly string[];
/** Optional clock injector for deterministic backoff tests. Defaults to Date.now. */
now?: () => number;
+ /**
+ * Opt-in per-event debug logging. Default `false` — zero perf cost when
+ * off (no allocations, no logs).
+ *
+ * When `true`, logs through `console.log` / `console.warn` with the
+ * stable `[scheduler]` prefix:
+ * - on start(): the filters array being sent to relays + the configured
+ * relay list
+ * - per event (after the switch branch resolves): kind, id prefix,
+ * delivering relay, and the resolved path (accepted / rejected-*
+ * / dropped / replaced)
+ * - per Layer B resolution: kind/id/url + verdict (verified /
+ * failed: / transient)
+ *
+ * Keep the surface console-only — no structured logger is wired through
+ * the package. Intended as a demo/X-ray aid, not production telemetry.
+ */
+ debug?: boolean;
};
/** NIP-87 + supporting kinds. See data-model-v1.md §1 for the full list. */
const SUBSCRIBED_KINDS = [38172, 38173, 38000, 0, 10002] as const;
+/**
+ * Expose the subscribed kinds tuple for UI consumers that want to render
+ * "filters in use" without duplicating the literal. Frozen through
+ * `as const` in the declaration above, so callers cannot mutate the
+ * underlying array.
+ */
+export function getSubscribedKinds(): readonly number[] {
+ return SUBSCRIBED_KINDS;
+}
+
/** Initial backoff window for a failed mint URL: attempts=0 → 30s. */
const BASE_BACKOFF_MS = 30_000;
/** Cap at 1 hour. */
@@ -269,6 +297,7 @@ function toRelayListRow(event: NostrEvent): RelayListRow | null {
export function createScheduler(config: SchedulerConfig): Scheduler {
const { db, pool, fetcher } = config;
const now = config.now ?? Date.now;
+ const debug = config.debug ?? false;
const stats: SchedulerStats = {
eventsReceived: 0,
@@ -552,6 +581,23 @@ export function createScheduler(config: SchedulerConfig): Scheduler {
} else {
stats.layerBFailed += 1;
}
+
+ if (debug) {
+ // Verdict mirrors `verdictForPersistence` shape: verified=true →
+ // verified; pubkey-mismatch → failed:; anything else →
+ // transient (the row stays null and will be retried).
+ let verdict: string;
+ if (result.verified) {
+ verdict = "verified";
+ } else if (typeof result.reason === "string" && result.reason.startsWith("pubkey-mismatch")) {
+ verdict = `failed:${result.reason}`;
+ } else {
+ verdict = `transient:${result.reason ?? "unknown"}`;
+ }
+ console.log(
+ `[scheduler] layerB kind=38172 id=${row.eventId.slice(0, 8)} url=${persistedUrl} verdict=${verdict}`,
+ );
+ }
}
/**
@@ -590,8 +636,20 @@ export function createScheduler(config: SchedulerConfig): Scheduler {
* gap). Log surface matches `reenqueueUnverified`'s existing pattern:
* a `[scheduler]`-prefixed console call, no structured logger is wired
* through the package yet.
+ *
+ * `relay` is the wss:// URL that delivered the event, threaded through
+ * from the pool's `onEvent(event, relay)` callback purely so the
+ * opt-in debug log line can include it. It is NOT otherwise used by
+ * the scheduler (single global watermark, no per-relay bookkeeping).
*/
- async function onEvent(event: NostrEvent): Promise {
+ // path labels for the debug per-event line. Kept narrow so we can't
+ // typo a path name and have it silently fall through.
+ type EventPath = "accepted" | "rejected-layerA" | "rejected-parse" | "dropped" | "replaced";
+ const logPath = (kind: number, eventId: string, relay: string, path: EventPath): void => {
+ if (!debug) return;
+ console.log(`[scheduler] kind=${kind} id=${eventId.slice(0, 8)} relay=${relay} path=${path}`);
+ };
+ async function onEvent(event: NostrEvent, relay: string): Promise {
if (stopped) return;
stats.eventsReceived += 1;
@@ -600,11 +658,16 @@ export function createScheduler(config: SchedulerConfig): Scheduler {
case 38173: {
try {
const parsed = parseMintAnnouncement(event);
- if (!parsed) return;
+ if (!parsed) {
+ logPath(event.kind, event.id, relay, "dropped");
+ return;
+ }
const row = toAnnouncementRow(parsed);
const result = await upsertAnnouncement(db, row);
if (result === "rejected-invalid") {
stats.rejectedByLayerA += 1;
+ logPath(event.kind, event.id, relay, "rejected-layerA");
+ return;
}
if (result === "inserted" || result === "replaced") {
stats.accepted += 1;
@@ -615,7 +678,12 @@ export function createScheduler(config: SchedulerConfig): Scheduler {
if (event.kind === 38172) {
enqueueLayerB(row);
}
+ logPath(event.kind, event.id, relay, result === "replaced" ? "replaced" : "accepted");
+ return;
}
+ // rejected-stale or any other terminal upsert result: count as
+ // a drop so the trace doesn't go silent on duplicates.
+ logPath(event.kind, event.id, relay, "dropped");
} catch (err) {
stats.handlerErrors += 1;
console.error("[scheduler] handler error", {
@@ -638,17 +706,22 @@ export function createScheduler(config: SchedulerConfig): Scheduler {
// — neither should reach here in a healthy pipeline but both
// are silent drops worth counting (silent-failure gap).
stats.rejectedByParse += 1;
+ logPath(event.kind, event.id, relay, "rejected-parse");
return;
}
const result = await upsertReviewWithAggregate(db, row, now);
if (result === "inserted" || result === "replaced") {
stats.accepted += 1;
updateWatermark(event.kind, event.created_at);
+ logPath(event.kind, event.id, relay, result === "replaced" ? "replaced" : "accepted");
} else if (result === "rejected-invalid") {
// Layer A gate on reviews: pointing at a bot-spam d-tag. Count
// under the same stats bucket as the announcement Layer A
// rejection — it's the same firewall.
stats.rejectedByLayerA += 1;
+ logPath(event.kind, event.id, relay, "rejected-layerA");
+ } else {
+ logPath(event.kind, event.id, relay, "dropped");
}
} catch (err) {
stats.handlerErrors += 1;
@@ -663,11 +736,17 @@ export function createScheduler(config: SchedulerConfig): Scheduler {
case 0: {
try {
const row = toProfileRow(event);
- if (!row) return;
+ if (!row) {
+ logPath(event.kind, event.id, relay, "dropped");
+ return;
+ }
const result = await upsertProfile(db, row);
if (result === "inserted" || result === "replaced") {
stats.accepted += 1;
updateWatermark(event.kind, event.created_at);
+ logPath(event.kind, event.id, relay, result === "replaced" ? "replaced" : "accepted");
+ } else {
+ logPath(event.kind, event.id, relay, "dropped");
}
} catch (err) {
stats.handlerErrors += 1;
@@ -682,11 +761,17 @@ export function createScheduler(config: SchedulerConfig): Scheduler {
case 10002: {
try {
const row = toRelayListRow(event);
- if (!row) return;
+ if (!row) {
+ logPath(event.kind, event.id, relay, "dropped");
+ return;
+ }
const result = await upsertRelayList(db, row);
if (result === "inserted" || result === "replaced") {
stats.accepted += 1;
updateWatermark(event.kind, event.created_at);
+ logPath(event.kind, event.id, relay, result === "replaced" ? "replaced" : "accepted");
+ } else {
+ logPath(event.kind, event.id, relay, "dropped");
}
} catch (err) {
stats.handlerErrors += 1;
@@ -699,6 +784,7 @@ export function createScheduler(config: SchedulerConfig): Scheduler {
return;
}
default:
+ logPath(event.kind, event.id, relay, "dropped");
return; // unknown kind — ignore
}
}
@@ -745,15 +831,20 @@ export function createScheduler(config: SchedulerConfig): Scheduler {
// duplicates CAS-fail at the cache layer.
return since !== undefined ? { kinds: [kind], since } : { kinds: [kind] };
});
+ if (debug) {
+ console.log(
+ `[scheduler] start — filters=${JSON.stringify(filters)} relays=${JSON.stringify(config.relays)}`,
+ );
+ }
handle = pool.subscribe({
filters,
- onEvent: (event) => {
+ onEvent: (event, relay) => {
// onEvent returns a promise; we don't await here because the
// pool callback contract is sync. Each kind's case body wraps
// its own try/catch that counts into stats.handlerErrors, so
// a thrown Dexie transaction can't escape as an unhandled
// rejection or silently freeze the stats.
- void onEvent(event);
+ void onEvent(event, relay);
},
closeOnEose: false,
});