@cogcoin/client 1.1.6 → 1.1.7

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@1.1.6` is the reference Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
+`@cogcoin/client@1.1.7` is the reference Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
 
 Use Node 22 or newer.
 
@@ -135,7 +135,7 @@ The installed `cogcoin` command covers the first-party local wallet and node wor
 - sync and service commands such as `status`, `sync`, `follow`, `bitcoin start`, `bitcoin stop`, `bitcoin status`, `indexer start`, `indexer stop`, and `indexer status`
 - domain and field commands such as `register`, `anchor`, `show`, `domains`, `fields`, `buy`, `sell`, and `transfer`
 - COG and reputation commands such as `send`, `cog lock`, `claim`, `reclaim`, `rep give`, and `rep revoke`
-- mining commands such as `mine`, `mine start`, `mine stop`, `mine status`, `mine log`, `mine setup`, `mine prompt`, and `mine prompt list`
+- mining commands such as `mine`, `mine status`, `mine log`, `mine setup`, `mine prompt`, and `mine prompt list`
 
 Use `cogcoin mine prompt <domain>` to set or clear a per-domain mining prompt override for one anchored root domain, and `cogcoin mine prompt list` to inspect the current per-domain prompt state alongside the global fallback prompt.
 Interactive text invocations periodically check the npm registry for newer `@cogcoin/client` releases and print `npm install -g @cogcoin/client` when a newer version is available.

package/dist/bitcoind/indexer-daemon.js

@@ -5,7 +5,8 @@ import { fileURLToPath } from "node:url";
 import net from "node:net";
 import { acquireFileLock, FileLockBusyError } from "../wallet/fs/lock.js";
 import { writeRuntimeStatusFile } from "../wallet/fs/status-file.js";
-import { buildManagedIndexerStatusFromSnapshotHandle, mapIndexerDaemonTransportError, mapIndexerDaemonValidationError, resolveIndexerDaemonProbeDecision, validateIndexerDaemonStatus, validateIndexerSnapshotHandle, validateIndexerSnapshotPayload, } from "./managed-runtime/indexer-policy.js";
+import { buildManagedIndexerStatusFromSnapshotHandle, mapIndexerDaemonTransportError, mapIndexerDaemonValidationError, validateIndexerDaemonStatus, validateIndexerSnapshotHandle, validateIndexerSnapshotPayload, } from "./managed-runtime/indexer-policy.js";
+import { attachOrStartManagedIndexerRuntime } from "./managed-runtime/indexer-runtime.js";
 import { readJsonFileIfPresent } from "./managed-runtime/status.js";
 import {} from "./types.js";
 import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "./service-paths.js";
@@ -347,86 +348,35 @@ export async function attachOrStartIndexerDaemon(options) {
             shutdownTimeoutMs: options.shutdownTimeoutMs,
         });
     };
-    const existingProbe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
-    const existingDecision = resolveIndexerDaemonProbeDecision({
-        probe: existingProbe,
+    return attachOrStartManagedIndexerRuntime({
+        ...options,
+        walletRootId,
+        startupTimeoutMs,
         expectedBinaryVersion,
-    });
-    if (existingDecision.action === "attach" && existingProbe.client !== null) {
-        try {
-            return await requestBackgroundFollow(existingProbe.client, existingProbe.status);
-        }
-        catch {
-            await existingProbe.client.close().catch(() => undefined);
-        }
-    }
-    if (existingDecision.action === "replace" && existingProbe.client !== null) {
-        await existingProbe.client.close().catch(() => undefined);
-    }
-    if (existingDecision.action === "reject") {
-        throw new Error(existingDecision.error ?? "indexer_daemon_protocol_error");
-    }
-    try {
-        const lock = await acquireFileLock(paths.indexerDaemonLockPath, {
+    }, {
+        getPaths: (runtimeOptions) => resolveManagedServicePaths(runtimeOptions.dataDir, runtimeOptions.walletRootId),
+        probeDaemon: async (runtimeOptions, runtimePaths) => probeIndexerDaemonAtSocket(runtimePaths.indexerDaemonSocketPath, runtimeOptions.walletRootId),
+        requestBackgroundFollow,
+        closeClient: async (client) => {
+            await client.close();
+        },
+        acquireStartLock: async (runtimeOptions, runtimePaths) => acquireFileLock(runtimePaths.indexerDaemonLockPath, {
             purpose: "indexer-daemon-start",
-            walletRootId,
-            dataDir: options.dataDir,
-            databasePath: options.databasePath,
-        });
-        try {
-            const liveProbe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
-            const liveDecision = resolveIndexerDaemonProbeDecision({
-                probe: liveProbe,
-                expectedBinaryVersion,
-            });
-            if (liveDecision.action === "attach" && liveProbe.client !== null) {
-                try {
-                    return await requestBackgroundFollow(liveProbe.client, liveProbe.status);
-                }
-                catch {
-                    await liveProbe.client.close().catch(() => undefined);
-                    await stopIndexerDaemonServiceWithLockHeld({
-                        dataDir: options.dataDir,
-                        walletRootId,
-                        shutdownTimeoutMs: options.shutdownTimeoutMs,
-                        paths,
-                        processId: liveProbe.status?.processId ?? null,
-                    });
-                }
-            }
-            else if (liveDecision.action === "replace" && liveProbe.client !== null) {
-                await liveProbe.client.close().catch(() => undefined);
-                await stopIndexerDaemonServiceWithLockHeld({
-                    dataDir: options.dataDir,
-                    walletRootId,
-                    shutdownTimeoutMs: options.shutdownTimeoutMs,
-                    paths,
-                    processId: liveProbe.status?.processId ?? null,
-                });
-            }
-            else if (liveDecision.action === "reject") {
-                throw new Error(liveDecision.error ?? "indexer_daemon_protocol_error");
-            }
-            const daemon = await startDaemon();
-            try {
-                return await requestBackgroundFollow(daemon);
-            }
-            catch (error) {
-                await daemon.close().catch(() => undefined);
-                throw new Error(INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED, { cause: error });
-            }
-        }
-        finally {
-            await lock.release();
-        }
-    }
-    catch (error) {
-        if (error instanceof FileLockBusyError) {
-            await waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
-            return attachOrStartIndexerDaemon(options);
-        }
-        throw error;
-    }
+            walletRootId: runtimeOptions.walletRootId,
+            dataDir: runtimeOptions.dataDir,
+            databasePath: runtimeOptions.databasePath,
+        }),
+        startDaemon: async () => startDaemon(),
+        stopWithLockHeld: async (runtimeOptions, runtimePaths, processId) => stopIndexerDaemonServiceWithLockHeld({
+            dataDir: runtimeOptions.dataDir,
+            walletRootId: runtimeOptions.walletRootId,
+            shutdownTimeoutMs: runtimeOptions.shutdownTimeoutMs,
+            paths: resolveManagedServicePaths(runtimeOptions.dataDir, runtimeOptions.walletRootId),
+            processId,
+        }),
+        isLockBusyError: (error) => error instanceof FileLockBusyError,
+        sleep,
+    });
 }
 export async function stopIndexerDaemonService(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;

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

@@ -0,0 +1,20 @@
+import type { ManagedBitcoindObservedStatus } from "../types.js";
+import type { ManagedBitcoindRuntimeOptionsLike, ManagedBitcoindRuntimePathsLike, ManagedBitcoindServiceProbeResult, ManagedBitcoindStatusCandidate, ManagedRuntimeLockLike } from "./types.js";
+type ManagedBitcoindRuntimeDependencies<TOptions, THandle> = {
+    getPaths(options: TOptions): ManagedBitcoindRuntimePathsLike;
+    listStatusCandidates(options: {
+        dataDir: string;
+        runtimeRoot: string;
+        expectedStatusPath: string;
+    }): Promise<ManagedBitcoindStatusCandidate[]>;
+    isProcessAlive(processId: number | null): Promise<boolean>;
+    probeStatusCandidate(status: ManagedBitcoindObservedStatus, options: TOptions, runtimeRoot: string): Promise<ManagedBitcoindServiceProbeResult>;
+    attachExisting(options: TOptions): Promise<THandle | null>;
+    acquireStartLock(options: TOptions, paths: ManagedBitcoindRuntimePathsLike): Promise<ManagedRuntimeLockLike>;
+    startService(options: TOptions, paths: ManagedBitcoindRuntimePathsLike): Promise<THandle>;
+    isLockBusyError(error: unknown): boolean;
+    sleep(ms: number): Promise<void>;
+};
+export declare function probeManagedBitcoindRuntime<TOptions extends ManagedBitcoindRuntimeOptionsLike>(options: TOptions, dependencies: Pick<ManagedBitcoindRuntimeDependencies<TOptions, never>, "getPaths" | "listStatusCandidates" | "isProcessAlive" | "probeStatusCandidate">): Promise<ManagedBitcoindServiceProbeResult>;
+export declare function attachOrStartManagedBitcoindRuntime<TOptions extends ManagedBitcoindRuntimeOptionsLike, THandle>(options: TOptions, dependencies: ManagedBitcoindRuntimeDependencies<TOptions, THandle>): Promise<THandle>;
+export {};

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

@@ -0,0 +1,74 @@
+import { resolveManagedBitcoindProbeDecision } from "./bitcoind-policy.js";
+async function waitForManagedBitcoindRuntime(options, dependencies) {
+    const deadline = Date.now() + options.startupTimeoutMs;
+    while (Date.now() < deadline) {
+        const attached = await dependencies.attachExisting(options).catch(() => null);
+        if (attached !== null) {
+            return attached;
+        }
+        await dependencies.sleep(250);
+    }
+    throw new Error("managed_bitcoind_service_start_timeout");
+}
+export async function probeManagedBitcoindRuntime(options, dependencies) {
+    const paths = dependencies.getPaths(options);
+    const candidates = await dependencies.listStatusCandidates({
+        dataDir: options.dataDir,
+        runtimeRoot: paths.runtimeRoot,
+        expectedStatusPath: paths.bitcoindStatusPath,
+    });
+    const expectedCandidate = candidates.find((candidate) => candidate.statusPath === paths.bitcoindStatusPath) ?? null;
+    for (const candidate of candidates) {
+        if (!await dependencies.isProcessAlive(candidate.status.processId)) {
+            continue;
+        }
+        return dependencies.probeStatusCandidate(candidate.status, options, paths.walletRuntimeRoot);
+    }
+    return {
+        compatibility: "unreachable",
+        status: expectedCandidate?.status ?? candidates[0]?.status ?? null,
+        error: null,
+    };
+}
+export async function attachOrStartManagedBitcoindRuntime(options, dependencies) {
+    const existingProbe = await probeManagedBitcoindRuntime(options, dependencies);
+    const existingDecision = resolveManagedBitcoindProbeDecision(existingProbe);
+    if (existingDecision.action === "attach") {
+        const existing = await dependencies.attachExisting(options);
+        if (existing !== null) {
+            return existing;
+        }
+        throw new Error("managed_bitcoind_protocol_error");
+    }
+    if (existingDecision.action === "reject") {
+        throw new Error(existingDecision.error ?? "managed_bitcoind_protocol_error");
+    }
+    const paths = dependencies.getPaths(options);
+    try {
+        const lock = await dependencies.acquireStartLock(options, paths);
+        try {
+            const liveProbe = await probeManagedBitcoindRuntime(options, dependencies);
+            const liveDecision = resolveManagedBitcoindProbeDecision(liveProbe);
+            if (liveDecision.action === "attach") {
+                const reattached = await dependencies.attachExisting(options);
+                if (reattached !== null) {
+                    return reattached;
+                }
+                throw new Error("managed_bitcoind_protocol_error");
+            }
+            if (liveDecision.action === "reject") {
+                throw new Error(liveDecision.error ?? "managed_bitcoind_protocol_error");
+            }
+            return await dependencies.startService(options, paths);
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    catch (error) {
+        if (dependencies.isLockBusyError(error)) {
+            return waitForManagedBitcoindRuntime(options, dependencies);
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +1,11 @@
+import type { ManagedBitcoindObservedStatus } from "../types.js";
+import type { ManagedBitcoindStatusCandidate } from "./types.js";
+export declare function listManagedBitcoindStatusCandidates(options: {
+    dataDir: string;
+    runtimeRoot: string;
+    expectedStatusPath: string;
+}): Promise<ManagedBitcoindStatusCandidate[]>;
+export declare function readManagedBitcoindObservedStatus(options: {
+    dataDir: string;
+    walletRootId: string;
+}): Promise<ManagedBitcoindObservedStatus | null>;

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-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/types.d.ts

@@ -1,11 +1,17 @@
 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;
@@ -21,6 +27,23 @@ 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;
@@ -35,3 +58,20 @@ export interface ManagedIndexerStatusProjection {
     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 {