@toon-protocol/hub 0.34.3

package/dist/orchestrator-dGq7CeaO.d.ts

@@ -0,0 +1,1507 @@
+import { EventEmitter } from 'node:events';
+import Docker from 'dockerode';
+import { NetworkMode } from '@toon-protocol/core';
+
+/**
+ * Townhouse configuration schema — TypeScript interfaces only.
+ * Runtime validation lives in validator.ts.
+ */
+
+interface TownNodeConfig {
+    enabled: boolean;
+    /**
+     * Publish price in ILP base units per event. Injected into the town container
+     * (FEE_PER_EVENT), enforced by the town's pricing validator, AND advertised in
+     * the town's kind:10032 `feePerByte` so clients know the cost before sending.
+     */
+    feePerEvent?: number;
+    /**
+     * Settlement chain the town advertises + prices in (kind:10032). Must be one
+     * of the deployment's supported chains (the `network` profile ∪ `chains add`).
+     * Picked via `node add town --settlement-chain`. When unset, defaults to the
+     * deployment's first supported chain. Validated at provision time.
+     */
+    settlementChainId?: string;
+    /**
+     * Settlement token on `settlementChainId` (USDC | ETH | SOL | MINA). Must be a
+     * token that chain supports (EVM: USDC/ETH · Solana: USDC/SOL · Mina: MINA
+     * only). Picked via `--asset`. When unset, defaults to USDC where supported,
+     * else the native token. `assetScale` is DERIVED from this token, not set here.
+     */
+    assetCode?: string;
+    /**
+     * @deprecated assetScale is derived from `assetCode`/`settlementChainId`
+     * (USDC 6, ETH 18, SOL 9, MINA 9). Retained for back-compat; ignored for the
+     * advertised value.
+     */
+    assetScale?: number;
+    /** Docker image override */
+    image?: string;
+}
+/**
+ * Apex connector negotiation values an operator can tune. Currently the routing
+ * fee the apex takes on packets it forwards to children. NOTE: enforcement is
+ * connector-side — emitting this only has effect on a connector image that reads
+ * a routing-fee field; see config-generator.ts.
+ */
+interface ApexConfig {
+    /** Routing fee in basis points (1 = 0.01%) the apex takes per forwarded packet. */
+    routingFeeBasisPoints?: number;
+}
+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;
+    /**
+     * Nostr relay URLs the mill listens on for swap requests. Mill's
+     * `validateConfig()` REQUIRES a non-empty list, so this must be supplied at
+     * `node add mill` time — via `--relays`, this field, or the `MILL_RELAYS`
+     * env var (resolution precedence: flag > config > env). Persisted here so
+     * subsequent `node remove && node add` and reconciliation no longer depend on
+     * a shell env var being exported at the right moment. Injected into the mill
+     * container as the comma-joined `MILL_RELAYS` env.
+     */
+    relays?: 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;
+    /**
+     * Arweave Turbo upload credential (a JWK JSON string) for kind:5094 blob
+     * jobs. OPTIONAL — the DVM boots without it and free-tier (<100KB)
+     * unauthenticated uploads still work; only larger/paid uploads need it.
+     * Supplied at `node add dvm` time via `--turbo-token`, this field, or the
+     * `TURBO_TOKEN` env var (resolution precedence: flag > config > env), then
+     * injected into the dvm container as `TURBO_TOKEN`.
+     *
+     * SECRET: unlike `mill.relays`, this is NOT auto-written here by `node add`
+     * (a private key in plaintext config.yaml is avoided by design). It is only
+     * READ if an operator chooses to set it manually, accepting that risk. The
+     * `--turbo-token` flag injects at runtime without persisting.
+     */
+    turboToken?: 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;
+}
+/**
+ * Connector chain-provider entry — what the connector needs to spin up its
+ * settlement subsystem (AccountManager + ClaimReceiver) for one chain. Without
+ * at least one entry, `/admin/earnings.json` returns 503 and Townhouse's
+ * earnings data plane breaks (Epic 47 BUG-1).
+ *
+ * This is a discriminated union on `chainType` that mirrors the connector's
+ * `ProviderConfig` contract (EVM | Solana | Mina), so entries pass straight
+ * through `ConnectorConfigGenerator` to the connector. The connector already
+ * implements payment-channel providers for all three chains.
+ *
+ * Dev-Anvil deterministic placeholders are exposed via
+ * `DEFAULT_HS_CHAIN_PROVIDERS` in `defaults.ts`; operators running on real
+ * chains override this in their `config.yaml`.
+ */
+/** Supported settlement chain families. */
+type ChainType = 'evm' | 'solana' | 'mina';
+/** EVM settlement chain (Base, Arbitrum, Anvil dev, …). */
+interface EvmChainProvider {
+    chainType: 'evm';
+    /** Canonical chain id, e.g. 'evm:base:31337' (dev-Anvil) or 'evm:base:8453' (mainnet). */
+    chainId: string;
+    /** JSON-RPC endpoint. May be a dead address in offline/demo mode. */
+    rpcUrl: string;
+    /** PaymentChannel registry contract. */
+    registryAddress: string;
+    /** Settlement token (USDC, etc.) contract. */
+    tokenAddress: string;
+    /**
+     * Hex private key / key id the connector signs settlement claims with.
+     * Optional: when omitted, `townhouse hs up` fills it with the operator's
+     * mnemonic-derived apex settlement key (acct index 3). Set it only to use an
+     * external/hardware key.
+     */
+    keyId?: string;
+    /**
+     * Settlement tuning knobs. The connector reads its GLOBAL settlement
+     * threshold from the FIRST EVM chainProvider that carries `settlementOptions`
+     * (connector `connector-node.ts`: `chainProviders.find(evm && settlementOptions)`)
+     * and applies that single `threshold` as the `defaultThreshold` for the
+     * event-driven settlement monitor across ALL chains (EVM, Solana, Mina).
+     *
+     * When omitted the connector falls back to a default threshold of `1000000`,
+     * which exactly equals the per-publish fee (1 USDC at scale 6). Because the
+     * monitor triggers on `cumulativeAmount > threshold` (STRICTLY greater), a
+     * single paid publish at the default never crosses it and on-chain
+     * settlement (`claimFromChannel`/`SETTLE_CHANNEL`) is never triggered for a
+     * dynamically-registered (anonymous HS) peer. Set `threshold` BELOW the
+     * per-publish fee to make a single paid publish settle on-chain.
+     *
+     * Mirrors the connector's `EVMProviderConfig.settlementOptions` contract.
+     */
+    settlementOptions?: {
+        /** Cumulative balance (in token base units, as a decimal string) that
+         * must be exceeded before the connector settles a peer on-chain. */
+        threshold?: string;
+        /** Channel settlement timeout in seconds (connector default 86400). */
+        settlementTimeoutSecs?: number;
+        /** Initial channel deposit multiplier (connector default 1). */
+        initialDepositMultiplier?: number;
+        /** Settlement polling interval in ms (legacy poll-based monitor). */
+        pollingIntervalMs?: number;
+    };
+}
+/** Solana settlement chain. */
+interface SolanaChainProvider {
+    chainType: 'solana';
+    /** Canonical chain id, e.g. 'solana:devnet' or 'solana:mainnet'. */
+    chainId: string;
+    /** Cluster RPC endpoint (HTTP). */
+    rpcUrl: string;
+    /** WebSocket endpoint for account subscriptions (derived from rpcUrl if absent). */
+    wsUrl?: string;
+    /** On-chain payment-channel program id (base58). */
+    programId: string;
+    /** Settlement token mint (base58). */
+    tokenMint?: string;
+    /**
+     * Key id the connector signs settlement claims with. Optional — when omitted,
+     * `townhouse hs up` fills it with the operator's mnemonic-derived apex key.
+     */
+    keyId?: string;
+}
+/** Mina settlement chain. */
+interface MinaChainProvider {
+    chainType: 'mina';
+    /** Canonical chain id, e.g. 'mina:devnet' or 'mina:mainnet'. */
+    chainId: string;
+    /** Mina GraphQL endpoint. */
+    graphqlUrl: string;
+    /** zkApp address for the payment-channel contract (base58). */
+    zkAppAddress: string;
+    /** Key id the connector signs settlement claims with. */
+    keyId?: string;
+}
+type ChainProviderEntry = EvmChainProvider | SolanaChainProvider | MinaChainProvider;
+/**
+ * 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: 'hs' for hidden-service (SOCKS5/Tor-based), 'direct' for clearnet */
+    mode: 'hs' | 'direct';
+    /** SOCKS5 proxy address when using hs transport */
+    socksProxy?: string;
+    /**
+     * Externally reachable BTP URL. Required when mode='hs' 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;
+    /**
+     * Public Nostr relay read URL the town advertises (kind:10032 `relayUrl` +
+     * kind:10166 seed entry) so clients know where to subscribe for FREE reads.
+     * - DIRECT mode: set this to your externally-reachable `ws(s)://<host>:7100`
+     *   and bind the port with `TOWNHOUSE_RELAY_BIND=0.0.0.0`.
+     * - HS mode: leave unset — `hs up` derives `wss://<relay-addr>.anyone/` from
+     *   the relay hidden service. Set it only to override the derived value.
+     */
+    relayExternalUrl?: string;
+}
+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;
+    /**
+     * Network mode selecting the chain tier for BOTH the apex connector and the
+     * child node containers (EVM = Base primary + Arbitrum; Solana; Mina):
+     * - `testnet` (default when unset) — public Sepolia / Solana+Mina devnets,
+     *   settlement-complete (this is the sane default so an operator who omits
+     *   `--network` gets a settlement-ready node, not a relay-only/dev fallback)
+     * - `devnet` — public Sepolia / Solana+Mina devnets (no local chain)
+     * - `mainnet` — public production chains, but TOON settlement contracts are
+     *   NOT deployed there yet → resolves relay-only (no chainProviders)
+     * - `custom` — operator supplies `chainProviders` directly, OR just RPC URLs
+     *   via `endpoints` (below) to point at the project's dev chains
+     *
+     * Resolved via `resolveNetworkProfile()` (@toon-protocol/core). An explicit
+     * non-empty `chainProviders` always overrides the derived providers.
+     */
+    network?: NetworkMode;
+    /**
+     * Operator-supplied RPC URLs for `network: 'custom'` (`--evm-url`/`--sol-url`
+     * or EVM_URL/SOL_URL env). Points the apex + nodes at the project's dev chains
+     * hosted anywhere — e.g. the anvil + solana that scripts/akash-deploy.sh
+     * deploys to Akash (ingress hostnames rotate per redeploy, so the operator
+     * passes the current URLs). EVM is the chain-id 31338 Anvil
+     * (settlement-complete); Solana is RPC + Mock-USDC only (relay-only).
+     */
+    endpoints?: {
+        evmUrl?: string;
+        solUrl?: string;
+    };
+    /**
+     * Connector chain providers — required for the connector's settlement
+     * subsystem (AccountManager + ClaimReceiver) to initialize. When unset on
+     * `townhouse hs up`, `hs-config-writer.ts` derives them from `network` (or
+     * injects `DEFAULT_HS_CHAIN_PROVIDERS` as a last resort) so the earnings
+     * route returns 200 out of the box (Epic 47 BUG-1 product fix).
+     */
+    chainProviders?: ChainProviderEntry[];
+    /** Present only when the config was generated by `init --preset=<name>`. */
+    preset?: PresetMetadata;
+    /** Apex connector negotiation values (e.g. routing fee). */
+    apex?: ApexConfig;
+}
+
+/**
+ * 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 = '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;
+}
+
+type ComposeProfile = 'dev' | 'hs' | 'direct';
+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;
+};
+
+/**
+ * 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;
+}
+/**
+ * Arweave JWK (RSA-4096) — matches `arweave-js` / `@ardrive/turbo-sdk`
+ * `JWKInterface` shape. Defined locally to avoid an arweave-js dependency.
+ *
+ * All fields are base64url-encoded big-endian integers per JWA (RFC 7518).
+ */
+interface ArweaveJwk {
+    kty: 'RSA';
+    /** Public exponent (typically "AQAB" = 65537) */
+    e: string;
+    /** Modulus n (base64url) */
+    n: string;
+    /** Private exponent d */
+    d?: string;
+    /** First prime factor p */
+    p?: string;
+    /** Second prime factor q */
+    q?: string;
+    /** d mod (p-1) */
+    dp?: string;
+    /** d mod (q-1) */
+    dq?: string;
+    /** q^-1 mod p */
+    qi?: 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 — derived for all node types */
+    solanaAddress?: string;
+    /** Raw 32-byte Ed25519 Solana private key seed */
+    solanaPrivateKey?: Uint8Array;
+    /** BIP-44 derivation path used for Solana key (SLIP-0010 all-hardened) */
+    solanaDerivationPath?: string;
+    /** Mina public key hex — mill only, omitted for town/dvm */
+    minaAddress?: string;
+    /** Arweave wallet address (base64url SHA-256 of modulus) — DVM only */
+    arweaveAddress?: string;
+    /**
+     * Arweave RSA-4096 JWK — DVM only. The full private JWK is held in
+     * memory for credit-buy + upload signing. Zeroed by `lock()`.
+     */
+    arweaveJwk?: ArweaveJwk;
+    /** BIP-44 derivation path used for the Arweave RSA sub-seed */
+    arweaveDerivationPath?: 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;
+    /** 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 — derived for all node types */
+    solanaAddress?: string;
+    /** Solana derivation path — present whenever solanaAddress is */
+    solanaDerivationPath?: string;
+    /** Mina public key hex — mill only, omitted for town/dvm */
+    minaAddress?: string;
+    /** Arweave wallet address (base64url) — DVM only */
+    arweaveAddress?: string;
+    /** Arweave derivation path — present whenever arweaveAddress is */
+    arweaveDerivationPath?: string;
+}
+/** Persisted wallet state (in memory after decryption) */
+interface WalletState {
+    /** All derived node keys */
+    keys: DerivedNodeKeys;
+    /**
+     * BIP-39 mnemonic held in memory for transient re-derivation.
+     * Cleared on lock() by setting this.state = null. Never serialized.
+     */
+    mnemonic: string;
+}
+/** 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
+ * Solana keys (all node types) coin 501: m/44'/501'/{account}'/0'/0'
+ *   (SLIP-0010 all-hardened, via @toon-protocol/mill::deriveMillKeys)
+ * Arweave keys (DVM only) coin 472:     m/44'/472'/2'/0/0
+ *   (32-byte BIP-32 sub-seed feeds a deterministic RSA-4096 PRNG via
+ *    rsa-from-seed.ts (HMAC-DRBG + node-forge 1.3.3). Derivation takes 5–30s per DVM unlock; this runs
+ *    once at unlock time, not per operation.)
+ */
+
+/**
+ * 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): 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;
+    /**
+     * Return the BIP-39 mnemonic from in-memory wallet state.
+     * Returns null when the wallet is locked or not initialized.
+     */
+    getMnemonic(): string | null;
+    /**
+     * Get derived keys for a specific node type at a given derivation index.
+     *
+     * Pure derivation — does NOT mutate `state`. Re-derives from the stored
+     * mnemonic each time it is called. For every node type, also derives the
+     * Solana key at the same account index. For 'dvm', also derives Arweave.
+     * Throws if the wallet is locked.
+     *
+     * v1 callers MUST pass `derivationIndex = ACCOUNT_INDEX_{type}` for the
+     * first (and only) instance per type. Multi-instance support is out of
+     * scope for v1 — the route layer enforces single-instance-per-type.
+     */
+    deriveNodeKey(type: NodeType, derivationIndex: number): Promise<NodeKeys>;
+    /**
+     * Returns the EVM private key for a node as a 64-char lowercase hex string.
+     * Throws when the wallet is locked. Callers MUST treat the returned string
+     * as sensitive (no logging, no persisting). The underlying Uint8Array is
+     * still owned by WalletManager and will be zeroed by `lock()`.
+     */
+    getEvmPrivateKeyHex(nodeType: NodeType): string;
+    /**
+     * Derive the APEX (connector) settlement key from the operator mnemonic at
+     * ACCOUNT_INDEX_APEX. The apex signs settlement claims with this key, so the
+     * operator never has to supply a raw `keyId` to `townhouse chains add`.
+     *
+     * Returns the EVM private key as a `0x`-prefixed 64-char hex string — the
+     * form the connector config's `keyId` expects (matches the dev placeholder
+     * `0x7c85…`). Also returns Solana + Mina settlement keys (connector 3.9.0)
+     * derived at the same `ACCOUNT_INDEX_APEX`, in the RAW base58 form the
+     * connector resolves a non-EVM `keyId` as:
+     *   - Solana: base58 of the 32-byte Ed25519 seed,
+     *   - Mina:   `EK…` base58check (via `hexToMinaBase58PrivateKey`).
+     *
+     * EVM derivation must always succeed (it throws on failure). Solana/Mina
+     * derivation is best-effort: if `deriveMillKeys` throws (unsupported
+     * platform, library load error) the corresponding key is OMITTED rather than
+     * failing the whole method, so the EVM keyId path is never blocked.
+     *
+     * Async because `deriveMillKeys` is async. Throws when the wallet is locked.
+     */
+    getApexSettlementKeys(): Promise<{
+        evmPrivateKeyHex: string;
+        solanaPrivateKeyBase58?: string;
+        minaPrivateKeyBase58?: string;
+    }>;
+    /**
+     * Returns the Solana Ed25519 private key seed for a node as a 64-char
+     * lowercase hex string (32 raw seed bytes). Throws when the wallet is
+     * locked or when the Solana key was not derived for this node type.
+     */
+    getSolanaPrivateKeyHex(nodeType: NodeType): string;
+    /**
+     * Returns the Arweave RSA JWK for a node. Throws when the wallet is locked
+     * or when AR derivation has not yet been triggered for this node type.
+     *
+     * Callers MUST `await ensureArweaveKey(nodeType)` first the first time per
+     * unlock — RSA-4096 derivation is 5–30s and is therefore not done eagerly
+     * at `fromMnemonic`/`generate` time. After the first `ensureArweaveKey`
+     * the JWK is cached on the in-memory state until `lock()`.
+     */
+    getArweaveJwk(nodeType: NodeType): ArweaveJwk;
+    /**
+     * Lazily derive the Arweave RSA-4096 JWK for a node type and cache it on
+     * the in-memory wallet state. Subsequent calls (within the same unlocked
+     * session) return the cached result without re-deriving.
+     *
+     * Only meaningful for node types that participate in the Arweave credit
+     * flow — `dvm` (account 2) in the current Townhouse layout. Calling on
+     * `town` or `mill` will derive a valid AR key at the corresponding
+     * account index but those keys are not used by any current code path.
+     *
+     * Throws if the wallet is locked or RSA derivation fails (unsupported
+     * platform, etc.). On success the result is also reflected in subsequent
+     * `getAllKeys()` calls (arweaveAddress + arweaveDerivationPath fields).
+     */
+    ensureArweaveKey(nodeType: NodeType, password?: string): Promise<ArweaveJwk>;
+    /**
+     * Derive keys for all node types from a mnemonic.
+     */
+    private deriveAllKeys;
+    /**
+     * Derive Nostr + EVM keys for a specific node type.
+     * Accepts an optional `accountIndex` to override the default per-type index.
+     * When omitted, uses `NODE_ACCOUNT_INDEX[nodeType]` (existing behavior).
+     */
+    private deriveNodeKeys;
+}
+
+/**
+ * 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='hs' → type='socks5').
+         */
+        mode: 'hs' | 'direct';
+        /** SOCKS5 proxy URL (must be socks5h://) — required when mode='hs'. */
+        socksProxy?: string;
+        /**
+         * Externally reachable BTP URL the connector advertises to peers.
+         * Required when mode='hs' 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;
+    /** Connector v3.7.0+ (toon-protocol/connector#73). Counts packets accepted
+     *  via the self-delivery code path (route nextHop === connector's own
+     *  nodeId). Older connectors omit this field — default to 0 at consumers. */
+    packetsLocallyDelivered?: 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;
+        /** Connector v3.7.0+ — see MetricsPeerEntry.packetsLocallyDelivered. */
+        packetsLocallyDelivered?: 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[];
+}
+/**
+ * Channel summary entry from GET /admin/channels on the connector's adminApi port.
+ * Mirrors `ChannelSummary` from `@toon-protocol/connector`
+ * (packages/connector/src/http/admin-api.ts ChannelSummary at v3.x).
+ *
+ * `status` is kept as `string` (not a union) because the connector's enum may
+ * grow without warning — the contract canary catches shape drift, not enum domain.
+ */
+interface ChannelSummary {
+    channelId: string;
+    peerId: string;
+    chain: string;
+    status: string;
+    deposit: string;
+    lastActivity: string;
+}
+/**
+ * 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';
+}
+/**
+ * Response from GET /admin/hs-hostname on the connector's adminApi port.
+ * Mirrors the connector v3.5.0+ `HsHostnameResponse` (Story 44.1 / AC FR35).
+ * Both fields are null while the .anyone hidden-service bootstrap is in
+ * progress; both become non-null once the descriptor is published.
+ */
+interface HsHostnameResponse {
+    hostname: string | null;
+    publishedAt: string | null;
+}
+
+/**
+ * Per-asset earnings row from GET /admin/earnings.json (endpoint added in connector v3.2.0).
+ * Mirrors `AdminEarningsByAsset` from `@toon-protocol/connector` admin-api.
+ *
+ * Cumulative amounts are decimal-string bigints (JSON-safe for any asset scale).
+ * `claimsReceivedTotal` tracks value received from the peer (they paid us);
+ * `claimsSentTotal` tracks value forwarded to the peer (they earned).
+ */
+interface AssetEarnings {
+    assetCode: string;
+    assetScale: number;
+    claimsReceivedTotal: string;
+    claimsSentTotal: string;
+    netBalance: string;
+    lastClaimAt: string | null;
+}
+/**
+ * Per-peer earnings entry from GET /admin/earnings.json.
+ * Mirrors `AdminEarningsJsonPeer` from
+ * `@toon-protocol/connector packages/connector/src/http/admin-api.ts:278-281`.
+ */
+interface PeerEarnings {
+    peerId: string;
+    byAsset: AssetEarnings[];
+}
+/**
+ * Connector fee rollup from GET /admin/earnings.json.
+ * Mirrors `AdminEarningsConnectorFee` from
+ * `@toon-protocol/connector packages/connector/src/http/admin-api.ts:283-287`.
+ */
+interface ConnectorFeeEntry {
+    assetCode: string;
+    assetScale: number;
+    total: string;
+}
+/**
+ * A single recent claim entry from GET /admin/earnings.json.
+ * Mirrors `AdminEarningsRecentClaim` from
+ * `@toon-protocol/connector packages/connector/src/http/admin-api.ts:289-296`.
+ */
+interface RecentClaim {
+    peerId: string;
+    assetCode: string;
+    assetScale: number;
+    amount: string;
+    direction: 'inbound' | 'outbound';
+    at: string;
+}
+/**
+ * Typed wrapper around the connector's wire-level `timestamp: string` field.
+ * The connector's `AdminEarningsJsonResponse` carries a plain ISO-8601 string
+ * (`packages/connector/src/http/admin-api.ts:298-304`). Townhouse wraps it as
+ * a value object so dashboard consumers have a typed handle and the field can
+ * be extended (`epoch?`, `timezone?`) without breaking callers.
+ *
+ * `ConnectorAdminClient.getEarnings()` performs the wrap on the way out:
+ * `timestamp: { iso: rawString }`.
+ */
+interface EarningsTimestamp {
+    iso: string;
+}
+/**
+ * Response from GET /admin/earnings.json on the connector's adminApi port.
+ * Mirrors `AdminEarningsJsonResponse` from
+ * `@toon-protocol/connector packages/connector/src/http/admin-api.ts:298-304`.
+ *
+ * NOTE: The connector's wire shape carries `timestamp: string`. Townhouse's
+ * `getEarnings()` adapts it to `timestamp: EarningsTimestamp` (value object).
+ *
+ * Returns HTTP 503 when the connector is started without settlement config
+ * (accountManager / claimReceiver not wired). Townhouse's apex always wires
+ * both; 503 in production indicates connector misconfiguration.
+ */
+interface EarningsResponse {
+    uptimeSeconds: number;
+    peers: PeerEarnings[];
+    connectorFees: ConnectorFeeEntry[];
+    recentClaims: RecentClaim[];
+    timestamp: EarningsTimestamp;
+}
+
+/**
+ * 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);
+    /** Public read of the configured base URL (used by drill-command probes to derive a sibling client). */
+    getBaseUrl(): string;
+    /**
+     * GET /health on the admin-API port — checks HTTP reachability of the
+     * connector without validating the rich HealthStatus shape. Use this from
+     * the drill-command health probe when only the admin URL is available
+     * (port 9401), not the healthCheckPort (8080). The admin server's /health
+     * returns `{status:'healthy', service:'admin-api', nodeId, timestamp}` —
+     * a different shape from `getHealth()`'s validator. This method returns
+     * a coarse status from a 200 response and reads `nodeId` if present.
+     *
+     * @throws Error when connector is unreachable or returns non-2xx.
+     */
+    pingAdminLive(): Promise<{
+        status: 'healthy';
+        nodeId?: string;
+    }>;
+    /**
+     * 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/hs-hostname — returns the connector's published .anyone hidden-service
+     * hostname (Epic 45 / Story 44.1). Returns 200 with {hostname, publishedAt} both
+     * possibly null while bootstrap is in progress, both non-null once anon publishes.
+     * Returns 503 when the connector is anon-disabled (anon.enabled: false in config).
+     *
+     * @throws Error('connector is anon-disabled (HTTP 503)') on 503 — caller can match
+     *   on this exact prefix for actionable diagnostics.
+     * @throws Error on non-200/503 status, network error, or shape-validation failure.
+     */
+    getHsHostname(): Promise<HsHostnameResponse>;
+    /**
+     * 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/earnings.json — returns the connector's per-peer per-asset
+     * earnings projection, mirroring `AdminEarningsJsonResponse` (connector v3.2.0+).
+     *
+     * Source of truth: @toon-protocol/connector
+     *   packages/connector/src/http/admin-api.ts:1864-1945
+     *
+     * Returns HTTP 503 when the connector is started without settlement config
+     * (accountManager / claimReceiver not wired). Townhouse's apex always wires
+     * both; 503 in production indicates connector misconfiguration.
+     *
+     * Wire-shape adaptation: the connector's `timestamp: string` field is
+     * wrapped into `{ iso: string }` on the way out (EarningsTimestamp).
+     *
+     * @throws Error when connector is not running, returns non-200, or shape is invalid
+     */
+    getEarnings(): Promise<EarningsResponse>;
+    /**
+     * 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 /admin/channels — returns the connector's payment-channel summaries
+     * across all registered chain providers. Multi-chain: one entry per channel
+     * regardless of chain.
+     *
+     * @throws Error when connector is not running, returns non-200, or shape is invalid
+     */
+    getChannels(): Promise<ChannelSummary[]>;
+    /**
+     * POST /admin/peers — register (or re-register, idempotent) a child peer
+     * with the connector. Used by the boot reconciler (Story 46.1) to
+     * re-register peers present in `nodes.yaml` but missing from the
+     * connector's runtime peer roster (e.g., after a connector restart).
+     *
+     * The connector's POST /admin/peers handler treats a POST whose `id`
+     * matches an existing peer as a re-registration (no-op for the peer
+     * itself; routes are appended). A POST with a new `id` triggers
+     * `addPeer()` and BTP connection setup.
+     *
+     * @param input.id - peer identifier (matches `nodes.yaml`'s `peerId` and
+     *   the connector's `PeerStatus.id`).
+     * @param input.url - BTP WebSocket URL the connector dials. MUST start
+     *   with `ws://` or `wss://` (the connector validates this).
+     * @param input.authToken - shared auth token; pass empty string for
+     *   internal Townhouse peers (no auth).
+     * @param input.routes - optional ILP route prefixes to register against
+     *   this peer. The reconciler passes the peer's ilpAddress.
+     * @param input.transport - optional per-peer transport selection
+     *   (connector >= 3.6.2). `'direct'` forces the connector to bypass the
+     *   global SOCKS5 transport for this peer, even when the apex itself
+     *   runs in `transport.type: socks5` mode. Required for Docker-sibling
+     *   peers in HS mode — the anon SOCKS5 proxy cannot resolve internal
+     *   Docker hostnames. When omitted, the peer inherits the connector's
+     *   global transport (back-compat with pre-3.6.2 connectors).
+     *
+     * @throws Error on non-2xx response, timeout, or connection refused.
+     */
+    registerPeer(input: {
+        id: string;
+        url: string;
+        authToken: string;
+        routes?: {
+            prefix: string;
+            priority?: number;
+        }[];
+        transport?: 'direct' | 'socks5';
+        relation?: 'parent' | 'peer' | 'child';
+    }): Promise<void>;
+    /**
+     * DELETE /admin/peers/:peerId?removeRoutes=true — deregister a child peer.
+     *
+     * Idempotent: a 404 from the connector (peer already removed) is treated as
+     * success so callers can safely use this as a rollback step without knowing
+     * whether the peer was ever registered.
+     *
+     * `removeRoutes=true` is always sent so the connector drops the ILP routing
+     * entries for this peer along with the BTP connection config.
+     *
+     * @throws Error on empty peerId (rejected at client, no network request made)
+     * @throws Error on non-2xx/404 response, timeout, or connection refused
+     */
+    removePeer(peerId: string): Promise<void>;
+    /**
+     * 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;
+}
+
+/**
+ * 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.
+ */
+
+interface RunDockerOptions {
+    timeout?: number;
+    maxBuffer?: number;
+    inheritStdio?: boolean;
+    /** Override the subprocess env. Defaults to process.env when omitted. */
+    env?: NodeJS.ProcessEnv;
+}
+type ExecFileAsyncSignature = (file: string, args: readonly string[], options?: RunDockerOptions) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Error thrown by DockerOrchestrator HS-path failures (Story 45.3).
+ * Carries the failed-service name + subprocess diagnostics so CLI consumers
+ * (Story 45.4) can render Sally's failure-state copy library (UX-DR5).
+ */
+declare class OrchestratorError extends Error {
+    readonly service?: string;
+    readonly exitCode?: number;
+    readonly stderr?: string;
+    constructor(message: string, options?: {
+        service?: string;
+        exitCode?: number;
+        stderr?: string;
+        cause?: Error;
+    });
+}
+/**
+ * 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;
+    private readonly profile;
+    private readonly composePath;
+    private readonly execFileAsync;
+    private readonly adminClientFactory;
+    constructor(docker: Docker, config: TownhouseConfig, walletManager?: WalletManager, options?: {
+        profile?: ComposeProfile;
+        composePath?: string;
+        execFileAsync?: ExecFileAsyncSignature;
+        adminClientFactory?: (baseUrl: string, timeoutMs: number) => ConnectorAdminClient;
+    });
+    /**
+     * Orchestrate full startup sequence. Branches on profile:
+     * - 'dev' (default): dockerode-based, preserves existing dev-stack behavior
+     * - 'hs': docker compose subprocess + HS hostname readiness gate
+     * - 'direct': docker compose subprocess + connector /health readiness gate
+     */
+    up(profiles: NodeType[]): Promise<void>;
+    private upDev;
+    /**
+     * Narrow `this.composePath` to a definite string. The constructor enforces
+     * this invariant for `profile: 'hs'`; this helper exists so the HS-path
+     * methods don't need a non-null assertion (lint-clean) and so a constructor
+     * regression surfaces as an `OrchestratorError` rather than a `TypeError`.
+     */
+    private requireComposePath;
+    /**
+     * validate that composePath is absolute and exists on disk before
+     * passing it to any subprocess call. Defence-in-depth — callers pass paths
+     * from materializeComposeTemplate so this should never fire in normal use.
+     */
+    private validateComposePath;
+    /**
+     * Shared compose `up -d` for the compose-driven profiles ('hs', 'direct').
+     * Validates the composePath, builds the profile-gated args, and runs
+     * `docker compose up -d`, surfacing failures the same way for both profiles.
+     * Does NOT apply any readiness gate — the caller layers that on (HS hostname
+     * for 'hs'; connector /health for 'direct').
+     */
+    private composeUp;
+    /** HS-mode startup: shell out to `docker compose up -d`, wait for HS hostname. */
+    private upHs;
+    /**
+     * Direct-mode startup: shell out to `docker compose up -d`, then gate on the
+     * connector's admin `/health` being reachable (no HS hostname to wait for).
+     *
+     * Readiness probe choice: a plain `:3000` BTP WebSocket-upgrade probe is
+     * awkward to do portably (it needs a ws client + the BTP auth handshake), so
+     * — as the plan permits — readiness here is the connector admin `/health`
+     * returning 200 (via `ConnectorAdminClient.pingAdminLive`, the same admin
+     * client the HS path uses). The compose healthcheck already gates the BTP
+     * port: docker only reports the connector `healthy` once its admin `/health`
+     * (port 9401) responds, and the connector binds its BTP server (:3000) and
+     * admin server together at boot, so a healthy admin endpoint implies the BTP
+     * listener is up. We poll the admin endpoint from the host (the host-mapped
+     * 127.0.0.1:9401) rather than inspecting container health so the gate works
+     * even when invoked against a remote daemon.
+     */
+    private upDirect;
+    /**
+     * Poll the connector admin `/health` (host-mapped 127.0.0.1:<adminPort>) until
+     * it returns 200 or the deadline elapses. Used as the direct-mode readiness
+     * gate. Uses a monotonic clock so suspend/resume cannot stretch the timeout.
+     */
+    private waitForConnectorHealth;
+    /**
+     * Parse Docker Compose stderr for failed-service names and emit a
+     * containerState event per failed service so callers see the failure via
+     * the same channel dev-mode uses (AC #6 — "for each failed service
+     * identified, it emits..."). When no pattern matches, emit a single
+     * fallback event with name `'compose-up'`.
+     */
+    private surfaceComposeFailure;
+    private waitForHsHostname;
+    /**
+     * 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[]): Promise<void>;
+    /**
+     * Hot-add a node after initial startup.
+     * Starts the node container, then restarts the connector with updated peer list.
+     */
+    addNode(type: NodeType): Promise<void>;
+    /**
+     * Hot-remove a node.
+     * Stops the node container, then restarts the connector with updated peer list.
+     */
+    removeNode(type: NodeType): Promise<void>;
+    /**
+     * Graceful shutdown. Branches on profile:
+     * - 'dev' (default): dockerode-based teardown
+     * - 'hs': docker compose subprocess
+     */
+    down(): Promise<void>;
+    private downDev;
+    private downHs;
+    /**
+     * 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[]): Promise<void>;
+    /**
+     * Pull a single image by its reference (tag or digest form).
+     *
+     * Skips the pull when the image already exists locally (matches against
+     * both RepoTags and RepoDigests so digest-form refs like
+     * `ghcr.io/toon-protocol/town@sha256:abc...` are found correctly).
+     * Throws `OrchestratorError` on pull failure.
+     */
+    pullImage(image: string): Promise<void>;
+    /**
+     * Start a child peer node via `docker compose --profile <type> up -d <type>`.
+     *
+     * HS-profile only — throws `OrchestratorError` when called on the dev profile.
+     *
+     * The `env` parameter supplies the per-node wallet secrets (e.g.
+     * `TOWN_SECRET_KEY`, `MILL_MNEMONIC`). It is layered on top of `process.env`
+     * so that PATH, HOME, and other process-level env vars are preserved for the
+     * docker CLI subprocess.
+     *
+     * Logging guard: the caller (nodes-lifecycle route) must NOT log the `env`
+     * argument — it contains secret keys and the wallet mnemonic.
+     */
+    startNodeViaCompose(type: NodeType, env: Record<string, string>): Promise<void>;
+    /**
+     * Stop and remove a child peer node via `docker compose stop` + `rm -f`.
+     *
+     * HS-profile only — throws `OrchestratorError` when called on the dev profile.
+     * Idempotent: stderr patterns indicating the service/container is already gone
+     * (`'no such service'`, `'no containers to remove'`, `'No such container'`)
+     * are treated as success so callers can run this as a rollback without
+     * worrying about the container's prior state.
+     */
+    stopNodeViaCompose(type: NodeType): 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.
+     */
+    /**
+     * Ensure the relay hidden-service sidecar is running (HS mode). Forwards the
+     * relay `.anyone` HS to the town container's Nostr port (7100) so external
+     * clients can READ over the hidden service. Idempotent: a no-op if already
+     * running; recreates a stale/exited one. The keypair persists in a named
+     * volume → stable address across `hs down`/`up`. Requires the town container
+     * to exist (the sidecar resolves its DNS at boot), so call it AFTER the town
+     * is (re)started.
+     */
+    ensureRelaySidecar(): Promise<void>;
+    /**
+     * Read the relay sidecar's published `.anyone` hostname (it writes the file
+     * once anon finishes bootstrapping). Polls until the file is non-empty or
+     * `timeoutMs` elapses; returns null on timeout. The file already contains the
+     * routable `.anyone` address (no scheme mapping needed).
+     */
+    getRelayHsHostname(timeoutMs?: number): Promise<string | null>;
+    /** Stop + remove the relay sidecar (called before `hs down`'s compose down). */
+    removeRelaySidecar(): Promise<void>;
+    /**
+     * 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.
+     *
+     * Async because the DVM path may need to derive an RSA-4096 Arweave key
+     * via `walletManager.ensureArweaveKey('dvm')` — that derivation takes
+     * 5–30s on first call per unlocked wallet (cached thereafter).
+     */
+    private buildNodeEnv;
+    /**
+     * Follow a Docker pull stream and emit progress events.
+     */
+    private followPullProgress;
+}
+
+export { type ApiConfig as A, type BandwidthStats as B, type ComposeLoaderOptions as C, DockerOrchestrator as D, type EncryptedWallet as E, type WalletConfig as F, type WalletManagerConfig as G, type HealthCheckOptions as H, type WalletState as I, loadComposeTemplate as J, materializeComposeTemplate as K, type LoggingConfig as L, type MetricsPeerEntry as M, type NodeType as N, OrchestratorError as O, type PacketLogEntry as P, type RecentClaim as R, type SolanaChainProvider as S, type TownhouseConfig as T, WalletManager as W, type ConnectorRuntimeConfig as a, ConnectorAdminClient as b, type ChainProviderEntry as c, type ChainType as d, ComposeLoaderError as e, type ComposeProfile as f, type ConnectorConfig as g, type ContainerSpec as h, type DerivedNodeKeys as i, type DvmNodeConfig as j, type EvmChainProvider as k, type HealthResponse as l, type HsHostnameResponse as m, type MetricsResponse as n, type MillNodeConfig as o, type MinaChainProvider as p, type NodeKeyInfo as q, type NodeKeys as r, type NodesConfig as s, type OrchestratorEvents as t, type PacketLogFilter as u, type PeerEntry as v, type PeerStatus as w, type PeersResponse as x, type TownNodeConfig as y, type TransportConfig as z };