@cogcoin/client 1.1.9 → 1.1.10

package/dist/bitcoind/managed-bitcoind-service-replica.js

@@ -0,0 +1,142 @@
+import { randomBytes } from "node:crypto";
+import { access, constants } from "node:fs/promises";
+import { join } from "node:path";
+export function getManagedBitcoindWalletReplicaName(walletRootId) {
+    return `cogcoin-${walletRootId}`.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 63);
+}
+export function createMissingManagedWalletReplicaStatus(walletRootId, message) {
+    return {
+        walletRootId,
+        walletName: getManagedBitcoindWalletReplicaName(walletRootId),
+        loaded: false,
+        descriptors: false,
+        privateKeysEnabled: false,
+        created: false,
+        proofStatus: "missing",
+        descriptorChecksum: null,
+        fundingAddress0: null,
+        fundingScriptPubKeyHex0: null,
+        message,
+    };
+}
+function isMissingWalletError(message) {
+    return message.includes("bitcoind_rpc_loadwallet_-18_")
+        || message.includes("Path does not exist")
+        || message.includes("not found");
+}
+export async function loadManagedWalletReplicaIfPresent(rpc, walletRootId, dataDir) {
+    const walletName = getManagedBitcoindWalletReplicaName(walletRootId);
+    const loadedWallets = await rpc.listWallets();
+    let loaded = loadedWallets.includes(walletName);
+    if (!loaded) {
+        try {
+            await rpc.loadWallet(walletName, false);
+            loaded = true;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!isMissingWalletError(message)) {
+                return {
+                    walletRootId,
+                    walletName,
+                    loaded: false,
+                    descriptors: false,
+                    privateKeysEnabled: false,
+                    created: false,
+                    proofStatus: "mismatch",
+                    descriptorChecksum: null,
+                    fundingAddress0: null,
+                    fundingScriptPubKeyHex0: null,
+                    message,
+                };
+            }
+            const walletDir = join(dataDir, "wallets", walletName);
+            const walletDirExists = await access(walletDir, constants.F_OK).then(() => true).catch(() => false);
+            return createMissingManagedWalletReplicaStatus(walletRootId, walletDirExists
+                ? "Managed Core wallet replica exists on disk but is not loaded."
+                : "Managed Core wallet replica is missing.");
+        }
+    }
+    const info = await rpc.getWalletInfo(walletName);
+    if (!info.descriptors || !info.private_keys_enabled) {
+        return {
+            walletRootId,
+            walletName,
+            loaded: true,
+            descriptors: info.descriptors,
+            privateKeysEnabled: info.private_keys_enabled,
+            created: false,
+            proofStatus: "mismatch",
+            descriptorChecksum: null,
+            fundingAddress0: null,
+            fundingScriptPubKeyHex0: null,
+            message: "Managed Core wallet replica is not an encrypted descriptor wallet with private keys enabled.",
+        };
+    }
+    try {
+        await rpc.walletLock(walletName);
+    }
+    catch {
+        // A freshly created encrypted wallet may already be locked.
+    }
+    return {
+        walletRootId,
+        walletName,
+        loaded: true,
+        descriptors: info.descriptors,
+        privateKeysEnabled: info.private_keys_enabled,
+        created: false,
+        proofStatus: "not-proven",
+        descriptorChecksum: null,
+        fundingAddress0: null,
+        fundingScriptPubKeyHex0: null,
+        message: null,
+    };
+}
+export async function createManagedWalletReplica(rpc, walletRootId, options = {}) {
+    const walletName = getManagedBitcoindWalletReplicaName(walletRootId);
+    const loadedWallets = await rpc.listWallets();
+    let created = false;
+    if (!loadedWallets.includes(walletName)) {
+        try {
+            await rpc.loadWallet(walletName, false);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!isMissingWalletError(message)) {
+                throw error;
+            }
+            await rpc.createWallet(walletName, {
+                blank: true,
+                descriptors: true,
+                disablePrivateKeys: false,
+                loadOnStartup: false,
+                passphrase: options.managedWalletPassphrase ?? randomBytes(32).toString("hex"),
+            });
+            created = true;
+        }
+    }
+    const info = await rpc.getWalletInfo(walletName);
+    if (!info.descriptors || !info.private_keys_enabled) {
+        throw new Error("managed_bitcoind_wallet_replica_invalid");
+    }
+    try {
+        await rpc.walletLock(walletName);
+    }
+    catch {
+        // A freshly created encrypted wallet may already be locked.
+    }
+    return {
+        walletRootId,
+        walletName,
+        loaded: true,
+        descriptors: info.descriptors,
+        privateKeysEnabled: info.private_keys_enabled,
+        created,
+        proofStatus: "not-proven",
+        descriptorChecksum: null,
+        fundingAddress0: null,
+        fundingScriptPubKeyHex0: null,
+        message: null,
+    };
+}

package/dist/bitcoind/managed-bitcoind-service-status.d.ts

@@ -0,0 +1,42 @@
+import { createRpcClient } from "./node.js";
+import { resolveManagedServicePaths } from "./service-paths.js";
+import { type ManagedBitcoindObservedStatus, type ManagedBitcoindNodeHandle, type ManagedBitcoindServiceStatus, type ManagedCoreWalletReplicaStatus } from "./types.js";
+import type { ManagedBitcoindServiceOwnership, ManagedBitcoindServiceOptions, ManagedBitcoindServiceStopResult } from "./managed-bitcoind-service-types.js";
+import { type BitcoindRpcConfig, type BitcoindZmqConfig } from "./managed-bitcoind-service-config.js";
+import type { ManagedBitcoindServiceProbeResult } from "./managed-runtime/types.js";
+export declare function waitForManagedBitcoindRpcReady(rpc: ReturnType<typeof createRpcClient>, cookieFile: string, expectedChain: "main" | "regtest", timeoutMs: number): Promise<void>;
+export declare function createBitcoindServiceStatus(options: {
+    binaryVersion: string;
+    serviceInstanceId: string;
+    state: ManagedBitcoindServiceStatus["state"];
+    processId: number | null;
+    walletRootId: string;
+    chain: "main" | "regtest";
+    dataDir: string;
+    runtimeRoot: string;
+    startHeight: number;
+    rpc: BitcoindRpcConfig;
+    zmq: BitcoindZmqConfig;
+    p2pPort: number;
+    getblockArchiveEndHeight: number | null;
+    getblockArchiveSha256: string | null;
+    walletReplica: ManagedCoreWalletReplicaStatus | null;
+    startedAtUnixMs: number;
+    heartbeatAtUnixMs: number;
+    lastError: string | null;
+}): ManagedBitcoindServiceStatus;
+export declare function probeManagedBitcoindStatusCandidate(status: ManagedBitcoindObservedStatus, options: ManagedBitcoindServiceOptions, runtimeRoot: string): Promise<ManagedBitcoindServiceProbeResult>;
+export declare function writeManagedBitcoindStatus(paths: ReturnType<typeof resolveManagedServicePaths>, status: ManagedBitcoindServiceStatus): Promise<void>;
+export declare function clearManagedBitcoindRuntimeArtifacts(paths: ReturnType<typeof resolveManagedServicePaths>): Promise<void>;
+export declare function refreshManagedBitcoindStatus(status: ManagedBitcoindServiceStatus, paths: ReturnType<typeof resolveManagedServicePaths>, options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindServiceStatus>;
+export declare function createManagedBitcoindNodeHandle(options: {
+    status: ManagedBitcoindServiceStatus;
+    paths: ReturnType<typeof resolveManagedServicePaths>;
+    serviceOptions: ManagedBitcoindServiceOptions;
+    ownership: ManagedBitcoindServiceOwnership;
+    stopService(options: {
+        dataDir: string;
+        walletRootId?: string;
+        shutdownTimeoutMs?: number;
+    }): Promise<ManagedBitcoindServiceStopResult>;
+}): ManagedBitcoindNodeHandle;

package/dist/bitcoind/managed-bitcoind-service-status.js

@@ -0,0 +1,178 @@
+import { mkdir, rm } from "node:fs/promises";
+import { writeFileAtomic } from "../wallet/fs/atomic.js";
+import { writeRuntimeStatusFile } from "../wallet/fs/status-file.js";
+import { mapManagedBitcoindRuntimeProbeFailure, mapManagedBitcoindValidationError, validateManagedBitcoindObservedStatus, } from "./managed-runtime/bitcoind-policy.js";
+import { createRpcClient, validateNodeConfigForTesting } from "./node.js";
+import { resolveManagedServicePaths } from "./service-paths.js";
+import { MANAGED_BITCOIND_SERVICE_API_VERSION, } from "./types.js";
+import { createMissingManagedWalletReplicaStatus, loadManagedWalletReplicaIfPresent, } from "./managed-bitcoind-service-replica.js";
+import { DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS, isManagedBitcoindProcessAlive, sleep, } from "./managed-bitcoind-service-process.js";
+import { waitForManagedBitcoindCookie, } from "./managed-bitcoind-service-config.js";
+export async function waitForManagedBitcoindRpcReady(rpc, cookieFile, expectedChain, timeoutMs) {
+    await waitForManagedBitcoindCookie(cookieFile, timeoutMs, sleep);
+    const deadline = Date.now() + timeoutMs;
+    let lastError = null;
+    while (Date.now() < deadline) {
+        try {
+            const info = await rpc.getBlockchainInfo();
+            if (info.chain !== expectedChain) {
+                throw new Error(`bitcoind_chain_expected_${expectedChain}_got_${info.chain}`);
+            }
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            await sleep(250);
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error("bitcoind_rpc_timeout");
+}
+export function createBitcoindServiceStatus(options) {
+    return {
+        serviceApiVersion: MANAGED_BITCOIND_SERVICE_API_VERSION,
+        binaryVersion: options.binaryVersion,
+        buildId: null,
+        serviceInstanceId: options.serviceInstanceId,
+        state: options.state,
+        processId: options.processId,
+        walletRootId: options.walletRootId,
+        chain: options.chain,
+        dataDir: options.dataDir,
+        runtimeRoot: options.runtimeRoot,
+        startHeight: options.startHeight,
+        rpc: options.rpc,
+        zmq: options.zmq,
+        p2pPort: options.p2pPort,
+        getblockArchiveEndHeight: options.getblockArchiveEndHeight,
+        getblockArchiveSha256: options.getblockArchiveSha256,
+        walletReplica: options.walletReplica,
+        startedAtUnixMs: options.startedAtUnixMs,
+        heartbeatAtUnixMs: options.heartbeatAtUnixMs,
+        updatedAtUnixMs: options.heartbeatAtUnixMs,
+        lastError: options.lastError,
+    };
+}
+export async function probeManagedBitcoindStatusCandidate(status, options, runtimeRoot) {
+    try {
+        validateManagedBitcoindObservedStatus(status, {
+            chain: options.chain,
+            dataDir: options.dataDir ?? "",
+            runtimeRoot,
+        });
+    }
+    catch (error) {
+        return mapManagedBitcoindValidationError(error, status);
+    }
+    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);
+        return {
+            compatibility: "compatible",
+            status,
+            error: null,
+        };
+    }
+    catch (error) {
+        return mapManagedBitcoindRuntimeProbeFailure(error, status);
+    }
+}
+export async function writeManagedBitcoindStatus(paths, status) {
+    await mkdir(paths.walletRuntimeRoot, { recursive: true });
+    await writeRuntimeStatusFile(paths.bitcoindStatusPath, status);
+    await writeFileAtomic(paths.bitcoindPidPath, `${status.processId ?? ""}\n`, { mode: 0o600 });
+    await writeFileAtomic(paths.bitcoindReadyPath, `${status.updatedAtUnixMs}\n`, { mode: 0o600 });
+    await writeRuntimeStatusFile(paths.bitcoindWalletStatusPath, status.walletReplica ?? createMissingManagedWalletReplicaStatus(status.walletRootId, "Managed Core wallet replica is missing."));
+    await writeRuntimeStatusFile(paths.bitcoindRuntimeConfigPath, {
+        chain: status.chain,
+        rpc: status.rpc,
+        zmqPort: status.zmq.port,
+        p2pPort: status.p2pPort,
+        getblockArchiveEndHeight: status.getblockArchiveEndHeight,
+        getblockArchiveSha256: status.getblockArchiveSha256,
+    });
+}
+export async function clearManagedBitcoindRuntimeArtifacts(paths) {
+    await rm(paths.bitcoindStatusPath, { force: true }).catch(() => undefined);
+    await rm(paths.bitcoindPidPath, { force: true }).catch(() => undefined);
+    await rm(paths.bitcoindReadyPath, { force: true }).catch(() => undefined);
+    await rm(paths.bitcoindWalletStatusPath, { force: true }).catch(() => undefined);
+}
+export async function refreshManagedBitcoindStatus(status, paths, options) {
+    const nowUnixMs = Date.now();
+    const rpc = createRpcClient(status.rpc);
+    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);
+        const walletReplica = await loadManagedWalletReplicaIfPresent(rpc, targetWalletRootId, status.dataDir);
+        const nextStatus = {
+            ...status,
+            walletRootId: targetWalletRootId,
+            runtimeRoot: paths.walletRuntimeRoot,
+            state: "ready",
+            processId: await isManagedBitcoindProcessAlive(status.processId) ? status.processId : null,
+            walletReplica,
+            heartbeatAtUnixMs: nowUnixMs,
+            updatedAtUnixMs: nowUnixMs,
+            lastError: walletReplica.message ?? null,
+        };
+        await writeManagedBitcoindStatus(paths, nextStatus);
+        return nextStatus;
+    }
+    catch (error) {
+        const nextStatus = {
+            ...status,
+            walletRootId: targetWalletRootId,
+            runtimeRoot: paths.walletRuntimeRoot,
+            state: "failed",
+            processId: await isManagedBitcoindProcessAlive(status.processId) ? status.processId : null,
+            heartbeatAtUnixMs: nowUnixMs,
+            updatedAtUnixMs: nowUnixMs,
+            lastError: error instanceof Error ? error.message : String(error),
+        };
+        await writeManagedBitcoindStatus(paths, nextStatus);
+        return nextStatus;
+    }
+}
+export function createManagedBitcoindNodeHandle(options) {
+    let currentStatus = options.status;
+    const rpc = createRpcClient(currentStatus.rpc);
+    let stopped = false;
+    return {
+        rpc: currentStatus.rpc,
+        zmq: currentStatus.zmq,
+        pid: currentStatus.processId,
+        expectedChain: currentStatus.chain,
+        startHeight: currentStatus.startHeight,
+        dataDir: currentStatus.dataDir,
+        getblockArchiveEndHeight: currentStatus.getblockArchiveEndHeight ?? null,
+        getblockArchiveSha256: currentStatus.getblockArchiveSha256 ?? null,
+        walletRootId: currentStatus.walletRootId,
+        runtimeRoot: options.paths.walletRuntimeRoot,
+        async validate() {
+            await validateNodeConfigForTesting(rpc, currentStatus.chain, currentStatus.zmq.endpoint);
+        },
+        async refreshServiceStatus() {
+            currentStatus = await refreshManagedBitcoindStatus(currentStatus, options.paths, options.serviceOptions);
+            this.getblockArchiveEndHeight = currentStatus.getblockArchiveEndHeight ?? null;
+            this.getblockArchiveSha256 = currentStatus.getblockArchiveSha256 ?? null;
+            this.walletRootId = currentStatus.walletRootId;
+            return currentStatus;
+        },
+        async stop() {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            if (options.serviceOptions.serviceLifetime !== "ephemeral" || options.ownership === "attached") {
+                return;
+            }
+            await options.stopService({
+                dataDir: currentStatus.dataDir,
+                walletRootId: currentStatus.walletRootId,
+                shutdownTimeoutMs: options.serviceOptions.shutdownTimeoutMs,
+            });
+        },
+    };
+}

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

@@ -0,0 +1,36 @@
+import type { InternalManagedBitcoindOptions } from "./types.js";
+export interface ManagedWalletReplicaRpc {
+    listWallets(): Promise<string[]>;
+    loadWallet(walletName: string, loadOnStartup?: boolean): Promise<{
+        name: string;
+        warning: string;
+    }>;
+    createWallet(walletName: string, options: {
+        blank: boolean;
+        descriptors: boolean;
+        disablePrivateKeys: boolean;
+        loadOnStartup: boolean;
+        passphrase: string;
+    }): Promise<unknown>;
+    getWalletInfo(walletName: string): Promise<{
+        descriptors: boolean;
+        private_keys_enabled: boolean;
+    }>;
+    walletLock(walletName: string): Promise<null>;
+}
+export type ManagedBitcoindServiceOptions = Pick<InternalManagedBitcoindOptions, "dataDir" | "chain" | "startHeight" | "walletRootId" | "rpcPort" | "zmqPort" | "p2pPort" | "pollIntervalMs" | "startupTimeoutMs" | "shutdownTimeoutMs" | "managedWalletPassphrase"> & {
+    getblockArchivePath?: string | null;
+    getblockArchiveEndHeight?: number | null;
+    getblockArchiveSha256?: string | null;
+    serviceLifetime?: "persistent" | "ephemeral";
+};
+export type ResolvedManagedBitcoindServiceOptions = ManagedBitcoindServiceOptions & {
+    dataDir: string;
+    walletRootId: string;
+    startupTimeoutMs: number;
+};
+export type ManagedBitcoindServiceOwnership = "attached" | "started";
+export interface ManagedBitcoindServiceStopResult {
+    status: "stopped" | "not-running";
+    walletRootId: string;
+}

package/dist/bitcoind/managed-bitcoind-service-types.js

@@ -0,0 +1 @@
+export {};

package/dist/bitcoind/service.d.ts

@@ -1,64 +1,8 @@
-import type { ManagedBitcoindServiceProbeResult } from "./managed-runtime/types.js";
-import { resolveManagedServicePaths } from "./service-paths.js";
-import type { InternalManagedBitcoindOptions, ManagedBitcoindObservedStatus, ManagedBitcoindRuntimeConfig, ManagedBitcoindNodeHandle, ManagedCoreWalletReplicaStatus } from "./types.js";
+import { buildManagedServiceArgsForTesting, resolveManagedBitcoindDbcacheMiB, writeBitcoinConfForTesting } from "./managed-bitcoind-service-config.js";
+import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, shutdownManagedBitcoindServiceForTesting, stopManagedBitcoindService, stopManagedBitcoindServiceWithLockHeld, withClaimedUninitializedManagedRuntime } from "./managed-bitcoind-service-lifecycle.js";
+import { createManagedWalletReplica } from "./managed-bitcoind-service-replica.js";
 export type { ManagedBitcoindServiceCompatibility, ManagedBitcoindServiceProbeResult, } from "./managed-runtime/types.js";
-export declare function resolveManagedBitcoindDbcacheMiB(totalRamBytes: number): number;
-interface ManagedWalletReplicaRpc {
-    listWallets(): Promise<string[]>;
-    loadWallet(walletName: string, loadOnStartup?: boolean): Promise<{
-        name: string;
-        warning: string;
-    }>;
-    createWallet(walletName: string, options: {
-        blank: boolean;
-        descriptors: boolean;
-        disablePrivateKeys: boolean;
-        loadOnStartup: boolean;
-        passphrase: string;
-    }): Promise<unknown>;
-    getWalletInfo(walletName: string): Promise<{
-        descriptors: boolean;
-        private_keys_enabled: boolean;
-    }>;
-    walletLock(walletName: string): Promise<null>;
-}
-type ManagedBitcoindServiceOptions = Pick<InternalManagedBitcoindOptions, "dataDir" | "chain" | "startHeight" | "walletRootId" | "rpcPort" | "zmqPort" | "p2pPort" | "pollIntervalMs" | "startupTimeoutMs" | "shutdownTimeoutMs" | "managedWalletPassphrase"> & {
-    getblockArchivePath?: string | null;
-    getblockArchiveEndHeight?: number | null;
-    getblockArchiveSha256?: string | null;
-    serviceLifetime?: "persistent" | "ephemeral";
-};
-export interface ManagedBitcoindServiceStopResult {
-    status: "stopped" | "not-running";
-    walletRootId: string;
-}
-export declare function writeBitcoinConfForTesting(filePath: string, options: ManagedBitcoindServiceOptions, runtimeConfig: ManagedBitcoindRuntimeConfig): Promise<void>;
-export declare function buildManagedServiceArgsForTesting(options: ManagedBitcoindServiceOptions, runtimeConfig: ManagedBitcoindRuntimeConfig): string[];
-export declare function createManagedWalletReplica(rpc: ManagedWalletReplicaRpc, walletRootId: string, options?: {
-    managedWalletPassphrase?: string;
-}): Promise<ManagedCoreWalletReplicaStatus>;
-export declare function stopManagedBitcoindServiceWithLockHeld(options: {
-    dataDir: string;
-    walletRootId?: string;
-    shutdownTimeoutMs?: number;
-    paths?: ReturnType<typeof resolveManagedServicePaths>;
-}): Promise<ManagedBitcoindServiceStopResult>;
-export declare function withClaimedUninitializedManagedRuntime<T>(options: {
-    dataDir: string;
-    walletRootId?: string;
-    shutdownTimeoutMs?: number;
-}, callback: () => Promise<T>): Promise<T>;
-export declare function probeManagedBitcoindService(options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindServiceProbeResult>;
-export declare function attachOrStartManagedBitcoindService(options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindNodeHandle>;
-export declare function stopManagedBitcoindService(options: {
-    dataDir: string;
-    walletRootId?: string;
-    shutdownTimeoutMs?: number;
-}): Promise<ManagedBitcoindServiceStopResult>;
-export declare function readManagedBitcoindServiceStatusForTesting(dataDir: string, walletRootId?: string): Promise<ManagedBitcoindObservedStatus | null>;
-export declare function shutdownManagedBitcoindServiceForTesting(options: {
-    dataDir: string;
-    chain?: "main" | "regtest";
-    walletRootId?: string;
-    shutdownTimeoutMs?: number;
-}): Promise<void>;
+export type { ManagedBitcoindServiceStopResult } from "./managed-bitcoind-service-types.js";
+export { attachOrStartManagedBitcoindService, createManagedWalletReplica, probeManagedBitcoindService, resolveManagedBitcoindDbcacheMiB, stopManagedBitcoindService, stopManagedBitcoindServiceWithLockHeld, withClaimedUninitializedManagedRuntime, writeBitcoinConfForTesting, buildManagedServiceArgsForTesting, };
+export declare function readManagedBitcoindServiceStatusForTesting(dataDir: string, walletRootId?: string): Promise<import("./types.js").ManagedBitcoindObservedStatus | null>;
+export { shutdownManagedBitcoindServiceForTesting, };