@cogcoin/client 0.5.4 → 0.5.6

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@0.5.4` 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/app-paths.d.ts

@@ -17,6 +17,8 @@ export interface CogcoinResolvedPaths {
     walletStateDirectory: string;
     walletStatePath: string;
     walletStateBackupPath: string;
+    walletInitPendingPath: string;
+    walletInitPendingBackupPath: string;
     walletUnlockSessionPath: string;
     walletExplicitLockPath: string;
     walletControlLockPath: string;

package/dist/app-paths.js

@@ -63,6 +63,8 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
     const walletStateDirectory = stateRoot;
     const walletStatePath = joinForPlatform(platform, walletStateDirectory, "wallet-state.enc");
     const walletStateBackupPath = joinForPlatform(platform, walletStateDirectory, "wallet-state.enc.bak");
+    const walletInitPendingPath = joinForPlatform(platform, walletStateDirectory, "wallet-init-pending.enc");
+    const walletInitPendingBackupPath = joinForPlatform(platform, walletStateDirectory, "wallet-init-pending.enc.bak");
     const walletUnlockSessionPath = joinForPlatform(platform, runtimeRoot, "wallet-unlock-session.enc");
     const walletExplicitLockPath = joinForPlatform(platform, runtimeRoot, "wallet-explicit-lock.json");
     const walletControlLockPath = joinForPlatform(platform, runtimeRoot, "wallet-control.lock");
@@ -91,6 +93,8 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
         walletStateDirectory,
         walletStatePath,
         walletStateBackupPath,
+        walletInitPendingPath,
+        walletInitPendingBackupPath,
         walletUnlockSessionPath,
         walletExplicitLockPath,
         walletControlLockPath,

package/dist/art/wallet.txt

@@ -1,10 +1,10 @@
                      ⛭ Write this down. Keep it secret, keep it safe. ⛭         
-▐▀▀▀▀▀▀▚    ╔──────────────────────────────────────────────────────────────────╗
-▛▞▀▀▀▀▀▀▚   │                                                                  │
-▌▝▀▀▀▀▀▀▀▌  │  1.achieved   6.achieved  11.achieved  16.achieved  21.achieved  │
-▌  ▗▙▙   ▌  │  2.achieved   7.achieved  12.achieved  17.achieved  22.achieved  │
-▌  ▐  ▌  ▌  │  3.achieved   8.achieved  13.achieved  18.achieved  23.achieved  │
-▌  ▐▀▀▚  ▌  │  4.achieved   9.achieved  14.achieved  19.achieved  24.achieved  │
-▌  ▐▄▄▞  ▌  │  5.achieved  10.achieved  15.achieved  20.achieved               │
-▌   ▘▘   ▌  │                                                                  │
-▝▀▀▀▀▀▀▀▀▘  ╚──────────────────────────────────────────────────────────────────╝
+▐▀▀▀▀▀▀▀▀▚  ╔──────────────────────────────────────────────────────────────────╗
+▛▞▀▀▀▀▀▀▀▀▚ │                                                                  │
+▌▝▀▀▀▀▀▀▀▀▀▌│  1.achieved   6.achieved  11.achieved  16.achieved  21.achieved  │
+▌   ▗▙▙    ▌│  2.achieved   7.achieved  12.achieved  17.achieved  22.achieved  │
+▌   ▐  ▌   ▌│  3.achieved   8.achieved  13.achieved  18.achieved  23.achieved  │
+▌   ▐▀▀▚   ▌│  4.achieved   9.achieved  14.achieved  19.achieved  24.achieved  │
+▌   ▐▄▄▞   ▌│  5.achieved  10.achieved  15.achieved  20.achieved               │
+▌    ▘▘    ▌│                                                                  │
+▝▀▀▀▀▀▀▀▀▀▀▘╚──────────────────────────────────────────────────────────────────╝

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

@@ -0,0 +1,14 @@
+import type { BootstrapPersistentState } from "./types.js";
+import type { SnapshotChunkManifest, SnapshotMetadata } from "../types.js";
+export declare function resolveBundledSnapshotChunkManifest(snapshot?: SnapshotMetadata): SnapshotChunkManifest;
+export declare function resolveSnapshotChunkCount(manifest: SnapshotChunkManifest): number;
+export declare function resolveSnapshotChunkSize(manifest: SnapshotChunkManifest, chunkIndex: number): number;
+export declare function resolveVerifiedChunkBytes(manifest: SnapshotChunkManifest, verifiedChunkCount: number): number;
+export declare function resolveVerifiedChunkCountFromBytes(manifest: SnapshotChunkManifest, bytes: number): number;
+export declare function clampVerifiedChunkCount(manifest: SnapshotChunkManifest, verifiedChunkCount: number): number;
+export declare function stateHasTrustedIntegrityFrontier(state: BootstrapPersistentState, manifest: SnapshotChunkManifest): boolean;
+export declare function createSnapshotChunkManifestRecord(options: {
+    snapshot: SnapshotMetadata;
+    chunkSha256s: string[];
+    chunkSizeBytes?: number;
+}): SnapshotChunkManifest;

package/dist/bitcoind/bootstrap/chunk-manifest.js

@@ -0,0 +1,85 @@
+import { DEFAULT_SNAPSHOT_CHUNK_SIZE_BYTES, SNAPSHOT_CHUNK_MANIFEST_VERSION, } from "./constants.js";
+import { DEFAULT_SNAPSHOT_CHUNK_MANIFEST } from "./default-snapshot-chunk-manifest.js";
+import { DEFAULT_SNAPSHOT_METADATA } from "./constants.js";
+function snapshotMatchesManifest(manifest, snapshot) {
+    return manifest.snapshotFilename === snapshot.filename
+        && manifest.snapshotHeight === snapshot.height
+        && manifest.snapshotSizeBytes === snapshot.sizeBytes
+        && manifest.snapshotSha256 === snapshot.sha256;
+}
+function snapshotMatchesDefault(snapshot) {
+    return snapshot.filename === DEFAULT_SNAPSHOT_METADATA.filename
+        && snapshot.height === DEFAULT_SNAPSHOT_METADATA.height
+        && snapshot.sizeBytes === DEFAULT_SNAPSHOT_METADATA.sizeBytes
+        && snapshot.sha256 === DEFAULT_SNAPSHOT_METADATA.sha256;
+}
+export function resolveBundledSnapshotChunkManifest(snapshot = DEFAULT_SNAPSHOT_METADATA) {
+    if (!snapshotMatchesDefault(snapshot)) {
+        throw new Error(`snapshot_chunk_manifest_unavailable_${snapshot.filename}`);
+    }
+    if (!snapshotMatchesManifest(DEFAULT_SNAPSHOT_CHUNK_MANIFEST, snapshot)) {
+        throw new Error(`snapshot_chunk_manifest_mismatch_${snapshot.filename}`);
+    }
+    return DEFAULT_SNAPSHOT_CHUNK_MANIFEST;
+}
+export function resolveSnapshotChunkCount(manifest) {
+    return manifest.chunkSha256s.length;
+}
+export function resolveSnapshotChunkSize(manifest, chunkIndex) {
+    if (chunkIndex < 0 || chunkIndex >= manifest.chunkSha256s.length) {
+        throw new Error(`snapshot_chunk_index_out_of_range_${chunkIndex}`);
+    }
+    const lastChunkIndex = manifest.chunkSha256s.length - 1;
+    if (chunkIndex < lastChunkIndex) {
+        return manifest.chunkSizeBytes;
+    }
+    const trailingBytes = manifest.snapshotSizeBytes % manifest.chunkSizeBytes;
+    return trailingBytes === 0 ? manifest.chunkSizeBytes : trailingBytes;
+}
+export function resolveVerifiedChunkBytes(manifest, verifiedChunkCount) {
+    const chunkCount = clampVerifiedChunkCount(manifest, verifiedChunkCount);
+    if (chunkCount <= 0) {
+        return 0;
+    }
+    if (chunkCount >= manifest.chunkSha256s.length) {
+        return manifest.snapshotSizeBytes;
+    }
+    return chunkCount * manifest.chunkSizeBytes;
+}
+export function resolveVerifiedChunkCountFromBytes(manifest, bytes) {
+    if (bytes >= manifest.snapshotSizeBytes) {
+        return manifest.chunkSha256s.length;
+    }
+    if (bytes <= 0) {
+        return 0;
+    }
+    return Math.floor(bytes / manifest.chunkSizeBytes);
+}
+export function clampVerifiedChunkCount(manifest, verifiedChunkCount) {
+    if (!Number.isFinite(verifiedChunkCount) || verifiedChunkCount <= 0) {
+        return 0;
+    }
+    return Math.min(Math.trunc(verifiedChunkCount), manifest.chunkSha256s.length);
+}
+export function stateHasTrustedIntegrityFrontier(state, manifest) {
+    if (state.integrityVersion !== SNAPSHOT_CHUNK_MANIFEST_VERSION) {
+        return false;
+    }
+    if (state.chunkSizeBytes !== manifest.chunkSizeBytes) {
+        return false;
+    }
+    const verifiedChunkCount = clampVerifiedChunkCount(manifest, state.verifiedChunkCount);
+    const verifiedBytes = resolveVerifiedChunkBytes(manifest, verifiedChunkCount);
+    return state.downloadedBytes === verifiedBytes;
+}
+export function createSnapshotChunkManifestRecord(options) {
+    return {
+        formatVersion: SNAPSHOT_CHUNK_MANIFEST_VERSION,
+        chunkSizeBytes: options.chunkSizeBytes ?? DEFAULT_SNAPSHOT_CHUNK_SIZE_BYTES,
+        snapshotFilename: options.snapshot.filename,
+        snapshotHeight: options.snapshot.height,
+        snapshotSizeBytes: options.snapshot.sizeBytes,
+        snapshotSha256: options.snapshot.sha256,
+        chunkSha256s: options.chunkSha256s,
+    };
+}

package/dist/bitcoind/bootstrap/chunk-recovery.d.ts

@@ -0,0 +1,4 @@
+import type { BootstrapPaths, BootstrapPersistentState, BootstrapStateSnapshotIdentity } from "./types.js";
+import type { SnapshotChunkManifest } from "../types.js";
+export declare function applyVerifiedFrontierState(state: BootstrapPersistentState, manifest: SnapshotChunkManifest, verifiedChunkCount: number): void;
+export declare function reconcileSnapshotDownloadArtifacts(paths: BootstrapPaths, state: BootstrapPersistentState, manifest: SnapshotChunkManifest, snapshotIdentity: BootstrapStateSnapshotIdentity): Promise<void>;

package/dist/bitcoind/bootstrap/chunk-recovery.js

@@ -0,0 +1,122 @@
+import { createHash } from "node:crypto";
+import { open, rename, rm } from "node:fs/promises";
+import { clampVerifiedChunkCount, resolveSnapshotChunkCount, resolveSnapshotChunkSize, resolveVerifiedChunkBytes, resolveVerifiedChunkCountFromBytes, stateHasTrustedIntegrityFrontier, } from "./chunk-manifest.js";
+import { resetSnapshotFiles, statOrNull } from "./snapshot-file.js";
+const TRUSTED_FRONTIER_REVERIFY_CHUNKS = 2;
+const HASH_READ_BUFFER_BYTES = 1024 * 1024;
+async function moveSnapshotPathToPartial(paths) {
+    const partInfo = await statOrNull(paths.partialSnapshotPath);
+    const fullInfo = await statOrNull(paths.snapshotPath);
+    if (fullInfo === null) {
+        return;
+    }
+    if (partInfo !== null && partInfo.size > fullInfo.size) {
+        await rm(paths.snapshotPath, { force: true });
+        return;
+    }
+    if (partInfo !== null) {
+        await rm(paths.partialSnapshotPath, { force: true });
+    }
+    await rename(paths.snapshotPath, paths.partialSnapshotPath);
+}
+async function hashChunkRange(path, manifest, chunkIndex) {
+    const file = await open(path, "r");
+    const chunkSizeBytes = resolveSnapshotChunkSize(manifest, chunkIndex);
+    const buffer = Buffer.allocUnsafe(Math.min(HASH_READ_BUFFER_BYTES, chunkSizeBytes));
+    const hash = createHash("sha256");
+    let remainingBytes = chunkSizeBytes;
+    let position = resolveVerifiedChunkBytes(manifest, chunkIndex);
+    try {
+        while (remainingBytes > 0) {
+            const readLength = Math.min(buffer.length, remainingBytes);
+            const { bytesRead } = await file.read(buffer, 0, readLength, position);
+            if (bytesRead === 0) {
+                return null;
+            }
+            hash.update(buffer.subarray(0, bytesRead));
+            remainingBytes -= bytesRead;
+            position += bytesRead;
+            if (bytesRead < readLength) {
+                return remainingBytes === 0 ? hash.digest("hex") : null;
+            }
+        }
+    }
+    finally {
+        await file.close();
+    }
+    return hash.digest("hex");
+}
+async function scanVerifiedPrefix(path, manifest, fileSize) {
+    const chunkCount = resolveSnapshotChunkCount(manifest);
+    for (let chunkIndex = 0; chunkIndex < chunkCount; chunkIndex += 1) {
+        const expectedChunkEnd = resolveVerifiedChunkBytes(manifest, chunkIndex + 1);
+        if (fileSize < expectedChunkEnd) {
+            return chunkIndex;
+        }
+        const actualSha256 = await hashChunkRange(path, manifest, chunkIndex);
+        if (actualSha256 !== manifest.chunkSha256s[chunkIndex]) {
+            return chunkIndex;
+        }
+    }
+    return chunkCount;
+}
+async function reverifyTrustedFrontier(path, manifest, verifiedChunkCount, fileSize) {
+    const maxCompleteChunkCount = resolveVerifiedChunkCountFromBytes(manifest, Math.min(fileSize, manifest.snapshotSizeBytes));
+    const tentativeVerifiedChunkCount = Math.min(clampVerifiedChunkCount(manifest, verifiedChunkCount), maxCompleteChunkCount);
+    const startChunk = Math.max(0, tentativeVerifiedChunkCount - TRUSTED_FRONTIER_REVERIFY_CHUNKS);
+    for (let chunkIndex = startChunk; chunkIndex < tentativeVerifiedChunkCount; chunkIndex += 1) {
+        const actualSha256 = await hashChunkRange(path, manifest, chunkIndex);
+        if (actualSha256 !== manifest.chunkSha256s[chunkIndex]) {
+            return chunkIndex;
+        }
+    }
+    return tentativeVerifiedChunkCount;
+}
+async function truncatePartialSnapshot(paths, verifiedBytes) {
+    const file = await open(paths.partialSnapshotPath, "a+");
+    try {
+        await file.truncate(verifiedBytes);
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+}
+export function applyVerifiedFrontierState(state, manifest, verifiedChunkCount) {
+    const clampedVerifiedChunkCount = clampVerifiedChunkCount(manifest, verifiedChunkCount);
+    state.integrityVersion = manifest.formatVersion;
+    state.chunkSizeBytes = manifest.chunkSizeBytes;
+    state.verifiedChunkCount = clampedVerifiedChunkCount;
+    state.downloadedBytes = resolveVerifiedChunkBytes(manifest, clampedVerifiedChunkCount);
+}
+export async function reconcileSnapshotDownloadArtifacts(paths, state, manifest, snapshotIdentity) {
+    if (snapshotIdentity === "different") {
+        await resetSnapshotFiles(paths);
+        state.phase = "snapshot_download";
+        state.loadTxOutSetComplete = false;
+        state.baseHeight = null;
+        state.tipHashHex = null;
+        state.lastError = null;
+        applyVerifiedFrontierState(state, manifest, 0);
+        state.validated = false;
+        return;
+    }
+    if (!state.validated) {
+        await moveSnapshotPathToPartial(paths);
+    }
+    const partialInfo = await statOrNull(paths.partialSnapshotPath);
+    if (partialInfo === null) {
+        applyVerifiedFrontierState(state, manifest, 0);
+        state.validated = false;
+        return;
+    }
+    const verifiedChunkCount = stateHasTrustedIntegrityFrontier(state, manifest)
+        ? await reverifyTrustedFrontier(paths.partialSnapshotPath, manifest, state.verifiedChunkCount, partialInfo.size)
+        : await scanVerifiedPrefix(paths.partialSnapshotPath, manifest, partialInfo.size);
+    const verifiedBytes = resolveVerifiedChunkBytes(manifest, verifiedChunkCount);
+    if (partialInfo.size !== verifiedBytes) {
+        await truncatePartialSnapshot(paths, verifiedBytes);
+    }
+    applyVerifiedFrontierState(state, manifest, verifiedChunkCount);
+    state.validated = false;
+}

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

@@ -1,5 +1,7 @@
 import type { SnapshotMetadata } from "../types.js";
-export declare const SNAPSHOT_METADATA_VERSION = 1;
+export declare const BOOTSTRAP_STATE_VERSION = 2;
+export declare const SNAPSHOT_CHUNK_MANIFEST_VERSION = 1;
+export declare const DEFAULT_SNAPSHOT_CHUNK_SIZE_BYTES: number;
 export declare const DOWNLOAD_RETRY_BASE_MS = 1000;
 export declare const DOWNLOAD_RETRY_MAX_MS = 30000;
 export declare const HEADER_POLL_MS = 2000;

package/dist/bitcoind/bootstrap/constants.js

@@ -1,4 +1,6 @@
-export const SNAPSHOT_METADATA_VERSION = 1;
+export const BOOTSTRAP_STATE_VERSION = 2;
+export const SNAPSHOT_CHUNK_MANIFEST_VERSION = 1;
+export const DEFAULT_SNAPSHOT_CHUNK_SIZE_BYTES = 4 * 1024 * 1024;
 export const DOWNLOAD_RETRY_BASE_MS = 1_000;
 export const DOWNLOAD_RETRY_MAX_MS = 30_000;
 export const HEADER_POLL_MS = 2_000;

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,15 +10,22 @@ 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"): Promise<void>;
+    ensureReady(indexedTip: ClientTip | null, expectedChain: "main" | "regtest", options?: {
+        signal?: AbortSignal;
+        retryState?: ManagedRpcRetryState;
+    }): Promise<void>;
     getStateForTesting(): Promise<{
         metadataVersion: number;
         snapshot: SnapshotMetadata;
         phase: BootstrapPhase;
+        integrityVersion: number;
+        chunkSizeBytes: number;
+        verifiedChunkCount: number;
         downloadedBytes: number;
         validated: boolean;
         loadTxOutSetComplete: boolean;

package/dist/bitcoind/bootstrap/controller.js

@@ -1,11 +1,13 @@
+import { join } from "node:path";
 import { createBootstrapProgressForTesting, ManagedProgressController } from "../progress.js";
 import { BitcoinRpcClient } from "../rpc.js";
 import { DEFAULT_SNAPSHOT_METADATA } from "./constants.js";
 import { downloadSnapshotFileForTesting } from "./download.js";
 import { waitForHeaders } from "./headers.js";
 import { resolveBootstrapPaths } from "./paths.js";
-import { loadBootstrapState, saveBootstrapState } from "./state.js";
-import { isSnapshotAlreadyLoaded } from "./chainstate.js";
+import { loadBootstrapStateRecord, saveBootstrapState } from "./state.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;
-    #statePromise = null;
+    #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() {
@@ -29,7 +35,7 @@ export class AssumeUtxoBootstrapController {
     get snapshot() {
         return this.#snapshot;
     }
-    async ensureReady(indexedTip, expectedChain) {
+    async ensureReady(indexedTip, expectedChain, options = {}) {
         if (expectedChain !== "main") {
             await this.#progress.setPhase("paused", {
                 ...createBootstrapProgressForTesting("paused", this.#snapshot),
@@ -45,42 +51,77 @@ export class AssumeUtxoBootstrapController {
             });
             return;
         }
-        const state = await this.#loadState();
+        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,
             state,
+            signal: options.signal,
+            snapshotIdentity,
         });
         if (!await isSnapshotAlreadyLoaded(this.#rpc, this.#snapshot, state)) {
-            await waitForHeaders(this.#rpc, this.#snapshot, this.#progress);
+            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,
@@ -88,14 +129,17 @@ 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() {
         return { ...(await this.#loadState()) };
     }
     async #loadState() {
-        this.#statePromise ??= loadBootstrapState(this.#paths, this.#snapshot);
-        return this.#statePromise;
+        return (await this.#loadStateRecord()).state;
+    }
+    async #loadStateRecord() {
+        this.#stateRecordPromise ??= loadBootstrapStateRecord(this.#paths, this.#snapshot);
+        return this.#stateRecordPromise;
     }
 }

package/dist/bitcoind/bootstrap/default-snapshot-chunk-manifest.d.ts

@@ -0,0 +1,2 @@
+import type { SnapshotChunkManifest } from "../types.js";
+export declare const DEFAULT_SNAPSHOT_CHUNK_MANIFEST: SnapshotChunkManifest;