@toon-protocol/client 0.4.2

package/dist/index.d.ts

@@ -0,0 +1,966 @@
+import * as _toon_protocol_core from '@toon-protocol/core';
+import { IlpPeerInfo, IlpSendResult, IlpClient, ConnectorAdminClient, ConnectorChannelClient, OpenChannelParams, OpenChannelResult, ChannelState } from '@toon-protocol/core';
+import { NostrEvent } from 'nostr-tools/pure';
+import { PrivateKeyAccount } from 'viem/accounts';
+
+/**
+ * Configuration for ToonClient.
+ *
+ * This story implements HTTP mode only. Embedded mode will be added in a future epic.
+ *
+ * @example HTTP Mode (implemented)
+ * ```typescript
+ * const client = new ToonClient({
+ *   connectorUrl: 'http://localhost:8080',
+ *   secretKey,
+ *   ilpInfo: { ilpAddress, btpEndpoint, pubkey },
+ *   toonEncoder: encodeEvent,
+ *   toonDecoder: decodeEvent,
+ * });
+ * ```
+ *
+ * @example Embedded Mode (not yet implemented)
+ * ```typescript
+ * const client = new ToonClient({
+ *   connector: embeddedConnectorInstance,  // Will throw error: "Embedded mode not yet implemented"
+ *   secretKey,
+ *   ilpInfo,
+ *   toonEncoder,
+ *   toonDecoder,
+ * });
+ * ```
+ */
+interface ToonClientConfig {
+    /**
+     * HTTP URL of external connector service.
+     * Required for HTTP mode.
+     * Example: 'http://localhost:8080'
+     */
+    connectorUrl?: string;
+    /**
+     * Embedded connector instance - NOT IMPLEMENTED in this story.
+     * Will throw error: "Embedded mode not yet implemented in ToonClient."
+     * Reserved for future implementation.
+     */
+    connector?: unknown;
+    /**
+     * 32-byte Nostr private key (hex or Uint8Array).
+     * Optional — if omitted, a keypair is auto-generated in applyDefaults().
+     */
+    secretKey?: Uint8Array;
+    /** ILP peer information for this client */
+    ilpInfo: IlpPeerInfo;
+    /** Function to encode Nostr events to TOON binary format */
+    toonEncoder: (event: NostrEvent) => Uint8Array;
+    /** Function to decode TOON binary format to Nostr events */
+    toonDecoder: (bytes: Uint8Array) => NostrEvent;
+    /**
+     * EVM private key for signing balance proofs and on-chain transactions.
+     *
+     * By default, this is derived from `secretKey` — both Nostr and EVM use
+     * secp256k1, so a single key provides both identities (matching the SDK's
+     * `fromMnemonic()`/`fromSecretKey()` behavior).
+     *
+     * Only set this if you need a *different* EVM key than your Nostr key
+     * (e.g., hardware wallet, custodial key, or legacy key separation).
+     */
+    evmPrivateKey?: string | Uint8Array;
+    /** Supported settlement chain identifiers (e.g., ["evm:anvil:31337"]) */
+    supportedChains?: string[];
+    /** Maps chain identifier to EVM settlement address */
+    settlementAddresses?: Record<string, string>;
+    /** Maps chain identifier to preferred token contract address */
+    preferredTokens?: Record<string, string>;
+    /** Maps chain identifier to TokenNetwork contract address (EVM only) */
+    tokenNetworks?: Record<string, string>;
+    /** BTP WebSocket URL (e.g., "ws://localhost:3000") */
+    btpUrl?: string;
+    /** Auth token for BTP handshake */
+    btpAuthToken?: string;
+    /** Peer ID for BTP connection (used in connector env var BTP_PEER_{ID}_SECRET) */
+    btpPeerId?: string;
+    /**
+     * ILP destination address for event publishing.
+     * Defaults to the connector's local address (derived from connectorUrl host).
+     * For multi-hop routing, set this to the target node's ILP address.
+     * Examples:
+     * - 'g.toon.genesis' - Publish to genesis node
+     * - 'g.toon.peer1' - Publish to peer1 node
+     */
+    destinationAddress?: string;
+    /** Maps chain identifier to RPC URL (e.g., {"evm:anvil:31337": "http://localhost:8545"}) */
+    chainRpcUrls?: Record<string, string>;
+    /** Amount to deposit when opening channel (default: "0") */
+    initialDeposit?: string;
+    /** Challenge period in seconds (default: 86400) */
+    settlementTimeout?: number;
+    /** File path for persisting payment channel nonce/amount state across restarts */
+    channelStorePath?: string;
+    /** Nostr relay URL for peer discovery. Default: 'ws://localhost:7100' */
+    relayUrl?: string;
+    /**
+     * Known peers to bootstrap with.
+     * If provided, these peers will be used for initial bootstrap.
+     * DiscoveryTracker will discover additional peers from kind:10032 events after bootstrap.
+     */
+    knownPeers?: {
+        pubkey: string;
+        relayUrl: string;
+        btpEndpoint?: string;
+    }[];
+    /** Query timeout in milliseconds. Default: 30000 */
+    queryTimeout?: number;
+    /** Maximum number of retries for failed operations. Default: 3 */
+    maxRetries?: number;
+    /** Delay between retries in milliseconds. Default: 1000 */
+    retryDelay?: number;
+}
+/**
+ * Result returned by ToonClient.start()
+ */
+interface ToonStartResult {
+    /** Number of peers discovered during bootstrap */
+    peersDiscovered: number;
+    /** Mode the client is running in */
+    mode: 'http' | 'embedded';
+}
+/**
+ * Result returned by ToonClient.publishEvent()
+ */
+interface PublishEventResult {
+    /** Whether the event was successfully published */
+    success: boolean;
+    /** ID of the published event */
+    eventId?: string;
+    /** ILP fulfillment from the relay (proof of payment) */
+    fulfillment?: string;
+    /** Error message if success is false */
+    error?: string;
+}
+/**
+ * Parameters for signing a balance proof.
+ */
+interface BalanceProofParams {
+    /** Payment channel identifier */
+    channelId: string;
+    /** Monotonically increasing nonce */
+    nonce: number;
+    /** Cumulative amount transferred */
+    transferredAmount: bigint;
+    /** Amount locked in pending transfers */
+    lockedAmount: bigint;
+    /** Merkle root of pending lock hashes */
+    locksRoot: string;
+}
+/**
+ * A signed balance proof with EIP-712 signature.
+ */
+interface SignedBalanceProof extends BalanceProofParams {
+    /** EIP-712 signature */
+    signature: string;
+    /** Address of the signer */
+    signerAddress: string;
+}
+
+/**
+ * ToonClient - High-level client for interacting with TOON network.
+ *
+ * This story implements HTTP mode only. Embedded mode will be added in a future epic.
+ *
+ * @example HTTP Mode
+ * ```typescript
+ * import { ToonClient } from '@toon-protocol/client';
+ * import { generateSecretKey, getPublicKey } from 'nostr-tools/pure';
+ * import { encodeEvent, decodeEvent } from '@toon-protocol/relay';
+ *
+ * const secretKey = generateSecretKey();
+ * const pubkey = getPublicKey(secretKey);
+ *
+ * const client = new ToonClient({
+ *   connectorUrl: 'http://localhost:8080',
+ *   secretKey,
+ *   ilpInfo: {
+ *     pubkey,
+ *     ilpAddress: `g.toon.${pubkey.slice(0, 8)}`,
+ *     btpEndpoint: 'ws://localhost:3000',
+ *   },
+ *   toonEncoder: encodeEvent,
+ *   toonDecoder: decodeEvent,
+ * });
+ *
+ * await client.start(); // Bootstrap peers, start monitoring
+ *
+ * // Publish to default destination (from config)
+ * await client.publishEvent(signedEvent);
+ *
+ * // Publish to specific destination (multi-hop routing)
+ * await client.publishEvent(signedEvent, { destination: 'g.toon.peer1' });
+ *
+ * await client.stop(); // Cleanup
+ * ```
+ */
+declare class ToonClient {
+    private readonly config;
+    private state;
+    private readonly evmSigner?;
+    private channelManager?;
+    /**
+     * Creates a new ToonClient instance.
+     *
+     * @param config - Client configuration
+     * @throws {ValidationError} If configuration is invalid
+     */
+    constructor(config: ToonClientConfig);
+    /**
+     * Generates a new Nostr keypair.
+     *
+     * @returns Object with secretKey (Uint8Array) and pubkey (hex string)
+     */
+    static generateKeypair(): {
+        secretKey: Uint8Array;
+        pubkey: string;
+    };
+    /**
+     * Gets the Nostr public key derived from the secret key.
+     * Works before start() is called.
+     */
+    getPublicKey(): string;
+    /**
+     * Gets the EVM address derived from the Nostr secret key (or explicit evmPrivateKey override).
+     */
+    getEvmAddress(): string | undefined;
+    /**
+     * Starts the ToonClient.
+     *
+     * This will:
+     * 1. Initialize HTTP mode components (runtime client, admin client, bootstrap, monitor)
+     * 2. Bootstrap the network (discover peers, register, and open channels)
+     * 3. Start monitoring relay for new peers (kind:10032 events)
+     *
+     * @returns Result with number of peers discovered and mode
+     * @throws {ToonClientError} If client is already started
+     * @throws {ToonClientError} If initialization fails
+     */
+    start(): Promise<ToonStartResult>;
+    /**
+     * Publishes a Nostr event to the relay via ILP payment.
+     *
+     * The event must already be finalized (signed with id, pubkey, sig).
+     *
+     * @param event - Signed Nostr event to publish
+     * @param options - Optional options including destination and signed balance proof claim
+     * @returns Result with success status, event ID, and fulfillment
+     * @throws {ToonClientError} If client is not started
+     * @throws {ToonClientError} If event publishing fails
+     */
+    publishEvent(event: NostrEvent, options?: {
+        destination?: string;
+        claim?: SignedBalanceProof;
+    }): Promise<PublishEventResult>;
+    /**
+     * Signs a balance proof for the given channel with the specified amount.
+     * Delegates to ChannelManager which auto-increments nonce and tracks cumulative amount.
+     *
+     * @param channelId - Payment channel identifier
+     * @param amount - Additional amount to add to cumulative transferred amount
+     * @returns Signed balance proof
+     * @throws {ToonClientError} If no EVM signer configured or channel not tracked
+     */
+    signBalanceProof(channelId: string, amount: bigint): Promise<SignedBalanceProof>;
+    /**
+     * Gets list of tracked payment channel IDs.
+     */
+    getTrackedChannels(): string[];
+    /**
+     * Sends an ILP payment, optionally with a balance proof claim via BTP.
+     *
+     * @param params - Payment parameters
+     * @returns ILP send result
+     * @throws {ToonClientError} If client is not started
+     */
+    sendPayment(params: {
+        destination: string;
+        amount: string;
+        data?: string;
+        claim?: SignedBalanceProof;
+    }): Promise<IlpSendResult>;
+    /**
+     * Stops the ToonClient and cleans up resources.
+     *
+     * This will:
+     * 1. Disconnect BTP client if connected
+     * 2. Clear internal state
+     *
+     * @throws {ToonClientError} If client is not started
+     */
+    stop(): Promise<void>;
+    /**
+     * Returns true if the client is currently started.
+     */
+    isStarted(): boolean;
+    /**
+     * Gets the number of peers discovered during bootstrap.
+     *
+     * @returns Number of peers discovered
+     * @throws {ToonClientError} If client is not started
+     */
+    getPeersCount(): number;
+    /**
+     * Gets the list of peers discovered by the relay monitor.
+     *
+     * @returns Array of discovered peer objects
+     * @throws {ToonClientError} If client is not started
+     */
+    getDiscoveredPeers(): _toon_protocol_core.DiscoveredPeer[];
+}
+
+/**
+ * Base error class for all TOON client errors.
+ */
+declare class ToonClientError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string, cause?: Error);
+}
+/**
+ * Network error for connection failures (ECONNREFUSED, ETIMEDOUT).
+ * These errors trigger retry logic with exponential backoff.
+ */
+declare class NetworkError extends ToonClientError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Connector error for 5xx server errors.
+ * These errors indicate the connector is unavailable or malfunctioning.
+ */
+declare class ConnectorError extends ToonClientError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Validation error for invalid input parameters.
+ * These errors are thrown before making any HTTP requests.
+ */
+declare class ValidationError extends ToonClientError {
+    constructor(message: string, cause?: Error);
+}
+
+/**
+ * Configuration options for HttpRuntimeClient.
+ */
+interface HttpRuntimeClientConfig {
+    /** Connector runtime API base URL (e.g., 'http://localhost:8080') */
+    connectorUrl: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum retry attempts for network failures (default: 3) */
+    maxRetries?: number;
+    /** Initial retry delay in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** HTTP client implementation (for testing) */
+    httpClient?: typeof fetch;
+}
+/**
+ * HTTP client for sending ILP packets to an external connector runtime API.
+ *
+ * Implements the IlpClient interface for use with TOON agents
+ * that need to send ILP packets without embedding a full connector.
+ *
+ * Features:
+ * - Request validation (destination, amount, data)
+ * - Retry logic with exponential backoff for transient network failures
+ * - Typed error handling (NetworkError, ConnectorError, ValidationError)
+ * - Connection pooling and keep-alive (via Node.js fetch)
+ *
+ * @example
+ * ```typescript
+ * const client = new HttpRuntimeClient({
+ *   connectorUrl: 'http://localhost:8080'
+ * });
+ *
+ * const result = await client.sendIlpPacket({
+ *   destination: 'g.toon.alice',
+ *   amount: '1000',
+ *   data: 'base64EncodedToonData==',
+ * });
+ *
+ * if (result.accepted) {
+ *   console.log('Payment accepted:', result.fulfillment);
+ * } else {
+ *   console.error('Payment rejected:', result.code, result.message);
+ * }
+ * ```
+ */
+declare class HttpRuntimeClient implements IlpClient {
+    private readonly connectorUrl;
+    private readonly timeout;
+    private readonly retryConfig;
+    private readonly httpClient;
+    constructor(config: HttpRuntimeClientConfig);
+    /**
+     * Send an ILP packet to the connector runtime API.
+     *
+     * @param params - ILP packet parameters
+     * @returns ILP packet response with acceptance status
+     * @throws {ValidationError} If request parameters are invalid
+     * @throws {NetworkError} If network connection fails after retries
+     * @throws {ConnectorError} If connector returns 5xx server error
+     */
+    sendIlpPacket(params: {
+        destination: string;
+        amount: string;
+        data: string;
+        timeout?: number;
+    }): Promise<IlpSendResult>;
+    /**
+     * Validate ILP packet request parameters.
+     *
+     * @throws {ValidationError} If any parameter is invalid
+     */
+    private validateRequest;
+    /**
+     * Send HTTP POST request to connector runtime API.
+     *
+     * @throws {NetworkError} On connection failures (ECONNREFUSED, ETIMEDOUT)
+     * @throws {ConnectorError} On 5xx server errors
+     * @returns IlpSendResult with acceptance status
+     */
+    private sendHttpRequest;
+}
+
+/**
+ * Configuration for HttpConnectorAdmin.
+ */
+interface HttpConnectorAdminConfig {
+    /** Admin API base URL (e.g., 'http://localhost:8081') */
+    adminUrl: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum retry attempts for network failures (default: 3) */
+    maxRetries?: number;
+    /** Initial retry delay in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** HTTP client for testing (default: global fetch) */
+    httpClient?: typeof fetch;
+}
+/**
+ * Result of a bulk peer operation.
+ */
+interface PeerOperationResult {
+    /** Peer ID that was operated on */
+    peerId: string;
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Error that occurred (if failed) */
+    error?: Error;
+}
+/**
+ * HTTP-based connector admin client for managing ILP peers via REST API.
+ *
+ * Implements the ConnectorAdminClient interface using HTTP requests to the
+ * connector's admin API (typically port 8081).
+ *
+ * @example
+ * ```typescript
+ * // Embedded mode (DirectConnectorAdmin)
+ * const adminClient = new DirectConnectorAdmin(connectorNode);
+ *
+ * // HTTP mode (HttpConnectorAdmin)
+ * const adminClient = new HttpConnectorAdmin({
+ *   adminUrl: 'http://localhost:8081'
+ * });
+ *
+ * // Add peer
+ * await adminClient.addPeer({
+ *   id: 'nostr-abc123',
+ *   url: 'btp+ws://alice.example.com:3000',
+ *   authToken: 'secret-token',
+ *   routes: [{ prefix: 'g.toon.alice' }]
+ * });
+ *
+ * // Remove peer
+ * await adminClient.removePeer('nostr-abc123');
+ * ```
+ *
+ * @throws {ValidationError} Input validation failed (before HTTP request)
+ * @throws {NetworkError} Connection failed (ECONNREFUSED, ETIMEDOUT)
+ * @throws {UnauthorizedError} Admin API returned 401 (missing/invalid auth)
+ * @throws {PeerAlreadyExistsError} Admin API returned 409 (duplicate peer)
+ * @throws {PeerNotFoundError} Admin API returned 404 (peer not found)
+ * @throws {ConnectorError} Admin API returned 5xx (server error)
+ */
+declare class HttpConnectorAdmin implements ConnectorAdminClient {
+    private readonly adminUrl;
+    private readonly timeout;
+    private readonly retryConfig;
+    private readonly httpClient;
+    constructor(config: HttpConnectorAdminConfig);
+    /**
+     * Add a peer to the connector via the admin API.
+     *
+     * Validates peer config parameters and sends HTTP POST to /admin/peers.
+     *
+     * @param config - Peer configuration
+     * @param config.id - Unique peer identifier (non-empty string)
+     * @param config.url - BTP WebSocket URL (must start with 'btp+ws://' or 'btp+wss://')
+     * @param config.authToken - Authentication token (non-empty string)
+     * @param config.routes - Optional routing table entries
+     * @param config.settlement - Optional settlement configuration
+     *
+     * @throws {ValidationError} Invalid peer config (missing id, invalid url, etc.)
+     * @throws {PeerAlreadyExistsError} Peer with same ID already exists (409 Conflict)
+     * @throws {UnauthorizedError} Admin API authentication failed (401)
+     * @throws {NetworkError} Connection to admin API failed
+     * @throws {ConnectorError} Admin API server error (5xx)
+     */
+    addPeer(config: {
+        id: string;
+        url: string;
+        authToken: string;
+        routes?: {
+            prefix: string;
+            priority?: number;
+        }[];
+        settlement?: {
+            preference: string;
+            evmAddress?: string;
+            tokenAddress?: string;
+            tokenNetworkAddress?: string;
+            chainId?: number;
+            channelId?: string;
+            initialDeposit?: string;
+        };
+    }): Promise<void>;
+    /**
+     * Remove a peer from the connector via the admin API.
+     *
+     * Sends HTTP DELETE to /admin/peers/:id.
+     *
+     * @param peerId - Unique peer identifier to remove (non-empty string)
+     *
+     * @throws {ValidationError} Invalid peerId (empty string)
+     * @throws {PeerNotFoundError} Peer does not exist (404 Not Found)
+     * @throws {UnauthorizedError} Admin API authentication failed (401)
+     * @throws {NetworkError} Connection to admin API failed
+     * @throws {ConnectorError} Admin API server error (5xx)
+     */
+    removePeer(peerId: string): Promise<void>;
+    /**
+     * Add multiple peers in parallel for efficient bootstrapping.
+     *
+     * Uses Promise.allSettled() to execute peer additions concurrently,
+     * returning results for each operation regardless of individual failures.
+     *
+     * @param configs - Array of peer configurations to add
+     * @returns Array of results indicating success/failure for each peer
+     *
+     * @example
+     * ```typescript
+     * const results = await admin.addPeers([
+     *   { id: 'peer1', url: 'btp+ws://...', authToken: 'token1' },
+     *   { id: 'peer2', url: 'btp+ws://...', authToken: 'token2' },
+     * ]);
+     *
+     * results.forEach(result => {
+     *   if (result.success) {
+     *     console.log(`Added peer: ${result.peerId}`);
+     *   } else {
+     *     console.error(`Failed to add ${result.peerId}:`, result.error);
+     *   }
+     * });
+     * ```
+     */
+    addPeers(configs: {
+        id: string;
+        url: string;
+        authToken: string;
+        routes?: {
+            prefix: string;
+            priority?: number;
+        }[];
+        settlement?: {
+            preference: string;
+            evmAddress?: string;
+            tokenAddress?: string;
+            tokenNetworkAddress?: string;
+            chainId?: number;
+            channelId?: string;
+            initialDeposit?: string;
+        };
+    }[]): Promise<PeerOperationResult[]>;
+    /**
+     * Remove multiple peers in parallel.
+     *
+     * Uses Promise.allSettled() to execute peer removals concurrently,
+     * returning results for each operation regardless of individual failures.
+     *
+     * @param peerIds - Array of peer IDs to remove
+     * @returns Array of results indicating success/failure for each peer
+     *
+     * @example
+     * ```typescript
+     * const results = await admin.removePeers(['peer1', 'peer2', 'peer3']);
+     *
+     * const succeeded = results.filter(r => r.success).length;
+     * console.log(`Removed ${succeeded}/${results.length} peers`);
+     * ```
+     */
+    removePeers(peerIds: string[]): Promise<PeerOperationResult[]>;
+    /**
+     * Send HTTP POST request to add a peer.
+     * Separated for retry logic wrapping.
+     */
+    private sendAddPeerRequest;
+    /**
+     * Send HTTP DELETE request to remove a peer.
+     * Separated for retry logic wrapping.
+     */
+    private sendRemovePeerRequest;
+    /**
+     * Handle network errors from HTTP requests.
+     *
+     * Converts connection failures, timeouts, and unknown errors to NetworkError.
+     * Re-throws existing ToonClientError instances.
+     *
+     * @param error - Error thrown by HTTP client
+     * @param url - Request URL (for error messages)
+     * @param operation - Operation name (for error messages)
+     * @throws {NetworkError} Network connection or timeout error
+     */
+    private handleNetworkError;
+    /**
+     * Handle HTTP error responses from the admin API.
+     *
+     * Converts HTTP status codes to appropriate error types.
+     *
+     * @param response - HTTP response from admin API
+     * @param endpoint - Endpoint being called (for error messages)
+     * @param peerId - Peer ID (for error messages)
+     * @throws {UnauthorizedError} 401 Unauthorized
+     * @throws {PeerNotFoundError} 404 Not Found
+     * @throws {PeerAlreadyExistsError} 409 Conflict
+     * @throws {ConnectorError} 5xx Server Error
+     */
+    private handleErrorResponse;
+}
+
+/**
+ * EVM claim message for BTP protocol data.
+ * Matches @toon-protocol/connector's EVMClaimMessage interface.
+ */
+interface EVMClaimMessage {
+    blockchain: 'evm';
+    senderId: string;
+    channelId: string;
+    nonce: number;
+    transferredAmount: string;
+    lockedAmount: string;
+    locksRoot: string;
+    signature: string;
+    signerAddress: string;
+}
+/**
+ * EVM signer for EIP-712 balance proofs and on-chain transactions.
+ *
+ * Encapsulates the private key — no getPrivateKey() method is exposed.
+ */
+declare class EvmSigner {
+    private readonly _account;
+    /**
+     * @param privateKey - EVM private key as hex string (with or without 0x prefix) or Uint8Array
+     */
+    constructor(privateKey: string | Uint8Array);
+    /** Derived 0x EVM address */
+    get address(): string;
+    /** Viem PrivateKeyAccount — usable with walletClient for on-chain transactions */
+    get account(): PrivateKeyAccount;
+    /**
+     * Signs a balance proof using EIP-712 typed data.
+     *
+     * @param params - Balance proof parameters plus chain context
+     * @returns Signed balance proof with signature
+     */
+    signBalanceProof(params: BalanceProofParams & {
+        chainId: number;
+        tokenNetworkAddress: string;
+    }): Promise<SignedBalanceProof>;
+    /**
+     * Builds an EVMClaimMessage from a signed balance proof.
+     * Static so it can be called without an EvmSigner instance.
+     *
+     * @param proof - Signed balance proof
+     * @param senderId - Nostr pubkey or identifier of the sender
+     * @returns EVMClaimMessage compatible with BTP_CLAIM_PROTOCOL
+     */
+    static buildClaimMessage(proof: SignedBalanceProof, senderId: string): EVMClaimMessage;
+}
+
+/** Pino-compatible logger interface */
+interface ConsoleLogger {
+    level: string;
+    silent: (...args: unknown[]) => void;
+    info: typeof console.info;
+    warn: typeof console.warn;
+    error: typeof console.error;
+    debug: typeof console.debug;
+    trace: typeof console.debug;
+    fatal: typeof console.error;
+    child: () => ConsoleLogger;
+}
+interface BtpRuntimeClientConfig {
+    btpUrl: string;
+    peerId: string;
+    authToken: string;
+    logger?: ConsoleLogger;
+    /** Max reconnection attempts on send failure (default: 3) */
+    maxRetries?: number;
+    /** Delay between reconnection attempts in ms (default: 1000) */
+    retryDelay?: number;
+}
+/**
+ * BTP transport implementing IlpClient.
+ * Wraps BTPClient from @toon-protocol/connector with auto-reconnect on connection loss.
+ */
+declare class BtpRuntimeClient implements IlpClient {
+    private btpClient;
+    private readonly config;
+    private _isConnected;
+    private readonly logger;
+    constructor(config: BtpRuntimeClientConfig);
+    /**
+     * Connects to the BTP peer via WebSocket.
+     */
+    connect(): Promise<void>;
+    /**
+     * Attempts to reconnect by creating a fresh BTPClient and connecting.
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Disconnects from the BTP peer.
+     */
+    disconnect(): Promise<void>;
+    get isConnected(): boolean;
+    /**
+     * Sends an ILP packet via BTP with auto-reconnect on connection errors.
+     * Satisfies IlpClient interface.
+     */
+    sendIlpPacket(params: {
+        destination: string;
+        amount: string;
+        data: string;
+        timeout?: number;
+    }): Promise<IlpSendResult>;
+    /**
+     * Sends a balance proof claim via BTP protocol data, then sends an ILP packet.
+     * Auto-reconnects on connection errors.
+     */
+    sendIlpPacketWithClaim(params: {
+        destination: string;
+        amount: string;
+        data: string;
+        timeout?: number;
+    }, claim: EVMClaimMessage): Promise<IlpSendResult>;
+    /**
+     * Single-attempt ILP packet send. Reconnects if not connected.
+     */
+    private _sendIlpPacketOnce;
+    /**
+     * Single-attempt claim + ILP packet send. Reconnects if not connected.
+     */
+    private _sendIlpPacketWithClaimOnce;
+}
+
+interface OnChainChannelClientConfig {
+    evmSigner: EvmSigner;
+    chainRpcUrls: Record<string, string>;
+}
+/**
+ * Implements ConnectorChannelClient using viem for direct on-chain
+ * interaction with TokenNetwork smart contract.
+ *
+ * Fully non-custodial — the client deposits its own funds on-chain.
+ */
+declare class OnChainChannelClient implements ConnectorChannelClient {
+    private readonly evmSigner;
+    private readonly chainRpcUrls;
+    private readonly channelContext;
+    constructor(config: OnChainChannelClientConfig);
+    /**
+     * Parse chain identifier to extract chainId.
+     * Format: "evm:{network}:{chainId}" e.g., "evm:anvil:31337"
+     */
+    private parseChainId;
+    /**
+     * Create viem clients for a given chain.
+     */
+    private createClients;
+    /**
+     * Opens a new payment channel on-chain.
+     *
+     * 1. Approve token spend if needed
+     * 2. Call TokenNetwork.openChannel()
+     * 3. Extract channelId from ChannelOpened event
+     * 4. Deposit initial funds if specified
+     */
+    openChannel(params: OpenChannelParams): Promise<OpenChannelResult>;
+    /**
+     * Gets the current state of a payment channel from on-chain data.
+     */
+    getChannelState(channelId: string): Promise<ChannelState>;
+}
+
+interface ChannelStoreEntry {
+    nonce: number;
+    cumulativeAmount: bigint;
+}
+/**
+ * Persistence interface for payment channel nonce/amount state.
+ */
+interface ChannelStore {
+    save(channelId: string, tracking: ChannelStoreEntry): void;
+    load(channelId: string): ChannelStoreEntry | undefined;
+    list(): string[];
+    delete(channelId: string): void;
+}
+
+/**
+ * Local nonce tracking and claim signing.
+ *
+ * Does NOT make any network calls — it only manages state
+ * and delegates signing to EvmSigner.
+ */
+declare class ChannelManager {
+    private readonly evmSigner;
+    private readonly channels;
+    private readonly store?;
+    constructor(evmSigner: EvmSigner, store?: ChannelStore);
+    /**
+     * Start tracking a channel.
+     * Called after bootstrap returns a channelId.
+     *
+     * @param channelId - Payment channel identifier
+     * @param initialNonce - Starting nonce (default: 0)
+     * @param initialAmount - Starting cumulative amount (default: 0n)
+     */
+    trackChannel(channelId: string, initialNonce?: number, initialAmount?: bigint): void;
+    /**
+     * Signs a balance proof for the given channel.
+     * Auto-increments nonce and adds to cumulative amount.
+     *
+     * @param channelId - Payment channel identifier
+     * @param additionalAmount - Amount to add to cumulative transferred amount
+     * @returns Signed balance proof
+     * @throws Error if channel is not being tracked
+     */
+    signBalanceProof(channelId: string, additionalAmount: bigint): Promise<SignedBalanceProof>;
+    /**
+     * Gets the current nonce for a tracked channel.
+     */
+    getNonce(channelId: string): number;
+    /**
+     * Gets the cumulative transferred amount for a tracked channel.
+     */
+    getCumulativeAmount(channelId: string): bigint;
+    /**
+     * Gets all tracked channel IDs.
+     */
+    getTrackedChannels(): string[];
+    /**
+     * Returns true if the channel is being tracked.
+     */
+    isTracking(channelId: string): boolean;
+}
+
+/**
+ * Configuration options for retry behavior with exponential backoff.
+ */
+interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries: number;
+    /** Initial delay in milliseconds between retries (default: 1000) */
+    retryDelay: number;
+    /** Use exponential backoff for delays (default: true) */
+    exponentialBackoff?: boolean;
+    /** Maximum delay cap in milliseconds (default: 30000) */
+    maxDelay?: number;
+    /** Custom predicate to determine if an error should trigger a retry */
+    shouldRetry?: (error: Error) => boolean;
+}
+/**
+ * Executes an async operation with retry logic and exponential backoff.
+ *
+ * @param operation - The async function to execute
+ * @param options - Retry configuration options
+ * @returns The result of the successful operation
+ * @throws The last error if all retries are exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   async () => fetchData(),
+ *   {
+ *     maxRetries: 3,
+ *     retryDelay: 1000,
+ *     shouldRetry: (err) => err.name === 'NetworkError'
+ *   }
+ * );
+ * ```
+ */
+declare function withRetry<T>(operation: () => Promise<T>, options: RetryOptions): Promise<T>;
+
+/**
+ * Settlement info produced by buildSettlementInfo().
+ * Extends the core SettlementConfig shape with ilpAddress for client use.
+ */
+interface ClientSettlementInfo {
+    ilpAddress?: string;
+    supportedChains?: string[];
+    settlementAddresses?: Record<string, string>;
+    preferredTokens?: Record<string, string>;
+    tokenNetworks?: Record<string, string>;
+}
+/**
+ * Validates ToonClient configuration.
+ *
+ * This story implements HTTP mode only. Embedded mode validation will be added in a future epic.
+ *
+ * @throws {ValidationError} If configuration is invalid
+ */
+declare function validateConfig(config: ToonClientConfig): void;
+/**
+ * The resolved config type after defaults are applied.
+ * secretKey is guaranteed to be present (auto-generated if omitted).
+ */
+type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'evmPrivateKey' | 'supportedChains' | 'settlementAddresses' | 'preferredTokens' | 'tokenNetworks' | 'btpUrl' | 'btpAuthToken' | 'btpPeerId' | 'chainRpcUrls' | 'initialDeposit' | 'settlementTimeout' | 'channelStorePath' | 'knownPeers' | 'destinationAddress'>> & {
+    connector?: unknown;
+    /** Always present after applyDefaults() — derived from secretKey if not explicitly provided */
+    evmPrivateKey: string | Uint8Array;
+    supportedChains?: string[];
+    settlementAddresses?: Record<string, string>;
+    preferredTokens?: Record<string, string>;
+    tokenNetworks?: Record<string, string>;
+    btpUrl?: string;
+    btpAuthToken?: string;
+    btpPeerId?: string;
+    chainRpcUrls?: Record<string, string>;
+    initialDeposit?: string;
+    settlementTimeout?: number;
+    channelStorePath?: string;
+    knownPeers?: {
+        pubkey: string;
+        relayUrl: string;
+        btpEndpoint?: string;
+    }[];
+    destinationAddress: string;
+};
+/**
+ * Applies default values to optional configuration fields.
+ * Auto-generates a Nostr keypair when secretKey is omitted.
+ * Derives btpUrl from connectorUrl when not provided.
+ */
+declare function applyDefaults(config: ToonClientConfig): ResolvedConfig;
+/**
+ * Builds SettlementConfig from client config.
+ * Returns undefined if no settlement-related config is present.
+ */
+declare function buildSettlementInfo(config: ToonClientConfig): ClientSettlementInfo | undefined;
+
+export { type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, ChannelManager, ConnectorError, type EVMClaimMessage, EvmSigner, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpRuntimeClient, type HttpRuntimeClientConfig, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type PublishEventResult, type RetryOptions, type SignedBalanceProof, ToonClient, type ToonClientConfig, ToonClientError, type ToonStartResult, ValidationError, applyDefaults, buildSettlementInfo, validateConfig, withRetry };