@toon-protocol/relay 1.1.1

package/README.md

@@ -0,0 +1,24 @@
+# @toon-protocol/relay
+
+ILP-gated Nostr relay with Business Logic Server.
+
+## Install
+
+```bash
+npm install @toon-protocol/relay
+```
+
+## Usage
+
+```ts
+import {
+  NostrRelayServer,
+  BusinessLogicServer,
+  PricingService,
+  SqliteEventStore,
+} from '@toon-protocol/relay';
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,469 @@
+import { NostrEvent } from 'nostr-tools/pure';
+import { Filter } from 'nostr-tools/filter';
+import { WebSocket } from 'ws';
+export { ToonDecodeError, ToonEncodeError, decodeEventFromToon, encodeEventToToon } from '@toon-protocol/core';
+import { Hono } from 'hono';
+import { SimplePool } from 'nostr-tools/pool';
+
+/**
+ * Configuration options for the Nostr relay.
+ */
+interface RelayConfig {
+    /** Port to listen on (default: 7000) */
+    port: number;
+    /** Maximum concurrent connections (default: 100) */
+    maxConnections?: number;
+    /** Maximum subscriptions per connection (default: 20) */
+    maxSubscriptionsPerConnection?: number;
+    /** Maximum filters per subscription (default: 10) */
+    maxFiltersPerSubscription?: number;
+    /** Path to SQLite database file (default: ':memory:' for in-memory) */
+    databasePath?: string;
+}
+/**
+ * Default relay configuration values.
+ */
+declare const DEFAULT_RELAY_CONFIG: Required<RelayConfig>;
+
+/**
+ * Interface for event storage backends.
+ */
+interface EventStore {
+    /** Store an event by its ID */
+    store(event: NostrEvent): void;
+    /** Retrieve a single event by ID */
+    get(id: string): NostrEvent | undefined;
+    /** Query events matching any of the provided filters */
+    query(filters: Filter[]): NostrEvent[];
+    /** Close the storage backend (optional) */
+    close?(): void;
+}
+/**
+ * In-memory implementation of EventStore.
+ * Events are stored in a Map keyed by event ID.
+ */
+declare class InMemoryEventStore implements EventStore {
+    private events;
+    store(event: NostrEvent): void;
+    get(id: string): NostrEvent | undefined;
+    query(filters: Filter[]): NostrEvent[];
+    /**
+     * Close the storage backend (no-op for in-memory store).
+     */
+    close(): void;
+}
+
+/**
+ * Custom error class for relay storage errors.
+ */
+declare class RelayError extends Error {
+    code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * SQLite implementation of EventStore.
+ * Persists events to a SQLite database file.
+ */
+declare class SqliteEventStore implements EventStore {
+    private db;
+    private insertStmt;
+    private getStmt;
+    private deleteByPubkeyKindStmt;
+    private deleteByPubkeyKindDTagStmt;
+    private getByPubkeyKindStmt;
+    private getByPubkeyKindDTagStmt;
+    /**
+     * Create a new SqliteEventStore.
+     * @param dbPath - Path to the database file. Use ':memory:' for in-memory database.
+     */
+    constructor(dbPath?: string);
+    /**
+     * Store an event in the database.
+     * Handles replaceable and parameterized replaceable events according to NIP-01.
+     */
+    store(event: NostrEvent): void;
+    /**
+     * Store a replaceable event (kinds 10000-19999).
+     * Only keeps the latest event per pubkey+kind.
+     */
+    private storeReplaceableEvent;
+    /**
+     * Store a parameterized replaceable event (kinds 30000-39999).
+     * Only keeps the latest event per pubkey+kind+d-tag.
+     */
+    private storeParameterizedReplaceableEvent;
+    /**
+     * Retrieve an event by its ID.
+     */
+    get(id: string): NostrEvent | undefined;
+    /**
+     * Query events matching any of the provided filters.
+     */
+    query(filters: Filter[]): NostrEvent[];
+    /**
+     * Build SQL query from filters.
+     */
+    private buildQuerySql;
+    /**
+     * Close the database connection.
+     */
+    close(): void;
+}
+
+/**
+ * Check if an event matches a single filter according to NIP-01 rules.
+ *
+ * Matching rules:
+ * - All specified fields must match (AND logic)
+ * - `ids` and `authors` support prefix matching
+ * - Tag filters (#e, #p, etc.) match events with corresponding tags
+ * - Empty filter matches all events
+ *
+ * @param event - The Nostr event to check
+ * @param filter - The filter to match against
+ * @returns true if the event matches the filter
+ */
+declare function matchFilter(event: NostrEvent, filter: Filter): boolean;
+
+/**
+ * Represents an active subscription from a client.
+ */
+interface Subscription {
+    /** Unique subscription identifier from the client */
+    id: string;
+    /** Filters applied to this subscription */
+    filters: Filter[];
+}
+/**
+ * Handles NIP-01 messages for a single WebSocket connection.
+ */
+declare class ConnectionHandler {
+    private ws;
+    private eventStore;
+    private subscriptions;
+    private config;
+    constructor(ws: WebSocket, eventStore: EventStore, config?: Partial<RelayConfig>);
+    /**
+     * Handle an incoming message from the WebSocket.
+     */
+    handleMessage(data: string): void;
+    /**
+     * Handle a REQ message to create/update a subscription.
+     */
+    private handleReq;
+    /**
+     * Handle an EVENT message to store an event.
+     * Accepts events for free (no payment required).
+     */
+    private handleEvent;
+    /**
+     * Handle a CLOSE message to terminate a subscription.
+     */
+    private handleClose;
+    /**
+     * Push a new event to all matching subscriptions on this connection.
+     * Used when events are stored outside the WebSocket flow (e.g., via ILP).
+     */
+    notifyNewEvent(event: NostrEvent): void;
+    /**
+     * Clean up all subscriptions for this connection.
+     */
+    cleanup(): void;
+    /**
+     * Get the number of active subscriptions.
+     */
+    getSubscriptionCount(): number;
+    private sendEvent;
+    private sendEose;
+    private sendOk;
+    private sendNotice;
+    private send;
+}
+
+/**
+ * A NIP-01 compliant Nostr relay WebSocket server.
+ * Handles client connections and routes messages to ConnectionHandlers.
+ */
+declare class NostrRelayServer {
+    private eventStore;
+    private wss;
+    private handlers;
+    private config;
+    constructor(config: Partial<RelayConfig> | undefined, eventStore: EventStore);
+    /**
+     * Start the WebSocket server.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the WebSocket server and close all connections.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the port the server is listening on.
+     * Returns 0 if the server is not started.
+     */
+    getPort(): number;
+    /**
+     * Get the number of connected clients.
+     */
+    getClientCount(): number;
+    /**
+     * 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.
+     */
+    broadcastEvent(event: NostrEvent): void;
+    private handleConnection;
+}
+
+/**
+ * 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.
+ *
+ * Environment variables:
+ * - RELAY_BASE_PRICE_PER_BYTE: Base price per byte (default: "10")
+ * - RELAY_KIND_OVERRIDES: JSON object mapping kind to price (optional)
+ *   Format: {"1":"5","30023":"100"}
+ *
+ * @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;
+    /** @deprecated Connector computes fulfillment from SHA256(toon_bytes). Will be removed in a future version. */
+    fulfillment?: string;
+    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.
+ */
+declare class BlsError extends RelayError {
+    constructor(message: string, code?: string);
+}
+
+/**
+ * Generate a fulfillment from an event ID.
+ * The fulfillment is SHA-256(eventId) encoded as base64.
+ *
+ * Note: The sender must use SHA256(SHA256(eventId)) as the condition
+ * in their ILP Prepare packet.
+ *
+ * @deprecated Connector computes fulfillment from SHA256(toon_bytes). BLS should not generate fulfillment.
+ */
+declare function generateFulfillment(eventId: string): 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;
+}
+
+/**
+ * Subscribe to upstream relays and propagate events into the local EventStore.
+ *
+ * Follows the same lifecycle pattern as core's discovery tracker and SocialPeerDiscovery:
+ * - Accept optional SimplePool for testability
+ * - start() returns { unsubscribe } cleanup handle
+ * - isUnsubscribed guard prevents processing after teardown
+ */
+
+/**
+ * Configuration for RelaySubscriber.
+ */
+interface RelaySubscriberConfig {
+    /** Upstream relay URLs to subscribe to */
+    relayUrls: string[];
+    /** Nostr filter for which events to pull (e.g. kinds, authors) */
+    filter: Filter;
+    /** Verify event signatures before storing (default: true) */
+    verifySignatures?: boolean;
+}
+/**
+ * Subscribes to upstream Nostr relays and stores received events
+ * in the local EventStore. Useful for relay-to-relay event propagation.
+ */
+declare class RelaySubscriber {
+    private readonly config;
+    private readonly eventStore;
+    private readonly pool;
+    private started;
+    /**
+     * @param config - Subscriber configuration
+     * @param eventStore - Storage backend to write events into
+     * @param pool - Optional SimplePool instance (creates new one if not provided)
+     */
+    constructor(config: RelaySubscriberConfig, eventStore: EventStore, pool?: SimplePool);
+    /**
+     * Start subscribing to the configured upstream relays.
+     *
+     * @returns Handle with unsubscribe() to stop the subscription
+     * @throws Error if already started
+     */
+    start(): {
+        unsubscribe: () => void;
+    };
+}
+
+/**
+ * @toon-protocol/relay
+ *
+ * ILP-gated Nostr relay with Business Logic Server.
+ */
+declare const VERSION = "0.1.0";
+
+export { type BlsConfig, BlsError, BusinessLogicServer, ConnectionHandler, DEFAULT_RELAY_CONFIG, type EventStore, type HandlePacketAcceptResponse, type HandlePacketRejectResponse, type HandlePacketRequest, type HandlePacketResponse, ILP_ERROR_CODES, InMemoryEventStore, NostrRelayServer, type PricingConfig, PricingError, PricingService, type RelayConfig, RelayError, RelaySubscriber, type RelaySubscriberConfig, SqliteEventStore, type Subscription, VERSION, generateFulfillment, isValidPubkey, loadPricingConfigFromEnv, loadPricingConfigFromFile, matchFilter };