@cogcoin/client 1.1.4 → 1.1.5

package/dist/wallet/lifecycle/repair-mining.js

@@ -0,0 +1,304 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { readLockMetadata } from "../fs/lock.js";
+import { readMiningGenerationActivity } from "../mining/coordination.js";
+import { loadClientConfig } from "../mining/config.js";
+import { saveMiningRuntimeStatus } from "../mining/runtime-artifacts.js";
+import { normalizeMiningStateRecord } from "../mining/state.js";
+import { createWalletSecretReference } from "../state/provider.js";
+import { persistWalletStateUpdate } from "../descriptor-normalization.js";
+import { isProcessAlive, stopRecordedManagedProcess } from "./repair-runtime.js";
+export function createSilentNonInteractivePrompter() {
+    return {
+        isInteractive: false,
+        writeLine() { },
+        async prompt() {
+            return "";
+        },
+    };
+}
+export function applyRepairStoppedMiningState(state) {
+    const miningState = normalizeMiningStateRecord(state.miningState);
+    return {
+        ...state,
+        miningState: {
+            ...miningState,
+            runMode: "stopped",
+            state: miningState.livePublishInMempool
+                ? miningState.state === "paused-stale"
+                    ? "paused-stale"
+                    : "paused"
+                : miningState.state === "repair-required"
+                    ? "repair-required"
+                    : "idle",
+            pauseReason: miningState.livePublishInMempool
+                ? miningState.state === "paused-stale"
+                    ? "stale-block-context"
+                    : "wallet-repair"
+                : miningState.state === "repair-required"
+                    ? miningState.pauseReason
+                    : null,
+        },
+    };
+}
+function createStoppedBackgroundRuntimeSnapshot(snapshot, nowUnixMs) {
+    return {
+        ...snapshot,
+        updatedAtUnixMs: nowUnixMs,
+        runMode: "stopped",
+        backgroundWorkerPid: null,
+        backgroundWorkerRunId: null,
+        backgroundWorkerHeartbeatAtUnixMs: null,
+        backgroundWorkerHealth: null,
+        currentPhase: "idle",
+        note: snapshot.livePublishInMempool
+            ? "Background mining stopped for wallet repair. The last mining transaction may still confirm from mempool."
+            : "Background mining stopped for wallet repair.",
+    };
+}
+function resolveMiningGenerationRequestPath(paths) {
+    return join(paths.miningRoot, "generation-request.json");
+}
+function resolveMiningGenerationActivityPath(paths) {
+    return join(paths.miningRoot, "generation-activity.json");
+}
+function normalizeRepairMiningPid(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0
+        ? value
+        : null;
+}
+function createRepairStoppedMiningNote(livePublishInMempool) {
+    return livePublishInMempool
+        ? "Background mining stopped for wallet repair. The last mining transaction may still confirm from mempool."
+        : "Background mining stopped for wallet repair.";
+}
+export function createStoppedMiningRuntimeSnapshotForRepair(options) {
+    const stoppedMiningState = normalizeMiningStateRecord(applyRepairStoppedMiningState(options.state).miningState);
+    const note = createRepairStoppedMiningNote(stoppedMiningState.livePublishInMempool);
+    if (options.snapshot !== null) {
+        return {
+            ...createStoppedBackgroundRuntimeSnapshot(options.snapshot, options.nowUnixMs),
+            miningState: stoppedMiningState.state,
+            currentPublishState: stoppedMiningState.currentPublishState,
+            targetBlockHeight: stoppedMiningState.currentBlockTargetHeight,
+            referencedBlockHashDisplay: stoppedMiningState.currentReferencedBlockHashDisplay,
+            currentDomainId: stoppedMiningState.currentDomainId,
+            currentDomainName: stoppedMiningState.currentDomain,
+            currentSentenceDisplay: stoppedMiningState.currentSentence,
+            currentTxid: stoppedMiningState.currentTxid,
+            currentWtxid: stoppedMiningState.currentWtxid,
+            livePublishInMempool: stoppedMiningState.livePublishInMempool,
+            currentFeeRateSatVb: stoppedMiningState.currentFeeRateSatVb,
+            currentAbsoluteFeeSats: stoppedMiningState.currentAbsoluteFeeSats,
+            currentBlockFeeSpentSats: stoppedMiningState.currentBlockFeeSpentSats,
+            sessionFeeSpentSats: stoppedMiningState.sessionFeeSpentSats,
+            lifetimeFeeSpentSats: stoppedMiningState.lifetimeFeeSpentSats,
+            currentPublishDecision: stoppedMiningState.currentPublishDecision,
+            pauseReason: stoppedMiningState.pauseReason,
+            note,
+        };
+    }
+    return {
+        schemaVersion: 1,
+        walletRootId: options.state.walletRootId,
+        workerApiVersion: null,
+        workerBinaryVersion: null,
+        workerBuildId: null,
+        updatedAtUnixMs: options.nowUnixMs,
+        runMode: "stopped",
+        backgroundWorkerPid: null,
+        backgroundWorkerRunId: null,
+        backgroundWorkerHeartbeatAtUnixMs: null,
+        backgroundWorkerHealth: null,
+        indexerDaemonState: null,
+        indexerDaemonInstanceId: null,
+        indexerSnapshotSeq: null,
+        indexerSnapshotOpenedAtUnixMs: null,
+        indexerTruthSource: undefined,
+        indexerHeartbeatAtUnixMs: null,
+        coreBestHeight: null,
+        coreBestHash: null,
+        indexerTipHeight: null,
+        indexerTipHash: null,
+        indexerReorgDepth: null,
+        indexerTipAligned: null,
+        corePublishState: null,
+        providerState: null,
+        lastSuspendDetectedAtUnixMs: null,
+        reconnectSettledUntilUnixMs: null,
+        tipSettledUntilUnixMs: null,
+        miningState: stoppedMiningState.state,
+        currentPhase: "idle",
+        currentPublishState: stoppedMiningState.currentPublishState,
+        targetBlockHeight: stoppedMiningState.currentBlockTargetHeight,
+        referencedBlockHashDisplay: stoppedMiningState.currentReferencedBlockHashDisplay,
+        currentDomainId: stoppedMiningState.currentDomainId,
+        currentDomainName: stoppedMiningState.currentDomain,
+        currentSentenceDisplay: stoppedMiningState.currentSentence,
+        currentCanonicalBlend: null,
+        currentTxid: stoppedMiningState.currentTxid,
+        currentWtxid: stoppedMiningState.currentWtxid,
+        livePublishInMempool: stoppedMiningState.livePublishInMempool,
+        currentFeeRateSatVb: stoppedMiningState.currentFeeRateSatVb,
+        currentAbsoluteFeeSats: stoppedMiningState.currentAbsoluteFeeSats,
+        currentBlockFeeSpentSats: stoppedMiningState.currentBlockFeeSpentSats,
+        sessionFeeSpentSats: stoppedMiningState.sessionFeeSpentSats,
+        lifetimeFeeSpentSats: stoppedMiningState.lifetimeFeeSpentSats,
+        sameDomainCompetitorSuppressed: null,
+        higherRankedCompetitorDomainCount: null,
+        dedupedCompetitorDomainCount: null,
+        competitivenessGateIndeterminate: null,
+        mempoolSequenceCacheStatus: null,
+        currentPublishDecision: stoppedMiningState.currentPublishDecision,
+        lastMempoolSequence: null,
+        lastCompetitivenessGateAtUnixMs: null,
+        pauseReason: stoppedMiningState.pauseReason,
+        providerConfigured: false,
+        providerKind: null,
+        bitcoindHealth: "unavailable",
+        bitcoindServiceState: null,
+        bitcoindReplicaStatus: null,
+        nodeHealth: "unavailable",
+        indexerHealth: "unavailable",
+        tipsAligned: null,
+        lastEventAtUnixMs: null,
+        lastError: null,
+        note,
+    };
+}
+export async function persistRepairState(options) {
+    return await persistWalletStateUpdate({
+        state: options.state,
+        access: {
+            provider: options.provider,
+            secretReference: createWalletSecretReference(options.state.walletRootId),
+        },
+        paths: options.paths,
+        nowUnixMs: options.nowUnixMs,
+        replacePrimary: options.replacePrimary,
+    });
+}
+export async function cleanupMiningForRepair(options) {
+    const controlLockMetadata = await readLockMetadata(options.paths.miningControlLockPath).catch(() => null);
+    const generationActivity = await readMiningGenerationActivity(options.paths).catch(() => null);
+    const controlLockPid = normalizeRepairMiningPid(controlLockMetadata?.processId);
+    const backgroundWorkerPid = normalizeRepairMiningPid(options.snapshot?.backgroundWorkerPid);
+    const generationOwnerPid = normalizeRepairMiningPid(generationActivity?.generationOwnerPid);
+    const discoveredPids = new Set();
+    let backgroundWorkerAlive = false;
+    let foregroundWorkerAlive = false;
+    const pidSources = [
+        { pid: backgroundWorkerPid, source: "background" },
+        { pid: controlLockPid, source: "foreground" },
+        { pid: generationOwnerPid, source: "foreground" },
+    ];
+    for (const source of pidSources) {
+        if (source.pid === null || source.pid === process.pid || !await isProcessAlive(source.pid)) {
+            continue;
+        }
+        discoveredPids.add(source.pid);
+        if (source.source === "background") {
+            backgroundWorkerAlive = true;
+        }
+        else {
+            foregroundWorkerAlive = true;
+        }
+    }
+    for (const pid of discoveredPids) {
+        await stopRecordedManagedProcess(pid, "mining_process_stop_timeout");
+    }
+    await rm(options.paths.miningControlLockPath, { force: true }).catch(() => undefined);
+    await rm(resolveMiningGenerationRequestPath(options.paths), { force: true }).catch(() => undefined);
+    await rm(resolveMiningGenerationActivityPath(options.paths), { force: true }).catch(() => undefined);
+    await saveMiningRuntimeStatus(options.paths.miningStatusPath, createStoppedMiningRuntimeSnapshotForRepair({
+        state: options.state,
+        snapshot: options.snapshot,
+        nowUnixMs: options.nowUnixMs,
+    }));
+    return {
+        preRepairRunMode: backgroundWorkerAlive
+            ? "background"
+            : foregroundWorkerAlive
+                ? "foreground"
+                : "stopped",
+    };
+}
+export async function canResumeBackgroundMiningAfterRepair(options) {
+    if (options.bitcoindPostRepairHealth !== "ready"
+        || options.indexerPostRepairHealth !== "synced"
+        || normalizeMiningStateRecord(options.repairedState.miningState).state === "repair-required") {
+        return false;
+    }
+    try {
+        const config = await loadClientConfig({
+            path: options.paths.clientConfigPath,
+            provider: options.provider,
+        });
+        return config?.mining.builtIn != null;
+    }
+    catch {
+        return false;
+    }
+}
+export async function resumeBackgroundMiningAfterRepair(options) {
+    const miningWasResumable = options.miningPreRepairRunMode === "background"
+        && normalizeMiningStateRecord(options.repairedState.miningState).state !== "repair-required";
+    if (options.miningPreRepairRunMode !== "background") {
+        return {
+            miningResumeAction: "none",
+            miningPostRepairRunMode: "stopped",
+            miningResumeError: null,
+        };
+    }
+    if (!miningWasResumable) {
+        return {
+            miningResumeAction: "skipped-not-resumable",
+            miningPostRepairRunMode: "stopped",
+            miningResumeError: null,
+        };
+    }
+    const postRepairResumeReady = await canResumeBackgroundMiningAfterRepair({
+        provider: options.provider,
+        paths: options.paths,
+        repairedState: options.repairedState,
+        bitcoindPostRepairHealth: options.bitcoindPostRepairHealth,
+        indexerPostRepairHealth: options.indexerPostRepairHealth,
+    });
+    if (!postRepairResumeReady) {
+        return {
+            miningResumeAction: "skipped-post-repair-blocked",
+            miningPostRepairRunMode: "stopped",
+            miningResumeError: null,
+        };
+    }
+    try {
+        const startBackgroundMining = options.startBackgroundMining
+            ?? (await import("../mining/runner.js")).startBackgroundMining;
+        const resumed = await startBackgroundMining({
+            dataDir: options.dataDir,
+            databasePath: options.databasePath,
+            provider: options.provider,
+            paths: options.paths,
+            prompter: createSilentNonInteractivePrompter(),
+        });
+        if (resumed.snapshot?.runMode === "background") {
+            return {
+                miningResumeAction: "resumed-background",
+                miningPostRepairRunMode: "background",
+                miningResumeError: null,
+            };
+        }
+        return {
+            miningResumeAction: "resume-failed",
+            miningPostRepairRunMode: "stopped",
+            miningResumeError: "Background mining did not report a background runtime after repair.",
+        };
+    }
+    catch (error) {
+        return {
+            miningResumeAction: "resume-failed",
+            miningPostRepairRunMode: "stopped",
+            miningResumeError: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/wallet/lifecycle/repair-runtime.d.ts

@@ -0,0 +1,36 @@
+import { attachOrStartIndexerDaemon, probeIndexerDaemon } from "../../bitcoind/indexer-daemon.js";
+import { probeManagedBitcoindService } from "../../bitcoind/service.js";
+import { resolveManagedServicePaths } from "../../bitcoind/service-paths.js";
+import type { ManagedBitcoindServiceStatus } from "../../bitcoind/types.js";
+import type { WalletRepairResult } from "./types.js";
+export declare function ensureIndexerDatabaseHealthy(options: {
+    databasePath: string;
+    dataDir: string;
+    walletRootId: string;
+    resetIfNeeded: boolean;
+}): Promise<boolean>;
+export declare function mapIndexerCompatibilityToRepairIssue(compatibility: Awaited<ReturnType<typeof probeIndexerDaemon>>["compatibility"]): WalletRepairResult["indexerCompatibilityIssue"];
+export declare function mapBitcoindCompatibilityToRepairIssue(compatibility: Awaited<ReturnType<typeof probeManagedBitcoindService>>["compatibility"]): WalletRepairResult["bitcoindCompatibilityIssue"];
+export declare function mapBitcoindRepairHealth(options: {
+    serviceState: ManagedBitcoindServiceStatus["state"] | null;
+    catchingUp: boolean;
+    replica: {
+        proofStatus?: "missing" | "mismatch" | "ready" | "not-proven";
+    } | null;
+}): WalletRepairResult["bitcoindPostRepairHealth"];
+export declare function verifyIndexerPostRepairHealth(options: {
+    daemon: Awaited<ReturnType<typeof attachOrStartIndexerDaemon>>;
+    probeIndexerDaemon: typeof probeIndexerDaemon;
+    dataDir: string;
+    walletRootId: string;
+    nowUnixMs: number;
+}): Promise<{
+    health: WalletRepairResult["indexerPostRepairHealth"];
+    daemonInstanceId: string;
+}>;
+export declare function isProcessAlive(pid: number | null): Promise<boolean>;
+export declare function waitForProcessExit(pid: number, timeoutMs?: number, errorCode?: string): Promise<void>;
+export declare function clearIndexerDaemonArtifacts(servicePaths: ReturnType<typeof resolveManagedServicePaths>): Promise<void>;
+export declare function clearManagedBitcoindArtifacts(servicePaths: ReturnType<typeof resolveManagedServicePaths>): Promise<void>;
+export declare function stopRecordedManagedProcess(pid: number | null, errorCode: string): Promise<void>;
+export declare function clearOrphanedRepairLocks(lockPaths: readonly string[]): Promise<void>;

package/dist/wallet/lifecycle/repair-runtime.js

@@ -0,0 +1,206 @@
+import { access, constants, mkdir, readFile, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import { attachOrStartIndexerDaemon, probeIndexerDaemon, readSnapshotWithRetry, } from "../../bitcoind/indexer-daemon.js";
+import { probeManagedBitcoindService } from "../../bitcoind/service.js";
+import { resolveManagedServicePaths } from "../../bitcoind/service-paths.js";
+import { openClient } from "../../client.js";
+import { openSqliteStore } from "../../sqlite/index.js";
+import { clearOrphanedFileLock } from "../fs/lock.js";
+async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensureIndexerDatabaseHealthy(options) {
+    try {
+        if (await pathExists(options.databasePath)) {
+            const header = await readFile(options.databasePath).then((buffer) => buffer.subarray(0, 16).toString("utf8"));
+            if (header.length > 0 && header !== "SQLite format 3\u0000") {
+                throw new Error("indexer_database_not_sqlite");
+            }
+        }
+        const store = await openSqliteStore({ filename: options.databasePath });
+        try {
+            const client = await openClient({ store });
+            try {
+                await client.getTip();
+            }
+            finally {
+                await client.close();
+            }
+        }
+        finally {
+            await store.close();
+        }
+        return false;
+    }
+    catch {
+        if (!options.resetIfNeeded) {
+            throw new Error("wallet_repair_indexer_reset_requires_yes");
+        }
+        await rm(options.databasePath, { force: true }).catch(() => undefined);
+        await rm(`${options.databasePath}-wal`, { force: true }).catch(() => undefined);
+        await rm(`${options.databasePath}-shm`, { force: true }).catch(() => undefined);
+        await mkdir(dirname(options.databasePath), { recursive: true });
+        return true;
+    }
+}
+export function mapIndexerCompatibilityToRepairIssue(compatibility) {
+    switch (compatibility) {
+        case "service-version-mismatch":
+            return "service-version-mismatch";
+        case "wallet-root-mismatch":
+            return "wallet-root-mismatch";
+        case "schema-mismatch":
+            return "schema-mismatch";
+        default:
+            return "none";
+    }
+}
+export function mapBitcoindCompatibilityToRepairIssue(compatibility) {
+    switch (compatibility) {
+        case "service-version-mismatch":
+            return "service-version-mismatch";
+        case "wallet-root-mismatch":
+            return "wallet-root-mismatch";
+        case "runtime-mismatch":
+            return "runtime-mismatch";
+        default:
+            return "none";
+    }
+}
+export function mapBitcoindRepairHealth(options) {
+    if (options.serviceState === null) {
+        return "unavailable";
+    }
+    if (options.serviceState === "starting" || options.serviceState === "stopping") {
+        return "starting";
+    }
+    if (options.serviceState !== "ready") {
+        return "failed";
+    }
+    if (options.replica?.proofStatus === "missing" || options.replica?.proofStatus === "mismatch") {
+        return "failed";
+    }
+    if (options.catchingUp) {
+        return "catching-up";
+    }
+    return "ready";
+}
+function mapLeaseStateToRepairHealth(state) {
+    switch (state) {
+        case "synced":
+            return "synced";
+        case "catching-up":
+        case "reorging":
+            return "catching-up";
+        case "starting":
+        case "stopping":
+            return "starting";
+        default:
+            return "failed";
+    }
+}
+const INDEXER_DAEMON_HEARTBEAT_STALE_MS = 15_000;
+export async function verifyIndexerPostRepairHealth(options) {
+    try {
+        const lease = await readSnapshotWithRetry(options.daemon, options.walletRootId);
+        return {
+            health: mapLeaseStateToRepairHealth(lease.status.state),
+            daemonInstanceId: lease.status.daemonInstanceId,
+        };
+    }
+    catch (leaseError) {
+        const probe = await options.probeIndexerDaemon({
+            dataDir: options.dataDir,
+            walletRootId: options.walletRootId,
+        });
+        try {
+            if (probe.compatibility === "compatible"
+                && probe.status !== null
+                && (options.nowUnixMs - probe.status.heartbeatAtUnixMs) <= INDEXER_DAEMON_HEARTBEAT_STALE_MS
+                && (probe.status.state === "starting" || probe.status.state === "catching-up" || probe.status.state === "reorging")) {
+                return {
+                    health: mapLeaseStateToRepairHealth(probe.status.state),
+                    daemonInstanceId: probe.status.daemonInstanceId,
+                };
+            }
+        }
+        finally {
+            await probe.client?.close().catch(() => undefined);
+        }
+        throw leaseError;
+    }
+}
+export async function isProcessAlive(pid) {
+    if (pid === null) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+            return false;
+        }
+        return true;
+    }
+}
+export async function waitForProcessExit(pid, timeoutMs = 15_000, errorCode = "indexer_daemon_stop_timeout") {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!await isProcessAlive(pid)) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error(errorCode);
+}
+export async function clearIndexerDaemonArtifacts(servicePaths) {
+    await rm(servicePaths.indexerDaemonStatusPath, { force: true }).catch(() => undefined);
+    await rm(servicePaths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
+}
+export async function clearManagedBitcoindArtifacts(servicePaths) {
+    await rm(servicePaths.bitcoindStatusPath, { force: true }).catch(() => undefined);
+    await rm(servicePaths.bitcoindPidPath, { force: true }).catch(() => undefined);
+    await rm(servicePaths.bitcoindReadyPath, { force: true }).catch(() => undefined);
+    await rm(servicePaths.bitcoindWalletStatusPath, { force: true }).catch(() => undefined);
+}
+export async function stopRecordedManagedProcess(pid, errorCode) {
+    if (pid === null || !await isProcessAlive(pid)) {
+        return;
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+            throw error;
+        }
+    }
+    try {
+        await waitForProcessExit(pid, 5_000, errorCode);
+        return;
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+                throw error;
+            }
+        }
+    }
+    await waitForProcessExit(pid, 5_000, errorCode);
+}
+export async function clearOrphanedRepairLocks(lockPaths) {
+    for (const lockPath of lockPaths) {
+        await clearOrphanedFileLock(lockPath, isProcessAlive);
+    }
+}

package/dist/wallet/lifecycle/repair.d.ts

@@ -0,0 +1,11 @@
+import { type WalletRuntimePaths } from "../runtime.js";
+import { type WalletSecretProvider } from "../state/provider.js";
+import type { WalletRepairDependencies, WalletRepairResult } from "./types.js";
+export declare function repairWallet(options: {
+    dataDir: string;
+    databasePath: string;
+    provider?: WalletSecretProvider;
+    assumeYes?: boolean;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+} & WalletRepairDependencies): Promise<WalletRepairResult>;