@cogcoin/client 1.2.1 → 1.2.3

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@1.2.1` is the reference 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@1.2.3` is the reference 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/bitcoind/managed-bitcoind-service-status.js

@@ -66,7 +66,9 @@ export async function probeManagedBitcoindStatusCandidate(status, options, runti
     const rpc = createRpcClient(status.rpc);
     try {
         await waitForManagedBitcoindRpcReady(rpc, status.rpc.cookieFile, status.chain, options.startupTimeoutMs ?? DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS);
-        await validateNodeConfigForTesting(rpc, status.chain, status.zmq.endpoint);
+        await validateNodeConfigForTesting(rpc, status.chain, status.zmq.endpoint, {
+            requireRawTxZmq: true,
+        });
         return {
             compatibility: "compatible",
             status,
@@ -96,7 +98,9 @@ export async function refreshManagedBitcoindStatus(status, paths, options) {
     const targetWalletRootId = options.walletRootId ?? status.walletRootId;
     try {
         await waitForManagedBitcoindRpcReady(rpc, status.rpc.cookieFile, status.chain, options.startupTimeoutMs ?? DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS);
-        await validateNodeConfigForTesting(rpc, status.chain, status.zmq.endpoint);
+        await validateNodeConfigForTesting(rpc, status.chain, status.zmq.endpoint, {
+            requireRawTxZmq: true,
+        });
         const walletReplica = await loadManagedWalletReplicaIfPresent(rpc, targetWalletRootId, status.dataDir);
         const nextStatus = {
             ...status,

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

@@ -4,7 +4,7 @@ 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";
+import { clearManagedBitcoindArtifactsForDataDir, isManagedBitcoindRpcUnavailableError, mapBitcoindCompatibilityToRepairIssue, mapBitcoindRepairHealth, waitForProcessExit, } from "./repair-runtime.js";
 export async function repairManagedBitcoindStage(options) {
     let state = options.state;
     let repairStateNeedsPersist = options.repairStateNeedsPersist;
@@ -40,7 +40,7 @@ export async function repairManagedBitcoindStage(options) {
                 if (initialBitcoindProbe.compatibility !== "rawtx-zmq-missing") {
                     throw new Error("managed_bitcoind_process_id_unavailable");
                 }
-                await clearManagedBitcoindArtifacts(options.servicePaths);
+                await clearManagedBitcoindArtifactsForDataDir(options.servicePaths, options.context.dataDir);
                 bitcoindServiceAction = "restarted-missing-rawtx-zmq";
             }
             else {
@@ -53,7 +53,7 @@ export async function repairManagedBitcoindStage(options) {
                     }
                 }
                 await waitForProcessExit(processId, 15_000, "managed_bitcoind_stop_timeout");
-                await clearManagedBitcoindArtifacts(options.servicePaths);
+                await clearManagedBitcoindArtifactsForDataDir(options.servicePaths, options.context.dataDir);
                 bitcoindServiceAction = initialBitcoindProbe.compatibility === "rawtx-zmq-missing"
                     ? "restarted-missing-rawtx-zmq"
                     : "stopped-incompatible-service";
@@ -68,7 +68,7 @@ export async function repairManagedBitcoindStage(options) {
                 options.servicePaths.bitcoindWalletStatusPath,
             ].map(pathExists));
             if (hasStaleArtifacts.some(Boolean)) {
-                await clearManagedBitcoindArtifacts(options.servicePaths);
+                await clearManagedBitcoindArtifactsForDataDir(options.servicePaths, options.context.dataDir);
                 bitcoindServiceAction = "cleared-stale-artifacts";
             }
         }
@@ -79,74 +79,105 @@ export async function repairManagedBitcoindStage(options) {
     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,
+    for (let attachAttempt = 0; attachAttempt < 2; attachAttempt += 1) {
+        let bitcoindHandle = null;
+        let handleClosed = false;
+        try {
+            bitcoindHandle = await options.context.attachService({
+                dataDir: options.context.dataDir,
+                chain: "main",
+                startHeight: 0,
+                walletRootId: state.walletRootId,
             });
-            recreatedManagedCoreWallet = true;
-            managedCoreReplicaAction = "recreated";
-            repairStateNeedsPersist = false;
-            replica = await verifyManagedCoreWalletReplica(state, options.context.dataDir, {
+            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";
+            }
+            return {
+                state,
+                repairStateNeedsPersist,
+                recreatedManagedCoreWallet,
+                bitcoindServiceAction,
+                bitcoindCompatibilityIssue,
+                managedCoreReplicaAction,
+                bitcoindPostRepairHealth,
+            };
         }
-        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";
+        catch (error) {
+            if (bitcoindHandle !== null) {
+                await bitcoindHandle.stop?.().catch(() => undefined);
+                handleClosed = true;
+            }
+            if (attachAttempt === 0 && isManagedBitcoindRpcUnavailableError(error)) {
+                const retryLock = await acquireFileLock(options.servicePaths.bitcoindLockPath, {
+                    purpose: "managed-bitcoind-repair-stale-rpc",
+                    walletRootId: state.walletRootId,
+                    dataDir: options.context.dataDir,
+                });
+                try {
+                    await clearManagedBitcoindArtifactsForDataDir(options.servicePaths, options.context.dataDir);
+                }
+                finally {
+                    await retryLock.release();
+                }
+                if (bitcoindServiceAction === "none") {
+                    bitcoindServiceAction = "restarted-compatible-service";
+                }
+                continue;
+            }
+            throw error;
+        }
+        finally {
+            if (!handleClosed) {
+                await bitcoindHandle?.stop?.().catch(() => undefined);
+            }
         }
     }
-    finally {
-        await bitcoindHandle.stop?.().catch(() => undefined);
-    }
-    return {
-        state,
-        repairStateNeedsPersist,
-        recreatedManagedCoreWallet,
-        bitcoindServiceAction,
-        bitcoindCompatibilityIssue,
-        managedCoreReplicaAction,
-        bitcoindPostRepairHealth,
-    };
+    throw new Error("managed_bitcoind_repair_retry_exhausted");
 }

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

@@ -29,8 +29,10 @@ export declare function verifyIndexerPostRepairHealth(options: {
     daemonInstanceId: string;
 }>;
 export declare function isProcessAlive(pid: number | null): Promise<boolean>;
+export declare function isManagedBitcoindRpcUnavailableError(error: unknown): 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 clearManagedBitcoindArtifactsForDataDir(servicePaths: ReturnType<typeof resolveManagedServicePaths>, dataDir: string): 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

@@ -1,5 +1,5 @@
-import { access, constants, mkdir, readFile, rm } from "node:fs/promises";
-import { dirname } from "node:path";
+import { access, constants, mkdir, readdir, readFile, rm } from "node:fs/promises";
+import { dirname, join } 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";
@@ -153,6 +153,22 @@ export async function isProcessAlive(pid) {
         return true;
     }
 }
+export function isManagedBitcoindRpcUnavailableError(error) {
+    if (error instanceof Error && "code" in error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ECONNREFUSED" || code === "ECONNRESET" || code === "EPIPE") {
+            return true;
+        }
+    }
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return error.message === "bitcoind_cookie_timeout"
+        || error.message.includes("cookie file is unavailable")
+        || error.message.includes("ECONNREFUSED")
+        || error.message.includes("ECONNRESET")
+        || error.message.includes("socket hang up");
+}
 export async function waitForProcessExit(pid, timeoutMs = 15_000, errorCode = "indexer_daemon_stop_timeout") {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
@@ -168,11 +184,62 @@ export async function clearIndexerDaemonArtifacts(servicePaths) {
     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.bitcoindRuntimeConfigPath, { force: true }).catch(() => undefined);
-    await rm(servicePaths.bitcoindWalletStatusPath, { force: true }).catch(() => undefined);
+    await clearManagedBitcoindArtifactRoot(servicePaths.walletRuntimeRoot);
+}
+async function readManagedBitcoindStatusAtRoot(serviceRoot) {
+    try {
+        return JSON.parse(await readFile(join(serviceRoot, "bitcoind-status.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function clearManagedBitcoindArtifactRoot(serviceRoot) {
+    await rm(join(serviceRoot, "bitcoind-status.json"), { force: true }).catch(() => undefined);
+    await rm(join(serviceRoot, "bitcoind.pid"), { force: true }).catch(() => undefined);
+    await rm(join(serviceRoot, "bitcoind.ready"), { force: true }).catch(() => undefined);
+    await rm(join(serviceRoot, "bitcoind-config.json"), { force: true }).catch(() => undefined);
+    await rm(join(serviceRoot, "bitcoind-wallet.json"), { force: true }).catch(() => undefined);
+}
+async function stopManagedBitcoindPid(pid) {
+    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;
+        }
+    }
+    await waitForProcessExit(pid, 15_000, "managed_bitcoind_stop_timeout");
+}
+export async function clearManagedBitcoindArtifactsForDataDir(servicePaths, dataDir) {
+    const serviceRoots = new Set([servicePaths.walletRuntimeRoot]);
+    const runtimeEntries = await readdir(servicePaths.runtimeRoot, { withFileTypes: true }).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    });
+    for (const entry of runtimeEntries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const serviceRoot = join(servicePaths.runtimeRoot, entry.name);
+        const status = await readManagedBitcoindStatusAtRoot(serviceRoot);
+        if (status?.dataDir === dataDir) {
+            serviceRoots.add(serviceRoot);
+        }
+    }
+    for (const serviceRoot of serviceRoots) {
+        const status = await readManagedBitcoindStatusAtRoot(serviceRoot);
+        if (status?.dataDir === dataDir) {
+            await stopManagedBitcoindPid(status.processId);
+        }
+        await clearManagedBitcoindArtifactRoot(serviceRoot);
+    }
 }
 export async function stopRecordedManagedProcess(pid, errorCode) {
     if (pid === null || !await isProcessAlive(pid)) {

package/package.json

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