@cogcoin/client 1.1.8 → 1.1.10

package/dist/cli/wallet-read-helpers.d.ts

@@ -0,0 +1,6 @@
+import type { WalletFieldView, WalletLockView, WalletReadContext } from "../wallet/read/index.js";
+export declare function listVisibleWalletLocks(context: WalletReadContext, options: {
+    claimableOnly: boolean;
+    reclaimableOnly: boolean;
+}): WalletLockView[] | null;
+export declare function listVisibleDomainFields(context: WalletReadContext, domainName: string): WalletFieldView[] | null;

package/dist/cli/wallet-read-helpers.js

@@ -0,0 +1,17 @@
+import { listDomainFields, listWalletLocks, } from "../wallet/read/index.js";
+export function listVisibleWalletLocks(context, options) {
+    const locks = listWalletLocks(context);
+    if (locks === null) {
+        return null;
+    }
+    if (options.claimableOnly) {
+        return locks.filter((lock) => lock.claimableNow);
+    }
+    if (options.reclaimableOnly) {
+        return locks.filter((lock) => lock.reclaimableNow);
+    }
+    return locks;
+}
+export function listVisibleDomainFields(context, domainName) {
+    return listDomainFields(context, domainName);
+}

package/dist/wallet/mining/candidate.d.ts

@@ -45,7 +45,7 @@ export declare function buildMiningGenerationRequest(options: {
         requiredWords: [string, string, string, string, string];
     }>;
     domainExtraPrompts: Record<string, string>;
-    extraPrompt: string | null;
+    fallbackInstruction: string | null;
 }): MiningSentenceGenerationRequest;
 export declare function generateCandidatesForDomains(options: {
     rpc: MiningRpcClient;

package/dist/wallet/mining/candidate.js

@@ -114,13 +114,13 @@ export function buildMiningGenerationRequest(options) {
         targetBlockHeight: options.targetBlockHeight,
         referencedBlockHashDisplay: options.referencedBlockHashDisplay,
         generatedAtUnixMs: options.generatedAtUnixMs ?? Date.now(),
-        extraPrompt: options.extraPrompt,
+        fallbackInstruction: options.fallbackInstruction,
         limits: createMiningSentenceRequestLimits(),
         rootDomains: options.domains.map((domain) => ({
             domainId: domain.domainId,
             domainName: domain.domainName,
             requiredWords: domain.requiredWords,
-            extraPrompt: options.domainExtraPrompts[domain.domainName.toLowerCase()] ?? null,
+            domainInstruction: options.domainExtraPrompts[domain.domainName.toLowerCase()] ?? null,
         })),
     };
 }
@@ -193,7 +193,7 @@ export async function generateCandidatesForDomains(options) {
             referencedBlockHashDisplay: bestBlockHash,
             domains: rootDomains,
             domainExtraPrompts: clientConfig?.mining.domainExtraPrompts ?? {},
-            extraPrompt: clientConfig?.mining.builtIn?.extraPrompt ?? null,
+            fallbackInstruction: clientConfig?.mining.builtIn?.extraPrompt ?? null,
         });
         let generated;
         try {

package/dist/wallet/mining/constants.d.ts

@@ -10,8 +10,8 @@ export declare const MINING_LOOP_INTERVAL_MS = 2000;
 export declare const MINING_BUILTIN_TIMEOUT_MS = 30000;
 export declare const MINING_SENTENCE_SCHEMA_VERSION: 1;
 export declare const MINING_SENTENCE_MAX_CANDIDATE_SENTENCE_UTF8_BYTES = 512;
-export declare const MINING_SENTENCE_MAX_CANDIDATES_PER_ROOT_DOMAIN = 8;
-export declare const MINING_SENTENCE_MAX_CANDIDATES_TOTAL = 64;
+export declare const MINING_SENTENCE_MAX_CANDIDATES_PER_ROOT_DOMAIN = 25;
+export declare const MINING_SENTENCE_MAX_CANDIDATES_TOTAL = 500;
 export declare const MINING_SENTENCE_TIMEOUT_MS = 30000;
 export declare const MINING_SHUTDOWN_GRACE_MS = 15000;
 export declare const MINING_SETTLEMENT_DUMMY_REWARD = 100n;

package/dist/wallet/mining/constants.js

@@ -10,8 +10,8 @@ export const MINING_LOOP_INTERVAL_MS = 2_000;
 export const MINING_BUILTIN_TIMEOUT_MS = 30_000;
 export const MINING_SENTENCE_SCHEMA_VERSION = 1;
 export const MINING_SENTENCE_MAX_CANDIDATE_SENTENCE_UTF8_BYTES = 512;
-export const MINING_SENTENCE_MAX_CANDIDATES_PER_ROOT_DOMAIN = 8;
-export const MINING_SENTENCE_MAX_CANDIDATES_TOTAL = 64;
+export const MINING_SENTENCE_MAX_CANDIDATES_PER_ROOT_DOMAIN = 25;
+export const MINING_SENTENCE_MAX_CANDIDATES_TOTAL = 500;
 export const MINING_SENTENCE_TIMEOUT_MS = 30_000;
 export const MINING_SHUTDOWN_GRACE_MS = 15_000;
 export const MINING_SETTLEMENT_DUMMY_REWARD = 100n;

package/dist/wallet/mining/engine-types.d.ts

@@ -88,6 +88,7 @@ export type ReadyMiningReadContext = WalletReadContext & {
     snapshot: NonNullable<WalletReadContext["snapshot"]>;
     model: NonNullable<WalletReadContext["model"]>;
 };
+export declare function resolveReadyMiningReadContext(readContext: WalletReadContext): ReadyMiningReadContext | null;
 export interface MiningPublishSkipResult {
     state: WalletStateV1;
     txid: null;

package/dist/wallet/mining/engine-types.js

@@ -1 +1,9 @@
-export {};
+export function resolveReadyMiningReadContext(readContext) {
+    if (readContext.localState.availability !== "ready"
+        || readContext.localState.state === null
+        || readContext.snapshot === null
+        || readContext.model === null) {
+        return null;
+    }
+    return readContext;
+}

package/dist/wallet/mining/publish.js

@@ -6,7 +6,7 @@ import { serializeMine } from "../cogop/index.js";
 import { openWalletReadContext } from "../read/index.js";
 import { assertFixedInputPrefixMatches, buildWalletMutationTransaction, fundAndValidateWalletMutationDraft, isAlreadyAcceptedError, isBroadcastUnknownError, isInsufficientFundsError, outpointKey as walletMutationOutpointKey, reconcilePersistentPolicyLocks, resolveWalletMutationFeeSelection, saveWalletStatePreservingUnlock, } from "../tx/common.js";
 import { createMiningEventRecord } from "./events.js";
-import {} from "./engine-types.js";
+import { resolveReadyMiningReadContext, } from "./engine-types.js";
 import { cloneMiningState, defaultMiningStatePatch, livePublishTargetsCandidateTip, miningCandidateIsCurrent, resolveSharedMiningConflictOutpoint, } from "./engine-state.js";
 import { deriveMiningWordIndices, numberToSats, resolveBip39WordsFromIndices, } from "./engine-utils.js";
 import { clearMiningPublishState, miningPublishMayStillExist, } from "./state.js";
@@ -576,13 +576,10 @@ export async function publishCandidate(options) {
     });
     try {
         options.throwIfStopping?.();
-        if (lockedReadContext.localState.availability !== "ready"
-            || lockedReadContext.localState.state === null
-            || lockedReadContext.snapshot === null
-            || lockedReadContext.model === null) {
+        const readyReadContext = resolveReadyMiningReadContext(lockedReadContext);
+        if (readyReadContext === null) {
             return await createStaleCandidateSkipResult(options.fallbackState);
         }
-        const readyReadContext = lockedReadContext;
         const refreshedCandidate = refreshMiningCandidateFromCurrentState(readyReadContext, options.candidate);
         if (refreshedCandidate === null) {
             return await createStaleCandidateSkipResult(readyReadContext.localState.state);

package/dist/wallet/mining/runner.js

@@ -27,6 +27,7 @@ import { createInsufficientFundsMiningPublishErrorMessage as createInsufficientF
 import { runMiningPhaseMachine } from "./cycle.js";
 import { attemptSaveMempool, handleDetectedMiningRuntimeResume, handleRecoverableMiningBitcoindFailure, isRecoverableMiningBitcoindError, refreshAndSaveMiningRuntimeStatus, resetMiningBitcoindRecoveryState, saveStopSnapshot, } from "./lifecycle.js";
 import { compareLexicographically, deriveMiningWordIndices, getBlockRewardCogtoshi, numberToSats, resolveBip39WordsFromIndices, rootDomain, tieBreakHash, } from "./engine-utils.js";
+import { resolveReadyMiningReadContext } from "./engine-types.js";
 import { isMiningGenerationAbortRequested, markMiningGenerationActive, markMiningGenerationInactive, readMiningGenerationActivity, readMiningPreemptionRequest, requestMiningGenerationPreemption, } from "./coordination.js";
 import { clearMiningPublishState, miningPublishIsInMempool, miningPublishMayStillExist, normalizeMiningPublishState, normalizeMiningStateRecord, } from "./state.js";
 import { runForegroundMining as runForegroundMiningSupervisor, } from "./supervisor.js";
@@ -292,9 +293,20 @@ async function performMiningCycle(options) {
         }
         const displaySats = await resolveFundingDisplaySats(effectiveReadContext.localState.state, rpc).catch(() => null);
         syncMiningVisualizerBalances(options.loopState, effectiveReadContext, displaySats);
-        if (effectiveReadContext.localState.state.miningState.state === "repair-required") {
+        const readyReadContext = resolveReadyMiningReadContext(effectiveReadContext);
+        if (readyReadContext === null) {
             clearMiningProviderWait(options.loopState);
             await saveCycleStatus(effectiveReadContext, {
+                runMode: options.runMode,
+                currentPhase: "waiting-indexer",
+                lastError: null,
+                note: "Mining is waiting for Bitcoin Core and the indexer to align.",
+            });
+            return;
+        }
+        if (readyReadContext.localState.state.miningState.state === "repair-required") {
+            clearMiningProviderWait(options.loopState);
+            await saveCycleStatus(readyReadContext, {
                 runMode: options.runMode,
                 currentPhase: "waiting",
                 lastError: null,
@@ -302,9 +314,9 @@ async function performMiningCycle(options) {
             });
             return;
         }
-        if (hasBlockingMutation(effectiveReadContext.localState.state)) {
+        if (hasBlockingMutation(readyReadContext.localState.state)) {
             clearMiningProviderWait(options.loopState);
-            const nextState = defaultMiningStatePatch(effectiveReadContext.localState.state, {
+            const nextState = defaultMiningStatePatch(readyReadContext.localState.state, {
                 state: "paused",
                 pauseReason: "wallet-busy",
             });
@@ -313,15 +325,15 @@ async function performMiningCycle(options) {
                 provider: options.provider,
                 paths: options.paths,
             });
-            effectiveReadContext = {
-                ...effectiveReadContext,
+            const blockedReadContext = {
+                ...readyReadContext,
                 localState: {
-                    ...effectiveReadContext.localState,
+                    ...readyReadContext.localState,
                     availability: "ready",
                     state: nextState,
                 },
             };
-            await saveCycleStatus(effectiveReadContext, {
+            await saveCycleStatus(blockedReadContext, {
                 runMode: options.runMode,
                 currentPhase: "waiting",
                 lastError: null,
@@ -332,9 +344,9 @@ async function performMiningCycle(options) {
         const preemptionRequest = await readMiningPreemptionRequest(options.paths);
         if (preemptionRequest !== null) {
             clearMiningProviderWait(options.loopState);
-            const nextState = defaultMiningStatePatch(effectiveReadContext.localState.state, {
-                state: effectiveReadContext.localState.state.miningState.livePublishInMempool
-                    && effectiveReadContext.localState.state.miningState.state === "paused-stale"
+            const nextState = defaultMiningStatePatch(readyReadContext.localState.state, {
+                state: readyReadContext.localState.state.miningState.livePublishInMempool
+                    && readyReadContext.localState.state.miningState.state === "paused-stale"
                     ? "paused-stale"
                     : "paused",
                 pauseReason: preemptionRequest.reason,
@@ -345,9 +357,9 @@ async function performMiningCycle(options) {
                 paths: options.paths,
             });
             await saveCycleStatus({
-                ...effectiveReadContext,
+                ...readyReadContext,
                 localState: {
-                    ...effectiveReadContext.localState,
+                    ...readyReadContext.localState,
                     state: nextState,
                 },
             }, {
@@ -370,10 +382,10 @@ async function performMiningCycle(options) {
             network: networkInfo,
             mempool: mempoolInfo,
         });
-        clearRecoveredBitcoindError = resetMiningBitcoindRecoveryState(options.loopState, effectiveReadContext.nodeStatus?.serviceStatus ?? { pid: service.pid });
+        clearRecoveredBitcoindError = resetMiningBitcoindRecoveryState(options.loopState, readyReadContext.nodeStatus?.serviceStatus ?? { pid: service.pid });
         if (targetBlockHeight !== null && getBlockRewardCogtoshi(targetBlockHeight) === 0n) {
             clearMiningProviderWait(options.loopState);
-            const nextState = defaultMiningStatePatch(effectiveReadContext.localState.state, {
+            const nextState = defaultMiningStatePatch(readyReadContext.localState.state, {
                 state: "paused",
                 pauseReason: "zero-reward",
             });
@@ -383,9 +395,9 @@ async function performMiningCycle(options) {
                 paths: options.paths,
             });
             await saveCycleStatus({
-                ...effectiveReadContext,
+                ...readyReadContext,
                 localState: {
-                    ...effectiveReadContext.localState,
+                    ...readyReadContext.localState,
                     state: nextState,
                 },
             }, {
@@ -397,7 +409,7 @@ async function performMiningCycle(options) {
             });
             await appendEvent(options.paths, createEvent("publish-skipped-zero-reward", "Skipped mining because the target block reward is zero.", {
                 targetBlockHeight,
-                referencedBlockHashDisplay: effectiveReadContext.nodeStatus?.nodeBestHashHex ?? null,
+                referencedBlockHashDisplay: readyReadContext.nodeStatus?.nodeBestHashHex ?? null,
                 runId: options.backgroundWorkerRunId,
             }));
             return;
@@ -409,7 +421,7 @@ async function performMiningCycle(options) {
             paths: options.paths,
             runMode: options.runMode,
             backgroundWorkerRunId: options.backgroundWorkerRunId,
-            readContext: effectiveReadContext,
+            readContext: readyReadContext,
             rpc,
             targetBlockHeight,
             tipKey,

package/dist/wallet/mining/sentence-protocol.d.ts

@@ -5,7 +5,7 @@ export interface MiningSentenceGenerationRequestV1 {
     targetBlockHeight: number;
     referencedBlockHashDisplay: string;
     generatedAtUnixMs: number;
-    extraPrompt: string | null;
+    fallbackInstruction: string | null;
     limits: {
         maxCandidatesPerRootDomain: number;
         maxCandidatesTotal: number;
@@ -16,7 +16,7 @@ export interface MiningSentenceGenerationRequestV1 {
         domainId: number;
         domainName: string;
         requiredWords: [string, string, string, string, string];
-        extraPrompt: string | null;
+        domainInstruction: string | null;
     }>;
 }
 export interface MiningSentenceCandidateV1 {

package/dist/wallet/mining/sentences.js

@@ -26,20 +26,20 @@ function createBuiltInProviderTimeoutError(options) {
     const unit = seconds === "1" ? "second" : "seconds";
     return new MiningProviderRequestError("unavailable", `The built-in ${providerName} mining provider timed out after ${seconds} ${unit}.`);
 }
-function buildSystemPrompt(extraPrompt) {
+function buildSystemPrompt(fallbackInstruction) {
     const lines = [
         "You are helping generate candidate Cogcoin mining sentences.",
         "Return only JSON matching the requested response schema.",
         "Every sentence must be a single natural-language sentence.",
         "Do not add commentary, markdown, or code fences.",
         "Do not invent domain IDs or request IDs.",
-        "Each rootDomains entry may include an extraPrompt that applies only to that domain.",
-        "If rootDomains[i].extraPrompt is present, use it only for candidates for that domainId.",
-        "If rootDomains[i].extraPrompt is null, fall back to the request-level extraPrompt when it is present.",
+        "Each rootDomains entry may include a domainInstruction that applies only to that domain.",
+        "If rootDomains[i].domainInstruction is present, use it only for candidates for that domainId.",
+        "If rootDomains[i].domainInstruction is null, fall back to the request-level fallbackInstruction when it is present.",
         "Never apply one domain's prompt to another domain's candidates.",
     ];
-    if (extraPrompt !== null && extraPrompt.trim().length > 0) {
-        lines.push(`Request-level fallback instruction: ${extraPrompt.trim()}`);
+    if (fallbackInstruction !== null && fallbackInstruction.trim().length > 0) {
+        lines.push(`Request-level fallback instruction: ${fallbackInstruction.trim()}`);
     }
     return lines.join("\n");
 }
@@ -162,7 +162,7 @@ async function requestBuiltInSentences(options) {
                     input: [
                         {
                             role: "system",
-                            content: buildSystemPrompt(options.request.extraPrompt),
+                            content: buildSystemPrompt(options.request.fallbackInstruction),
                         },
                         {
                             role: "user",
@@ -209,7 +209,7 @@ async function requestBuiltInSentences(options) {
             body: JSON.stringify({
                 model,
                 max_tokens: 1_200,
-                system: buildSystemPrompt(options.request.extraPrompt),
+                system: buildSystemPrompt(options.request.fallbackInstruction),
                 messages: [
                     {
                         role: "user",

package/dist/wallet/mining/visualizer.js

@@ -64,9 +64,6 @@ function formatRewardCogAmount(value) {
         minFractionDigits: 1,
     })} COG`;
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function consumeWrappedLine(text, capacity) {
     const remaining = text.trimStart();
     if (remaining.length <= capacity) {
@@ -91,12 +88,16 @@ function consumeWrappedLine(text, capacity) {
 function highlightRequiredWords(sentence, requiredWords) {
     const uniqueWords = [...new Set(requiredWords
             .map((word) => word.trim().toLowerCase())
-            .filter((word) => word.length > 0))].sort((left, right) => right.length - left.length);
+            .filter((word) => word.length > 0))];
     if (uniqueWords.length === 0) {
         return sentence;
     }
-    const pattern = new RegExp(`\\b(?:${uniqueWords.map(escapeRegExp).join("|")})\\b`, "gi");
-    return sentence.replace(pattern, (match) => match.toUpperCase());
+    return sentence.replace(/[A-Za-z]+/g, (match) => {
+        const normalizedToken = match.toLowerCase();
+        return uniqueWords.some((word) => normalizedToken.includes(word))
+            ? match.toUpperCase()
+            : match;
+    });
 }
 function formatSentenceSlot(prefix, sentence, requiredWords, lineCount) {
     if (sentence === null) {

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

@@ -1,14 +1,8 @@
-import { readSnapshotWithRetry } from "../../bitcoind/indexer-daemon.js";
+export { readSnapshotWithRetry, } from "../../bitcoind/indexer-daemon.js";
 import { type WalletSecretProvider } from "../state/provider.js";
-import type { WalletLocalStateStatus, WalletReadContext } from "./types.js";
+import { inspectWalletLocalState } from "./local-state.js";
+import type { WalletReadContext } from "./types.js";
 import type { WalletRuntimePaths } from "../runtime.js";
-declare function inspectWalletLocalState(options?: {
-    dataDir?: string;
-    secretProvider?: WalletSecretProvider;
-    now?: number;
-    paths?: WalletRuntimePaths;
-    walletControlLockHeld?: boolean;
-}): Promise<WalletLocalStateStatus>;
 export declare function openWalletReadContext(options: {
     dataDir: string;
     databasePath: string;
@@ -19,4 +13,4 @@ export declare function openWalletReadContext(options: {
     now?: number;
     paths?: WalletRuntimePaths;
 }): Promise<WalletReadContext>;
-export { inspectWalletLocalState, readSnapshotWithRetry, };
+export { inspectWalletLocalState, };

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, readFundingSpendableSats } 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()
@@ -288,4 +65,4 @@ export async function openWalletReadContext(options) {
         },
     };
 }
-export { inspectWalletLocalState, readSnapshotWithRetry, };
+export { inspectWalletLocalState, };

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

@@ -0,0 +1,28 @@
+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 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 {};