@cogcoin/client 0.5.4 → 0.5.5

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@0.5.4` 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.5` is the store-backed Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
 
 Use Node 22 or newer.
 

package/dist/app-paths.d.ts

@@ -17,6 +17,8 @@ export interface CogcoinResolvedPaths {
     walletStateDirectory: string;
     walletStatePath: string;
     walletStateBackupPath: string;
+    walletInitPendingPath: string;
+    walletInitPendingBackupPath: string;
     walletUnlockSessionPath: string;
     walletExplicitLockPath: string;
     walletControlLockPath: string;

package/dist/app-paths.js

@@ -63,6 +63,8 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
     const walletStateDirectory = stateRoot;
     const walletStatePath = joinForPlatform(platform, walletStateDirectory, "wallet-state.enc");
     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");
@@ -91,6 +93,8 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
         walletStateDirectory,
         walletStatePath,
         walletStateBackupPath,
+        walletInitPendingPath,
+        walletInitPendingBackupPath,
         walletUnlockSessionPath,
         walletExplicitLockPath,
         walletControlLockPath,

package/dist/art/wallet.txt

@@ -1,10 +1,10 @@
                      ⛭ Write this down. Keep it secret, keep it safe. ⛭         
-▐▀▀▀▀▀▀▚    ╔──────────────────────────────────────────────────────────────────╗
-▛▞▀▀▀▀▀▀▚   │                                                                  │
-▌▝▀▀▀▀▀▀▀▌  │  1.achieved   6.achieved  11.achieved  16.achieved  21.achieved  │
-▌  ▗▙▙   ▌  │  2.achieved   7.achieved  12.achieved  17.achieved  22.achieved  │
-▌  ▐  ▌  ▌  │  3.achieved   8.achieved  13.achieved  18.achieved  23.achieved  │
-▌  ▐▀▀▚  ▌  │  4.achieved   9.achieved  14.achieved  19.achieved  24.achieved  │
-▌  ▐▄▄▞  ▌  │  5.achieved  10.achieved  15.achieved  20.achieved               │
-▌   ▘▘   ▌  │                                                                  │
-▝▀▀▀▀▀▀▀▀▘  ╚──────────────────────────────────────────────────────────────────╝
+▐▀▀▀▀▀▀▀▀▚  ╔──────────────────────────────────────────────────────────────────╗
+▛▞▀▀▀▀▀▀▀▀▚ │                                                                  │
+▌▝▀▀▀▀▀▀▀▀▀▌│  1.achieved   6.achieved  11.achieved  16.achieved  21.achieved  │
+▌   ▗▙▙    ▌│  2.achieved   7.achieved  12.achieved  17.achieved  22.achieved  │
+▌   ▐  ▌   ▌│  3.achieved   8.achieved  13.achieved  18.achieved  23.achieved  │
+▌   ▐▀▀▚   ▌│  4.achieved   9.achieved  14.achieved  19.achieved  24.achieved  │
+▌   ▐▄▄▞   ▌│  5.achieved  10.achieved  15.achieved  20.achieved               │
+▌    ▘▘    ▌│                                                                  │
+▝▀▀▀▀▀▀▀▀▀▀▘╚──────────────────────────────────────────────────────────────────╝

package/dist/bitcoind/bootstrap/chunk-manifest.d.ts

@@ -0,0 +1,14 @@
+import type { BootstrapPersistentState } from "./types.js";
+import type { SnapshotChunkManifest, SnapshotMetadata } from "../types.js";
+export declare function resolveBundledSnapshotChunkManifest(snapshot?: SnapshotMetadata): SnapshotChunkManifest;
+export declare function resolveSnapshotChunkCount(manifest: SnapshotChunkManifest): number;
+export declare function resolveSnapshotChunkSize(manifest: SnapshotChunkManifest, chunkIndex: number): number;
+export declare function resolveVerifiedChunkBytes(manifest: SnapshotChunkManifest, verifiedChunkCount: number): number;
+export declare function resolveVerifiedChunkCountFromBytes(manifest: SnapshotChunkManifest, bytes: number): number;
+export declare function clampVerifiedChunkCount(manifest: SnapshotChunkManifest, verifiedChunkCount: number): number;
+export declare function stateHasTrustedIntegrityFrontier(state: BootstrapPersistentState, manifest: SnapshotChunkManifest): boolean;
+export declare function createSnapshotChunkManifestRecord(options: {
+    snapshot: SnapshotMetadata;
+    chunkSha256s: string[];
+    chunkSizeBytes?: number;
+}): SnapshotChunkManifest;

package/dist/bitcoind/bootstrap/chunk-manifest.js

@@ -0,0 +1,85 @@
+import { DEFAULT_SNAPSHOT_CHUNK_SIZE_BYTES, SNAPSHOT_CHUNK_MANIFEST_VERSION, } from "./constants.js";
+import { DEFAULT_SNAPSHOT_CHUNK_MANIFEST } from "./default-snapshot-chunk-manifest.js";
+import { DEFAULT_SNAPSHOT_METADATA } from "./constants.js";
+function snapshotMatchesManifest(manifest, snapshot) {
+    return manifest.snapshotFilename === snapshot.filename
+        && manifest.snapshotHeight === snapshot.height
+        && manifest.snapshotSizeBytes === snapshot.sizeBytes
+        && manifest.snapshotSha256 === snapshot.sha256;
+}
+function snapshotMatchesDefault(snapshot) {
+    return snapshot.filename === DEFAULT_SNAPSHOT_METADATA.filename
+        && snapshot.height === DEFAULT_SNAPSHOT_METADATA.height
+        && snapshot.sizeBytes === DEFAULT_SNAPSHOT_METADATA.sizeBytes
+        && snapshot.sha256 === DEFAULT_SNAPSHOT_METADATA.sha256;
+}
+export function resolveBundledSnapshotChunkManifest(snapshot = DEFAULT_SNAPSHOT_METADATA) {
+    if (!snapshotMatchesDefault(snapshot)) {
+        throw new Error(`snapshot_chunk_manifest_unavailable_${snapshot.filename}`);
+    }
+    if (!snapshotMatchesManifest(DEFAULT_SNAPSHOT_CHUNK_MANIFEST, snapshot)) {
+        throw new Error(`snapshot_chunk_manifest_mismatch_${snapshot.filename}`);
+    }
+    return DEFAULT_SNAPSHOT_CHUNK_MANIFEST;
+}
+export function resolveSnapshotChunkCount(manifest) {
+    return manifest.chunkSha256s.length;
+}
+export function resolveSnapshotChunkSize(manifest, chunkIndex) {
+    if (chunkIndex < 0 || chunkIndex >= manifest.chunkSha256s.length) {
+        throw new Error(`snapshot_chunk_index_out_of_range_${chunkIndex}`);
+    }
+    const lastChunkIndex = manifest.chunkSha256s.length - 1;
+    if (chunkIndex < lastChunkIndex) {
+        return manifest.chunkSizeBytes;
+    }
+    const trailingBytes = manifest.snapshotSizeBytes % manifest.chunkSizeBytes;
+    return trailingBytes === 0 ? manifest.chunkSizeBytes : trailingBytes;
+}
+export function resolveVerifiedChunkBytes(manifest, verifiedChunkCount) {
+    const chunkCount = clampVerifiedChunkCount(manifest, verifiedChunkCount);
+    if (chunkCount <= 0) {
+        return 0;
+    }
+    if (chunkCount >= manifest.chunkSha256s.length) {
+        return manifest.snapshotSizeBytes;
+    }
+    return chunkCount * manifest.chunkSizeBytes;
+}
+export function resolveVerifiedChunkCountFromBytes(manifest, bytes) {
+    if (bytes >= manifest.snapshotSizeBytes) {
+        return manifest.chunkSha256s.length;
+    }
+    if (bytes <= 0) {
+        return 0;
+    }
+    return Math.floor(bytes / manifest.chunkSizeBytes);
+}
+export function clampVerifiedChunkCount(manifest, verifiedChunkCount) {
+    if (!Number.isFinite(verifiedChunkCount) || verifiedChunkCount <= 0) {
+        return 0;
+    }
+    return Math.min(Math.trunc(verifiedChunkCount), manifest.chunkSha256s.length);
+}
+export function stateHasTrustedIntegrityFrontier(state, manifest) {
+    if (state.integrityVersion !== SNAPSHOT_CHUNK_MANIFEST_VERSION) {
+        return false;
+    }
+    if (state.chunkSizeBytes !== manifest.chunkSizeBytes) {
+        return false;
+    }
+    const verifiedChunkCount = clampVerifiedChunkCount(manifest, state.verifiedChunkCount);
+    const verifiedBytes = resolveVerifiedChunkBytes(manifest, verifiedChunkCount);
+    return state.downloadedBytes === verifiedBytes;
+}
+export function createSnapshotChunkManifestRecord(options) {
+    return {
+        formatVersion: SNAPSHOT_CHUNK_MANIFEST_VERSION,
+        chunkSizeBytes: options.chunkSizeBytes ?? DEFAULT_SNAPSHOT_CHUNK_SIZE_BYTES,
+        snapshotFilename: options.snapshot.filename,
+        snapshotHeight: options.snapshot.height,
+        snapshotSizeBytes: options.snapshot.sizeBytes,
+        snapshotSha256: options.snapshot.sha256,
+        chunkSha256s: options.chunkSha256s,
+    };
+}

package/dist/bitcoind/bootstrap/chunk-recovery.d.ts

@@ -0,0 +1,4 @@
+import type { BootstrapPaths, BootstrapPersistentState, BootstrapStateSnapshotIdentity } from "./types.js";
+import type { SnapshotChunkManifest } from "../types.js";
+export declare function applyVerifiedFrontierState(state: BootstrapPersistentState, manifest: SnapshotChunkManifest, verifiedChunkCount: number): void;
+export declare function reconcileSnapshotDownloadArtifacts(paths: BootstrapPaths, state: BootstrapPersistentState, manifest: SnapshotChunkManifest, snapshotIdentity: BootstrapStateSnapshotIdentity): Promise<void>;

package/dist/bitcoind/bootstrap/chunk-recovery.js

@@ -0,0 +1,122 @@
+import { createHash } from "node:crypto";
+import { open, rename, rm } from "node:fs/promises";
+import { clampVerifiedChunkCount, resolveSnapshotChunkCount, resolveSnapshotChunkSize, resolveVerifiedChunkBytes, resolveVerifiedChunkCountFromBytes, stateHasTrustedIntegrityFrontier, } from "./chunk-manifest.js";
+import { resetSnapshotFiles, statOrNull } from "./snapshot-file.js";
+const TRUSTED_FRONTIER_REVERIFY_CHUNKS = 2;
+const HASH_READ_BUFFER_BYTES = 1024 * 1024;
+async function moveSnapshotPathToPartial(paths) {
+    const partInfo = await statOrNull(paths.partialSnapshotPath);
+    const fullInfo = await statOrNull(paths.snapshotPath);
+    if (fullInfo === null) {
+        return;
+    }
+    if (partInfo !== null && partInfo.size > fullInfo.size) {
+        await rm(paths.snapshotPath, { force: true });
+        return;
+    }
+    if (partInfo !== null) {
+        await rm(paths.partialSnapshotPath, { force: true });
+    }
+    await rename(paths.snapshotPath, paths.partialSnapshotPath);
+}
+async function hashChunkRange(path, manifest, chunkIndex) {
+    const file = await open(path, "r");
+    const chunkSizeBytes = resolveSnapshotChunkSize(manifest, chunkIndex);
+    const buffer = Buffer.allocUnsafe(Math.min(HASH_READ_BUFFER_BYTES, chunkSizeBytes));
+    const hash = createHash("sha256");
+    let remainingBytes = chunkSizeBytes;
+    let position = resolveVerifiedChunkBytes(manifest, chunkIndex);
+    try {
+        while (remainingBytes > 0) {
+            const readLength = Math.min(buffer.length, remainingBytes);
+            const { bytesRead } = await file.read(buffer, 0, readLength, position);
+            if (bytesRead === 0) {
+                return null;
+            }
+            hash.update(buffer.subarray(0, bytesRead));
+            remainingBytes -= bytesRead;
+            position += bytesRead;
+            if (bytesRead < readLength) {
+                return remainingBytes === 0 ? hash.digest("hex") : null;
+            }
+        }
+    }
+    finally {
+        await file.close();
+    }
+    return hash.digest("hex");
+}
+async function scanVerifiedPrefix(path, manifest, fileSize) {
+    const chunkCount = resolveSnapshotChunkCount(manifest);
+    for (let chunkIndex = 0; chunkIndex < chunkCount; chunkIndex += 1) {
+        const expectedChunkEnd = resolveVerifiedChunkBytes(manifest, chunkIndex + 1);
+        if (fileSize < expectedChunkEnd) {
+            return chunkIndex;
+        }
+        const actualSha256 = await hashChunkRange(path, manifest, chunkIndex);
+        if (actualSha256 !== manifest.chunkSha256s[chunkIndex]) {
+            return chunkIndex;
+        }
+    }
+    return chunkCount;
+}
+async function reverifyTrustedFrontier(path, manifest, verifiedChunkCount, fileSize) {
+    const maxCompleteChunkCount = resolveVerifiedChunkCountFromBytes(manifest, Math.min(fileSize, manifest.snapshotSizeBytes));
+    const tentativeVerifiedChunkCount = Math.min(clampVerifiedChunkCount(manifest, verifiedChunkCount), maxCompleteChunkCount);
+    const startChunk = Math.max(0, tentativeVerifiedChunkCount - TRUSTED_FRONTIER_REVERIFY_CHUNKS);
+    for (let chunkIndex = startChunk; chunkIndex < tentativeVerifiedChunkCount; chunkIndex += 1) {
+        const actualSha256 = await hashChunkRange(path, manifest, chunkIndex);
+        if (actualSha256 !== manifest.chunkSha256s[chunkIndex]) {
+            return chunkIndex;
+        }
+    }
+    return tentativeVerifiedChunkCount;
+}
+async function truncatePartialSnapshot(paths, verifiedBytes) {
+    const file = await open(paths.partialSnapshotPath, "a+");
+    try {
+        await file.truncate(verifiedBytes);
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+}
+export function applyVerifiedFrontierState(state, manifest, verifiedChunkCount) {
+    const clampedVerifiedChunkCount = clampVerifiedChunkCount(manifest, verifiedChunkCount);
+    state.integrityVersion = manifest.formatVersion;
+    state.chunkSizeBytes = manifest.chunkSizeBytes;
+    state.verifiedChunkCount = clampedVerifiedChunkCount;
+    state.downloadedBytes = resolveVerifiedChunkBytes(manifest, clampedVerifiedChunkCount);
+}
+export async function reconcileSnapshotDownloadArtifacts(paths, state, manifest, snapshotIdentity) {
+    if (snapshotIdentity === "different") {
+        await resetSnapshotFiles(paths);
+        state.phase = "snapshot_download";
+        state.loadTxOutSetComplete = false;
+        state.baseHeight = null;
+        state.tipHashHex = null;
+        state.lastError = null;
+        applyVerifiedFrontierState(state, manifest, 0);
+        state.validated = false;
+        return;
+    }
+    if (!state.validated) {
+        await moveSnapshotPathToPartial(paths);
+    }
+    const partialInfo = await statOrNull(paths.partialSnapshotPath);
+    if (partialInfo === null) {
+        applyVerifiedFrontierState(state, manifest, 0);
+        state.validated = false;
+        return;
+    }
+    const verifiedChunkCount = stateHasTrustedIntegrityFrontier(state, manifest)
+        ? await reverifyTrustedFrontier(paths.partialSnapshotPath, manifest, state.verifiedChunkCount, partialInfo.size)
+        : await scanVerifiedPrefix(paths.partialSnapshotPath, manifest, partialInfo.size);
+    const verifiedBytes = resolveVerifiedChunkBytes(manifest, verifiedChunkCount);
+    if (partialInfo.size !== verifiedBytes) {
+        await truncatePartialSnapshot(paths, verifiedBytes);
+    }
+    applyVerifiedFrontierState(state, manifest, verifiedChunkCount);
+    state.validated = false;
+}

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

@@ -1,5 +1,7 @@
 import type { SnapshotMetadata } from "../types.js";
-export declare const SNAPSHOT_METADATA_VERSION = 1;
+export declare const BOOTSTRAP_STATE_VERSION = 2;
+export declare const SNAPSHOT_CHUNK_MANIFEST_VERSION = 1;
+export declare const DEFAULT_SNAPSHOT_CHUNK_SIZE_BYTES: number;
 export declare const DOWNLOAD_RETRY_BASE_MS = 1000;
 export declare const DOWNLOAD_RETRY_MAX_MS = 30000;
 export declare const HEADER_POLL_MS = 2000;

package/dist/bitcoind/bootstrap/constants.js

@@ -1,4 +1,6 @@
-export const SNAPSHOT_METADATA_VERSION = 1;
+export const BOOTSTRAP_STATE_VERSION = 2;
+export const SNAPSHOT_CHUNK_MANIFEST_VERSION = 1;
+export const DEFAULT_SNAPSHOT_CHUNK_SIZE_BYTES = 4 * 1024 * 1024;
 export const DOWNLOAD_RETRY_BASE_MS = 1_000;
 export const DOWNLOAD_RETRY_MAX_MS = 30_000;
 export const HEADER_POLL_MS = 2_000;

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

@@ -13,11 +13,16 @@ export declare class AssumeUtxoBootstrapController {
     });
     get quoteStatePath(): string;
     get snapshot(): SnapshotMetadata;
-    ensureReady(indexedTip: ClientTip | null, expectedChain: "main" | "regtest"): Promise<void>;
+    ensureReady(indexedTip: ClientTip | null, expectedChain: "main" | "regtest", options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
     getStateForTesting(): Promise<{
         metadataVersion: number;
         snapshot: SnapshotMetadata;
         phase: BootstrapPhase;
+        integrityVersion: number;
+        chunkSizeBytes: number;
+        verifiedChunkCount: number;
         downloadedBytes: number;
         validated: boolean;
         loadTxOutSetComplete: boolean;

package/dist/bitcoind/bootstrap/controller.js

@@ -4,7 +4,7 @@ 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 { loadBootstrapStateRecord, saveBootstrapState } from "./state.js";
 import { isSnapshotAlreadyLoaded } from "./chainstate.js";
 async function loadSnapshotIntoNode(rpc, snapshotPath) {
     return rpc.loadTxOutSet(snapshotPath);
@@ -15,7 +15,7 @@ export class AssumeUtxoBootstrapController {
     #progress;
     #snapshot;
     #fetchImpl;
-    #statePromise = null;
+    #stateRecordPromise = null;
     constructor(options) {
         this.#rpc = options.rpc;
         this.#progress = options.progress;
@@ -29,7 +29,7 @@ export class AssumeUtxoBootstrapController {
     get snapshot() {
         return this.#snapshot;
     }
-    async ensureReady(indexedTip, expectedChain) {
+    async ensureReady(indexedTip, expectedChain, options = {}) {
         if (expectedChain !== "main") {
             await this.#progress.setPhase("paused", {
                 ...createBootstrapProgressForTesting("paused", this.#snapshot),
@@ -45,7 +45,7 @@ export class AssumeUtxoBootstrapController {
             });
             return;
         }
-        const state = await this.#loadState();
+        const { state, snapshotIdentity } = await this.#loadStateRecord();
         if (state.loadTxOutSetComplete && await isSnapshotAlreadyLoaded(this.#rpc, this.#snapshot, state)) {
             await this.#progress.setPhase("bitcoin_sync", {
                 blocks: state.baseHeight,
@@ -63,9 +63,13 @@ export class AssumeUtxoBootstrapController {
             paths: this.#paths,
             progress: this.#progress,
             state,
+            signal: options.signal,
+            snapshotIdentity,
         });
         if (!await isSnapshotAlreadyLoaded(this.#rpc, this.#snapshot, state)) {
-            await waitForHeaders(this.#rpc, this.#snapshot, this.#progress);
+            await waitForHeaders(this.#rpc, this.#snapshot, this.#progress, {
+                signal: options.signal,
+            });
             await this.#progress.setPhase("load_snapshot", {
                 downloadedBytes: this.#snapshot.sizeBytes,
                 totalBytes: this.#snapshot.sizeBytes,
@@ -95,7 +99,10 @@ export class AssumeUtxoBootstrapController {
         return { ...(await this.#loadState()) };
     }
     async #loadState() {
-        this.#statePromise ??= loadBootstrapState(this.#paths, this.#snapshot);
-        return this.#statePromise;
+        return (await this.#loadStateRecord()).state;
+    }
+    async #loadStateRecord() {
+        this.#stateRecordPromise ??= loadBootstrapStateRecord(this.#paths, this.#snapshot);
+        return this.#stateRecordPromise;
     }
 }

package/dist/bitcoind/bootstrap/default-snapshot-chunk-manifest.d.ts

@@ -0,0 +1,2 @@
+import type { SnapshotChunkManifest } from "../types.js";
+export declare const DEFAULT_SNAPSHOT_CHUNK_MANIFEST: SnapshotChunkManifest;