@toon-protocol/relay 1.3.3 → 2.0.0

package/dist/index.d.ts

@@ -1,13 +1,11 @@
 import { NostrEvent } from 'nostr-tools/pure';
 import { Filter } from 'nostr-tools/filter';
 import { WebSocket } from 'ws';
-import { EmbeddableConnectorLike, SkillDescriptor, BootstrapPhase, ChainPreset, IlpClient } from '@toon-protocol/core';
-export { ToonDecodeError, ToonEncodeError, decodeEventFromToon, encodeEventToToon } from '@toon-protocol/core';
-import { Hono, Context } from 'hono';
 import { SimplePool } from 'nostr-tools/pool';
-import { Handler } from '@toon-protocol/sdk';
-import { PublicClient, WalletClient } from 'viem';
-import { ToonRoutingMeta } from '@toon-protocol/core/toon';
+import { Context } from 'hono';
+
+/** Package version, surfaced on `GET /health`. */
+declare const VERSION = "0.1.0";
 
 /**
  * Configuration options for the Nostr relay.
@@ -226,189 +224,31 @@ declare class NostrRelayServer {
 }
 
 /**
- * Configuration for the Pricing Service.
- */
-interface PricingConfig {
-    /** Base price per byte for event storage */
-    basePricePerByte: bigint;
-    /** Optional price overrides by event kind */
-    kindOverrides?: Map<number, bigint>;
-}
-/**
- * Error class for pricing-specific errors.
- */
-declare class PricingError extends RelayError {
-    constructor(message: string, code?: string);
-}
-
-/**
- * Service for calculating event storage prices with kind-based overrides.
- */
-declare class PricingService {
-    private readonly basePricePerByte;
-    private readonly kindOverrides;
-    constructor(config: PricingConfig);
-    /**
-     * Calculate price for a Nostr event.
-     *
-     * @param event - The Nostr event to price
-     * @returns The calculated price as bigint
-     */
-    calculatePrice(event: NostrEvent): bigint;
-    /**
-     * Calculate price from raw TOON bytes and event kind.
-     *
-     * @param bytes - The TOON-encoded event bytes
-     * @param kind - The event kind number
-     * @returns The calculated price as bigint
-     */
-    calculatePriceFromBytes(bytes: Uint8Array, kind: number): bigint;
-    /**
-     * Get the effective price per byte for a given kind.
-     *
-     * @param kind - The event kind number
-     * @returns The price per byte (kind override if exists, otherwise base price)
-     */
-    getPricePerByte(kind: number): bigint;
-}
-
-/**
- * Load pricing configuration from environment variables.
+ * TOON event codec.
  *
- * Environment variables:
- * - RELAY_BASE_PRICE_PER_BYTE: Base price per byte (default: "1")
- * - RELAY_KIND_OVERRIDES: JSON object mapping kind to price (optional)
- *   Format: {"1":"5","30023":"100"}
+ * 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.
  *
- * @returns PricingConfig loaded from environment
- * @throws PricingError if env vars contain invalid values
- */
-declare function loadPricingConfigFromEnv(): PricingConfig;
-/**
- * Load pricing configuration from a JSON file.
- *
- * File format:
- * {
- *   "basePricePerByte": "10",
- *   "kindOverrides": {
- *     "0": "0",
- *     "1": "5",
- *     "30023": "100"
- *   }
- * }
- *
- * @param path - Path to the JSON config file
- * @returns PricingConfig loaded from file
- * @throws PricingError if file cannot be read or contains invalid values
- */
-declare function loadPricingConfigFromFile(path: string): PricingConfig;
-
-/**
- * Validate that a string is a valid Nostr pubkey format.
- * @param pubkey - The pubkey to validate
- * @returns true if valid 64-character lowercase hex string
- */
-declare function isValidPubkey(pubkey: string): boolean;
-/**
- * Configuration for the Business Logic Server.
- */
-interface BlsConfig {
-    /** Base price per byte for event storage (used for simple pricing) */
-    basePricePerByte: bigint;
-    /** Optional PricingService for kind-based pricing overrides */
-    pricingService?: PricingService;
-    /** Optional owner pubkey - events from this pubkey bypass payment */
-    ownerPubkey?: string;
-}
-/**
- * Incoming packet request from ILP connector.
- */
-interface HandlePacketRequest {
-    /** Payment amount as string (parsed to bigint) */
-    amount: string;
-    /** ILP destination address */
-    destination: string;
-    /** Base64-encoded TOON Nostr event */
-    data: string;
-    /** Source ILP address */
-    sourceAccount?: string;
-}
-/**
- * Response for accepted packet.
- */
-interface HandlePacketAcceptResponse {
-    accept: true;
-    metadata?: {
-        eventId: string;
-        storedAt: number;
-    };
-}
-/**
- * Response for rejected packet.
- */
-interface HandlePacketRejectResponse {
-    accept: false;
-    /** ILP error code (F00, F06, etc.) */
-    code: string;
-    /** Human-readable error message */
-    message: string;
-    metadata?: {
-        required?: string;
-        received?: string;
-    };
-}
-/**
- * Union type for packet response.
- */
-type HandlePacketResponse = HandlePacketAcceptResponse | HandlePacketRejectResponse;
-/**
- * ILP error code constants.
- */
-declare const ILP_ERROR_CODES: {
-    readonly BAD_REQUEST: "F00";
-    readonly INSUFFICIENT_AMOUNT: "F06";
-    readonly INTERNAL_ERROR: "T00";
-};
-/**
- * BLS-specific error class.
+ * @module
  */
-declare class BlsError extends RelayError {
-    constructor(message: string, code?: string);
-}
 
-/**
- * Business Logic Server for ILP payment verification.
- *
- * Handles payment requests from an ILP connector, verifying that the
- * payment amount meets the required price for storing the included
- * Nostr event.
- */
-declare class BusinessLogicServer {
-    private config;
-    private eventStore;
-    private app;
-    constructor(config: BlsConfig, eventStore: EventStore);
-    /**
-     * Set up HTTP routes.
-     */
-    private setupRoutes;
-    /**
-     * Process a packet request.
-     *
-     * This method is public to support direct connector integration in embedded mode,
-     * where the connector calls this method directly via setPacketHandler() instead
-     * of making HTTP requests.
-     */
-    handlePacket(request: HandlePacketRequest): HandlePacketAcceptResponse | HandlePacketRejectResponse;
-    /**
-     * Get the Hono app instance for testing or composition.
-     */
-    getApp(): Hono;
-    /**
-     * Start the HTTP server on the specified port.
-     */
-    start(port: number): void;
-}
+/** 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.
@@ -459,239 +299,70 @@ declare class RelaySubscriber {
 /**
  * startRelay() -- Programmatic API for starting a TOON relay node.
  *
- * This module wraps the same SDK components used by docker/src/entrypoint-sdk.ts
- * into a single function call with a typed configuration object. Both
- * `startRelay()` and the Docker entrypoint compose the same pipeline:
+ * The relay is a plain HTTP/WebSocket app. It does NOT speak ILP and contains
+ * no payment, connector, settlement, or pricing logic: payment is enforced
+ * entirely upstream by an external terminator (see the connector repo). By the
+ * time a write reaches this process it is already proven paid, so the relay
+ * simply stores the event and serves reads.
  *
- *   Identity -> Verification -> Pricing -> HandlerRegistry -> BLS + Relay + Bootstrap
+ * Two surfaces:
  *
- * The key difference is lifecycle management: the Docker entrypoint uses
- * process-level signals (SIGINT/SIGTERM), while `startRelay()` returns a
- * `RelayInstance` with an explicit `.stop()` method.
+ *   - `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.
+ *   - Free NIP-01 WebSocket reads (TOON_RELAY_PORT, default 7100).
  *
- * ## Deployment Modes
+ * `startRelay()` returns a `RelayInstance` with an explicit `.stop()` for
+ * lifecycle control (the CLI wraps this with process-signal handling).
  *
- * The town node ALWAYS runs an embedded `ConnectorNode` so that packets
- * destined for its own ILP address can be routed locally (the connector and
- * the BLS handler must share a process for the round-trip to work).
- *
- * - **Standalone embedded** (no `connectorUrl`): A self-routing embedded
- *   connector with no upstream peers. Useful for genesis nodes and tests.
- * - **Embedded with parent** (`connectorUrl` set): The embedded connector
- *   is configured with `connectorUrl` as a parent BTP peer, plus a self-route
- *   for local delivery and a default-route to the parent for everything else.
- * - **Pre-built embedded** (`connector`): Pass a fully constructed
- *   `EmbeddableConnectorLike`. The town does not modify it.
- *
- * `connector` and `connectorUrl` are mutually exclusive — provide at most one.
+ * @module
  */
 
 /**
  * Configuration for starting a TOON relay node via `startRelay()`.
  *
- * Exactly one of `mnemonic` or `secretKey` must be provided.
- * `connector` and `connectorUrl` are mutually exclusive — provide at most one.
- *
- * - When neither is provided, a standalone embedded `ConnectorNode` is built
- *   with only a self-route (no upstream peers).
- * - When `connectorUrl` is set, the embedded connector is configured with
- *   that URL as a parent BTP peer plus a default-route to it. `ilpAddress`
- *   becomes REQUIRED in this mode and must fall under the parent's prefix
- *   (e.g. `g.townhouse.<self>`).
- * - When `connector` is set, the caller-supplied `EmbeddableConnectorLike`
- *   is used as-is; town does not configure peers, routes, or settlement on it.
+ * Exactly one of `mnemonic` or `secretKey` must be provided -- it is the node's
+ * Nostr identity (surfaced on `/health`).
  */
 interface RelayConfig {
-    /** 12-word or 24-word BIP-39 mnemonic phrase. */
+    /** 12-word or 24-word BIP-39 mnemonic phrase (NIP-06 derivation). */
     mnemonic?: string;
     /** 32-byte secp256k1 secret key. */
     secretKey?: Uint8Array;
-    /**
-     * Pre-built embedded connector. Mutually exclusive with `connectorUrl`.
-     * When provided, town does not modify the connector — peers, routes, and
-     * settlement are the caller's responsibility.
-     */
-    connector?: EmbeddableConnectorLike;
-    /**
-     * Parent connector BTP URL (e.g. `ws://apex.example:3001`). When set, the
-     * embedded connector is built with this URL as a parent peer and a default
-     * `g.` route to that peer; `ilpAddress` MUST also be set and fall under the
-     * parent's prefix. Mutually exclusive with `connector`.
-     */
-    connectorUrl?: string;
-    /** BTP peer id to use for the parent connector (default: `'apex'`). */
-    parentPeerId?: string;
-    /** BTP auth token for the parent peer (default: empty string -- no-auth). */
-    parentAuthToken?: string;
-    /** Stable nodeId for the embedded connector (default: `toon-<pubkeyShort>`). */
-    nodeId?: string;
-    /** BTP server port for the embedded connector (default: 3000). */
-    btpServerPort?: number;
-    /**
-     * EVM private key for settlement infrastructure on the embedded connector.
-     * If not set, the identity's secp256k1 key is reused.
-     */
-    settlementPrivateKey?: string;
-    /**
-     * EVM treasury address advertised to the parent connector for the
-     * embedded-with-parent peer entry. The apex's PerPacketClaimService uses
-     * this as the `peerAddress` when the apex opens a payment channel toward
-     * this child. Only meaningful when `connectorUrl` is set. When omitted,
-     * the parent peer entry has no `evmAddress` and the apex's channel-open
-     * call must supply `peerAddress` explicitly.
-     */
-    parentEvmAddress?: string;
-    /** WebSocket relay port (default: 7100). */
+    /** WebSocket relay (read) port (default: 7100). */
     relayPort?: number;
-    /** BLS HTTP server port (default: 3100). */
+    /** HTTP write/health port (default: 3100). */
     blsPort?: number;
     /**
-     * ILP address for this node. Default `g.toon.<pubkeyShort>` is used only
-     * when no parent connector is configured. When `connectorUrl` is set this
-     * field is REQUIRED and must fall under the parent's address prefix.
+     * WebSocket bind host (default: 0.0.0.0). Set to `127.0.0.1` to bind the read
+     * port to localhost only (e.g. when an upstream proxy handles inbound).
      */
-    ilpAddress?: string;
-    /** BTP WebSocket endpoint (default: ws://localhost:3000). */
-    btpEndpoint?: string;
-    /** Base price per byte in ILP units (default: 10n). */
-    basePricePerByte?: bigint;
-    /** Routing buffer percentage for x402 multi-hop overhead (default: 10). */
-    routingBufferPercent?: number;
-    /** Enable x402 /publish endpoint (default: false). */
-    x402Enabled?: boolean;
-    /** Facilitator EVM address for x402 payments. Defaults to the node's EVM address. */
-    facilitatorAddress?: string;
-    /** Known peers to bootstrap with. */
-    knownPeers?: {
-        pubkey: string;
-        relayUrl: string;
-        btpEndpoint: string;
-    }[];
-    /** Chain preset name (default: 'anvil'). See resolveChainConfig(). */
-    chain?: string;
-    /** Chain ID -> RPC URL mapping (e.g., { 'evm:base:31337': 'http://localhost:8545' }). */
-    chainRpcUrls?: Record<string, string>;
-    /** Chain ID -> TokenNetwork contract address. */
-    tokenNetworks?: Record<string, string>;
-    /** Chain ID -> preferred token address. */
-    preferredTokens?: Record<string, string>;
-    /**
-     * Chain ID -> settlement (recipient) address advertised in kind:10032.
-     *
-     * By default every supported chain advertises the identity's EVM address.
-     * That is wrong for non-EVM chains (e.g. `solana:devnet`), whose settlement
-     * recipient must be a chain-native address (a base58 Solana pubkey). Provide
-     * a per-chain override here to advertise a chain-native recipient; chains
-     * absent from this map keep the EVM-address default.
-     *
-     * NOTE (Phase-2 Stage 2 gate): advertising a Solana recipient is necessary
-     * but NOT sufficient for a settleable Solana loop — the client must also open
-     * a real on-chain Solana payment-channel PDA and sign over that PDA. See the
-     * Stage-2 PR description / gate report.
-     */
-    settlementAddresses?: Record<string, string>;
-    /** Data directory path (default: ./data). */
+    host?: string;
+    /** Data directory for the file-backed SQLite store (default: ./data). */
     dataDir?: string;
-    /** Enable dev mode (skip verification). Default: false. */
-    devMode?: boolean;
-    /** Discovery mode: 'seed-list' for production, 'genesis' for dev (default: 'genesis'). */
-    discovery?: 'seed-list' | 'genesis';
-    /** Public Nostr relay URLs for seed relay discovery (used when discovery: 'seed-list'). */
-    seedRelays?: string[];
-    /** Whether to publish this node as a seed relay entry (default: false). */
-    publishSeedEntry?: boolean;
-    /** External WebSocket URL of this relay (required if publishSeedEntry is true). */
-    externalRelayUrl?: string;
     /**
-     * Ator hidden service configuration for the relay.
-     *
-     * When enabled, the relay binds to localhost only (ator handles inbound routing)
-     * and publishes the `.anon` address in seed relay discovery events.
-     *
-     * - `enabled: false` (default): Relay binds to `0.0.0.0`, no privacy overlay.
-     * - `enabled: true`: Relay binds to `127.0.0.1`, publishes `anonAddress` for discovery.
+     * Pre-built EventStore. When provided, the relay uses it instead of building
+     * the default file-backed `SqliteEventStore` under `dataDir` (useful for
+     * tests via `InMemoryEventStore`, or to share a store when embedding). The
+     * caller owns its lifecycle when supplied.
      */
-    ator?: {
-        enabled: boolean;
-        /** The `.anon` hidden service address for this relay (e.g., "wss://abc123.anon:443"). */
-        anonAddress?: string;
-        /** SOCKS5 proxy URL for outbound connections (default: "socks5h://127.0.0.1:9050"). */
-        socksProxy?: string;
-    };
-    /**
-     * Optional DVM skill descriptor to include in service discovery events.
-     * When provided, the service discovery event will include the `skill` field.
-     * Typically computed by `node.getSkillDescriptor()` from the SDK.
-     */
-    skill?: SkillDescriptor;
-    /** Enable ArDrive peer lookup (default: false). */
-    ardriveEnabled?: boolean;
-    /** Public Nostr relay URLs for social discovery. */
-    relayUrls?: string[];
-    /** Asset code for ILP (default: 'USD'). */
-    assetCode?: string;
-    /** Asset scale for ILP (default: 6). */
-    assetScale?: number;
-    /**
-     * Fee per event in ILP units (overrides basePricePerByte when set).
-     * When provided, sets basePricePerByte to this value. Used by the
-     * Townhouse orchestrator via TOON_FEE_PER_EVENT env var.
-     */
-    feePerEvent?: number;
-    /**
-     * NIP-40 time-to-live for this node's kind:10032 announcement, in seconds
-     * (default 3600). The node re-publishes its announcement at half this
-     * interval so a live apex stays fresh while an offline one expires, letting
-     * clients skip its unreachable BTP endpoint (issue #261). Set to 0 to disable
-     * the expiration tag and the heartbeat (non-expiring announcement). Override
-     * via the `TOON_ANNOUNCEMENT_TTL_SECONDS` env var.
-     */
-    announcementTtlSeconds?: number;
+    eventStore?: EventStore;
+    /** Skip event-signature verification on `POST /write` (default: false). */
+    devMode?: boolean;
 }
 /**
- * Resolved configuration with all defaults applied. All fields are non-optional
- * (ports, pricing, paths have been filled in).
+ * Resolved configuration with all defaults applied.
  */
 interface ResolvedRelayConfig {
     relayPort: number;
     blsPort: number;
-    ilpAddress: string;
-    btpEndpoint: string;
-    /** Stable nodeId of the embedded connector. */
-    nodeId: string;
-    /** Parent connector URL when peering with one (omitted otherwise). */
-    connectorUrl?: string;
-    /** Parent BTP peer id (only meaningful when connectorUrl is set). */
-    parentPeerId?: string;
-    basePricePerByte: bigint;
-    routingBufferPercent: number;
-    x402Enabled: boolean;
-    knownPeers: {
-        pubkey: string;
-        relayUrl: string;
-        btpEndpoint: string;
-    }[];
+    host: string;
     dataDir: string;
     devMode: boolean;
-    ardriveEnabled: boolean;
-    relayUrls: string[];
-    assetCode: string;
-    assetScale: number;
-    /** Discovery mode: 'seed-list' for production, 'genesis' for dev. */
-    discovery: 'seed-list' | 'genesis';
-    /** Public Nostr relay URLs for seed relay discovery. */
-    seedRelays: string[];
-    /** Whether to publish this node as a seed relay entry. */
-    publishSeedEntry: boolean;
-    /** External WebSocket URL of this relay (for seed entry publishing). */
-    externalRelayUrl?: string;
-    /** Chain preset name (e.g., 'anvil', 'arbitrum-one'). */
-    chain: string;
 }
 /**
  * A running TOON relay node instance returned by `startRelay()`.
- *
- * Provides lifecycle control (stop), identity info, and bootstrap results.
  */
 interface RelayInstance {
     /** Whether the relay is currently running. */
@@ -699,28 +370,19 @@ interface RelayInstance {
     /** Gracefully stop the relay and release all resources. */
     stop(): Promise<void>;
     /**
-     * Subscribe to a remote Nostr relay. Received events are stored in the
-     * Town's EventStore. Returns a handle for lifecycle management.
+     * Subscribe to a remote Nostr relay. Received events are stored in this
+     * node's EventStore. Returns a handle for lifecycle management.
      *
      * @param relayUrl - WebSocket URL of the relay to subscribe to.
      * @param filter - Nostr filter (kinds, authors, etc.).
      * @returns A RelaySubscription handle.
-     * @throws If the town is not running.
+     * @throws If the relay is not running.
      */
     subscribe(relayUrl: string, filter: Filter): RelaySubscription;
     /** The node's Nostr x-only public key (64-char hex). */
     pubkey: string;
-    /** The node's EVM address (0x-prefixed). */
-    evmAddress: string;
     /** The resolved configuration with all defaults applied. */
     config: ResolvedRelayConfig;
-    /** Bootstrap results from the startup phase. */
-    bootstrapResult: {
-        peerCount: number;
-        channelCount: number;
-    };
-    /** Discovery mode used by this instance. */
-    discoveryMode: 'seed-list' | 'genesis';
 }
 /**
  * Handle for managing an outbound subscription to a remote Nostr relay.
@@ -737,636 +399,104 @@ interface RelaySubscription {
 /**
  * Start a TOON relay node with the given configuration.
  *
- * Composes the full SDK pipeline (identity, verification, pricing, handlers)
- * and starts the relay WebSocket server, BLS HTTP server, bootstrap service,
- * and relay monitor. Returns a `RelayInstance` for lifecycle management.
- *
- * The town node ALWAYS runs an embedded `ConnectorNode`. Three configurations
- * are supported:
- * - No connector args: standalone embedded connector with self-route only.
- * - `connectorUrl`: embedded connector configured with that URL as a parent
- *   BTP peer plus a default `g.` route to it. `ilpAddress` is REQUIRED here.
- * - `connector`: pass a pre-built `EmbeddableConnectorLike`; town does not
- *   modify it.
+ * Wires the event store, the HTTP write/health server, and the NIP-01
+ * WebSocket read server, then returns a `RelayInstance` for lifecycle control.
  *
- * @param config - Node configuration. One of `mnemonic`/`secretKey` is required;
- *   `connector` and `connectorUrl` are mutually exclusive.
+ * @param config - Node configuration. One of `mnemonic`/`secretKey` is required.
  * @returns A running RelayInstance.
  * @throws If both or neither of mnemonic/secretKey are provided.
- * @throws If both connector and connectorUrl are provided.
- * @throws If connectorUrl is set without an explicit ilpAddress.
  *
  * @example
  * ```typescript
- * // Standalone (no parent)
- * const town = await startRelay({ mnemonic: 'abandon ...' });
- *
- * // Embedded with parent
- * const town = await startRelay({
- *   mnemonic: 'abandon ...',
- *   connectorUrl: 'ws://apex.example:3001',
- *   parentPeerId: 'apex',
- *   parentAuthToken: '',
- *   ilpAddress: 'g.townhouse.alice',
- * });
+ * const relay = await startRelay({ secretKey });
+ * // ... POST /write on 3100, read NIP-01 on 7100 ...
+ * await relay.stop();
  * ```
  */
 declare function startRelay(config: RelayConfig): Promise<RelayInstance>;
-/**
- * @deprecated Use {@link startRelay} instead. Retained for backwards
- * compatibility after the town → relay package merge.
- */
-declare const startTown: typeof startRelay;
-/**
- * @deprecated Use {@link RelayConfig} instead.
- */
-type TownConfig = RelayConfig;
-/**
- * @deprecated Use {@link RelayInstance} instead.
- */
-type TownInstance = RelayInstance;
-/**
- * @deprecated Use {@link ResolvedRelayConfig} instead.
- */
-type ResolvedTownConfig = ResolvedRelayConfig;
-/**
- * @deprecated Use {@link RelaySubscription} instead.
- */
-type TownSubscription = RelaySubscription;
 
 /**
- * Enriched health response for TOON relay nodes (Story 3.6).
- *
- * Provides a pure function `createHealthResponse()` that builds a comprehensive
- * health JSON object combining static configuration (pricing, chain, version,
- * capabilities) with live runtime state (phase, peerCount, channelCount).
+ * Health response for the relay's HTTP server.
  *
- * The response mirrors kind:10035 service discovery event fields but adds
- * runtime-only fields that cannot be known at event publish time.
+ * The relay is a plain read/write app (no payment, connector, or settlement
+ * layer), so the health response is deliberately minimal: liveness plus the
+ * node's identity and version. It is served from `GET /health` on the write
+ * port and is the target of the container healthcheck.
  *
  * @module
  */
-
-/** TEE attestation state for the health response (enforcement guideline 12). */
-interface TeeHealthInfo {
-    /** Whether a valid attestation has been published. */
-    attested: boolean;
-    /** Enclave type identifier (e.g., 'aws-nitro', 'marlin-oyster'). */
-    enclaveType: string;
-    /** Unix timestamp of the last attestation event. */
-    lastAttestation: number;
-    /** Platform Configuration Register 0 (SHA-384 hex, 96 chars). */
-    pcr0: string;
-    /** Attestation validity state. */
-    state: 'valid' | 'stale' | 'unattested';
-}
 /** Configuration for building a health response. */
 interface HealthConfig {
-    /** Current bootstrap phase. */
-    phase: BootstrapPhase;
     /** Node's Nostr pubkey (64-char hex). */
     pubkey: string;
-    /** Node's ILP address. */
-    ilpAddress: string;
-    /** Number of registered peers. */
-    peerCount: number;
-    /** Number of discovered (not yet registered) peers. */
-    discoveredPeerCount: number;
-    /** Number of open payment channels. */
-    channelCount: number;
-    /**
-     * Base price per byte (bigint from config, converted to number via Number()).
-     * Values exceeding Number.MAX_SAFE_INTEGER (2^53 - 1) will lose precision.
-     */
-    basePricePerByte: bigint;
-    /** Whether x402 is enabled. */
-    x402Enabled: boolean;
-    /** Chain preset name. */
-    chain: string;
-    /**
-     * TEE attestation info.
-     * Omit entirely when not running in a TEE (enforcement guideline 12).
-     */
-    tee?: TeeHealthInfo;
 }
-/** The enriched health response shape. */
+/** The health response shape. */
 interface HealthResponse {
     status: 'healthy';
-    phase: BootstrapPhase;
     pubkey: string;
-    ilpAddress: string;
-    peerCount: number;
-    discoveredPeerCount: number;
-    channelCount: number;
-    pricing: {
-        basePricePerByte: number;
-        currency: 'USDC';
-    };
-    x402?: {
-        enabled: true;
-        endpoint: string;
-    };
-    /**
-     * TEE attestation info. Only present when running in a TEE enclave.
-     * Entirely absent when not in TEE (enforcement guideline 12 --
-     * never `{ attested: false }`, simply omit the field).
-     */
-    tee?: TeeHealthInfo;
     capabilities: string[];
-    chain: string;
     version: string;
-    sdk: true;
     timestamp: number;
 }
 /**
- * Build an enriched health response from the given configuration.
- *
- * This is a pure function -- it takes a config object and returns a response
- * object. No Hono context or HTTP request is needed, making it easy to unit
- * test and reuse across entrypoints.
+ * Build a health response for the relay.
  *
- * The `x402` field is entirely omitted when x402 is disabled (AC #2).
- * This matches the same omission semantics used in kind:10035 events.
+ * Pure function: takes a config and returns the response object, so it is
+ * trivially unit-testable and reusable.
  *
- * @param config - Health configuration with runtime state and static config.
- * @returns The enriched health response object.
+ * @param config - Health configuration (the node's pubkey).
+ * @returns The health response object.
  */
 declare function createHealthResponse(config: HealthConfig): HealthResponse;
 
 /**
- * Event storage handler for @toon-protocol/relay.
- *
- * Stores incoming Nostr events in the EventStore after decoding from TOON.
- * This is the "default" handler for the relay -- it processes all event kinds
- * except those handled by kind-specific handlers.
- *
- * The handler is intentionally simple (~15 lines of logic). The SDK pipeline
- * handles signature verification, pricing validation, and self-write bypass
- * before the handler is invoked. The handler only needs to:
- *   1. ctx.decode() -- lazy-decode the TOON payload into a NostrEvent
- *   2. eventStore.store(event) -- persist the event
- *   3. ctx.accept({ eventId, storedAt }) -- accept the ILP packet
- */
-
-/**
- * Configuration for the event storage handler.
- *
- * Minimal by design -- the handler's only job is decode + store + accept.
- * Pricing, verification, and self-write bypass are SDK pipeline concerns.
- */
-interface EventStorageHandlerConfig {
-    /** Event store backend (e.g., SqliteEventStore from @toon-protocol/relay). */
-    eventStore: EventStore;
-}
-/**
- * Creates an event storage handler that decodes TOON payloads and stores
- * Nostr events in the configured EventStore.
- *
- * Errors from `ctx.decode()` or `eventStore.store()` are not caught here --
- * they propagate to the SDK's dispatch error boundary, which converts
- * unhandled exceptions to `{ accept: false, code: 'T00', message: 'Internal error' }`.
- *
- * @param config - Handler configuration with the event store backend.
- * @returns A handler function compatible with `node.onDefault(handler)`.
- */
-declare function createEventStorageHandler(config: EventStorageHandlerConfig): Handler;
-
-/**
- * EIP-3009 types and constants for the x402 publish endpoint.
+ * Write handler for @toon-protocol/relay.
  *
- * EIP-3009 (`transferWithAuthorization`) allows gasless USDC transfers:
- * the user signs an off-chain authorization, and the facilitator (node
- * operator) submits it on-chain, paying gas. The user pays only the
- * USDC transfer amount.
+ * 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.
  *
- * @module
- */
-
-/**
- * EIP-3009 `transferWithAuthorization` signed authorization.
- *
- * The user signs this off-chain (EIP-712 typed data). The facilitator
- * submits the signature on-chain to execute the USDC transfer.
- */
-interface Eip3009Authorization {
-    /** Sender's EVM address ('0x...'). */
-    from: string;
-    /** Recipient's EVM address ('0x...' -- facilitator). */
-    to: string;
-    /** USDC amount in micro-units (bigint). */
-    value: bigint;
-    /** Unix timestamp: authorization valid after this time. */
-    validAfter: number;
-    /** Unix timestamp: authorization expires at this time. */
-    validBefore: number;
-    /** 32-byte nonce ('0x...' hex string). */
-    nonce: string;
-    /** ECDSA recovery id (27 or 28). */
-    v: number;
-    /** ECDSA r component ('0x...' 32 bytes). */
-    r: string;
-    /** ECDSA s component ('0x...' 32 bytes). */
-    s: string;
-}
-/**
- * EIP-712 typed data structure for `transferWithAuthorization`.
- *
- * This is the type definition used for off-chain signature verification
- * and on-chain contract calls.
- *
- * NOTE: The EIP-712 domain for USDC's `transferWithAuthorization` is
- * different from the EIP-712 domain for TokenNetwork's balance proofs.
- * The x402 handler must use the USDC contract's domain.
- */
-declare const EIP_3009_TYPES: {
-    readonly TransferWithAuthorization: readonly [{
-        readonly name: "from";
-        readonly type: "address";
-    }, {
-        readonly name: "to";
-        readonly type: "address";
-    }, {
-        readonly name: "value";
-        readonly type: "uint256";
-    }, {
-        readonly name: "validAfter";
-        readonly type: "uint256";
-    }, {
-        readonly name: "validBefore";
-        readonly type: "uint256";
-    }, {
-        readonly name: "nonce";
-        readonly type: "bytes32";
-    }];
-};
-/**
- * EIP-712 domain separator for USDC's `transferWithAuthorization`.
- *
- * Uses the USDC contract's name and version, NOT the TokenNetwork's.
- */
-declare const USDC_EIP712_DOMAIN: {
-    readonly name: "USD Coin";
-    readonly version: "2";
-};
-/**
- * Minimal EventStore interface for destination reachability checks.
- * Uses structural typing to avoid importing @toon-protocol/relay directly.
- * The query method accepts Filter[] (array) per the relay's EventStore interface.
- */
-interface EventStoreLike {
-    query(filters: {
-        kinds?: number[];
-        authors?: string[];
-    }[]): unknown[];
-}
-/**
- * Request body for the x402 `/publish` endpoint.
- *
- * The client sends a signed Nostr event and a destination ILP address.
- * The handler TOON-encodes the event before routing.
- */
-interface X402PublishRequest {
-    /** Signed Nostr event. */
-    event: NostrEvent;
-    /** Target ILP address (e.g., "g.toon.target-relay"). */
-    destination: string;
-}
-/**
- * Response body for a successful x402 `/publish` request (HTTP 200).
- */
-interface X402PublishResponse {
-    /** Nostr event ID (64-char hex). */
-    eventId: string;
-    /** On-chain settlement transaction hash. */
-    settlementTxHash: string;
-    /** Whether the ILP PREPARE was fulfilled or rejected by the destination. */
-    deliveryStatus: 'fulfilled' | 'rejected';
-    /** Always false -- no refunds on REJECT per protocol design. */
-    refundInitiated: false;
-}
-/**
- * Response body for the 402 pricing negotiation.
- */
-interface X402PricingResponse {
-    /** Price in USDC micro-units (as string for BigInt serialization). */
-    amount: string;
-    /** Node operator's EVM address that will receive the USDC. */
-    facilitatorAddress: string;
-    /** Payment network identifier. */
-    paymentNetwork: 'eip-3009';
-    /** EVM chain ID. */
-    chainId: number;
-    /** USDC contract address on this chain. */
-    usdcAddress: string;
-}
-/**
- * Minimal USDC ABI for EIP-3009 operations.
- *
- * Includes only the functions needed by the x402 handler:
- * - `balanceOf`: Read sender's USDC balance (pre-flight check #2)
- * - `authorizationState`: Check nonce freshness (pre-flight check #3)
- * - `transferWithAuthorization`: Execute gasless USDC transfer (settlement)
- */
-declare const USDC_ABI: readonly [{
-    readonly name: "balanceOf";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [{
-        readonly name: "account";
-        readonly type: "address";
-    }];
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "uint256";
-    }];
-}, {
-    readonly name: "authorizationState";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [{
-        readonly name: "authorizer";
-        readonly type: "address";
-    }, {
-        readonly name: "nonce";
-        readonly type: "bytes32";
-    }];
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "bool";
-    }];
-}, {
-    readonly name: "transferWithAuthorization";
-    readonly type: "function";
-    readonly stateMutability: "nonpayable";
-    readonly inputs: readonly [{
-        readonly name: "from";
-        readonly type: "address";
-    }, {
-        readonly name: "to";
-        readonly type: "address";
-    }, {
-        readonly name: "value";
-        readonly type: "uint256";
-    }, {
-        readonly name: "validAfter";
-        readonly type: "uint256";
-    }, {
-        readonly name: "validBefore";
-        readonly type: "uint256";
-    }, {
-        readonly name: "nonce";
-        readonly type: "bytes32";
-    }, {
-        readonly name: "v";
-        readonly type: "uint8";
-    }, {
-        readonly name: "r";
-        readonly type: "bytes32";
-    }, {
-        readonly name: "s";
-        readonly type: "bytes32";
-    }];
-    readonly outputs: readonly [];
-}];
-
-/**
- * Pre-flight validation pipeline for the x402 publish endpoint.
- *
- * Implements 6 free checks that run before any on-chain transaction,
- * preventing gas griefing (E3-R008). All checks are either pure
- * cryptography or read-only RPC calls (no gas cost).
- *
- * Check order (cheapest to most expensive):
- * 1. EIP-3009 signature verification (off-chain, ~1ms)
- * 2. USDC balance check (eth_call, ~50ms)
- * 3. Nonce freshness check (eth_call, ~50ms)
- * 4. TOON shallow parse (pure computation, ~0.1ms)
- * 5. Schnorr signature verification (pure crypto, ~2ms)
- * 6. Destination reachability check (local lookup, ~0.1ms)
- *
- * @module
- */
-
-/**
- * Result of running the pre-flight validation pipeline.
- */
-interface PreflightResult {
-    /** Whether all checks passed. */
-    passed: boolean;
-    /** Which check failed (only set if passed is false). */
-    failedCheck?: string;
-    /** List of check names that were executed. */
-    checksPerformed: string[];
-}
-/**
- * Callback for Schnorr signature verification.
- * Returns true if the signature is valid.
- */
-type SchnorrVerifyFn = (meta: ToonRoutingMeta) => Promise<boolean>;
-/**
- * Configuration for the pre-flight validation pipeline.
- */
-interface PreflightConfig {
-    /** Resolved chain configuration. */
-    chainConfig: ChainPreset;
-    /** Base price per byte for pricing validation. */
-    basePricePerByte: bigint;
-    /** This node's Nostr public key. */
-    ownPubkey: string;
-    /** Whether dev mode is enabled (skips Schnorr verification). */
-    devMode: boolean;
-    /** viem public client for read-only contract calls (optional, for testing). */
-    publicClient?: PublicClient;
-    /** EventStore for destination reachability check (optional). */
-    eventStore?: EventStoreLike;
-    /** Schnorr verification callback (optional, uses SDK verification pipeline). */
-    schnorrVerify?: SchnorrVerifyFn;
-}
-/**
- * Run the 6-stage pre-flight validation pipeline.
- *
- * All checks are free (no gas cost). If any check fails, execution
- * stops immediately and no on-chain transaction is attempted.
- *
- * @param authorization - EIP-3009 signed authorization from the client.
- * @param toonData - Base64-encoded TOON payload.
- * @param destination - Target ILP address.
- * @param config - Pre-flight configuration.
- * @returns PreflightResult indicating success or which check failed.
- */
-declare function runPreflight(authorization: Eip3009Authorization, toonData: string, destination: string, config: PreflightConfig): Promise<PreflightResult>;
-
-/**
- * EIP-3009 on-chain settlement module for the x402 publish endpoint.
- *
- * Executes `transferWithAuthorization` on the USDC contract to settle
- * the gasless USDC transfer from the client to the facilitator (node
- * operator). The facilitator pays gas; the client pays only USDC.
- *
- * Settlement atomicity (E3-R006):
- * - If settlement fails (revert), no ILP PREPARE is constructed.
- * - If settlement succeeds but ILP PREPARE is rejected, no refund.
- *
- * @module
- */
-
-/**
- * Result of an EIP-3009 settlement attempt.
- */
-interface X402SettlementResult {
-    /** Whether the on-chain transaction succeeded. */
-    success: boolean;
-    /** Transaction hash (only set on success). */
-    txHash?: string;
-    /** Error message (only set on failure). */
-    error?: string;
-}
-/**
- * @deprecated Use X402SettlementResult instead.
- */
-type SettlementResult = X402SettlementResult;
-/**
- * Configuration for the settlement module.
- *
- * Named `X402SettlementConfig` to avoid collision with
- * `SettlementConfig` from `@toon-protocol/core` (bootstrap).
- */
-interface X402SettlementConfig {
-    /** Resolved chain configuration. */
-    chainConfig: ChainPreset;
-    /** viem wallet client for the facilitator (submits the tx, pays gas). */
-    walletClient: WalletClient;
-    /** viem public client for waiting on transaction receipts. */
-    publicClient?: PublicClient;
-}
-/**
- * Settle an EIP-3009 `transferWithAuthorization` on-chain.
- *
- * Submits the client's signed authorization to the USDC contract.
- * The facilitator (node operator) pays gas for the transaction.
- *
- * @param authorization - Signed EIP-3009 authorization from the client.
- * @param config - Settlement configuration with wallet client.
- * @returns SettlementResult indicating success/failure.
- */
-/**
- * @deprecated Use X402SettlementConfig instead.
- */
-type SettlementConfig = X402SettlementConfig;
-declare function settleEip3009(authorization: Eip3009Authorization, config: X402SettlementConfig): Promise<X402SettlementResult>;
-
-/**
- * x402 publish handler for the TOON protocol.
- *
- * Implements the HTTP-native payment on-ramp via the x402 protocol pattern.
- * Allows any HTTP client (AI agents, browsers, CLI tools) to publish Nostr
- * events to the network by paying USDC, without understanding ILP or
- * running an ILP client.
+ * 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.
  *
  * Flow:
- * 1. Client sends request without X-PAYMENT header -> 402 with pricing
- * 2. Client signs EIP-3009 auth and retries with X-PAYMENT header
- * 3. Handler runs 6 free pre-flight checks
- * 4. Handler settles USDC on-chain via transferWithAuthorization
- * 5. Handler constructs ILP PREPARE via shared buildIlpPrepare()
- * 6. Handler routes PREPARE through connector
- * 7. Handler returns 200 with event ID and tx hash
+ * 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
  *
  * @module
  */
 
 /**
- * Configuration for the x402 publish handler.
+ * Configuration for the write handler.
  */
-interface X402HandlerConfig {
-    /** Whether x402 is enabled for this node. */
-    x402Enabled: boolean;
-    /** Resolved chain configuration. */
-    chainConfig: ChainPreset;
-    /** Base price per byte in USDC micro-units. */
-    basePricePerByte: bigint;
-    /** Routing buffer percentage for multi-hop overhead (default: 10). */
-    routingBufferPercent: number;
-    /** Facilitator's EVM address (receives USDC payments). */
-    facilitatorAddress: string;
-    /** This node's Nostr public key. */
-    ownPubkey: string;
-    /** Whether dev mode is enabled (skips Schnorr verification). */
+interface WriteHandlerConfig {
+    /** Event store backend used to persist accepted events. */
+    eventStore: EventStore;
+    /** Whether dev mode is enabled (skips Schnorr signature verification). */
     devMode: boolean;
-    /** ILP client for sending PREPARE packets. */
-    ilpClient?: IlpClient;
-    /** Event store for destination reachability check. */
-    eventStore?: EventStoreLike;
-    /** TOON encoder function (defaults to core's encodeEventToToon). */
-    toonEncoder?: (event: NostrEvent) => Uint8Array;
-    /** viem wallet client for on-chain settlement (facilitator pays gas). */
-    walletClient?: WalletClient;
-    /** viem public client for read-only contract calls. */
-    publicClient?: PublicClient;
-    /** Override settle function (for testing). */
-    settle?: (auth: Eip3009Authorization, config: X402SettlementConfig) => Promise<X402SettlementResult>;
-    /** Override pre-flight function (for testing). */
-    runPreflightFn?: typeof runPreflight;
+    /** Optional callback fired after an event is successfully stored. */
+    onStored?: (event: NostrEvent) => void;
 }
 /**
- * x402 publish handler instance.
+ * Write handler instance.
  */
-interface X402Handler {
-    /** Handle a /publish request (both 402 pricing and paid publish). */
-    handlePublish: (c: Context) => Promise<Response>;
+interface WriteHandler {
+    /** Handle a plain-HTTP write request. */
+    handleWrite(c: Context): Promise<Response>;
 }
 /**
- * Create an x402 publish handler.
- *
- * Returns a handler that processes both the 402 pricing negotiation
- * (no X-PAYMENT header) and the paid publish flow (with X-PAYMENT header).
+ * Create a write handler.
  *
  * @param config - Handler configuration.
- * @returns X402Handler with handlePublish method.
+ * @returns A WriteHandler with a handleWrite method.
  */
-declare function createX402Handler(config: X402HandlerConfig): X402Handler;
-
-/**
- * x402 pricing calculator with multi-hop routing buffer.
- *
- * Computes the all-in USDC price for publishing a Nostr event via the
- * x402 HTTP on-ramp. The price includes a configurable routing buffer
- * (default 10%) to cover multi-hop overhead -- intermediate relays charge
- * their own per-byte fees.
- *
- * @module
- */
-/**
- * Configuration for the x402 pricing calculator.
- */
-interface X402PricingConfig {
-    /** Base price per byte in ILP/USDC micro-units (e.g., 10n). */
-    basePricePerByte: bigint;
-    /** Routing buffer percentage (default: 10, meaning 10%). */
-    routingBufferPercent: number;
-}
-/**
- * Calculate the all-in x402 price for a TOON payload.
- *
- * Formula:
- *   basePrice = basePricePerByte * toonLength
- *   buffer    = basePrice * routingBufferPercent / 100
- *   total     = basePrice + buffer
- *
- * The routing buffer covers multi-hop overhead. 10% default is a
- * conservative estimate per Party Mode Decision 8.
- *
- * @param config - Pricing configuration with base price and buffer percent.
- * @param toonLength - Length of the TOON-encoded payload in bytes.
- * @returns Total price in USDC micro-units.
- */
-declare function calculateX402Price(config: X402PricingConfig, toonLength: number): bigint;
-
-/**
- * @toon-protocol/relay
- *
- * ILP-gated Nostr relay with Business Logic Server.
- */
-declare const VERSION = "0.1.0";
+declare function createWriteHandler(config: WriteHandlerConfig): WriteHandler;
 
-export { type BlsConfig, BlsError, BusinessLogicServer, ConnectionHandler, DEFAULT_RELAY_CONFIG, EIP_3009_TYPES, type Eip3009Authorization, type EventStorageHandlerConfig, type EventStore, type EventStoreLike, type HandlePacketAcceptResponse, type HandlePacketRejectResponse, type HandlePacketRequest, type HandlePacketResponse, type HealthConfig, type HealthResponse, ILP_ERROR_CODES, InMemoryEventStore, NostrRelayServer, type PreflightConfig, type PreflightResult, type PricingConfig, PricingError, PricingService, type RelayConfig, RelayError, type RelayInstance, type RelayServerConfig, RelaySubscriber, type RelaySubscriberConfig, type RelaySubscription, type ResolvedRelayConfig, type ResolvedTownConfig, type SettlementConfig, type SettlementResult, SqliteEventStore, type Subscription, type TeeHealthInfo, type TownConfig, type TownInstance, type TownSubscription, USDC_ABI, USDC_EIP712_DOMAIN, VERSION, type X402Handler, type X402HandlerConfig, type X402PricingConfig, type X402PricingResponse, type X402PublishRequest, type X402PublishResponse, type X402SettlementConfig, type X402SettlementResult, calculateX402Price, createEventStorageHandler, createHealthResponse, createX402Handler, isValidPubkey, loadPricingConfigFromEnv, loadPricingConfigFromFile, matchFilter, runPreflight, settleEip3009, startRelay, startTown };
+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 };