@cogcoin/client 0.5.15 → 1.0.1

package/README.md

@@ -1,39 +1,95 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@0.5.15` 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@1.0.0` is the reference 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
+npm install -g @cogcoin/client
+cogcoin init
+cogcoin address  # Send 0.0015 BTC to address
+cogcoin register <domainname> # 6+ character domain for 0.001 BTC
+cogcoin anchor <domainname> # You can leave a founding message permanently on Bitcoin!
+cogcoin mine setup
+cogcoin mine # Use remaining ~0.0005 BTC for mining tx, ~1000 sats per entry (0.00001 BTC)
+```
+
+## Preview
+
+```bash
+
+     ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
+   ▄▀                  ▀▄
+   █  ▄▀▀▀▀▀▀▀▀▀▀▀▀▀▀▄  █    Welcome to...
+   █  █              █  █
+   █  █   █   █  █   █  █     █████  █████   █████   █████  █████  ██ ███    ██
+   █  █       █      █  █    ██     ██   ██ ██      ██     ██   ██ ██ ████   ██
+   █  █      ▄█      █  █    ██     ██   ██ ██  ███ ██     ██   ██ ██ ██ ██  ██
+   █  █    ▄    ▄    █  █    ██     ██   ██ ██   ██ ██     ██   ██ ██ ██  ██ ██
+   █  █     ▀▀▀▀     █  █     █████  █████   █████   █████  █████  ██ ██   ████
+   █  ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀  █
+   █                    █        ┏┳┓╻┏┓╻┏━╸   ╻ ╻╻╺┳╸╻ ╻   ╻ ╻┏━┓┏━┓╺┳┓┏━┓    
+   █                    █        ┃┃┃┃┃┗┫┣╸    ┃╻┃┃ ┃ ┣━┫   ┃╻┃┃ ┃┣┳┛ ┃┃┗━┓
+   █   ▄▄      ▄▄▄▄▄▄   █        ╹ ╹╹╹ ╹┗━╸   ┗┻┛╹ ╹ ╹ ╹   ┗┻┛┗━┛╹┗╸╺┻┛┗━┛
+   █                    █
+   ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀            We are so happy to have you here!        
+    █▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄█
+
+
 ```
 
-Then, from your project root, run:
+```bash
+                            ⛭ Behold, your Cogcoin wallet. ⛭                    
+▐▀▀▀▀▀▀▀▀▚  ╔──────────────────────────────────────────────────────────────────╗
+▛▞▀▀▀▀▀▀▀▀▚ │                                                                  │
+▌▝▀▀▀▀▀▀▀▀▀▌│ Funding address: bc1qsamplewallet0000000000000000000000000      │
+▌   ▗▙▙    ▌│                                                                  │
+▌   ▐  ▌   ▌│ Bitcoin Balance: 0.00150000 BTC                                  │
+▌   ▐▀▀▚   ▌│ Cogcoin Balance: 12.50000000 COG                                 │
+▌   ▐▄▄▞   ▌│                                                                  │
+▌    ▘▘    ▌│ mempool.space/address/bc1qsamplewallet0000000000000000000000000 |
+▝▀▀▀▀▀▀▀▀▀▀▘╚──────────────────────────────────────────────────────────────────╝
+
+Anchored Domains
+⌂ cogdemo
+
+Unanchored Domains
+--- No unanchored domains ---
+```
 
 ```bash
-node node_modules/@cogcoin/genesis/verify.mjs
-npx cogcoin init
-npx cogcoin sync
+ _____                                                                    _____ 
+( ___ ) 12.500 COG            ⛭  C O G C O I N  ⛭             150000 SAT ( ___ )
+ |   |~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|   | 
+ |   |                                                                    |   | 
+ |   |                                                                    |   | 
+ |   |                              945516  945515  945514  945513  945512|   | 
+ |   |_|"""""|                     _|"""""|_|"""""|_|"""""|_|"""""|_|"""""|   | 
+ |   |"`-0-0-'                     "`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-|   | 
+ |   | ~10 min                                                            |   | 
+ |   |                                                                    |   | 
+ |   |                                                                    |   | 
+ |___|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|___| 
+(_____)                       Waiting for indexer                        (_____)
+
+[░░░░░░░░░░░░░░░░████] Mining is waiting for Bitcoin Core and the indexer to align.
+Required words: OWNER, OLYMPIC, ERODE, DESK, DIFFER
+@cogdemo: By the desk, the owner observed that Olympic lettering could erode over time, though experts differ.
 ```
 
-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.
-Provider-backed local wallets unlock on demand by default; `cogcoin wallet lock` suppresses that behavior until `cogcoin unlock` is run again.
-Passphrase-wrapped wallet-state flows still require explicit passphrase-based access.
+## 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)
 
 ## Dependency Surface
 
@@ -41,7 +97,7 @@ The published package depends on:
 
 - `@cogcoin/bitcoin@30.2.0`
 - `@cogcoin/genesis@1.0.0`
-- `@cogcoin/indexer@1.0.0`
+- `@cogcoin/indexer@1.0.1`
 - `@cogcoin/scoring@1.0.0`
 - `@scure/base@^2.0.0`
 - `@scure/bip32@^2.0.1`
@@ -74,21 +130,20 @@ Managed node subpath:
 
 The installed `cogcoin` command covers the first-party local wallet and node workflow:
 
-- wallet lifecycle commands such as `init`, `restore`, `unlock`, `lock`, `repair`, `export`, and `import`
+- wallet lifecycle commands such as `init`, `restore`, `wallet delete`, `wallet show-mnemonic`, and `repair`
 - sync and service commands such as `status`, `sync`, `follow`, `bitcoin start`, `bitcoin stop`, `bitcoin status`, `indexer start`, `indexer stop`, and `indexer status`
 - 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`
+- mining commands such as `mine`, `mine start`, `mine stop`, `mine status`, `mine log`, and `mine setup`
 
 The CLI also supports stable `--output json` and `--output preview-json` envelopes on the commands that advertise machine-readable output.
 Interactive text invocations periodically check the npm registry for newer `@cogcoin/client` releases and print `npm install -g @cogcoin/client` when a newer version is available.
 Set `COGCOIN_DISABLE_UPDATE_CHECK=1` to disable the CLI update notice entirely.
 Ordinary `sync`, `follow`, and wallet-aware read/status flows detach from the managed Bitcoin and indexer services on exit instead of stopping them.
 Use the explicit `bitcoin ...` and `indexer ...` commands when you want direct service inspection or start/stop control.
-For provider-backed local wallets, normal reads, mutations, export, and mining setup flows auto-materialize a local unlock session when the wallet is not explicitly locked.
+For provider-backed local wallets, normal reads, mutations, and mining setup flows load local wallet state on demand whenever the local secret provider is available.
 `cogcoin restore` and `cogcoin wallet restore` rebuild a fresh local wallet from a 24-word English BIP39 mnemonic and recreate the managed Core wallet replica.
 Run `cogcoin sync` afterward to bootstrap the managed Bitcoin/indexer state.
-`cogcoin wallet import <path>` remains the richer encrypted-archive restore path that preserves more local continuity metadata than mnemonic-only restore.
 
 ## SQLite Store
 

package/dist/app-paths.d.ts

@@ -8,7 +8,6 @@ export interface CogcoinResolvedPaths {
     configRoot: string;
     stateRoot: string;
     runtimeRoot: string;
-    hooksRoot: string;
     bitcoinDataDir: string;
     clientDataDir: string;
     clientDatabasePath: string;
@@ -19,21 +18,21 @@ export interface CogcoinResolvedPaths {
     walletStateBackupPath: string;
     walletInitPendingPath: string;
     walletInitPendingBackupPath: string;
-    walletUnlockSessionPath: string;
-    walletExplicitLockPath: 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 resolveLegacyHooksRootPath(options: {
+    dataRoot: string;
+    clientConfigPath: string;
+    platform?: NodeJS.Platform;
+}): string;
 export declare function resolveCogcoinPathsForTesting(resolution?: CogcoinPathResolution): CogcoinResolvedPaths;
 export declare function resolveCogcoinAppRootForTesting(resolution?: CogcoinPathResolution): string;
 export declare function resolveDefaultBitcoindDataDirForTesting(resolution?: CogcoinPathResolution): string;

package/dist/app-paths.js

@@ -21,9 +21,16 @@ function resolveLinuxRoots(env, homeDirectory) {
         configRoot,
         stateRoot,
         runtimeRoot,
-        hooksRoot: join(configRoot, "hooks"),
     };
 }
+export function resolveLegacyHooksRootPath(options) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "darwin" || platform === "win32") {
+        return joinForPlatform(platform, options.dataRoot, "hooks");
+    }
+    const configDirectory = dirname(options.clientConfigPath);
+    return joinForPlatform(platform, configDirectory, "hooks");
+}
 export function resolveCogcoinPathsForTesting(resolution = {}) {
     const platform = resolution.platform ?? process.platform;
     const env = resolution.env ?? process.env;
@@ -32,20 +39,17 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
     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);
@@ -53,7 +57,6 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
         configRoot = linuxRoots.configRoot;
         stateRoot = linuxRoots.stateRoot;
         runtimeRoot = linuxRoots.runtimeRoot;
-        hooksRoot = linuxRoots.hooksRoot;
     }
     const bitcoinDataDir = joinForPlatform(platform, dataRoot, "bitcoin");
     const clientDataDir = joinForPlatform(platform, dataRoot, "client");
@@ -65,16 +68,11 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
     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");
     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");
@@ -84,7 +82,6 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
         configRoot,
         stateRoot,
         runtimeRoot,
-        hooksRoot,
         bitcoinDataDir,
         clientDataDir,
         clientDatabasePath,
@@ -95,16 +92,11 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
         walletStateBackupPath,
         walletInitPendingPath,
         walletInitPendingBackupPath,
-        walletUnlockSessionPath,
-        walletExplicitLockPath,
         walletControlLockPath,
         bitcoindLockPath,
         bitcoindStatusPath,
         indexerDaemonLockPath,
         indexerStatusPath,
-        hooksMiningDir,
-        hooksMiningEntrypointPath,
-        hooksMiningPackageJsonPath,
         miningRoot,
         miningStatusPath,
         miningEventsPath,

package/dist/art/balance.txt

@@ -0,0 +1,10 @@
+                            ⛭ Behold, your Cogcoin wallet. ⛭                    
+▐▀▀▀▀▀▀▀▀▚  ╔──────────────────────────────────────────────────────────────────╗
+▛▞▀▀▀▀▀▀▀▀▚ │                                                                  │
+▌▝▀▀▀▀▀▀▀▀▀▌│ Funding address:                                                 │
+▌   ▗▙▙    ▌│                                                                  │
+▌   ▐  ▌   ▌│ Bitcoin Balance:                                                 │
+▌   ▐▀▀▚   ▌│ Cogcoin Balance:                                                 │
+▌   ▐▄▄▞   ▌│                                                                  │
+▌    ▘▘    ▌│ mempool.space/address/                                           |
+▝▀▀▀▀▀▀▀▀▀▀▘╚──────────────────────────────────────────────────────────────────╝

package/dist/art/welcome.txt

@@ -0,0 +1,16 @@
+     ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
+   ▄▀                  ▀▄
+   █  ▄▀▀▀▀▀▀▀▀▀▀▀▀▀▀▄  █    Welcome to...
+   █  █              █  █
+   █  █   █   █  █   █  █     █████  █████   █████   █████  █████  ██ ███    ██
+   █  █       █      █  █    ██     ██   ██ ██      ██     ██   ██ ██ ████   ██
+   █  █      ▄█      █  █    ██     ██   ██ ██  ███ ██     ██   ██ ██ ██ ██  ██
+   █  █    ▄    ▄    █  █    ██     ██   ██ ██   ██ ██     ██   ██ ██ ██  ██ ██
+   █  █     ▀▀▀▀     █  █     █████  █████   █████   █████  █████  ██ ██   ████
+   █  ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀  █
+   █                    █        ┏┳┓╻┏┓╻┏━╸   ╻ ╻╻╺┳╸╻ ╻   ╻ ╻┏━┓┏━┓╺┳┓┏━┓    
+   █                    █        ┃┃┃┃┃┗┫┣╸    ┃╻┃┃ ┃ ┣━┫   ┃╻┃┃ ┃┣┳┛ ┃┃┗━┓
+   █   ▄▄      ▄▄▄▄▄▄   █        ╹ ╹╹╹ ╹┗━╸   ┗┻┛╹ ╹ ╹ ╹   ┗┻┛┗━┛╹┗╸╺┻┛┗━┛
+   █                    █
+   ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀            We are so happy to have you here!        
+    █▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄█

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

@@ -36,5 +36,6 @@ export declare class AssumeUtxoBootstrapController {
         lastError: string | null;
         updatedAt: number;
     }>;
+    cleanupObsoleteSnapshotFilesIfNeeded(): Promise<boolean>;
 }
 export {};

package/dist/bitcoind/bootstrap/controller.js

@@ -5,6 +5,7 @@ import { DEFAULT_SNAPSHOT_METADATA } from "./constants.js";
 import { downloadSnapshotFileForTesting } from "./download.js";
 import { waitForHeaders } from "./headers.js";
 import { resolveBootstrapPaths } from "./paths.js";
+import { resetSnapshotFiles } from "./snapshot-file.js";
 import { loadBootstrapStateRecord, saveBootstrapState } from "./state.js";
 import { findLoadedSnapshotChainState, isSnapshotAlreadyLoaded } from "./chainstate.js";
 import { describeManagedRpcRetryError, isRetryableManagedRpcError, } from "../retryable-rpc.js";
@@ -54,7 +55,8 @@ export class AssumeUtxoBootstrapController {
             return;
         }
         const { state, snapshotIdentity } = await this.#loadStateRecord();
-        if (state.loadTxOutSetComplete && await isSnapshotAlreadyLoaded(this.#rpc, this.#snapshot, state)) {
+        const lifecycle = await this.#probeSnapshotLifecycle(state);
+        if (lifecycle.lifecycle === "snapshot-active") {
             if (state.lastError !== null) {
                 state.lastError = null;
                 await saveBootstrapState(this.#paths, state);
@@ -69,6 +71,25 @@ export class AssumeUtxoBootstrapController {
             });
             return;
         }
+        if (lifecycle.lifecycle === "snapshot-obsolete") {
+            await this.#deleteSnapshotArtifactsBestEffort();
+            if (state.lastError !== null || state.phase !== "bitcoin_sync") {
+                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: null,
+            });
+            return;
+        }
         await downloadSnapshotFileForTesting({
             fetchImpl: this.#fetchImpl,
             manifest: this.#manifest,
@@ -137,6 +158,20 @@ export class AssumeUtxoBootstrapController {
     async getStateForTesting() {
         return { ...(await this.#loadState()) };
     }
+    async cleanupObsoleteSnapshotFilesIfNeeded() {
+        try {
+            const { state } = await this.#loadStateRecord();
+            const lifecycle = await this.#probeSnapshotLifecycle(state);
+            if (lifecycle.lifecycle !== "snapshot-obsolete") {
+                return false;
+            }
+            await this.#deleteSnapshotArtifactsBestEffort();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     async #loadState() {
         return (await this.#loadStateRecord()).state;
     }
@@ -144,4 +179,21 @@ export class AssumeUtxoBootstrapController {
         this.#stateRecordPromise ??= loadBootstrapStateRecord(this.#paths, this.#snapshot);
         return this.#stateRecordPromise;
     }
+    async #probeSnapshotLifecycle(state) {
+        if (!state.loadTxOutSetComplete) {
+            return {
+                state,
+                lifecycle: "bootstrap-pending",
+            };
+        }
+        return {
+            state,
+            lifecycle: await isSnapshotAlreadyLoaded(this.#rpc, this.#snapshot, state)
+                ? "snapshot-active"
+                : "snapshot-obsolete",
+        };
+    }
+    async #deleteSnapshotArtifactsBestEffort() {
+        await resetSnapshotFiles(this.#paths).catch(() => undefined);
+    }
 }

package/dist/bitcoind/client/follow-block-times.d.ts

@@ -1,5 +1,6 @@
 import type { Client, ClientStoreAdapter } from "../../types.js";
 import type { BitcoinRpcClient } from "../rpc.js";
+export declare const FOLLOW_VISIBLE_PRIOR_BLOCKS = 4;
 export declare function loadVisibleFollowBlockTimes(options: {
     tip: Awaited<ReturnType<Client["getTip"]>>;
     startHeight: number;

package/dist/bitcoind/client/follow-block-times.js

@@ -1,4 +1,4 @@
-const FOLLOW_VISIBLE_PRIOR_BLOCKS = 4;
+export const FOLLOW_VISIBLE_PRIOR_BLOCKS = 4;
 export async function loadVisibleFollowBlockTimes(options) {
     const { tip, startHeight, store, rpc } = options;
     if (tip === null) {

package/dist/bitcoind/client/internal-types.d.ts

@@ -1,4 +1,4 @@
-import type { Client, ClientStoreAdapter } from "../../types.js";
+import type { Client, ClientCheckpoint, ClientStoreAdapter, ClientTip } from "../../types.js";
 import type { AssumeUtxoBootstrapController } from "../bootstrap.js";
 import type { ManagedProgressController } from "../progress.js";
 import type { BitcoinRpcClient } from "../rpc.js";
@@ -8,13 +8,17 @@ export interface SyncPassResult {
     rewoundBlocks: number;
     commonAncestorHeight: number | null;
 }
+export interface SyncRecoveryClient extends Client {
+    restoreCheckpoint(checkpoint: ClientCheckpoint): Promise<ClientTip>;
+    resetToInitialState(): Promise<null>;
+}
 export interface BlockRateTracker {
     lastHeight: number | null;
     lastUpdatedAt: number | null;
     blocksPerSecond: number | null;
 }
 export interface SyncEngineDependencies {
-    client: Client;
+    client: SyncRecoveryClient;
     store: ClientStoreAdapter;
     node: ManagedBitcoindNodeHandle;
     rpc: BitcoinRpcClient;
@@ -26,7 +30,7 @@ export interface SyncEngineDependencies {
     cogcoinRateTracker: BlockRateTracker;
     abortSignal?: AbortSignal;
     isFollowing(): boolean;
-    loadVisibleFollowBlockTimes(tip: Awaited<ReturnType<Client["getTip"]>>): Promise<Record<number, number>>;
+    loadVisibleFollowBlockTimes(tip: Awaited<ReturnType<SyncRecoveryClient["getTip"]>>): Promise<Record<number, number>>;
 }
 export interface FollowLoopSubscriber extends AsyncIterable<unknown> {
     close(): void;

package/dist/bitcoind/client/managed-client.d.ts

@@ -1,13 +1,14 @@
 import type { BitcoinBlock } from "@cogcoin/indexer/types";
-import type { Client, ClientStoreAdapter } from "../../types.js";
+import type { ClientStoreAdapter } from "../../types.js";
 import { AssumeUtxoBootstrapController } from "../bootstrap.js";
 import type { IndexerDaemonClient } from "../indexer-daemon.js";
 import type { ManagedProgressController } from "../progress.js";
 import type { BitcoinRpcClient } from "../rpc.js";
 import type { ManagedBitcoindClient, ManagedBitcoindNodeHandle, ManagedBitcoindStatus, SyncResult } from "../types.js";
+import { type SyncRecoveryClient } from "./internal-types.js";
 export declare class DefaultManagedBitcoindClient implements ManagedBitcoindClient {
     #private;
-    constructor(client: Client, store: ClientStoreAdapter, node: ManagedBitcoindNodeHandle, rpc: BitcoinRpcClient, progress: ManagedProgressController, bootstrap: AssumeUtxoBootstrapController, indexerDaemon: IndexerDaemonClient | null, reattachIndexerDaemon: (() => Promise<IndexerDaemonClient | null>) | null, startHeight: number, syncDebounceMs: number, dataDir: string, walletRootId: string, startupTimeoutMs: number | undefined, shutdownTimeoutMs: number | undefined, fetchImpl: typeof fetch | undefined);
+    constructor(client: SyncRecoveryClient, store: ClientStoreAdapter, node: ManagedBitcoindNodeHandle, rpc: BitcoinRpcClient, progress: ManagedProgressController, bootstrap: AssumeUtxoBootstrapController, indexerDaemon: IndexerDaemonClient | null, reattachIndexerDaemon: (() => Promise<IndexerDaemonClient | null>) | null, startHeight: number, syncDebounceMs: number, dataDir: string, walletRootId: string, startupTimeoutMs: number | undefined, shutdownTimeoutMs: number | undefined, fetchImpl: typeof fetch | undefined);
     getTip(): Promise<import("../../types.js").ClientTip | null>;
     getState(): Promise<import("@cogcoin/indexer/types").IndexerState>;
     applyBlock(block: BitcoinBlock): Promise<import("../../types.js").ApplyBlockResult>;
@@ -17,4 +18,5 @@ export declare class DefaultManagedBitcoindClient implements ManagedBitcoindClie
     getNodeStatus(): Promise<ManagedBitcoindStatus>;
     close(): Promise<void>;
     playSyncCompletionScene(): Promise<void>;
+    detachToBackgroundFollow(): Promise<void>;
 }

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

@@ -45,6 +45,7 @@ export class DefaultManagedBitcoindClient {
     #syncPromise = Promise.resolve(createInitialSyncResult());
     #debounceTimer = null;
     #syncAbortControllers = new Set();
+    #backgroundFollowResumed = false;
     constructor(client, store, node, rpc, progress, bootstrap, indexerDaemon, reattachIndexerDaemon, startHeight, syncDebounceMs, dataDir, walletRootId, startupTimeoutMs, shutdownTimeoutMs, fetchImpl) {
         this.#client = client;
         this.#store = store;
@@ -198,11 +199,18 @@ export class DefaultManagedBitcoindClient {
         await this.#client.close();
         await this.#resumeIndexerBackgroundFollow();
         await this.#indexerDaemon?.close();
+        this.#indexerDaemon = null;
     }
     async playSyncCompletionScene() {
         this.#assertOpen();
         await this.#progress.playCompletionScene();
     }
+    async detachToBackgroundFollow() {
+        this.#assertOpen();
+        await this.#resumeIndexerBackgroundFollow();
+        await this.#indexerDaemon?.close();
+        this.#indexerDaemon = null;
+    }
     async #setGetblockStatusMessage(currentHeight, message, targetHeight = currentHeight) {
         const safeTargetHeight = Math.max(currentHeight, targetHeight);
         await this.#progress.setPhase("bitcoin_sync", {
@@ -397,12 +405,17 @@ export class DefaultManagedBitcoindClient {
         }
     }
     async #resumeIndexerBackgroundFollow() {
+        if (this.#backgroundFollowResumed) {
+            return;
+        }
         if (this.#indexerDaemon === null && this.#reattachIndexerDaemon === null) {
+            this.#backgroundFollowResumed = true;
             return;
         }
         if (this.#indexerDaemon !== null) {
             try {
                 await this.#indexerDaemon.resumeBackgroundFollow();
+                this.#backgroundFollowResumed = true;
                 return;
             }
             catch (error) {
@@ -418,5 +431,6 @@ export class DefaultManagedBitcoindClient {
         const replacementDaemon = await reattachIndexerDaemon();
         this.#indexerDaemon = replacementDaemon;
         await replacementDaemon?.resumeBackgroundFollow();
+        this.#backgroundFollowResumed = true;
     }
 }