@cogcoin/client 0.5.10 → 0.5.12

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@0.5.10` 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.12` 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.
 
@@ -81,6 +81,8 @@ The installed `cogcoin` command covers the first-party local wallet and node wor
 - 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.
+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.

package/dist/app-paths.d.ts

@@ -39,3 +39,4 @@ export declare function resolveCogcoinAppRootForTesting(resolution?: CogcoinPath
 export declare function resolveDefaultBitcoindDataDirForTesting(resolution?: CogcoinPathResolution): string;
 export declare function resolveDefaultClientDatabasePathForTesting(resolution?: CogcoinPathResolution): string;
 export declare function resolveDefaultClientDatabaseDirectoryForTesting(resolution?: CogcoinPathResolution): string;
+export declare function resolveDefaultUpdateCheckStatePathForTesting(resolution?: CogcoinPathResolution): string;

package/dist/app-paths.js

@@ -125,3 +125,6 @@ export function resolveDefaultClientDatabaseDirectoryForTesting(resolution = {})
     const dbPath = resolveDefaultClientDatabasePathForTesting(resolution);
     return platform === "win32" ? win32Path.dirname(dbPath) : dirname(dbPath);
 }
+export function resolveDefaultUpdateCheckStatePathForTesting(resolution = {}) {
+    return joinForPlatform(resolution.platform ?? process.platform, resolveCogcoinPathsForTesting(resolution).stateRoot, "update-check.json");
+}

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

@@ -3,6 +3,7 @@ import { ManagedProgressController } from "../progress.js";
 import { BitcoinRpcClient } from "../rpc.js";
 import { type ManagedRpcRetryState } from "../retryable-rpc.js";
 import type { BootstrapPhase, SnapshotMetadata, SnapshotChunkManifest } from "../types.js";
+type ResumeDisplayMode = "sync" | "follow";
 export declare class AssumeUtxoBootstrapController {
     #private;
     constructor(options: {
@@ -18,6 +19,7 @@ export declare class AssumeUtxoBootstrapController {
     ensureReady(indexedTip: ClientTip | null, expectedChain: "main" | "regtest", options?: {
         signal?: AbortSignal;
         retryState?: ManagedRpcRetryState;
+        resumeDisplayMode?: ResumeDisplayMode;
     }): Promise<void>;
     getStateForTesting(): Promise<{
         metadataVersion: number;
@@ -35,3 +37,4 @@ export declare class AssumeUtxoBootstrapController {
         updatedAt: number;
     }>;
 }
+export {};

package/dist/bitcoind/bootstrap/controller.js

@@ -44,11 +44,13 @@ export class AssumeUtxoBootstrapController {
             return;
         }
         if (indexedTip !== null) {
-            await this.#progress.setPhase("follow_tip", {
-                blocks: indexedTip.height,
-                targetHeight: indexedTip.height,
-                message: "Resuming from the persisted Cogcoin indexed tip.",
-            });
+            if ((options.resumeDisplayMode ?? "sync") === "follow") {
+                await this.#progress.setPhase("follow_tip", {
+                    blocks: indexedTip.height,
+                    targetHeight: indexedTip.height,
+                    message: "Resuming from the persisted Cogcoin indexed tip.",
+                });
+            }
             return;
         }
         const { state, snapshotIdentity } = await this.#loadStateRecord();

package/dist/bitcoind/client/factory.d.ts

@@ -1,3 +1,11 @@
+import { stopIndexerDaemonService, type IndexerDaemonClient } from "../indexer-daemon.js";
 import type { InternalManagedBitcoindOptions, ManagedBitcoindClient } from "../types.js";
+export declare function pauseIndexerDaemonForForegroundClientForTesting(options: {
+    daemon: IndexerDaemonClient;
+    dataDir: string;
+    walletRootId: string;
+    shutdownTimeoutMs?: number;
+    stopDaemon?: typeof stopIndexerDaemonService;
+}): Promise<IndexerDaemonClient | null>;
 export declare function openManagedBitcoindClient(options: Omit<InternalManagedBitcoindOptions, "chain" | "startHeight">): Promise<ManagedBitcoindClient>;
 export declare function openManagedBitcoindClientInternal(options: InternalManagedBitcoindOptions): Promise<ManagedBitcoindClient>;

package/dist/bitcoind/client/factory.js

@@ -2,13 +2,46 @@ import { loadBundledGenesisParameters } from "@cogcoin/indexer";
 import { resolveDefaultBitcoindDataDirForTesting } from "../../app-paths.js";
 import { openClient } from "../../client.js";
 import { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, resolveBootstrapPathsForTesting, } from "../bootstrap.js";
-import { attachOrStartIndexerDaemon } from "../indexer-daemon.js";
+import { attachOrStartIndexerDaemon, stopIndexerDaemonService, } from "../indexer-daemon.js";
 import { createRpcClient } from "../node.js";
 import { assertCogcoinProcessingStartHeight, resolveCogcoinProcessingStartHeight, } from "../processing-start-height.js";
 import { ManagedProgressController } from "../progress.js";
 import { attachOrStartManagedBitcoindService, } from "../service.js";
 import { DefaultManagedBitcoindClient } from "./managed-client.js";
 const DEFAULT_SYNC_DEBOUNCE_MS = 250;
+function isRecoverableIndexerDaemonPauseError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    if (error.message === "indexer_daemon_request_timeout"
+        || error.message === "indexer_daemon_connection_closed"
+        || error.message === "indexer_daemon_protocol_error") {
+        return true;
+    }
+    if ("code" in error) {
+        const code = error.code;
+        return code === "ENOENT" || code === "ECONNREFUSED" || code === "ECONNRESET";
+    }
+    return false;
+}
+export async function pauseIndexerDaemonForForegroundClientForTesting(options) {
+    try {
+        await options.daemon.pauseBackgroundFollow();
+        return options.daemon;
+    }
+    catch (error) {
+        await options.daemon.close().catch(() => undefined);
+        if (!isRecoverableIndexerDaemonPauseError(error)) {
+            throw error;
+        }
+        await (options.stopDaemon ?? stopIndexerDaemonService)({
+            dataDir: options.dataDir,
+            walletRootId: options.walletRootId,
+            shutdownTimeoutMs: options.shutdownTimeoutMs,
+        });
+        return null;
+    }
+}
 async function createManagedBitcoindClient(options) {
     const genesisParameters = options.genesisParameters ?? await loadBundledGenesisParameters();
     assertCogcoinProcessingStartHeight({
@@ -51,14 +84,18 @@ async function createManagedBitcoindClient(options) {
             snapshotInterval: options.snapshotInterval,
         });
         const indexerDaemon = options.databasePath
-            ? await attachOrStartIndexerDaemon({
+            ? await pauseIndexerDaemonForForegroundClientForTesting({
+                daemon: await attachOrStartIndexerDaemon({
+                    dataDir,
+                    databasePath: options.databasePath,
+                    walletRootId: options.walletRootId,
+                    startupTimeoutMs: options.startupTimeoutMs,
+                }),
                 dataDir,
-                databasePath: options.databasePath,
-                walletRootId: options.walletRootId,
-                startupTimeoutMs: options.startupTimeoutMs,
+                walletRootId,
+                shutdownTimeoutMs: options.shutdownTimeoutMs,
             })
             : null;
-        await indexerDaemon?.pauseBackgroundFollow();
         // The persistent service may already exist from a non-processing attach path
         // that used startHeight 0. Cogcoin replay still begins at the requested
         // processing boundary for this managed client.

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

@@ -292,7 +292,10 @@ export class DefaultManagedBitcoindClient {
     async #ensureBootstrapReady(signal) {
         await this.#node.validate();
         const indexedTipBeforeBootstrap = await this.#client.getTip();
-        await this.#bootstrap.ensureReady(indexedTipBeforeBootstrap, this.#node.expectedChain, { signal });
+        await this.#bootstrap.ensureReady(indexedTipBeforeBootstrap, this.#node.expectedChain, {
+            signal,
+            resumeDisplayMode: this.#following ? "follow" : "sync",
+        });
     }
     async #restartManagedNodeWithRange(readyRange, abortSignal) {
         if (abortSignal.aborted) {
@@ -372,19 +375,25 @@ export class DefaultManagedBitcoindClient {
         }
     }
     async #resumeIndexerBackgroundFollow() {
-        if (this.#indexerDaemon === null) {
+        if (this.#indexerDaemon === null && this.#reattachIndexerDaemon === null) {
             return;
         }
-        try {
-            await this.#indexerDaemon.resumeBackgroundFollow();
-            return;
-        }
-        catch (error) {
-            if (this.#reattachIndexerDaemon === null) {
-                throw error;
+        if (this.#indexerDaemon !== null) {
+            try {
+                await this.#indexerDaemon.resumeBackgroundFollow();
+                return;
             }
+            catch (error) {
+                if (this.#reattachIndexerDaemon === null) {
+                    throw error;
+                }
+            }
+        }
+        const reattachIndexerDaemon = this.#reattachIndexerDaemon;
+        if (reattachIndexerDaemon === null) {
+            return;
         }
-        const replacementDaemon = await this.#reattachIndexerDaemon();
+        const replacementDaemon = await reattachIndexerDaemon();
         this.#indexerDaemon = replacementDaemon;
         await replacementDaemon?.resumeBackgroundFollow();
     }

package/dist/bitcoind/client/sync-engine.js

@@ -4,6 +4,7 @@ import { normalizeRpcBlock } from "../normalize.js";
 import { MANAGED_RPC_RETRY_MESSAGE, consumeManagedRpcRetryDelayMs, createManagedRpcRetryState, describeManagedRpcRetryError, isRetryableManagedRpcError, resetManagedRpcRetryState, } from "../retryable-rpc.js";
 import { estimateEtaSeconds } from "./rate-tracker.js";
 const DEFAULT_SYNC_CATCH_UP_POLL_MS = 2_000;
+const BITCOIN_SYNC_PHASE_DEBOUNCE_MS = DEFAULT_SYNC_CATCH_UP_POLL_MS * 3;
 function createAbortError(signal) {
     const reason = signal?.reason;
     if (reason instanceof Error) {
@@ -53,6 +54,22 @@ async function setBitcoinSyncProgress(dependencies, info, targetHeightCap) {
             : "Reading blocks from the managed Bitcoin node.",
     });
 }
+function resolveIndexedHeightForReplayWindow(tip, startHeight) {
+    return tip?.height ?? (startHeight - 1);
+}
+function hasPendingCogcoinReplay(tip, startHeight, bestHeight) {
+    if (bestHeight < startHeight) {
+        return false;
+    }
+    return resolveIndexedHeightForReplayWindow(tip, startHeight) < bestHeight;
+}
+function shouldPreserveCogcoinSyncPhase(dependencies) {
+    const status = dependencies.progress.getStatusSnapshot();
+    // Keep the TTY on Cogcoin replay through brief idle gaps so it does not
+    // bounce back to Bitcoin sync between closely spaced replay passes.
+    return status.bootstrapPhase === "cogcoin_sync"
+        && Date.now() - status.bootstrapProgress.updatedAt < BITCOIN_SYNC_PHASE_DEBOUNCE_MS;
+}
 async function setRetryingProgress(dependencies, error) {
     const status = dependencies.progress.getStatusSnapshot();
     const { phase: _phase, updatedAt: _updatedAt, ...progress } = status.bootstrapProgress;
@@ -152,6 +169,7 @@ export async function syncToTip(dependencies) {
         await runRpc(() => dependencies.bootstrap.ensureReady(indexedTipBeforeBootstrap, dependencies.node.expectedChain, {
             signal: dependencies.abortSignal,
             retryState,
+            resumeDisplayMode: dependencies.isFollowing() ? "follow" : "sync",
         }));
         if (dependencies.node.expectedChain === "main"
             && dependencies.node.getblockArchiveEndHeight !== null) {
@@ -175,7 +193,11 @@ export async function syncToTip(dependencies) {
             const cappedBestHeight = dependencies.targetHeightCap === null || dependencies.targetHeightCap === undefined
                 ? startInfo.blocks
                 : Math.min(startInfo.blocks, dependencies.targetHeightCap);
-            await setBitcoinSyncProgress(dependencies, startInfo, dependencies.targetHeightCap ?? null);
+            const tipBeforePass = await dependencies.client.getTip();
+            if (!hasPendingCogcoinReplay(tipBeforePass, dependencies.startHeight, cappedBestHeight)
+                && !shouldPreserveCogcoinSyncPhase(dependencies)) {
+                await setBitcoinSyncProgress(dependencies, startInfo, dependencies.targetHeightCap ?? null);
+            }
             const pass = await syncAgainstBestHeight(dependencies, cappedBestHeight, runRpc);
             aggregate.appliedBlocks += pass.appliedBlocks;
             aggregate.rewoundBlocks += pass.rewoundBlocks;
@@ -193,8 +215,10 @@ export async function syncToTip(dependencies) {
             aggregate.endingHeight = finalTip?.height ?? null;
             aggregate.bestHeight = endBestHeight;
             aggregate.bestHashHex = endInfo.bestblockhash;
-            if ((dependencies.targetHeightCap !== null && dependencies.targetHeightCap !== undefined && caughtUpCogcoin)
-                || (endInfo.blocks === endInfo.headers && caughtUpCogcoin)) {
+            if (dependencies.targetHeightCap !== null && dependencies.targetHeightCap !== undefined && caughtUpCogcoin) {
+                return aggregate;
+            }
+            if (endInfo.blocks === endInfo.headers && caughtUpCogcoin) {
                 if (dependencies.isFollowing()) {
                     dependencies.progress.replaceFollowBlockTimes(await runRpc(() => dependencies.loadVisibleFollowBlockTimes(finalTip)));
                 }
@@ -209,10 +233,12 @@ export async function syncToTip(dependencies) {
                 });
                 return aggregate;
             }
-            await setBitcoinSyncProgress(dependencies, endInfo, dependencies.targetHeightCap ?? null);
             if (endBestHeight >= dependencies.startHeight && finalTip?.height !== endBestHeight) {
                 continue;
             }
+            if (!shouldPreserveCogcoinSyncPhase(dependencies)) {
+                await setBitcoinSyncProgress(dependencies, endInfo, dependencies.targetHeightCap ?? null);
+            }
             await sleep(DEFAULT_SYNC_CATCH_UP_POLL_MS, dependencies.abortSignal);
         }
     }

package/dist/bitcoind/progress/formatting.js

@@ -144,7 +144,7 @@ export function resolveStatusFieldText(progress, snapshotHeight, now = 0) {
         case "follow_tip":
             return `Waiting for next block to be mined${animateStatusEllipsis(now)}`;
         case "complete":
-            return `Syncing Cogcoin Blocks${animateStatusEllipsis(now)}`;
+            return `Sync complete${animateStatusEllipsis(now)}`;
         case "error":
             return progress.lastError === null
                 ? progress.message

package/dist/bitcoind/testing.d.ts

@@ -1,5 +1,6 @@
 export { openManagedBitcoindClientInternal } from "./client.js";
 export { DefaultManagedBitcoindClient } from "./client/managed-client.js";
+export { pauseIndexerDaemonForForegroundClientForTesting } from "./client/factory.js";
 export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopIndexerDaemonService, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";

package/dist/bitcoind/testing.js

@@ -1,5 +1,6 @@
 export { openManagedBitcoindClientInternal } from "./client.js";
 export { DefaultManagedBitcoindClient } from "./client/managed-client.js";
+export { pauseIndexerDaemonForForegroundClientForTesting } from "./client/factory.js";
 export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopIndexerDaemonService, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";

package/dist/cli/commands/follow.js

@@ -1,22 +1,38 @@
 import { dirname } from "node:path";
+import { FileLockBusyError, acquireFileLock } from "../../wallet/fs/lock.js";
 import { resolveWalletRootIdFromLocalArtifacts } from "../../wallet/root-resolution.js";
 import { usesTtyProgress, writeLine } from "../io.js";
-import { classifyCliError } from "../output.js";
+import { classifyCliError, formatCliTextError } from "../output.js";
 import { createStopSignalWatcher } from "../signals.js";
 export async function runFollowCommand(parsed, context) {
     const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
     const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
-    const walletRoot = await resolveWalletRootIdFromLocalArtifacts({
-        paths: context.resolveWalletRuntimePaths(),
-        provider: context.walletSecretProvider,
-        loadRawWalletStateEnvelope: context.loadRawWalletStateEnvelope,
-        loadUnlockSession: context.loadUnlockSession,
-        loadWalletExplicitLock: context.loadWalletExplicitLock,
-    });
-    await context.ensureDirectory(dirname(dbPath));
-    const store = await context.openSqliteStore({ filename: dbPath });
+    const runtimePaths = context.resolveWalletRuntimePaths();
+    let controlLock = null;
+    let store = null;
     let storeOwned = true;
     try {
+        const walletRoot = await resolveWalletRootIdFromLocalArtifacts({
+            paths: runtimePaths,
+            provider: context.walletSecretProvider,
+            loadRawWalletStateEnvelope: context.loadRawWalletStateEnvelope,
+            loadUnlockSession: context.loadUnlockSession,
+            loadWalletExplicitLock: context.loadWalletExplicitLock,
+        });
+        try {
+            controlLock = await acquireFileLock(runtimePaths.walletControlLockPath, {
+                purpose: "managed-follow",
+                walletRootId: walletRoot.walletRootId,
+            });
+        }
+        catch (error) {
+            if (error instanceof FileLockBusyError) {
+                throw new Error("wallet_control_lock_busy");
+            }
+            throw error;
+        }
+        await context.ensureDirectory(dirname(dbPath));
+        store = await context.openSqliteStore({ filename: dbPath });
         const client = await context.openManagedBitcoindClient({
             store,
             databasePath: dbPath,
@@ -25,7 +41,7 @@ export async function runFollowCommand(parsed, context) {
             progressOutput: parsed.progressOutput,
         });
         storeOwned = false;
-        const stopWatcher = createStopSignalWatcher(context.signalSource, context.stderr, client, context.forceExit);
+        const stopWatcher = createStopSignalWatcher(context.signalSource, context.stderr, client, context.forceExit, [runtimePaths.walletControlLockPath]);
         try {
             await client.startFollowingTip();
             if (!usesTtyProgress(parsed.progressOutput, context.stderr)) {
@@ -43,10 +59,27 @@ export async function runFollowCommand(parsed, context) {
         }
     }
     catch (error) {
-        writeLine(context.stderr, `follow failed: ${error instanceof Error ? error.message : String(error)}`);
-        if (storeOwned) {
+        const classified = classifyCliError(error);
+        if (classified.errorCode === "wallet_control_lock_busy") {
+            const formatted = formatCliTextError(error);
+            if (formatted !== null) {
+                for (const line of formatted) {
+                    writeLine(context.stderr, line);
+                }
+            }
+            else {
+                writeLine(context.stderr, classified.message);
+            }
+        }
+        else {
+            writeLine(context.stderr, `follow failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (storeOwned && store !== null) {
             await store.close().catch(() => undefined);
         }
-        return classifyCliError(error).exitCode;
+        return classified.exitCode;
+    }
+    finally {
+        await controlLock?.release().catch(() => undefined);
     }
 }

package/dist/cli/commands/sync.js

@@ -1,23 +1,39 @@
 import { dirname } from "node:path";
 import { formatManagedSyncErrorMessage } from "../../bitcoind/errors.js";
+import { FileLockBusyError, acquireFileLock } from "../../wallet/fs/lock.js";
 import { resolveWalletRootIdFromLocalArtifacts } from "../../wallet/root-resolution.js";
 import { writeLine } from "../io.js";
-import { classifyCliError } from "../output.js";
+import { classifyCliError, formatCliTextError } from "../output.js";
 import { createStopSignalWatcher, waitForCompletionOrStop } from "../signals.js";
 export async function runSyncCommand(parsed, context) {
     const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
     const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
-    const walletRoot = await resolveWalletRootIdFromLocalArtifacts({
-        paths: context.resolveWalletRuntimePaths(),
-        provider: context.walletSecretProvider,
-        loadRawWalletStateEnvelope: context.loadRawWalletStateEnvelope,
-        loadUnlockSession: context.loadUnlockSession,
-        loadWalletExplicitLock: context.loadWalletExplicitLock,
-    });
-    await context.ensureDirectory(dirname(dbPath));
-    const store = await context.openSqliteStore({ filename: dbPath });
+    const runtimePaths = context.resolveWalletRuntimePaths();
+    let controlLock = null;
+    let store = null;
     let storeOwned = true;
     try {
+        const walletRoot = await resolveWalletRootIdFromLocalArtifacts({
+            paths: runtimePaths,
+            provider: context.walletSecretProvider,
+            loadRawWalletStateEnvelope: context.loadRawWalletStateEnvelope,
+            loadUnlockSession: context.loadUnlockSession,
+            loadWalletExplicitLock: context.loadWalletExplicitLock,
+        });
+        try {
+            controlLock = await acquireFileLock(runtimePaths.walletControlLockPath, {
+                purpose: "managed-sync",
+                walletRootId: walletRoot.walletRootId,
+            });
+        }
+        catch (error) {
+            if (error instanceof FileLockBusyError) {
+                throw new Error("wallet_control_lock_busy");
+            }
+            throw error;
+        }
+        await context.ensureDirectory(dirname(dbPath));
+        store = await context.openSqliteStore({ filename: dbPath });
         const client = await context.openManagedBitcoindClient({
             store,
             databasePath: dbPath,
@@ -26,7 +42,7 @@ export async function runSyncCommand(parsed, context) {
             progressOutput: parsed.progressOutput,
         });
         storeOwned = false;
-        const stopWatcher = createStopSignalWatcher(context.signalSource, context.stderr, client, context.forceExit);
+        const stopWatcher = createStopSignalWatcher(context.signalSource, context.stderr, client, context.forceExit, [runtimePaths.walletControlLockPath]);
         try {
             const syncOutcome = await waitForCompletionOrStop(client.syncToTip(), stopWatcher);
             if (syncOutcome.kind === "stopped") {
@@ -51,11 +67,28 @@ export async function runSyncCommand(parsed, context) {
         }
     }
     catch (error) {
-        const message = formatManagedSyncErrorMessage(error instanceof Error ? error.message : String(error));
-        writeLine(context.stderr, `sync failed: ${message}`);
-        if (storeOwned) {
+        const classified = classifyCliError(error);
+        if (classified.errorCode === "wallet_control_lock_busy") {
+            const formatted = formatCliTextError(error);
+            if (formatted !== null) {
+                for (const line of formatted) {
+                    writeLine(context.stderr, line);
+                }
+            }
+            else {
+                writeLine(context.stderr, classified.message);
+            }
+        }
+        else {
+            const message = formatManagedSyncErrorMessage(error instanceof Error ? error.message : String(error));
+            writeLine(context.stderr, `sync failed: ${message}`);
+        }
+        if (storeOwned && store !== null) {
             await store.close().catch(() => undefined);
         }
-        return classifyCliError(error).exitCode;
+        return classified.exitCode;
+    }
+    finally {
+        await controlLock?.release().catch(() => undefined);
     }
 }

package/dist/cli/context.js

@@ -2,7 +2,7 @@ import { mkdir, readFile } from "node:fs/promises";
 import { attachOrStartIndexerDaemon, probeIndexerDaemon, readObservedIndexerDaemonStatus, stopIndexerDaemonService, } from "../bitcoind/indexer-daemon.js";
 import { createRpcClient } from "../bitcoind/node.js";
 import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopManagedBitcoindService, } from "../bitcoind/service.js";
-import { resolveDefaultBitcoindDataDirForTesting, resolveDefaultClientDatabasePathForTesting, } from "../app-paths.js";
+import { resolveDefaultBitcoindDataDirForTesting, resolveDefaultClientDatabasePathForTesting, resolveDefaultUpdateCheckStatePathForTesting, } from "../app-paths.js";
 import { openManagedBitcoindClient } from "../bitcoind/index.js";
 import { inspectPassiveClientStatus } from "../passive-status.js";
 import { openSqliteStore } from "../sqlite/index.js";
@@ -26,10 +26,13 @@ export function createDefaultContext(overrides = {}) {
         stdout: overrides.stdout ?? process.stdout,
         stderr: overrides.stderr ?? process.stderr,
         stdin: overrides.stdin ?? process.stdin,
+        env: overrides.env ?? process.env,
+        now: overrides.now ?? (() => Date.now()),
         signalSource: overrides.signalSource ?? process,
         forceExit: overrides.forceExit ?? ((code) => {
             process.exit(code);
         }),
+        fetchImpl: overrides.fetchImpl ?? fetch,
         openSqliteStore: overrides.openSqliteStore ?? openSqliteStore,
         openManagedBitcoindClient: overrides.openManagedBitcoindClient ?? openManagedBitcoindClient,
         inspectPassiveClientStatus: overrides.inspectPassiveClientStatus ?? inspectPassiveClientStatus,
@@ -96,6 +99,7 @@ export function createDefaultContext(overrides = {}) {
         loadWalletExplicitLock: overrides.loadWalletExplicitLock ?? loadWalletExplicitLock,
         resolveDefaultBitcoindDataDir: overrides.resolveDefaultBitcoindDataDir ?? resolveDefaultBitcoindDataDirForTesting,
         resolveDefaultClientDatabasePath: overrides.resolveDefaultClientDatabasePath ?? resolveDefaultClientDatabasePathForTesting,
+        resolveUpdateCheckStatePath: overrides.resolveUpdateCheckStatePath ?? resolveDefaultUpdateCheckStatePathForTesting,
         resolveWalletRuntimePaths: overrides.resolveWalletRuntimePaths ?? ((seedName) => resolveWalletRuntimePathsForTesting({ seedName })),
     };
 }

package/dist/cli/output.js

@@ -187,6 +187,10 @@ export function classifyCliError(error) {
     return { exitCode: 5, errorCode: message, message };
 }
 function isBlockedError(message) {
+    if (message === "wallet_control_lock_busy"
+        || message.startsWith("file_lock_busy_")) {
+        return true;
+    }
     if (message === "wallet_locked"
         || message === "wallet_uninitialized"
         || message === "local-state-corrupt"
@@ -239,6 +243,13 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
             next: "Run `cogcoin unlock --for 15m` and retry.",
         };
     }
+    if (errorCode === "wallet_control_lock_busy") {
+        return {
+            what: "Another Cogcoin command is already controlling this wallet.",
+            why: "Commands that sync, follow, or mutate the local index take an exclusive wallet control lock so they do not write the same sqlite store concurrently.",
+            next: "Wait for the other Cogcoin command to finish, or stop it cleanly before retrying.",
+        };
+    }
     if (errorCode === "reset_wallet_choice_invalid") {
         return {
             what: "Wallet reset choice is invalid.",

package/dist/cli/runner.js

@@ -12,6 +12,7 @@ import { runSyncCommand } from "./commands/sync.js";
 import { runWalletAdminCommand } from "./commands/wallet-admin.js";
 import { runWalletMutationCommand } from "./commands/wallet-mutation.js";
 import { runWalletReadCommand } from "./commands/wallet-read.js";
+import { maybeNotifyAboutCliUpdate } from "./update-notifier.js";
 import { findWalletSeedRecord, loadWalletSeedIndex } from "../wallet/state/seed-index.js";
 function commandUsesExistingWalletSeed(parsed) {
     return parsed.seedName !== null
@@ -48,6 +49,7 @@ export async function runCli(argv, contextOverrides = {}) {
         writeLine(context.stdout, HELP_TEXT.trimEnd());
         return parsed.help ? 0 : 2;
     }
+    await maybeNotifyAboutCliUpdate(parsed, context);
     try {
         if (commandUsesExistingWalletSeed(parsed)) {
             const mainPaths = context.resolveWalletRuntimePaths("main");

package/dist/cli/signals.d.ts

@@ -1,4 +1,4 @@
 import type { InterruptibleOutcome, ManagedClientLike, SignalSource, StopSignalWatcher, WritableLike } from "./types.js";
-export declare function createStopSignalWatcher(signalSource: SignalSource, stderr: WritableLike, client: ManagedClientLike, forceExit: (code: number) => never | void): StopSignalWatcher;
+export declare function createStopSignalWatcher(signalSource: SignalSource, stderr: WritableLike, client: ManagedClientLike, forceExit: (code: number) => never | void, lockPaths?: readonly string[]): StopSignalWatcher;
 export declare function createOwnedLockCleanupSignalWatcher(signalSource: SignalSource, forceExit: (code: number) => never | void, lockPaths: readonly string[]): StopSignalWatcher;
 export declare function waitForCompletionOrStop<T>(promise: Promise<T>, stopWatcher: StopSignalWatcher): Promise<InterruptibleOutcome<T>>;

package/dist/cli/signals.js

@@ -1,6 +1,6 @@
 import { writeLine } from "./io.js";
 import { clearLockIfOwnedByCurrentProcess } from "../wallet/fs/lock.js";
-export function createStopSignalWatcher(signalSource, stderr, client, forceExit) {
+export function createStopSignalWatcher(signalSource, stderr, client, forceExit, lockPaths = []) {
     let closing = false;
     let resolved = false;
     let onSignal = () => { };
@@ -17,16 +17,23 @@ export function createStopSignalWatcher(signalSource, stderr, client, forceExit)
             cleanup();
             resolve(code);
         };
+        const releaseOwnedLocks = async () => {
+            await Promise.allSettled([...new Set(lockPaths)].map(async (lockPath) => {
+                await clearLockIfOwnedByCurrentProcess(lockPath);
+            }));
+        };
         const onFirstSignal = () => {
             closing = true;
             writeLine(stderr, "Detaching from managed Cogcoin client and resuming background indexer follow...");
-            void client.close().then(() => {
+            void client.close().then(async () => {
+                await releaseOwnedLocks();
                 if (resolved) {
                     return;
                 }
                 writeLine(stderr, "Detached cleanly; background indexer follow resumed.");
                 settle(0);
-            }, () => {
+            }, async () => {
+                await releaseOwnedLocks();
                 if (resolved) {
                     return;
                 }
@@ -40,7 +47,13 @@ export function createStopSignalWatcher(signalSource, stderr, client, forceExit)
                 return;
             }
             settle(130);
-            forceExit(130);
+            if (lockPaths.length === 0) {
+                forceExit(130);
+                return;
+            }
+            void releaseOwnedLocks().finally(() => {
+                forceExit(130);
+            });
         };
     });
     signalSource.on("SIGINT", onSignal);

package/dist/cli/types.d.ts

@@ -87,8 +87,11 @@ export interface CliRunnerContext {
     stdout?: WritableLike;
     stderr?: WritableLike;
     stdin?: ReadableLike;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
     signalSource?: SignalSource;
     forceExit?: (code: number) => never | void;
+    fetchImpl?: typeof fetch;
     openSqliteStore?: typeof openSqliteStore;
     openManagedBitcoindClient?: (options: {
         store: ClientStoreAdapter;
@@ -163,6 +166,7 @@ export interface CliRunnerContext {
     readPackageVersion?: () => Promise<string>;
     resolveDefaultBitcoindDataDir?: () => string;
     resolveDefaultClientDatabasePath?: () => string;
+    resolveUpdateCheckStatePath?: () => string;
     resolveWalletRuntimePaths?: (seedName?: string | null) => WalletRuntimePaths;
 }
 export interface StopSignalWatcher {

package/dist/cli/update-notifier.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedCliArgs, RequiredCliRunnerContext } from "./types.js";
+export declare function maybeNotifyAboutCliUpdate(parsed: ParsedCliArgs, context: RequiredCliRunnerContext): Promise<void>;

package/dist/cli/update-notifier.js

@@ -0,0 +1,276 @@
+import { readFile } from "node:fs/promises";
+import { writeJsonFileAtomic } from "../wallet/fs/atomic.js";
+import { writeLine } from "./io.js";
+const UPDATE_CHECK_CACHE_SCHEMA_VERSION = 1;
+const UPDATE_CHECK_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const UPDATE_CHECK_TIMEOUT_MS = 500;
+const UPDATE_CHECK_URL = "https://registry.npmjs.org/@cogcoin/client/latest";
+function createEmptyUpdateCheckCache() {
+    return {
+        schemaVersion: UPDATE_CHECK_CACHE_SCHEMA_VERSION,
+        lastCheckedAtUnixMs: 0,
+        latestVersion: null,
+        lastNotifiedCurrentVersion: null,
+        lastNotifiedLatestVersion: null,
+        lastNotifiedAtUnixMs: null,
+    };
+}
+function parseSemver(version) {
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(version.trim());
+    if (match === null) {
+        return null;
+    }
+    const prerelease = match[4] === undefined
+        ? []
+        : match[4].split(".").map((raw) => ({
+            raw,
+            numeric: /^(0|[1-9]\d*)$/.test(raw),
+            numericValue: /^(0|[1-9]\d*)$/.test(raw) ? Number(raw) : null,
+        }));
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease,
+    };
+}
+function compareSemver(left, right) {
+    const leftParsed = parseSemver(left);
+    const rightParsed = parseSemver(right);
+    if (leftParsed === null || rightParsed === null) {
+        return null;
+    }
+    if (leftParsed.major !== rightParsed.major) {
+        return leftParsed.major > rightParsed.major ? 1 : -1;
+    }
+    if (leftParsed.minor !== rightParsed.minor) {
+        return leftParsed.minor > rightParsed.minor ? 1 : -1;
+    }
+    if (leftParsed.patch !== rightParsed.patch) {
+        return leftParsed.patch > rightParsed.patch ? 1 : -1;
+    }
+    if (leftParsed.prerelease.length === 0 && rightParsed.prerelease.length === 0) {
+        return 0;
+    }
+    if (leftParsed.prerelease.length === 0) {
+        return 1;
+    }
+    if (rightParsed.prerelease.length === 0) {
+        return -1;
+    }
+    const maxLength = Math.max(leftParsed.prerelease.length, rightParsed.prerelease.length);
+    for (let index = 0; index < maxLength; index += 1) {
+        const leftIdentifier = leftParsed.prerelease[index];
+        const rightIdentifier = rightParsed.prerelease[index];
+        if (leftIdentifier === undefined) {
+            return -1;
+        }
+        if (rightIdentifier === undefined) {
+            return 1;
+        }
+        if (leftIdentifier.numeric && rightIdentifier.numeric) {
+            if (leftIdentifier.numericValue !== rightIdentifier.numericValue) {
+                return leftIdentifier.numericValue > rightIdentifier.numericValue ? 1 : -1;
+            }
+            continue;
+        }
+        if (leftIdentifier.numeric !== rightIdentifier.numeric) {
+            return leftIdentifier.numeric ? -1 : 1;
+        }
+        if (leftIdentifier.raw !== rightIdentifier.raw) {
+            return leftIdentifier.raw > rightIdentifier.raw ? 1 : -1;
+        }
+    }
+    return 0;
+}
+function isUpdateCheckDisabled(env) {
+    const raw = env.COGCOIN_DISABLE_UPDATE_CHECK;
+    if (raw === undefined) {
+        return false;
+    }
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+function isEligibleForUpdateNotification(parsed, context) {
+    if (parsed.outputMode !== "text" || parsed.help || parsed.version) {
+        return false;
+    }
+    return context.stdout.isTTY === true || context.stderr.isTTY === true;
+}
+function normalizeUpdateCheckCache(parsed) {
+    if (typeof parsed !== "object" || parsed === null) {
+        return null;
+    }
+    const candidate = parsed;
+    if (candidate.schemaVersion !== UPDATE_CHECK_CACHE_SCHEMA_VERSION) {
+        return null;
+    }
+    return {
+        schemaVersion: UPDATE_CHECK_CACHE_SCHEMA_VERSION,
+        lastCheckedAtUnixMs: typeof candidate.lastCheckedAtUnixMs === "number" ? candidate.lastCheckedAtUnixMs : 0,
+        latestVersion: typeof candidate.latestVersion === "string" ? candidate.latestVersion : null,
+        lastNotifiedCurrentVersion: typeof candidate.lastNotifiedCurrentVersion === "string"
+            ? candidate.lastNotifiedCurrentVersion
+            : null,
+        lastNotifiedLatestVersion: typeof candidate.lastNotifiedLatestVersion === "string"
+            ? candidate.lastNotifiedLatestVersion
+            : null,
+        lastNotifiedAtUnixMs: typeof candidate.lastNotifiedAtUnixMs === "number"
+            ? candidate.lastNotifiedAtUnixMs
+            : null,
+        lastCheckErrorKind: typeof candidate.lastCheckErrorKind === "string"
+            ? candidate.lastCheckErrorKind
+            : undefined,
+    };
+}
+async function loadUpdateCheckCache(cachePath) {
+    try {
+        const raw = await readFile(cachePath, "utf8");
+        return normalizeUpdateCheckCache(JSON.parse(raw));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        return null;
+    }
+}
+function shouldRefreshUpdateCheck(cache, now) {
+    return now - cache.lastCheckedAtUnixMs >= UPDATE_CHECK_MAX_AGE_MS;
+}
+function shouldNotifyForVersionPair(cache, currentVersion, latestVersion, now) {
+    const versionComparison = compareSemver(latestVersion, currentVersion);
+    if (versionComparison === null || versionComparison <= 0) {
+        return false;
+    }
+    if (cache.lastNotifiedCurrentVersion !== currentVersion
+        || cache.lastNotifiedLatestVersion !== latestVersion) {
+        return true;
+    }
+    if (cache.lastNotifiedAtUnixMs === null) {
+        return true;
+    }
+    return now - cache.lastNotifiedAtUnixMs >= UPDATE_CHECK_MAX_AGE_MS;
+}
+function recordUpdateNotification(cache, currentVersion, latestVersion, now) {
+    return {
+        ...cache,
+        lastNotifiedCurrentVersion: currentVersion,
+        lastNotifiedLatestVersion: latestVersion,
+        lastNotifiedAtUnixMs: now,
+    };
+}
+async function fetchLatestPublishedVersion(fetchImpl) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, UPDATE_CHECK_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(UPDATE_CHECK_URL, {
+            headers: {
+                accept: "application/json",
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return {
+                kind: "failure",
+                errorKind: `http_${response.status}`,
+            };
+        }
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            return {
+                kind: "failure",
+                errorKind: "invalid_json",
+            };
+        }
+        const latestVersion = typeof payload.version === "string"
+            ? payload.version
+            : null;
+        if (latestVersion === null) {
+            return {
+                kind: "failure",
+                errorKind: "invalid_payload",
+            };
+        }
+        if (parseSemver(latestVersion) === null) {
+            return {
+                kind: "failure",
+                errorKind: "invalid_semver",
+            };
+        }
+        return {
+            kind: "success",
+            latestVersion,
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            return {
+                kind: "failure",
+                errorKind: "timeout",
+            };
+        }
+        return {
+            kind: "failure",
+            errorKind: "network",
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function writeUpdateNotice(context, currentVersion, latestVersion) {
+    writeLine(context.stderr, `Update available: Cogcoin ${currentVersion} -> ${latestVersion}`);
+    writeLine(context.stderr, "Run: npm install -g @cogcoin/client");
+}
+async function persistUpdateCheckCache(cachePath, cache) {
+    await writeJsonFileAtomic(cachePath, cache);
+}
+export async function maybeNotifyAboutCliUpdate(parsed, context) {
+    try {
+        if (!isEligibleForUpdateNotification(parsed, context) || isUpdateCheckDisabled(context.env)) {
+            return;
+        }
+        const currentVersion = await context.readPackageVersion();
+        if (parseSemver(currentVersion) === null) {
+            return;
+        }
+        const cachePath = context.resolveUpdateCheckStatePath();
+        const now = context.now();
+        let cache = await loadUpdateCheckCache(cachePath) ?? createEmptyUpdateCheckCache();
+        let cacheChanged = false;
+        if (shouldRefreshUpdateCheck(cache, now)) {
+            const updateResult = await fetchLatestPublishedVersion(context.fetchImpl);
+            cache = {
+                ...cache,
+                lastCheckedAtUnixMs: now,
+                latestVersion: updateResult.kind === "success"
+                    ? updateResult.latestVersion
+                    : cache.latestVersion,
+                lastCheckErrorKind: updateResult.kind === "success"
+                    ? undefined
+                    : updateResult.errorKind,
+            };
+            cacheChanged = true;
+        }
+        if (cache.latestVersion !== null
+            && shouldNotifyForVersionPair(cache, currentVersion, cache.latestVersion, now)) {
+            writeUpdateNotice(context, currentVersion, cache.latestVersion);
+            cache = recordUpdateNotification(cache, currentVersion, cache.latestVersion, now);
+            cacheChanged = true;
+            await persistUpdateCheckCache(cachePath, cache);
+            return;
+        }
+        if (cacheChanged) {
+            await persistUpdateCheckCache(cachePath, cache);
+        }
+    }
+    catch {
+        // Update checks are best-effort only.
+    }
+}

package/dist/client/default-client.d.ts

@@ -2,7 +2,7 @@ import type { BitcoinBlock, GenesisParameters, IndexerState } from "@cogcoin/ind
 import type { ApplyBlockResult, Client, ClientStoreAdapter, ClientTip } from "../types.js";
 export declare class DefaultClient implements Client {
     #private;
-    constructor(store: ClientStoreAdapter, genesisParameters: GenesisParameters, state: IndexerState, tip: ClientTip | null, snapshotInterval: number);
+    constructor(store: ClientStoreAdapter, genesisParameters: GenesisParameters, state: IndexerState, tip: ClientTip | null, snapshotInterval: number, blockRecordRetention: number);
     getTip(): Promise<ClientTip | null>;
     getState(): Promise<IndexerState>;
     applyBlock(block: BitcoinBlock): Promise<ApplyBlockResult>;

package/dist/client/default-client.js

@@ -4,16 +4,18 @@ export class DefaultClient {
     #store;
     #genesisParameters;
     #snapshotInterval;
+    #blockRecordRetention;
     #state;
     #tip;
     #closed = false;
     #queue = Promise.resolve();
-    constructor(store, genesisParameters, state, tip, snapshotInterval) {
+    constructor(store, genesisParameters, state, tip, snapshotInterval, blockRecordRetention) {
         this.#store = store;
         this.#genesisParameters = genesisParameters;
         this.#state = state;
         this.#tip = tip;
         this.#snapshotInterval = snapshotInterval;
+        this.#blockRecordRetention = blockRecordRetention;
     }
     async getTip() {
         await this.#queue;
@@ -39,6 +41,7 @@ export class DefaultClient {
                 blockRecord: createStoredBlockRecord(applied.blockRecord, createdAt),
                 checkpoint,
                 deleteAboveHeight: null,
+                deleteBelowHeight: this.#blockRecordLowerBound(block.height),
             };
             await this.#store.writeAppliedBlock(writeEntry);
             this.#state = applied.state;
@@ -110,6 +113,9 @@ export class DefaultClient {
     #shouldCheckpoint(height) {
         return this.#snapshotInterval > 0 && height % this.#snapshotInterval === 0;
     }
+    #blockRecordLowerBound(height) {
+        return height - this.#blockRecordRetention + 1;
+    }
     #enqueue(operation) {
         const next = this.#queue.then(operation, operation);
         this.#queue = next.then(() => undefined, () => undefined);

package/dist/client/factory.js

@@ -3,13 +3,18 @@ import { DefaultClient } from "./default-client.js";
 import { initializeState } from "./initialization.js";
 import { createClientStoreAdapter } from "./store-adapter.js";
 const DEFAULT_SNAPSHOT_INTERVAL = 1000;
+const DEFAULT_BLOCK_RECORD_RETENTION = 1000;
 export async function openClient(options) {
     const store = createClientStoreAdapter(options.store);
     const genesisParameters = options.genesisParameters ?? await loadBundledGenesisParameters();
     const snapshotInterval = options.snapshotInterval ?? DEFAULT_SNAPSHOT_INTERVAL;
+    const blockRecordRetention = options.blockRecordRetention ?? DEFAULT_BLOCK_RECORD_RETENTION;
     if (!Number.isInteger(snapshotInterval) || snapshotInterval < 1) {
         throw new RangeError("client_snapshot_interval_invalid");
     }
+    if (!Number.isInteger(blockRecordRetention) || blockRecordRetention < 1) {
+        throw new RangeError("client_block_record_retention_invalid");
+    }
     const { state, tip } = await initializeState(store, genesisParameters);
-    return new DefaultClient(store, genesisParameters, state, tip, snapshotInterval);
+    return new DefaultClient(store, genesisParameters, state, tip, snapshotInterval, blockRecordRetention);
 }

package/dist/sqlite/store.js

@@ -66,6 +66,9 @@ export function createSqliteStoreAdapter(database) {
                         await database.run(`DELETE FROM block_records WHERE height > ?`, [entry.deleteAboveHeight]);
                         await deleteCheckpointsAbove(database, entry.deleteAboveHeight);
                     }
+                    if (entry.deleteBelowHeight !== null && entry.deleteBelowHeight !== undefined) {
+                        await database.run(`DELETE FROM block_records WHERE height < ?`, [entry.deleteBelowHeight]);
+                    }
                     if (entry.blockRecord !== null && entry.blockRecord !== undefined) {
                         await database.run(`INSERT INTO block_records (height, block_hash, previous_hash, record_bytes, state_hash_hex, created_at)
                VALUES (?, ?, ?, ?, ?, ?)`, [

package/dist/types.d.ts

@@ -25,6 +25,7 @@ export interface WriteAppliedBlockEntry {
     blockRecord?: StoredBlockRecord | null;
     checkpoint?: ClientCheckpoint | null;
     deleteAboveHeight?: number | null;
+    deleteBelowHeight?: number | null;
 }
 export interface ClientStoreAdapter {
     loadTip(): Promise<ClientTip | null>;
@@ -39,6 +40,7 @@ export interface ClientOptions {
     store: ClientStoreAdapter;
     genesisParameters?: GenesisParameters;
     snapshotInterval?: number;
+    blockRecordRetention?: number;
 }
 export interface ApplyBlockResult {
     tip: ClientTip;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogcoin/client",
-  "version": "0.5.10",
+  "version": "0.5.12",
   "description": "Store-backed Cogcoin client with wallet flows, SQLite persistence, and managed Bitcoin Core integration.",
   "license": "MIT",
   "type": "module",