@cogcoin/client 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cogcoin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# `@cogcoin/client`
+
+`@cogcoin/client@0.5.0` 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.
+
+## Links
+
+- Website: [cogcoin.org](https://cogcoin.org)
+- Whitepaper: [cogcoin.org/whitepaper.md](https://cogcoin.org/whitepaper.md)
+- Source: [github.com/cogcoin/client](https://github.com/cogcoin/client)
+- Bitcoin package: [npmjs.com/package/@cogcoin/bitcoin](https://www.npmjs.com/package/@cogcoin/bitcoin)
+- Genesis package: [npmjs.com/package/@cogcoin/genesis](https://www.npmjs.com/package/@cogcoin/genesis)
+- Indexer package: [npmjs.com/package/@cogcoin/indexer](https://www.npmjs.com/package/@cogcoin/indexer)
+- Scoring package: [npmjs.com/package/@cogcoin/scoring](https://www.npmjs.com/package/@cogcoin/scoring)
+
+## Quick Start
+
+Install the package:
+
+```bash
+npm install @cogcoin/client
+```
+
+Then, from your project root, run:
+
+```bash
+node node_modules/@cogcoin/genesis/verify.mjs
+npx cogcoin init
+npx cogcoin sync
+```
+
+Verify the installed genesis artifacts before using the client in a production implementation.
+The installed package provides the `cogcoin` command for local wallet setup, sync, reads, writes, and mining workflows.
+
+## Dependency Surface
+
+The published package depends on:
+
+- `@cogcoin/bitcoin@30.2.0`
+- `@cogcoin/genesis@1.0.0`
+- `@cogcoin/indexer@1.0.0`
+- `@cogcoin/scoring@1.0.0`
+- `@scure/base@^2.0.0`
+- `@scure/bip32@^2.0.1`
+- `@scure/bip39@^2.0.1`
+- `better-sqlite3@12.8.0`
+- `zeromq@6.5.0`
+
+`@cogcoin/vectors` is kept as a repository development dependency for conformance tests and is not part of the published runtime dependency surface.
+
+## API
+
+Root package:
+
+- `openClient(options)`
+- `createClientStoreAdapter(store)`
+
+SQLite subpath:
+
+- `@cogcoin/client/sqlite`
+- `openSqliteStore(options)`
+- `migrateSqliteStore(database)`
+
+Managed node subpath:
+
+- `@cogcoin/client/bitcoind`
+- `openManagedBitcoindClient(options)`
+
+## CLI
+
+The installed `cogcoin` command covers the first-party local wallet and node workflow:
+
+- wallet lifecycle commands such as `init`, `unlock`, `lock`, `repair`, `export`, and `import`
+- sync and service commands such as `status`, `sync`, and `follow`
+- domain and field commands such as `register`, `anchor`, `show`, `domains`, `fields`, `buy`, `sell`, and `transfer`
+- COG and reputation commands such as `send`, `cog lock`, `claim`, `reclaim`, `rep give`, and `rep revoke`
+- mining and hook commands such as `mine`, `mine start`, `mine stop`, `mine status`, `mine log`, `mine setup`, and `hooks status`
+
+The CLI also supports stable `--output json` and `--output preview-json` envelopes on the commands that advertise machine-readable output.
+
+## SQLite Store
+
+The built-in SQLite adapter persists opaque indexer bytes rather than protocol tables:
+
+- serialized `IndexerState`
+- serialized `BlockRecord`
+- current tip metadata
+- periodic checkpoints
+
+This keeps correctness tied to `@cogcoin/indexer` rather than duplicating protocol state in SQL.
+
+## Managed `bitcoind`
+
+The built-in managed-node integration:
+
+- resolves Bitcoin Core binaries through `@cogcoin/bitcoin`
+- 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`
+- composes the existing SQLite-backed client rather than replacing it
+
+If `dataDir` is omitted, the managed node defaults to:
+
+- macOS: `~/Library/Application Support/Cogcoin/bitcoin`
+- Linux: `~/.cogcoin/bitcoin`
+- Windows: `%APPDATA%\\Cogcoin\\bitcoin`
+
+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
+
+The managed `bitcoind` client also exposes:
+
+- `onProgress(event)` for structured bootstrap/sync progress updates
+- `progressOutput: "auto" | "tty" | "none"` for the built-in scroll-train terminal progress UI
+
+The default TTY progress renderer ships with the package and uses the bundled scroll, train, and quote assets from `dist/art/*` and `dist/writing_quotes.json`.
+
+## Published Contents
+
+- `dist/index.js`: public package entrypoint
+- `dist/index.d.ts`: bundled type declarations
+- `dist/cli.js`: installed `cogcoin` command
+- `dist/bitcoind/index.js`: managed `bitcoind` subpath
+- `dist/bitcoind/index.d.ts`: managed `bitcoind` declarations
+- `dist/sqlite/index.js`: SQLite adapter subpath
+- `dist/sqlite/index.d.ts`: SQLite adapter declarations
+- `dist/writing_quotes.json`: bundled progress UI quote dataset
+- `dist/art/*`: bundled terminal progress artwork
+- `dist/*`: compiled ESM implementation
+- `README.md`: package guide
+- `LICENSE`: MIT license text

package/dist/app-paths.d.ts

@@ -0,0 +1,38 @@
+export interface CogcoinPathResolution {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    homeDirectory?: string;
+}
+export interface CogcoinResolvedPaths {
+    dataRoot: string;
+    configRoot: string;
+    stateRoot: string;
+    runtimeRoot: string;
+    hooksRoot: string;
+    bitcoinDataDir: string;
+    clientDataDir: string;
+    clientDatabasePath: string;
+    indexerRoot: string;
+    clientConfigPath: string;
+    walletStateDirectory: string;
+    walletStatePath: string;
+    walletStateBackupPath: string;
+    walletUnlockSessionPath: string;
+    walletControlLockPath: string;
+    bitcoindLockPath: string;
+    bitcoindStatusPath: string;
+    indexerDaemonLockPath: string;
+    indexerStatusPath: string;
+    hooksMiningDir: string;
+    hooksMiningEntrypointPath: string;
+    hooksMiningPackageJsonPath: string;
+    miningRoot: string;
+    miningStatusPath: string;
+    miningEventsPath: string;
+    miningControlLockPath: string;
+}
+export declare function resolveCogcoinPathsForTesting(resolution?: CogcoinPathResolution): CogcoinResolvedPaths;
+export declare function resolveCogcoinAppRootForTesting(resolution?: CogcoinPathResolution): string;
+export declare function resolveDefaultBitcoindDataDirForTesting(resolution?: CogcoinPathResolution): string;
+export declare function resolveDefaultClientDatabasePathForTesting(resolution?: CogcoinPathResolution): string;
+export declare function resolveDefaultClientDatabaseDirectoryForTesting(resolution?: CogcoinPathResolution): string;

package/dist/app-paths.js

@@ -0,0 +1,121 @@
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, win32 as win32Path } from "node:path";
+function resolveLocalAppDataWindows(env, homeDirectory) {
+    return env.LOCALAPPDATA ?? win32Path.join(homeDirectory, "AppData", "Local");
+}
+function joinForPlatform(platform, ...parts) {
+    return platform === "win32" ? win32Path.join(...parts) : join(...parts);
+}
+function resolveAbsoluteEnvPath(value, fallbackPath) {
+    return value && isAbsolute(value) ? value : fallbackPath;
+}
+function resolveLinuxRoots(env, homeDirectory) {
+    const dataRoot = join(resolveAbsoluteEnvPath(env.XDG_DATA_HOME, join(homeDirectory, ".local", "share")), "cogcoin");
+    const configRoot = join(resolveAbsoluteEnvPath(env.XDG_CONFIG_HOME, join(homeDirectory, ".config")), "cogcoin");
+    const stateRoot = join(resolveAbsoluteEnvPath(env.XDG_STATE_HOME, join(homeDirectory, ".local", "state")), "cogcoin");
+    const runtimeRoot = env.XDG_RUNTIME_DIR && isAbsolute(env.XDG_RUNTIME_DIR)
+        ? join(env.XDG_RUNTIME_DIR, "cogcoin")
+        : join(stateRoot, "runtime");
+    return {
+        dataRoot,
+        configRoot,
+        stateRoot,
+        runtimeRoot,
+        hooksRoot: join(configRoot, "hooks"),
+    };
+}
+export function resolveCogcoinPathsForTesting(resolution = {}) {
+    const platform = resolution.platform ?? process.platform;
+    const env = resolution.env ?? process.env;
+    const homeDirectory = resolution.homeDirectory ?? homedir();
+    let dataRoot;
+    let configRoot;
+    let stateRoot;
+    let runtimeRoot;
+    let hooksRoot;
+    if (platform === "darwin") {
+        dataRoot = join(homeDirectory, "Library", "Application Support", "Cogcoin");
+        configRoot = join(dataRoot, "config");
+        stateRoot = join(dataRoot, "state");
+        runtimeRoot = join(dataRoot, "runtime");
+        hooksRoot = join(dataRoot, "hooks");
+    }
+    else if (platform === "win32") {
+        dataRoot = win32Path.join(resolveLocalAppDataWindows(env, homeDirectory), "Cogcoin");
+        configRoot = win32Path.join(dataRoot, "config");
+        stateRoot = win32Path.join(dataRoot, "state");
+        runtimeRoot = win32Path.join(dataRoot, "runtime");
+        hooksRoot = win32Path.join(dataRoot, "hooks");
+    }
+    else {
+        const linuxRoots = resolveLinuxRoots(env, homeDirectory);
+        dataRoot = linuxRoots.dataRoot;
+        configRoot = linuxRoots.configRoot;
+        stateRoot = linuxRoots.stateRoot;
+        runtimeRoot = linuxRoots.runtimeRoot;
+        hooksRoot = linuxRoots.hooksRoot;
+    }
+    const bitcoinDataDir = joinForPlatform(platform, dataRoot, "bitcoin");
+    const clientDataDir = joinForPlatform(platform, dataRoot, "client");
+    const clientDatabasePath = joinForPlatform(platform, clientDataDir, "client.sqlite");
+    const indexerRoot = joinForPlatform(platform, dataRoot, "indexer");
+    const clientConfigPath = joinForPlatform(platform, configRoot, "client-config.json");
+    const walletStateDirectory = stateRoot;
+    const walletStatePath = joinForPlatform(platform, walletStateDirectory, "wallet-state.enc");
+    const walletStateBackupPath = joinForPlatform(platform, walletStateDirectory, "wallet-state.enc.bak");
+    const walletUnlockSessionPath = joinForPlatform(platform, runtimeRoot, "wallet-unlock-session.enc");
+    const walletControlLockPath = joinForPlatform(platform, runtimeRoot, "wallet-control.lock");
+    const bitcoindLockPath = joinForPlatform(platform, runtimeRoot, "bitcoind.lock");
+    const bitcoindStatusPath = joinForPlatform(platform, runtimeRoot, "bitcoind-status.json");
+    const indexerDaemonLockPath = joinForPlatform(platform, runtimeRoot, "indexer-daemon.lock");
+    const indexerStatusPath = joinForPlatform(platform, indexerRoot, "status.json");
+    const hooksMiningDir = joinForPlatform(platform, hooksRoot, "mining");
+    const hooksMiningEntrypointPath = joinForPlatform(platform, hooksMiningDir, "generate-sentences.js");
+    const hooksMiningPackageJsonPath = joinForPlatform(platform, hooksMiningDir, "package.json");
+    const miningRoot = joinForPlatform(platform, runtimeRoot, "mining");
+    const miningStatusPath = joinForPlatform(platform, miningRoot, "status.json");
+    const miningEventsPath = joinForPlatform(platform, miningRoot, "events.jsonl");
+    const miningControlLockPath = joinForPlatform(platform, runtimeRoot, "mining-control.lock");
+    return {
+        dataRoot,
+        configRoot,
+        stateRoot,
+        runtimeRoot,
+        hooksRoot,
+        bitcoinDataDir,
+        clientDataDir,
+        clientDatabasePath,
+        indexerRoot,
+        clientConfigPath,
+        walletStateDirectory,
+        walletStatePath,
+        walletStateBackupPath,
+        walletUnlockSessionPath,
+        walletControlLockPath,
+        bitcoindLockPath,
+        bitcoindStatusPath,
+        indexerDaemonLockPath,
+        indexerStatusPath,
+        hooksMiningDir,
+        hooksMiningEntrypointPath,
+        hooksMiningPackageJsonPath,
+        miningRoot,
+        miningStatusPath,
+        miningEventsPath,
+        miningControlLockPath,
+    };
+}
+export function resolveCogcoinAppRootForTesting(resolution = {}) {
+    return resolveCogcoinPathsForTesting(resolution).dataRoot;
+}
+export function resolveDefaultBitcoindDataDirForTesting(resolution = {}) {
+    return resolveCogcoinPathsForTesting(resolution).bitcoinDataDir;
+}
+export function resolveDefaultClientDatabasePathForTesting(resolution = {}) {
+    return resolveCogcoinPathsForTesting(resolution).clientDatabasePath;
+}
+export function resolveDefaultClientDatabaseDirectoryForTesting(resolution = {}) {
+    const platform = resolution.platform ?? process.platform;
+    const dbPath = resolveDefaultClientDatabasePathForTesting(resolution);
+    return platform === "win32" ? win32Path.dirname(dbPath) : dirname(dbPath);
+}

package/dist/art/banner.txt

@@ -0,0 +1,13 @@
+ _____                                                                    _____ 
+( ___ )                                                                  ( ___ )
+ |   |~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|   | 
+ |   |                                                                    |   | 
+ |   |         ___     ___     ___     ___     ___     ___    _  _        |   | 
+ |   |        / __|   / _ \   / __|   / __|   / _ \   |_ _|  | \| |       |   | 
+ |   |       | (__   | (_) | | (_ |  | (__   | (_) |   | |   | .` |       |   | 
+ |   |        \___|   \___/   \___|   \___|   \___/   |___|  |_|\_|       |   | 
+ |   |      _|"""""|_|"""""|_|"""""|_|"""""|_|"""""|_|"""""|_|"""""|      |   | 
+ |   |      "`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'      |   | 
+ |   |                                                                    |   | 
+ |___|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|___| 
+(_____)                                                                  (_____)

package/dist/art/scroll.txt

@@ -0,0 +1,13 @@
+ _____                                                                    _____ 
+( ___ )                                                                  ( ___ )
+ |   |~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|   | 
+ |   |                                                                    |   | 
+ |   |                                                                    |   | 
+ |   |                                                                    |   | 
+ |   |                                                                    |   | 
+ |   |                                                                    |   | 
+ |   |                                                                    |   | 
+ |   |                                                                    |   | 
+ |   |                                                                    |   | 
+ |___|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|___| 
+(_____)                                                                  (_____)

package/dist/art/train-car.txt

@@ -0,0 +1,6 @@
+
+
+
+
+_|"""""|
+"`-0-0-'

package/dist/art/train-smoke.txt

@@ -0,0 +1,6 @@
+     o     ___     ___     ___     ___     ___     ___    _  _ 
+    o     / __|   / _ \   / __|   / __|   / _ \   |_ _|  | \| |
+  __     | (__   | (_) | | (_ |  | (__   | (_) |   | |   | .` |
+  ||      \___|   \___/   \___|   \___|   \___/   |___|  |_|\_|
+_|"""""|_|"""""|_|"""""|_|"""""|_|"""""|_|"""""|_|"""""|_|"""""|
+"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'

package/dist/art/train.txt

@@ -0,0 +1,6 @@
+           ___     ___     ___     ___     ___     ___    _  _ 
+          / __|   / _ \   / __|   / __|   / _ \   |_ _|  | \| |
+  __     | (__   | (_) | | (_ |  | (__   | (_) |   | |   | .` |
+  ||      \___|   \___/   \___|   \___|   \___/   |___|  |_|\_|
+_|"""""|_|"""""|_|"""""|_|"""""|_|"""""|_|"""""|_|"""""|_|"""""|
+"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'

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

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

package/dist/bitcoind/bootstrap/chainstate.js

@@ -0,0 +1,13 @@
+function chainStateMatches(chainState, snapshot, baseHeight, tipHashHex) {
+    if (tipHashHex !== null && chainState.snapshot_blockhash === tipHashHex) {
+        return true;
+    }
+    if (baseHeight !== null && chainState.blocks === baseHeight && chainState.validated === false) {
+        return true;
+    }
+    return chainState.blocks === snapshot.height && chainState.validated === false;
+}
+export async function isSnapshotAlreadyLoaded(rpc, snapshot, state) {
+    const chainStates = await rpc.getChainStates();
+    return chainStates.chainstates.some((chainState) => chainStateMatches(chainState, snapshot, state.baseHeight, state.tipHashHex));
+}

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

@@ -0,0 +1,7 @@
+import type { SnapshotMetadata } from "../types.js";
+export declare const SNAPSHOT_METADATA_VERSION = 1;
+export declare const DOWNLOAD_RETRY_BASE_MS = 1000;
+export declare const DOWNLOAD_RETRY_MAX_MS = 30000;
+export declare const HEADER_POLL_MS = 2000;
+export declare const HEADER_NO_PEER_TIMEOUT_MS = 60000;
+export declare const DEFAULT_SNAPSHOT_METADATA: SnapshotMetadata;

package/dist/bitcoind/bootstrap/constants.js

@@ -0,0 +1,12 @@
+export const SNAPSHOT_METADATA_VERSION = 1;
+export const DOWNLOAD_RETRY_BASE_MS = 1_000;
+export const DOWNLOAD_RETRY_MAX_MS = 30_000;
+export const HEADER_POLL_MS = 2_000;
+export const HEADER_NO_PEER_TIMEOUT_MS = 60_000;
+export const DEFAULT_SNAPSHOT_METADATA = {
+    url: "https://snapshots.cogcoin.org/utxo-910000.dat",
+    filename: "utxo-910000.dat",
+    height: 910_000,
+    sha256: "6ac0208110d6d6c0783c50ea825aae32f5229cf1dcb63ac986543e95aa0306bf",
+    sizeBytes: 9_637_809_744,
+};

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

@@ -0,0 +1,29 @@
+import type { ClientTip } from "../../types.js";
+import { ManagedProgressController } from "../progress.js";
+import { BitcoinRpcClient } from "../rpc.js";
+import type { BootstrapPhase, SnapshotMetadata } from "../types.js";
+export declare class AssumeUtxoBootstrapController {
+    #private;
+    constructor(options: {
+        rpc: BitcoinRpcClient;
+        dataDir: string;
+        progress: ManagedProgressController;
+        snapshot?: SnapshotMetadata;
+        fetchImpl?: typeof fetch;
+    });
+    get quoteStatePath(): string;
+    get snapshot(): SnapshotMetadata;
+    ensureReady(indexedTip: ClientTip | null, expectedChain: "main" | "regtest"): Promise<void>;
+    getStateForTesting(): Promise<{
+        metadataVersion: number;
+        snapshot: SnapshotMetadata;
+        phase: BootstrapPhase;
+        downloadedBytes: number;
+        validated: boolean;
+        loadTxOutSetComplete: boolean;
+        baseHeight: number | null;
+        tipHashHex: string | null;
+        lastError: string | null;
+        updatedAt: number;
+    }>;
+}

package/dist/bitcoind/bootstrap/controller.js

@@ -0,0 +1,101 @@
+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";
+async function loadSnapshotIntoNode(rpc, snapshotPath) {
+    return rpc.loadTxOutSet(snapshotPath);
+}
+export class AssumeUtxoBootstrapController {
+    #rpc;
+    #paths;
+    #progress;
+    #snapshot;
+    #fetchImpl;
+    #statePromise = null;
+    constructor(options) {
+        this.#rpc = options.rpc;
+        this.#progress = options.progress;
+        this.#snapshot = options.snapshot ?? DEFAULT_SNAPSHOT_METADATA;
+        this.#paths = resolveBootstrapPaths(options.dataDir, this.#snapshot);
+        this.#fetchImpl = options.fetchImpl;
+    }
+    get quoteStatePath() {
+        return this.#paths.quoteStatePath;
+    }
+    get snapshot() {
+        return this.#snapshot;
+    }
+    async ensureReady(indexedTip, expectedChain) {
+        if (expectedChain !== "main") {
+            await this.#progress.setPhase("paused", {
+                ...createBootstrapProgressForTesting("paused", this.#snapshot),
+                message: "Managed regtest sync does not use assumeutxo bootstrap.",
+            });
+            return;
+        }
+        if (indexedTip !== null) {
+            await this.#progress.setPhase("follow_tip", {
+                blocks: indexedTip.height,
+                targetHeight: indexedTip.height,
+                message: "Resuming from the persisted Cogcoin indexed tip.",
+            });
+            return;
+        }
+        const state = await this.#loadState();
+        if (state.loadTxOutSetComplete && await isSnapshotAlreadyLoaded(this.#rpc, this.#snapshot, 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,
+            });
+            return;
+        }
+        await downloadSnapshotFileForTesting({
+            fetchImpl: this.#fetchImpl,
+            metadata: this.#snapshot,
+            paths: this.#paths,
+            progress: this.#progress,
+            state,
+        });
+        if (!await isSnapshotAlreadyLoaded(this.#rpc, this.#snapshot, state)) {
+            await waitForHeaders(this.#rpc, this.#snapshot, this.#progress);
+            await this.#progress.setPhase("load_snapshot", {
+                downloadedBytes: this.#snapshot.sizeBytes,
+                totalBytes: this.#snapshot.sizeBytes,
+                percent: 100,
+                message: "Loading the UTXO snapshot into bitcoind.",
+            });
+            const loadResult = await loadSnapshotIntoNode(this.#rpc, this.#paths.snapshotPath);
+            state.loadTxOutSetComplete = true;
+            state.baseHeight = loadResult.base_height;
+            state.tipHashHex = loadResult.tip_hash;
+            state.phase = "bitcoin_sync";
+            state.lastError = null;
+            await saveBootstrapState(this.#paths, state);
+        }
+        const info = await this.#rpc.getBlockchainInfo();
+        await this.#progress.setPhase("bitcoin_sync", {
+            blocks: info.blocks,
+            headers: info.headers,
+            targetHeight: info.headers,
+            baseHeight: state.baseHeight,
+            tipHashHex: state.tipHashHex,
+            message: "Bitcoin Core is syncing blocks after assumeutxo bootstrap.",
+            lastError: state.lastError,
+        });
+    }
+    async getStateForTesting() {
+        return { ...(await this.#loadState()) };
+    }
+    async #loadState() {
+        this.#statePromise ??= loadBootstrapState(this.#paths, this.#snapshot);
+        return this.#statePromise;
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { DownloadSnapshotOptions } from "./types.js";
+export declare function downloadSnapshotFileForTesting(options: DownloadSnapshotOptions): Promise<void>;