@cogcoin/client 0.5.4 → 0.5.6

package/dist/bitcoind/bootstrap/state.js

@@ -1,11 +1,14 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { DEFAULT_SNAPSHOT_METADATA, SNAPSHOT_METADATA_VERSION, } from "./constants.js";
+import { BOOTSTRAP_STATE_VERSION, DEFAULT_SNAPSHOT_METADATA, } from "./constants.js";
 function createInitialBootstrapState(snapshot) {
     return {
-        metadataVersion: SNAPSHOT_METADATA_VERSION,
+        metadataVersion: BOOTSTRAP_STATE_VERSION,
         snapshot,
         phase: "snapshot_download",
+        integrityVersion: 0,
+        chunkSizeBytes: 0,
+        verifiedChunkCount: 0,
         downloadedBytes: 0,
         validated: false,
         loadTxOutSetComplete: false,
@@ -21,30 +24,48 @@ async function writeJsonAtomic(path, payload) {
     await writeFile(tempPath, JSON.stringify(payload, null, 2));
     await rename(tempPath, path);
 }
-export async function loadBootstrapState(paths, snapshot) {
+function snapshotIdentityMatches(parsed, snapshot) {
+    return parsed.snapshot?.sha256 === snapshot.sha256
+        && parsed.snapshot?.sizeBytes === snapshot.sizeBytes
+        && parsed.snapshot?.height === snapshot.height
+        && parsed.snapshot?.filename === snapshot.filename;
+}
+function normalizeLoadedBootstrapState(parsed, snapshot) {
+    if (typeof parsed.downloadedBytes !== "number"
+        || typeof parsed.validated !== "boolean"
+        || typeof parsed.loadTxOutSetComplete !== "boolean") {
+        return null;
+    }
+    return {
+        metadataVersion: BOOTSTRAP_STATE_VERSION,
+        snapshot,
+        phase: parsed.phase ?? "snapshot_download",
+        integrityVersion: typeof parsed.integrityVersion === "number" ? parsed.integrityVersion : 0,
+        chunkSizeBytes: typeof parsed.chunkSizeBytes === "number" ? parsed.chunkSizeBytes : 0,
+        verifiedChunkCount: typeof parsed.verifiedChunkCount === "number" ? parsed.verifiedChunkCount : 0,
+        downloadedBytes: parsed.downloadedBytes,
+        validated: parsed.validated,
+        loadTxOutSetComplete: parsed.loadTxOutSetComplete,
+        baseHeight: parsed.baseHeight ?? null,
+        tipHashHex: parsed.tipHashHex ?? null,
+        lastError: parsed.lastError ?? null,
+        updatedAt: typeof parsed.updatedAt === "number" ? parsed.updatedAt : Date.now(),
+    };
+}
+export async function loadBootstrapStateRecord(paths, snapshot) {
     try {
         const raw = await readFile(paths.statePath, "utf8");
         const parsed = JSON.parse(raw);
-        if (parsed.metadataVersion === SNAPSHOT_METADATA_VERSION
-            && parsed.snapshot?.url === snapshot.url
-            && parsed.snapshot?.sha256 === snapshot.sha256
-            && parsed.snapshot?.sizeBytes === snapshot.sizeBytes
-            && parsed.snapshot?.height === snapshot.height
-            && parsed.snapshot?.filename === snapshot.filename
-            && typeof parsed.downloadedBytes === "number"
-            && typeof parsed.validated === "boolean"
-            && typeof parsed.loadTxOutSetComplete === "boolean") {
+        const snapshotIdentity = parsed.snapshot === undefined
+            ? "unknown"
+            : snapshotIdentityMatches(parsed, snapshot)
+                ? "current"
+                : "different";
+        const normalized = normalizeLoadedBootstrapState(parsed, snapshot);
+        if (normalized !== null) {
             return {
-                metadataVersion: SNAPSHOT_METADATA_VERSION,
-                snapshot,
-                phase: parsed.phase ?? "snapshot_download",
-                downloadedBytes: parsed.downloadedBytes,
-                validated: parsed.validated,
-                loadTxOutSetComplete: parsed.loadTxOutSetComplete,
-                baseHeight: parsed.baseHeight ?? null,
-                tipHashHex: parsed.tipHashHex ?? null,
-                lastError: parsed.lastError ?? null,
-                updatedAt: typeof parsed.updatedAt === "number" ? parsed.updatedAt : Date.now(),
+                state: normalized,
+                snapshotIdentity,
             };
         }
     }
@@ -53,7 +74,13 @@ export async function loadBootstrapState(paths, snapshot) {
     }
     const state = createInitialBootstrapState(snapshot);
     await writeJsonAtomic(paths.statePath, state);
-    return state;
+    return {
+        state,
+        snapshotIdentity: "unknown",
+    };
+}
+export async function loadBootstrapState(paths, snapshot) {
+    return (await loadBootstrapStateRecord(paths, snapshot)).state;
 }
 export async function saveBootstrapState(paths, state) {
     state.updatedAt = Date.now();

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

@@ -1,9 +1,12 @@
 import type { ManagedProgressController } from "../progress.js";
-import type { BootstrapPhase, SnapshotMetadata } from "../types.js";
+import type { BootstrapPhase, SnapshotChunkManifest, SnapshotMetadata } from "../types.js";
 export interface BootstrapPersistentState {
     metadataVersion: number;
     snapshot: SnapshotMetadata;
     phase: BootstrapPhase;
+    integrityVersion: number;
+    chunkSizeBytes: number;
+    verifiedChunkCount: number;
     downloadedBytes: number;
     validated: boolean;
     loadTxOutSetComplete: boolean;
@@ -12,6 +15,11 @@ export interface BootstrapPersistentState {
     lastError: string | null;
     updatedAt: number;
 }
+export type BootstrapStateSnapshotIdentity = "current" | "different" | "unknown";
+export interface LoadedBootstrapState {
+    state: BootstrapPersistentState;
+    snapshotIdentity: BootstrapStateSnapshotIdentity;
+}
 export interface BootstrapPaths {
     directory: string;
     snapshotPath: string;
@@ -22,7 +30,10 @@ export interface BootstrapPaths {
 export interface DownloadSnapshotOptions {
     fetchImpl?: typeof fetch;
     metadata: SnapshotMetadata;
+    manifest?: SnapshotChunkManifest;
     paths: BootstrapPaths;
     progress: Pick<ManagedProgressController, "setPhase">;
     state: BootstrapPersistentState;
+    signal?: AbortSignal;
+    snapshotIdentity?: BootstrapStateSnapshotIdentity;
 }

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

@@ -23,6 +23,7 @@ export interface SyncEngineDependencies {
     startHeight: number;
     bitcoinRateTracker: BlockRateTracker;
     cogcoinRateTracker: BlockRateTracker;
+    abortSignal?: AbortSignal;
     isFollowing(): boolean;
     loadVisibleFollowBlockTimes(tip: Awaited<ReturnType<Client["getTip"]>>): Promise<Record<number, number>>;
 }

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

@@ -21,7 +21,8 @@ export class DefaultManagedBitcoindClient {
     #cogcoinRateTracker = createBlockRateTracker();
     #syncPromise = Promise.resolve(createInitialSyncResult());
     #debounceTimer = null;
-    constructor(client, store, node, rpc, progress, bootstrap, indexerDaemon, syncDebounceMs) {
+    #syncAbortControllers = new Set();
+    constructor(client, store, node, rpc, progress, bootstrap, indexerDaemon, startHeight, syncDebounceMs) {
         this.#client = client;
         this.#store = store;
         this.#node = node;
@@ -29,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() {
@@ -47,19 +48,29 @@ export class DefaultManagedBitcoindClient {
     async syncToTip() {
         this.#assertOpen();
         await this.#progress.start();
-        const run = async () => runManagedSync({
-            client: this.#client,
-            store: this.#store,
-            node: this.#node,
-            rpc: this.#rpc,
-            progress: this.#progress,
-            bootstrap: this.#bootstrap,
-            startHeight: this.#startHeight,
-            bitcoinRateTracker: this.#bitcoinRateTracker,
-            cogcoinRateTracker: this.#cogcoinRateTracker,
-            isFollowing: () => this.#following,
-            loadVisibleFollowBlockTimes: (tip) => this.#loadVisibleFollowBlockTimes(tip),
-        });
+        const run = async () => {
+            const abortController = new AbortController();
+            this.#syncAbortControllers.add(abortController);
+            try {
+                return await runManagedSync({
+                    client: this.#client,
+                    store: this.#store,
+                    node: this.#node,
+                    rpc: this.#rpc,
+                    progress: this.#progress,
+                    bootstrap: this.#bootstrap,
+                    startHeight: this.#startHeight,
+                    bitcoinRateTracker: this.#bitcoinRateTracker,
+                    cogcoinRateTracker: this.#cogcoinRateTracker,
+                    abortSignal: abortController.signal,
+                    isFollowing: () => this.#following,
+                    loadVisibleFollowBlockTimes: (tip) => this.#loadVisibleFollowBlockTimes(tip),
+                });
+            }
+            finally {
+                this.#syncAbortControllers.delete(abortController);
+            }
+        };
         const nextPromise = this.#syncPromise.then(run, run);
         this.#syncPromise = nextPromise;
         return nextPromise;
@@ -159,6 +170,9 @@ export class DefaultManagedBitcoindClient {
         this.#subscriber = null;
         this.#followLoop = null;
         this.#pollTimer = null;
+        for (const abortController of this.#syncAbortControllers) {
+            abortController.abort(new Error("managed_sync_aborted"));
+        }
         await this.#syncPromise.catch(() => undefined);
         await this.#progress.close();
         await this.#node.stop();

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

@@ -1,10 +1,41 @@
 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 sleep(ms) {
-    return new Promise((resolve) => {
-        setTimeout(resolve, ms);
+function createAbortError(signal) {
+    const reason = signal?.reason;
+    if (reason instanceof Error) {
+        return reason;
+    }
+    const error = new Error("managed_sync_aborted");
+    error.name = "AbortError";
+    return error;
+}
+function isAbortError(error, signal) {
+    if (signal?.aborted) {
+        return true;
+    }
+    return error instanceof Error
+        && (error.name === "AbortError" || error.message === "managed_sync_aborted");
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw createAbortError(signal);
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            reject(createAbortError(signal));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
 async function setBitcoinSyncProgress(dependencies, info) {
@@ -14,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
@@ -28,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,
@@ -47,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);
@@ -63,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") {
@@ -81,9 +142,15 @@ async function syncAgainstBestHeight(dependencies, bestHeight) {
 }
 export async function syncToTip(dependencies) {
     try {
-        await dependencies.node.validate();
+        const retryState = createManagedRpcRetryState();
+        const runRpc = (operation) => runWithManagedRpcRetry(dependencies, retryState, operation);
+        throwIfAborted(dependencies.abortSignal);
+        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,
@@ -95,9 +162,10 @@ export async function syncToTip(dependencies) {
             bestHashHex: "",
         };
         while (true) {
-            const startInfo = await dependencies.rpc.getBlockchainInfo();
+            throwIfAborted(dependencies.abortSignal);
+            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) {
@@ -106,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.",
@@ -129,10 +198,13 @@ export async function syncToTip(dependencies) {
             if (endInfo.blocks >= dependencies.startHeight && finalTip?.height !== endInfo.blocks) {
                 continue;
             }
-            await sleep(DEFAULT_SYNC_CATCH_UP_POLL_MS);
+            await sleep(DEFAULT_SYNC_CATCH_UP_POLL_MS, dependencies.abortSignal);
         }
     }
     catch (error) {
+        if (isAbortError(error, dependencies.abortSignal)) {
+            throw createAbortError(dependencies.abortSignal);
+        }
         const message = formatManagedSyncErrorMessage(error instanceof Error ? error.message : String(error));
         await dependencies.progress.setPhase("error", {
             lastError: message,

package/dist/bitcoind/errors.js

@@ -18,6 +18,15 @@ export function formatManagedSyncErrorMessage(message) {
     if (message === "snapshot_response_body_missing") {
         return appendNextStep("Snapshot server returned an empty response body.", "Wait a moment, confirm the snapshot host is reachable, then rerun sync.");
     }
+    if (message === "snapshot_resume_requires_partial_content") {
+        return appendNextStep("Snapshot server ignored the resume request for a partial download.", "Wait a moment and rerun sync. If this keeps happening, confirm the snapshot host supports HTTP range requests.");
+    }
+    if (message.startsWith("snapshot_chunk_sha256_mismatch_")) {
+        return appendNextStep("A downloaded snapshot chunk was corrupted and was rolled back to the last verified checkpoint.", "Wait a moment and rerun sync. If this keeps happening, check local disk health and the stability of the snapshot connection.");
+    }
+    if (message.startsWith("snapshot_download_incomplete_")) {
+        return appendNextStep("Snapshot download ended before the expected file size was reached.", "Wait a moment and rerun sync. The downloader will resume from the last verified checkpoint.");
+    }
     if (message === "bitcoind_cookie_timeout") {
         return appendNextStep("The managed Bitcoin node did not finish starting in time.", "Check the node logs and local permissions for the Bitcoin data directory, then rerun sync.");
     }

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");
+    }
+}

package/dist/bitcoind/progress/controller.js

@@ -117,6 +117,7 @@ export class ManagedProgressController {
             phase: "cogcoin_sync",
             message: createDefaultMessage("cogcoin_sync"),
             etaSeconds,
+            lastError: null,
             updatedAt: Date.now(),
         };
         if (this.#followVisualMode) {

package/dist/bitcoind/progress/formatting.js

@@ -4,7 +4,7 @@ export function createDefaultMessage(phase) {
         case "snapshot_download":
             return "Downloading UTXO snapshot.";
         case "wait_headers_for_snapshot":
-            return "Waiting for Bitcoin headers to reach the snapshot height.";
+            return "Pre-synchronizing blockheaders.";
         case "load_snapshot":
             return "Loading the UTXO snapshot into bitcoind.";
         case "bitcoin_sync":
@@ -125,6 +125,9 @@ export function resolveStatusFieldText(progress, snapshotHeight, now = 0) {
         case "snapshot_download":
             return `Downloading snapshot to ${snapshotHeight}${animateStatusEllipsis(now)}`;
         case "wait_headers_for_snapshot":
+            return progress.message === "Waiting for Bitcoin headers to reach the snapshot height."
+                ? `Waiting for Bitcoin headers to reach the snapshot height${animateStatusEllipsis(now)}`
+                : `Pre-synchronizing blockheaders${animateStatusEllipsis(now)}`;
         case "load_snapshot":
         case "bitcoin_sync":
             return `Syncing Bitcoin Blocks${animateStatusEllipsis(now)}`;

package/dist/bitcoind/retryable-rpc.d.ts

@@ -0,0 +1,11 @@
+export declare const MANAGED_RPC_RETRY_BASE_MS = 1000;
+export declare const MANAGED_RPC_RETRY_MAX_MS = 15000;
+export declare const MANAGED_RPC_RETRY_MESSAGE = "Managed Bitcoin RPC temporarily unavailable; retrying until canceled.";
+export interface ManagedRpcRetryState {
+    nextDelayMs: number;
+}
+export declare function createManagedRpcRetryState(): ManagedRpcRetryState;
+export declare function resetManagedRpcRetryState(state: ManagedRpcRetryState): void;
+export declare function consumeManagedRpcRetryDelayMs(state: ManagedRpcRetryState): number;
+export declare function isRetryableManagedRpcError(error: unknown): boolean;
+export declare function describeManagedRpcRetryError(error: unknown): string;