@toon-protocol/relay 1.3.1 → 1.3.3

package/dist/index.d.ts

@@ -1,16 +1,22 @@
 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 } from 'hono';
+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';
 
 /**
  * Configuration options for the Nostr relay.
  */
-interface RelayConfig {
+interface RelayServerConfig {
     /** Port to listen on (default: 7000) */
     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) */
     maxConnections?: number;
     /** Maximum subscriptions per connection (default: 20) */
@@ -23,7 +29,7 @@ interface RelayConfig {
 /**
  * Default relay configuration values.
  */
-declare const DEFAULT_RELAY_CONFIG: Required<RelayConfig>;
+declare const DEFAULT_RELAY_CONFIG: Required<RelayServerConfig>;
 
 /**
  * Interface for event storage backends.
@@ -142,7 +148,7 @@ declare class ConnectionHandler {
     private eventStore;
     private subscriptions;
     private config;
-    constructor(ws: WebSocket, eventStore: EventStore, config?: Partial<RelayConfig>);
+    constructor(ws: WebSocket, eventStore: EventStore, config?: Partial<RelayServerConfig>);
     /**
      * Handle an incoming message from the WebSocket.
      */
@@ -192,7 +198,7 @@ declare class NostrRelayServer {
     private wss;
     private handlers;
     private config;
-    constructor(config: Partial<RelayConfig> | undefined, eventStore: EventStore);
+    constructor(config: Partial<RelayServerConfig> | undefined, eventStore: EventStore);
     /**
      * Start the WebSocket server.
      */
@@ -450,6 +456,912 @@ 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:
+ *
+ *   Identity -> Verification -> Pricing -> HandlerRegistry -> BLS + Relay + Bootstrap
+ *
+ * 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.
+ *
+ * ## Deployment Modes
+ *
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+interface RelayConfig {
+    /** 12-word or 24-word BIP-39 mnemonic phrase. */
+    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). */
+    relayPort?: number;
+    /** BLS HTTP server 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.
+     */
+    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). */
+    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.
+     */
+    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;
+}
+/**
+ * Resolved configuration with all defaults applied. All fields are non-optional
+ * (ports, pricing, paths have been filled in).
+ */
+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;
+    }[];
+    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. */
+    isRunning(): boolean;
+    /** 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.
+     *
+     * @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.
+     */
+    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.
+ * Returned by `RelayInstance.subscribe()`.
+ */
+interface RelaySubscription {
+    /** Close the subscription and disconnect from the relay. */
+    close(): void;
+    /** The relay URL this subscription is connected to. */
+    relayUrl: string;
+    /** Whether this subscription is still active. */
+    isActive(): boolean;
+}
+/**
+ * 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.
+ *
+ * @param config - Node configuration. One of `mnemonic`/`secretKey` is required;
+ *   `connector` and `connectorUrl` are mutually exclusive.
+ * @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',
+ * });
+ * ```
+ */
+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).
+ *
+ * The response mirrors kind:10035 service discovery event fields but adds
+ * runtime-only fields that cannot be known at event publish time.
+ *
+ * @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. */
+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.
+ *
+ * The `x402` field is entirely omitted when x402 is disabled (AC #2).
+ * This matches the same omission semantics used in kind:10035 events.
+ *
+ * @param config - Health configuration with runtime state and static config.
+ * @returns The enriched 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.
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * 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
+ *
+ * @module
+ */
+
+/**
+ * Configuration for the x402 publish 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). */
+    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;
+}
+/**
+ * x402 publish handler instance.
+ */
+interface X402Handler {
+    /** Handle a /publish request (both 402 pricing and paid publish). */
+    handlePublish: (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).
+ *
+ * @param config - Handler configuration.
+ * @returns X402Handler with handlePublish 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
  *
@@ -457,4 +1369,4 @@ declare class RelaySubscriber {
  */
 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, isValidPubkey, loadPricingConfigFromEnv, loadPricingConfigFromFile, matchFilter };
+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 };