@toon-protocol/townhouse 0.1.0-rc5

package/dist/index.d.ts

@@ -0,0 +1,1410 @@
+import { EventEmitter } from 'node:events';
+import Docker from 'dockerode';
+import { FastifyBaseLogger, FastifyInstance } from 'fastify';
+import { MillHealthResponse } from '@toon-protocol/mill';
+export { MillHealthResponse } from '@toon-protocol/mill';
+
+/**
+ * Townhouse configuration schema — TypeScript interfaces only.
+ * Runtime validation lives in validator.ts.
+ */
+interface TownNodeConfig {
+    enabled: boolean;
+    /** Nostr relay fee in millisatoshis per event */
+    feePerEvent?: number;
+    /** Docker image override */
+    image?: string;
+}
+interface ChainEndpoint {
+    rpcUrl: string;
+    wsUrl?: string;
+}
+interface MillChainsConfig {
+    evm?: ChainEndpoint;
+    solana?: ChainEndpoint;
+    mina?: ChainEndpoint;
+}
+interface MillNodeConfig {
+    enabled: boolean;
+    /** Swap fee basis points (1 = 0.01%) */
+    feeBasisPoints?: number;
+    /** Docker image override */
+    image?: string;
+    /**
+     * Chain RPC endpoints the mill should swap against (D2). The orchestrator
+     * does not currently forward this directly into MILL_CONFIG_JSON — it
+     * round-trips through YAML so the dashboard and future stories can read it.
+     */
+    chains?: MillChainsConfig;
+    /** Enabled swap pairs, e.g. ['EVM<->SOL']. Informational; D2-introduced. */
+    pairs?: string[];
+}
+interface DvmNodeConfig {
+    enabled: boolean;
+    /** DVM job fee in millisatoshis */
+    feePerJob?: number;
+    /** Per-kind pricing in millisatoshis (key = stringified kind number) */
+    kindPricing?: Record<string, number>;
+    /** Docker image override */
+    image?: string;
+}
+interface NodesConfig {
+    town: TownNodeConfig;
+    mill: MillNodeConfig;
+    dvm: DvmNodeConfig;
+}
+interface WalletConfig {
+    /** Path to encrypted wallet file (no plaintext mnemonic in config) */
+    encrypted_path: string;
+}
+interface ConnectorConfig {
+    /** Docker image for the shared ILP connector */
+    image: string;
+    /** Admin API port */
+    adminPort: number;
+}
+/**
+ * Hidden-service publication config (Story 35.5 of the connector repo).
+ *
+ * When set, the connector boots `@anyone-protocol/anyone-client` in-process,
+ * spawns the `anon` binary, publishes a v3 hidden service, and advertises
+ * its `wss://<addr>.anyone/btp` URL to peers. The keypair lives at `dir`
+ * inside the connector container and persists across restarts when that
+ * path is on a mounted volume.
+ *
+ * Operator surface (this type) is intentionally narrow; the connector's
+ * own config has more knobs (binaryPath, configFilePath) that we omit
+ * here until a real use case demands them.
+ */
+interface HiddenServiceConfig$1 {
+    /** Path inside the connector container for hs_ed25519_secret_key etc. */
+    dir: string;
+    /** Hidden service port — peers dial <addr>.anyone:<port>. */
+    port: number;
+    /**
+     * Optional override of the externalUrl the connector advertises. Default
+     * is `"auto"` — the connector reads `${dir}/hostname` at startup and
+     * builds `wss://<hostname>.anyone/btp` itself.
+     */
+    externalUrl?: string;
+    /** Optional override of the SDK's start-up readiness deadline (ms). */
+    startupTimeoutMs?: number;
+    /** Optional override of the SDK's shutdown deadline (ms). */
+    stopTimeoutMs?: number;
+}
+interface TransportConfig {
+    /** Transport mode: 'ator' for Tor-based, 'direct' for clearnet */
+    mode: 'ator' | 'direct';
+    /** SOCKS5 proxy address when using ator transport */
+    socksProxy?: string;
+    /**
+     * Externally reachable BTP URL. Required when mode='ator' AND
+     * hiddenService is unset (operator runs their own anon binary external
+     * to the connector and is responsible for the URL). Ignored for
+     * mode='direct'. When hiddenService is set and externalUrl is unset,
+     * the generator emits the literal `"auto"` so the connector resolves
+     * the .anyone hostname from disk at startup.
+     */
+    externalUrl?: string;
+    /**
+     * Optional inbound hidden-service publication. When set, the connector
+     * manages its own anon binary and publishes a .anyone hidden service.
+     */
+    hiddenService?: HiddenServiceConfig$1;
+    /**
+     * Town relay hidden service. When set, the orchestrator starts a second
+     * ator sidecar (parallel to any connector HS sidecar) that forwards
+     * inbound HS traffic to the town container's Nostr WebSocket port (7100),
+     * and the town container is configured to advertise the .anyone URL.
+     * Reuses HiddenServiceConfig — same shape as connector HS config.
+     */
+    relayHiddenService?: HiddenServiceConfig$1;
+}
+interface ApiConfig {
+    /** Dashboard/API port */
+    port: number;
+    /** Bind address */
+    host: string;
+}
+interface LoggingConfig {
+    level: 'debug' | 'info' | 'warn' | 'error';
+}
+interface PresetMetadata {
+    /** Preset that produced this config (D2). */
+    name: 'demo';
+    /** Where the chain endpoints came from — leases.json path or 'local-fallback'. */
+    chainEndpointSource: string;
+}
+interface TownhouseConfig {
+    nodes: NodesConfig;
+    wallet: WalletConfig;
+    connector: ConnectorConfig;
+    transport: TransportConfig;
+    api: ApiConfig;
+    logging: LoggingConfig;
+    /** Present only when the config was generated by `init --preset=<name>`. */
+    preset?: PresetMetadata;
+}
+
+/**
+ * Sensible default configuration. All nodes disabled by default —
+ * operator must explicitly enable what they want to run.
+ */
+declare function getDefaultConfig(): TownhouseConfig;
+
+/**
+ * Config file loader — reads YAML, validates, writes.
+ */
+
+/**
+ * Load and validate a Townhouse config from a YAML file.
+ * Environment variables override YAML values for key settings:
+ *   - TOWNHOUSE_API_PORT
+ *   - TOWNHOUSE_TRANSPORT_MODE
+ *   - TOWNHOUSE_LOG_LEVEL
+ */
+declare function loadConfig(configPath: string): TownhouseConfig;
+/**
+ * Save a config to a YAML file atomically.
+ * Writes to a temp file first, then renames to the target (atomic on POSIX).
+ */
+declare function saveConfig(configPath: string, config: TownhouseConfig): void;
+
+/**
+ * Runtime validation for Townhouse configuration.
+ * Validates shape, narrows types, returns typed config or throws.
+ */
+
+declare class ConfigValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate raw input and return a typed TownhouseConfig.
+ * Throws ConfigValidationError with descriptive messages on invalid input.
+ */
+declare function validateConfig(raw: unknown): TownhouseConfig;
+
+/**
+ * Docker orchestration types for Townhouse (Story 21.2).
+ *
+ * STUB FILE: Created by ATDD workflow (red phase).
+ * Implementation will be added during the green phase.
+ */
+/** Node types that can be orchestrated by Townhouse. */
+type NodeType$1 = 'town' | 'mill' | 'dvm';
+/** Specification for a container to be created by the orchestrator. */
+interface ContainerSpec {
+    /** Container name (e.g., 'townhouse-town') */
+    name: string;
+    /** Docker image to use */
+    image: string;
+    /** Environment variables to pass to the container */
+    env: Record<string, string>;
+    /** Network to attach the container to */
+    network: string;
+    /** Port mappings (host:container) */
+    ports?: Record<string, string>;
+}
+/** Events emitted by the orchestrator during operations. */
+interface OrchestratorEvents {
+    /** Emitted during image pull with progress info */
+    pullProgress: {
+        image: string;
+        status: string;
+        id?: string;
+        progress?: string;
+    };
+    /** Emitted when a container changes state */
+    containerState: {
+        name: string;
+        state: 'creating' | 'starting' | 'running' | 'stopping' | 'stopped' | 'error';
+        /** Additional context for error states (e.g., error message) */
+        detail?: string;
+    };
+    /** Emitted during health check polling */
+    healthCheck: {
+        name: string;
+        status: string;
+        attempt: number;
+    };
+    /** Emitted before connector restart during peer registration update */
+    connectorRestarting: {
+        reason: string;
+    };
+    /** Emitted after connector restart and health check passes */
+    connectorRestarted: {
+        peers: string[];
+    };
+}
+/** Options for health check polling. */
+interface HealthCheckOptions {
+    /** Polling interval in milliseconds (default: 2000) */
+    interval?: number;
+    /** Timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+/** Network I/O stats for a container (from dockerode stats stream) */
+interface BandwidthStats {
+    bytesIn: number;
+    bytesOut: number;
+    sampleAt: number;
+}
+
+/**
+ * Wallet management types for Townhouse (Story 21.4).
+ *
+ * Defines interfaces for HD wallet key derivation, encryption at rest,
+ * and node key management.
+ */
+
+/** Configuration for the WalletManager */
+interface WalletManagerConfig {
+    /** Path to encrypted wallet file */
+    encryptedPath: string;
+}
+/** Keys derived for a specific node type */
+interface NodeKeys {
+    /** Nostr public key (hex-encoded, 32 bytes) */
+    nostrPubkey: string;
+    /** Nostr secret key (raw 32-byte scalar) */
+    nostrSecretKey: Uint8Array;
+    /** EVM address (checksummed, 0x-prefixed) */
+    evmAddress: string;
+    /** EVM private key (raw 32 bytes) */
+    evmPrivateKey: Uint8Array;
+    /** BIP-44 derivation path used for Nostr key */
+    nostrDerivationPath: string;
+    /** BIP-44 derivation path used for EVM key */
+    evmDerivationPath: string;
+    /** Base58-encoded Solana public key — mill only, omitted for town/dvm */
+    solanaAddress?: string;
+    /** Mina public key hex — mill only, omitted for town/dvm */
+    minaAddress?: string;
+}
+/** Map of node type to its derived keys */
+interface DerivedNodeKeys {
+    town: NodeKeys;
+    mill: NodeKeys;
+    dvm: NodeKeys;
+}
+/** Summary info for display (no secrets) */
+interface NodeKeyInfo {
+    /** Node type */
+    nodeType: NodeType$1;
+    /** Nostr public key (hex) */
+    nostrPubkey: string;
+    /** EVM address (checksummed) */
+    evmAddress: string;
+    /** Nostr derivation path */
+    nostrDerivationPath: string;
+    /** EVM derivation path */
+    evmDerivationPath: string;
+    /** Base58-encoded Solana public key — mill only, omitted for town/dvm */
+    solanaAddress?: string;
+    /** Mina public key hex — mill only, omitted for town/dvm */
+    minaAddress?: string;
+}
+/** Persisted wallet state (in memory after decryption) */
+interface WalletState {
+    /** All derived node keys */
+    keys: DerivedNodeKeys;
+}
+/** Encrypted wallet file format (JSON, all fields base64-encoded) */
+interface EncryptedWallet {
+    /** scrypt salt (base64) */
+    salt: string;
+    /** AES-GCM initialization vector (base64) */
+    iv: string;
+    /** AES-256-GCM ciphertext (base64) */
+    ciphertext: string;
+    /** AES-GCM authentication tag (base64) */
+    tag: string;
+}
+
+/**
+ * WalletManager — HD key derivation for Townhouse (Story 21.4, Task 1).
+ *
+ * Single BIP-39 mnemonic, deterministic HD derivation per node type.
+ * Uses BIP-44 paths with distinct account indices per node type:
+ *   - Town: account 0
+ *   - Mill: account 1
+ *   - DVM:  account 2
+ *
+ * Nostr keys use NIP-06 coin type 1237: m/44'/1237'/{account}'/0/0
+ * EVM keys use standard coin type 60:   m/44'/60'/{account}'/0/0
+ */
+
+/**
+ * WalletManager handles mnemonic generation, key derivation, and in-memory
+ * key lifecycle for Townhouse node operations.
+ */
+declare class WalletManager {
+    private readonly config;
+    private state;
+    constructor(config: WalletManagerConfig);
+    /** Path to the encrypted wallet file */
+    get encryptedPath(): string;
+    /**
+     * Generate a new 12-word BIP-39 mnemonic and derive all node keys.
+     * Returns the mnemonic (for one-time display) and the derived state.
+     */
+    generate(): Promise<{
+        mnemonic: string;
+        state: WalletState;
+    }>;
+    /**
+     * Import an existing mnemonic (12 or 24 words) and derive all node keys.
+     * Throws if mnemonic is invalid (wrong checksum, wrong word count, etc).
+     */
+    fromMnemonic(mnemonic: string): Promise<WalletState>;
+    /**
+     * Get derived keys for a specific node type.
+     * Throws if wallet has not been initialized (call generate() or fromMnemonic() first).
+     */
+    getNodeKeys(nodeType: NodeType$1): NodeKeys;
+    /**
+     * Get display-safe info for all node types (no secrets).
+     */
+    getAllKeys(): NodeKeyInfo[];
+    /**
+     * List keys for all node types (alias for getAllKeys for API compatibility).
+     */
+    listKeys(): NodeKeyInfo[];
+    /**
+     * Zero all in-memory key material. After calling lock(),
+     * getNodeKeys() and getAllKeys() will throw.
+     */
+    lock(): void;
+    /**
+     * Derive keys for all node types from a mnemonic.
+     */
+    private deriveAllKeys;
+    /**
+     * Derive Nostr + EVM keys for a specific node type.
+     */
+    private deriveNodeKeys;
+}
+
+/**
+ * Wallet encryption/decryption for Townhouse (Story 21.4, Task 2).
+ *
+ * Uses Node.js crypto: scrypt for KDF, AES-256-GCM for authenticated encryption.
+ * The mnemonic is the plaintext being encrypted.
+ */
+
+/**
+ * Encrypt a mnemonic with a password using scrypt + AES-256-GCM.
+ */
+declare function encryptWallet(mnemonic: string, password: string): EncryptedWallet;
+/**
+ * Decrypt an encrypted wallet with a password.
+ * Throws on wrong password (GCM auth tag verification failure).
+ */
+declare function decryptWallet(encrypted: EncryptedWallet, password: string): string;
+
+/**
+ * Wallet file I/O for Townhouse (Story 21.4, Task 2.2).
+ *
+ * Persists encrypted wallet to disk with 0o600 permissions (owner-only).
+ * Warns if existing file has world-readable permissions.
+ */
+
+/**
+ * Save encrypted wallet to disk with restrictive permissions.
+ * Creates parent directory if missing.
+ */
+declare function saveWallet(path: string, encrypted: EncryptedWallet): Promise<void>;
+/**
+ * Load encrypted wallet from disk.
+ * Returns null if file does not exist.
+ * Warns (via returned flag) if file permissions are too open.
+ */
+declare function loadWallet(path: string): Promise<{
+    wallet: EncryptedWallet;
+    permissionsWarning?: string;
+} | null>;
+
+/**
+ * Docker Orchestration Engine for Townhouse (Story 21.2).
+ *
+ * Manages the full container lifecycle: network creation, image pulling,
+ * container creation/start/stop/removal, and health check polling.
+ * Uses dockerode for programmatic Docker control with DI for testability.
+ */
+
+/**
+ * DockerOrchestrator manages the lifecycle of Townhouse containers.
+ *
+ * Constructor accepts a dockerode instance (DI for testability) and config.
+ * Emits typed events defined in OrchestratorEvents: pullProgress,
+ * containerState, and healthCheck.
+ */
+declare class DockerOrchestrator extends EventEmitter {
+    private readonly docker;
+    private readonly config;
+    private readonly configGenerator;
+    private readonly walletManager;
+    private activeNodes;
+    private readonly statsCache;
+    constructor(docker: Docker, config: TownhouseConfig, walletManager?: WalletManager);
+    /**
+     * Orchestrate full startup sequence:
+     * 1. Ensure network exists
+     * 2. Pull images (with progress)
+     * 3. Start connector, wait for health
+     * 4. Start enabled node containers in parallel
+     */
+    up(profiles: NodeType$1[]): Promise<void>;
+    /**
+     * Regenerate connector config and restart the connector container
+     * with updated environment variables (peer list).
+     *
+     * Sequence: emit connectorRestarting -> stop -> remove -> create -> start -> health -> emit connectorRestarted
+     */
+    regenerateConnectorConfig(activeNodes: NodeType$1[]): Promise<void>;
+    /**
+     * Hot-add a node after initial startup.
+     * Starts the node container, then restarts the connector with updated peer list.
+     */
+    addNode(type: NodeType$1): Promise<void>;
+    /**
+     * Hot-remove a node.
+     * Stops the node container, then restarts the connector with updated peer list.
+     */
+    removeNode(type: NodeType$1): Promise<void>;
+    /**
+     * Graceful shutdown — stops containers in reverse order:
+     * 1. Stop all node containers in parallel
+     * 2. Stop connector
+     * 3. Remove network
+     */
+    down(): Promise<void>;
+    /**
+     * Resolve the Nostr relay WebSocket URL for a Town node instance.
+     *
+     * Inspects the container's port bindings to get the host-bound port for
+     * the relay WebSocket (7100/tcp). Falls back to the Docker-internal URL
+     * when the server is running inside the Docker network or bindings are absent.
+     *
+     * @param nodeId - The `NodeInfo.id` value (e.g. 'town', 'dev-town-01')
+     */
+    getNodeRelayEndpoint(nodeId: string): Promise<string>;
+    /**
+     * Resolve the BLS health HTTP URL for a node instance.
+     *
+     * Inspects the container's port bindings to find the host-bound port for the
+     * node's health endpoint. Falls back to Docker-internal URL when running
+     * inside the Docker network or when bindings are absent.
+     *
+     * @param nodeId - The `NodeInfo.id` value (e.g. 'mill', 'dev-mill-01')
+     * @param type - Node type (determines which internal port to use)
+     */
+    getNodeHealthEndpoint(nodeId: string, type: 'town' | 'mill' | 'dvm'): Promise<string>;
+    /**
+     * Fetch network I/O stats for a container.
+     * Results are cached for 5 seconds to avoid per-request Docker API overhead.
+     *
+     * @param containerName - Full container name (e.g. 'townhouse-town')
+     * @returns Bandwidth stats or null when container is not running
+     */
+    getContainerStats(containerName: string): Promise<BandwidthStats | null>;
+    /**
+     * Return status for all townhouse containers.
+     *
+     * Discovers both single-instance (townhouse-<type>) and multi-instance
+     * (townhouse-<prefix>-<type>-<n>) containers. Multi-instance containers
+     * are returned with a `name` matching their instance suffix so callers
+     * can build per-instance NodeInfo entries (e.g. "dev-town-01").
+     */
+    status(): Promise<{
+        name: string;
+        type: 'connector' | 'town' | 'mill' | 'dvm';
+        state: string;
+        health?: string;
+        startedAt?: string;
+    }[]>;
+    /**
+     * Pull required images before starting containers.
+     * Skips images that already exist locally.
+     * Emits pullProgress events during download.
+     */
+    pullImages(profiles: NodeType$1[]): Promise<void>;
+    /**
+     * Poll container health status via inspect().
+     * Retries at configurable interval, throws on timeout.
+     */
+    healthCheck(containerName: string, options?: HealthCheckOptions): Promise<string>;
+    /**
+     * Create the townhouse-net bridge network if it doesn't exist.
+     */
+    private ensureNetwork;
+    /**
+     * Start the connector container — always runs first.
+     *
+     * The connector image at 3.3.x reads its config from a YAML file pointed
+     * to by the `CONFIG_FILE` env var (default `./config.yaml`). We write the
+     * generated YAML to `<configDir>/connector.yaml` (sibling to wallet.enc),
+     * mount it as `/config/connector.yaml`, and set CONFIG_FILE accordingly.
+     *
+     * (Env-var-based config was set on the container historically but the
+     * connector image silently ignored them — see the YAML fix landing with
+     * this comment block.)
+     */
+    private startConnector;
+    /**
+     * Start a node container (town, mill, or dvm).
+     * Retries up to MAX_START_RETRIES on failure.
+     */
+    private startNode;
+    /**
+     * Wait for a container's health check to pass.
+     */
+    private waitForHealth;
+    /**
+     * Start the relay-side ator sidecar that publishes a v3 hidden service
+     * forwarding inbound traffic to the town container's Nostr WebSocket port.
+     *
+     * The keypair directory is mounted read-write because the sidecar's
+     * entrypoint writes the `hostname` file on first boot (see
+     * docker/townhouse-ator-sidecar/Dockerfile). The town container picks up
+     * the resulting .anyone URL via the operator-set externalUrl field.
+     */
+    private startRelayAtorSidecar;
+    /**
+     * Stop and remove a single container.
+     */
+    private stopAndRemove;
+    /**
+     * Remove the townhouse-net network if it exists.
+     */
+    private removeNetwork;
+    /**
+     * Build environment variables for the connector container.
+     * Delegates to ConnectorConfigGenerator for consistent config generation.
+     */
+    private buildConnectorEnv;
+    /**
+     * Build environment variables for a node container.
+     * If a WalletManager is provided, injects per-node identity keys.
+     */
+    private buildNodeEnv;
+    /**
+     * Follow a Docker pull stream and emit progress events.
+     */
+    private followPullProgress;
+}
+
+/**
+ * Connector types for Townhouse (Story 21.3).
+ *
+ * Defines the runtime configuration shape for the standalone ILP connector,
+ * peer entries, and admin API response types.
+ */
+
+/**
+ * A peer entry representing a child node connected to the connector via BTP.
+ * Each active node becomes a child peer of the connector.
+ */
+interface PeerEntry {
+    /** Node type identifier (e.g., 'town', 'mill', 'dvm') */
+    id: string;
+    /** Relationship to connector — nodes are always children */
+    relation: 'child';
+    /** BTP WebSocket URL for Docker-internal communication */
+    btpUrl: string;
+    /** Asset code for ILP packets (e.g., 'USD') */
+    assetCode: string;
+    /** Asset scale (e.g., 6 for micro-units) */
+    assetScale: number;
+}
+/**
+/**
+ * Hidden-service configuration for the connector's inbound BTP path.
+ *
+ * When set under transport.hiddenService, the connector boots the
+ * `@anyone-protocol/anyone-client` SDK in-process (Story 35.5 of the
+ * connector repo, "ManagedAnonClient") which spawns the `anon` binary
+ * and publishes a v3 hidden service. The .anyone hostname is read from
+ * `${dir}/hostname` after publish and substituted into the connector's
+ * externalUrl as `wss://<hostname>.anyone/btp`.
+ *
+ * Operator surface lives at transport.hiddenService.{dir, port}; the
+ * connector's wire format is more verbose (transport.managedOptions.*) —
+ * config-generator handles the translation.
+ *
+ * Per-townhouse-instance keypair: the secret key under `${dir}/` is the
+ * .anyone identity. Persist it across redeploys to keep the address stable;
+ * delete it to rotate.
+ */
+interface HiddenServiceConfig {
+    /**
+     * Absolute path to the v3 hidden-service key directory inside the
+     * connector container. The connector creates `hs_ed25519_secret_key`,
+     * `hs_ed25519_public_key`, and `hostname` here on first boot, then
+     * reuses them on subsequent boots if present.
+     */
+    dir: string;
+    /**
+     * Hidden service port advertised on the .anyone address. Forwards to
+     * the connector's BTP server (typically same port as connector's
+     * btpServerPort, since the HS port = the port external peers dial).
+     */
+    port: number;
+    /**
+     * Optional override for the externalUrl the connector advertises.
+     * Defaults to the literal "auto" when unset, which makes the connector
+     * resolve the .anyone hostname from `${dir}/hostname` at startup.
+     * Set explicitly only when forcing a specific .anyone address (rare).
+     */
+    externalUrl?: string;
+    /** Overall deadline for SOCKS port readiness (ms). Default 60000. */
+    startupTimeoutMs?: number;
+    /** Overall deadline for `sdk.stop()` (ms). Default 10000. */
+    stopTimeoutMs?: number;
+}
+/**
+ * Runtime configuration for the standalone ILP connector.
+ * Generated by ConnectorConfigGenerator from TownhouseConfig.
+ */
+interface ConnectorRuntimeConfig {
+    /** Admin API listen port */
+    adminPort: number;
+    /** Base ILP address for this connector */
+    ilpAddress: string;
+    /** List of child peer entries (one per active node) */
+    peers: PeerEntry[];
+    /** Transport configuration */
+    transport: {
+        /**
+         * Operator-facing transport selection. Maps to the connector's
+         * discriminated union internally (mode='ator' → type='socks5').
+         */
+        mode: 'ator' | 'direct';
+        /** SOCKS5 proxy URL (must be socks5h://) — required when mode='ator'. */
+        socksProxy?: string;
+        /**
+         * Externally reachable BTP URL the connector advertises to peers.
+         * Required when mode='ator' AND hiddenService is unset (operator runs
+         * their own anon binary externally). Ignored for mode='direct'.
+         * When hiddenService IS set and externalUrl is unset, the generator
+         * emits the literal "auto" so the connector resolves the .anyone
+         * hostname at startup.
+         */
+        externalUrl?: string;
+        /** Inbound hidden-service publication (Story 35.5 path). */
+        hiddenService?: HiddenServiceConfig;
+    };
+}
+/**
+ * Response from GET /health on the connector's healthCheckPort.
+ * Mirrors `HealthStatus` from `@toon-protocol/connector`.
+ */
+interface HealthResponse {
+    status: 'healthy' | 'unhealthy' | 'starting' | 'degraded';
+    uptime: number;
+    peersConnected: number;
+    totalPeers: number;
+    timestamp: string;
+    nodeId?: string;
+    version?: string;
+}
+/**
+ * Per-peer ILP counter snapshot from GET /admin/metrics.json.
+ * Mirrors `AdminMetricsJsonPeer` from `@toon-protocol/connector`.
+ */
+interface MetricsPeerEntry {
+    peerId: string;
+    connected: boolean;
+    packetsForwarded: number;
+    packetsRejected: number;
+    bytesSent: number;
+    lastPacketAt: string | null;
+}
+/**
+ * Response from GET /admin/metrics.json on the connector's adminApi port.
+ * Mirrors `AdminMetricsJsonResponse` from `@toon-protocol/connector`.
+ */
+interface MetricsResponse {
+    uptimeSeconds: number;
+    aggregate: {
+        packetsForwarded: number;
+        packetsRejected: number;
+        bytesSent: number;
+    };
+    peers: MetricsPeerEntry[];
+    timestamp: string;
+}
+/**
+ * Peer entry from GET /admin/peers on the connector's adminApi port.
+ * Mirrors the response of the connector's `router.get('/peers', …)` handler.
+ * Note: per-peer packet counters live on /admin/metrics.json, not here.
+ */
+interface PeerStatus {
+    id: string;
+    connected: boolean;
+    ilpAddresses: string[];
+    routeCount: number;
+}
+/**
+ * Wrapper response from GET /admin/peers.
+ * Mirrors the connector's `router.get('/peers')` JSON envelope.
+ */
+interface PeersResponse {
+    nodeId: string;
+    peerCount: number;
+    connectedCount: number;
+    peers: PeerStatus[];
+}
+/**
+ * Filter params for GET /packets on the connector admin API.
+ *
+ * Townhouse-Side Contract (§getPacketLog) — added in story 21.10.
+ * The connector must expose `GET /packets?ilpAddress=<>&since=<>&limit=<>`.
+ * If the running connector image does not expose this endpoint, the
+ * /nodes/:type/packets/timeseries route returns 503 and the contract canary
+ * will catch the drift. See packages/sdk/CONNECTOR_MIGRATION.md §Townhouse-Side Contract.
+ */
+interface PacketLogFilter {
+    ilpAddress?: string;
+    since?: number;
+    limit?: number;
+}
+/** A single packet log entry returned by GET /packets */
+interface PacketLogEntry {
+    ts: number;
+    ilpAddressFrom: string;
+    ilpAddressTo: string;
+    amount: string;
+    result: 'fulfill' | 'reject' | 'timeout';
+}
+
+/**
+ * Connector Config Generator for Townhouse (Story 21.3).
+ *
+ * Generates runtime configuration for the standalone ILP connector
+ * based on the Townhouse config and currently active nodes.
+ */
+
+/** Default ATOR SOCKS proxy address */
+declare const DEFAULT_ATOR_PROXY = "socks5h://proxy.ator.io:9050";
+/**
+ * ConnectorConfigGenerator produces runtime configuration for the standalone
+ * ILP connector based on Townhouse config and active node list.
+ *
+ * Key design: peer BTP URLs are deterministic Docker DNS names, so nodes
+ * don't need to be running for config generation to work.
+ */
+declare class ConnectorConfigGenerator {
+    private readonly config;
+    constructor(config: TownhouseConfig);
+    /**
+     * Generate a ConnectorRuntimeConfig for the given set of active nodes.
+     *
+     * @param activeNodes - Node types currently running or about to start
+     * @returns Typed configuration object (not serialized)
+     */
+    generate(activeNodes: NodeType$1[]): ConnectorRuntimeConfig;
+    /**
+     * Serialize a ConnectorRuntimeConfig into environment variable key-value pairs.
+     *
+     * @returns Record of env var name to string value
+     */
+    toEnvVars(runtimeConfig: ConnectorRuntimeConfig): Record<string, string>;
+    /**
+     * Convert a ConnectorRuntimeConfig into the string[] format expected by
+     * dockerode's container create API (Env option: ['KEY=VALUE', ...]).
+     *
+     * @returns Array of 'KEY=VALUE' strings
+     */
+    toEnvArray(runtimeConfig: ConnectorRuntimeConfig): string[];
+    /**
+     * Render a connector YAML config string the connector image at 3.3.x can
+     * load via its `CONFIG_FILE` env var (default `./config.yaml`).
+     *
+     * The shape mirrors `docker/configs/townhouse-dev-connector.yaml` (the
+     * working dev fixture) — peers list is empty because child nodes dial
+     * INTO the connector at startup; the connector accepts BTP connections
+     * (no-auth in dev) without needing pre-configured peer entries.
+     *
+     * Added in the orchestrator-bug-fix: env vars set on the container were
+     * silently ignored by the connector image, which only reads from this
+     * YAML file. Caller writes the returned string to disk and mounts it
+     * at `/config/connector.yaml` in the container.
+     */
+    toYaml(runtimeConfig: ConnectorRuntimeConfig): string;
+    /**
+     * Translate the runtime config's transport block into the discriminated-
+     * union shape the connector expects. See toYaml's note for why this was
+     * silently broken before.
+     */
+    private buildConnectorTransportBlock;
+    /**
+     * Generate PeerEntry list for each active node type.
+     * BTP URLs use Docker DNS: btp+ws://townhouse-{type}:3000 // nosemgrep: javascript.lang.security.detect-insecure-websocket.detect-insecure-websocket
+     */
+    private generatePeerList;
+    /**
+     * Generate transport config from Townhouse config.
+     * When mode is 'ator', includes SOCKS proxy (uses default if not configured).
+     * Carries forward externalUrl + hiddenService when set; downstream
+     * buildConnectorTransportBlock handles translation to the connector's
+     * wire shape.
+     */
+    private generateTransportConfig;
+}
+
+/**
+ * Connector Admin Client for Townhouse (Story 21.3, contract aligned in 21.7.5).
+ *
+ * HTTP client for the connector's admin API endpoints. Paths and response
+ * shapes mirror the connector source-of-truth — see
+ * `@toon-protocol/connector` `packages/connector/src/http/{types,admin-api}.ts`.
+ *
+ * Uses Node.js native fetch (available in Node 20+).
+ *
+ * Two distinct HTTP servers live on the connector image:
+ *   - healthCheckPort serves /health and /health/{live,ready}
+ *   - adminApi.port serves /admin/* (peers, metrics.json, routes, channels, …)
+ *
+ * The base URL passed to this client must point at whichever server hosts
+ * the endpoint being called: pass the healthCheckPort base for `getHealth`
+ * and the adminApi.port base for `getPeers` / `getMetrics`. In practice
+ * Townhouse currently runs both ports on the same host, so callers either
+ * construct two clients or hit a shared base URL when the ports overlap.
+ */
+
+declare class ConnectorAdminClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    /**
+     * @param baseUrl - Base URL for the connector admin API (e.g., 'http://localhost:9402')
+     * @param timeoutMs - Request timeout in milliseconds (default: 5000)
+     */
+    constructor(baseUrl: string, timeoutMs?: number);
+    /**
+     * GET /health — returns the connector's HealthStatus from the healthCheckPort server.
+     *
+     * @throws Error when connector is not running, returns non-200, or shape is invalid
+     */
+    getHealth(): Promise<HealthResponse>;
+    /**
+     * GET /admin/metrics.json — returns the connector's per-peer ILP counters
+     * with an aggregate rollup, mirroring `AdminMetricsJsonResponse`.
+     *
+     * @throws Error when connector is not running, returns non-200, or shape is invalid
+     */
+    getMetrics(): Promise<MetricsResponse>;
+    /**
+     * GET /admin/peers — returns the connector's peer roster with route counts
+     * and ILP addresses. Returns the unwrapped peers array (the wrapper's
+     * nodeId / peerCount / connectedCount fields are dropped).
+     *
+     * @throws Error when connector is not running, returns non-200, or shape is invalid
+     */
+    getPeers(): Promise<PeerStatus[]>;
+    /**
+     * GET /packets — returns the connector's raw packet log filtered by the
+     * given criteria. Used by the timeseries aggregation route (story 21.10).
+     *
+     * Townhouse-Side Contract: see packages/sdk/CONNECTOR_MIGRATION.md §getPacketLog.
+     * If the connector image does not expose GET /packets, this method throws
+     * with a `ConnectorEndpointNotFound` error code so the route can return 503.
+     *
+     * @throws Error with code='ConnectorEndpointNotFound' when connector returns 404
+     * @throws Error when connector is not running, returns non-200, or shape is invalid
+     */
+    getPacketLog(filter?: PacketLogFilter): Promise<PacketLogEntry[]>;
+    /**
+     * Perform an HTTP GET request to the connector admin API.
+     * Wraps fetch with error handling for connection refused and non-200 responses.
+     */
+    private fetch;
+}
+
+/**
+ * ATOR transport probe — periodically TCP-connects to the configured SOCKS5
+ * proxy host:port and measures direct HTTPS latency for comparison.
+ *
+ * The probe answers a single operator question: "is my configured ATOR proxy
+ * contactable from this host?" TCP connect is the right granularity — if the
+ * TCP listener is up, the connector's real BTP traffic will succeed.
+ *
+ * The probe NEVER makes a real SOCKS5 handshake or proxied request — only a
+ * plain TCP connect to the proxy host:port.
+ */
+interface TransportProbeOptions {
+    proxyUrl: string;
+    intervalMs?: number;
+    /** Override the direct-latency probe URL (for tests — avoids real network). */
+    directProbeUrl?: string;
+}
+interface TransportProbeStatus {
+    reachable: boolean;
+    latencyProxyMs: number | null;
+    latencyDirectMs: number | null;
+    lastProbedAt: number;
+    probeError: string | null;
+}
+declare class TransportProbe {
+    private proxyUrl;
+    private readonly intervalMs;
+    private readonly directProbeUrl;
+    private running;
+    private timer;
+    private status;
+    constructor(opts: TransportProbeOptions);
+    /** Start the probe loop. Idempotent — calling twice while running is a no-op. */
+    start(): void;
+    /** Stop the probe loop. Idempotent. */
+    stop(): void;
+    /** Returns the latest probe snapshot synchronously. Never blocks. */
+    getStatus(): TransportProbeStatus;
+    /**
+     * Update the target proxy URL.
+     * The next tick will use the new URL; the current tick may complete against the old URL.
+     */
+    setProxyUrl(url: string): void;
+    private tick;
+    private probeTcp;
+    private probeDirectLatency;
+    private logTransition;
+}
+
+type ComposeProfile = 'dev' | 'hs';
+interface ComposeLoaderOptions {
+    /** Override default `~/.townhouse/` write target. Used by tests. */
+    townhouseHome?: string;
+    /** Override the package-relative dist directory the loader reads from.
+     *  Defaults to the `dist/` adjacent to compose-loader.js at runtime.
+     *  Tests use this to point at fixture directories. */
+    distDir?: string;
+}
+declare class ComposeLoaderError extends Error {
+    constructor(message: string);
+}
+/**
+ * Returns the rendered compose YAML for the requested profile.
+ * For 'hs', digest substitutions are already applied (resolved at build time).
+ * For 'dev', the YAML is returned verbatim (uses local `toon:*` image tags).
+ * Throws `ComposeLoaderError` if the requested profile's YAML is unreadable.
+ */
+declare function loadComposeTemplate(profile: ComposeProfile, options?: ComposeLoaderOptions): string;
+/**
+ * Writes the resolved compose YAML to `<townhouseHome>/compose/<profile>.yml`
+ * and copies `dist/image-manifest.json` to `<townhouseHome>/image-manifest.json`.
+ * BOTH output files are written with mode 0o600 (NFR8 — operator-secret file mode).
+ * Returns the absolute paths of the two files written.
+ */
+declare function materializeComposeTemplate(profile: ComposeProfile, options?: ComposeLoaderOptions): {
+    composePath: string;
+    manifestPath: string;
+};
+
+/**
+ * Townhouse API — type definitions.
+ */
+
+/** Per-kind job count for jobsRecent.byKind */
+interface DvmJobsByKindEntry {
+    kind: number;
+    count: number;
+}
+/** Per-status job counts for the sliding window */
+interface DvmJobsByStatus {
+    processing: number;
+    success: number;
+    error: number;
+    partial: number;
+}
+/** Windowed recent-jobs telemetry (default window: 5 min) */
+interface DvmJobsRecent {
+    total: number;
+    byKind: DvmJobsByKindEntry[];
+    byStatus: DvmJobsByStatus;
+}
+/** Response shape for GET /health on the DVM BLS server (port 3400). */
+interface DvmHealthResponse {
+    status: 'starting' | 'ok' | 'stopping' | 'stopped' | 'error';
+    version: string;
+    nodePubkey: string;
+    uptimeSec: number;
+    /** Registered handler event kinds (e.g. [5094]). */
+    handlerKinds: number[];
+    /** Per-kind pricing in string-encoded bigint (e.g. { "5094": "10" }). */
+    kindPricing: Record<string, string>;
+    basePricePerByte: string;
+    jobsRecent: DvmJobsRecent;
+}
+/** Node types supported by Townhouse */
+type NodeType = 'town' | 'mill' | 'dvm';
+/** Runtime state of a node container */
+type NodeState = 'running' | 'stopped' | 'error' | 'not-created';
+/** Response shape for GET /nodes */
+interface NodeInfo {
+    /**
+     * Unique instance identifier — equals `type` for single-instance deployments.
+     * Required in responses from this API; undefined in legacy test fixtures.
+     */
+    id: string;
+    type: NodeType;
+    enabled: boolean;
+    state: NodeState;
+    uptimeSeconds: number | null;
+    image: string;
+}
+/** Detailed response shape for GET /nodes/:type */
+interface NodeDetail extends NodeInfo {
+    config: {
+        feePerEvent?: number;
+        feeBasisPoints?: number;
+        feePerJob?: number;
+        kindPricing?: Record<string, number>;
+        enabled: boolean;
+    };
+    metrics: MetricsPayload | null;
+}
+/** Metrics payload from connector admin — narrowed per connector-team agreement 2026-04-21 */
+interface MetricsPayload {
+    packetsForwarded: number;
+    packetsRejected: number;
+    bytesSent: number;
+    attribution: 'aggregate' | 'per-peer';
+    available: boolean;
+}
+/** Nostr event shape forwarded in relayEvents messages */
+interface NostrEventPayload {
+    id: string;
+    kind: number;
+    pubkey: string;
+    content: string;
+    tags: string[][];
+    sig: string;
+    created_at: number;
+}
+/** WebSocket message shapes */
+interface WsMetricsMessage {
+    type: 'metrics';
+    payload: MetricsPayload;
+    ts: number;
+}
+interface WsNodeStateMessage {
+    type: 'nodeState';
+    payload: NodeStatePayload;
+    ts: number;
+}
+interface WsHeartbeatMessage {
+    type: 'heartbeat';
+    ts: number;
+}
+interface WsBatchMessage {
+    type: 'batch';
+    messages: WsMessage[];
+    ts: number;
+}
+/** Forwarded Nostr event from a Town relay subscription */
+interface WsRelayEventsMessage {
+    type: 'relayEvents';
+    nodeId: string;
+    payload: NostrEventPayload;
+    ts: number;
+}
+/** Connector restart notifications (emitted around fee-config PATCH) */
+interface WsConnectorRestartingMessage {
+    type: 'connectorRestarting';
+    ts: number;
+}
+interface WsConnectorRestartedMessage {
+    type: 'connectorRestarted';
+    ts: number;
+}
+interface NodeStatePayload {
+    name: string;
+    state: string;
+}
+/** Server notification when the upstream relay WebSocket for a nodeId disconnects */
+interface WsRelayEventsStatusMessage {
+    type: 'relayEventsStatus';
+    nodeId: string;
+    connected: boolean;
+    ts: number;
+}
+type WsMessage = WsMetricsMessage | WsNodeStateMessage | WsHeartbeatMessage | WsBatchMessage | WsRelayEventsMessage | WsConnectorRestartingMessage | WsConnectorRestartedMessage | WsRelayEventsStatusMessage;
+/** Response shape for GET /nodes/:type/bandwidth */
+interface BandwidthPayload {
+    bytesIn: number;
+    bytesOut: number;
+    sampleAt: number;
+}
+/** Packet log time-series bucket */
+interface TimeseriesBucket {
+    ts: number;
+    count: number;
+}
+/** Response shape for GET /nodes/:type/packets/timeseries */
+interface PacketTimeseriesPayload {
+    buckets: TimeseriesBucket[];
+}
+
+/** Minimal common health shape; superset emitted by Town containers. */
+interface TownHealthPayload {
+    status: 'ok' | 'starting' | 'stopping' | 'stopped' | 'error';
+    version?: string;
+    uptimeSec?: number;
+    nodePubkey?: string;
+}
+/** Union of all node health response shapes. */
+type NodeHealthPayload = MillHealthResponse | TownHealthPayload | DvmHealthResponse;
+/** Per-kind job activity bucket for GET /nodes/:nodeId/jobs/recent */
+interface JobsByKindEntry {
+    kind: number;
+    count: number;
+    volume: string;
+}
+/** Response shape for GET /nodes/:nodeId/jobs/recent */
+interface JobsRecentPayload {
+    count: number;
+    volume: string;
+    byKind: JobsByKindEntry[];
+    byStatus: {
+        processing: number;
+        success: number;
+        error: number;
+        partial: number;
+    };
+}
+/** Per-pair swap activity bucket */
+interface SwapByPairEntry {
+    pair: string;
+    count: number;
+    volume: string;
+}
+/** Response shape for GET /nodes/mill/swaps/recent */
+interface MillSwapsRecentPayload {
+    count: number;
+    volume: string;
+    byPair: SwapByPairEntry[];
+}
+/** Per-chain deposit address entry */
+interface DepositAddressEntry {
+    family: 'evm' | 'solana' | 'mina';
+    address: string;
+}
+/** Response shape for GET /nodes/:type/deposit-addresses */
+interface DepositAddressesPayload {
+    chains: DepositAddressEntry[];
+}
+/** Per-chain balance entry returned by GET /api/wallet/balances */
+interface WalletBalanceEntry {
+    nodeType: 'town' | 'mill' | 'dvm';
+    family: 'evm' | 'solana' | 'mina';
+    token: 'ETH' | 'USDC' | 'SOL' | 'MINA';
+    address: string;
+    /** Decimal string in raw units (wei, lamports, etc.) */
+    balance: string;
+    /** Decimal places — 18 for ETH, 6 for USDC, 9 for SOL, 9 for MINA */
+    scale: number;
+    available: boolean;
+    /** Populated when available === false */
+    reason?: string;
+}
+/** Response shape for GET /api/wallet/balances */
+interface WalletBalancesPayload {
+    entries: WalletBalanceEntry[];
+    ts: number;
+}
+/** Request body for POST /api/wallet/withdraw.
+ *  `chainFamily` lists all values the route accepts at the wire level — the
+ *  handler returns 501 for solana/mina with a structured payload pointing the
+ *  caller at the deposit-address copy flow. */
+interface WithdrawRequest {
+    nodeType: 'town' | 'mill' | 'dvm';
+    chainFamily: 'evm' | 'solana' | 'mina';
+    token: 'native' | 'USDC';
+    recipient: string;
+    /** Decimal string in raw units */
+    amount: string;
+    /** When true: returns gas estimate without broadcasting */
+    dryRun?: boolean;
+}
+/** Successful broadcast response (dryRun !== true). */
+interface WithdrawSuccessResponse {
+    txHash: `0x${string}`;
+    chainId: number;
+}
+/** Successful dryRun response (no broadcast performed). */
+interface WithdrawDryRunResponse {
+    estimatedGas: string;
+    estimatedFee: string;
+}
+/** Discriminated union — callers narrow by presence of `txHash`. */
+type WithdrawResponse = WithdrawSuccessResponse | WithdrawDryRunResponse;
+/** Request body for POST /api/wallet/reveal */
+interface RevealRequest {
+    password: string;
+}
+/** Response shape for POST /api/wallet/reveal */
+type RevealResponse = {
+    mnemonic: string;
+} | {
+    error: 'invalid_password' | 'wallet_not_initialized' | 'wallet_corrupted';
+    message?: string;
+};
+/** Response shape for GET /api/wallet/transaction/:txHash */
+interface TransactionReceiptPayload {
+    status: 'pending' | 'success' | 'reverted';
+    blockNumber?: number;
+    txHash: string;
+}
+/** Response shape for GET /api/wizard/state */
+interface WizardStatePayload {
+    config_exists: boolean;
+    wallet_exists: boolean;
+    containers_running: boolean;
+    mode: 'wizard' | 'normal';
+    ts: number;
+}
+/** Request body for POST /api/wizard/init.
+ *  `mnemonic` is required in BOTH modes — `mnemonic_mode` is purely a UX hint
+ *  for the SPA, the server is stateless WRT the mnemonic and validates it on
+ *  every init regardless of mode (see story 21.14 Dev Notes). */
+interface WizardInitRequest {
+    password: string;
+    password_confirm: string;
+    mnemonic_mode: 'generate' | 'import';
+    mnemonic: string;
+    backup_ack: boolean;
+    nodes: {
+        town: {
+            enabled: boolean;
+            feePerEvent?: number;
+        };
+        mill: {
+            enabled: boolean;
+            feeBasisPoints?: number;
+        };
+        dvm: {
+            enabled: boolean;
+            feePerJob?: number;
+        };
+    };
+    transport: {
+        mode: 'direct' | 'ator';
+    };
+}
+/** Progress messages streamed over WS /api/wizard/progress */
+type WizardProgressMessage = {
+    type: 'pull_progress';
+    image: string;
+    status: string;
+    progress?: string;
+    ts: number;
+} | {
+    type: 'container_starting';
+    name: string;
+    ts: number;
+} | {
+    type: 'container_healthy';
+    name: string;
+    ts: number;
+} | {
+    type: 'container_failed';
+    name: string;
+    reason: string;
+    ts: number;
+} | {
+    type: 'launch_complete';
+    ts: number;
+} | {
+    type: 'error';
+    message: string;
+    ts: number;
+};
+/** Response shape for GET /api/transport */
+interface TransportStatusPayload {
+    mode: 'direct' | 'ator';
+    /** Present only when mode === 'ator' */
+    socksProxy?: string;
+    reachable: boolean;
+    latencyProxyMs: number | null;
+    latencyDirectMs: number | null;
+    /** ms epoch; 0 if probe never ran */
+    lastProbedAt: number;
+    probeError: string | null;
+    /** Server timestamp at response build time */
+    ts: number;
+}
+/** Request body for PATCH /api/transport */
+interface TransportPatchRequest {
+    mode: 'direct' | 'ator';
+    socksProxy?: string;
+}
+/** Response body for PATCH /api/transport */
+interface TransportPatchResponse {
+    mode: 'direct' | 'ator';
+    socksProxy?: string;
+    restartTriggered: boolean;
+    /** ms epoch of connector restart; present when restartTriggered === true */
+    restartedAt?: number;
+}
+/** API server returned by createApiServer */
+interface ApiServer {
+    app: FastifyInstance;
+    close: () => Promise<void>;
+}
+/** Dependencies required to create the API server */
+interface ApiDeps {
+    configPath: string;
+    config: TownhouseConfig;
+    orchestrator: DockerOrchestrator;
+    wallet: WalletManager;
+    connectorAdmin: ConnectorAdminClient;
+    /**
+     * Probe instance. Required: callers (createApiServer, createWizardApiServer,
+     * cli, dev API server) construct it from the config and pass it explicitly.
+     */
+    transportProbe: TransportProbe;
+    logger?: FastifyBaseLogger;
+}
+
+/**
+ * API Server Factory.
+ *
+ * SECURITY: Only binds to loopback address by default (localhost-only for v1).
+ * Set TOWNHOUSE_API_ALLOW_REMOTE=1 to override this security boundary.
+ */
+
+/**
+ * Create the Fastify API server. Caller MUST supply a `transportProbe` in
+ * `deps` (constructed from the config and started if mode === 'ator').
+ */
+declare function createApiServer(deps: ApiDeps): Promise<ApiServer>;
+
+/**
+ * Wizard API Server Factory.
+ *
+ * Starts in wizard mode (only wizard routes), transitions to normal mode
+ * after POST /wizard/init completes and containers are healthy.
+ * SECURITY: Wizard mode hard-rejects non-loopback bind regardless of env var.
+ */
+
+interface WizardInitialDeps {
+    /** Directory where ~/.townhouse/ (or override) lives */
+    configDir: string;
+    /** Full path to config.yaml */
+    configPath: string;
+    /** Full path to wallet.enc */
+    walletPath: string;
+    /** Port to bind the API */
+    port: number;
+    /** Bind host — must be a loopback address; defaults to 127.0.0.1 */
+    bindHost?: string;
+    docker: Docker;
+    logger?: FastifyBaseLogger | boolean;
+}
+/**
+ * Create the wizard API server. Starts in wizard-only mode.
+ * After POST /wizard/init + orchestrator launch, transitions to normal mode.
+ */
+declare function createWizardApiServer(initialDeps: WizardInitialDeps): Promise<ApiServer>;
+
+export { type ApiConfig, type ApiDeps, type ApiServer, type BandwidthPayload, type BandwidthStats, ComposeLoaderError, type ComposeLoaderOptions, type ComposeProfile, ConfigValidationError, ConnectorAdminClient, type ConnectorConfig, ConnectorConfigGenerator, type ConnectorRuntimeConfig, type ContainerSpec, DEFAULT_ATOR_PROXY, type DepositAddressEntry, type DepositAddressesPayload, type DerivedNodeKeys, DockerOrchestrator, type DvmHealthResponse, type DvmNodeConfig, type EncryptedWallet, type HealthCheckOptions, type HealthResponse, type JobsByKindEntry, type JobsRecentPayload, type LoggingConfig, type MetricsPayload, type MetricsPeerEntry, type MetricsResponse, type MillNodeConfig, type MillSwapsRecentPayload, type NodeDetail, type NodeHealthPayload, type NodeInfo, type NodeKeyInfo, type NodeKeys, type NodeState, type NodeType$1 as NodeType, type NodesConfig, type NostrEventPayload, type OrchestratorEvents, type PacketLogEntry, type PacketLogFilter, type PacketTimeseriesPayload, type PeerEntry, type PeerStatus, type PeersResponse, type RevealRequest, type RevealResponse, type SwapByPairEntry, type TimeseriesBucket, type TownHealthPayload, type TownNodeConfig, type TownhouseConfig, type TransactionReceiptPayload, type TransportConfig, type TransportPatchRequest, type TransportPatchResponse, TransportProbe, type TransportStatusPayload, type WalletBalanceEntry, type WalletBalancesPayload, type WalletConfig, WalletManager, type WalletManagerConfig, type WalletState, type WithdrawDryRunResponse, type WithdrawRequest, type WithdrawResponse, type WithdrawSuccessResponse, type WizardInitRequest, type WizardProgressMessage, type WizardStatePayload, type WsBatchMessage, type WsConnectorRestartedMessage, type WsConnectorRestartingMessage, type WsHeartbeatMessage, type WsMessage, type WsMetricsMessage, type WsNodeStateMessage, type WsRelayEventsMessage, createApiServer, createWizardApiServer, decryptWallet, encryptWallet, getDefaultConfig, loadComposeTemplate, loadConfig, loadWallet, materializeComposeTemplate, saveConfig, saveWallet, validateConfig };