@cogcoin/client 1.2.0 → 1.2.2

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@1.2.0` 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.2` 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/bitcoind/managed-runtime/bitcoind-policy.js

@@ -8,6 +8,9 @@ function isRuntimeMismatchError(error) {
     return error.message.startsWith("bitcoind_chain_expected_")
         || error.message === "managed_bitcoind_runtime_mismatch";
 }
+function isMissingRawTxZmqError(error) {
+    return error instanceof Error && error.message === "bitcoind_zmq_rawtx_missing";
+}
 function isUnreachableManagedBitcoindError(error) {
     if (error instanceof Error) {
         if ("code" in error) {
@@ -47,6 +50,13 @@ export function mapManagedBitcoindValidationError(error, status) {
     };
 }
 export function mapManagedBitcoindRuntimeProbeFailure(error, status) {
+    if (isMissingRawTxZmqError(error)) {
+        return {
+            compatibility: "rawtx-zmq-missing",
+            status,
+            error: "bitcoind_zmq_rawtx_missing",
+        };
+    }
     if (isRuntimeMismatchError(error)) {
         return {
             compatibility: "runtime-mismatch",

package/dist/bitcoind/managed-runtime/types.d.ts

@@ -2,7 +2,7 @@ import type { ClientTip } from "../../types.js";
 import type { ManagedServicePaths } from "../service-paths.js";
 import type { ManagedBitcoindObservedStatus, ManagedIndexerDaemonObservedStatus, ManagedIndexerTruthSource } from "../types.js";
 import type { WalletBitcoindStatus, WalletIndexerStatus, WalletNodeStatus, WalletServiceHealth, WalletSnapshotView } from "../../wallet/read/types.js";
-export type ManagedBitcoindServiceCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "unreachable" | "protocol-error";
+export type ManagedBitcoindServiceCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "rawtx-zmq-missing" | "unreachable" | "protocol-error";
 export interface ManagedBitcoindServiceProbeResult {
     compatibility: ManagedBitcoindServiceCompatibility;
     status: ManagedBitcoindObservedStatus | null;

package/dist/cli/output/rules/services.js

@@ -108,6 +108,13 @@ export const serviceErrorRules = [
                 next: "Run `cogcoin repair` so the wallet can clear the conflicting runtime and restart a compatible managed bitcoind service.",
             };
         }
+        if (errorCode === "bitcoind_zmq_rawtx_missing" || errorCode.includes("rawtx_zmq_missing")) {
+            return {
+                what: "The live managed bitcoind service is missing raw transaction ZMQ.",
+                why: "This usually means an older managed bitcoind runtime is still running without the v1.2.0 `zmqpubrawtx` setting.",
+                next: "Run `cogcoin repair` so the wallet can stop the stale managed bitcoind service and restart it with the current ZMQ configuration.",
+            };
+        }
         if (errorCode.includes("bitcoind_replica_missing")) {
             return {
                 what: "The managed Core wallet replica is missing.",

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 { clearManagedBitcoindArtifacts, isManagedBitcoindRpcUnavailableError, mapBitcoindCompatibilityToRepairIssue, mapBitcoindRepairHealth, waitForProcessExit, } from "./repair-runtime.js";
 export async function repairManagedBitcoindStage(options) {
     let state = options.state;
     let repairStateNeedsPersist = options.repairStateNeedsPersist;
@@ -33,28 +33,38 @@ export async function repairManagedBitcoindStage(options) {
         bitcoindCompatibilityIssue = mapBitcoindCompatibilityToRepairIssue(initialBitcoindProbe.compatibility);
         if (initialBitcoindProbe.compatibility === "service-version-mismatch"
             || initialBitcoindProbe.compatibility === "wallet-root-mismatch"
-            || initialBitcoindProbe.compatibility === "runtime-mismatch") {
+            || initialBitcoindProbe.compatibility === "runtime-mismatch"
+            || initialBitcoindProbe.compatibility === "rawtx-zmq-missing") {
             const processId = initialBitcoindProbe.status?.processId ?? null;
             if (processId === null) {
-                throw new Error("managed_bitcoind_process_id_unavailable");
-            }
-            try {
-                process.kill(processId, "SIGTERM");
+                if (initialBitcoindProbe.compatibility !== "rawtx-zmq-missing") {
+                    throw new Error("managed_bitcoind_process_id_unavailable");
+                }
+                await clearManagedBitcoindArtifacts(options.servicePaths);
+                bitcoindServiceAction = "restarted-missing-rawtx-zmq";
             }
-            catch (error) {
-                if (!(error instanceof Error) || !("code" in error) || error.code !== "ESRCH") {
-                    throw error;
+            else {
+                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 = initialBitcoindProbe.compatibility === "rawtx-zmq-missing"
+                    ? "restarted-missing-rawtx-zmq"
+                    : "stopped-incompatible-service";
             }
-            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.bitcoindRuntimeConfigPath,
                 options.servicePaths.bitcoindWalletStatusPath,
             ].map(pathExists));
             if (hasStaleArtifacts.some(Boolean)) {
@@ -69,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,
+            });
+            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,
             });
-            recreatedManagedCoreWallet = true;
-            managedCoreReplicaAction = "recreated";
-            repairStateNeedsPersist = false;
-            replica = await verifyManagedCoreWalletReplica(state, options.context.dataDir, {
+            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 clearManagedBitcoindArtifacts(options.servicePaths);
+                }
+                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,6 +29,7 @@ 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>;

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

@@ -69,6 +69,8 @@ export function mapBitcoindCompatibilityToRepairIssue(compatibility) {
             return "wallet-root-mismatch";
         case "runtime-mismatch":
             return "runtime-mismatch";
+        case "rawtx-zmq-missing":
+            return "rawtx-zmq-missing";
         default:
             return "none";
     }
@@ -151,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) {
@@ -169,6 +187,7 @@ 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);
 }
 export async function stopRecordedManagedProcess(pid, errorCode) {

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

@@ -36,8 +36,8 @@ export interface WalletRepairResult {
     recoveredFromBackup: boolean;
     recreatedManagedCoreWallet: boolean;
     resetIndexerDatabase: boolean;
-    bitcoindServiceAction: "none" | "cleared-stale-artifacts" | "stopped-incompatible-service" | "restarted-compatible-service";
-    bitcoindCompatibilityIssue: "none" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch";
+    bitcoindServiceAction: "none" | "cleared-stale-artifacts" | "stopped-incompatible-service" | "restarted-compatible-service" | "restarted-missing-rawtx-zmq";
+    bitcoindCompatibilityIssue: "none" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "rawtx-zmq-missing";
     managedCoreReplicaAction: "none" | "recreated";
     bitcoindPostRepairHealth: "ready" | "catching-up" | "starting" | "failed" | "unavailable";
     indexerDaemonAction: "none" | "cleared-stale-artifacts" | "stopped-incompatible-daemon" | "restarted-compatible-daemon";

package/package.json

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