@cogcoin/client 0.5.13 → 0.5.14

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@0.5.13` 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.14` 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/getblock-archive.d.ts

@@ -1,5 +1,5 @@
 import type { ManagedProgressController } from "../progress.js";
-import type { GetblockArchiveManifest } from "../types.js";
+import type { GetblockArchiveManifest, GetblockRangeManifest } from "../types.js";
 interface GetblockArchivePaths {
     directory: string;
     artifactPath: string;
@@ -10,8 +10,27 @@ export interface ReadyGetblockArchive {
     manifest: GetblockArchiveManifest;
     artifactPath: string;
 }
+export interface RefreshedGetblockManifest {
+    manifest: GetblockRangeManifest | null;
+    source: "remote" | "cache" | "none";
+}
+export declare function refreshGetblockManifestCache(options: {
+    dataDir: string;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+    persist?: boolean;
+}): Promise<RefreshedGetblockManifest>;
+export declare function resolveGetblockArchiveRange(manifest: GetblockRangeManifest, firstBlockHeight: number, lastBlockHeight: number): GetblockArchiveManifest | null;
+export declare function resolveGetblockArchiveRangeForHeight(manifest: GetblockRangeManifest, height: number): GetblockArchiveManifest | null;
 export declare function resolveGetblockArchivePathsForTesting(dataDir: string, firstBlockHeight?: number, lastBlockHeight?: number): GetblockArchivePaths;
 export declare function resolveReadyGetblockArchiveForTesting(dataDir: string, manifest: GetblockArchiveManifest): Promise<ReadyGetblockArchive | null>;
+export declare function preparePublishedGetblockArchiveRange(options: {
+    dataDir: string;
+    progress: Pick<ManagedProgressController, "setPhase">;
+    manifest: GetblockArchiveManifest;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<ReadyGetblockArchive>;
 export declare function prepareGetblockArchiveRange(options: {
     dataDir: string;
     progress: Pick<ManagedProgressController, "setPhase">;
@@ -33,7 +52,10 @@ export declare function prepareLatestGetblockArchive(options: {
 }): Promise<ReadyGetblockArchive | null>;
 export declare const prepareLatestGetblockArchiveForTesting: typeof prepareLatestGetblockArchive;
 export declare const prepareGetblockArchiveRangeForTesting: typeof prepareGetblockArchiveRange;
+export declare const preparePublishedGetblockArchiveRangeForTesting: typeof preparePublishedGetblockArchiveRange;
 export declare const deleteGetblockArchiveRangeForTesting: typeof deleteGetblockArchiveRange;
+export declare const refreshGetblockManifestCacheForTesting: typeof refreshGetblockManifestCache;
+export declare const resolveGetblockArchiveRangeForHeightForTesting: typeof resolveGetblockArchiveRangeForHeight;
 export declare function waitForGetblockArchiveImportForTesting(rpc: Pick<{
     getBlockchainInfo(): Promise<{
         blocks: number;

package/dist/bitcoind/bootstrap/getblock-archive.js

@@ -6,6 +6,7 @@ const GETBLOCK_ARCHIVE_STATE_VERSION = 1;
 const GETBLOCK_ARCHIVE_BASE_HEIGHT = 910_000;
 const GETBLOCK_ARCHIVE_RANGE_SIZE = 500;
 const GETBLOCK_ARCHIVE_FIRST_HEIGHT = GETBLOCK_ARCHIVE_BASE_HEIGHT + 1;
+const GETBLOCK_ARCHIVE_MANIFEST_FILENAME = "getblock-manifest.json";
 const GETBLOCK_ARCHIVE_REMOTE_BASE_URL = "https://snapshots.cogcoin.org/";
 const GETBLOCK_ARCHIVE_REMOTE_MANIFEST_URL = `${GETBLOCK_ARCHIVE_REMOTE_BASE_URL}getblock-manifest.json`;
 const TRUSTED_FRONTIER_REVERIFY_CHUNKS = 2;
@@ -14,6 +15,9 @@ const IMPORT_POLL_MS = 2_000;
 function buildRangeFilename(firstBlockHeight, lastBlockHeight) {
     return `getblock-${firstBlockHeight}-${lastBlockHeight}.dat`;
 }
+function resolveManifestCachePath(dataDir) {
+    return join(dataDir, "bootstrap", "getblock", GETBLOCK_ARCHIVE_MANIFEST_FILENAME);
+}
 function createInitialState() {
     return {
         metadataVersion: GETBLOCK_ARCHIVE_STATE_VERSION,
@@ -117,6 +121,12 @@ async function writeJsonAtomic(path, payload) {
     await writeFile(tempPath, JSON.stringify(payload, null, 2));
     await rename(tempPath, path);
 }
+async function writeTextAtomic(path, payload) {
+    await mkdir(dirname(path), { recursive: true });
+    const tempPath = `${path}.tmp`;
+    await writeFile(tempPath, payload);
+    await rename(tempPath, path);
+}
 async function loadState(paths) {
     try {
         const parsed = JSON.parse(await readFile(paths.statePath, "utf8"));
@@ -466,16 +476,74 @@ async function downloadRemoteArchive(paths, manifest, state, progress, fetchImpl
     }
 }
 async function fetchManifestRange(fetchImpl, firstBlockHeight, lastBlockHeight, signal) {
-    const response = await fetchImpl(GETBLOCK_ARCHIVE_REMOTE_MANIFEST_URL, { signal });
-    if (response.status === 404) {
+    const refreshed = await refreshGetblockManifestCache({
+        dataDir: "",
+        fetchImpl,
+        signal,
+        persist: false,
+    });
+    if (refreshed.manifest === null) {
         return null;
     }
+    return resolveGetblockArchiveRange(refreshed.manifest, firstBlockHeight, lastBlockHeight);
+}
+async function fetchAggregateManifest(fetchImpl, signal) {
+    const response = await fetchImpl(GETBLOCK_ARCHIVE_REMOTE_MANIFEST_URL, { signal });
     if (!response.ok) {
         throw new Error(`managed_getblock_archive_manifest_http_${response.status}`);
     }
-    const manifest = assertAggregateManifestShape(await response.json());
+    const rawText = await response.text();
+    return {
+        manifest: assertAggregateManifestShape(JSON.parse(rawText)),
+        rawText,
+    };
+}
+async function loadCachedAggregateManifest(dataDir) {
+    try {
+        return assertAggregateManifestShape(JSON.parse(await readFile(resolveManifestCachePath(dataDir), "utf8")));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        return null;
+    }
+}
+async function saveCachedAggregateManifest(dataDir, rawText) {
+    await writeTextAtomic(resolveManifestCachePath(dataDir), rawText);
+}
+export async function refreshGetblockManifestCache(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    try {
+        const { manifest, rawText } = await fetchAggregateManifest(fetchImpl, options.signal);
+        if (options.persist !== false) {
+            await saveCachedAggregateManifest(options.dataDir, rawText).catch(() => undefined);
+        }
+        return {
+            manifest,
+            source: "remote",
+        };
+    }
+    catch {
+        if (options.persist === false) {
+            return {
+                manifest: null,
+                source: "none",
+            };
+        }
+        const cachedManifest = await loadCachedAggregateManifest(options.dataDir);
+        return {
+            manifest: cachedManifest,
+            source: cachedManifest === null ? "none" : "cache",
+        };
+    }
+}
+export function resolveGetblockArchiveRange(manifest, firstBlockHeight, lastBlockHeight) {
     return manifest.ranges.find((range) => range.firstBlockHeight === firstBlockHeight && range.lastBlockHeight === lastBlockHeight) ?? null;
 }
+export function resolveGetblockArchiveRangeForHeight(manifest, height) {
+    return manifest.ranges.find((range) => range.firstBlockHeight <= height && height <= range.lastBlockHeight) ?? null;
+}
 export function resolveGetblockArchivePathsForTesting(dataDir, firstBlockHeight = GETBLOCK_ARCHIVE_FIRST_HEIGHT, lastBlockHeight = GETBLOCK_ARCHIVE_BASE_HEIGHT + GETBLOCK_ARCHIVE_RANGE_SIZE) {
     return resolvePaths(dataDir, firstBlockHeight, lastBlockHeight);
 }
@@ -512,49 +580,68 @@ async function resolveReadyLocalGetblockArchive(paths, manifest, state = null) {
 export async function resolveReadyGetblockArchiveForTesting(dataDir, manifest) {
     return resolveReadyLocalGetblockArchive(resolvePaths(dataDir, manifest.firstBlockHeight, manifest.lastBlockHeight), manifest);
 }
+export async function preparePublishedGetblockArchiveRange(options) {
+    const paths = resolvePaths(options.dataDir, options.manifest.firstBlockHeight, options.manifest.lastBlockHeight);
+    await mkdir(paths.directory, { recursive: true });
+    const state = await loadState(paths);
+    const readyLocal = await resolveReadyLocalGetblockArchive(paths, options.manifest, state);
+    if (readyLocal !== null) {
+        return readyLocal;
+    }
+    await downloadRemoteArchive(paths, options.manifest, state, options.progress, options.fetchImpl ?? fetch, options.signal);
+    const ready = await resolveReadyLocalGetblockArchive(paths, options.manifest, state);
+    if (ready === null) {
+        throw new Error("managed_getblock_archive_ready_resolution_failed");
+    }
+    return ready;
+}
 export async function prepareGetblockArchiveRange(options) {
     const paths = resolvePaths(options.dataDir, options.firstBlockHeight, options.lastBlockHeight);
     await mkdir(paths.directory, { recursive: true });
     const state = await loadState(paths);
     const fetchImpl = options.fetchImpl ?? fetch;
-    let remoteManifest;
-    try {
-        remoteManifest = await fetchManifestRange(fetchImpl, options.firstBlockHeight, options.lastBlockHeight, options.signal);
+    const refreshed = await refreshGetblockManifestCache({
+        dataDir: options.dataDir,
+        fetchImpl,
+        signal: options.signal,
+    });
+    const publishedRange = refreshed.manifest === null
+        ? null
+        : resolveGetblockArchiveRange(refreshed.manifest, options.firstBlockHeight, options.lastBlockHeight);
+    if (publishedRange !== null) {
+        return preparePublishedGetblockArchiveRange({
+            dataDir: options.dataDir,
+            progress: options.progress,
+            manifest: publishedRange,
+            fetchImpl,
+            signal: options.signal,
+        });
     }
-    catch {
-        const readyLocal = {
-            formatVersion: state.formatVersion,
-            chain: "main",
-            baseSnapshotHeight: GETBLOCK_ARCHIVE_BASE_HEIGHT,
-            firstBlockHeight: state.firstBlockHeight ?? options.firstBlockHeight,
-            lastBlockHeight: state.lastBlockHeight ?? options.lastBlockHeight,
-            artifactFilename: buildRangeFilename(state.firstBlockHeight ?? options.firstBlockHeight, state.lastBlockHeight ?? options.lastBlockHeight),
-            artifactSizeBytes: state.artifactSizeBytes,
-            artifactSha256: state.artifactSha256 ?? "",
-            chunkSizeBytes: state.chunkSizeBytes,
-            chunkSha256s: [],
-        };
-        if (state.validated
-            && state.firstBlockHeight === options.firstBlockHeight
-            && state.lastBlockHeight === options.lastBlockHeight
-            && state.artifactSha256 !== null) {
-            const resolved = await resolveReadyLocalGetblockArchive(paths, readyLocal, state).catch(() => null);
-            if (resolved !== null) {
-                return resolved;
-            }
+    const readyLocal = {
+        formatVersion: state.formatVersion,
+        chain: "main",
+        baseSnapshotHeight: GETBLOCK_ARCHIVE_BASE_HEIGHT,
+        firstBlockHeight: state.firstBlockHeight ?? options.firstBlockHeight,
+        lastBlockHeight: state.lastBlockHeight ?? options.lastBlockHeight,
+        artifactFilename: buildRangeFilename(state.firstBlockHeight ?? options.firstBlockHeight, state.lastBlockHeight ?? options.lastBlockHeight),
+        artifactSizeBytes: state.artifactSizeBytes,
+        artifactSha256: state.artifactSha256 ?? "",
+        chunkSizeBytes: state.chunkSizeBytes,
+        chunkSha256s: [],
+    };
+    if (state.validated
+        && state.firstBlockHeight === options.firstBlockHeight
+        && state.lastBlockHeight === options.lastBlockHeight
+        && state.artifactSha256 !== null) {
+        const resolved = await resolveReadyLocalGetblockArchive(paths, readyLocal, state).catch(() => null);
+        if (resolved !== null) {
+            return resolved;
         }
-        throw new Error("managed_getblock_archive_manifest_refresh_failed");
-    }
-    if (remoteManifest === null) {
-        return null;
     }
-    const readyLocal = await resolveReadyLocalGetblockArchive(paths, remoteManifest, state);
-    if (readyLocal !== null
-        && readyLocal.manifest.artifactSha256 === remoteManifest.artifactSha256) {
-        return readyLocal;
+    if (refreshed.source === "none") {
+        throw new Error("managed_getblock_archive_manifest_refresh_failed");
     }
-    await downloadRemoteArchive(paths, remoteManifest, state, options.progress, fetchImpl, options.signal);
-    return resolveReadyLocalGetblockArchive(paths, remoteManifest, state);
+    return null;
 }
 export async function deleteGetblockArchiveRange(options) {
     const paths = resolvePaths(options.dataDir, options.firstBlockHeight, options.lastBlockHeight);
@@ -571,7 +658,10 @@ export async function prepareLatestGetblockArchive(options) {
 }
 export const prepareLatestGetblockArchiveForTesting = prepareLatestGetblockArchive;
 export const prepareGetblockArchiveRangeForTesting = prepareGetblockArchiveRange;
+export const preparePublishedGetblockArchiveRangeForTesting = preparePublishedGetblockArchiveRange;
 export const deleteGetblockArchiveRangeForTesting = deleteGetblockArchiveRange;
+export const refreshGetblockManifestCacheForTesting = refreshGetblockManifestCache;
+export const resolveGetblockArchiveRangeForHeightForTesting = resolveGetblockArchiveRangeForHeight;
 export async function waitForGetblockArchiveImportForTesting(rpc, progress, targetEndHeight, signal) {
     await waitForGetblockArchiveImport(rpc, progress, targetEndHeight, signal);
 }

package/dist/bitcoind/bootstrap.d.ts

@@ -1,7 +1,7 @@
 export { DEFAULT_SNAPSHOT_METADATA } from "./bootstrap/constants.js";
 export { AssumeUtxoBootstrapController } from "./bootstrap/controller.js";
 export { downloadSnapshotFileForTesting } from "./bootstrap/download.js";
-export { deleteGetblockArchiveRange, deleteGetblockArchiveRangeForTesting, prepareGetblockArchiveRange, prepareGetblockArchiveRangeForTesting, prepareLatestGetblockArchive, prepareLatestGetblockArchiveForTesting, resolveGetblockArchivePathsForTesting, resolveReadyGetblockArchiveForTesting, waitForGetblockArchiveImport, waitForGetblockArchiveImportForTesting, } from "./bootstrap/getblock-archive.js";
+export { deleteGetblockArchiveRange, deleteGetblockArchiveRangeForTesting, preparePublishedGetblockArchiveRange, preparePublishedGetblockArchiveRangeForTesting, prepareGetblockArchiveRange, prepareGetblockArchiveRangeForTesting, prepareLatestGetblockArchive, prepareLatestGetblockArchiveForTesting, refreshGetblockManifestCache, refreshGetblockManifestCacheForTesting, resolveGetblockArchiveRange, resolveGetblockArchiveRangeForHeight, resolveGetblockArchiveRangeForHeightForTesting, resolveGetblockArchivePathsForTesting, resolveReadyGetblockArchiveForTesting, waitForGetblockArchiveImport, waitForGetblockArchiveImportForTesting, } from "./bootstrap/getblock-archive.js";
 export { waitForHeadersForTesting } from "./bootstrap/headers.js";
 export { resolveBootstrapPathsForTesting } from "./bootstrap/paths.js";
 export { loadBootstrapStateForTesting, saveBootstrapStateForTesting, createBootstrapStateForTesting, } from "./bootstrap/state.js";

package/dist/bitcoind/bootstrap.js

@@ -1,7 +1,7 @@
 export { DEFAULT_SNAPSHOT_METADATA } from "./bootstrap/constants.js";
 export { AssumeUtxoBootstrapController } from "./bootstrap/controller.js";
 export { downloadSnapshotFileForTesting } from "./bootstrap/download.js";
-export { deleteGetblockArchiveRange, deleteGetblockArchiveRangeForTesting, prepareGetblockArchiveRange, prepareGetblockArchiveRangeForTesting, prepareLatestGetblockArchive, prepareLatestGetblockArchiveForTesting, resolveGetblockArchivePathsForTesting, resolveReadyGetblockArchiveForTesting, waitForGetblockArchiveImport, waitForGetblockArchiveImportForTesting, } from "./bootstrap/getblock-archive.js";
+export { deleteGetblockArchiveRange, deleteGetblockArchiveRangeForTesting, preparePublishedGetblockArchiveRange, preparePublishedGetblockArchiveRangeForTesting, prepareGetblockArchiveRange, prepareGetblockArchiveRangeForTesting, prepareLatestGetblockArchive, prepareLatestGetblockArchiveForTesting, refreshGetblockManifestCache, refreshGetblockManifestCacheForTesting, resolveGetblockArchiveRange, resolveGetblockArchiveRangeForHeight, resolveGetblockArchiveRangeForHeightForTesting, resolveGetblockArchivePathsForTesting, resolveReadyGetblockArchiveForTesting, waitForGetblockArchiveImport, waitForGetblockArchiveImportForTesting, } from "./bootstrap/getblock-archive.js";
 export { waitForHeadersForTesting } from "./bootstrap/headers.js";
 export { resolveBootstrapPathsForTesting } from "./bootstrap/paths.js";
 export { loadBootstrapStateForTesting, saveBootstrapStateForTesting, createBootstrapStateForTesting, } from "./bootstrap/state.js";

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

@@ -1,4 +1,4 @@
-import { AssumeUtxoBootstrapController, deleteGetblockArchiveRange, prepareGetblockArchiveRange, } from "../bootstrap.js";
+import { AssumeUtxoBootstrapController, deleteGetblockArchiveRange, preparePublishedGetblockArchiveRange, refreshGetblockManifestCache, resolveGetblockArchiveRangeForHeight, } from "../bootstrap.js";
 import { createRpcClient } from "../node.js";
 import { attachOrStartManagedBitcoindService, stopManagedBitcoindService, } from "../service.js";
 import { closeFollowLoopResources, scheduleSync, startFollowingTipLoop } from "./follow-loop.js";
@@ -6,21 +6,6 @@ import { loadVisibleFollowBlockTimes } from "./follow-block-times.js";
 import { createBlockRateTracker, createInitialSyncResult, } from "./internal-types.js";
 import { syncToTip as runManagedSync } from "./sync-engine.js";
 const GETBLOCK_RANGE_BASE_HEIGHT = 910_000;
-const GETBLOCK_RANGE_SIZE = 500;
-function isBoundaryHeight(height) {
-    return height >= GETBLOCK_RANGE_BASE_HEIGHT
-        && (height - GETBLOCK_RANGE_BASE_HEIGHT) % GETBLOCK_RANGE_SIZE === 0;
-}
-function resolveNextBoundary(height) {
-    if (height < GETBLOCK_RANGE_BASE_HEIGHT) {
-        return GETBLOCK_RANGE_BASE_HEIGHT;
-    }
-    if (isBoundaryHeight(height)) {
-        return height;
-    }
-    return GETBLOCK_RANGE_BASE_HEIGHT
-        + Math.ceil((height - GETBLOCK_RANGE_BASE_HEIGHT) / GETBLOCK_RANGE_SIZE) * GETBLOCK_RANGE_SIZE;
-}
 function mergeSyncResults(target, source) {
     target.appliedBlocks += source.appliedBlocks;
     target.rewoundBlocks += source.rewoundBlocks;
@@ -218,56 +203,93 @@ export class DefaultManagedBitcoindClient {
         this.#assertOpen();
         await this.#progress.playCompletionScene();
     }
+    async #setGetblockStatusMessage(currentHeight, message, targetHeight = currentHeight) {
+        const safeTargetHeight = Math.max(currentHeight, targetHeight);
+        await this.#progress.setPhase("bitcoin_sync", {
+            blocks: currentHeight,
+            headers: safeTargetHeight,
+            targetHeight: safeTargetHeight,
+            etaSeconds: null,
+            lastError: null,
+            message,
+        });
+    }
+    async #refreshGetblockManifest(currentHeight, abortSignal, mode) {
+        await this.#setGetblockStatusMessage(currentHeight, mode === "startup"
+            ? "Fetching Getblock manifest."
+            : "Refreshing Getblock manifest.");
+        const refreshed = await refreshGetblockManifestCache({
+            dataDir: this.#dataDir,
+            fetchImpl: this.#fetchImpl,
+            signal: abortSignal,
+        });
+        if (refreshed.source === "remote" && refreshed.manifest !== null) {
+            await this.#setGetblockStatusMessage(currentHeight, `Getblock manifest ready through height ${refreshed.manifest.publishedThroughHeight.toLocaleString()}.`, refreshed.manifest.publishedThroughHeight);
+            return refreshed.manifest;
+        }
+        if (refreshed.source === "cache" && refreshed.manifest !== null) {
+            await this.#setGetblockStatusMessage(currentHeight, `Warning: Getblock manifest fetch failed; using cached manifest through height ${refreshed.manifest.publishedThroughHeight.toLocaleString()}.`, refreshed.manifest.publishedThroughHeight);
+            return refreshed.manifest;
+        }
+        await this.#setGetblockStatusMessage(currentHeight, "Warning: Getblock manifest fetch failed and no cached manifest is available; continuing with ordinary Bitcoin sync.");
+        return null;
+    }
     async #syncWithStagedRanges(abortSignal) {
         const aggregate = createInitialSyncResult();
-        let stagedModeEnabled = true;
         await this.#ensureBootstrapReady(abortSignal);
-        while (stagedModeEnabled) {
-            const info = await this.#rpc.getBlockchainInfo();
-            if (info.blocks < GETBLOCK_RANGE_BASE_HEIGHT) {
-                break;
+        let info = await this.#rpc.getBlockchainInfo();
+        if (info.blocks < GETBLOCK_RANGE_BASE_HEIGHT) {
+            mergeSyncResults(aggregate, await this.#runManagedSyncPass(null, abortSignal));
+            return aggregate;
+        }
+        let manifest = await this.#refreshGetblockManifest(info.blocks, abortSignal, "startup");
+        while (manifest !== null) {
+            const nextMissingHeight = info.blocks + 1;
+            if (nextMissingHeight > manifest.publishedThroughHeight) {
+                const refreshed = await this.#refreshGetblockManifest(info.blocks, abortSignal, "refresh");
+                if (refreshed === null || refreshed.publishedThroughHeight < nextMissingHeight) {
+                    manifest = refreshed;
+                    break;
+                }
+                manifest = refreshed;
             }
-            const nextBoundary = resolveNextBoundary(info.blocks);
-            if (nextBoundary === null) {
+            if (manifest === null) {
                 break;
             }
-            if (!isBoundaryHeight(info.blocks)) {
-                mergeSyncResults(aggregate, await this.#runManagedSyncPass(nextBoundary, abortSignal));
-                continue;
+            const selectedRange = resolveGetblockArchiveRangeForHeight(manifest, nextMissingHeight);
+            if (selectedRange === null) {
+                await this.#setGetblockStatusMessage(info.blocks, `Warning: Getblock manifest has no published range for next missing block ${nextMissingHeight.toLocaleString()}; continuing with ordinary Bitcoin sync.`);
+                break;
             }
-            const firstBlockHeight = info.blocks + 1;
-            const lastBlockHeight = info.blocks + GETBLOCK_RANGE_SIZE;
+            await this.#setGetblockStatusMessage(info.blocks, `Using Getblock range ${selectedRange.firstBlockHeight.toLocaleString()}-${selectedRange.lastBlockHeight.toLocaleString()} for current Bitcoin height ${info.blocks.toLocaleString()} (next missing block ${nextMissingHeight.toLocaleString()}).`, selectedRange.lastBlockHeight);
             let readyRange;
             try {
-                readyRange = await prepareGetblockArchiveRange({
+                readyRange = await preparePublishedGetblockArchiveRange({
                     dataDir: this.#dataDir,
                     progress: this.#progress,
-                    firstBlockHeight,
-                    lastBlockHeight,
+                    manifest: selectedRange,
                     fetchImpl: this.#fetchImpl,
                     signal: abortSignal,
                 });
             }
             catch {
-                stagedModeEnabled = false;
-                break;
-            }
-            if (readyRange === null) {
-                stagedModeEnabled = false;
+                await this.#setGetblockStatusMessage(info.blocks, "Warning: Getblock range staging failed; continuing with ordinary Bitcoin sync.");
                 break;
             }
             const stagedRestartActive = await this.#restartManagedNodeWithRange(readyRange, abortSignal);
-            mergeSyncResults(aggregate, await this.#runManagedSyncPass(lastBlockHeight, abortSignal));
+            mergeSyncResults(aggregate, await this.#runManagedSyncPass(selectedRange.lastBlockHeight, abortSignal));
             if (stagedRestartActive) {
                 await deleteGetblockArchiveRange({
                     dataDir: this.#dataDir,
-                    firstBlockHeight,
-                    lastBlockHeight,
+                    firstBlockHeight: selectedRange.firstBlockHeight,
+                    lastBlockHeight: selectedRange.lastBlockHeight,
                 }).catch(() => undefined);
             }
             else {
-                stagedModeEnabled = false;
+                await this.#setGetblockStatusMessage(selectedRange.lastBlockHeight, "Warning: Restarting with the Getblock archive failed; continuing with ordinary Bitcoin sync.");
+                break;
             }
+            info = await this.#rpc.getBlockchainInfo();
         }
         mergeSyncResults(aggregate, await this.#runManagedSyncPass(null, abortSignal));
         return aggregate;

package/dist/bitcoind/testing.d.ts

@@ -5,7 +5,7 @@ export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopInde
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";
 export { attachOrStartManagedBitcoindService, buildManagedServiceArgsForTesting, readManagedBitcoindServiceStatusForTesting, resolveManagedBitcoindDbcacheMiB, stopManagedBitcoindService, shutdownManagedBitcoindServiceForTesting, writeBitcoinConfForTesting, } from "./service.js";
-export { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, createBootstrapStateForTesting, deleteGetblockArchiveRangeForTesting, downloadSnapshotFileForTesting, loadBootstrapStateForTesting, prepareGetblockArchiveRangeForTesting, prepareLatestGetblockArchiveForTesting, resolveBootstrapPathsForTesting, resolveGetblockArchivePathsForTesting, resolveReadyGetblockArchiveForTesting, saveBootstrapStateForTesting, validateSnapshotFileForTesting, waitForGetblockArchiveImportForTesting, waitForHeadersForTesting, } from "./bootstrap.js";
+export { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, createBootstrapStateForTesting, deleteGetblockArchiveRangeForTesting, downloadSnapshotFileForTesting, loadBootstrapStateForTesting, preparePublishedGetblockArchiveRangeForTesting, prepareGetblockArchiveRangeForTesting, prepareLatestGetblockArchiveForTesting, refreshGetblockManifestCacheForTesting, resolveBootstrapPathsForTesting, resolveGetblockArchivePathsForTesting, resolveGetblockArchiveRangeForHeightForTesting, 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

@@ -5,7 +5,7 @@ export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopInde
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";
 export { attachOrStartManagedBitcoindService, buildManagedServiceArgsForTesting, readManagedBitcoindServiceStatusForTesting, resolveManagedBitcoindDbcacheMiB, stopManagedBitcoindService, shutdownManagedBitcoindServiceForTesting, writeBitcoinConfForTesting, } from "./service.js";
-export { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, createBootstrapStateForTesting, deleteGetblockArchiveRangeForTesting, downloadSnapshotFileForTesting, loadBootstrapStateForTesting, prepareGetblockArchiveRangeForTesting, prepareLatestGetblockArchiveForTesting, resolveBootstrapPathsForTesting, resolveGetblockArchivePathsForTesting, resolveReadyGetblockArchiveForTesting, saveBootstrapStateForTesting, validateSnapshotFileForTesting, waitForGetblockArchiveImportForTesting, waitForHeadersForTesting, } from "./bootstrap.js";
+export { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, createBootstrapStateForTesting, deleteGetblockArchiveRangeForTesting, downloadSnapshotFileForTesting, loadBootstrapStateForTesting, preparePublishedGetblockArchiveRangeForTesting, prepareGetblockArchiveRangeForTesting, prepareLatestGetblockArchiveForTesting, refreshGetblockManifestCacheForTesting, resolveBootstrapPathsForTesting, resolveGetblockArchivePathsForTesting, resolveGetblockArchiveRangeForHeightForTesting, 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/cli/commands/status.js

@@ -24,7 +24,7 @@ export async function runStatusCommand(parsed, context) {
             }));
             return 0;
         }
-        writeLine(context.stdout, formatWalletOverviewReport(readContext));
+        writeLine(context.stdout, formatWalletOverviewReport(readContext, await context.readPackageVersion()));
         return 0;
     }
     finally {

package/dist/cli/commands/sync.js

@@ -1,14 +1,106 @@
 import { dirname } from "node:path";
 import { formatManagedSyncErrorMessage } from "../../bitcoind/errors.js";
+import { formatBytes, formatDuration } from "../../bitcoind/progress/formatting.js";
 import { FileLockBusyError, acquireFileLock } from "../../wallet/fs/lock.js";
 import { resolveWalletRootIdFromLocalArtifacts } from "../../wallet/root-resolution.js";
-import { writeLine } from "../io.js";
+import { usesTtyProgress, writeLine } from "../io.js";
 import { classifyCliError, formatCliTextError } from "../output.js";
 import { createStopSignalWatcher, waitForCompletionOrStop } from "../signals.js";
+const SYNC_PROGRESS_LOG_INTERVAL_MS = 5_000;
+function createSyncProgressReporter(options) {
+    let lastPhase = null;
+    let lastMessage = "";
+    let lastDownloadPrintedAt = 0;
+    let lastDownloadBytes = null;
+    let lastImportPrintedAt = 0;
+    let lastImportBlocks = null;
+    const infoEnabled = options.progressOutput !== "none";
+    function shouldPrintEntryMessage(message, phase) {
+        if (message === "Waiting to start managed sync." || message === "Sync complete.") {
+            return false;
+        }
+        if (message.startsWith("Warning:")) {
+            return true;
+        }
+        if (!infoEnabled) {
+            return false;
+        }
+        if (phase === "getblock_archive_download" || phase === "getblock_archive_import") {
+            return true;
+        }
+        return phase === "snapshot_download"
+            || phase === "wait_headers_for_snapshot"
+            || phase === "load_snapshot"
+            || phase === "bitcoin_sync"
+            || phase === "cogcoin_sync"
+            || message.includes("Getblock manifest")
+            || message.startsWith("Fetching Getblock manifest.")
+            || message.startsWith("Refreshing Getblock manifest.")
+            || message.startsWith("Using Getblock range ");
+    }
+    function formatDownloadLine(label, event) {
+        const current = event.progress.downloadedBytes ?? 0;
+        const total = event.progress.totalBytes ?? 0;
+        const percent = event.progress.percent ?? (total > 0 ? (current / total) * 100 : 0);
+        const speed = event.progress.bytesPerSecond === null ? "--" : `${formatBytes(event.progress.bytesPerSecond)}/s`;
+        return `${label}: ${percent.toFixed(2)}% (${formatBytes(current)} / ${formatBytes(total)}, ${speed}, ETA ${formatDuration(event.progress.etaSeconds)})`;
+    }
+    return (event) => {
+        const message = event.progress.message.trim();
+        const phaseChanged = event.phase !== lastPhase;
+        const messageChanged = message !== lastMessage;
+        if ((phaseChanged || messageChanged) && shouldPrintEntryMessage(message, event.phase)) {
+            options.write(message);
+        }
+        if (infoEnabled && event.phase === "getblock_archive_download") {
+            const now = Date.now();
+            const currentBytes = event.progress.downloadedBytes ?? 0;
+            const isComplete = (event.progress.percent ?? 0) >= 100;
+            const shouldPrintMilestone = phaseChanged
+                || lastDownloadBytes !== currentBytes && (isComplete
+                    || now - lastDownloadPrintedAt >= SYNC_PROGRESS_LOG_INTERVAL_MS);
+            if (shouldPrintMilestone) {
+                options.write(formatDownloadLine("Getblock download", event));
+                lastDownloadPrintedAt = now;
+                lastDownloadBytes = currentBytes;
+            }
+        }
+        else if (infoEnabled && event.phase === "snapshot_download") {
+            const now = Date.now();
+            const currentBytes = event.progress.downloadedBytes ?? 0;
+            const isComplete = (event.progress.percent ?? 0) >= 100;
+            const shouldPrintMilestone = phaseChanged
+                || lastDownloadBytes !== currentBytes && (isComplete
+                    || now - lastDownloadPrintedAt >= SYNC_PROGRESS_LOG_INTERVAL_MS);
+            if (shouldPrintMilestone) {
+                options.write(formatDownloadLine("Snapshot download", event));
+                lastDownloadPrintedAt = now;
+                lastDownloadBytes = currentBytes;
+            }
+        }
+        else if (infoEnabled && event.phase === "getblock_archive_import") {
+            const now = Date.now();
+            const currentBlocks = event.progress.blocks ?? 0;
+            const targetBlocks = event.progress.targetHeight ?? currentBlocks;
+            const isComplete = currentBlocks >= targetBlocks;
+            const shouldPrintMilestone = phaseChanged
+                || lastImportBlocks !== currentBlocks && (isComplete
+                    || now - lastImportPrintedAt >= SYNC_PROGRESS_LOG_INTERVAL_MS);
+            if (shouldPrintMilestone) {
+                options.write(`Getblock import: Bitcoin ${currentBlocks.toLocaleString()} / ${targetBlocks.toLocaleString()}`);
+                lastImportPrintedAt = now;
+                lastImportBlocks = currentBlocks;
+            }
+        }
+        lastPhase = event.phase;
+        lastMessage = message;
+    };
+}
 export async function runSyncCommand(parsed, context) {
     const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
     const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
     const runtimePaths = context.resolveWalletRuntimePaths();
+    const ttyProgressActive = usesTtyProgress(parsed.progressOutput, context.stderr);
     let controlLock = null;
     let store = null;
     let storeOwned = true;
@@ -40,6 +132,12 @@ export async function runSyncCommand(parsed, context) {
             dataDir,
             walletRootId: walletRoot.walletRootId,
             progressOutput: parsed.progressOutput,
+            onProgress: ttyProgressActive ? undefined : createSyncProgressReporter({
+                progressOutput: parsed.progressOutput,
+                write: (line) => {
+                    writeLine(context.stderr, line);
+                },
+            }),
         });
         storeOwned = false;
         const stopWatcher = createStopSignalWatcher(context.signalSource, context.stderr, client, context.forceExit, [runtimePaths.walletControlLockPath]);