@cogcoin/client 1.1.5 → 1.1.6

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

@@ -0,0 +1,26 @@
+import { type WalletRuntimePaths } from "../runtime.js";
+import { type WalletSecretProvider } from "../state/provider.js";
+import type { WalletManagedCoreContext, WalletManagedCoreDependencies, WalletPrompter, WalletRepairContext, WalletRepairDependencies, WalletSetupContext, WalletSetupDependencies } from "./types.js";
+export declare function pathExists(path: string): Promise<boolean>;
+export declare function walletStateExists(paths: WalletRuntimePaths): Promise<boolean>;
+export declare function resolveWalletManagedCoreContext(options: {
+    provider?: WalletSecretProvider;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+} & WalletManagedCoreDependencies): WalletManagedCoreContext;
+export declare function resolveWalletSetupContext(options: {
+    dataDir: string;
+    prompter: WalletPrompter;
+    provider?: WalletSecretProvider;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+} & WalletSetupDependencies): WalletSetupContext;
+export declare function resolveWalletRepairContext(options: {
+    dataDir: string;
+    databasePath: string;
+    provider?: WalletSecretProvider;
+    assumeYes?: boolean;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+} & WalletRepairDependencies): WalletRepairContext;
+export declare function acquireWalletControlLock(paths: WalletRuntimePaths, purpose: "wallet-init" | "wallet-show-mnemonic" | "wallet-repair"): Promise<import("../fs/lock.js").FileLockHandle>;

package/dist/wallet/lifecycle/context.js

@@ -0,0 +1,58 @@
+import { access, constants } from "node:fs/promises";
+import { attachOrStartIndexerDaemon, probeIndexerDaemon, } from "../../bitcoind/indexer-daemon.js";
+import { createRpcClient } from "../../bitcoind/node.js";
+import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, } from "../../bitcoind/service.js";
+import { acquireFileLock } from "../fs/lock.js";
+import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
+import { createDefaultWalletSecretProvider, } from "../state/provider.js";
+export async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function walletStateExists(paths) {
+    const [hasPrimaryState, hasBackupState] = await Promise.all([
+        pathExists(paths.walletStatePath),
+        pathExists(paths.walletStateBackupPath),
+    ]);
+    return hasPrimaryState || hasBackupState;
+}
+export function resolveWalletManagedCoreContext(options) {
+    return {
+        provider: options.provider ?? createDefaultWalletSecretProvider(),
+        paths: options.paths ?? resolveWalletRuntimePathsForTesting(),
+        nowUnixMs: options.nowUnixMs ?? Date.now(),
+        attachService: options.attachService ?? attachOrStartManagedBitcoindService,
+        rpcFactory: options.rpcFactory ?? createRpcClient,
+    };
+}
+export function resolveWalletSetupContext(options) {
+    return {
+        ...resolveWalletManagedCoreContext(options),
+        dataDir: options.dataDir,
+        prompter: options.prompter,
+    };
+}
+export function resolveWalletRepairContext(options) {
+    return {
+        ...resolveWalletManagedCoreContext(options),
+        dataDir: options.dataDir,
+        databasePath: options.databasePath,
+        assumeYes: options.assumeYes ?? false,
+        probeBitcoindService: options.probeBitcoindService ?? probeManagedBitcoindService,
+        attachIndexerDaemon: options.attachIndexerDaemon ?? attachOrStartIndexerDaemon,
+        probeIndexerDaemon: options.probeIndexerDaemon ?? probeIndexerDaemon,
+        requestMiningPreemption: options.requestMiningPreemption,
+        startBackgroundMining: options.startBackgroundMining,
+    };
+}
+export async function acquireWalletControlLock(paths, purpose) {
+    return await acquireFileLock(paths.walletControlLockPath, {
+        purpose,
+        walletRootId: null,
+    });
+}

package/dist/wallet/lifecycle/managed-core.d.ts

@@ -4,16 +4,8 @@ import type { ManagedCoreWalletReplicaStatus } from "../../bitcoind/types.js";
 import type { WalletRuntimePaths } from "../runtime.js";
 import { type WalletSecretProvider } from "../state/provider.js";
 import type { WalletStateV1 } from "../types.js";
-import type { WalletLifecycleRpcClient, WalletManagedCoreDependencies, WalletLifecycleResolvedContext } from "./types.js";
+import type { WalletLifecycleRpcClient, WalletManagedCoreDependencies } from "./types.js";
 export declare function sanitizeWalletName(walletRootId: string): string;
-export declare function normalizeLoadedWalletStateIfNeeded(options: WalletLifecycleResolvedContext & {
-    state: WalletStateV1;
-    source: "primary" | "backup";
-    dataDir?: string;
-} & WalletManagedCoreDependencies): Promise<{
-    state: WalletStateV1;
-    source: "primary" | "backup";
-}>;
 export declare function importDescriptorIntoManagedCoreWallet(state: WalletStateV1, provider: WalletSecretProvider, paths: WalletRuntimePaths, dataDir: string, nowUnixMs: number, attachService?: typeof attachOrStartManagedBitcoindService, rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletLifecycleRpcClient): Promise<WalletStateV1>;
 export declare function recreateManagedCoreWalletReplica(state: WalletStateV1, provider: WalletSecretProvider, paths: WalletRuntimePaths, dataDir: string, nowUnixMs: number, options?: WalletManagedCoreDependencies): Promise<WalletStateV1>;
 export declare function verifyManagedCoreWalletReplica(state: WalletStateV1, dataDir: string, dependencies?: WalletManagedCoreDependencies & {

package/dist/wallet/lifecycle/managed-core.js

@@ -1,75 +1,15 @@
-import { access, constants, rename } from "node:fs/promises";
+import { rename } from "node:fs/promises";
 import { join } from "node:path";
 import { attachOrStartManagedBitcoindService, createManagedWalletReplica } from "../../bitcoind/service.js";
 import { createRpcClient } from "../../bitcoind/node.js";
-import { persistWalletCoinControlStateIfNeeded, normalizeWalletStateRecord } from "../coin-control.js";
-import { persistNormalizedWalletDescriptorStateIfNeeded, resolveNormalizedWalletDescriptorState, } from "../descriptor-normalization.js";
-import { normalizeMiningStateRecord } from "../mining/state.js";
+import { resolveNormalizedWalletDescriptorState, } from "../descriptor-normalization.js";
 import { createWalletSecretReference } from "../state/provider.js";
 import { saveWalletState } from "../state/storage.js";
 import { withUnlockedManagedCoreWallet } from "../managed-core-wallet.js";
+import { pathExists } from "./context.js";
 export function sanitizeWalletName(walletRootId) {
     return `cogcoin-${walletRootId}`.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 63);
 }
-async function pathExists(path) {
-    try {
-        await access(path, constants.F_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export async function normalizeLoadedWalletStateIfNeeded(options) {
-    let state = options.state;
-    let source = options.source;
-    if (options.dataDir !== undefined) {
-        const node = await (options.attachService ?? attachOrStartManagedBitcoindService)({
-            dataDir: options.dataDir,
-            chain: "main",
-            startHeight: 0,
-            walletRootId: state.walletRootId,
-        });
-        try {
-            const normalized = await persistNormalizedWalletDescriptorStateIfNeeded({
-                state,
-                access: {
-                    provider: options.provider,
-                    secretReference: createWalletSecretReference(state.walletRootId),
-                },
-                paths: options.paths,
-                nowUnixMs: options.nowUnixMs,
-                replacePrimary: options.source === "backup",
-                rpc: (options.rpcFactory ?? createRpcClient)(node.rpc),
-            });
-            state = normalized.state;
-            source = normalized.changed ? "primary" : options.source;
-            const coinControl = await persistWalletCoinControlStateIfNeeded({
-                state,
-                access: {
-                    provider: options.provider,
-                    secretReference: createWalletSecretReference(state.walletRootId),
-                },
-                paths: options.paths,
-                nowUnixMs: options.nowUnixMs,
-                replacePrimary: source === "backup",
-                rpc: createRpcClient(node.rpc),
-            });
-            state = coinControl.state;
-            source = coinControl.changed ? "primary" : source;
-        }
-        finally {
-            await node.stop?.().catch(() => undefined);
-        }
-    }
-    return {
-        state: normalizeWalletStateRecord({
-            ...state,
-            miningState: normalizeMiningStateRecord(state.miningState),
-        }),
-        source,
-    };
-}
 export async function importDescriptorIntoManagedCoreWallet(state, provider, paths, dataDir, nowUnixMs, attachService = attachOrStartManagedBitcoindService, rpcFactory = createRpcClient) {
     const node = await attachService({
         dataDir,

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

@@ -0,0 +1,10 @@
+import type { ManagedServicePaths } from "../../bitcoind/service-paths.js";
+import type { WalletStateV1 } from "../types.js";
+import type { WalletBitcoindRepairStageResult, WalletRepairContext } from "./types.js";
+export declare function repairManagedBitcoindStage(options: {
+    context: WalletRepairContext;
+    servicePaths: ManagedServicePaths;
+    state: WalletStateV1;
+    recoveredFromBackup: boolean;
+    repairStateNeedsPersist: boolean;
+}): Promise<WalletBitcoindRepairStageResult>;

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

@@ -0,0 +1,142 @@
+import { normalizeWalletDescriptorState } from "../descriptor-normalization.js";
+import { acquireFileLock } from "../fs/lock.js";
+import { persistWalletCoinControlStateIfNeeded } from "../coin-control.js";
+import { createWalletSecretReference } from "../state/provider.js";
+import { recreateManagedCoreWalletReplica, verifyManagedCoreWalletReplica } from "./managed-core.js";
+import { pathExists } from "./context.js";
+import { clearManagedBitcoindArtifacts, mapBitcoindCompatibilityToRepairIssue, mapBitcoindRepairHealth, waitForProcessExit, } from "./repair-runtime.js";
+export async function repairManagedBitcoindStage(options) {
+    let state = options.state;
+    let repairStateNeedsPersist = options.repairStateNeedsPersist;
+    let bitcoindServiceAction = "none";
+    let bitcoindCompatibilityIssue = "none";
+    let managedCoreReplicaAction = "none";
+    let recreatedManagedCoreWallet = false;
+    let initialBitcoindProbe = {
+        compatibility: "unreachable",
+        status: null,
+        error: null,
+    };
+    let bitcoindPostRepairHealth = "unavailable";
+    const bitcoindLock = await acquireFileLock(options.servicePaths.bitcoindLockPath, {
+        purpose: "managed-bitcoind-repair",
+        walletRootId: state.walletRootId,
+        dataDir: options.context.dataDir,
+    });
+    try {
+        initialBitcoindProbe = await options.context.probeBitcoindService({
+            dataDir: options.context.dataDir,
+            chain: "main",
+            startHeight: 0,
+            walletRootId: state.walletRootId,
+        });
+        bitcoindCompatibilityIssue = mapBitcoindCompatibilityToRepairIssue(initialBitcoindProbe.compatibility);
+        if (initialBitcoindProbe.compatibility === "service-version-mismatch"
+            || initialBitcoindProbe.compatibility === "wallet-root-mismatch"
+            || initialBitcoindProbe.compatibility === "runtime-mismatch") {
+            const processId = initialBitcoindProbe.status?.processId ?? null;
+            if (processId === null) {
+                throw new Error("managed_bitcoind_process_id_unavailable");
+            }
+            try {
+                process.kill(processId, "SIGTERM");
+            }
+            catch (error) {
+                if (!(error instanceof Error) || !("code" in error) || error.code !== "ESRCH") {
+                    throw error;
+                }
+            }
+            await waitForProcessExit(processId, 15_000, "managed_bitcoind_stop_timeout");
+            await clearManagedBitcoindArtifacts(options.servicePaths);
+            bitcoindServiceAction = "stopped-incompatible-service";
+        }
+        else if (initialBitcoindProbe.compatibility === "unreachable") {
+            const hasStaleArtifacts = await Promise.all([
+                options.servicePaths.bitcoindStatusPath,
+                options.servicePaths.bitcoindPidPath,
+                options.servicePaths.bitcoindReadyPath,
+                options.servicePaths.bitcoindWalletStatusPath,
+            ].map(pathExists));
+            if (hasStaleArtifacts.some(Boolean)) {
+                await clearManagedBitcoindArtifacts(options.servicePaths);
+                bitcoindServiceAction = "cleared-stale-artifacts";
+            }
+        }
+        else if (initialBitcoindProbe.compatibility === "protocol-error") {
+            throw new Error(initialBitcoindProbe.error ?? "managed_bitcoind_protocol_error");
+        }
+    }
+    finally {
+        await bitcoindLock.release();
+    }
+    const bitcoindHandle = await options.context.attachService({
+        dataDir: options.context.dataDir,
+        chain: "main",
+        startHeight: 0,
+        walletRootId: state.walletRootId,
+    });
+    try {
+        const rpc = options.context.rpcFactory(bitcoindHandle.rpc);
+        const normalizedDescriptorState = await normalizeWalletDescriptorState(state, rpc);
+        if (normalizedDescriptorState.changed) {
+            state = normalizedDescriptorState.state;
+            repairStateNeedsPersist = true;
+        }
+        const reconciledCoinControl = await persistWalletCoinControlStateIfNeeded({
+            state,
+            access: {
+                provider: options.context.provider,
+                secretReference: createWalletSecretReference(state.walletRootId),
+            },
+            paths: options.context.paths,
+            nowUnixMs: options.context.nowUnixMs,
+            replacePrimary: options.recoveredFromBackup && !repairStateNeedsPersist,
+            rpc,
+        });
+        state = reconciledCoinControl.state;
+        if (reconciledCoinControl.changed) {
+            repairStateNeedsPersist = false;
+        }
+        let replica = await verifyManagedCoreWalletReplica(state, options.context.dataDir, {
+            nodeHandle: bitcoindHandle,
+            attachService: options.context.attachService,
+            rpcFactory: options.context.rpcFactory,
+        });
+        if (replica.proofStatus !== "ready") {
+            state = await recreateManagedCoreWalletReplica(state, options.context.provider, options.context.paths, options.context.dataDir, options.context.nowUnixMs, {
+                attachService: options.context.attachService,
+                rpcFactory: options.context.rpcFactory,
+            });
+            recreatedManagedCoreWallet = true;
+            managedCoreReplicaAction = "recreated";
+            repairStateNeedsPersist = false;
+            replica = await verifyManagedCoreWalletReplica(state, options.context.dataDir, {
+                nodeHandle: bitcoindHandle,
+                attachService: options.context.attachService,
+                rpcFactory: options.context.rpcFactory,
+            });
+        }
+        const finalBitcoindStatus = await bitcoindHandle.refreshServiceStatus?.() ?? null;
+        const chainInfo = await rpc.getBlockchainInfo();
+        bitcoindPostRepairHealth = mapBitcoindRepairHealth({
+            serviceState: finalBitcoindStatus?.state ?? null,
+            catchingUp: chainInfo.blocks < chainInfo.headers,
+            replica,
+        });
+        if (bitcoindServiceAction === "none" && initialBitcoindProbe.compatibility === "unreachable") {
+            bitcoindServiceAction = "restarted-compatible-service";
+        }
+    }
+    finally {
+        await bitcoindHandle.stop?.().catch(() => undefined);
+    }
+    return {
+        state,
+        repairStateNeedsPersist,
+        recreatedManagedCoreWallet,
+        bitcoindServiceAction,
+        bitcoindCompatibilityIssue,
+        managedCoreReplicaAction,
+        bitcoindPostRepairHealth,
+    };
+}

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

@@ -0,0 +1,8 @@
+import type { ManagedServicePaths } from "../../bitcoind/service-paths.js";
+import type { WalletStateV1 } from "../types.js";
+import type { WalletIndexerRepairStageResult, WalletRepairContext } from "./types.js";
+export declare function repairManagedIndexerStage(options: {
+    context: WalletRepairContext;
+    servicePaths: ManagedServicePaths;
+    state: WalletStateV1;
+}): Promise<WalletIndexerRepairStageResult>;

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

@@ -0,0 +1,117 @@
+import { acquireFileLock } from "../fs/lock.js";
+import { pathExists } from "./context.js";
+import { clearIndexerDaemonArtifacts, ensureIndexerDatabaseHealthy, mapIndexerCompatibilityToRepairIssue, verifyIndexerPostRepairHealth, waitForProcessExit, } from "./repair-runtime.js";
+export async function repairManagedIndexerStage(options) {
+    let indexerDaemonAction = "none";
+    let indexerCompatibilityIssue = "none";
+    let initialIndexerDaemonInstanceId = null;
+    const indexerLock = await acquireFileLock(options.servicePaths.indexerDaemonLockPath, {
+        purpose: "indexer-daemon-repair",
+        walletRootId: options.state.walletRootId,
+        dataDir: options.context.dataDir,
+        databasePath: options.context.databasePath,
+    });
+    let resetIndexerDatabase = false;
+    try {
+        const initialProbe = await options.context.probeIndexerDaemon({
+            dataDir: options.context.dataDir,
+            walletRootId: options.state.walletRootId,
+        });
+        indexerCompatibilityIssue = mapIndexerCompatibilityToRepairIssue(initialProbe.compatibility);
+        initialIndexerDaemonInstanceId = initialProbe.status?.daemonInstanceId ?? null;
+        if (initialProbe.compatibility === "compatible") {
+            await initialProbe.client?.close().catch(() => undefined);
+        }
+        else if (initialProbe.compatibility === "service-version-mismatch"
+            || initialProbe.compatibility === "wallet-root-mismatch"
+            || initialProbe.compatibility === "schema-mismatch") {
+            const processId = initialProbe.status?.processId ?? null;
+            if (processId === null) {
+                throw new Error("indexer_daemon_process_id_unavailable");
+            }
+            try {
+                process.kill(processId, "SIGTERM");
+            }
+            catch (error) {
+                if (!(error instanceof Error) || !("code" in error) || error.code !== "ESRCH") {
+                    throw error;
+                }
+            }
+            await waitForProcessExit(processId);
+            await clearIndexerDaemonArtifacts(options.servicePaths);
+            indexerDaemonAction = "stopped-incompatible-daemon";
+        }
+        else if (initialProbe.compatibility === "unreachable") {
+            const hasStaleArtifacts = await Promise.all([
+                options.servicePaths.indexerDaemonSocketPath,
+                options.servicePaths.indexerDaemonStatusPath,
+            ].map(pathExists));
+            if (hasStaleArtifacts.some(Boolean)) {
+                await clearIndexerDaemonArtifacts(options.servicePaths);
+                indexerDaemonAction = "cleared-stale-artifacts";
+            }
+        }
+        else {
+            throw new Error(initialProbe.error ?? "indexer_daemon_protocol_error");
+        }
+        resetIndexerDatabase = await ensureIndexerDatabaseHealthy({
+            databasePath: options.context.databasePath,
+            dataDir: options.context.dataDir,
+            walletRootId: options.state.walletRootId,
+            resetIfNeeded: options.context.assumeYes,
+        });
+    }
+    finally {
+        await indexerLock.release();
+    }
+    let preAttachIndexerDaemonInstanceId = null;
+    const preAttachProbe = await options.context.probeIndexerDaemon({
+        dataDir: options.context.dataDir,
+        walletRootId: options.state.walletRootId,
+    });
+    if (preAttachProbe.compatibility === "compatible") {
+        preAttachIndexerDaemonInstanceId = preAttachProbe.status?.daemonInstanceId ?? null;
+        await preAttachProbe.client?.close().catch(() => undefined);
+    }
+    else if (preAttachProbe.compatibility !== "unreachable") {
+        throw new Error(preAttachProbe.error ?? "indexer_daemon_protocol_error");
+    }
+    const daemon = await options.context.attachIndexerDaemon({
+        dataDir: options.context.dataDir,
+        databasePath: options.context.databasePath,
+        walletRootId: options.state.walletRootId,
+    });
+    try {
+        const { health: indexerPostRepairHealth, daemonInstanceId: postRepairDaemonInstanceId, } = await verifyIndexerPostRepairHealth({
+            daemon,
+            probeIndexerDaemon: options.context.probeIndexerDaemon,
+            dataDir: options.context.dataDir,
+            walletRootId: options.state.walletRootId,
+            nowUnixMs: options.context.nowUnixMs,
+        });
+        const restartedIndexerDaemon = indexerDaemonAction !== "none" || preAttachProbe.compatibility === "unreachable";
+        if (restartedIndexerDaemon
+            && initialIndexerDaemonInstanceId !== null
+            && postRepairDaemonInstanceId === initialIndexerDaemonInstanceId) {
+            throw new Error("indexer_daemon_repair_identity_not_rotated");
+        }
+        if (!restartedIndexerDaemon
+            && preAttachProbe.compatibility === "compatible"
+            && preAttachIndexerDaemonInstanceId !== null
+            && postRepairDaemonInstanceId !== preAttachIndexerDaemonInstanceId) {
+            throw new Error("indexer_daemon_repair_identity_changed");
+        }
+        if (indexerDaemonAction === "none" && preAttachProbe.compatibility === "unreachable") {
+            indexerDaemonAction = "restarted-compatible-daemon";
+        }
+        return {
+            resetIndexerDatabase,
+            indexerDaemonAction,
+            indexerCompatibilityIssue,
+            indexerPostRepairHealth,
+        };
+    }
+    finally {
+        await daemon.close().catch(() => undefined);
+    }
+}

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

@@ -1,11 +1,9 @@
-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;
+    provider?: import("../state/provider.js").WalletSecretProvider;
     assumeYes?: boolean;
     nowUnixMs?: number;
-    paths?: WalletRuntimePaths;
+    paths?: import("../runtime.js").WalletRuntimePaths;
 } & WalletRepairDependencies): Promise<WalletRepairResult>;