@cogcoin/client 1.1.5 → 1.1.7

package/dist/bitcoind/managed-runtime/bitcoind-status.js

@@ -0,0 +1,44 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveManagedServicePaths } from "../service-paths.js";
+import { readJsonFileIfPresent } from "./status.js";
+export async function listManagedBitcoindStatusCandidates(options) {
+    const candidates = new Map();
+    const addCandidate = async (statusPath, allowDataDirMismatch = false) => {
+        const status = await readJsonFileIfPresent(statusPath);
+        if (status === null) {
+            return;
+        }
+        if (!allowDataDirMismatch && status.dataDir !== options.dataDir) {
+            return;
+        }
+        candidates.set(statusPath, status);
+    };
+    await addCandidate(options.expectedStatusPath, true);
+    try {
+        const entries = await readdir(options.runtimeRoot, {
+            withFileTypes: true,
+        });
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const statusPath = join(options.runtimeRoot, entry.name, "bitcoind-status.json");
+            if (statusPath === options.expectedStatusPath) {
+                continue;
+            }
+            await addCandidate(statusPath);
+        }
+    }
+    catch {
+        // Missing runtime roots are handled by returning no candidates.
+    }
+    return [...candidates.entries()].map(([statusPath, status]) => ({
+        statusPath,
+        status,
+    }));
+}
+export async function readManagedBitcoindObservedStatus(options) {
+    const paths = resolveManagedServicePaths(options.dataDir, options.walletRootId);
+    return readJsonFileIfPresent(paths.bitcoindStatusPath);
+}

package/dist/bitcoind/managed-runtime/indexer-policy.d.ts

@@ -0,0 +1,34 @@
+import type { WalletIndexerStatus } from "../../wallet/read/types.js";
+import type { IndexerSnapshotHandle, IndexerSnapshotPayload } from "../indexer-daemon.js";
+import { type ManagedIndexerDaemonObservedStatus, type ManagedIndexerDaemonStatus, type ManagedIndexerTruthSource } from "../types.js";
+import { buildManagedIndexerStatusFromSnapshotHandle } from "./status.js";
+import type { IndexerDaemonProbeDecision, ManagedIndexerDaemonProbeResult, ManagedIndexerSnapshotLike } from "./types.js";
+type IndexerRuntimeIdentityLike = {
+    serviceApiVersion: string;
+    schemaVersion: string;
+    walletRootId: string;
+    daemonInstanceId: string;
+    processId: number | null;
+    startedAtUnixMs: number;
+    state?: ManagedIndexerDaemonStatus["state"] | string;
+};
+export declare function validateIndexerRuntimeIdentity(identity: IndexerRuntimeIdentityLike, expectedWalletRootId: string): void;
+export declare function validateIndexerDaemonStatus(status: ManagedIndexerDaemonObservedStatus, expectedWalletRootId: string): void;
+export declare function validateIndexerSnapshotHandle(handle: IndexerSnapshotHandle, expectedWalletRootId: string): void;
+export declare function validateIndexerSnapshotPayload(payload: IndexerSnapshotPayload, handle: IndexerSnapshotHandle, expectedWalletRootId: string): void;
+export declare function mapIndexerDaemonValidationError<TClient>(error: unknown, status: ManagedIndexerDaemonObservedStatus): ManagedIndexerDaemonProbeResult<TClient>;
+export declare function mapIndexerDaemonTransportError<TClient>(error: unknown): ManagedIndexerDaemonProbeResult<TClient>;
+export declare function isStaleIndexerDaemonVersion(status: ManagedIndexerDaemonObservedStatus | null, expectedBinaryVersion: string | null | undefined): boolean;
+export declare function resolveIndexerDaemonProbeDecision<TClient>(options: {
+    probe: ManagedIndexerDaemonProbeResult<TClient>;
+    expectedBinaryVersion: string | null | undefined;
+}): IndexerDaemonProbeDecision;
+export declare function deriveManagedIndexerWalletStatus(options: {
+    daemonStatus: ManagedIndexerDaemonStatus | null;
+    observedStatus?: ManagedIndexerDaemonObservedStatus | null;
+    snapshot: ManagedIndexerSnapshotLike | null;
+    source: ManagedIndexerTruthSource;
+    now: number;
+    startupError: string | null;
+}): WalletIndexerStatus;
+export { buildManagedIndexerStatusFromSnapshotHandle };

package/dist/bitcoind/managed-runtime/indexer-policy.js

@@ -0,0 +1,200 @@
+import { compareSemver, parseSemver } from "../../semver.js";
+import { INDEXER_DAEMON_SCHEMA_VERSION, INDEXER_DAEMON_SERVICE_API_VERSION, } from "../types.js";
+import { buildManagedIndexerStatusFromSnapshotHandle, resolveManagedIndexerStatusProjection } from "./status.js";
+const STALE_HEARTBEAT_THRESHOLD_MS = 15_000;
+function isUnreachableIndexerDaemonError(error) {
+    if (error instanceof Error) {
+        if (error.message === "indexer_daemon_connection_closed"
+            || error.message === "indexer_daemon_request_timeout"
+            || error.message === "indexer_daemon_protocol_error") {
+            return false;
+        }
+        if ("code" in error) {
+            const code = error.code;
+            return code === "ENOENT" || code === "ECONNREFUSED" || code === "ECONNRESET";
+        }
+    }
+    return false;
+}
+export function validateIndexerRuntimeIdentity(identity, expectedWalletRootId) {
+    void expectedWalletRootId;
+    if (identity.serviceApiVersion !== INDEXER_DAEMON_SERVICE_API_VERSION) {
+        throw new Error("indexer_daemon_service_version_mismatch");
+    }
+    // Managed indexer daemons are adopted across wallet roots when the runtime
+    // is otherwise compatible. Wallet-root ownership remains advisory here.
+    if (identity.schemaVersion !== INDEXER_DAEMON_SCHEMA_VERSION || identity.state === "schema-mismatch") {
+        throw new Error("indexer_daemon_schema_mismatch");
+    }
+}
+export function validateIndexerDaemonStatus(status, expectedWalletRootId) {
+    validateIndexerRuntimeIdentity(status, expectedWalletRootId);
+}
+export function validateIndexerSnapshotHandle(handle, expectedWalletRootId) {
+    validateIndexerRuntimeIdentity(handle, expectedWalletRootId);
+}
+export function validateIndexerSnapshotPayload(payload, handle, expectedWalletRootId) {
+    validateIndexerRuntimeIdentity(payload, expectedWalletRootId);
+    if (payload.token !== handle.token
+        || payload.daemonInstanceId !== handle.daemonInstanceId
+        || payload.processId !== handle.processId
+        || payload.startedAtUnixMs !== handle.startedAtUnixMs
+        || payload.snapshotSeq !== handle.snapshotSeq
+        || payload.tipHeight !== handle.tipHeight
+        || payload.tipHash !== handle.tipHash
+        || payload.openedAtUnixMs !== handle.openedAtUnixMs) {
+        throw new Error("indexer_daemon_snapshot_identity_mismatch");
+    }
+    if (payload.tip === null) {
+        if (payload.tipHeight !== null || payload.tipHash !== null) {
+            throw new Error("indexer_daemon_snapshot_identity_mismatch");
+        }
+    }
+    else if (payload.tip.height !== payload.tipHeight || payload.tip.blockHashHex !== payload.tipHash) {
+        throw new Error("indexer_daemon_snapshot_identity_mismatch");
+    }
+}
+export function mapIndexerDaemonValidationError(error, status) {
+    return {
+        compatibility: error instanceof Error
+            ? error.message === "indexer_daemon_service_version_mismatch"
+                ? "service-version-mismatch"
+                : "schema-mismatch"
+            : "protocol-error",
+        status,
+        client: null,
+        error: error instanceof Error ? error.message : "indexer_daemon_protocol_error",
+    };
+}
+export function mapIndexerDaemonTransportError(error) {
+    return {
+        compatibility: isUnreachableIndexerDaemonError(error) ? "unreachable" : "protocol-error",
+        status: null,
+        client: null,
+        error: isUnreachableIndexerDaemonError(error)
+            ? null
+            : error instanceof Error
+                ? "indexer_daemon_protocol_error"
+                : "indexer_daemon_protocol_error",
+    };
+}
+export function isStaleIndexerDaemonVersion(status, expectedBinaryVersion) {
+    if (status === null || expectedBinaryVersion === null || expectedBinaryVersion === undefined) {
+        return false;
+    }
+    if (parseSemver(expectedBinaryVersion) === null) {
+        return false;
+    }
+    const comparison = compareSemver(status.binaryVersion, expectedBinaryVersion);
+    return comparison === null || comparison < 0;
+}
+export function resolveIndexerDaemonProbeDecision(options) {
+    if (options.probe.compatibility === "compatible") {
+        return {
+            action: isStaleIndexerDaemonVersion(options.probe.status, options.expectedBinaryVersion)
+                ? "replace"
+                : "attach",
+            error: null,
+        };
+    }
+    if (options.probe.compatibility === "unreachable") {
+        return {
+            action: "start",
+            error: null,
+        };
+    }
+    return {
+        action: "reject",
+        error: options.probe.error ?? "indexer_daemon_protocol_error",
+    };
+}
+function mapIndexerStartupError(message) {
+    switch (message) {
+        case "indexer_daemon_start_timeout":
+            return {
+                health: "starting",
+                message: "Indexer daemon is still starting.",
+            };
+        case "indexer_daemon_service_version_mismatch":
+            return {
+                health: "service-version-mismatch",
+                message: "The live indexer daemon is running an incompatible service API version.",
+            };
+        case "indexer_daemon_schema_mismatch":
+            return {
+                health: "schema-mismatch",
+                message: "The live indexer daemon is using an incompatible sqlite schema.",
+            };
+        case "indexer_daemon_wallet_root_mismatch":
+            return {
+                health: "wallet-root-mismatch",
+                message: "The live indexer daemon belongs to a different wallet root.",
+            };
+        case "indexer_daemon_protocol_error":
+            return {
+                health: "unavailable",
+                message: "The live indexer daemon socket responded with an invalid or incomplete protocol exchange.",
+            };
+        case "indexer_daemon_background_follow_recovery_failed":
+            return {
+                health: "failed",
+                message: "The managed indexer daemon could not recover automatic background follow.",
+            };
+        default:
+            return {
+                health: "unavailable",
+                message,
+            };
+    }
+}
+export function deriveManagedIndexerWalletStatus(options) {
+    const projection = resolveManagedIndexerStatusProjection({
+        daemonStatus: options.daemonStatus,
+        observedStatus: options.observedStatus,
+        snapshot: options.snapshot,
+        source: options.source,
+    });
+    const createResult = (health, message) => ({
+        health,
+        status: projection.status,
+        message,
+        snapshotTip: projection.snapshotTip,
+        source: projection.source,
+        daemonInstanceId: projection.daemonInstanceId,
+        snapshotSeq: projection.snapshotSeq,
+        openedAtUnixMs: projection.openedAtUnixMs,
+    });
+    if (options.startupError !== null) {
+        const mapped = mapIndexerStartupError(options.startupError);
+        return createResult(mapped.health, mapped.message);
+    }
+    if (projection.status === null) {
+        return createResult("unavailable", "Indexer daemon is unavailable.");
+    }
+    if ((options.now - projection.status.heartbeatAtUnixMs) > STALE_HEARTBEAT_THRESHOLD_MS) {
+        return createResult("stale-heartbeat", "Indexer daemon heartbeat is stale.");
+    }
+    if (projection.status.state === "schema-mismatch") {
+        return createResult("schema-mismatch", projection.status.lastError ?? "Indexer daemon sqlite schema is incompatible.");
+    }
+    if (projection.status.state === "failed") {
+        return createResult("failed", projection.status.lastError ?? "Indexer daemon refresh failed.");
+    }
+    if (projection.status.state === "service-version-mismatch") {
+        return createResult("service-version-mismatch", "Indexer daemon service API is incompatible.");
+    }
+    if (options.snapshot === null) {
+        if (projection.status.state === "reorging") {
+            return createResult("reorging", "Indexer daemon is replaying a reorg and refreshing the coherent snapshot.");
+        }
+        return createResult(projection.status.state === "catching-up" ? "catching-up" : "starting", "Indexer snapshot is not ready yet.");
+    }
+    if (projection.status.state === "catching-up") {
+        return createResult("catching-up", "Indexer daemon is still catching up to the managed Bitcoin tip.");
+    }
+    if (projection.status.state === "reorging") {
+        return createResult("reorging", "Indexer daemon is replaying a reorg and refreshing the coherent snapshot.");
+    }
+    return createResult("synced", null);
+}
+export { buildManagedIndexerStatusFromSnapshotHandle };

package/dist/bitcoind/managed-runtime/indexer-runtime.d.ts

@@ -0,0 +1,15 @@
+import type { ManagedIndexerDaemonObservedStatus } from "../types.js";
+import type { ManagedIndexerDaemonProbeResult, ManagedIndexerRuntimeOptionsLike, ManagedIndexerRuntimePathsLike, ManagedRuntimeLockLike } from "./types.js";
+type ManagedIndexerRuntimeDependencies<TOptions, TClient> = {
+    getPaths(options: TOptions): ManagedIndexerRuntimePathsLike;
+    probeDaemon(options: TOptions, paths: ManagedIndexerRuntimePathsLike): Promise<ManagedIndexerDaemonProbeResult<TClient>>;
+    requestBackgroundFollow(client: TClient, observedStatus: ManagedIndexerDaemonObservedStatus | null): Promise<TClient>;
+    closeClient(client: TClient): Promise<void>;
+    acquireStartLock(options: TOptions, paths: ManagedIndexerRuntimePathsLike): Promise<ManagedRuntimeLockLike>;
+    startDaemon(options: TOptions, paths: ManagedIndexerRuntimePathsLike): Promise<TClient>;
+    stopWithLockHeld(options: TOptions, paths: ManagedIndexerRuntimePathsLike, processId: number | null): Promise<unknown>;
+    isLockBusyError(error: unknown): boolean;
+    sleep(ms: number): Promise<void>;
+};
+export declare function attachOrStartManagedIndexerRuntime<TOptions extends ManagedIndexerRuntimeOptionsLike, TClient>(options: TOptions, dependencies: ManagedIndexerRuntimeDependencies<TOptions, TClient>): Promise<TClient>;
+export {};

package/dist/bitcoind/managed-runtime/indexer-runtime.js

@@ -0,0 +1,82 @@
+import { resolveIndexerDaemonProbeDecision } from "./indexer-policy.js";
+async function waitForManagedIndexerRuntime(options, dependencies, paths) {
+    const deadline = Date.now() + options.startupTimeoutMs;
+    while (Date.now() < deadline) {
+        const probe = await dependencies.probeDaemon(options, paths);
+        if (probe.compatibility === "compatible" && probe.client !== null) {
+            await dependencies.closeClient(probe.client).catch(() => undefined);
+            return;
+        }
+        if (probe.compatibility !== "unreachable") {
+            throw new Error(probe.error ?? "indexer_daemon_protocol_error");
+        }
+        await dependencies.sleep(250);
+    }
+    throw new Error("indexer_daemon_start_timeout");
+}
+export async function attachOrStartManagedIndexerRuntime(options, dependencies) {
+    const paths = dependencies.getPaths(options);
+    const existingProbe = await dependencies.probeDaemon(options, paths);
+    const existingDecision = resolveIndexerDaemonProbeDecision({
+        probe: existingProbe,
+        expectedBinaryVersion: options.expectedBinaryVersion ?? null,
+    });
+    if (existingDecision.action === "attach" && existingProbe.client !== null) {
+        try {
+            return await dependencies.requestBackgroundFollow(existingProbe.client, existingProbe.status);
+        }
+        catch {
+            await dependencies.closeClient(existingProbe.client).catch(() => undefined);
+        }
+    }
+    if (existingDecision.action === "replace" && existingProbe.client !== null) {
+        await dependencies.closeClient(existingProbe.client).catch(() => undefined);
+    }
+    if (existingDecision.action === "reject") {
+        throw new Error(existingDecision.error ?? "indexer_daemon_protocol_error");
+    }
+    try {
+        const lock = await dependencies.acquireStartLock(options, paths);
+        try {
+            const liveProbe = await dependencies.probeDaemon(options, paths);
+            const liveDecision = resolveIndexerDaemonProbeDecision({
+                probe: liveProbe,
+                expectedBinaryVersion: options.expectedBinaryVersion ?? null,
+            });
+            if (liveDecision.action === "attach" && liveProbe.client !== null) {
+                try {
+                    return await dependencies.requestBackgroundFollow(liveProbe.client, liveProbe.status);
+                }
+                catch {
+                    await dependencies.closeClient(liveProbe.client).catch(() => undefined);
+                    await dependencies.stopWithLockHeld(options, paths, liveProbe.status?.processId ?? null);
+                }
+            }
+            else if (liveDecision.action === "replace" && liveProbe.client !== null) {
+                await dependencies.closeClient(liveProbe.client).catch(() => undefined);
+                await dependencies.stopWithLockHeld(options, paths, liveProbe.status?.processId ?? null);
+            }
+            else if (liveDecision.action === "reject") {
+                throw new Error(liveDecision.error ?? "indexer_daemon_protocol_error");
+            }
+            const daemon = await dependencies.startDaemon(options, paths);
+            try {
+                return await dependencies.requestBackgroundFollow(daemon, null);
+            }
+            catch (error) {
+                await dependencies.closeClient(daemon).catch(() => undefined);
+                throw new Error("indexer_daemon_background_follow_recovery_failed", { cause: error });
+            }
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    catch (error) {
+        if (dependencies.isLockBusyError(error)) {
+            await waitForManagedIndexerRuntime(options, dependencies, paths);
+            return attachOrStartManagedIndexerRuntime(options, dependencies);
+        }
+        throw error;
+    }
+}

package/dist/bitcoind/managed-runtime/status.d.ts

@@ -0,0 +1,11 @@
+import type { IndexerSnapshotHandle } from "../indexer-daemon.js";
+import { type ManagedIndexerDaemonObservedStatus, type ManagedIndexerDaemonStatus, type ManagedIndexerTruthSource } from "../types.js";
+import type { ManagedIndexerSnapshotLike, ManagedIndexerStatusProjection } from "./types.js";
+export declare function readJsonFileIfPresent<T>(filePath: string): Promise<T | null>;
+export declare function buildManagedIndexerStatusFromSnapshotHandle(handle: IndexerSnapshotHandle): ManagedIndexerDaemonStatus;
+export declare function resolveManagedIndexerStatusProjection(options: {
+    daemonStatus: ManagedIndexerDaemonStatus | null;
+    observedStatus?: ManagedIndexerDaemonObservedStatus | null;
+    snapshot: ManagedIndexerSnapshotLike | null;
+    source: ManagedIndexerTruthSource;
+}): ManagedIndexerStatusProjection;

package/dist/bitcoind/managed-runtime/status.js

@@ -0,0 +1,59 @@
+import { readFile } from "node:fs/promises";
+import { INDEXER_DAEMON_SCHEMA_VERSION, INDEXER_DAEMON_SERVICE_API_VERSION, } from "../types.js";
+export async function readJsonFileIfPresent(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export function buildManagedIndexerStatusFromSnapshotHandle(handle) {
+    return {
+        serviceApiVersion: INDEXER_DAEMON_SERVICE_API_VERSION,
+        binaryVersion: handle.binaryVersion,
+        buildId: handle.buildId,
+        updatedAtUnixMs: Math.max(handle.heartbeatAtUnixMs, handle.openedAtUnixMs),
+        walletRootId: handle.walletRootId,
+        daemonInstanceId: handle.daemonInstanceId,
+        schemaVersion: INDEXER_DAEMON_SCHEMA_VERSION,
+        state: handle.state,
+        processId: handle.processId,
+        startedAtUnixMs: handle.startedAtUnixMs,
+        heartbeatAtUnixMs: handle.heartbeatAtUnixMs,
+        ipcReady: true,
+        rpcReachable: handle.rpcReachable,
+        coreBestHeight: handle.coreBestHeight,
+        coreBestHash: handle.coreBestHash,
+        appliedTipHeight: handle.appliedTipHeight,
+        appliedTipHash: handle.appliedTipHash,
+        snapshotSeq: handle.snapshotSeq,
+        backlogBlocks: handle.backlogBlocks,
+        reorgDepth: handle.reorgDepth,
+        lastAppliedAtUnixMs: handle.lastAppliedAtUnixMs,
+        activeSnapshotCount: handle.activeSnapshotCount,
+        lastError: handle.lastError,
+        backgroundFollowActive: handle.backgroundFollowActive,
+        bootstrapPhase: handle.bootstrapPhase,
+        bootstrapProgress: handle.bootstrapProgress,
+        cogcoinSyncHeight: handle.cogcoinSyncHeight,
+        cogcoinSyncTargetHeight: handle.cogcoinSyncTargetHeight,
+    };
+}
+export function resolveManagedIndexerStatusProjection(options) {
+    const status = options.source === "lease"
+        ? options.daemonStatus
+        : options.observedStatus ?? options.daemonStatus;
+    const source = status === null && options.snapshot === null ? "none" : options.source;
+    return {
+        status,
+        source,
+        snapshotTip: options.snapshot?.tip ?? null,
+        daemonInstanceId: options.snapshot?.daemonInstanceId ?? status?.daemonInstanceId ?? null,
+        snapshotSeq: options.snapshot?.snapshotSeq ?? status?.snapshotSeq ?? null,
+        openedAtUnixMs: options.snapshot?.openedAtUnixMs ?? null,
+    };
+}

package/dist/bitcoind/managed-runtime/types.d.ts

@@ -0,0 +1,77 @@
+import type { ClientTip } from "../../types.js";
+import type { ManagedServicePaths } from "../service-paths.js";
+import type { ManagedBitcoindObservedStatus, ManagedIndexerDaemonObservedStatus, ManagedIndexerTruthSource } from "../types.js";
+import type { WalletBitcoindStatus, WalletIndexerStatus, WalletNodeStatus, WalletServiceHealth, WalletSnapshotView } from "../../wallet/read/types.js";
+export type ManagedBitcoindServiceCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "unreachable" | "protocol-error";
+export interface ManagedBitcoindServiceProbeResult {
+    compatibility: ManagedBitcoindServiceCompatibility;
+    status: ManagedBitcoindObservedStatus | null;
+    error: string | null;
+}
+export interface ManagedBitcoindStatusCandidate {
+    status: ManagedBitcoindObservedStatus;
+    statusPath: string;
+}
+export type IndexerDaemonCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "schema-mismatch" | "unreachable" | "protocol-error";
+export interface ManagedIndexerDaemonProbeResult<TClient> {
+    compatibility: IndexerDaemonCompatibility;
+    status: ManagedIndexerDaemonObservedStatus | null;
+    client: TClient | null;
+    error: string | null;
+}
+export interface ManagedBitcoindProbeDecision {
+    action: "attach" | "start" | "reject";
+    error: string | null;
+}
+export interface IndexerDaemonProbeDecision {
+    action: "attach" | "replace" | "start" | "reject";
+    error: string | null;
+}
+export interface ManagedRuntimeLockLike {
+    release(): Promise<void>;
+}
+export type ManagedBitcoindRuntimePathsLike = ManagedServicePaths;
+export type ManagedIndexerRuntimePathsLike = ManagedServicePaths;
+export interface ManagedBitcoindRuntimeOptionsLike {
+    dataDir: string;
+    walletRootId: string;
+    startupTimeoutMs: number;
+}
+export interface ManagedIndexerRuntimeOptionsLike {
+    dataDir: string;
+    walletRootId: string;
+    startupTimeoutMs: number;
+    shutdownTimeoutMs?: number;
+    expectedBinaryVersion?: string | null;
+}
+export interface ManagedIndexerSnapshotLike {
+    tip: ClientTip | null;
+    daemonInstanceId?: string | null;
+    snapshotSeq?: string | null;
+    openedAtUnixMs?: number | null;
+}
+export interface ManagedIndexerStatusProjection {
+    status: ManagedIndexerDaemonObservedStatus | null;
+    source: ManagedIndexerTruthSource;
+    snapshotTip: ClientTip | null;
+    daemonInstanceId: string | null;
+    snapshotSeq: string | null;
+    openedAtUnixMs: number | null;
+}
+export interface ManagedWalletNodeConnection<TNodeHandle, TRpc> {
+    handle: TNodeHandle | null;
+    rpc: TRpc | null;
+    status: WalletNodeStatus | null;
+    observedStatus: ManagedBitcoindObservedStatus | null;
+    error: string | null;
+}
+export interface ManagedWalletReadServiceBundle<TNodeHandle, TRpc, TDaemonClient> {
+    node: ManagedWalletNodeConnection<TNodeHandle, TRpc>;
+    bitcoind: WalletBitcoindStatus;
+    nodeHealth: WalletServiceHealth;
+    nodeMessage: string | null;
+    daemonClient: TDaemonClient | null;
+    indexer: WalletIndexerStatus;
+    snapshot: WalletSnapshotView | null;
+    close(): Promise<void>;
+}

package/dist/bitcoind/node.d.ts

@@ -1,8 +1,8 @@
 import { resolveDefaultBitcoindDataDirForTesting } from "../app-paths.js";
-import { BitcoinRpcClient } from "./rpc.js";
+import { BitcoinRpcClient, type RpcTransportOptions } from "./rpc.js";
 import type { BitcoindRpcConfig, InternalManagedBitcoindOptions, ManagedBitcoindNodeHandle } from "./types.js";
 export { resolveDefaultBitcoindDataDirForTesting };
 export declare function buildBitcoindArgsForTesting(options: InternalManagedBitcoindOptions, rpcPort: number, zmqPort: number, p2pPort: number): string[];
 export declare function validateNodeConfigForTesting(rpcClient: BitcoinRpcClient, expectedChain: "main" | "regtest", zmqEndpoint: string): Promise<void>;
 export declare function launchManagedBitcoindNode(options: InternalManagedBitcoindOptions): Promise<ManagedBitcoindNodeHandle>;
-export declare function createRpcClient(config: BitcoindRpcConfig): BitcoinRpcClient;
+export declare function createRpcClient(config: BitcoindRpcConfig, options?: RpcTransportOptions): BitcoinRpcClient;

package/dist/bitcoind/node.js

@@ -217,6 +217,6 @@ export async function launchManagedBitcoindNode(options) {
         },
     };
 }
-export function createRpcClient(config) {
-    return new BitcoinRpcClient(config.url, config.cookieFile);
+export function createRpcClient(config, options = {}) {
+    return new BitcoinRpcClient(config.url, config.cookieFile, options);
 }

package/dist/bitcoind/rpc.d.ts

@@ -7,9 +7,10 @@ interface RpcResponsePayload {
     readonly statusCode: number;
     readonly bodyText: string;
 }
-interface RpcTransportOptions {
+export interface RpcTransportOptions {
     fetchImpl?: typeof fetch;
     requestTimeoutMs?: number;
+    abortSignal?: AbortSignal;
     requestImpl?: (request: {
         url: URL;
         payload: RpcRequestPayload;

package/dist/bitcoind/rpc.js

@@ -1,17 +1,20 @@
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { readFile } from "node:fs/promises";
+const DEFAULT_MANAGED_RPC_REQUEST_TIMEOUT_MS = 30_000;
 export class BitcoinRpcClient {
     #url;
     #cookieFile;
     #fetchImpl;
     #requestTimeoutMs;
+    #abortSignal;
     #requestImpl;
     constructor(url, cookieFile, options = {}) {
         this.#url = url;
         this.#cookieFile = cookieFile;
         this.#fetchImpl = options.fetchImpl ?? fetch;
-        this.#requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
+        this.#requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_MANAGED_RPC_REQUEST_TIMEOUT_MS;
+        this.#abortSignal = options.abortSignal;
         this.#requestImpl = options.requestImpl ?? this.#sendNodeRequest.bind(this);
     }
     async call(method, params = []) {
@@ -25,20 +28,67 @@ export class BitcoinRpcClient {
     async #callAtUrl(urlString, method, params = []) {
         const payload = await this.#buildRequestPayload(method, params);
         let response;
-        const abortSignal = AbortSignal.timeout(this.#requestTimeoutMs);
+        const requestSignal = this.#createRequestSignal();
         try {
             response = await this.#fetchImpl(urlString, {
                 method: "POST",
                 headers: payload.headers,
                 body: payload.body,
-                signal: abortSignal,
+                signal: requestSignal.signal,
             });
         }
         catch (error) {
+            if (this.#abortSignal?.aborted) {
+                const reason = this.#abortSignal.reason;
+                if (reason instanceof Error) {
+                    throw reason;
+                }
+            }
             throw new Error(this.#describeTransportError(urlString, method, error), { cause: error });
         }
+        finally {
+            requestSignal.dispose();
+        }
         return this.#parseResponse(method, response.status, await response.text());
     }
+    #createRequestSignal() {
+        const timeoutSignal = AbortSignal.timeout(this.#requestTimeoutMs);
+        if (this.#abortSignal === undefined) {
+            return {
+                signal: timeoutSignal,
+                dispose() { },
+            };
+        }
+        const controller = new AbortController();
+        const handleAbort = (source) => {
+            controller.abort(source.reason);
+        };
+        const forwardTimeout = () => {
+            handleAbort(timeoutSignal);
+        };
+        const forwardAbort = () => {
+            handleAbort(this.#abortSignal);
+        };
+        if (timeoutSignal.aborted) {
+            handleAbort(timeoutSignal);
+        }
+        else {
+            timeoutSignal.addEventListener("abort", forwardTimeout, { once: true });
+        }
+        if (this.#abortSignal.aborted) {
+            handleAbort(this.#abortSignal);
+        }
+        else {
+            this.#abortSignal.addEventListener("abort", forwardAbort, { once: true });
+        }
+        return {
+            signal: controller.signal,
+            dispose: () => {
+                timeoutSignal.removeEventListener("abort", forwardTimeout);
+                this.#abortSignal?.removeEventListener("abort", forwardAbort);
+            },
+        };
+    }
     async #buildRequestPayload(method, params) {
         let cookie;
         try {