@cogcoin/client 1.1.9 → 1.1.10

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@1.1.9` 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.10` 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.
 

package/dist/bitcoind/managed-bitcoind-service-config.d.ts

@@ -0,0 +1,13 @@
+import type { BitcoindRpcConfig, BitcoindZmqConfig, ManagedBitcoindRuntimeConfig } from "./types.js";
+import type { ManagedBitcoindServiceOptions } from "./managed-bitcoind-service-types.js";
+export declare const LOCAL_HOST = "127.0.0.1";
+export declare const SUPPORTED_BITCOIND_VERSION = "30.2.0";
+export declare function resolveManagedBitcoindDbcacheMiB(totalRamBytes: number): number;
+export declare function detectManagedBitcoindDbcacheMiB(): number;
+export declare function verifyManagedBitcoindVersion(bitcoindPath: string): Promise<void>;
+export declare function getManagedBitcoindCookieFile(dataDir: string, chain: "main" | "regtest"): string;
+export declare function resolveManagedBitcoindRuntimeConfig(statusPath: string, configPath: string, options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindRuntimeConfig>;
+export declare function writeBitcoinConfForTesting(filePath: string, options: ManagedBitcoindServiceOptions, runtimeConfig: ManagedBitcoindRuntimeConfig): Promise<void>;
+export declare function buildManagedServiceArgsForTesting(options: ManagedBitcoindServiceOptions, runtimeConfig: ManagedBitcoindRuntimeConfig): string[];
+export declare function waitForManagedBitcoindCookie(cookieFile: string, timeoutMs: number, sleepImpl: (ms: number) => Promise<void>): Promise<void>;
+export type { BitcoindRpcConfig, BitcoindZmqConfig, };

package/dist/bitcoind/managed-bitcoind-service-config.js

@@ -0,0 +1,165 @@
+import { execFile } from "node:child_process";
+import { access, constants, mkdir } from "node:fs/promises";
+import { totalmem } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import net from "node:net";
+import { writeFileAtomic } from "../wallet/fs/atomic.js";
+import { readJsonFileIfPresent } from "./managed-runtime/status.js";
+const execFileAsync = promisify(execFile);
+export const LOCAL_HOST = "127.0.0.1";
+export const SUPPORTED_BITCOIND_VERSION = "30.2.0";
+const DEFAULT_DBCACHE_MIB = 450;
+const GIB = 1024 ** 3;
+export function resolveManagedBitcoindDbcacheMiB(totalRamBytes) {
+    if (!Number.isFinite(totalRamBytes) || totalRamBytes <= 0) {
+        return DEFAULT_DBCACHE_MIB;
+    }
+    if (totalRamBytes < 8 * GIB) {
+        return 450;
+    }
+    if (totalRamBytes < 16 * GIB) {
+        return 768;
+    }
+    if (totalRamBytes < 32 * GIB) {
+        return 1024;
+    }
+    return 2048;
+}
+export function detectManagedBitcoindDbcacheMiB() {
+    try {
+        return resolveManagedBitcoindDbcacheMiB(totalmem());
+    }
+    catch {
+        return DEFAULT_DBCACHE_MIB;
+    }
+}
+async function allocatePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, LOCAL_HOST, () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                server.close();
+                reject(new Error("bitcoind_port_allocation_failed"));
+                return;
+            }
+            const { port } = address;
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve(port);
+            });
+        });
+        server.on("error", reject);
+    });
+}
+async function allocateDistinctPort(reserved) {
+    while (true) {
+        const port = await allocatePort();
+        if (!reserved.has(port)) {
+            reserved.add(port);
+            return port;
+        }
+    }
+}
+export async function verifyManagedBitcoindVersion(bitcoindPath) {
+    const { stdout } = await execFileAsync(bitcoindPath, ["-nosettings=1", "-version"]);
+    if (!stdout.includes("Bitcoin Core") || !stdout.includes(`v${SUPPORTED_BITCOIND_VERSION}`)) {
+        throw new Error("bitcoind_version_unsupported");
+    }
+}
+export function getManagedBitcoindCookieFile(dataDir, chain) {
+    return chain === "main" ? join(dataDir, ".cookie") : join(dataDir, chain, ".cookie");
+}
+export async function resolveManagedBitcoindRuntimeConfig(statusPath, configPath, options) {
+    const previousStatus = await readJsonFileIfPresent(statusPath);
+    const previousConfig = await readJsonFileIfPresent(configPath);
+    const reserved = new Set();
+    const rpcPort = options.rpcPort
+        ?? previousStatus?.rpc.port
+        ?? previousConfig?.rpc?.port
+        ?? await allocateDistinctPort(reserved);
+    reserved.add(rpcPort);
+    const zmqPort = options.zmqPort
+        ?? previousStatus?.zmq.port
+        ?? previousConfig?.zmqPort
+        ?? await allocateDistinctPort(reserved);
+    reserved.add(zmqPort);
+    const p2pPort = options.p2pPort
+        ?? previousStatus?.p2pPort
+        ?? previousConfig?.p2pPort
+        ?? await allocateDistinctPort(reserved);
+    return {
+        chain: options.chain,
+        rpc: {
+            url: `http://${LOCAL_HOST}:${rpcPort}`,
+            cookieFile: getManagedBitcoindCookieFile(options.dataDir ?? "", options.chain),
+            port: rpcPort,
+        },
+        zmqPort,
+        p2pPort,
+        dbcacheMiB: detectManagedBitcoindDbcacheMiB(),
+        getblockArchiveEndHeight: options.getblockArchiveEndHeight ?? null,
+        getblockArchiveSha256: options.getblockArchiveSha256 ?? null,
+    };
+}
+export async function writeBitcoinConfForTesting(filePath, options, runtimeConfig) {
+    const walletDir = join(options.dataDir ?? "", "wallets");
+    await mkdir(dirname(filePath), { recursive: true });
+    await mkdir(walletDir, { recursive: true });
+    const lines = [
+        "server=1",
+        "prune=0",
+        "dnsseed=1",
+        "listen=0",
+        `dbcache=${runtimeConfig.dbcacheMiB}`,
+        `rpcbind=${LOCAL_HOST}`,
+        `rpcallowip=${LOCAL_HOST}`,
+        `rpcport=${runtimeConfig.rpc.port}`,
+        `port=${runtimeConfig.p2pPort}`,
+        `zmqpubhashblock=tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
+        `walletdir=${walletDir}`,
+    ];
+    await writeFileAtomic(filePath, `${lines.join("\n")}\n`, { mode: 0o600 });
+}
+export function buildManagedServiceArgsForTesting(options, runtimeConfig) {
+    const walletDir = join(options.dataDir ?? "", "wallets");
+    const args = [
+        "-nosettings=1",
+        `-datadir=${options.dataDir}`,
+        `-rpcbind=${LOCAL_HOST}`,
+        `-rpcallowip=${LOCAL_HOST}`,
+        `-rpcport=${runtimeConfig.rpc.port}`,
+        `-port=${runtimeConfig.p2pPort}`,
+        `-zmqpubhashblock=tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
+        `-walletdir=${walletDir}`,
+        "-server=1",
+        "-prune=0",
+        "-dnsseed=1",
+        "-listen=0",
+        `-dbcache=${runtimeConfig.dbcacheMiB}`,
+    ];
+    if (options.chain === "regtest") {
+        args.push("-chain=regtest");
+    }
+    if (options.getblockArchivePath !== undefined && options.getblockArchivePath !== null) {
+        args.push(`-loadblock=${options.getblockArchivePath}`);
+    }
+    return args;
+}
+export async function waitForManagedBitcoindCookie(cookieFile, timeoutMs, sleepImpl) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            await access(cookieFile, constants.R_OK);
+            return;
+        }
+        catch {
+            await sleepImpl(250);
+        }
+    }
+    throw new Error("bitcoind_cookie_timeout");
+}

package/dist/bitcoind/managed-bitcoind-service-lifecycle.d.ts

@@ -0,0 +1,28 @@
+import type { ManagedBitcoindServiceProbeResult } from "./managed-runtime/types.js";
+import { resolveManagedServicePaths } from "./service-paths.js";
+import { type ManagedBitcoindNodeHandle } from "./types.js";
+import type { ManagedBitcoindServiceOptions, ManagedBitcoindServiceStopResult } from "./managed-bitcoind-service-types.js";
+export declare function stopManagedBitcoindServiceWithLockHeld(options: {
+    dataDir: string;
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+    paths?: ReturnType<typeof resolveManagedServicePaths>;
+}): Promise<ManagedBitcoindServiceStopResult>;
+export declare function withClaimedUninitializedManagedRuntime<T>(options: {
+    dataDir: string;
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+}, callback: () => Promise<T>): Promise<T>;
+export declare function probeManagedBitcoindService(options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindServiceProbeResult>;
+export declare function attachOrStartManagedBitcoindService(options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindNodeHandle>;
+export declare function stopManagedBitcoindService(options: {
+    dataDir: string;
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+}): Promise<ManagedBitcoindServiceStopResult>;
+export declare function shutdownManagedBitcoindServiceForTesting(options: {
+    dataDir: string;
+    chain?: "main" | "regtest";
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+}): Promise<void>;

package/dist/bitcoind/managed-bitcoind-service-lifecycle.js

@@ -0,0 +1,290 @@
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { mkdir, rm } from "node:fs/promises";
+import { getBitcoindPath } from "@cogcoin/bitcoin";
+import { acquireFileLock } from "../wallet/fs/lock.js";
+import { stopIndexerDaemonServiceWithLockHeld } from "./indexer-daemon.js";
+import { readManagedBitcoindObservedStatus, listManagedBitcoindStatusCandidates } from "./managed-runtime/bitcoind-status.js";
+import { attachOrStartManagedBitcoindRuntime, probeManagedBitcoindRuntime } from "./managed-runtime/bitcoind-runtime.js";
+import { createRpcClient, validateNodeConfigForTesting } from "./node.js";
+import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "./service-paths.js";
+import { DEFAULT_MANAGED_BITCOIND_FOLLOW_POLL_INTERVAL_MS, } from "./types.js";
+import { buildManagedServiceArgsForTesting, LOCAL_HOST, resolveManagedBitcoindRuntimeConfig, SUPPORTED_BITCOIND_VERSION, verifyManagedBitcoindVersion, writeBitcoinConfForTesting, } from "./managed-bitcoind-service-config.js";
+import { DEFAULT_MANAGED_BITCOIND_SHUTDOWN_TIMEOUT_MS, DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS, FileLockBusyError, acquireManagedBitcoindFileLockWithRetry, isManagedBitcoindProcessAlive, waitForManagedBitcoindProcessExit, sleep, } from "./managed-bitcoind-service-process.js";
+import { createManagedWalletReplica, loadManagedWalletReplicaIfPresent, } from "./managed-bitcoind-service-replica.js";
+import { clearManagedBitcoindRuntimeArtifacts, createBitcoindServiceStatus, createManagedBitcoindNodeHandle, probeManagedBitcoindStatusCandidate, refreshManagedBitcoindStatus, waitForManagedBitcoindRpcReady, writeManagedBitcoindStatus, } from "./managed-bitcoind-service-status.js";
+const claimedUninitializedRuntimeKeys = new Set();
+export async function stopManagedBitcoindServiceWithLockHeld(options) {
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const paths = options.paths ?? resolveManagedServicePaths(options.dataDir, walletRootId);
+    const status = await readManagedBitcoindObservedStatus({
+        dataDir: options.dataDir,
+        walletRootId,
+    });
+    const processId = status?.processId ?? null;
+    if (status === null || processId === null || !await isManagedBitcoindProcessAlive(processId)) {
+        await clearManagedBitcoindRuntimeArtifacts(paths);
+        return {
+            status: "not-running",
+            walletRootId,
+        };
+    }
+    const rpc = createRpcClient(status.rpc);
+    try {
+        await rpc.stop();
+    }
+    catch {
+        try {
+            process.kill(processId, "SIGTERM");
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+                throw error;
+            }
+        }
+    }
+    await waitForManagedBitcoindProcessExit(processId, options.shutdownTimeoutMs ?? DEFAULT_MANAGED_BITCOIND_SHUTDOWN_TIMEOUT_MS, "managed_bitcoind_service_stop_timeout");
+    await clearManagedBitcoindRuntimeArtifacts(paths);
+    return {
+        status: "stopped",
+        walletRootId,
+    };
+}
+export async function withClaimedUninitializedManagedRuntime(options, callback) {
+    const targetWalletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const targetPaths = resolveManagedServicePaths(options.dataDir, targetWalletRootId);
+    const uninitializedPaths = resolveManagedServicePaths(options.dataDir, UNINITIALIZED_WALLET_ROOT_ID);
+    if (targetPaths.walletRuntimeRoot === uninitializedPaths.walletRuntimeRoot) {
+        return callback();
+    }
+    if (targetWalletRootId === UNINITIALIZED_WALLET_ROOT_ID) {
+        return callback();
+    }
+    const claimKey = `${options.dataDir}\n${targetWalletRootId}`;
+    if (claimedUninitializedRuntimeKeys.has(claimKey)) {
+        return callback();
+    }
+    claimedUninitializedRuntimeKeys.add(claimKey);
+    const lockTimeoutMs = options.shutdownTimeoutMs ?? DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS;
+    const bitcoindLock = await acquireManagedBitcoindFileLockWithRetry(uninitializedPaths.bitcoindLockPath, {
+        purpose: "managed-bitcoind-claim-uninitialized",
+        walletRootId: UNINITIALIZED_WALLET_ROOT_ID,
+        dataDir: options.dataDir,
+    }, lockTimeoutMs);
+    try {
+        const indexerLock = await acquireManagedBitcoindFileLockWithRetry(uninitializedPaths.indexerDaemonLockPath, {
+            purpose: "managed-indexer-claim-uninitialized",
+            walletRootId: UNINITIALIZED_WALLET_ROOT_ID,
+            dataDir: options.dataDir,
+        }, lockTimeoutMs);
+        try {
+            await stopIndexerDaemonServiceWithLockHeld({
+                dataDir: options.dataDir,
+                walletRootId: UNINITIALIZED_WALLET_ROOT_ID,
+                shutdownTimeoutMs: options.shutdownTimeoutMs,
+                paths: uninitializedPaths,
+            });
+            await stopManagedBitcoindServiceWithLockHeld({
+                dataDir: options.dataDir,
+                walletRootId: UNINITIALIZED_WALLET_ROOT_ID,
+                shutdownTimeoutMs: options.shutdownTimeoutMs,
+                paths: uninitializedPaths,
+            });
+            return await callback();
+        }
+        finally {
+            await indexerLock.release();
+        }
+    }
+    finally {
+        claimedUninitializedRuntimeKeys.delete(claimKey);
+        await bitcoindLock.release();
+    }
+}
+async function tryAttachExistingManagedBitcoindService(options) {
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const paths = resolveManagedServicePaths(options.dataDir ?? "", walletRootId);
+    const probe = await probeManagedBitcoindService(options);
+    if (probe.compatibility !== "compatible" || probe.status === null) {
+        return null;
+    }
+    const refreshed = await refreshManagedBitcoindStatus(probe.status, paths, options);
+    return createManagedBitcoindNodeHandle({
+        status: refreshed,
+        paths,
+        serviceOptions: options,
+        ownership: "attached",
+        stopService: stopManagedBitcoindService,
+    });
+}
+export async function probeManagedBitcoindService(options) {
+    const resolvedOptions = {
+        ...options,
+        dataDir: options.dataDir ?? "",
+        walletRootId: options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID,
+        startupTimeoutMs: options.startupTimeoutMs ?? DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS,
+    };
+    return probeManagedBitcoindRuntime(resolvedOptions, {
+        getPaths: (runtimeOptions) => resolveManagedServicePaths(runtimeOptions.dataDir, runtimeOptions.walletRootId),
+        listStatusCandidates: listManagedBitcoindStatusCandidates,
+        isProcessAlive: isManagedBitcoindProcessAlive,
+        probeStatusCandidate: probeManagedBitcoindStatusCandidate,
+    });
+}
+export async function attachOrStartManagedBitcoindService(options) {
+    const resolvedOptions = {
+        ...options,
+        dataDir: options.dataDir,
+        serviceLifetime: options.serviceLifetime ?? "persistent",
+        walletRootId: options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID,
+    };
+    const startupTimeoutMs = resolvedOptions.startupTimeoutMs ?? DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS;
+    return withClaimedUninitializedManagedRuntime({
+        dataDir: resolvedOptions.dataDir ?? "",
+        walletRootId: resolvedOptions.walletRootId,
+        shutdownTimeoutMs: resolvedOptions.shutdownTimeoutMs,
+    }, async () => {
+        return attachOrStartManagedBitcoindRuntime({
+            ...resolvedOptions,
+            dataDir: resolvedOptions.dataDir ?? "",
+            walletRootId: resolvedOptions.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID,
+            startupTimeoutMs,
+        }, {
+            getPaths: (runtimeOptions) => resolveManagedServicePaths(runtimeOptions.dataDir, runtimeOptions.walletRootId),
+            listStatusCandidates: listManagedBitcoindStatusCandidates,
+            isProcessAlive: isManagedBitcoindProcessAlive,
+            probeStatusCandidate: probeManagedBitcoindStatusCandidate,
+            attachExisting: tryAttachExistingManagedBitcoindService,
+            acquireStartLock: async (runtimeOptions, paths) => acquireFileLock(paths.bitcoindLockPath, {
+                purpose: "managed-bitcoind-start",
+                walletRootId: runtimeOptions.walletRootId,
+                dataDir: runtimeOptions.dataDir,
+            }),
+            startService: async (runtimeOptions, paths) => {
+                const bitcoindPath = await getBitcoindPath();
+                await verifyManagedBitcoindVersion(bitcoindPath);
+                const binaryVersion = SUPPORTED_BITCOIND_VERSION;
+                await mkdir(runtimeOptions.dataDir, { recursive: true });
+                const startManagedProcess = async (startOptions) => {
+                    const runtimeConfig = await resolveManagedBitcoindRuntimeConfig(paths.bitcoindStatusPath, paths.bitcoindRuntimeConfigPath, startOptions);
+                    await writeBitcoinConfForTesting(paths.bitcoinConfPath, startOptions, runtimeConfig);
+                    const rpcConfig = runtimeConfig.rpc;
+                    const zmqConfig = {
+                        endpoint: `tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
+                        topic: "hashblock",
+                        port: runtimeConfig.zmqPort,
+                        pollIntervalMs: startOptions.pollIntervalMs ?? DEFAULT_MANAGED_BITCOIND_FOLLOW_POLL_INTERVAL_MS,
+                    };
+                    const spawnOptions = startOptions.serviceLifetime === "ephemeral"
+                        ? {
+                            stdio: "ignore",
+                        }
+                        : {
+                            detached: true,
+                            stdio: "ignore",
+                        };
+                    const child = spawn(bitcoindPath, buildManagedServiceArgsForTesting(startOptions, runtimeConfig), {
+                        ...spawnOptions,
+                    });
+                    if (startOptions.serviceLifetime !== "ephemeral") {
+                        child.unref();
+                    }
+                    const rpc = createRpcClient(rpcConfig);
+                    try {
+                        await waitForManagedBitcoindRpcReady(rpc, rpcConfig.cookieFile, startOptions.chain, startupTimeoutMs);
+                        await validateNodeConfigForTesting(rpc, startOptions.chain, zmqConfig.endpoint);
+                    }
+                    catch (error) {
+                        if (child.pid !== undefined) {
+                            try {
+                                process.kill(child.pid, "SIGTERM");
+                            }
+                            catch {
+                                // ignore kill failures during startup cleanup
+                            }
+                        }
+                        throw error;
+                    }
+                    const nowUnixMs = Date.now();
+                    const walletReplica = await loadManagedWalletReplicaIfPresent(rpc, startOptions.walletRootId, startOptions.dataDir);
+                    return createBitcoindServiceStatus({
+                        binaryVersion,
+                        serviceInstanceId: randomBytes(16).toString("hex"),
+                        state: "ready",
+                        processId: child.pid ?? null,
+                        walletRootId: startOptions.walletRootId,
+                        chain: startOptions.chain,
+                        dataDir: startOptions.dataDir,
+                        runtimeRoot: paths.walletRuntimeRoot,
+                        startHeight: startOptions.startHeight,
+                        rpc: rpcConfig,
+                        zmq: zmqConfig,
+                        p2pPort: runtimeConfig.p2pPort,
+                        getblockArchiveEndHeight: runtimeConfig.getblockArchiveEndHeight ?? null,
+                        getblockArchiveSha256: runtimeConfig.getblockArchiveSha256 ?? null,
+                        walletReplica,
+                        startedAtUnixMs: nowUnixMs,
+                        heartbeatAtUnixMs: nowUnixMs,
+                        lastError: walletReplica.message ?? null,
+                    });
+                };
+                let status;
+                try {
+                    status = await startManagedProcess(runtimeOptions);
+                }
+                catch (error) {
+                    if (runtimeOptions.getblockArchivePath === undefined || runtimeOptions.getblockArchivePath === null) {
+                        throw error;
+                    }
+                    status = await startManagedProcess({
+                        ...runtimeOptions,
+                        getblockArchivePath: null,
+                        getblockArchiveEndHeight: null,
+                        getblockArchiveSha256: null,
+                    });
+                }
+                await writeManagedBitcoindStatus(paths, status);
+                return createManagedBitcoindNodeHandle({
+                    status,
+                    paths: resolveManagedServicePaths(runtimeOptions.dataDir, runtimeOptions.walletRootId),
+                    serviceOptions: runtimeOptions,
+                    ownership: "started",
+                    stopService: stopManagedBitcoindService,
+                });
+            },
+            isLockBusyError: (error) => error instanceof FileLockBusyError,
+            sleep,
+        });
+    });
+}
+export async function stopManagedBitcoindService(options) {
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
+    const lock = await acquireFileLock(paths.bitcoindLockPath, {
+        purpose: "managed-bitcoind-stop",
+        walletRootId,
+        dataDir: options.dataDir,
+    });
+    try {
+        return stopManagedBitcoindServiceWithLockHeld({
+            ...options,
+            walletRootId,
+            paths,
+        });
+    }
+    finally {
+        await lock.release();
+    }
+}
+export async function shutdownManagedBitcoindServiceForTesting(options) {
+    await stopManagedBitcoindService({
+        dataDir: options.dataDir,
+        walletRootId: options.walletRootId,
+        shutdownTimeoutMs: options.shutdownTimeoutMs,
+    }).catch(async (error) => {
+        const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+        const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
+        await rm(paths.bitcoindReadyPath, { force: true }).catch(() => undefined);
+        throw error;
+    });
+}

package/dist/bitcoind/managed-bitcoind-service-process.d.ts

@@ -0,0 +1,8 @@
+import { acquireFileLock, FileLockBusyError } from "../wallet/fs/lock.js";
+export declare const DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS = 60000;
+export declare const DEFAULT_MANAGED_BITCOIND_SHUTDOWN_TIMEOUT_MS = 15000;
+export declare function sleep(ms: number): Promise<void>;
+export declare function isManagedBitcoindProcessAlive(pid: number | null): Promise<boolean>;
+export declare function waitForManagedBitcoindProcessExit(pid: number, timeoutMs: number, errorCode: string): Promise<void>;
+export declare function acquireManagedBitcoindFileLockWithRetry(lockPath: string, metadata: Parameters<typeof acquireFileLock>[1], timeoutMs: number): Promise<Awaited<ReturnType<typeof acquireFileLock>>>;
+export { FileLockBusyError };

package/dist/bitcoind/managed-bitcoind-service-process.js

@@ -0,0 +1,48 @@
+import { acquireFileLock, FileLockBusyError } from "../wallet/fs/lock.js";
+export const DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS = 60_000;
+export const DEFAULT_MANAGED_BITCOIND_SHUTDOWN_TIMEOUT_MS = 15_000;
+export function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export async function isManagedBitcoindProcessAlive(pid) {
+    if (pid === null) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+            return false;
+        }
+        return true;
+    }
+}
+export async function waitForManagedBitcoindProcessExit(pid, timeoutMs, errorCode) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!await isManagedBitcoindProcessAlive(pid)) {
+            return;
+        }
+        await sleep(250);
+    }
+    throw new Error(errorCode);
+}
+export async function acquireManagedBitcoindFileLockWithRetry(lockPath, metadata, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        try {
+            return await acquireFileLock(lockPath, metadata);
+        }
+        catch (error) {
+            if (!(error instanceof FileLockBusyError) || Date.now() >= deadline) {
+                throw error;
+            }
+            await sleep(250);
+        }
+    }
+}
+export { FileLockBusyError };

package/dist/bitcoind/managed-bitcoind-service-replica.d.ts

@@ -0,0 +1,8 @@
+import type { ManagedCoreWalletReplicaStatus } from "./types.js";
+import type { ManagedWalletReplicaRpc } from "./managed-bitcoind-service-types.js";
+export declare function getManagedBitcoindWalletReplicaName(walletRootId: string): string;
+export declare function createMissingManagedWalletReplicaStatus(walletRootId: string, message: string): ManagedCoreWalletReplicaStatus;
+export declare function loadManagedWalletReplicaIfPresent(rpc: ManagedWalletReplicaRpc, walletRootId: string, dataDir: string): Promise<ManagedCoreWalletReplicaStatus>;
+export declare function createManagedWalletReplica(rpc: ManagedWalletReplicaRpc, walletRootId: string, options?: {
+    managedWalletPassphrase?: string;
+}): Promise<ManagedCoreWalletReplicaStatus>;