@cogcoin/client 0.5.5 → 0.5.6

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@0.5.5` is the store-backed 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@0.5.6` is the store-backed 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/bootstrap/chainstate.d.ts

@@ -1,4 +1,5 @@
 import type { BitcoinRpcClient } from "../rpc.js";
-import type { SnapshotMetadata } from "../types.js";
+import type { RpcChainState, SnapshotMetadata } from "../types.js";
 import type { BootstrapPersistentState } from "./types.js";
 export declare function isSnapshotAlreadyLoaded(rpc: Pick<BitcoinRpcClient, "getChainStates">, snapshot: SnapshotMetadata, state: BootstrapPersistentState): Promise<boolean>;
+export declare function findLoadedSnapshotChainState(rpc: Pick<BitcoinRpcClient, "getChainStates">, snapshot: SnapshotMetadata, state: BootstrapPersistentState): Promise<RpcChainState | null>;

package/dist/bitcoind/bootstrap/chainstate.js

@@ -8,6 +8,9 @@ function chainStateMatches(chainState, snapshot, baseHeight, tipHashHex) {
     return chainState.blocks === snapshot.height && chainState.validated === false;
 }
 export async function isSnapshotAlreadyLoaded(rpc, snapshot, state) {
+    return (await findLoadedSnapshotChainState(rpc, snapshot, state)) !== null;
+}
+export async function findLoadedSnapshotChainState(rpc, snapshot, state) {
     const chainStates = await rpc.getChainStates();
-    return chainStates.chainstates.some((chainState) => chainStateMatches(chainState, snapshot, state.baseHeight, state.tipHashHex));
+    return chainStates.chainstates.find((chainState) => chainStateMatches(chainState, snapshot, state.baseHeight, state.tipHashHex)) ?? null;
 }

package/dist/bitcoind/bootstrap/controller.d.ts

@@ -1,7 +1,8 @@
 import type { ClientTip } from "../../types.js";
 import { ManagedProgressController } from "../progress.js";
 import { BitcoinRpcClient } from "../rpc.js";
-import type { BootstrapPhase, SnapshotMetadata } from "../types.js";
+import { type ManagedRpcRetryState } from "../retryable-rpc.js";
+import type { BootstrapPhase, SnapshotMetadata, SnapshotChunkManifest } from "../types.js";
 export declare class AssumeUtxoBootstrapController {
     #private;
     constructor(options: {
@@ -9,12 +10,14 @@ export declare class AssumeUtxoBootstrapController {
         dataDir: string;
         progress: ManagedProgressController;
         snapshot?: SnapshotMetadata;
+        manifest?: SnapshotChunkManifest;
         fetchImpl?: typeof fetch;
     });
     get quoteStatePath(): string;
     get snapshot(): SnapshotMetadata;
     ensureReady(indexedTip: ClientTip | null, expectedChain: "main" | "regtest", options?: {
         signal?: AbortSignal;
+        retryState?: ManagedRpcRetryState;
     }): Promise<void>;
     getStateForTesting(): Promise<{
         metadataVersion: number;

package/dist/bitcoind/bootstrap/controller.js

@@ -1,3 +1,4 @@
+import { join } from "node:path";
 import { createBootstrapProgressForTesting, ManagedProgressController } from "../progress.js";
 import { BitcoinRpcClient } from "../rpc.js";
 import { DEFAULT_SNAPSHOT_METADATA } from "./constants.js";
@@ -5,7 +6,8 @@ import { downloadSnapshotFileForTesting } from "./download.js";
 import { waitForHeaders } from "./headers.js";
 import { resolveBootstrapPaths } from "./paths.js";
 import { loadBootstrapStateRecord, saveBootstrapState } from "./state.js";
-import { isSnapshotAlreadyLoaded } from "./chainstate.js";
+import { findLoadedSnapshotChainState, isSnapshotAlreadyLoaded } from "./chainstate.js";
+import { describeManagedRpcRetryError, isRetryableManagedRpcError, } from "../retryable-rpc.js";
 async function loadSnapshotIntoNode(rpc, snapshotPath) {
     return rpc.loadTxOutSet(snapshotPath);
 }
@@ -14,13 +16,17 @@ export class AssumeUtxoBootstrapController {
     #paths;
     #progress;
     #snapshot;
+    #debugLogPath;
+    #manifest;
     #fetchImpl;
     #stateRecordPromise = null;
     constructor(options) {
         this.#rpc = options.rpc;
         this.#progress = options.progress;
         this.#snapshot = options.snapshot ?? DEFAULT_SNAPSHOT_METADATA;
+        this.#manifest = options.manifest;
         this.#paths = resolveBootstrapPaths(options.dataDir, this.#snapshot);
+        this.#debugLogPath = join(options.dataDir, "debug.log");
         this.#fetchImpl = options.fetchImpl;
     }
     get quoteStatePath() {
@@ -47,18 +53,23 @@ export class AssumeUtxoBootstrapController {
         }
         const { state, snapshotIdentity } = await this.#loadStateRecord();
         if (state.loadTxOutSetComplete && await isSnapshotAlreadyLoaded(this.#rpc, this.#snapshot, state)) {
+            if (state.lastError !== null) {
+                state.lastError = null;
+                await saveBootstrapState(this.#paths, state);
+            }
             await this.#progress.setPhase("bitcoin_sync", {
                 blocks: state.baseHeight,
                 targetHeight: state.baseHeight ?? this.#snapshot.height,
                 baseHeight: state.baseHeight,
                 tipHashHex: state.tipHashHex,
                 message: "Using the previously loaded assumeutxo chainstate.",
-                lastError: state.lastError,
+                lastError: null,
             });
             return;
         }
         await downloadSnapshotFileForTesting({
             fetchImpl: this.#fetchImpl,
+            manifest: this.#manifest,
             metadata: this.#snapshot,
             paths: this.#paths,
             progress: this.#progress,
@@ -69,22 +80,48 @@ export class AssumeUtxoBootstrapController {
         if (!await isSnapshotAlreadyLoaded(this.#rpc, this.#snapshot, state)) {
             await waitForHeaders(this.#rpc, this.#snapshot, this.#progress, {
                 signal: options.signal,
+                retryState: options.retryState,
+                debugLogPath: this.#debugLogPath,
             });
             await this.#progress.setPhase("load_snapshot", {
                 downloadedBytes: this.#snapshot.sizeBytes,
                 totalBytes: this.#snapshot.sizeBytes,
                 percent: 100,
                 message: "Loading the UTXO snapshot into bitcoind.",
+                lastError: null,
             });
-            const loadResult = await loadSnapshotIntoNode(this.#rpc, this.#paths.snapshotPath);
+            let loadResult;
+            try {
+                loadResult = await loadSnapshotIntoNode(this.#rpc, this.#paths.snapshotPath);
+            }
+            catch (error) {
+                if (!isRetryableManagedRpcError(error)) {
+                    throw error;
+                }
+                state.lastError = describeManagedRpcRetryError(error);
+                await saveBootstrapState(this.#paths, state);
+                const loadedChainState = await findLoadedSnapshotChainState(this.#rpc, this.#snapshot, state);
+                if (loadedChainState === null) {
+                    throw error;
+                }
+                loadResult = {
+                    base_height: loadedChainState.blocks ?? this.#snapshot.height,
+                    coins_loaded: 0,
+                    tip_hash: loadedChainState.snapshot_blockhash ?? state.tipHashHex ?? "",
+                };
+            }
             state.loadTxOutSetComplete = true;
             state.baseHeight = loadResult.base_height;
-            state.tipHashHex = loadResult.tip_hash;
+            state.tipHashHex = loadResult.tip_hash === "" ? state.tipHashHex : loadResult.tip_hash;
             state.phase = "bitcoin_sync";
             state.lastError = null;
             await saveBootstrapState(this.#paths, state);
         }
         const info = await this.#rpc.getBlockchainInfo();
+        if (state.lastError !== null) {
+            state.lastError = null;
+            await saveBootstrapState(this.#paths, state);
+        }
         await this.#progress.setPhase("bitcoin_sync", {
             blocks: info.blocks,
             headers: info.headers,
@@ -92,7 +129,7 @@ export class AssumeUtxoBootstrapController {
             baseHeight: state.baseHeight,
             tipHashHex: state.tipHashHex,
             message: "Bitcoin Core is syncing blocks after assumeutxo bootstrap.",
-            lastError: state.lastError,
+            lastError: null,
         });
     }
     async getStateForTesting() {

package/dist/bitcoind/bootstrap/headers.d.ts

@@ -1,3 +1,4 @@
+import { type ManagedRpcRetryState } from "../retryable-rpc.js";
 import type { BitcoinRpcClient } from "../rpc.js";
 import type { ManagedProgressController } from "../progress.js";
 import type { SnapshotMetadata } from "../types.js";
@@ -6,10 +7,21 @@ export declare function waitForHeaders(rpc: Pick<BitcoinRpcClient, "getBlockchai
     sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
     noPeerTimeoutMs?: number;
     signal?: AbortSignal;
+    retryState?: ManagedRpcRetryState;
+    debugLogPath?: string;
+    readDebugLogProgress?: (debugLogPath: string) => Promise<{
+        height: number;
+        message: string;
+    } | null>;
 }): Promise<void>;
 export declare function waitForHeadersForTesting(rpc: Pick<BitcoinRpcClient, "getBlockchainInfo" | "getNetworkInfo">, snapshot: SnapshotMetadata | undefined, progress: Pick<ManagedProgressController, "setPhase">, options?: {
     now?: () => number;
     sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
     noPeerTimeoutMs?: number;
     signal?: AbortSignal;
+    debugLogPath?: string;
+    readDebugLogProgress?: (debugLogPath: string) => Promise<{
+        height: number;
+        message: string;
+    } | null>;
 }): Promise<void>;

package/dist/bitcoind/bootstrap/headers.js

@@ -1,5 +1,9 @@
+import { open } from "node:fs/promises";
 import { formatManagedSyncErrorMessage } from "../errors.js";
+import { MANAGED_RPC_RETRY_MESSAGE, consumeManagedRpcRetryDelayMs, createManagedRpcRetryState, describeManagedRpcRetryError, resetManagedRpcRetryState, isRetryableManagedRpcError, } from "../retryable-rpc.js";
 import { DEFAULT_SNAPSHOT_METADATA, HEADER_NO_PEER_TIMEOUT_MS, HEADER_POLL_MS, } from "./constants.js";
+const DEBUG_LOG_TAIL_BYTES = 64 * 1024;
+const HEADER_SYNC_DEBUG_LINE_PATTERN = /Pre-synchronizing blockheaders,\s*height:\s*([\d,]+)\s*\(~(\d+(?:\.\d+)?)%\)/u;
 function createAbortError(signal) {
     const reason = signal?.reason;
     if (reason instanceof Error) {
@@ -33,7 +37,52 @@ function resolvePeerCount(networkInfo) {
         ? networkInfo.connections
         : (networkInfo.connections_in ?? 0) + (networkInfo.connections_out ?? 0);
 }
-function resolveHeaderWaitMessage(headers, peerCount, networkActive) {
+async function readDebugLogTail(filePath, maxBytes = DEBUG_LOG_TAIL_BYTES) {
+    let handle = null;
+    try {
+        handle = await open(filePath, "r");
+        const stats = await handle.stat();
+        const bytesToRead = Math.min(maxBytes, Math.max(0, stats.size));
+        if (bytesToRead === 0) {
+            return null;
+        }
+        const buffer = Buffer.alloc(bytesToRead);
+        await handle.read(buffer, 0, bytesToRead, stats.size - bytesToRead);
+        return buffer.toString("utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        return null;
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+async function readHeaderSyncProgressFromDebugLog(debugLogPath) {
+    const tail = await readDebugLogTail(debugLogPath);
+    if (tail === null) {
+        return null;
+    }
+    const lines = tail.split(/\r?\n/u).reverse();
+    for (const line of lines) {
+        const match = HEADER_SYNC_DEBUG_LINE_PATTERN.exec(line);
+        if (match === null) {
+            continue;
+        }
+        const height = Number(match[1].replaceAll(",", ""));
+        if (!Number.isFinite(height) || height < 0) {
+            return null;
+        }
+        return {
+            height,
+            message: `Pre-synchronizing blockheaders, height: ${height.toLocaleString()} (~${match[2]}%)`,
+        };
+    }
+    return null;
+}
+function resolveHeaderWaitMessage(headers, peerCount, networkActive, rpcHeaders, headerSyncMessage) {
     if (!networkActive) {
         return "Bitcoin networking is inactive for the managed node.";
     }
@@ -43,33 +92,69 @@ function resolveHeaderWaitMessage(headers, peerCount, networkActive) {
     if (peerCount === 0) {
         return `Waiting for peers to continue header sync (${headers.toLocaleString()} headers, 0 peers).`;
     }
-    return "Waiting for Bitcoin headers to reach the snapshot height.";
+    if (rpcHeaders > 0) {
+        return "Waiting for Bitcoin headers to reach the snapshot height.";
+    }
+    return headerSyncMessage ?? "Pre-synchronizing blockheaders.";
 }
 export async function waitForHeaders(rpc, snapshot, progress, options = {}) {
     const now = options.now ?? Date.now;
     const sleepImpl = options.sleep ?? sleep;
     const noPeerTimeoutMs = options.noPeerTimeoutMs ?? HEADER_NO_PEER_TIMEOUT_MS;
     const { signal } = options;
+    const retryState = options.retryState ?? createManagedRpcRetryState();
+    const readDebugLogProgress = options.readDebugLogProgress ?? readHeaderSyncProgressFromDebugLog;
     let noPeerSince = null;
+    let lastBlocks = 0;
+    let lastHeaders = 0;
     while (true) {
         throwIfAborted(signal);
-        const [info, networkInfo] = await Promise.all([
-            rpc.getBlockchainInfo(),
-            rpc.getNetworkInfo(),
-        ]);
+        let info;
+        let networkInfo;
+        try {
+            [info, networkInfo] = await Promise.all([
+                rpc.getBlockchainInfo(),
+                rpc.getNetworkInfo(),
+            ]);
+            resetManagedRpcRetryState(retryState);
+        }
+        catch (error) {
+            if (!isRetryableManagedRpcError(error)) {
+                throw error;
+            }
+            await progress.setPhase("wait_headers_for_snapshot", {
+                headers: lastHeaders,
+                targetHeight: snapshot.height,
+                blocks: lastBlocks,
+                percent: (Math.min(lastHeaders, snapshot.height) / snapshot.height) * 100,
+                lastError: describeManagedRpcRetryError(error),
+                message: MANAGED_RPC_RETRY_MESSAGE,
+            });
+            await sleepImpl(consumeManagedRpcRetryDelayMs(retryState), signal);
+            continue;
+        }
+        lastBlocks = info.blocks;
+        const debugLogProgress = info.headers === 0 && options.debugLogPath !== undefined
+            ? await readDebugLogProgress(options.debugLogPath)
+            : null;
+        const observedHeaders = info.headers > 0
+            ? info.headers
+            : Math.max(info.headers, debugLogProgress?.height ?? 0);
+        lastHeaders = observedHeaders;
         const peerCount = resolvePeerCount(networkInfo);
-        const message = resolveHeaderWaitMessage(info.headers, peerCount, networkInfo.networkactive);
+        const message = resolveHeaderWaitMessage(observedHeaders, peerCount, networkInfo.networkactive, info.headers, debugLogProgress?.message ?? null);
         await progress.setPhase("wait_headers_for_snapshot", {
-            headers: info.headers,
+            headers: observedHeaders,
             targetHeight: snapshot.height,
             blocks: info.blocks,
-            percent: (Math.min(info.headers, snapshot.height) / snapshot.height) * 100,
+            percent: (Math.min(observedHeaders, snapshot.height) / snapshot.height) * 100,
+            lastError: null,
             message,
         });
         if (info.headers >= snapshot.height) {
             return;
         }
-        if (info.headers === 0 && peerCount === 0) {
+        if (observedHeaders === 0 && peerCount === 0) {
             noPeerSince ??= now();
             if (now() - noPeerSince >= noPeerTimeoutMs) {
                 throw new Error(formatManagedSyncErrorMessage("bitcoind_no_peers_for_header_sync_check_internet_or_firewall"));

package/dist/bitcoind/client/factory.js

@@ -4,12 +4,18 @@ import { openClient } from "../../client.js";
 import { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, resolveBootstrapPathsForTesting } from "../bootstrap.js";
 import { attachOrStartIndexerDaemon } from "../indexer-daemon.js";
 import { createRpcClient } from "../node.js";
+import { assertCogcoinProcessingStartHeight, resolveCogcoinProcessingStartHeight, } from "../processing-start-height.js";
 import { ManagedProgressController } from "../progress.js";
 import { attachOrStartManagedBitcoindService } from "../service.js";
 import { DefaultManagedBitcoindClient } from "./managed-client.js";
 const DEFAULT_SYNC_DEBOUNCE_MS = 250;
 async function createManagedBitcoindClient(options) {
     const genesisParameters = options.genesisParameters ?? await loadBundledGenesisParameters();
+    assertCogcoinProcessingStartHeight({
+        chain: options.chain,
+        startHeight: options.startHeight,
+        genesisParameters,
+    });
     const dataDir = options.dataDir ?? resolveDefaultBitcoindDataDirForTesting();
     const node = await attachOrStartManagedBitcoindService({
         ...options,
@@ -41,7 +47,10 @@ async function createManagedBitcoindClient(options) {
             startupTimeoutMs: options.startupTimeoutMs,
         })
         : null;
-    return new DefaultManagedBitcoindClient(client, options.store, node, rpc, progress, bootstrap, indexerDaemon, options.syncDebounceMs ?? DEFAULT_SYNC_DEBOUNCE_MS);
+    // The persistent service may already exist from a non-processing attach path
+    // that used startHeight 0. Cogcoin replay still begins at the requested
+    // processing boundary for this managed client.
+    return new DefaultManagedBitcoindClient(client, options.store, node, rpc, progress, bootstrap, indexerDaemon, options.startHeight, options.syncDebounceMs ?? DEFAULT_SYNC_DEBOUNCE_MS);
 }
 export async function openManagedBitcoindClient(options) {
     const genesisParameters = options.genesisParameters ?? await loadBundledGenesisParameters();
@@ -49,7 +58,7 @@ export async function openManagedBitcoindClient(options) {
         ...options,
         genesisParameters,
         chain: "main",
-        startHeight: genesisParameters.genesisBlock,
+        startHeight: resolveCogcoinProcessingStartHeight(genesisParameters),
     });
 }
 export async function openManagedBitcoindClientInternal(options) {

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

@@ -7,7 +7,7 @@ import type { BitcoinRpcClient } from "../rpc.js";
 import type { ManagedBitcoindClient, ManagedBitcoindNodeHandle, ManagedBitcoindStatus, SyncResult } from "../types.js";
 export declare class DefaultManagedBitcoindClient implements ManagedBitcoindClient {
     #private;
-    constructor(client: Client, store: ClientStoreAdapter, node: ManagedBitcoindNodeHandle, rpc: BitcoinRpcClient, progress: ManagedProgressController, bootstrap: AssumeUtxoBootstrapController, indexerDaemon: IndexerDaemonClient | null, syncDebounceMs: number);
+    constructor(client: Client, store: ClientStoreAdapter, node: ManagedBitcoindNodeHandle, rpc: BitcoinRpcClient, progress: ManagedProgressController, bootstrap: AssumeUtxoBootstrapController, indexerDaemon: IndexerDaemonClient | null, startHeight: number, syncDebounceMs: number);
     getTip(): Promise<import("../../types.js").ClientTip | null>;
     getState(): Promise<import("@cogcoin/indexer/types").IndexerState>;
     applyBlock(block: BitcoinBlock): Promise<import("../../types.js").ApplyBlockResult>;

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

@@ -22,7 +22,7 @@ export class DefaultManagedBitcoindClient {
     #syncPromise = Promise.resolve(createInitialSyncResult());
     #debounceTimer = null;
     #syncAbortControllers = new Set();
-    constructor(client, store, node, rpc, progress, bootstrap, indexerDaemon, syncDebounceMs) {
+    constructor(client, store, node, rpc, progress, bootstrap, indexerDaemon, startHeight, syncDebounceMs) {
         this.#client = client;
         this.#store = store;
         this.#node = node;
@@ -30,7 +30,7 @@ export class DefaultManagedBitcoindClient {
         this.#progress = progress;
         this.#bootstrap = bootstrap;
         this.#indexerDaemon = indexerDaemon;
-        this.#startHeight = node.startHeight;
+        this.#startHeight = startHeight;
         this.#syncDebounceMs = syncDebounceMs;
     }
     async getTip() {

package/dist/bitcoind/client/sync-engine.js

@@ -1,5 +1,6 @@
 import { formatManagedSyncErrorMessage } from "../errors.js";
 import { normalizeRpcBlock } from "../normalize.js";
+import { MANAGED_RPC_RETRY_MESSAGE, consumeManagedRpcRetryDelayMs, createManagedRpcRetryState, describeManagedRpcRetryError, isRetryableManagedRpcError, resetManagedRpcRetryState, } from "../retryable-rpc.js";
 import { estimateEtaSeconds } from "./rate-tracker.js";
 const DEFAULT_SYNC_CATCH_UP_POLL_MS = 2_000;
 function createAbortError(signal) {
@@ -44,12 +45,42 @@ async function setBitcoinSyncProgress(dependencies, info) {
         headers: info.headers,
         targetHeight: info.headers,
         etaSeconds,
+        lastError: null,
         message: dependencies.node.expectedChain === "main"
             ? "Bitcoin Core is syncing blocks after assumeutxo bootstrap."
             : "Reading blocks from the managed Bitcoin node.",
     });
 }
-async function findCommonAncestor(dependencies, tip, bestHeight) {
+async function setRetryingProgress(dependencies, error) {
+    const status = dependencies.progress.getStatusSnapshot();
+    const { phase: _phase, updatedAt: _updatedAt, ...progress } = status.bootstrapProgress;
+    await dependencies.progress.setPhase(status.bootstrapPhase, {
+        ...progress,
+        lastError: describeManagedRpcRetryError(error),
+        message: MANAGED_RPC_RETRY_MESSAGE,
+    });
+}
+async function runWithManagedRpcRetry(dependencies, retryState, operation) {
+    while (true) {
+        throwIfAborted(dependencies.abortSignal);
+        try {
+            const result = await operation();
+            resetManagedRpcRetryState(retryState);
+            return result;
+        }
+        catch (error) {
+            if (isAbortError(error, dependencies.abortSignal)) {
+                throw createAbortError(dependencies.abortSignal);
+            }
+            if (!isRetryableManagedRpcError(error)) {
+                throw error;
+            }
+            await setRetryingProgress(dependencies, error);
+            await sleep(consumeManagedRpcRetryDelayMs(retryState), dependencies.abortSignal);
+        }
+    }
+}
+async function findCommonAncestor(dependencies, tip, bestHeight, runRpc) {
     const startHeight = Math.min(tip.height, bestHeight);
     for (let height = startHeight; height >= dependencies.startHeight; height -= 1) {
         const localHashHex = height === tip.height
@@ -58,14 +89,14 @@ async function findCommonAncestor(dependencies, tip, bestHeight) {
         if (localHashHex === null) {
             continue;
         }
-        const chainHashHex = await dependencies.rpc.getBlockHash(height);
+        const chainHashHex = await runRpc(() => dependencies.rpc.getBlockHash(height));
         if (chainHashHex === localHashHex) {
             return height;
         }
     }
     return dependencies.startHeight - 1;
 }
-async function syncAgainstBestHeight(dependencies, bestHeight) {
+async function syncAgainstBestHeight(dependencies, bestHeight, runRpc) {
     if (bestHeight < dependencies.startHeight) {
         return {
             appliedBlocks: 0,
@@ -77,7 +108,7 @@ async function syncAgainstBestHeight(dependencies, bestHeight) {
     let rewoundBlocks = 0;
     let commonAncestorHeight = null;
     if (startTip !== null) {
-        const rewindTarget = await findCommonAncestor(dependencies, startTip, bestHeight);
+        const rewindTarget = await findCommonAncestor(dependencies, startTip, bestHeight, runRpc);
         if (rewindTarget < startTip.height) {
             commonAncestorHeight = rewindTarget < dependencies.startHeight ? null : rewindTarget;
             await dependencies.client.rewindToHeight(rewindTarget);
@@ -93,8 +124,8 @@ async function syncAgainstBestHeight(dependencies, bestHeight) {
         await dependencies.progress.setCogcoinSync(nextHeight - 1, bestHeight, estimateEtaSeconds(dependencies.cogcoinRateTracker, nextHeight - 1, bestHeight));
     }
     for (let height = nextHeight; height <= bestHeight; height += 1) {
-        const blockHashHex = await dependencies.rpc.getBlockHash(height);
-        const rpcBlock = await dependencies.rpc.getBlock(blockHashHex);
+        const blockHashHex = await runRpc(() => dependencies.rpc.getBlockHash(height));
+        const rpcBlock = await runRpc(() => dependencies.rpc.getBlock(blockHashHex));
         const normalizedBlock = normalizeRpcBlock(rpcBlock);
         await dependencies.client.applyBlock(normalizedBlock);
         if (typeof rpcBlock.time === "number") {
@@ -111,12 +142,15 @@ async function syncAgainstBestHeight(dependencies, bestHeight) {
 }
 export async function syncToTip(dependencies) {
     try {
+        const retryState = createManagedRpcRetryState();
+        const runRpc = (operation) => runWithManagedRpcRetry(dependencies, retryState, operation);
         throwIfAborted(dependencies.abortSignal);
-        await dependencies.node.validate();
+        await runRpc(() => dependencies.node.validate());
         const indexedTipBeforeBootstrap = await dependencies.client.getTip();
-        await dependencies.bootstrap.ensureReady(indexedTipBeforeBootstrap, dependencies.node.expectedChain, {
+        await runRpc(() => dependencies.bootstrap.ensureReady(indexedTipBeforeBootstrap, dependencies.node.expectedChain, {
             signal: dependencies.abortSignal,
-        });
+            retryState,
+        }));
         const startTip = await dependencies.client.getTip();
         const aggregate = {
             appliedBlocks: 0,
@@ -129,9 +163,9 @@ export async function syncToTip(dependencies) {
         };
         while (true) {
             throwIfAborted(dependencies.abortSignal);
-            const startInfo = await dependencies.rpc.getBlockchainInfo();
+            const startInfo = await runRpc(() => dependencies.rpc.getBlockchainInfo());
             await setBitcoinSyncProgress(dependencies, startInfo);
-            const pass = await syncAgainstBestHeight(dependencies, startInfo.blocks);
+            const pass = await syncAgainstBestHeight(dependencies, startInfo.blocks, runRpc);
             aggregate.appliedBlocks += pass.appliedBlocks;
             aggregate.rewoundBlocks += pass.rewoundBlocks;
             if (pass.commonAncestorHeight !== null) {
@@ -140,19 +174,20 @@ export async function syncToTip(dependencies) {
                     : Math.min(aggregate.commonAncestorHeight, pass.commonAncestorHeight);
             }
             const finalTip = await dependencies.client.getTip();
-            const endInfo = await dependencies.rpc.getBlockchainInfo();
+            const endInfo = await runRpc(() => dependencies.rpc.getBlockchainInfo());
             const caughtUpCogcoin = endInfo.blocks < dependencies.startHeight || finalTip?.height === endInfo.blocks;
             aggregate.endingHeight = finalTip?.height ?? null;
             aggregate.bestHeight = endInfo.blocks;
             aggregate.bestHashHex = endInfo.bestblockhash;
             if (endInfo.blocks === endInfo.headers && caughtUpCogcoin) {
                 if (dependencies.isFollowing()) {
-                    dependencies.progress.replaceFollowBlockTimes(await dependencies.loadVisibleFollowBlockTimes(finalTip));
+                    dependencies.progress.replaceFollowBlockTimes(await runRpc(() => dependencies.loadVisibleFollowBlockTimes(finalTip)));
                 }
                 await dependencies.progress.setPhase(dependencies.isFollowing() ? "follow_tip" : "complete", {
                     blocks: endInfo.blocks,
                     headers: endInfo.headers,
                     targetHeight: endInfo.headers,
+                    lastError: null,
                     message: dependencies.isFollowing()
                         ? "Following the live Bitcoin tip."
                         : "Managed sync fully caught up to the live tip.",

package/dist/bitcoind/indexer-daemon.d.ts

@@ -1,4 +1,5 @@
 import { type ManagedIndexerDaemonObservedStatus, type ManagedIndexerDaemonStatus } from "./types.js";
+import { resolveManagedServicePaths } from "./service-paths.js";
 interface DaemonRequest {
     id: string;
     method: "GetStatus" | "OpenSnapshot" | "ReadSnapshot" | "CloseSnapshot";
@@ -81,6 +82,12 @@ export interface CoherentIndexerSnapshotLease {
     payload: IndexerSnapshotPayload;
     status: ManagedIndexerDaemonStatus;
 }
+export declare function stopIndexerDaemonServiceWithLockHeld(options: {
+    dataDir: string;
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+    paths?: ReturnType<typeof resolveManagedServicePaths>;
+}): Promise<IndexerDaemonStopResult>;
 export declare function probeIndexerDaemon(options: {
     dataDir: string;
     walletRootId?: string;

package/dist/bitcoind/indexer-daemon.js

@@ -53,6 +53,33 @@ async function clearIndexerDaemonRuntimeArtifacts(paths) {
     await rm(paths.indexerDaemonStatusPath, { force: true }).catch(() => undefined);
     await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
 }
+export async function stopIndexerDaemonServiceWithLockHeld(options) {
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const paths = options.paths ?? resolveManagedServicePaths(options.dataDir, walletRootId);
+    const status = await readJsonFile(paths.indexerDaemonStatusPath);
+    const processId = status?.processId ?? null;
+    if (status === null || processId === null || !await isProcessAlive(processId)) {
+        await clearIndexerDaemonRuntimeArtifacts(paths);
+        return {
+            status: "not-running",
+            walletRootId,
+        };
+    }
+    try {
+        process.kill(processId, "SIGTERM");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+            throw error;
+        }
+    }
+    await waitForProcessExit(processId, options.shutdownTimeoutMs ?? 5_000, "indexer_daemon_stop_timeout");
+    await clearIndexerDaemonRuntimeArtifacts(paths);
+    return {
+        status: "stopped",
+        walletRootId,
+    };
+}
 function createIndexerDaemonClient(socketPath) {
     async function sendRequest(request) {
         return new Promise((resolve, reject) => {
@@ -380,29 +407,11 @@ export async function stopIndexerDaemonService(options) {
         dataDir: options.dataDir,
     });
     try {
-        const status = await readJsonFile(paths.indexerDaemonStatusPath);
-        const processId = status?.processId ?? null;
-        if (status === null || processId === null || !await isProcessAlive(processId)) {
-            await clearIndexerDaemonRuntimeArtifacts(paths);
-            return {
-                status: "not-running",
-                walletRootId,
-            };
-        }
-        try {
-            process.kill(processId, "SIGTERM");
-        }
-        catch (error) {
-            if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
-                throw error;
-            }
-        }
-        await waitForProcessExit(processId, options.shutdownTimeoutMs ?? 5_000, "indexer_daemon_stop_timeout");
-        await clearIndexerDaemonRuntimeArtifacts(paths);
-        return {
-            status: "stopped",
+        return await stopIndexerDaemonServiceWithLockHeld({
+            ...options,
             walletRootId,
-        };
+            paths,
+        });
     }
     finally {
         await lock.release();

package/dist/bitcoind/processing-start-height.d.ts

@@ -0,0 +1,7 @@
+import type { GenesisParameters } from "@cogcoin/indexer/types";
+export declare function resolveCogcoinProcessingStartHeight(genesisParameters: GenesisParameters): number;
+export declare function assertCogcoinProcessingStartHeight(options: {
+    chain: "main" | "regtest";
+    startHeight: number;
+    genesisParameters: GenesisParameters;
+}): void;

package/dist/bitcoind/processing-start-height.js

@@ -0,0 +1,9 @@
+export function resolveCogcoinProcessingStartHeight(genesisParameters) {
+    return genesisParameters.genesisBlock;
+}
+export function assertCogcoinProcessingStartHeight(options) {
+    const processingStartHeight = resolveCogcoinProcessingStartHeight(options.genesisParameters);
+    if (options.chain === "main" && options.startHeight < processingStartHeight) {
+        throw new Error("cogcoin_processing_start_height_before_genesis");
+    }
+}