@toon-protocol/relay 2.0.1 → 2.1.0

package/dist/index.d.ts

@@ -4,18 +4,27 @@ import { WebSocket } from 'ws';
 import { SimplePool } from 'nostr-tools/pool';
 import { Context } from 'hono';
 
-/** Package version, surfaced on `GET /health`. */
-declare const VERSION = "0.1.0";
+declare const VERSION: string;
 
 /**
  * Configuration options for the Nostr relay.
  */
 interface RelayServerConfig {
-    /** Port to listen on (default: 7000) */
+    /** Port to listen on (default: 7100) */
     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;
@@ -23,12 +32,42 @@ interface RelayServerConfig {
     maxFiltersPerSubscription?: number;
     /** Path to SQLite database file (default: ':memory:' for in-memory) */
     databasePath?: string;
+    /**
+     * Enforce NIP-40 expiration on the live broadcast path (default: true).
+     *
+     * The stored-history path is enforced by the EventStore; this flag covers
+     * the other way an event reaches a subscriber — the fan-out of a freshly
+     * written event. Both are driven from the same launcher setting so a relay
+     * cannot serve an expired event on one path while hiding it on the other.
+     */
+    enforceExpiration?: boolean;
 }
 /**
  * Default relay configuration values.
  */
 declare const DEFAULT_RELAY_CONFIG: Required<RelayServerConfig>;
 
+/**
+ * Construction options shared by every EventStore implementation.
+ */
+interface EventStoreOptions {
+    /**
+     * Enforce NIP-40 expiration at serve time (default: true).
+     *
+     * When true, events past their `expiration` tag are not returned by
+     * `get()` or `query()`. Set false as a KILL SWITCH: it restores the
+     * pre-NIP-40 behaviour of serving every stored event forever, which is the
+     * only recourse if enforcement ever starves discovery (see the launcher's
+     * `enforceExpiration` docs for the failure mode this guards against).
+     */
+    enforceExpiration?: boolean;
+    /**
+     * Operator-blocked event ids (64-char lowercase hex). Blocked events are
+     * refused on write and swept from storage. See `nips/blocklist.ts` for why
+     * this is scoped to ids and to startup configuration.
+     */
+    blockedEventIds?: Iterable<string>;
+}
 /**
  * Interface for event storage backends.
  */
@@ -39,6 +78,11 @@ interface EventStore {
     get(id: string): NostrEvent | undefined;
     /** Query events matching any of the provided filters */
     query(filters: Filter[]): NostrEvent[];
+    /**
+     * Permanently drop events expired for longer than `graceSeconds` (NIP-40).
+     * Optional: a backend may serve-filter only. Returns rows removed.
+     */
+    reapExpired?(nowSeconds: number, graceSeconds?: number): number;
     /** Close the storage backend (optional) */
     close?(): void;
 }
@@ -48,9 +92,30 @@ interface EventStore {
  */
 declare class InMemoryEventStore implements EventStore {
     private events;
+    /** NIP-09 id tombstones: event id -> the pubkey that requested deletion. */
+    private deletedIds;
+    /** NIP-09 address tombstones: `<kind>:<pubkey>:<d>` -> deletion created_at. */
+    private deletedAddresses;
+    private readonly enforceExpiration;
+    private readonly blockedEventIds;
+    constructor(options?: EventStoreOptions);
     store(event: NostrEvent): void;
     get(id: string): NostrEvent | undefined;
     query(filters: Filter[]): NostrEvent[];
+    /**
+     * Drop events expired for longer than `graceSeconds` (NIP-40).
+     *
+     * @param now - Current unix time in seconds.
+     * @param graceSeconds - Extra time an expired event is kept.
+     * @returns The number of events removed.
+     */
+    reapExpired(now: number, graceSeconds?: number): number;
+    /** The NIP-01 addressable coordinate of an event, `<kind>:<pubkey>:<d>`. */
+    private static coordinateOf;
+    /** Whether a NIP-09 request already retracted this event (same author). */
+    private isRetracted;
+    /** Apply a kind:5 request to the author's OWN events only. */
+    private applyDeletion;
     /**
      * Close the storage backend (no-op for in-memory store).
      */
@@ -71,19 +136,31 @@ declare class RelayError extends Error {
 declare class SqliteEventStore implements EventStore {
     private db;
     private insertStmt;
+    private insertOrIgnoreStmt;
     private getStmt;
     private deleteByPubkeyKindStmt;
     private deleteByPubkeyKindDTagStmt;
     private getByPubkeyKindStmt;
     private getByPubkeyKindDTagStmt;
+    private tombstoneIdStmt;
+    private getTombstoneStmt;
+    private tombstoneAddressStmt;
+    private getAddressTombstoneStmt;
+    private deleteExpiredStmt;
+    private readonly enforceExpiration;
+    private readonly blockedEventIds;
     /**
      * Create a new SqliteEventStore.
      * @param dbPath - Path to the database file. Use ':memory:' for in-memory database.
+     * @param options - Expiry-enforcement and operator-blocklist settings.
      */
-    constructor(dbPath?: string);
+    constructor(dbPath?: string, options?: EventStoreOptions);
     /**
      * Store an event in the database.
-     * Handles replaceable and parameterized replaceable events according to NIP-01.
+     *
+     * Handles replaceable and parameterized replaceable events according to
+     * NIP-01, applies NIP-09 deletion requests, and refuses events the operator
+     * has blocked or that a previous NIP-09 request already retracted.
      */
     store(event: NostrEvent): void;
     /**
@@ -96,8 +173,64 @@ declare class SqliteEventStore implements EventStore {
      * Only keeps the latest event per pubkey+kind+d-tag.
      */
     private storeParameterizedReplaceableEvent;
+    /**
+     * Bind an event to one of the prepared INSERT statements.
+     *
+     * The `expires_at` column is derived here, at the single point every write
+     * funnels through, so no insert path can forget it.
+     */
+    private runInsert;
+    /**
+     * The NIP-01 addressable coordinate of an event, `<kind>:<pubkey>:<d>`.
+     * The `d` value is the empty string for events that carry no `d` tag —
+     * which is every kind:10032 announce on the network today.
+     */
+    private static coordinateOf;
+    /**
+     * Whether a NIP-09 deletion request already retracted this event, so it
+     * must not be re-admitted.
+     *
+     * The id tombstone only bites when the arriving event's OWN pubkey matches
+     * the pubkey that asked for the deletion; otherwise anyone could pre-block
+     * an id they merely predicted. Address tombstones already carry the
+     * author's pubkey inside the coordinate.
+     */
+    private isRetracted;
+    /**
+     * Apply a NIP-09 deletion request: remove the author's own targeted events
+     * and record tombstones so a re-publish cannot resurrect them.
+     *
+     * Every statement here is scoped by `pubkey = <the requester>`, which is
+     * what makes a cross-author deletion a no-op rather than a privilege.
+     */
+    private applyDeletion;
+    /**
+     * Rows for a (kind, pubkey) pair with their parsed tags, so the caller can
+     * compare `d` values in code. SQL cannot distinguish `["d",""]` from a
+     * missing `d` tag, and both mean "the empty identifier".
+     */
+    private findByCoordinate;
+    /**
+     * NIP-40 reaper: permanently delete events whose expiration is further than
+     * `graceSeconds` in the past.
+     *
+     * The grace window is the safety net for enforcement itself. Serve-time
+     * filtering is instantly reversible (flip `enforceExpiration` off and every
+     * still-present event is served again); a DELETE is not. Keeping recently
+     * expired events on disk for a while means an operator who discovers that
+     * enforcement broke discovery can undo it without having lost the data.
+     *
+     * @param nowSeconds - Current unix time in seconds.
+     * @param graceSeconds - Extra time to keep an expired event on disk.
+     * @returns The number of rows deleted.
+     */
+    reapExpired(nowSeconds: number, graceSeconds?: number): number;
     /**
      * Retrieve an event by its ID.
+     *
+     * Returns undefined for an event that is past its NIP-40 expiration while
+     * enforcement is on, even though the row may still be on disk inside the
+     * reaper's grace window.
      */
     get(id: string): NostrEvent | undefined;
     /**
@@ -129,6 +262,323 @@ declare class SqliteEventStore implements EventStore {
  */
 declare function matchFilter(event: NostrEvent, filter: Filter): boolean;
 
+/**
+ * NIP-40 — "Expiration Timestamp".
+ *
+ * An event MAY carry `["expiration", "<unix seconds>"]`. Past that timestamp
+ * the relay SHOULD stop serving it. Until relay#137 this relay parsed no such
+ * tag and enforced nothing, so an announce that said "I am valid for ten
+ * minutes" was still handed to every discovering client a week later (two
+ * such kind:10032 announces — one of them a `g.toon.relay` from an identity
+ * that no longer exists — were live on devnet when this was written).
+ *
+ * This module is deliberately pure: parsing and the expiry predicate only.
+ * WHERE enforcement happens (serve-time filtering, the background reaper) is
+ * the storage layer's and launcher's business.
+ *
+ * @module
+ */
+
+/** The NIP-40 tag name. */
+declare const EXPIRATION_TAG = "expiration";
+/**
+ * Read an event's NIP-40 expiration timestamp, in unix seconds.
+ *
+ * FAIL-OPEN on anything malformed. A tag whose value is not a non-negative
+ * integer (empty, `"soon"`, `"1.5"`, `"-1"`, absent) yields `undefined`, i.e.
+ * "never expires" — the same treatment an event with no tag at all gets.
+ * Dropping an event because its own author wrote a bad timestamp would turn a
+ * publisher-side typo into an unrecoverable read outage, and NIP-40 asks
+ * relays to honour a valid expiration, not to police an invalid one.
+ *
+ * The FIRST syntactically valid expiration tag wins when several are present
+ * (NIP-40 does not define multi-tag behaviour; the event is signed by the
+ * author about the author's own event, so there is no adversary to defend
+ * against here — only a need to be deterministic).
+ *
+ * @param event - Any Nostr event (only `tags` is read).
+ * @returns Unix-seconds expiry, or undefined when the event never expires.
+ */
+declare function getExpiration(event: {
+    tags: string[][];
+}): number | undefined;
+/**
+ * Whether an event is past its NIP-40 expiration at `nowSeconds`.
+ *
+ * Events with no (or a malformed) expiration are never expired.
+ *
+ * @param event - The event to test.
+ * @param nowSeconds - Current unix time in seconds.
+ * @returns True when the event must no longer be served.
+ */
+declare function isExpired(event: Pick<NostrEvent, 'tags'>, nowSeconds: number): boolean;
+
+/**
+ * NIP-09 — "Event Deletion Request".
+ *
+ * A kind:5 event asks the relay to stop serving events the SAME pubkey
+ * published, named either by id (`e` tags) or by addressable coordinate
+ * (`a` tags, `<kind>:<pubkey>:<d-identifier>`).
+ *
+ * THE AUTHORIZATION RULE IS THE WHOLE NIP: a deletion request may only ever
+ * retract events signed by its own author. A kind:5 that names someone else's
+ * event id is not an error and not a partial success — the named target is
+ * simply not deleted. Anything looser turns a public relay into a surface
+ * where one key can erase another's history.
+ *
+ * This module is pure: it parses targets and answers "may this deletion
+ * request retract this event?". Applying that answer to stored rows (and
+ * remembering it, so a re-publish cannot resurrect the event) belongs to the
+ * storage layer.
+ *
+ * @module
+ */
+
+/** The NIP-09 deletion-request kind. */
+declare const DELETION_KIND = 5;
+/** Whether `kind` is a NIP-09 deletion request. */
+declare function isDeletionKind(kind: number): boolean;
+/**
+ * A NIP-01 addressable coordinate, `<kind>:<pubkey>:<d-identifier>`, as
+ * carried by a NIP-09 `a` tag.
+ */
+interface AddressCoordinate {
+    /** Event kind the coordinate addresses. */
+    kind: number;
+    /** Author pubkey (64-char lowercase hex). */
+    pubkey: string;
+    /** The `d` tag value; the empty string when the kind carries no `d`. */
+    identifier: string;
+}
+/** Targets named by a deletion request. */
+interface DeletionTargets {
+    /** Event ids from `e` tags (64-char lowercase hex, de-duplicated). */
+    ids: string[];
+    /** Coordinates from `a` tags (de-duplicated by their raw tag value). */
+    addresses: AddressCoordinate[];
+}
+/**
+ * Parse an `a`-tag value into a coordinate.
+ *
+ * @param value - Raw tag value, `<kind>:<pubkey>:<d-identifier>`.
+ * @returns The coordinate, or undefined when the value is malformed.
+ */
+declare function parseAddressCoordinate(value: string): AddressCoordinate | undefined;
+/**
+ * Collect the targets a deletion request names.
+ *
+ * Malformed tags are skipped rather than failing the whole request: a client
+ * that emits one bad `a` tag alongside three good ones still gets the three.
+ *
+ * @param event - A kind:5 event (the kind is not re-checked here).
+ * @returns De-duplicated ids and coordinates.
+ */
+declare function parseDeletionTargets(event: Pick<NostrEvent, 'tags'>): DeletionTargets;
+/**
+ * Whether `deletion` is allowed to retract `target`.
+ *
+ * Two conditions, both required:
+ *
+ *  1. Same author. This is the trust boundary — see the module comment.
+ *  2. `target.created_at <= deletion.created_at`. A deletion request cannot
+ *     pre-emptively retract a future event; without this, one kind:5 would
+ *     permanently silence every later event a key publishes.
+ *
+ * @param target - The stored event being considered for retraction.
+ * @param deletion - The kind:5 deletion request.
+ * @returns True when the retraction is authorized.
+ */
+declare function isDeletableBy(target: Pick<NostrEvent, 'pubkey' | 'created_at'>, deletion: Pick<NostrEvent, 'pubkey' | 'created_at'>): boolean;
+
+/**
+ * Operator event blocklist — the escape hatch for litter that NEITHER NIP
+ * can clear.
+ *
+ * WHY THIS EXISTS. NIP-01 replacement needs the author's key. NIP-09 deletion
+ * needs the author's key. When a node publishes an announce and then the key
+ * is lost — a throwaway proof rig wiped off an operator workstation, say —
+ * the announce is unretractable BY CONSTRUCTION, and if it also carries no
+ * NIP-40 `expiration` tag then nothing in the protocol will ever remove it.
+ * That is exactly the state devnet was in: a kind:5094-era swap maker
+ * advertising `g.toon.swap.sol` at `ws://127.0.0.1:3401` — a loopback address
+ * that resolves to whatever machine READS it — with no expiry and no key.
+ *
+ * WHY IT IS SHAPED LIKE THIS. Any mechanism that lets an operator remove
+ * other people's events is a censorship surface, so the scope is drawn as
+ * narrowly as the job allows:
+ *
+ *   - **Event ids only, never pubkeys.** Blocking a pubkey silences an
+ *     identity's entire past and future output with one line of config.
+ *     Blocking a 64-hex id removes exactly one event that the operator had to
+ *     name explicitly, having already seen it. A key that is still alive can
+ *     simply publish again, so this cannot be used to suppress a live
+ *     participant — only to sweep a specific dead artifact.
+ *   - **Config at startup, not an API.** There is no admin endpoint, no
+ *     authenticated mutation, nothing network-reachable. The list arrives as
+ *     process configuration (`TOON_BLOCKED_EVENT_IDS`) and changing it means
+ *     restarting the process with a changed deployment — an act that lands in
+ *     a git history and a deploy log rather than in an unlogged HTTP call.
+ *   - **Loud.** The launcher prints every blocked id at startup. A relay that
+ *     is withholding events should say so on every boot.
+ *
+ * A blocked id is refused on write, filtered on read, and swept from the
+ * database — but the block still lives only in ONE relay's configuration.
+ * Other relays serving the same event are unaffected, which is the correct
+ * outcome: this is an operator declining to carry a specific artifact, not a
+ * protocol-level retraction.
+ *
+ * @module
+ */
+/**
+ * Parse an operator blocklist from its configuration string.
+ *
+ * Accepts a comma- and/or whitespace-separated list of 64-char hex event ids.
+ * Case is normalized to lowercase. Entries that are not well-formed event ids
+ * are reported separately rather than silently dropped: a typo in a blocklist
+ * must be visible, because its failure mode (an event the operator believes
+ * is blocked but is still being served) is silent otherwise.
+ *
+ * @param raw - Raw configuration value, or undefined.
+ * @returns The accepted ids and any rejected entries.
+ */
+declare function parseBlockedEventIds(raw: string | undefined): {
+    ids: string[];
+    invalid: string[];
+};
+
+/**
+ * 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 +588,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 +635,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.
      */
@@ -188,14 +660,24 @@ declare class ConnectionHandler {
      * 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.
@@ -227,44 +709,17 @@ 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;
 }
 
-/**
- * TOON event codec.
- *
- * 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
- */
-
-/** Thrown when a Nostr event cannot be encoded to TOON. */
-declare class ToonEncodeError extends Error {
-    readonly code = "TOON_ENCODE_ERROR";
-    constructor(message: string, cause?: Error);
-}
-/** Thrown when TOON data cannot be decoded into a valid Nostr event. */
-declare class ToonDecodeError extends Error {
-    readonly code = "TOON_DECODE_ERROR";
-    constructor(message: string, cause?: Error);
-}
-/** Encode a Nostr event to TOON bytes (UTF-8). */
-declare function encodeEventToToon(event: NostrEvent): Uint8Array;
-/** Decode TOON bytes into a validated Nostr event. */
-declare function decodeEventFromToon(data: Uint8Array): NostrEvent;
-
 /**
  * Subscribe to upstream relays and propagate events into the local EventStore.
  *
@@ -320,12 +775,23 @@ declare class RelaySubscriber {
  * time a write reaches this process it is already proven paid, so the relay
  * simply stores the event and serves reads.
  *
- * Two surfaces:
+ * Three surfaces:
  *
- *   - `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.
+ *   - `POST /write` (TOON_BLS_PORT, default 3100): accepts `{ event }` as JSON.
+ *     By the time a request reaches this surface it is already proven paid;
+ *     the terminating connector asserts nothing about that payment to this
+ *     relay -- no payer, amount, or chain (`toon-protocol/connector` ADR
+ *     0036) -- so the handler verifies only the event's own signature for
+ *     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.
+ *   - `POST /write-ephemeral` (same port, relay#129): the FREE ephemeral
+ *     write lane. Accepts only ephemeral kinds (NIP-16, 20000 <= kind <
+ *     30000), always runs FULL schnorr verification (no skip -- this lane
+ *     has no payment gate), and never stores. Bounded by a per-key rate
+ *     limit and a body-size cap (see `ephemeralRateLimit` /
+ *     `ephemeralMaxBodyBytes`). Terminated at the connector by its own
+ *     zero-priced route (`deploy/connector.toml`'s `g.toon.relay.ephemeral`).
  *   - Free NIP-01 WebSocket reads (TOON_RELAY_PORT, default 7100).
  *
  * `startRelay()` returns a `RelayInstance` with an explicit `.stop()` for
@@ -354,6 +820,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;
     /**
@@ -363,8 +848,99 @@ interface RelayConfig {
      * caller owns its lifecycle when supplied.
      */
     eventStore?: EventStore;
+    /**
+     * Enforce NIP-40 expiration (default: true; env: TOON_ENFORCE_EXPIRATION).
+     *
+     * When true, an event past its `expiration` tag is not served from history
+     * and not fanned out live. Setting this false is the KILL SWITCH back to
+     * the pre-relay#137 behaviour of serving everything forever.
+     *
+     * ! READ THIS BEFORE ASSUMING THE DEFAULT IS FREE !
+     * On the TOON devnet the only events carrying an `expiration` tag are
+     * kind:10032 node announces, published with a 600s TTL and refreshed by a
+     * shell loop every 240s — 2.5 refresh periods of margin, and the loop's
+     * failure backoff (5s doubling, capped at 240s) needs SEVEN consecutive
+     * failed publishes before an announce goes past its expiry. That margin is
+     * comfortable, but it is a margin, not a guarantee: the store and swap
+     * announce loops PAY for each republish out of a payment channel, so a
+     * drained channel makes every republish fail indefinitely. Before this
+     * flag existed, that failure degraded to "a stale announce is still
+     * served"; with enforcement on, it becomes "the node vanishes from
+     * discovery". That is the intended semantics — a node that cannot afford
+     * to say it is alive should not be advertised — but it is a real change in
+     * blast radius, and this flag is how an operator buys time.
+     */
+    enforceExpiration?: boolean;
+    /**
+     * How long an expired event is kept on disk before the reaper deletes it
+     * (default: 86400 = 24h; env: TOON_EXPIRATION_REAP_GRACE_SECONDS).
+     *
+     * Serve-time filtering is reversible; a DELETE is not. The grace window is
+     * what makes flipping `enforceExpiration` back off an actual recovery
+     * rather than an apology. Set 0 to reap the moment an event expires.
+     */
+    expirationReapGraceSeconds?: number;
+    /**
+     * How often the reaper sweeps (default: 3600 = hourly; env:
+     * TOON_EXPIRATION_REAP_INTERVAL_SECONDS). 0 disables reaping entirely;
+     * serve-time filtering is unaffected.
+     */
+    expirationReapIntervalSeconds?: number;
+    /**
+     * Operator-blocked event ids (env: TOON_BLOCKED_EVENT_IDS, comma-separated).
+     *
+     * The narrow escape hatch for an event that neither NIP-01 replacement nor
+     * NIP-09 deletion can reach because its author's key is gone. Ids only,
+     * never pubkeys; startup configuration only, never an API. See
+     * `nips/blocklist.ts` for the full reasoning and the censorship hazard it
+     * is drawn around.
+     */
+    blockedEventIds?: string[];
     /** 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;
+    /**
+     * Per-key sliding-window rate limit for `POST /write-ephemeral` (default:
+     * 200 requests / 10s; env: TOON_EPHEMERAL_RATE_LIMIT /
+     * TOON_EPHEMERAL_RATE_WINDOW_MS). This lane has no payment gate, so this
+     * bound (plus `ephemeralMaxBodyBytes`) IS its admission control -- see
+     * `EphemeralWriteHandlerConfig` for the full reasoning.
+     */
+    ephemeralRateLimit?: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    /**
+     * Request-body size cap in bytes for `POST /write-ephemeral` (default:
+     * 8192; env: TOON_EPHEMERAL_MAX_BODY_BYTES).
+     */
+    ephemeralMaxBodyBytes?: 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.
@@ -373,8 +949,22 @@ interface ResolvedRelayConfig {
     relayPort: number;
     blsPort: number;
     host: string;
+    writeHost: string;
+    maxConnections: number;
     dataDir: string;
     devMode: boolean;
+    verifyEphemeral: boolean;
+    verifyWorkers: number;
+    ephemeralRateLimit: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    ephemeralMaxBodyBytes: number;
+    logWrites: boolean;
+    enforceExpiration: boolean;
+    expirationReapGraceSeconds: number;
+    expirationReapIntervalSeconds: number;
+    blockedEventIds: string[];
 }
 /**
  * A running TOON relay node instance returned by `startRelay()`.
@@ -411,6 +1001,40 @@ 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:`).
+ *
+ * `POST /write-ephemeral` (relay#129) shares this same port/host but needs
+ * no exposure check of its own: it always runs full verification (no skip
+ * for exposure to weaken) and enforces its own rate limit/size cap
+ * regardless of how a request reaches it. This guard's warning is scoped to
+ * the paid-write skip above, which stays the one exposure risk on this port.
+ *
+ * @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.
  *
@@ -464,26 +1088,151 @@ 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;
+    /**
+     * Free ephemeral write lane (relay#129, `POST /write-ephemeral`). Always
+     * present -- the lane is always mounted -- and static for the process
+     * lifetime: it has no payment gate, so these bounds ARE its admission
+     * control, and the acceptance criteria requires them to be visible here
+     * alongside the startup log line.
+     */
+    ephemeralWriteLane: {
+        enabled: true;
+        rateLimit: {
+            maxRequests: number;
+            windowMs: number;
+        };
+        maxBodyBytes: number;
+    };
+}
+/** 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 + ephemeral-lane bounds surfaced in
+ *   the snapshot (relay#129).
+ */
+declare function createMetricsRegistry(info: {
+    verifyImplementation: string;
+    verifyWorkers: number;
+    ephemeralRateLimit: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    ephemeralMaxBodyBytes: number;
+}): MetricsRegistry;
+
 /**
  * Write handler for @toon-protocol/relay.
  *
- * Exposes a plain-HTTP write surface that accepts an event-as-JSON, trusts
- * (but does NOT validate) injected payment headers, verifies ONLY the event
- * signature for integrity, and stores the event.
+ * Exposes a plain-HTTP write surface that accepts an event-as-JSON, verifies
+ * ONLY the event signature for integrity, and stores the event.
  *
  * This handler is intentionally decoupled from any payment layer: it contains
  * no claim/settlement/ILP logic and imports none of it. Payment validation is
- * the upstream terminator's concern; by the time a request reaches this surface
- * the trusted `X-TOON-*` headers are assumed already proven. The handler
- * captures them purely for the response echo and a log line.
+ * the upstream terminator's concern; by the time a request reaches this
+ * surface it is already proven paid.
+ *
+ * What the terminator DOES state, it records. A terminating connector states
+ * `X-TOON-Payer` / `X-TOON-Amount` / `X-TOON-Chain` on a delivery whose
+ * payment it verified at its own client edge (`toon-protocol/connector`
+ * ADR 0040, relay#133); the handler reads them, echoes a well-formed triple
+ * back on the 200, and treats their absence as "this hop was not the one
+ * paid" -- NEVER as "unpaid". See payment-attribution.ts for the contract and
+ * for why the same header names were right to distrust before ADR 0040.
  *
  * 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
- * 6. Respond 200 with the event id, storedAt timestamp, and echoed headers
+ * 2. 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.
+ * 3. 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.
+ * 4. Fire the optional onStored callback (ephemeral events included: it is
+ *    the live-broadcast hook, and ephemeral events exist only as that
+ *    broadcast)
+ * 5. Respond 200 with the event id, storedAt timestamp, and -- when the
+ *    connector stated one -- the payment it attributed the write to
  *
  * @module
  */
@@ -496,8 +1245,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.
@@ -514,4 +1307,227 @@ 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 };
+/**
+ * The connector's payment statement, as read off a delivery to `POST /write`.
+ *
+ * A terminating connector states three headers on a delivery whose payment it
+ * verified at its OWN client edge (`toon-protocol/connector` ADR 0040):
+ *
+ * | header          | value                                                       |
+ * | --------------- | ----------------------------------------------------------- |
+ * | `X-TOON-Payer`  | `evm:0x<64 hex>` or `solana:<base58>` -- the client CHANNEL  |
+ * |                 | key whose covering claim that connector verified             |
+ * | `X-TOON-Amount` | the route's flat price (ADR 0020), decimal, base units       |
+ * | `X-TOON-Chain`  | that key's namespace -- `evm` or `solana`                    |
+ *
+ * ! ABSENCE IS NOT "UNPAID" ! The headers are present ONLY when this
+ * connector was the hop that took the payment and the route's price is
+ * non-zero. They are absent -- not empty -- on a peer-wire arrival, a
+ * forwarded packet, and every `price = 0` route (which is why the free
+ * ephemeral lane never sees them). A handler that read absence as "nobody
+ * paid" would reject exactly the deliveries a longer path produced.
+ *
+ * The relay does not, and cannot, re-validate any of this: it holds no chain
+ * state and speaks no ILP. The connector's statement IS the trust model. What
+ * this module adds is that a malformed statement is treated as no statement
+ * at all -- a garbled value from a stale or hostile caller becomes `undefined`
+ * rather than something the relay records and echoes as fact.
+ *
+ * History worth not repeating: relay#122 removed the earlier reading of these
+ * same header NAMES, correctly, because the TypeScript-era connector set
+ * `X-TOON-Payer` to the PREVIOUS HOP -- which on any path longer than one hop
+ * named the wrong party. ADR 0040's successor is a chain-verified channel key
+ * that is never stated by a hop that did not take the payment, so the value
+ * now means what its name says (relay#133).
+ *
+ * @module
+ */
+
+/** A payment the terminating connector states it verified. */
+interface PaymentAttribution {
+    /** The client channel key, namespaced: `evm:0x<64 hex>` / `solana:<base58>`. */
+    payer: string;
+    /** The route's flat price in base units, decimal. */
+    amount: string;
+    /** The payer key's namespace. */
+    chain: 'evm' | 'solana';
+}
+/**
+ * Read the connector's payment statement off a request.
+ *
+ * Returns `undefined` unless ALL THREE headers are present, individually
+ * well-formed, and mutually consistent (the payer's namespace must be the
+ * chain it claims). Anything else -- one header, two headers, a payer from a
+ * chain the `X-TOON-Chain` header disagrees with, a non-decimal amount -- is
+ * discarded whole. Partial attribution is worse than none: it would record
+ * half a fact as if it were the whole one.
+ *
+ * This never rejects the request. A caller that states nothing, or states
+ * nonsense, still gets its write handled on the merits of the event itself;
+ * the payment gate is upstream and has already run by the time anything
+ * reaches this process.
+ */
+declare function readPaymentAttribution(c: Context): PaymentAttribution | undefined;
+
+/**
+ * A minimal in-memory sliding-window rate limiter (relay#129).
+ *
+ * Built for the free ephemeral write lane (`POST /write-ephemeral`,
+ * handlers/write-ephemeral-handler.ts): with no payment gate, request volume
+ * is the only admission control that lane has, so every request must be
+ * checked against a per-key budget before any other work happens.
+ * Dependency-free and small enough to own outright rather than pull in a
+ * library, matching the shape the rest of the launcher already uses for
+ * self-contained stateful helpers (crypto/verify-pool.ts, launcher/metrics.ts).
+ *
+ * Sliding-window LOG, not a fixed-window counter: a fixed window lets a
+ * caller burst up to 2x the limit across a window boundary (all of window
+ * N's budget at :59, all of window N+1's budget at :00). The log costs one
+ * array per active key and O(requests-in-window) work per call, which is
+ * fine at the request volumes a bound like this is meant to police.
+ *
+ * @module
+ */
+/** Options for {@link createRateLimiter}. */
+interface RateLimiterOptions {
+    /** Max requests allowed per key within the trailing window. */
+    maxRequests: number;
+    /** Trailing window length in milliseconds. */
+    windowMs: number;
+    /** Clock override for deterministic tests (default: `Date.now`). */
+    now?: () => number;
+}
+/** A live rate limiter. One instance per bound; keys are caller-defined. */
+interface RateLimiter {
+    /**
+     * Check `key`'s budget. Returns `true` and records this call towards the
+     * budget when the key is under its limit; returns `false` (and records
+     * nothing) when the key is over budget. Never throws.
+     */
+    allow(key: string): boolean;
+}
+/**
+ * Create a sliding-window rate limiter.
+ *
+ * @param options - Bound + optional clock override.
+ */
+declare function createRateLimiter(options: RateLimiterOptions): RateLimiter;
+
+/**
+ * Free ephemeral write handler for @toon-protocol/relay (relay#129, ephemeral
+ * epic toon-meta#393 E2).
+ *
+ * A SECOND write surface, `POST /write-ephemeral`, distinct from the paid
+ * `POST /write` (write-handler.ts). It exists because the connector cannot
+ * carry two prices on one `handler_url` (`ConflictingHandlerPrice`,
+ * connector `route.rs:378-399`) -- a free lane needs its own endpoint,
+ * terminated by its own zero-priced route in the deploy config (see
+ * `deploy/connector.toml`'s `g.toon.relay.ephemeral` route).
+ *
+ * Differences from the paid handler, all deliberate:
+ *
+ * - Accepts ONLY ephemeral kinds (NIP-16, 20000 <= kind < 30000) -- anything
+ *   else is a 400. Persistent kinds have no business on a free lane; letting
+ *   them through would be a free ride around pay-to-write.
+ * - NEVER stores. Ephemeral kinds are never persisted on the paid path
+ *   either (NIP-16; write-handler.ts), so there is nothing this lane would
+ *   ever write to an EventStore -- it does not take one as a dependency.
+ * - Schnorr verification is ALWAYS FULL, with no skip and no config knob to
+ *   add one. The paid path's ephemeral verify-skip (write-handler.ts) is
+ *   safe ONLY because payment is the admission gate; this lane has no
+ *   payment gate, so signature verification IS its only defense against
+ *   forged-signature spam before the bounds below even apply. Reusing that
+ *   skip here would let anyone broadcast garbage to every subscriber for
+ *   free -- exactly the case write-handler.ts's own invariant comment warns
+ *   against.
+ * - Bounds, because free + broadcast = spam surface: a per-key sliding-
+ *   window rate limit (rate-limiter.ts) and a request-body size cap, both
+ *   config-gated with conservative defaults (see
+ *   {@link EphemeralWriteHandlerConfig}).
+ *
+ * Flow:
+ * 1. Rate-limit check, keyed by remote address (falling back to a shared
+ *    bucket when connection info is unavailable -- see `defaultClientKey`)
+ *    -- BEFORE any body is read, so a rate-limited caller costs as little
+ *    work as possible -> 429 over budget.
+ * 2. Body-size check against `maxBodyBytes` -- BEFORE JSON parsing, so an
+ *    oversized payload is never deserialized -> 413 too large.
+ * 3. Parse JSON body `{ event }` -> 400 on malformed/missing event.
+ * 4. Reject non-ephemeral kinds -> 400.
+ * 5. Full schnorr verification, never skipped -> 422 on invalid signature.
+ * 6. Fire the optional onBroadcast callback (the live-broadcast hook).
+ *    Nothing is ever stored.
+ * 7. Respond 200 with the event id.
+ *
+ * @module
+ */
+
+/**
+ * Conservative default rate-limit bound: 200 requests per 10-second window
+ * per key. Sized for presence/typing traffic (the epic's motivating
+ * workload, toon-meta#393), not huddle-frame rates -- that traffic stays on
+ * the paid path. Deliberately generous rather than tight: this is a spam
+ * ceiling, not a fairness scheduler, and a false-positive reject on
+ * legitimate ephemeral traffic (a dropped typing indicator) is silent and
+ * has no client-side retry signal.
+ */
+declare const DEFAULT_EPHEMERAL_RATE_LIMIT: {
+    maxRequests: number;
+    windowMs: number;
+};
+/**
+ * Conservative default body-size cap in bytes. Ephemeral events on this lane
+ * (presence heartbeats, typing indicators) are small JSON; 8 KiB comfortably
+ * covers a signed Nostr event with generous tag/content headroom while
+ * bounding worst-case memory per request on an unpaid surface.
+ */
+declare const DEFAULT_EPHEMERAL_MAX_BODY_BYTES: number;
+/** Configuration for the ephemeral write handler. */
+interface EphemeralWriteHandlerConfig {
+    /**
+     * Signature verifier. Defaults to the inline `verifyEventSignature`; the
+     * launcher injects the worker-pool verifier (crypto/verify-pool.ts),
+     * shared with the paid handler, so verify bursts run off the event loop
+     * (relay#85). May resolve asynchronously -- the handler awaits it.
+     *
+     * There is NO devMode/skip option here, unlike the paid handler --
+     * verification on this lane is always full (see the module doc).
+     */
+    verifyEvent?: (event: NostrEvent) => Promise<boolean> | boolean;
+    /** Optional callback fired after an event passes all checks (broadcast hook). */
+    onBroadcast?: (event: NostrEvent) => void;
+    /** Log one line per accepted write (default: false), matching write-handler.ts. */
+    logWrites?: boolean;
+    /** Rate-limit bound (default {@link DEFAULT_EPHEMERAL_RATE_LIMIT}). */
+    rateLimit?: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    /** Request body size cap in bytes (default {@link DEFAULT_EPHEMERAL_MAX_BODY_BYTES}). */
+    maxBodyBytes?: number;
+    /**
+     * Test-only: inject a rate limiter directly (e.g. with a fake clock)
+     * instead of letting the handler build one from `rateLimit`.
+     */
+    rateLimiter?: RateLimiter;
+    /**
+     * Test-only: override how a request is keyed for rate limiting. Defaults
+     * to `defaultClientKey` (remote address via `getConnInfo`, falling back to
+     * a shared bucket).
+     */
+    getClientKey?: (c: Context) => string;
+}
+/** Ephemeral write handler instance. */
+interface EphemeralWriteHandler {
+    /** Handle a plain-HTTP ephemeral write request. */
+    handleWrite(c: Context): Promise<Response>;
+}
+/**
+ * Create the ephemeral write handler.
+ *
+ * @param config - Handler configuration.
+ * @returns An EphemeralWriteHandler with a handleWrite method.
+ */
+declare function createEphemeralWriteHandler(config?: EphemeralWriteHandlerConfig): EphemeralWriteHandler;
+
+export { type AddressCoordinate, ConnectionHandler, DEFAULT_EPHEMERAL_MAX_BODY_BYTES, DEFAULT_EPHEMERAL_RATE_LIMIT, DEFAULT_RELAY_CONFIG, DELETION_KIND, type DeletionTargets, type DurationStats, EXPIRATION_TAG, type EphemeralWriteHandler, type EphemeralWriteHandlerConfig, type EventStore, type EventStoreOptions, type HealthConfig, type HealthResponse, InMemoryEventStore, type MetricsRegistry, type MetricsSnapshot, NostrRelayServer, type PaymentAttribution, type RateLimiter, type RateLimiterOptions, type RelayConfig, RelayError, type RelayInstance, type RelayServerConfig, RelaySubscriber, type RelaySubscriberConfig, type RelaySubscription, type ResolvedRelayConfig, SqliteEventStore, type Subscription, VERSION, type VerifyPool, type VerifyPoolOptions, type WriteHandler, type WriteHandlerConfig, createEphemeralWriteHandler, createHealthResponse, createMetricsRegistry, createRateLimiter, createVerifyPool, createWriteHandler, defaultVerifyWorkers, getExpiration, isDeletableBy, isDeletionKind, isExpired, isInternalBindHost, matchFilter, parseAddressCoordinate, parseBlockedEventIds, parseDeletionTargets, readOpenFilesSoftLimit, readPaymentAttribution, serializeEventFrame, startRelay, verifyEventId, verifyEventSignature, verifyImplementation, warnIfWritePortExposed };