@cogcoin/client 1.1.9 → 1.1.11

package/dist/wallet/read/context.js

@@ -1,236 +1,13 @@
-import { access, constants } from "node:fs/promises";
 import { readPackageVersionFromDisk } from "../../package-version.js";
-import { readSnapshotWithRetry, } from "../../bitcoind/indexer-daemon.js";
-import { createRpcClient } from "../../bitcoind/node.js";
+export { readSnapshotWithRetry, } from "../../bitcoind/indexer-daemon.js";
 import { UNINITIALIZED_WALLET_ROOT_ID } from "../../bitcoind/service-paths.js";
-import { attachOrStartManagedBitcoindService } from "../../bitcoind/service.js";
-import {} from "../../bitcoind/types.js";
-import { normalizeWalletStateRecord, persistWalletCoinControlStateIfNeeded } from "../coin-control.js";
-import { persistNormalizedWalletDescriptorStateIfNeeded } from "../descriptor-normalization.js";
 import { inspectMiningControlPlane } from "../mining/index.js";
-import { normalizeMiningStateRecord } from "../mining/state.js";
-import { resolveWalletRootIdFromLocalArtifacts } from "../root-resolution.js";
 import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
-import { extractWalletRootIdHintFromWalletStateEnvelope, loadRawWalletStateEnvelope, loadWalletState, } from "../state/storage.js";
-import { createDefaultWalletSecretProvider, createWalletSecretReference, inspectClientPasswordSetupReadiness, } from "../state/provider.js";
-import { describeClientPasswordLockedMessage, describeClientPasswordMigrationMessage, describeClientPasswordSetupMessage, } from "../state/client-password.js";
+import { createDefaultWalletSecretProvider, } from "../state/provider.js";
 import { openManagedWalletReadServiceBundle } from "./managed-services.js";
+import { inspectWalletLocalState, readFundingBalanceSummary } from "./local-state.js";
 import { createWalletReadModel } from "./project.js";
 const DEFAULT_SERVICE_START_TIMEOUT_MS = 60_000;
-function btcAmountToSats(value) {
-    return BigInt(Math.round(value * 100_000_000));
-}
-function isSpendableFundingUtxo(entry, fundingScriptPubKeyHex) {
-    return entry.scriptPubKey === fundingScriptPubKeyHex
-        && entry.confirmations >= 1
-        && entry.spendable !== false
-        && entry.safe !== false;
-}
-async function pathExists(path) {
-    try {
-        await access(path, constants.F_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function isWalletAccessError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return message.startsWith("wallet_secret_missing_")
-        || message.startsWith("wallet_secret_provider_")
-        || message.startsWith("wallet_client_password_")
-        || message === "wallet_state_legacy_envelope_unsupported";
-}
-function describeWalletAccessMessage(options) {
-    const message = options.accessError instanceof Error ? options.accessError.message : String(options.accessError ?? "");
-    if (message === "wallet_state_legacy_envelope_unsupported") {
-        return "Wallet state exists but was created by an older Cogcoin wallet format that this version no longer loads directly.";
-    }
-    if (message === "wallet_client_password_setup_required") {
-        return describeClientPasswordSetupMessage();
-    }
-    if (message === "wallet_client_password_migration_required") {
-        return describeClientPasswordMigrationMessage();
-    }
-    if (message === "wallet_client_password_locked") {
-        return describeClientPasswordLockedMessage();
-    }
-    if (message.startsWith("wallet_secret_provider_")) {
-        return "Wallet state exists but the local secret provider is unavailable.";
-    }
-    if (message.startsWith("wallet_secret_missing_")) {
-        return "Wallet state exists but its local secret-provider material is unavailable.";
-    }
-    return message.length > 0
-        ? message
-        : "Wallet state exists but could not be loaded from the local secret provider.";
-}
-async function normalizeLoadedWalletStateForRead(options) {
-    if (options.dataDir === undefined) {
-        return options.loaded;
-    }
-    const node = await attachOrStartManagedBitcoindService({
-        dataDir: options.dataDir,
-        chain: "main",
-        startHeight: 0,
-        walletRootId: options.loaded.state.walletRootId,
-    });
-    try {
-        const access = {
-            provider: options.access.provider,
-            secretReference: createWalletSecretReference(options.loaded.state.walletRootId),
-        };
-        const normalized = await persistNormalizedWalletDescriptorStateIfNeeded({
-            state: options.loaded.state,
-            access,
-            paths: options.paths,
-            nowUnixMs: options.now,
-            replacePrimary: options.loaded.source === "backup",
-            rpc: createRpcClient(node.rpc),
-        });
-        const coinControl = await persistWalletCoinControlStateIfNeeded({
-            state: normalized.state,
-            access,
-            paths: options.paths,
-            nowUnixMs: options.now,
-            replacePrimary: (normalized.changed ? "primary" : options.loaded.source) === "backup",
-            rpc: createRpcClient(node.rpc),
-        });
-        return {
-            source: coinControl.changed ? "primary" : normalized.changed ? "primary" : options.loaded.source,
-            state: coinControl.state,
-        };
-    }
-    finally {
-        await node.stop?.().catch(() => undefined);
-    }
-}
-async function inspectWalletLocalState(options = {}) {
-    const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
-    const now = options.now ?? Date.now();
-    const provider = options.secretProvider ?? createDefaultWalletSecretProvider();
-    const [hasPrimaryStateFile, hasBackupStateFile] = await Promise.all([
-        pathExists(paths.walletStatePath),
-        pathExists(paths.walletStateBackupPath),
-    ]);
-    const clientPasswordReadiness = await inspectClientPasswordSetupReadiness(provider).catch(() => "ready");
-    if (!hasPrimaryStateFile && !hasBackupStateFile) {
-        return {
-            availability: "uninitialized",
-            clientPasswordReadiness,
-            unlockRequired: false,
-            walletRootId: null,
-            state: null,
-            source: null,
-            hasPrimaryStateFile,
-            hasBackupStateFile,
-            message: "Wallet state has not been initialized yet.",
-        };
-    }
-    if (clientPasswordReadiness !== "ready") {
-        const rawEnvelope = await loadRawWalletStateEnvelope({
-            primaryPath: paths.walletStatePath,
-            backupPath: paths.walletStateBackupPath,
-        }).catch(() => null);
-        if (rawEnvelope?.envelope.secretProvider == null) {
-            return {
-                availability: "local-state-corrupt",
-                clientPasswordReadiness: "ready",
-                unlockRequired: false,
-                walletRootId: extractWalletRootIdHintFromWalletStateEnvelope(rawEnvelope?.envelope ?? null),
-                state: null,
-                source: null,
-                hasPrimaryStateFile,
-                hasBackupStateFile,
-                message: "Wallet state exists but was created by an older Cogcoin wallet format that this version no longer loads directly.",
-            };
-        }
-        const resolvedRoot = await resolveWalletRootIdFromLocalArtifacts({
-            paths,
-            provider,
-        }).catch(() => null);
-        return {
-            availability: "local-state-corrupt",
-            clientPasswordReadiness,
-            unlockRequired: false,
-            walletRootId: resolvedRoot?.walletRootId ?? null,
-            state: null,
-            source: null,
-            hasPrimaryStateFile,
-            hasBackupStateFile,
-            message: clientPasswordReadiness === "migration-required"
-                ? describeClientPasswordMigrationMessage()
-                : describeClientPasswordSetupMessage(),
-        };
-    }
-    try {
-        const loaded = await loadWalletState({
-            primaryPath: paths.walletStatePath,
-            backupPath: paths.walletStateBackupPath,
-        }, {
-            provider,
-        });
-        const normalized = await normalizeLoadedWalletStateForRead({
-            loaded,
-            access: { provider },
-            dataDir: options.dataDir,
-            now,
-            paths,
-        });
-        return {
-            availability: "ready",
-            clientPasswordReadiness,
-            unlockRequired: false,
-            walletRootId: normalized.state.walletRootId,
-            state: normalizeWalletStateRecord({
-                ...normalized.state,
-                miningState: normalizeMiningStateRecord(normalized.state.miningState),
-            }),
-            source: normalized.source,
-            hasPrimaryStateFile,
-            hasBackupStateFile,
-            message: null,
-        };
-    }
-    catch (error) {
-        const resolvedRoot = await resolveWalletRootIdFromLocalArtifacts({
-            paths,
-            provider,
-        }).catch(() => null);
-        const message = error instanceof Error ? error.message : String(error);
-        return {
-            availability: "local-state-corrupt",
-            clientPasswordReadiness,
-            unlockRequired: message === "wallet_client_password_locked",
-            walletRootId: resolvedRoot?.walletRootId ?? null,
-            state: null,
-            source: null,
-            hasPrimaryStateFile,
-            hasBackupStateFile,
-            message: isWalletAccessError(error)
-                ? describeWalletAccessMessage({ accessError: error })
-                : error instanceof Error
-                    ? error.message
-                    : String(error),
-        };
-    }
-}
-async function readFundingSpendableSats(options) {
-    if (options.state === null || options.rpc === null) {
-        return null;
-    }
-    const state = options.state;
-    try {
-        const utxos = await options.rpc.listUnspent(state.managedCoreWallet.walletName, 1);
-        return utxos.reduce((sum, entry) => isSpendableFundingUtxo(entry, state.funding.scriptPubKeyHex)
-            ? sum + btcAmountToSats(entry.amount)
-            : sum, 0n);
-    }
-    catch {
-        return null;
-    }
-}
 export async function openWalletReadContext(options) {
     const expectedIndexerBinaryVersion = options.expectedIndexerBinaryVersion === undefined
         ? await readPackageVersionFromDisk()
@@ -254,7 +31,7 @@ export async function openWalletReadContext(options) {
         expectedIndexerBinaryVersion,
         now,
     });
-    const fundingSpendableSats = await readFundingSpendableSats({
+    const { fundingDisplaySats, fundingSpendableSats, } = await readFundingBalanceSummary({
         state: localState.state,
         rpc: managedServices.node.rpc,
     });
@@ -281,6 +58,7 @@ export async function openWalletReadContext(options) {
         model: localState.state === null
             ? null
             : createWalletReadModel(localState.state, managedServices.snapshot),
+        fundingDisplaySats,
         fundingSpendableSats,
         mining,
         async close() {
@@ -288,4 +66,4 @@ export async function openWalletReadContext(options) {
         },
     };
 }
-export { inspectWalletLocalState, readSnapshotWithRetry, };
+export { inspectWalletLocalState, };

package/dist/wallet/read/local-state.d.ts

@@ -0,0 +1,36 @@
+import { attachOrStartManagedBitcoindService } from "../../bitcoind/service.js";
+import { createRpcClient } from "../../bitcoind/node.js";
+import { type WalletRuntimePaths } from "../runtime.js";
+import { type WalletSecretProvider } from "../state/provider.js";
+import type { WalletLocalStateStatus } from "./types.js";
+type WalletLocalStateDeps = {
+    attachOrStartManagedBitcoindService: typeof attachOrStartManagedBitcoindService;
+    createRpcClient: typeof createRpcClient;
+};
+export interface FundingBalanceSummary {
+    fundingDisplaySats: bigint | null;
+    fundingSpendableSats: bigint | null;
+}
+export declare function inspectWalletLocalStateWithDependencies(options?: {
+    dataDir?: string;
+    secretProvider?: WalletSecretProvider;
+    now?: number;
+    paths?: WalletRuntimePaths;
+    walletControlLockHeld?: boolean;
+}, dependencies?: WalletLocalStateDeps): Promise<WalletLocalStateStatus>;
+export declare function inspectWalletLocalState(options?: {
+    dataDir?: string;
+    secretProvider?: WalletSecretProvider;
+    now?: number;
+    paths?: WalletRuntimePaths;
+    walletControlLockHeld?: boolean;
+}): Promise<WalletLocalStateStatus>;
+export declare function readFundingSpendableSats(options: {
+    state: WalletLocalStateStatus["state"];
+    rpc: ReturnType<typeof createRpcClient> | null;
+}): Promise<bigint | null>;
+export declare function readFundingBalanceSummary(options: {
+    state: WalletLocalStateStatus["state"];
+    rpc: Pick<ReturnType<typeof createRpcClient>, "listUnspent"> | null;
+}): Promise<FundingBalanceSummary>;
+export {};

package/dist/wallet/read/local-state.js

@@ -0,0 +1,259 @@
+import { access, constants } from "node:fs/promises";
+import { normalizeWalletStateRecord, persistWalletCoinControlStateIfNeeded } from "../coin-control.js";
+import { persistNormalizedWalletDescriptorStateIfNeeded } from "../descriptor-normalization.js";
+import { attachOrStartManagedBitcoindService } from "../../bitcoind/service.js";
+import { createRpcClient } from "../../bitcoind/node.js";
+import { normalizeMiningStateRecord } from "../mining/state.js";
+import { resolveWalletRootIdFromLocalArtifacts } from "../root-resolution.js";
+import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
+import { extractWalletRootIdHintFromWalletStateEnvelope, loadRawWalletStateEnvelope, loadWalletState, } from "../state/storage.js";
+import { createDefaultWalletSecretProvider, createWalletSecretReference, inspectClientPasswordSetupReadiness, } from "../state/provider.js";
+import { describeClientPasswordLockedMessage, describeClientPasswordMigrationMessage, describeClientPasswordSetupMessage, } from "../state/client-password.js";
+const defaultWalletLocalStateDeps = {
+    attachOrStartManagedBitcoindService,
+    createRpcClient,
+};
+function btcAmountToSats(value) {
+    return BigInt(Math.round(value * 100_000_000));
+}
+function isSpendableFundingUtxo(entry, fundingScriptPubKeyHex) {
+    return entry.scriptPubKey === fundingScriptPubKeyHex
+        && entry.confirmations >= 1
+        && entry.spendable !== false
+        && entry.safe !== false;
+}
+function isDisplayFundingUtxo(entry, fundingScriptPubKeyHex) {
+    return entry.scriptPubKey === fundingScriptPubKeyHex
+        && entry.spendable !== false;
+}
+async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isWalletAccessError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.startsWith("wallet_secret_missing_")
+        || message.startsWith("wallet_secret_provider_")
+        || message.startsWith("wallet_client_password_")
+        || message === "wallet_state_legacy_envelope_unsupported";
+}
+function describeWalletAccessMessage(options) {
+    const message = options.accessError instanceof Error ? options.accessError.message : String(options.accessError ?? "");
+    if (message === "wallet_state_legacy_envelope_unsupported") {
+        return "Wallet state exists but was created by an older Cogcoin wallet format that this version no longer loads directly.";
+    }
+    if (message === "wallet_client_password_setup_required") {
+        return describeClientPasswordSetupMessage();
+    }
+    if (message === "wallet_client_password_migration_required") {
+        return describeClientPasswordMigrationMessage();
+    }
+    if (message === "wallet_client_password_locked") {
+        return describeClientPasswordLockedMessage();
+    }
+    if (message.startsWith("wallet_secret_provider_")) {
+        return "Wallet state exists but the local secret provider is unavailable.";
+    }
+    if (message.startsWith("wallet_secret_missing_")) {
+        return "Wallet state exists but its local secret-provider material is unavailable.";
+    }
+    return message.length > 0
+        ? message
+        : "Wallet state exists but could not be loaded from the local secret provider.";
+}
+async function normalizeLoadedWalletStateForRead(options) {
+    if (options.dataDir === undefined) {
+        return options.loaded;
+    }
+    const node = await options.dependencies.attachOrStartManagedBitcoindService({
+        dataDir: options.dataDir,
+        chain: "main",
+        startHeight: 0,
+        walletRootId: options.loaded.state.walletRootId,
+    });
+    try {
+        const access = {
+            provider: options.access.provider,
+            secretReference: createWalletSecretReference(options.loaded.state.walletRootId),
+        };
+        const normalized = await persistNormalizedWalletDescriptorStateIfNeeded({
+            state: options.loaded.state,
+            access,
+            paths: options.paths,
+            nowUnixMs: options.now,
+            replacePrimary: options.loaded.source === "backup",
+            rpc: options.dependencies.createRpcClient(node.rpc),
+        });
+        const coinControl = await persistWalletCoinControlStateIfNeeded({
+            state: normalized.state,
+            access,
+            paths: options.paths,
+            nowUnixMs: options.now,
+            replacePrimary: (normalized.changed ? "primary" : options.loaded.source) === "backup",
+            rpc: options.dependencies.createRpcClient(node.rpc),
+        });
+        return {
+            source: coinControl.changed ? "primary" : normalized.changed ? "primary" : options.loaded.source,
+            state: coinControl.state,
+        };
+    }
+    finally {
+        await node.stop?.().catch(() => undefined);
+    }
+}
+export async function inspectWalletLocalStateWithDependencies(options = {}, dependencies = defaultWalletLocalStateDeps) {
+    const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
+    const now = options.now ?? Date.now();
+    const provider = options.secretProvider ?? createDefaultWalletSecretProvider();
+    const [hasPrimaryStateFile, hasBackupStateFile] = await Promise.all([
+        pathExists(paths.walletStatePath),
+        pathExists(paths.walletStateBackupPath),
+    ]);
+    const clientPasswordReadiness = await inspectClientPasswordSetupReadiness(provider).catch(() => "ready");
+    if (!hasPrimaryStateFile && !hasBackupStateFile) {
+        return {
+            availability: "uninitialized",
+            clientPasswordReadiness,
+            unlockRequired: false,
+            walletRootId: null,
+            state: null,
+            source: null,
+            hasPrimaryStateFile,
+            hasBackupStateFile,
+            message: "Wallet state has not been initialized yet.",
+        };
+    }
+    if (clientPasswordReadiness !== "ready") {
+        const rawEnvelope = await loadRawWalletStateEnvelope({
+            primaryPath: paths.walletStatePath,
+            backupPath: paths.walletStateBackupPath,
+        }).catch(() => null);
+        if (rawEnvelope?.envelope.secretProvider == null) {
+            return {
+                availability: "local-state-corrupt",
+                clientPasswordReadiness: "ready",
+                unlockRequired: false,
+                walletRootId: extractWalletRootIdHintFromWalletStateEnvelope(rawEnvelope?.envelope ?? null),
+                state: null,
+                source: null,
+                hasPrimaryStateFile,
+                hasBackupStateFile,
+                message: "Wallet state exists but was created by an older Cogcoin wallet format that this version no longer loads directly.",
+            };
+        }
+        const resolvedRoot = await resolveWalletRootIdFromLocalArtifacts({
+            paths,
+            provider,
+        }).catch(() => null);
+        return {
+            availability: "local-state-corrupt",
+            clientPasswordReadiness,
+            unlockRequired: false,
+            walletRootId: resolvedRoot?.walletRootId ?? null,
+            state: null,
+            source: null,
+            hasPrimaryStateFile,
+            hasBackupStateFile,
+            message: clientPasswordReadiness === "migration-required"
+                ? describeClientPasswordMigrationMessage()
+                : describeClientPasswordSetupMessage(),
+        };
+    }
+    try {
+        const loaded = await loadWalletState({
+            primaryPath: paths.walletStatePath,
+            backupPath: paths.walletStateBackupPath,
+        }, {
+            provider,
+        });
+        const normalized = await normalizeLoadedWalletStateForRead({
+            loaded,
+            access: { provider },
+            dataDir: options.dataDir,
+            now,
+            paths,
+            dependencies,
+        });
+        return {
+            availability: "ready",
+            clientPasswordReadiness,
+            unlockRequired: false,
+            walletRootId: normalized.state.walletRootId,
+            state: normalizeWalletStateRecord({
+                ...normalized.state,
+                miningState: normalizeMiningStateRecord(normalized.state.miningState),
+            }),
+            source: normalized.source,
+            hasPrimaryStateFile,
+            hasBackupStateFile,
+            message: null,
+        };
+    }
+    catch (error) {
+        const resolvedRoot = await resolveWalletRootIdFromLocalArtifacts({
+            paths,
+            provider,
+        }).catch(() => null);
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            availability: "local-state-corrupt",
+            clientPasswordReadiness,
+            unlockRequired: message === "wallet_client_password_locked",
+            walletRootId: resolvedRoot?.walletRootId ?? null,
+            state: null,
+            source: null,
+            hasPrimaryStateFile,
+            hasBackupStateFile,
+            message: isWalletAccessError(error)
+                ? describeWalletAccessMessage({ accessError: error })
+                : error instanceof Error
+                    ? error.message
+                    : String(error),
+        };
+    }
+}
+export async function inspectWalletLocalState(options = {}) {
+    return inspectWalletLocalStateWithDependencies(options);
+}
+export async function readFundingSpendableSats(options) {
+    return (await readFundingBalanceSummary(options)).fundingSpendableSats;
+}
+export async function readFundingBalanceSummary(options) {
+    if (options.state === null || options.rpc === null) {
+        return {
+            fundingDisplaySats: null,
+            fundingSpendableSats: null,
+        };
+    }
+    const state = options.state;
+    try {
+        const utxos = await options.rpc.listUnspent(state.managedCoreWallet.walletName, 0);
+        let fundingDisplaySats = 0n;
+        let fundingSpendableSats = 0n;
+        for (const entry of utxos) {
+            if (!isDisplayFundingUtxo(entry, state.funding.scriptPubKeyHex)) {
+                continue;
+            }
+            const amountSats = btcAmountToSats(entry.amount);
+            fundingDisplaySats += amountSats;
+            if (isSpendableFundingUtxo(entry, state.funding.scriptPubKeyHex)) {
+                fundingSpendableSats += amountSats;
+            }
+        }
+        return {
+            fundingDisplaySats,
+            fundingSpendableSats,
+        };
+    }
+    catch {
+        return {
+            fundingDisplaySats: null,
+            fundingSpendableSats: null,
+        };
+    }
+}

package/dist/wallet/read/managed-bitcoind.d.ts

@@ -0,0 +1,30 @@
+import { loadBundledGenesisParameters } from "@cogcoin/indexer";
+import type { ManagedWalletNodeConnection } from "../../bitcoind/managed-runtime/types.js";
+import { createRpcClient } from "../../bitcoind/node.js";
+import { attachOrStartManagedBitcoindService, probeManagedBitcoindService } from "../../bitcoind/service.js";
+import type { ManagedBitcoindNodeHandle } from "../../bitcoind/types.js";
+import { verifyManagedCoreWalletReplica } from "../lifecycle.js";
+import type { WalletBitcoindStatus, WalletLocalStateStatus, WalletNodeStatus, WalletServiceHealth } from "./types.js";
+export type ManagedWalletBitcoindReadDeps = {
+    loadBundledGenesisParameters: typeof loadBundledGenesisParameters;
+    probeManagedBitcoindService: typeof probeManagedBitcoindService;
+    attachOrStartManagedBitcoindService: typeof attachOrStartManagedBitcoindService;
+    createRpcClient: typeof createRpcClient;
+    verifyManagedCoreWalletReplica: typeof verifyManagedCoreWalletReplica;
+};
+export interface ManagedWalletBitcoindReadState {
+    node: ManagedWalletNodeConnection<ManagedBitcoindNodeHandle, ReturnType<typeof createRpcClient>>;
+    bitcoind: WalletBitcoindStatus;
+    nodeHealth: WalletServiceHealth;
+    nodeMessage: string | null;
+}
+export declare function deriveNodeHealthForTesting(status: WalletNodeStatus | null, bitcoindHealth: WalletBitcoindStatus["health"]): {
+    health: WalletServiceHealth;
+    message: string | null;
+};
+export declare function openManagedWalletBitcoindReadState(options: {
+    dataDir: string;
+    walletRootId: string;
+    localState: WalletLocalStateStatus;
+    startupTimeoutMs: number;
+}, dependencies?: ManagedWalletBitcoindReadDeps): Promise<ManagedWalletBitcoindReadState>;