@cogcoin/client 0.5.5 → 0.5.7

package/dist/bitcoind/service.js

@@ -2,12 +2,14 @@ import { randomBytes } from "node:crypto";
 import { execFile, spawn } from "node:child_process";
 import { access, constants, mkdir, readFile, readdir, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { totalmem } from "node:os";
 import { promisify } from "node:util";
 import net from "node:net";
 import { getBitcoindPath } from "@cogcoin/bitcoin";
 import { acquireFileLock, FileLockBusyError } from "../wallet/fs/lock.js";
 import { writeFileAtomic } from "../wallet/fs/atomic.js";
 import { writeRuntimeStatusFile } from "../wallet/fs/status-file.js";
+import { stopIndexerDaemonServiceWithLockHeld } from "./indexer-daemon.js";
 import { createRpcClient, validateNodeConfigForTesting } from "./node.js";
 import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "./service-paths.js";
 import { MANAGED_BITCOIND_SERVICE_API_VERSION as MANAGED_BITCOIND_SERVICE_API_VERSION_VALUE } from "./types.js";
@@ -16,6 +18,32 @@ const LOCAL_HOST = "127.0.0.1";
 const SUPPORTED_BITCOIND_VERSION = "30.2.0";
 const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 15_000;
+const DEFAULT_DBCACHE_MIB = 450;
+const claimedUninitializedRuntimeKeys = new Set();
+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;
+}
+function detectManagedBitcoindDbcacheMiB() {
+    try {
+        return resolveManagedBitcoindDbcacheMiB(totalmem());
+    }
+    catch {
+        return DEFAULT_DBCACHE_MIB;
+    }
+}
 function sleep(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
@@ -31,6 +59,20 @@ async function waitForProcessExit(pid, timeoutMs, errorCode) {
     }
     throw new Error(errorCode);
 }
+async function acquireFileLockWithRetry(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);
+        }
+    }
+}
 function getWalletReplicaName(walletRootId) {
     return `cogcoin-${walletRootId}`.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 63);
 }
@@ -184,15 +226,14 @@ async function waitForRpcReady(rpc, cookieFile, expectedChain, timeoutMs) {
     throw lastError instanceof Error ? lastError : new Error("bitcoind_rpc_timeout");
 }
 function validateManagedBitcoindStatus(status, options, runtimeRoot) {
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const legacyRuntimeRoot = join(resolveManagedServicePaths(options.dataDir ?? "", walletRootId).runtimeRoot, walletRootId);
     if (status.serviceApiVersion !== MANAGED_BITCOIND_SERVICE_API_VERSION_VALUE) {
         throw new Error("managed_bitcoind_service_version_mismatch");
     }
-    if (status.walletRootId !== (options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID)) {
-        throw new Error("managed_bitcoind_wallet_root_mismatch");
-    }
     if (status.chain !== options.chain
         || status.dataDir !== (options.dataDir ?? "")
-        || status.runtimeRoot !== runtimeRoot) {
+        || (status.runtimeRoot !== runtimeRoot && status.runtimeRoot !== legacyRuntimeRoot)) {
         throw new Error("managed_bitcoind_runtime_mismatch");
     }
 }
@@ -233,6 +274,8 @@ function createBitcoindServiceStatus(options) {
         rpc: options.rpc,
         zmq: options.zmq,
         p2pPort: options.p2pPort,
+        getblockArchiveEndHeight: options.getblockArchiveEndHeight,
+        getblockArchiveSha256: options.getblockArchiveSha256,
         walletReplica: options.walletReplica,
         startedAtUnixMs: options.startedAtUnixMs,
         heartbeatAtUnixMs: options.heartbeatAtUnixMs,
@@ -245,9 +288,7 @@ function mapManagedBitcoindValidationError(error) {
         compatibility: error instanceof Error
             ? error.message === "managed_bitcoind_service_version_mismatch"
                 ? "service-version-mismatch"
-                : error.message === "managed_bitcoind_wallet_root_mismatch"
-                    ? "wallet-root-mismatch"
-                    : "runtime-mismatch"
+                : "runtime-mismatch"
             : "protocol-error",
         status: null,
         error: error instanceof Error ? error.message : "managed_bitcoind_protocol_error",
@@ -323,6 +364,9 @@ async function resolveRuntimeConfig(statusPath, configPath, options) {
         },
         zmqPort,
         p2pPort,
+        dbcacheMiB: detectManagedBitcoindDbcacheMiB(),
+        getblockArchiveEndHeight: options.getblockArchiveEndHeight ?? null,
+        getblockArchiveSha256: options.getblockArchiveSha256 ?? null,
     };
 }
 async function writeBitcoinConf(filePath, options, runtimeConfig) {
@@ -334,6 +378,7 @@ async function writeBitcoinConf(filePath, options, runtimeConfig) {
         "prune=0",
         "dnsseed=1",
         "listen=0",
+        `dbcache=${runtimeConfig.dbcacheMiB}`,
         `rpcbind=${LOCAL_HOST}`,
         `rpcallowip=${LOCAL_HOST}`,
         `rpcport=${runtimeConfig.rpc.port}`,
@@ -358,12 +403,22 @@ function buildManagedServiceArgs(options, runtimeConfig) {
         "-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 writeBitcoinConfForTesting(filePath, options, runtimeConfig) {
+    await writeBitcoinConf(filePath, options, runtimeConfig);
+}
+export function buildManagedServiceArgsForTesting(options, runtimeConfig) {
+    return buildManagedServiceArgs(options, runtimeConfig);
+}
 function isMissingWalletError(message) {
     return message.includes("bitcoind_rpc_loadwallet_-18_")
         || message.includes("Path does not exist")
@@ -496,6 +551,8 @@ async function writeBitcoindStatus(paths, status) {
         rpc: status.rpc,
         zmqPort: status.zmq.port,
         p2pPort: status.p2pPort,
+        getblockArchiveEndHeight: status.getblockArchiveEndHeight,
+        getblockArchiveSha256: status.getblockArchiveSha256,
     });
 }
 async function clearManagedBitcoindRuntimeArtifacts(paths) {
@@ -504,15 +561,102 @@ async function clearManagedBitcoindRuntimeArtifacts(paths) {
     await rm(paths.bitcoindReadyPath, { force: true }).catch(() => undefined);
     await rm(paths.bitcoindWalletStatusPath, { force: true }).catch(() => undefined);
 }
+export async function stopManagedBitcoindServiceWithLockHeld(options) {
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const paths = options.paths ?? resolveManagedServicePaths(options.dataDir, walletRootId);
+    const status = await readJsonFile(paths.bitcoindStatusPath);
+    const processId = status?.processId ?? null;
+    if (status === null || processId === null || !await isProcessAlive(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 waitForProcessExit(processId, options.shutdownTimeoutMs ?? DEFAULT_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_STARTUP_TIMEOUT_MS;
+    const bitcoindLock = await acquireFileLockWithRetry(uninitializedPaths.bitcoindLockPath, {
+        purpose: "managed-bitcoind-claim-uninitialized",
+        walletRootId: UNINITIALIZED_WALLET_ROOT_ID,
+        dataDir: options.dataDir,
+    }, lockTimeoutMs);
+    try {
+        const indexerLock = await acquireFileLockWithRetry(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 refreshManagedBitcoindStatus(status, paths, options) {
     const nowUnixMs = Date.now();
     const rpc = createRpcClient(status.rpc);
+    const targetWalletRootId = options.walletRootId ?? status.walletRootId;
     try {
         await waitForRpcReady(rpc, status.rpc.cookieFile, status.chain, options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS);
         await validateNodeConfigForTesting(rpc, status.chain, status.zmq.endpoint);
-        const walletReplica = await loadManagedWalletReplicaIfPresent(rpc, status.walletRootId, status.dataDir);
+        const walletReplica = await loadManagedWalletReplicaIfPresent(rpc, targetWalletRootId, status.dataDir);
         const nextStatus = {
             ...status,
+            walletRootId: targetWalletRootId,
+            runtimeRoot: paths.walletRuntimeRoot,
             state: "ready",
             processId: await isProcessAlive(status.processId) ? status.processId : null,
             walletReplica,
@@ -526,6 +670,8 @@ async function refreshManagedBitcoindStatus(status, paths, options) {
     catch (error) {
         const nextStatus = {
             ...status,
+            walletRootId: targetWalletRootId,
+            runtimeRoot: paths.walletRuntimeRoot,
             state: "failed",
             processId: await isProcessAlive(status.processId) ? status.processId : null,
             heartbeatAtUnixMs: nowUnixMs,
@@ -546,6 +692,8 @@ function createNodeHandle(status, paths, options) {
         expectedChain: currentStatus.chain,
         startHeight: currentStatus.startHeight,
         dataDir: currentStatus.dataDir,
+        getblockArchiveEndHeight: currentStatus.getblockArchiveEndHeight ?? null,
+        getblockArchiveSha256: currentStatus.getblockArchiveSha256 ?? null,
         walletRootId: currentStatus.walletRootId,
         runtimeRoot: paths.walletRuntimeRoot,
         async validate() {
@@ -553,6 +701,9 @@ function createNodeHandle(status, paths, options) {
         },
         async refreshServiceStatus() {
             currentStatus = await refreshManagedBitcoindStatus(currentStatus, paths, options);
+            this.getblockArchiveEndHeight = currentStatus.getblockArchiveEndHeight ?? null;
+            this.getblockArchiveSha256 = currentStatus.getblockArchiveSha256 ?? null;
+            this.walletRootId = currentStatus.walletRootId;
             return currentStatus;
         },
         async stop() {
@@ -617,103 +768,128 @@ export async function attachOrStartManagedBitcoindService(options) {
         dataDir: options.dataDir,
         walletRootId: options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID,
     };
-    const existingProbe = await probeManagedBitcoindService(resolvedOptions);
-    if (existingProbe.compatibility === "compatible") {
-        const existing = await tryAttachExistingManagedBitcoindService(resolvedOptions);
-        if (existing !== null) {
-            return existing;
-        }
-    }
-    if (existingProbe.compatibility !== "unreachable") {
-        throw new Error(existingProbe.error ?? "managed_bitcoind_protocol_error");
-    }
-    const paths = resolveManagedServicePaths(resolvedOptions.dataDir ?? "", resolvedOptions.walletRootId);
     const startupTimeoutMs = resolvedOptions.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
-    try {
-        const lock = await acquireFileLock(paths.bitcoindLockPath, {
-            purpose: "managed-bitcoind-start",
-            walletRootId: resolvedOptions.walletRootId,
-            dataDir: resolvedOptions.dataDir,
-        });
-        try {
-            const liveProbe = await probeManagedBitcoindService(resolvedOptions);
-            if (liveProbe.compatibility === "compatible") {
-                const reattached = await tryAttachExistingManagedBitcoindService(resolvedOptions);
-                if (reattached !== null) {
-                    return reattached;
-                }
+    return withClaimedUninitializedManagedRuntime({
+        dataDir: resolvedOptions.dataDir ?? "",
+        walletRootId: resolvedOptions.walletRootId,
+        shutdownTimeoutMs: resolvedOptions.shutdownTimeoutMs,
+    }, async () => {
+        const existingProbe = await probeManagedBitcoindService(resolvedOptions);
+        if (existingProbe.compatibility === "compatible") {
+            const existing = await tryAttachExistingManagedBitcoindService(resolvedOptions);
+            if (existing !== null) {
+                return existing;
             }
-            if (liveProbe.compatibility !== "unreachable") {
-                throw new Error(liveProbe.error ?? "managed_bitcoind_protocol_error");
-            }
-            const bitcoindPath = await getBitcoindPath();
-            await verifyBitcoindVersion(bitcoindPath);
-            const binaryVersion = SUPPORTED_BITCOIND_VERSION;
-            await mkdir(resolvedOptions.dataDir ?? "", { recursive: true });
-            const runtimeConfig = await resolveRuntimeConfig(paths.bitcoindStatusPath, paths.bitcoindRuntimeConfigPath, resolvedOptions);
-            await writeBitcoinConf(paths.bitcoinConfPath, resolvedOptions, runtimeConfig);
-            const rpcConfig = runtimeConfig.rpc;
-            const zmqConfig = {
-                endpoint: `tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
-                topic: "hashblock",
-                port: runtimeConfig.zmqPort,
-                pollIntervalMs: resolvedOptions.pollIntervalMs ?? 15_000,
-            };
-            const child = spawn(bitcoindPath, buildManagedServiceArgs(resolvedOptions, runtimeConfig), {
-                detached: true,
-                stdio: "ignore",
+        }
+        if (existingProbe.compatibility !== "unreachable") {
+            throw new Error(existingProbe.error ?? "managed_bitcoind_protocol_error");
+        }
+        const paths = resolveManagedServicePaths(resolvedOptions.dataDir ?? "", resolvedOptions.walletRootId);
+        try {
+            const lock = await acquireFileLock(paths.bitcoindLockPath, {
+                purpose: "managed-bitcoind-start",
+                walletRootId: resolvedOptions.walletRootId,
+                dataDir: resolvedOptions.dataDir,
             });
-            child.unref();
-            const rpc = createRpcClient(rpcConfig);
             try {
-                await waitForRpcReady(rpc, rpcConfig.cookieFile, resolvedOptions.chain, startupTimeoutMs);
-                await validateNodeConfigForTesting(rpc, resolvedOptions.chain, zmqConfig.endpoint);
-            }
-            catch (error) {
-                if (child.pid !== undefined) {
+                const liveProbe = await probeManagedBitcoindService(resolvedOptions);
+                if (liveProbe.compatibility === "compatible") {
+                    const reattached = await tryAttachExistingManagedBitcoindService(resolvedOptions);
+                    if (reattached !== null) {
+                        return reattached;
+                    }
+                }
+                if (liveProbe.compatibility !== "unreachable") {
+                    throw new Error(liveProbe.error ?? "managed_bitcoind_protocol_error");
+                }
+                const bitcoindPath = await getBitcoindPath();
+                await verifyBitcoindVersion(bitcoindPath);
+                const binaryVersion = SUPPORTED_BITCOIND_VERSION;
+                await mkdir(resolvedOptions.dataDir ?? "", { recursive: true });
+                const startManagedProcess = async (startOptions) => {
+                    const runtimeConfig = await resolveRuntimeConfig(paths.bitcoindStatusPath, paths.bitcoindRuntimeConfigPath, startOptions);
+                    await writeBitcoinConf(paths.bitcoinConfPath, startOptions, runtimeConfig);
+                    const rpcConfig = runtimeConfig.rpc;
+                    const zmqConfig = {
+                        endpoint: `tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
+                        topic: "hashblock",
+                        port: runtimeConfig.zmqPort,
+                        pollIntervalMs: startOptions.pollIntervalMs ?? 15_000,
+                    };
+                    const child = spawn(bitcoindPath, buildManagedServiceArgs(startOptions, runtimeConfig), {
+                        detached: true,
+                        stdio: "ignore",
+                    });
+                    child.unref();
+                    const rpc = createRpcClient(rpcConfig);
                     try {
-                        process.kill(child.pid, "SIGTERM");
+                        await waitForRpcReady(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;
                     }
-                    catch {
-                        // ignore kill failures during startup cleanup
+                    const nowUnixMs = Date.now();
+                    const walletRootId = startOptions.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+                    const walletReplica = await loadManagedWalletReplicaIfPresent(rpc, walletRootId, startOptions.dataDir ?? "");
+                    return createBitcoindServiceStatus({
+                        binaryVersion,
+                        serviceInstanceId: randomBytes(16).toString("hex"),
+                        state: "ready",
+                        processId: child.pid ?? null,
+                        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(resolvedOptions);
+                }
+                catch (error) {
+                    if (resolvedOptions.getblockArchivePath === undefined || resolvedOptions.getblockArchivePath === null) {
+                        throw error;
                     }
+                    status = await startManagedProcess({
+                        ...resolvedOptions,
+                        getblockArchivePath: null,
+                        getblockArchiveEndHeight: null,
+                        getblockArchiveSha256: null,
+                    });
                 }
-                throw error;
+                await writeBitcoindStatus(paths, status);
+                return createNodeHandle(status, paths, resolvedOptions);
+            }
+            finally {
+                await lock.release();
             }
-            const nowUnixMs = Date.now();
-            const walletRootId = resolvedOptions.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
-            const walletReplica = await loadManagedWalletReplicaIfPresent(rpc, walletRootId, resolvedOptions.dataDir ?? "");
-            const status = createBitcoindServiceStatus({
-                binaryVersion,
-                serviceInstanceId: randomBytes(16).toString("hex"),
-                state: "ready",
-                processId: child.pid ?? null,
-                walletRootId,
-                chain: resolvedOptions.chain,
-                dataDir: resolvedOptions.dataDir ?? "",
-                runtimeRoot: paths.walletRuntimeRoot,
-                startHeight: resolvedOptions.startHeight,
-                rpc: rpcConfig,
-                zmq: zmqConfig,
-                p2pPort: runtimeConfig.p2pPort,
-                walletReplica,
-                startedAtUnixMs: nowUnixMs,
-                heartbeatAtUnixMs: nowUnixMs,
-                lastError: walletReplica.message ?? null,
-            });
-            await writeBitcoindStatus(paths, status);
-            return createNodeHandle(status, paths, resolvedOptions);
-        }
-        finally {
-            await lock.release();
         }
-    }
-    catch (error) {
-        if (error instanceof FileLockBusyError) {
-            return waitForManagedBitcoindService(resolvedOptions, startupTimeoutMs);
+        catch (error) {
+            if (error instanceof FileLockBusyError) {
+                return waitForManagedBitcoindService(resolvedOptions, startupTimeoutMs);
+            }
+            throw error;
         }
-        throw error;
-    }
+    });
 }
 export async function stopManagedBitcoindService(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
@@ -724,35 +900,11 @@ export async function stopManagedBitcoindService(options) {
         dataDir: options.dataDir,
     });
     try {
-        const status = await readJsonFile(paths.bitcoindStatusPath);
-        const processId = status?.processId ?? null;
-        if (status === null || processId === null || !await isProcessAlive(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 waitForProcessExit(processId, options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS, "managed_bitcoind_service_stop_timeout");
-        await clearManagedBitcoindRuntimeArtifacts(paths);
-        return {
-            status: "stopped",
+        return stopManagedBitcoindServiceWithLockHeld({
+            ...options,
             walletRootId,
-        };
+            paths,
+        });
     }
     finally {
         await lock.release();

package/dist/bitcoind/testing.d.ts

@@ -2,8 +2,8 @@ export { openManagedBitcoindClientInternal } from "./client.js";
 export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopIndexerDaemonService, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";
-export { attachOrStartManagedBitcoindService, readManagedBitcoindServiceStatusForTesting, stopManagedBitcoindService, shutdownManagedBitcoindServiceForTesting, } from "./service.js";
-export { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, createBootstrapStateForTesting, downloadSnapshotFileForTesting, loadBootstrapStateForTesting, resolveBootstrapPathsForTesting, saveBootstrapStateForTesting, validateSnapshotFileForTesting, waitForHeadersForTesting, } from "./bootstrap.js";
+export { attachOrStartManagedBitcoindService, buildManagedServiceArgsForTesting, readManagedBitcoindServiceStatusForTesting, resolveManagedBitcoindDbcacheMiB, stopManagedBitcoindService, shutdownManagedBitcoindServiceForTesting, writeBitcoinConfForTesting, } from "./service.js";
+export { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, createBootstrapStateForTesting, downloadSnapshotFileForTesting, loadBootstrapStateForTesting, prepareLatestGetblockArchiveForTesting, resolveBootstrapPathsForTesting, resolveGetblockArchivePathsForTesting, resolveReadyGetblockArchiveForTesting, saveBootstrapStateForTesting, validateSnapshotFileForTesting, waitForGetblockArchiveImportForTesting, waitForHeadersForTesting, } from "./bootstrap.js";
 export { buildBitcoindArgsForTesting, createRpcClient, launchManagedBitcoindNode, resolveDefaultBitcoindDataDirForTesting, validateNodeConfigForTesting, } from "./node.js";
 export { ManagedProgressController, TtyProgressRenderer, advanceFollowSceneStateForTesting, createFollowSceneStateForTesting, createBootstrapProgressForTesting, formatCompactFollowAgeLabelForTesting, loadBannerArtForTesting, loadScrollArtForTesting, loadTrainCarArtForTesting, loadTrainArtForTesting, loadTrainSmokeArtForTesting, formatProgressLineForTesting, formatQuoteLineForTesting, renderArtFrameForTesting, renderCompletionFrameForTesting, renderFollowFrameForTesting, renderIntroFrameForTesting, resolveCompletionMessageForTesting, resolveIntroMessageForTesting, resolveStatusFieldTextForTesting, setFollowBlockTimeForTesting, setFollowBlockTimesForTesting, syncFollowSceneStateForTesting, } from "./progress.js";
 export { WritingQuoteRotator, loadWritingQuotesForTesting, shuffleIndicesForTesting, } from "./quotes.js";

package/dist/bitcoind/testing.js

@@ -2,8 +2,8 @@ export { openManagedBitcoindClientInternal } from "./client.js";
 export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopIndexerDaemonService, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";
-export { attachOrStartManagedBitcoindService, readManagedBitcoindServiceStatusForTesting, stopManagedBitcoindService, shutdownManagedBitcoindServiceForTesting, } from "./service.js";
-export { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, createBootstrapStateForTesting, downloadSnapshotFileForTesting, loadBootstrapStateForTesting, resolveBootstrapPathsForTesting, saveBootstrapStateForTesting, validateSnapshotFileForTesting, waitForHeadersForTesting, } from "./bootstrap.js";
+export { attachOrStartManagedBitcoindService, buildManagedServiceArgsForTesting, readManagedBitcoindServiceStatusForTesting, resolveManagedBitcoindDbcacheMiB, stopManagedBitcoindService, shutdownManagedBitcoindServiceForTesting, writeBitcoinConfForTesting, } from "./service.js";
+export { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, createBootstrapStateForTesting, downloadSnapshotFileForTesting, loadBootstrapStateForTesting, prepareLatestGetblockArchiveForTesting, resolveBootstrapPathsForTesting, resolveGetblockArchivePathsForTesting, resolveReadyGetblockArchiveForTesting, saveBootstrapStateForTesting, validateSnapshotFileForTesting, waitForGetblockArchiveImportForTesting, waitForHeadersForTesting, } from "./bootstrap.js";
 export { buildBitcoindArgsForTesting, createRpcClient, launchManagedBitcoindNode, resolveDefaultBitcoindDataDirForTesting, validateNodeConfigForTesting, } from "./node.js";
 export { ManagedProgressController, TtyProgressRenderer, advanceFollowSceneStateForTesting, createFollowSceneStateForTesting, createBootstrapProgressForTesting, formatCompactFollowAgeLabelForTesting, loadBannerArtForTesting, loadScrollArtForTesting, loadTrainCarArtForTesting, loadTrainArtForTesting, loadTrainSmokeArtForTesting, formatProgressLineForTesting, formatQuoteLineForTesting, renderArtFrameForTesting, renderCompletionFrameForTesting, renderFollowFrameForTesting, renderIntroFrameForTesting, resolveCompletionMessageForTesting, resolveIntroMessageForTesting, resolveStatusFieldTextForTesting, setFollowBlockTimeForTesting, setFollowBlockTimesForTesting, syncFollowSceneStateForTesting, } from "./progress.js";
 export { WritingQuoteRotator, loadWritingQuotesForTesting, shuffleIndicesForTesting, } from "./quotes.js";

package/dist/bitcoind/types.d.ts

@@ -1,5 +1,5 @@
 import type { BitcoinBlock, Client, ClientOptions, ClientTip } from "../types.js";
-export type BootstrapPhase = "snapshot_download" | "wait_headers_for_snapshot" | "load_snapshot" | "bitcoin_sync" | "cogcoin_sync" | "follow_tip" | "paused" | "error" | "complete";
+export type BootstrapPhase = "getblock_archive_download" | "getblock_archive_import" | "snapshot_download" | "wait_headers_for_snapshot" | "load_snapshot" | "bitcoin_sync" | "cogcoin_sync" | "follow_tip" | "paused" | "error" | "complete";
 export type ProgressOutputMode = "auto" | "tty" | "none";
 export interface SnapshotMetadata {
     url: string;
@@ -17,6 +17,28 @@ export interface SnapshotChunkManifest {
     snapshotSha256: string;
     chunkSha256s: string[];
 }
+export interface GetblockArchiveManifestBlockRecord {
+    height: number;
+    blockHash: string;
+    previousBlockHash: string;
+    recordOffset: number;
+    recordLength: number;
+    rawBlockSizeBytes: number;
+}
+export interface GetblockArchiveManifest {
+    formatVersion: number;
+    chain: "main";
+    baseSnapshotHeight: number;
+    firstBlockHeight: number;
+    endHeight: number;
+    blockCount: number;
+    artifactFilename: string;
+    artifactSizeBytes: number;
+    artifactSha256: string;
+    chunkSizeBytes: number;
+    chunkSha256s: string[];
+    blocks: GetblockArchiveManifestBlockRecord[];
+}
 export interface WritingQuote {
     quote: string;
     author: string;
@@ -62,6 +84,9 @@ export interface ManagedBitcoindRuntimeConfig {
     rpc: BitcoindRpcConfig;
     zmqPort: number;
     p2pPort: number;
+    dbcacheMiB: number;
+    getblockArchiveEndHeight?: number | null;
+    getblockArchiveSha256?: string | null;
 }
 export declare const MANAGED_BITCOIND_SERVICE_API_VERSION = "cogcoin/bitcoind-service/v1";
 export type ManagedBitcoindServiceState = "starting" | "ready" | "stopping" | "failed";
@@ -80,6 +105,8 @@ export interface ManagedBitcoindServiceStatus {
     rpc: BitcoindRpcConfig;
     zmq: BitcoindZmqConfig;
     p2pPort: number;
+    getblockArchiveEndHeight: number | null;
+    getblockArchiveSha256: string | null;
     walletReplica: ManagedCoreWalletReplicaStatus | null;
     startedAtUnixMs: number;
     heartbeatAtUnixMs: number;
@@ -122,6 +149,10 @@ export interface ManagedBitcoindStatus {
     serviceStatus?: ManagedBitcoindObservedStatus | null;
     indexerDaemon?: ManagedIndexerDaemonObservedStatus | null;
 }
+export interface ManagedGetblockArchiveRestartRequest {
+    currentArchiveEndHeight: number | null;
+    nextArchiveEndHeight: number;
+}
 export interface ManagedBitcoindOptions extends ClientOptions {
     dataDir?: string;
     databasePath?: string;
@@ -136,6 +167,8 @@ export interface ManagedBitcoindOptions extends ClientOptions {
     managedWalletPassphrase?: string;
     onProgress?: (event: ManagedBitcoindProgressEvent) => void;
     progressOutput?: ProgressOutputMode;
+    fetchImpl?: typeof fetch;
+    confirmGetblockArchiveRestart?: (request: ManagedGetblockArchiveRestartRequest) => Promise<boolean>;
 }
 export interface ManagedBitcoindClient extends Client {
     syncToTip(): Promise<SyncResult>;
@@ -396,6 +429,8 @@ export interface ManagedBitcoindNodeHandle {
     expectedChain: "main" | "regtest";
     startHeight: number;
     dataDir: string;
+    getblockArchiveEndHeight: number | null;
+    getblockArchiveSha256: string | null;
     walletRootId?: string;
     runtimeRoot?: string;
     validate(): Promise<void>;