@cogcoin/client 0.5.5 → 0.5.7

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@0.5.5` is the store-backed Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
+`@cogcoin/client@0.5.7` 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.
 
@@ -107,6 +107,7 @@ The built-in managed-node integration:
 - uses RPC for durable reads and ZMQ `hashblock` notifications for tip following
 - launches a local full node with cookie auth
 - defaults to an assumeutxo-first mainnet bootstrap using `https://snapshots.cogcoin.org/utxo-910000.dat`
+- opportunistically loads the public getblock archive family from `https://snapshots.cogcoin.org/getblock-910000-latest.{json,dat}` to accelerate post-`910000` Bitcoin Core catch-up
 - composes the existing SQLite-backed client rather than replacing it
 
 If `dataDir` is omitted, the managed node defaults to:
@@ -120,7 +121,15 @@ On a fresh mainnet managed sync, `syncToTip()` or `startFollowingTip()`:
 1. downloads the pinned Cogcoin UTXO snapshot with resume support
 2. validates its known size and SHA-256
 3. loads it with Bitcoin Core assumeutxo
-4. continues Bitcoin sync and Cogcoin replay from the managed node until the live tip is caught up
+4. opportunistically downloads and validates the public getblock archive for raw post-snapshot Bitcoin blocks
+5. loads that archive into managed Bitcoin Core when available
+6. continues Bitcoin sync and Cogcoin replay from the managed node until the live tip is caught up
+
+The public getblock archive provenance is tracked in the companion scraper repository:
+
+- [`github.com/cogcoin/bitcoin-scrape`](https://github.com/cogcoin/bitcoin-scrape)
+
+That repo documents how the `getblock-910000-latest.dat` and `getblock-910000-latest.json` artifacts are assembled from `bitcoin-cli getblockhash` plus `bitcoin-cli getblock <hash> 0`, including the blk-style file layout, manifest format, durability guarantees, and height-based cache-busting rules.
 
 The managed `bitcoind` client also exposes:
 

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

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

package/dist/bitcoind/bootstrap/chainstate.js

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

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

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

package/dist/bitcoind/bootstrap/controller.js

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

package/dist/bitcoind/bootstrap/getblock-archive.d.ts

@@ -0,0 +1,39 @@
+import type { ManagedProgressController } from "../progress.js";
+import type { GetblockArchiveManifest } from "../types.js";
+interface GetblockArchivePaths {
+    directory: string;
+    artifactPath: string;
+    partialArtifactPath: string;
+    manifestPath: string;
+    partialManifestPath: string;
+    statePath: string;
+}
+export interface ReadyGetblockArchive {
+    manifest: GetblockArchiveManifest;
+    artifactPath: string;
+    manifestPath: string;
+}
+export declare function resolveGetblockArchivePathsForTesting(dataDir: string): GetblockArchivePaths;
+export declare function resolveReadyGetblockArchiveForTesting(dataDir: string): Promise<ReadyGetblockArchive | null>;
+export declare function prepareLatestGetblockArchive(options: {
+    dataDir: string;
+    progress: Pick<ManagedProgressController, "setPhase">;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<ReadyGetblockArchive | null>;
+export declare const prepareLatestGetblockArchiveForTesting: typeof prepareLatestGetblockArchive;
+export declare function waitForGetblockArchiveImportForTesting(rpc: Pick<{
+    getBlockchainInfo(): Promise<{
+        blocks: number;
+        headers: number;
+        bestblockhash: string;
+    }>;
+}, "getBlockchainInfo">, progress: Pick<ManagedProgressController, "setPhase">, targetEndHeight: number, signal?: AbortSignal): Promise<void>;
+export declare function waitForGetblockArchiveImport(rpc: Pick<{
+    getBlockchainInfo(): Promise<{
+        blocks: number;
+        headers: number;
+        bestblockhash: string;
+    }>;
+}, "getBlockchainInfo">, progress: Pick<ManagedProgressController, "setPhase">, targetEndHeight: number, signal?: AbortSignal): Promise<void>;
+export {};