@cogcoin/client 0.5.4 → 0.5.5

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

@@ -2,9 +2,39 @@ import { formatManagedSyncErrorMessage } from "../errors.js";
 import { normalizeRpcBlock } from "../normalize.js";
 import { estimateEtaSeconds } from "./rate-tracker.js";
 const DEFAULT_SYNC_CATCH_UP_POLL_MS = 2_000;
-function sleep(ms) {
-    return new Promise((resolve) => {
-        setTimeout(resolve, ms);
+function createAbortError(signal) {
+    const reason = signal?.reason;
+    if (reason instanceof Error) {
+        return reason;
+    }
+    const error = new Error("managed_sync_aborted");
+    error.name = "AbortError";
+    return error;
+}
+function isAbortError(error, signal) {
+    if (signal?.aborted) {
+        return true;
+    }
+    return error instanceof Error
+        && (error.name === "AbortError" || error.message === "managed_sync_aborted");
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw createAbortError(signal);
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            reject(createAbortError(signal));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
 async function setBitcoinSyncProgress(dependencies, info) {
@@ -81,9 +111,12 @@ async function syncAgainstBestHeight(dependencies, bestHeight) {
 }
 export async function syncToTip(dependencies) {
     try {
+        throwIfAborted(dependencies.abortSignal);
         await dependencies.node.validate();
         const indexedTipBeforeBootstrap = await dependencies.client.getTip();
-        await dependencies.bootstrap.ensureReady(indexedTipBeforeBootstrap, dependencies.node.expectedChain);
+        await dependencies.bootstrap.ensureReady(indexedTipBeforeBootstrap, dependencies.node.expectedChain, {
+            signal: dependencies.abortSignal,
+        });
         const startTip = await dependencies.client.getTip();
         const aggregate = {
             appliedBlocks: 0,
@@ -95,6 +128,7 @@ export async function syncToTip(dependencies) {
             bestHashHex: "",
         };
         while (true) {
+            throwIfAborted(dependencies.abortSignal);
             const startInfo = await dependencies.rpc.getBlockchainInfo();
             await setBitcoinSyncProgress(dependencies, startInfo);
             const pass = await syncAgainstBestHeight(dependencies, startInfo.blocks);
@@ -129,10 +163,13 @@ export async function syncToTip(dependencies) {
             if (endInfo.blocks >= dependencies.startHeight && finalTip?.height !== endInfo.blocks) {
                 continue;
             }
-            await sleep(DEFAULT_SYNC_CATCH_UP_POLL_MS);
+            await sleep(DEFAULT_SYNC_CATCH_UP_POLL_MS, dependencies.abortSignal);
         }
     }
     catch (error) {
+        if (isAbortError(error, dependencies.abortSignal)) {
+            throw createAbortError(dependencies.abortSignal);
+        }
         const message = formatManagedSyncErrorMessage(error instanceof Error ? error.message : String(error));
         await dependencies.progress.setPhase("error", {
             lastError: message,

package/dist/bitcoind/errors.js

@@ -18,6 +18,15 @@ export function formatManagedSyncErrorMessage(message) {
     if (message === "snapshot_response_body_missing") {
         return appendNextStep("Snapshot server returned an empty response body.", "Wait a moment, confirm the snapshot host is reachable, then rerun sync.");
     }
+    if (message === "snapshot_resume_requires_partial_content") {
+        return appendNextStep("Snapshot server ignored the resume request for a partial download.", "Wait a moment and rerun sync. If this keeps happening, confirm the snapshot host supports HTTP range requests.");
+    }
+    if (message.startsWith("snapshot_chunk_sha256_mismatch_")) {
+        return appendNextStep("A downloaded snapshot chunk was corrupted and was rolled back to the last verified checkpoint.", "Wait a moment and rerun sync. If this keeps happening, check local disk health and the stability of the snapshot connection.");
+    }
+    if (message.startsWith("snapshot_download_incomplete_")) {
+        return appendNextStep("Snapshot download ended before the expected file size was reached.", "Wait a moment and rerun sync. The downloader will resume from the last verified checkpoint.");
+    }
     if (message === "bitcoind_cookie_timeout") {
         return appendNextStep("The managed Bitcoin node did not finish starting in time.", "Check the node logs and local permissions for the Bitcoin data directory, then rerun sync.");
     }

package/dist/bitcoind/types.d.ts

@@ -8,6 +8,15 @@ export interface SnapshotMetadata {
     sha256: string;
     sizeBytes: number;
 }
+export interface SnapshotChunkManifest {
+    formatVersion: number;
+    chunkSizeBytes: number;
+    snapshotFilename: string;
+    snapshotHeight: number;
+    snapshotSizeBytes: number;
+    snapshotSha256: string;
+    chunkSha256s: string[];
+}
 export interface WritingQuote {
     quote: string;
     author: string;

package/dist/cli/output.js

@@ -335,7 +335,7 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
         return {
             what: "Mnemonic confirmation failed.",
             why: "The requested recovery-phrase confirmation word did not match, so wallet initialization was canceled before it could finish.",
-            next: "Run `cogcoin init` again and re-enter the requested confirmation words carefully.",
+            next: "Run `cogcoin init` again and re-enter the requested confirmation words carefully. The same recovery phrase will be shown until confirmation succeeds.",
         };
     }
     if (errorCode === "wallet_restore_mnemonic_invalid") {

package/dist/wallet/lifecycle.js

@@ -19,8 +19,9 @@ import { loadMiningRuntimeStatus, saveMiningRuntimeStatus } from "./mining/runti
 import { normalizeMiningStateRecord } from "./mining/state.js";
 import { renderWalletMnemonicRevealArt } from "./mnemonic-art.js";
 import { clearWalletExplicitLock, loadWalletExplicitLock, saveWalletExplicitLock, } from "./state/explicit-lock.js";
+import { clearWalletPendingInitializationState, loadWalletPendingInitializationStateOrNull, saveWalletPendingInitializationState, } from "./state/pending-init.js";
 import { clearUnlockSession, loadUnlockSession, saveUnlockSession } from "./state/session.js";
-import { createDefaultWalletSecretProvider, createWalletRootId, createWalletSecretReference, } from "./state/provider.js";
+import { createDefaultWalletSecretProvider, createWalletPendingInitSecretReference, createWalletRootId, createWalletSecretReference, } from "./state/provider.js";
 import { loadWalletState, saveWalletState } from "./state/storage.js";
 export const DEFAULT_UNLOCK_DURATION_MS = 15 * 60 * 1000;
 export { previewResetWallet, resetWallet, } from "./reset.js";
@@ -62,6 +63,53 @@ function extractWalletRootIdFromEnvelope(envelope) {
     }
     return keyId.slice(prefix.length);
 }
+function resolvePendingInitializationStoragePaths(paths) {
+    return {
+        primaryPath: paths.walletInitPendingPath,
+        backupPath: paths.walletInitPendingBackupPath,
+    };
+}
+async function clearPendingInitialization(paths, provider) {
+    await clearWalletPendingInitializationState(resolvePendingInitializationStoragePaths(paths), {
+        provider,
+        secretReference: createWalletPendingInitSecretReference(paths.stateRoot),
+    });
+}
+async function loadOrCreatePendingInitializationMaterial(options) {
+    try {
+        const loaded = await loadWalletPendingInitializationStateOrNull(resolvePendingInitializationStoragePaths(options.paths), {
+            provider: options.provider,
+        });
+        if (loaded !== null) {
+            return deriveWalletMaterialFromMnemonic(loaded.state.mnemonic.phrase);
+        }
+    }
+    catch {
+        await clearPendingInitialization(options.paths, options.provider);
+    }
+    const material = generateWalletMaterial();
+    const secretReference = createWalletPendingInitSecretReference(options.paths.stateRoot);
+    const pendingState = {
+        schemaVersion: 1,
+        createdAtUnixMs: options.nowUnixMs,
+        mnemonic: {
+            phrase: material.mnemonic.phrase,
+            language: material.mnemonic.language,
+        },
+    };
+    await options.provider.storeSecret(secretReference.keyId, randomBytes(32));
+    try {
+        await saveWalletPendingInitializationState(resolvePendingInitializationStoragePaths(options.paths), pendingState, {
+            provider: options.provider,
+            secretReference,
+        });
+    }
+    catch (error) {
+        await options.provider.deleteSecret(secretReference.keyId).catch(() => undefined);
+        throw error;
+    }
+    return material;
+}
 function createInitialWalletState(options) {
     return {
         schemaVersion: 1,
@@ -780,8 +828,9 @@ export function parseUnlockDurationToMs(raw) {
     }
     return duration;
 }
-async function ensureWalletNotInitialized(paths) {
+async function ensureWalletNotInitialized(paths, provider) {
     if (await pathExists(paths.walletStatePath) || await pathExists(paths.walletStateBackupPath)) {
+        await clearPendingInitialization(paths, provider);
         throw new Error("wallet_already_initialized");
     }
 }
@@ -1079,11 +1128,16 @@ export async function initializeWallet(options) {
         walletRootId: null,
     });
     try {
-        await ensureWalletNotInitialized(paths);
-        const material = generateWalletMaterial();
+        await ensureWalletNotInitialized(paths, provider);
+        const material = await loadOrCreatePendingInitializationMaterial({
+            provider,
+            paths,
+            nowUnixMs,
+        });
         let mnemonicRevealed = false;
         options.prompter.writeLine("Cogcoin Wallet Initialization");
-        options.prompter.writeLine("Write down this 24-word recovery phrase. It will only be shown once:");
+        options.prompter.writeLine("Write down this 24-word recovery phrase.");
+        options.prompter.writeLine("The same phrase will be shown again until confirmation succeeds:");
         options.prompter.writeLine("");
         for (const line of renderWalletMnemonicRevealArt(material.mnemonic.words)) {
             options.prompter.writeLine(line);
@@ -1126,6 +1180,7 @@ export async function initializeWallet(options) {
             provider,
             secretReference,
         });
+        await clearPendingInitialization(paths, provider);
         return {
             walletRootId,
             fundingAddress: verifiedState.funding.address,
@@ -1290,6 +1345,7 @@ export async function importWallet(options) {
         const replacementStateExists = await pathExists(paths.walletStatePath) || await pathExists(paths.walletStateBackupPath);
         const importedWalletDir = join(options.dataDir, "wallets", sanitizeWalletName(payload.walletRootId));
         const replacementCoreWalletExists = await pathExists(importedWalletDir);
+        await clearPendingInitialization(paths, provider);
         if (replacementStateExists || replacementCoreWalletExists) {
             await confirmTypedAcknowledgement(options.prompter, "IMPORT", "Type IMPORT to replace the existing local wallet state and managed Core wallet replica: ");
         }
@@ -1333,6 +1389,7 @@ export async function importWallet(options) {
             provider,
             secretReference,
         });
+        await clearPendingInitialization(paths, provider);
         if (previousWalletRootId !== null && previousWalletRootId !== payload.walletRootId) {
             await provider.deleteSecret(createWalletSecretReference(previousWalletRootId).keyId).catch(() => undefined);
         }
@@ -1372,6 +1429,7 @@ export async function restoreWalletFromMnemonic(options) {
             || await pathExists(paths.walletStateBackupPath);
         const replacementCoreWalletExists = await detectExistingManagedWalletReplica(options.dataDir);
         const mnemonicPhrase = await promptForRestoreMnemonic(options.prompter);
+        await clearPendingInitialization(paths, provider);
         if (replacementStateExists || replacementCoreWalletExists) {
             await confirmRestoreReplacement(options.prompter);
         }
@@ -1425,6 +1483,7 @@ export async function restoreWalletFromMnemonic(options) {
                 provider,
                 secretReference,
             });
+            await clearPendingInitialization(paths, provider);
             if (previousWalletRootId !== null && previousWalletRootId !== walletRootId) {
                 try {
                     await clearPreviousManagedWalletRuntime({

package/dist/wallet/runtime.d.ts

@@ -9,6 +9,8 @@ export interface WalletRuntimePaths {
     indexerRoot: string;
     walletStatePath: string;
     walletStateBackupPath: string;
+    walletInitPendingPath: string;
+    walletInitPendingBackupPath: string;
     walletUnlockSessionPath: string;
     walletExplicitLockPath: string;
     walletControlLockPath: string;

package/dist/wallet/runtime.js

@@ -11,6 +11,8 @@ export function resolveWalletRuntimePathsForTesting(resolution = {}) {
         indexerRoot: paths.indexerRoot,
         walletStatePath: paths.walletStatePath,
         walletStateBackupPath: paths.walletStateBackupPath,
+        walletInitPendingPath: paths.walletInitPendingPath,
+        walletInitPendingBackupPath: paths.walletInitPendingBackupPath,
         walletUnlockSessionPath: paths.walletUnlockSessionPath,
         walletExplicitLockPath: paths.walletExplicitLockPath,
         walletControlLockPath: paths.walletControlLockPath,

package/dist/wallet/state/pending-init.d.ts

@@ -0,0 +1,24 @@
+import type { WalletPendingInitializationStateV1 } from "../types.js";
+import type { WalletSecretProvider, WalletSecretReference } from "./provider.js";
+export interface WalletPendingInitializationStoragePaths {
+    primaryPath: string;
+    backupPath: string;
+}
+export interface LoadedWalletPendingInitializationState {
+    source: "primary" | "backup";
+    state: WalletPendingInitializationStateV1;
+}
+export declare function saveWalletPendingInitializationState(paths: WalletPendingInitializationStoragePaths, state: WalletPendingInitializationStateV1, access: {
+    provider: WalletSecretProvider;
+    secretReference: WalletSecretReference;
+}): Promise<void>;
+export declare function loadWalletPendingInitializationState(paths: WalletPendingInitializationStoragePaths, access: {
+    provider: WalletSecretProvider;
+}): Promise<LoadedWalletPendingInitializationState>;
+export declare function loadWalletPendingInitializationStateOrNull(paths: WalletPendingInitializationStoragePaths, access: {
+    provider: WalletSecretProvider;
+}): Promise<LoadedWalletPendingInitializationState | null>;
+export declare function clearWalletPendingInitializationState(paths: WalletPendingInitializationStoragePaths, access?: {
+    provider?: WalletSecretProvider;
+    secretReference?: WalletSecretReference;
+}): Promise<void>;

package/dist/wallet/state/pending-init.js

@@ -0,0 +1,59 @@
+import { readFile, rm } from "node:fs/promises";
+import { writeJsonFileAtomic } from "../fs/atomic.js";
+import { decryptJsonWithSecretProvider, encryptJsonWithSecretProvider, } from "./crypto.js";
+function isMissingFileError(error) {
+    return error instanceof Error
+        && "code" in error
+        && error.code === "ENOENT";
+}
+async function readEnvelope(path) {
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw);
+}
+async function loadFromPath(path, source, provider) {
+    return {
+        source,
+        state: await decryptJsonWithSecretProvider(await readEnvelope(path), provider),
+    };
+}
+export async function saveWalletPendingInitializationState(paths, state, access) {
+    const envelope = await encryptJsonWithSecretProvider(state, access.provider, access.secretReference, {
+        format: "cogcoin-wallet-init-pending-state",
+    });
+    await writeJsonFileAtomic(paths.primaryPath, envelope, { mode: 0o600 });
+    await writeJsonFileAtomic(paths.backupPath, envelope, { mode: 0o600 });
+}
+export async function loadWalletPendingInitializationState(paths, access) {
+    try {
+        return await loadFromPath(paths.primaryPath, "primary", access.provider);
+    }
+    catch (primaryError) {
+        try {
+            return await loadFromPath(paths.backupPath, "backup", access.provider);
+        }
+        catch (backupError) {
+            if (isMissingFileError(primaryError)) {
+                throw backupError;
+            }
+            throw primaryError;
+        }
+    }
+}
+export async function loadWalletPendingInitializationStateOrNull(paths, access) {
+    try {
+        return await loadWalletPendingInitializationState(paths, access);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function clearWalletPendingInitializationState(paths, access) {
+    await rm(paths.primaryPath, { force: true }).catch(() => undefined);
+    await rm(paths.backupPath, { force: true }).catch(() => undefined);
+    if (access?.provider != null && access.secretReference != null) {
+        await access.provider.deleteSecret(access.secretReference.keyId).catch(() => undefined);
+    }
+}

package/dist/wallet/state/provider.d.ts

@@ -23,6 +23,7 @@ export interface WalletSecretProvider {
     deleteSecret(keyId: string): Promise<void>;
 }
 export declare function createWalletSecretReference(walletRootId: string): WalletSecretReference;
+export declare function createWalletPendingInitSecretReference(stateRoot: string): WalletSecretReference;
 export declare class MemoryWalletSecretProvider implements WalletSecretProvider {
     #private;
     readonly kind = "memory-test";

package/dist/wallet/state/provider.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { execFile, spawn } from "node:child_process";
 import { mkdir, readFile, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -17,6 +17,12 @@ export function createWalletSecretReference(walletRootId) {
         keyId: `wallet-state:${walletRootId}`,
     };
 }
+export function createWalletPendingInitSecretReference(stateRoot) {
+    return {
+        kind: "wallet-init-pending-key",
+        keyId: `wallet-init-pending:${createHash("sha256").update(stateRoot).digest("hex")}`,
+    };
+}
 function bytesToBase64(secret) {
     return Buffer.from(secret).toString("base64");
 }

package/dist/wallet/types.d.ts

@@ -252,3 +252,11 @@ export interface WalletExplicitLockStateV1 {
     walletRootId: string;
     lockedAtUnixMs: number;
 }
+export interface WalletPendingInitializationStateV1 {
+    schemaVersion: 1;
+    createdAtUnixMs: number;
+    mnemonic: {
+        phrase: string;
+        language: WalletMnemonicLanguage;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogcoin/client",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "Store-backed Cogcoin client with wallet flows, SQLite persistence, and managed Bitcoin Core integration.",
   "license": "MIT",
   "type": "module",
@@ -53,10 +53,12 @@
   "files": [
     "LICENSE",
     "README.md",
-    "dist/**/*"
+    "dist"
   ],
   "scripts": {
     "build": "rm -rf dist && node ./node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"import('node:fs/promises').then(async (fs) => { await fs.mkdir('dist/art', { recursive: true }); await Promise.all([fs.copyFile('src/writing_quotes.json', 'dist/writing_quotes.json'), fs.copyFile('src/art/banner.txt', 'dist/art/banner.txt'), fs.copyFile('src/art/scroll.txt', 'dist/art/scroll.txt'), fs.copyFile('src/art/train-smoke.txt', 'dist/art/train-smoke.txt'), fs.copyFile('src/art/train.txt', 'dist/art/train.txt'), fs.copyFile('src/art/train-car.txt', 'dist/art/train-car.txt'), fs.copyFile('src/art/wallet.txt', 'dist/art/wallet.txt')]); })\"",
+    "generate:default-snapshot-chunk-manifest": "node scripts/generate-default-snapshot-chunk-manifest.mjs",
+    "verify:default-snapshot-chunk-manifest": "node scripts/generate-default-snapshot-chunk-manifest.mjs --check",
     "test": "rm -rf .test-dist && node ./node_modules/typescript/bin/tsc -p tsconfig.test.json && node -e \"import('node:fs/promises').then(async (fs) => { await fs.mkdir('.test-dist/src/art', { recursive: true }); await Promise.all([fs.copyFile('src/writing_quotes.json', '.test-dist/src/writing_quotes.json'), fs.copyFile('src/art/banner.txt', '.test-dist/src/art/banner.txt'), fs.copyFile('src/art/scroll.txt', '.test-dist/src/art/scroll.txt'), fs.copyFile('src/art/train-smoke.txt', '.test-dist/src/art/train-smoke.txt'), fs.copyFile('src/art/train.txt', '.test-dist/src/art/train.txt'), fs.copyFile('src/art/train-car.txt', '.test-dist/src/art/train-car.txt'), fs.copyFile('src/art/wallet.txt', '.test-dist/src/art/wallet.txt')]); })\" && node --test .test-dist/test/*.test.js"
   },
   "dependencies": {