@toon-protocol/relay 2.0.0 → 2.0.2

package/dist/index.d.ts

@@ -15,7 +15,17 @@ interface RelayServerConfig {
     port: number;
     /** Host/IP to bind to (default: '0.0.0.0'). Set to '127.0.0.1' for hidden service mode. */
     host?: string;
-    /** Maximum concurrent connections (default: 100) */
+    /**
+     * Maximum concurrent WebSocket connections (default: 4096; relay#90).
+     *
+     * Each connection costs one file descriptor plus a few KB of handler
+     * state, so the practical ceiling is fd-limit-shaped, not memory-shaped.
+     * 4096 supports several hundred-listener huddles at once (the stock 100
+     * made >100 listeners impossible) while leaving comfortable headroom
+     * under docker's default nofile limit (1048576) AND still fitting under a
+     * conservative 8192 ulimit; on a classic 1024 soft limit the startup
+     * fd-limit check logs a warning (see NostrRelayServer.start).
+     */
     maxConnections?: number;
     /** Maximum subscriptions per connection (default: 20) */
     maxSubscriptionsPerConnection?: number;
@@ -71,6 +81,7 @@ declare class RelayError extends Error {
 declare class SqliteEventStore implements EventStore {
     private db;
     private insertStmt;
+    private insertOrIgnoreStmt;
     private getStmt;
     private deleteByPubkeyKindStmt;
     private deleteByPubkeyKindDTagStmt;
@@ -129,6 +140,139 @@ declare class SqliteEventStore implements EventStore {
  */
 declare function matchFilter(event: NostrEvent, filter: Filter): boolean;
 
+/**
+ * Event-signature verification for the paid-write hot path (relay#85).
+ *
+ * nostr-tools' `verifyEvent` runs BIP-340 schnorr verification in pure-JS
+ * noble at ~1.3ms per event -- synchronously, on the relay's single Node
+ * event loop. Post-#84 that verify IS the write-path ceiling: the devnet
+ * relay caps at ~240-260 events/s aggregate, CPU-bound (connector#685
+ * Phase G measurements).
+ *
+ * This module verifies with libsecp256k1 compiled to WASM (`tiny-secp256k1`,
+ * ~0.20ms per event on the same workload -- ~7x faster) and keeps noble as a
+ * fallback: if the WASM module fails to load or fails a startup self-test on
+ * a known-good/known-bad vector pair, verification transparently degrades to
+ * `verifyEvent` from nostr-tools. The relay never hard-fails because of the
+ * fast path. WASM was chosen over a native addon deliberately: it needs no
+ * platform toolchain in the Docker build, and the `secp256k1` native-addon
+ * package exposes no schnorr API at all.
+ *
+ * Semantics match nostr-tools `verifyEvent` -- serialize per NIP-01, SHA-256,
+ * compare against `event.id`, then BIP-340-verify `event.sig` -- with one
+ * deliberate improvement: a structurally invalid event returns `false` here
+ * (nostr-tools' `getEventHash` throws instead). `verifyEventSignature` never
+ * throws.
+ *
+ * @module
+ */
+
+/**
+ * Which verify implementation is active. Surfaced so the launcher can log it
+ * once at startup (the noble fallback is a silent ~7x throughput loss
+ * otherwise).
+ */
+declare const verifyImplementation: 'libsecp256k1-wasm' | 'noble-pure-js';
+/**
+ * Verify ONLY that `event.id` is the correct NIP-01 SHA-256 hash of the
+ * event's serialized form. Does NOT check the schnorr signature and does NOT
+ * stamp nostr-tools' `verifiedSymbol` cache (an id check is not a signature
+ * verdict).
+ *
+ * This is the integrity floor for the paid-ephemeral skip-verify path
+ * (relay#85): when the relay skips schnorr for payment-gated ephemeral kinds,
+ * it still refuses events whose id does not match their content, so a paid
+ * writer cannot make the relay broadcast a frame whose bytes disagree with
+ * the id that clients index/verify by.
+ *
+ * Never throws; structurally invalid events return false.
+ *
+ * @param event - The event whose id to check.
+ * @returns True iff `event.id` equals the NIP-01 SHA-256 of the event.
+ */
+declare function verifyEventId(event: NostrEvent): boolean;
+/**
+ * Verify a Nostr event's id and BIP-340 signature.
+ *
+ * Drop-in replacement for nostr-tools' `verifyEvent` on the write hot path:
+ * same accept/reject semantics for well-formed events, ~7x faster via WASM
+ * libsecp256k1 when available, noble pure-JS otherwise. Never throws;
+ * structurally invalid events return false.
+ *
+ * @param event - The event to verify.
+ * @returns True iff the id matches the NIP-01 hash and the signature is valid.
+ */
+declare function verifyEventSignature(event: NostrEvent): boolean;
+
+/**
+ * Worker-thread pool for event-signature verification (relay#85).
+ *
+ * Post-#87 the WASM verify takes ~0.2ms per event -- but it still runs ON the
+ * single Node event loop, which also carries every WebSocket broadcast.
+ * Agent writers make persistent-kind write rates potentially bursty and high;
+ * a verify burst on the loop is exactly the kind of stall that shows up as
+ * tail jitter on ephemeral (huddle-frame) latency. The pool moves persistent
+ * -kind schnorr verification onto worker threads so verify bursts cannot
+ * stall the loop, at the cost of one thread-hop per verified event.
+ *
+ * Shape:
+ * - `size` workers (default `max(0, os.cpus().length - 1)`); each worker
+ *   imports `verify-event.ts` and therefore instantiates its OWN WASM
+ *   libsecp256k1 (same self-test + noble fallback semantics as inline).
+ * - `size: 0` -- automatic on 1-core boxes, and the explicit config escape
+ *   hatch (TOON_VERIFY_WORKERS=0) -- keeps the current inline path: `verify`
+ *   resolves synchronously-computed results, no threads are created.
+ * - Dispatch is least-busy; per-call results resolve independently.
+ *   ORDERING: results for CONCURRENT calls may settle out of submission
+ *   order. The write path stays correct because the upstream connector
+ *   serializes each BTP session's POSTs (next request only after the
+ *   previous response) -- pinned by tests in write-handler.test.ts.
+ * - Worker failure degrades transparently: pending and future verifies fall
+ *   back to the inline implementation (the pool never hard-fails a write).
+ * - Hand-rolled on `node:worker_threads` -- ~100 lines beats a piscina
+ *   dependency in a package whose runtime deps are deliberately minimal.
+ *
+ * @module
+ */
+
+/** A pool that verifies event signatures off the main event loop. */
+interface VerifyPool {
+    /**
+     * Verify an event's id + BIP-340 signature. Never rejects; invalid or
+     * structurally broken events resolve `false`. Semantics match
+     * `verifyEventSignature`, including stamping the nostr-tools
+     * verified-event cache symbol on the caller's object.
+     */
+    verify(event: NostrEvent): Promise<boolean>;
+    /** Live worker count (0 = inline path). */
+    readonly size: number;
+    /** Terminate all workers. Idempotent. Pending verifies resolve inline. */
+    destroy(): Promise<void>;
+}
+/**
+ * Default pool size: one worker per CPU minus one core reserved for the
+ * event loop (WS fan-out + HTTP). On a 1-core box this is 0 -- the inline
+ * path -- because a worker would only add thread-hop overhead while
+ * competing for the same core.
+ */
+declare function defaultVerifyWorkers(): number;
+/** Options for {@link createVerifyPool}. */
+interface VerifyPoolOptions {
+    /** Worker count (default {@link defaultVerifyWorkers}; 0 = inline). */
+    size?: number;
+    /**
+     * Called with the wall-clock milliseconds of each verify -- including
+     * pool queue + thread-hop time, i.e. the latency a write actually paid.
+     * The launcher wires this into the /metrics registry.
+     */
+    onMeasure?: (ms: number) => void;
+}
+/**
+ * Create a verify pool. See the module doc for semantics; see
+ * {@link VerifyPoolOptions} for knobs.
+ */
+declare function createVerifyPool(options?: VerifyPoolOptions): VerifyPool;
+
 /**
  * Represents an active subscription from a client.
  */
@@ -138,6 +282,21 @@ interface Subscription {
     /** Filters applied to this subscription */
     filters: Filter[];
 }
+/**
+ * Build a NIP-01 EVENT frame from an ALREADY-SERIALIZED event payload,
+ * splicing in the (JSON-escaped) subscription id.
+ *
+ * Byte-identical to `JSON.stringify(['EVENT', subscriptionId, event])` --
+ * pinned by tests -- but lets the broadcast fan-out serialize the event
+ * ONCE and reuse the string across every matching subscriber (relay#91:
+ * 500 subscribers previously meant 500 identical `JSON.stringify(event)`
+ * calls per frame, measured pinning a core in the s500 benchmark run).
+ *
+ * @param subscriptionId - The per-subscriber NIP-01 subscription id.
+ * @param eventJson - `JSON.stringify(event)` output to reuse.
+ * @returns The full EVENT frame string for the wire.
+ */
+declare function serializeEventFrame(subscriptionId: string, eventJson: string): string;
 /**
  * Handles NIP-01 messages for a single WebSocket connection.
  */
@@ -170,8 +329,15 @@ declare class ConnectionHandler {
     /**
      * Push a new event to all matching subscriptions on this connection.
      * Used when events are stored outside the WebSocket flow (e.g., via ILP).
+     *
+     * @param event - The event to fan out (used for filter matching).
+     * @param eventJson - Optional pre-serialized `JSON.stringify(event)`.
+     *   `NostrRelayServer.broadcastEvent` serializes the event ONCE and passes
+     *   it here so a 500-subscriber fan-out costs one serialization, not 500
+     *   (relay#91). When omitted (direct callers), the event is serialized
+     *   on first matching send.
      */
-    notifyNewEvent(event: NostrEvent): void;
+    notifyNewEvent(event: NostrEvent, eventJson?: string): void;
     /**
      * Clean up all subscriptions for this connection.
      */
@@ -180,13 +346,32 @@ declare class ConnectionHandler {
      * Get the number of active subscriptions.
      */
     getSubscriptionCount(): number;
+    /**
+     * Emit an outbound NIP-01 EVENT frame.
+     *
+     * The event MUST go on the wire as canonical NIP-01 JSON —
+     * `["EVENT", <subId>, {id, pubkey, created_at, kind, tags, content, sig}]`
+     * with the event as a plain JSON object — so any standard nostr client can
+     * parse it and verify `id`/`sig` from the wire bytes (#46). Never re-encode
+     * the event (TOON text, double-JSON-stringify, etc.) at this boundary.
+     * serializeEventFrame is byte-identical to the full JSON.stringify
+     * envelope (pinned by tests).
+     */
     private sendEvent;
     private sendEose;
     private sendOk;
     private sendNotice;
+    /** Send a message: pre-serialized frames go out as-is (relay#91). */
     private send;
 }
 
+/**
+ * Read this process's soft "Max open files" limit from /proc/self/limits.
+ * Returns null off-Linux or on any parse failure (the check is advisory).
+ *
+ * @internal Exported for unit testing.
+ */
+declare function readOpenFilesSoftLimit(read?: (path: string) => string): number | null;
 /**
  * A NIP-01 compliant Nostr relay WebSocket server.
  * Handles client connections and routes messages to ConnectionHandlers.
@@ -218,6 +403,12 @@ declare class NostrRelayServer {
      * Broadcast an event to all connected clients with matching subscriptions.
      * Call this after storing an event outside the WebSocket flow (e.g., via ILP)
      * so that discovery subscribers are notified.
+     *
+     * Serialize-once fan-out (relay#91): the event payload is stringified ONE
+     * time here and reused for every matching subscriber -- only the small
+     * per-subscription `["EVENT",<subId>,...]` envelope is spliced per send.
+     * Previously each of N subscribers re-serialized the identical event
+     * (N=500 pinned a core doing 500 identical stringifies per frame).
      */
     broadcastEvent(event: NostrEvent): void;
     private handleConnection;
@@ -226,11 +417,17 @@ declare class NostrRelayServer {
 /**
  * TOON event codec.
  *
- * Encodes/decodes Nostr events to and from the TOON wire format used on this
- * relay's NIP-01 read surface. Vendored from `@toon-protocol/core` so the relay
- * depends only on the lightweight `@toon-format/toon` encoder rather than core's
- * full transitive tree (which pulls Arweave / web3 wallet stacks the relay does
- * not use). Same MIT license / org.
+ * Encodes/decodes Nostr events to and from the TOON text format. Vendored from
+ * `@toon-protocol/core` so the relay depends only on the lightweight
+ * `@toon-format/toon` encoder rather than core's full transitive tree (which
+ * pulls Arweave / web3 wallet stacks the relay does not use). Same MIT
+ * license / org.
+ *
+ * NOTE: this codec is NOT used on the relay's NIP-01 read surface. Outbound
+ * EVENT frames are canonical NIP-01 JSON (see
+ * `websocket/ConnectionHandler.sendEvent`, #46) so that standard nostr clients
+ * can parse events and verify signatures from the wire. The codec remains
+ * exported for library consumers that exchange TOON-text events elsewhere.
  *
  * @module
  */
@@ -310,7 +507,9 @@ declare class RelaySubscriber {
  *   - `POST /write` (TOON_BLS_PORT, default 3100): accepts `{ event }` as JSON,
  *     trusts the injected `X-TOON-Payer`/`-Amount`/`-Chain` headers WITHOUT
  *     re-validating payment, verifies only the event's own signature for
- *     integrity, and stores it. `GET /health` lives on the same port.
+ *     integrity (paid ephemeral kinds skip schnorr by default and keep the
+ *     id check -- relay#85, see `verifyEphemeral`), and stores it.
+ *     `GET /health` and `GET /metrics` live on the same port.
  *   - Free NIP-01 WebSocket reads (TOON_RELAY_PORT, default 7100).
  *
  * `startRelay()` returns a `RelayInstance` with an explicit `.stop()` for
@@ -339,6 +538,25 @@ interface RelayConfig {
      * port to localhost only (e.g. when an upstream proxy handles inbound).
      */
     host?: string;
+    /**
+     * Bind host for the HTTP write/health listener (default: 0.0.0.0).
+     *
+     * The write port MUST only be reachable via the payment-gating connector
+     * (see `verifyEphemeral`): in the canonical compose deploy that is enforced
+     * by NOT host-publishing the port (docker `expose:`, never `ports:` --
+     * note that docker `ports:` publishes bypass ufw). When the relay runs
+     * directly on a host, bind this to a loopback/internal address instead.
+     * A non-internal bind while the ephemeral verify skip is active logs a
+     * prominent startup warning (never a hard failure -- topologies vary).
+     */
+    writeHost?: string;
+    /**
+     * Maximum concurrent WebSocket read connections (default: 4096; env:
+     * TOON_MAX_CONNECTIONS). Connections beyond the cap are closed with 1013.
+     * Fd-limit-shaped, not memory-shaped -- see RelayServerConfig
+     * .maxConnections for the sizing reasoning (relay#90).
+     */
+    maxConnections?: number;
     /** Data directory for the file-backed SQLite store (default: ./data). */
     dataDir?: string;
     /**
@@ -350,6 +568,33 @@ interface RelayConfig {
     eventStore?: EventStore;
     /** Skip event-signature verification on `POST /write` (default: false). */
     devMode?: boolean;
+    /**
+     * Run FULL schnorr verification on ephemeral kinds (default: false -- the
+     * paid-ephemeral verify skip is ON by default, relay#85).
+     *
+     * The default skip is safe ONLY because `POST /write` is payment-gated by
+     * the upstream connector and clients verify every signature themselves;
+     * the SHA-256 event-id check always runs. Community operators fronting the
+     * write port with anything other than a payment-gating connector should
+     * set this to true (env: TOON_VERIFY_EPHEMERAL=true). See
+     * `WriteHandlerConfig.verifyEphemeral` for the full invariant.
+     */
+    verifyEphemeral?: boolean;
+    /**
+     * Worker-thread verify pool size for persistent-kind signature
+     * verification (default: `max(0, os.cpus().length - 1)`; env:
+     * TOON_VERIFY_WORKERS). `0` -- automatic on 1-core boxes -- is the inline
+     * escape hatch: verification runs synchronously on the event loop as
+     * before. Workers keep bursty agent-writer verify load from stalling the
+     * loop and jittering ephemeral frame latency (relay#85).
+     */
+    verifyWorkers?: number;
+    /**
+     * Log one line per accepted `POST /write` (default: false). Per-event
+     * console I/O is measurable tail jitter on the write hot path (relay#85),
+     * so this is a debug switch, not an access log.
+     */
+    logWrites?: boolean;
 }
 /**
  * Resolved configuration with all defaults applied.
@@ -358,8 +603,13 @@ interface ResolvedRelayConfig {
     relayPort: number;
     blsPort: number;
     host: string;
+    writeHost: string;
+    maxConnections: number;
     dataDir: string;
     devMode: boolean;
+    verifyEphemeral: boolean;
+    verifyWorkers: number;
+    logWrites: boolean;
 }
 /**
  * A running TOON relay node instance returned by `startRelay()`.
@@ -396,6 +646,34 @@ interface RelaySubscription {
     /** Whether this subscription is still active. */
     isActive(): boolean;
 }
+/**
+ * Whether `host` is a bind address that cannot be reached from the public
+ * internet directly: loopback, RFC1918 private, IPv6 unique-local/link-local.
+ * `0.0.0.0` / `::` (all interfaces) and public addresses return false.
+ *
+ * Used by the startup exposure guard: with the paid-ephemeral verify skip
+ * active, the write port must only be reachable via the payment-gating
+ * connector. Note a "false" here is not proof of exposure -- inside a
+ * container, 0.0.0.0 is required for the connector to dial the compose
+ * network and the port is kept private by not host-publishing it -- which is
+ * why the guard warns instead of failing.
+ *
+ * @internal Exported for unit testing.
+ */
+declare function isInternalBindHost(host: string): boolean;
+/**
+ * Log the prominent write-port exposure warning when the paid-ephemeral
+ * verify skip is active and the write listener binds a non-internal
+ * interface. Deliberately a warning, not a hard failure: in the canonical
+ * compose deploy the port binds 0.0.0.0 inside the container and is private
+ * because it is never host-published (docker `expose:`, not `ports:`).
+ *
+ * @internal Exported for unit testing.
+ */
+declare function warnIfWritePortExposed(writeHost: string, blsPort: number, options: {
+    verifyEphemeral: boolean;
+    devMode: boolean;
+}): boolean;
 /**
  * Start a TOON relay node with the given configuration.
  *
@@ -449,6 +727,87 @@ interface HealthResponse {
  */
 declare function createHealthResponse(config: HealthConfig): HealthResponse;
 
+/**
+ * Metrics for the relay's HTTP telemetry surface (relay#85).
+ *
+ * Served as JSON from `GET /metrics` on the write/health port, next to
+ * `/health`. Two families, chosen because they are the TRIGGER METRICS for
+ * future scaling decisions (2026-08-02 benchmarking, toon-meta
+ * proto/spacetimedb-relay RESULTS.md):
+ *
+ * - **Event-loop delay**: the single Node loop carries every WS broadcast;
+ *   loop lag IS ephemeral (huddle-frame) tail latency. Sustained p99 growth
+ *   here is the signal to shed load or scale out.
+ * - **Per-event verify time**: wall-clock ms per signature verification as
+ *   the write actually paid it (including verify-pool queue + thread-hop
+ *   when workers are enabled). Growth here is the signal to resize the
+ *   verify pool (TOON_VERIFY_WORKERS) or move boxes.
+ *
+ * The registry is deliberately dependency-free: `monitorEventLoopDelay`
+ * from node:perf_hooks plus a fixed-size ring of recent verify durations
+ * (percentiles over the last {@link VERIFY_WINDOW} samples -- bounded
+ * memory, O(window log window) only when a snapshot is requested).
+ *
+ * @module
+ */
+/** Aggregates for one duration family, in milliseconds. */
+interface DurationStats {
+    /** Total samples recorded since startup. */
+    count: number;
+    /** Mean over ALL samples since startup. */
+    meanMs: number;
+    /** Max over ALL samples since startup. */
+    maxMs: number;
+    /** Median over the most recent window (up to {@link VERIFY_WINDOW}). */
+    p50Ms: number;
+    /** 99th percentile over the most recent window. */
+    p99Ms: number;
+}
+/** The `GET /metrics` response shape. */
+interface MetricsSnapshot {
+    timestamp: number;
+    /**
+     * Event-loop delay in ms (node:perf_hooks monitorEventLoopDelay since the
+     * last snapshot reset -- lifetime of the process unless noted). `mean`,
+     * `p50`, `p99`, `max` -- loop lag is ephemeral-frame tail latency.
+     */
+    eventLoopDelayMs: {
+        mean: number;
+        p50: number;
+        p99: number;
+        max: number;
+    };
+    /** Per-event signature-verify timing (trigger metric for pool sizing). */
+    verify: {
+        /** Active implementation: 'libsecp256k1-wasm' or 'noble-pure-js'. */
+        implementation: string;
+        /** Verify-pool worker count (0 = inline on the event loop). */
+        workers: number;
+    } & DurationStats;
+}
+/** Live registry behind `GET /metrics`. */
+interface MetricsRegistry {
+    /** Record one verify duration in milliseconds. */
+    recordVerify(ms: number): void;
+    /** Build the current snapshot (cheap; safe to poll). */
+    snapshot(): MetricsSnapshot;
+    /** Update the reported worker count (pool may degrade at runtime). */
+    setVerifyWorkers(workers: number): void;
+    /** Disable the loop-delay histogram (call on relay stop). */
+    stop(): void;
+}
+/**
+ * Create the metrics registry. One per relay instance; the launcher wires
+ * `recordVerify` into the verify pool's `onMeasure` and serves `snapshot()`
+ * from `GET /metrics`.
+ *
+ * @param info - Static verify metadata surfaced in the snapshot.
+ */
+declare function createMetricsRegistry(info: {
+    verifyImplementation: string;
+    verifyWorkers: number;
+}): MetricsRegistry;
+
 /**
  * Write handler for @toon-protocol/relay.
  *
@@ -465,9 +824,26 @@ declare function createHealthResponse(config: HealthConfig): HealthResponse;
  * Flow:
  * 1. Parse JSON body `{ event }` -> 400 on malformed/missing event
  * 2. Capture trusted X-TOON-Payer / X-TOON-Amount / X-TOON-Chain headers
- * 3. Verify the event signature (skipped in devMode) -> 422 on invalid sig
- * 4. Store the event in the EventStore
- * 5. Fire the optional onStored callback
+ * 3. Verify the event signature (skipped in devMode) -> 422 on invalid sig.
+ *    Verification uses the fast WASM libsecp256k1 path (crypto/verify-event)
+ *    rather than noble pure-JS: post-#84 the synchronous ~1.3ms noble verify
+ *    on the single event loop WAS the write-path ceiling (~240-260 events/s
+ *    aggregate, relay#85 / connector#685 Phase G).
+ *    PAID-EPHEMERAL EXCEPTION (relay#85, decision 2026-08-02): for ephemeral
+ *    kinds (20000 <= kind < 30000) the schnorr verification is SKIPPED by
+ *    default -- only the SHA-256 id check runs -> 422 on id mismatch. See
+ *    the loud comment at the verify step for why this is safe, and
+ *    `verifyEphemeral` to turn full verification back on.
+ * 4. Store the event in the EventStore -- unless its kind is ephemeral
+ *    (NIP-16: 20000 <= kind < 30000), which is delivered live and never
+ *    persisted. Skipping the store here is not only NIP-16 semantics: the
+ *    synchronous per-event disk write was the serialization point that
+ *    capped the whole paid-write pipeline at ~150 events/s globally
+ *    (connector#685), and ephemeral traffic -- audio frames -- is exactly
+ *    the traffic that hits that path hardest.
+ * 5. Fire the optional onStored callback (ephemeral events included: it is
+ *    the live-broadcast hook, and ephemeral events exist only as that
+ *    broadcast)
  * 6. Respond 200 with the event id, storedAt timestamp, and echoed headers
  *
  * @module
@@ -481,8 +857,52 @@ interface WriteHandlerConfig {
     eventStore: EventStore;
     /** Whether dev mode is enabled (skips Schnorr signature verification). */
     devMode: boolean;
+    /**
+     * Run FULL schnorr verification on ephemeral kinds too (default: false --
+     * i.e. the paid-ephemeral verify skip is ON by default).
+     *
+     * ! SECURITY INVARIANT -- READ BEFORE TOUCHING !
+     * The default skip is safe ONLY because this write surface is payment-gated:
+     * every request reaching `POST /write` has already passed the upstream
+     * connector's claim gate (payment IS the admission/spam gate), and the
+     * protocol rule is that clients trust the signature chain and verify every
+     * event themselves -- never the relay. Relay-side schnorr on ephemeral
+     * frames is therefore pure spam defense that payment already provides;
+     * forging a speaker costs real money to emit frames every client discards.
+     * The SHA-256 id check is ALWAYS kept (see handleWrite).
+     *
+     * If you ever add a FREE (non-payment-gated) ephemeral write lane, it MUST
+     * NOT reuse this skip -- free spam with valid-looking ids would be
+     * broadcast to every subscriber. Community operators who front this port
+     * with anything other than a payment-gating connector should set
+     * `verifyEphemeral: true` (TOON_VERIFY_EPHEMERAL=true).
+     */
+    verifyEphemeral?: boolean;
+    /**
+     * Signature verifier for non-skipped (persistent-kind) events. Defaults to
+     * the inline `verifyEventSignature`; the launcher injects the worker-pool
+     * verifier (`crypto/verify-pool.ts`) so verify bursts run off the event
+     * loop (relay#85). May resolve asynchronously -- the handler awaits it.
+     *
+     * ORDERING NOTE: an async verifier means CONCURRENT requests can complete
+     * out of arrival order. Per-session write ordering is enforced UPSTREAM:
+     * the connector serializes each BTP session's POSTs (it does not send the
+     * next request until the previous response arrives), so sequential
+     * same-session writes can never reorder here. Pinned by the ordering test
+     * in write-handler.test.ts -- do not weaken that contract upstream without
+     * revisiting this.
+     */
+    verifyEvent?: (event: NostrEvent) => Promise<boolean> | boolean;
     /** Optional callback fired after an event is successfully stored. */
     onStored?: (event: NostrEvent) => void;
+    /**
+     * Log one line per accepted write (default: false). Off by default because
+     * per-event console I/O on the single event loop is measurable tail jitter
+     * at huddle frame rates (relay#85, connector#685 Phase G): every write's
+     * log line goes through docker's json-file driver, i.e. residual per-event
+     * disk I/O that #84 did not remove.
+     */
+    logWrites?: boolean;
 }
 /**
  * Write handler instance.
@@ -499,4 +919,4 @@ interface WriteHandler {
  */
 declare function createWriteHandler(config: WriteHandlerConfig): WriteHandler;
 
-export { ConnectionHandler, DEFAULT_RELAY_CONFIG, type EventStore, type HealthConfig, type HealthResponse, InMemoryEventStore, NostrRelayServer, type RelayConfig, RelayError, type RelayInstance, type RelayServerConfig, RelaySubscriber, type RelaySubscriberConfig, type RelaySubscription, type ResolvedRelayConfig, SqliteEventStore, type Subscription, ToonDecodeError, ToonEncodeError, VERSION, type WriteHandler, type WriteHandlerConfig, createHealthResponse, createWriteHandler, decodeEventFromToon, encodeEventToToon, matchFilter, startRelay };
+export { ConnectionHandler, DEFAULT_RELAY_CONFIG, type DurationStats, type EventStore, type HealthConfig, type HealthResponse, InMemoryEventStore, type MetricsRegistry, type MetricsSnapshot, NostrRelayServer, type RelayConfig, RelayError, type RelayInstance, type RelayServerConfig, RelaySubscriber, type RelaySubscriberConfig, type RelaySubscription, type ResolvedRelayConfig, SqliteEventStore, type Subscription, ToonDecodeError, ToonEncodeError, VERSION, type VerifyPool, type VerifyPoolOptions, type WriteHandler, type WriteHandlerConfig, createHealthResponse, createMetricsRegistry, createVerifyPool, createWriteHandler, decodeEventFromToon, defaultVerifyWorkers, encodeEventToToon, isInternalBindHost, matchFilter, readOpenFilesSoftLimit, serializeEventFrame, startRelay, verifyEventId, verifyEventSignature, verifyImplementation, warnIfWritePortExposed };