@cogcoin/client 1.1.10 → 1.1.11

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

@@ -9,7 +9,7 @@ import { attachOrStartManagedBitcoindRuntime, probeManagedBitcoindRuntime } from
 import { createRpcClient, validateNodeConfigForTesting } from "./node.js";
 import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "./service-paths.js";
 import { DEFAULT_MANAGED_BITCOIND_FOLLOW_POLL_INTERVAL_MS, } from "./types.js";
-import { buildManagedServiceArgsForTesting, LOCAL_HOST, resolveManagedBitcoindRuntimeConfig, SUPPORTED_BITCOIND_VERSION, verifyManagedBitcoindVersion, writeBitcoinConfForTesting, } from "./managed-bitcoind-service-config.js";
+import { buildManagedServiceArgsForTesting, LOCAL_HOST, resolveManagedBitcoindRuntimeConfig, SUPPORTED_BITCOIND_VERSION, verifyManagedBitcoindVersion, writeManagedBitcoindRuntimeConfigFile, writeManagedBitcoindRuntimeConfigFileFromStatus, writeBitcoinConfForTesting, } from "./managed-bitcoind-service-config.js";
 import { DEFAULT_MANAGED_BITCOIND_SHUTDOWN_TIMEOUT_MS, DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS, FileLockBusyError, acquireManagedBitcoindFileLockWithRetry, isManagedBitcoindProcessAlive, waitForManagedBitcoindProcessExit, sleep, } from "./managed-bitcoind-service-process.js";
 import { createManagedWalletReplica, loadManagedWalletReplicaIfPresent, } from "./managed-bitcoind-service-replica.js";
 import { clearManagedBitcoindRuntimeArtifacts, createBitcoindServiceStatus, createManagedBitcoindNodeHandle, probeManagedBitcoindStatusCandidate, refreshManagedBitcoindStatus, waitForManagedBitcoindRpcReady, writeManagedBitcoindStatus, } from "./managed-bitcoind-service-status.js";
@@ -109,6 +109,7 @@ async function tryAttachExistingManagedBitcoindService(options) {
         return null;
     }
     const refreshed = await refreshManagedBitcoindStatus(probe.status, paths, options);
+    await writeManagedBitcoindRuntimeConfigFileFromStatus(paths.bitcoindRuntimeConfigPath, refreshed);
     return createManagedBitcoindNodeHandle({
         status: refreshed,
         paths,
@@ -207,42 +208,47 @@ export async function attachOrStartManagedBitcoindService(options) {
                     }
                     const nowUnixMs = Date.now();
                     const walletReplica = await loadManagedWalletReplicaIfPresent(rpc, startOptions.walletRootId, startOptions.dataDir);
-                    return createBitcoindServiceStatus({
-                        binaryVersion,
-                        serviceInstanceId: randomBytes(16).toString("hex"),
-                        state: "ready",
-                        processId: child.pid ?? null,
-                        walletRootId: startOptions.walletRootId,
-                        chain: startOptions.chain,
-                        dataDir: startOptions.dataDir,
-                        runtimeRoot: paths.walletRuntimeRoot,
-                        startHeight: startOptions.startHeight,
-                        rpc: rpcConfig,
-                        zmq: zmqConfig,
-                        p2pPort: runtimeConfig.p2pPort,
-                        getblockArchiveEndHeight: runtimeConfig.getblockArchiveEndHeight ?? null,
-                        getblockArchiveSha256: runtimeConfig.getblockArchiveSha256 ?? null,
-                        walletReplica,
-                        startedAtUnixMs: nowUnixMs,
-                        heartbeatAtUnixMs: nowUnixMs,
-                        lastError: walletReplica.message ?? null,
-                    });
+                    return {
+                        runtimeConfig,
+                        status: createBitcoindServiceStatus({
+                            binaryVersion,
+                            serviceInstanceId: randomBytes(16).toString("hex"),
+                            state: "ready",
+                            processId: child.pid ?? null,
+                            walletRootId: startOptions.walletRootId,
+                            chain: startOptions.chain,
+                            dataDir: startOptions.dataDir,
+                            runtimeRoot: paths.walletRuntimeRoot,
+                            startHeight: startOptions.startHeight,
+                            rpc: rpcConfig,
+                            zmq: zmqConfig,
+                            p2pPort: runtimeConfig.p2pPort,
+                            getblockArchiveEndHeight: runtimeConfig.getblockArchiveEndHeight ?? null,
+                            getblockArchiveSha256: runtimeConfig.getblockArchiveSha256 ?? null,
+                            walletReplica,
+                            startedAtUnixMs: nowUnixMs,
+                            heartbeatAtUnixMs: nowUnixMs,
+                            lastError: walletReplica.message ?? null,
+                        }),
+                    };
                 };
+                let runtimeConfig;
                 let status;
                 try {
-                    status = await startManagedProcess(runtimeOptions);
+                    ({ runtimeConfig, status } = await startManagedProcess(runtimeOptions));
                 }
                 catch (error) {
                     if (runtimeOptions.getblockArchivePath === undefined || runtimeOptions.getblockArchivePath === null) {
                         throw error;
                     }
-                    status = await startManagedProcess({
+                    ({ runtimeConfig, status } = await startManagedProcess({
                         ...runtimeOptions,
                         getblockArchivePath: null,
                         getblockArchiveEndHeight: null,
                         getblockArchiveSha256: null,
-                    });
+                    }));
                 }
+                await writeManagedBitcoindRuntimeConfigFile(paths.bitcoindRuntimeConfigPath, runtimeConfig);
                 await writeManagedBitcoindStatus(paths, status);
                 return createManagedBitcoindNodeHandle({
                     status,

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

@@ -83,14 +83,6 @@ export async function writeManagedBitcoindStatus(paths, 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);

package/dist/cli/mining-format.js

@@ -1,3 +1,4 @@
+import { resolveWaitingProviderNote } from "../wallet/mining/projection.js";
 function formatMaybeIso(unixMs) {
     return unixMs === null ? "none" : new Date(unixMs).toISOString();
 }
@@ -33,7 +34,11 @@ function resolveInsufficientFundsNextStep() {
 function resolveMiningRuntimeNote(mining) {
     return mining.runtime.currentPublishDecision === "publish-paused-insufficient-funds"
         ? "Insufficient BTC to mine."
-        : mining.runtime.note;
+        : mining.runtime.note !== null
+            ? mining.runtime.note
+            : mining.runtime.currentPhase === "waiting-provider"
+                ? resolveWaitingProviderNote(mining.runtime.providerState)
+                : null;
 }
 export function formatMiningSummaryLine(mining) {
     const provider = mining.provider.configured

package/dist/cli/wallet-format/balance.js

@@ -34,7 +34,7 @@ function renderBalanceArtCard(context) {
             return renderBalanceArtLine(line, "Funding address:", ` ${fundingAddress}`);
         }
         if (line.includes("Bitcoin Balance:")) {
-            return renderBalanceArtLine(line, "Bitcoin Balance:", ` ${formatBitcoinAmount(context.fundingSpendableSats ?? null)}`);
+            return renderBalanceArtLine(line, "Bitcoin Balance:", ` ${formatBitcoinAmount(context.fundingDisplaySats ?? null)}`);
         }
         if (line.includes("Cogcoin Balance:")) {
             return renderBalanceArtLine(line, "Cogcoin Balance:", ` ${formatCogAmount(spendableCog)}`);

package/dist/client/default-client.d.ts

@@ -1,10 +1,12 @@
 import type { BitcoinBlock, GenesisParameters, IndexerState } from "@cogcoin/indexer/types";
-import type { ApplyBlockResult, Client, ClientCheckpoint, ClientStoreAdapter, ClientTip } from "../types.js";
+import type { ApplyBlockResult, Client, ClientCheckpoint, ClientMirrorDelta, ClientMirrorSnapshot, ClientStoreAdapter, ClientTip } from "../types.js";
 export declare class DefaultClient implements Client {
     #private;
     constructor(store: ClientStoreAdapter, genesisParameters: GenesisParameters, state: IndexerState, tip: ClientTip | null, snapshotInterval: number, blockRecordRetention: number);
     getTip(): Promise<ClientTip | null>;
     getState(): Promise<IndexerState>;
+    readMirrorSnapshot(): Promise<ClientMirrorSnapshot>;
+    readMirrorDelta(afterHeight: number): Promise<ClientMirrorDelta>;
     applyBlock(block: BitcoinBlock): Promise<ApplyBlockResult>;
     rewindToHeight(height: number): Promise<ClientTip | null>;
     restoreCheckpoint(checkpoint: ClientCheckpoint): Promise<ClientTip>;

package/dist/client/default-client.js

@@ -26,6 +26,28 @@ export class DefaultClient {
         await this.#queue;
         return this.#state;
     }
+    async readMirrorSnapshot() {
+        return this.#enqueue(async () => {
+            this.#assertOpen();
+            return {
+                tip: this.#tip === null ? null : { ...this.#tip },
+                stateBytes: serializeIndexerState(this.#state),
+            };
+        });
+    }
+    async readMirrorDelta(afterHeight) {
+        return this.#enqueue(async () => {
+            this.#assertOpen();
+            const blockRecords = await this.#store.loadBlockRecordsAfter(afterHeight);
+            return {
+                tip: this.#tip === null ? null : { ...this.#tip },
+                blockRecords: blockRecords.map((record) => ({
+                    ...record,
+                    recordBytes: new Uint8Array(record.recordBytes),
+                })),
+            };
+        });
+    }
     async applyBlock(block) {
         return this.#enqueue(async () => {
             this.#assertOpen();

package/dist/types.d.ts

@@ -19,6 +19,18 @@ export interface StoredBlockRecord {
     recordBytes: Uint8Array;
     createdAt: number;
 }
+export interface ClientMirrorSnapshot {
+    tip: ClientTip | null;
+    stateBytes: Uint8Array;
+}
+export interface ClientMirrorDelta {
+    tip: ClientTip | null;
+    blockRecords: StoredBlockRecord[];
+}
+export interface ClientMirrorReader {
+    readMirrorSnapshot(): Promise<ClientMirrorSnapshot>;
+    readMirrorDelta(afterHeight: number): Promise<ClientMirrorDelta>;
+}
 export interface WriteAppliedBlockEntry {
     tip: ClientTip | null;
     stateBytes: Uint8Array | null;
@@ -48,7 +60,7 @@ export interface ApplyBlockResult {
     checkpoint: ClientCheckpoint | null;
     applied: AppliedBlock;
 }
-export interface Client {
+export interface Client extends ClientMirrorReader {
     getTip(): Promise<ClientTip | null>;
     getState(): Promise<IndexerState>;
     applyBlock(block: BitcoinBlock): Promise<ApplyBlockResult>;

package/dist/wallet/fs/atomic.d.ts

@@ -1,6 +1,15 @@
+import { rename, rm } from "node:fs/promises";
 export interface AtomicWriteOptions {
     mode?: number;
     encoding?: BufferEncoding;
 }
-export declare function writeFileAtomic(filePath: string, data: string | Uint8Array, options?: AtomicWriteOptions): Promise<void>;
-export declare function writeJsonFileAtomic(filePath: string, value: unknown, options?: AtomicWriteOptions): Promise<void>;
+export interface AtomicWriteDependencies {
+    platform?: NodeJS.Platform;
+    rename?: typeof rename;
+    rm?: typeof rm;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+export declare function replaceFileAtomicWithRetryForTesting(tempPath: string, filePath: string, dependencies?: AtomicWriteDependencies): Promise<void>;
+export declare function writeFileAtomic(filePath: string, data: string | Uint8Array, options?: AtomicWriteOptions, dependencies?: AtomicWriteDependencies): Promise<void>;
+export declare function writeJsonFileAtomic(filePath: string, value: unknown, options?: AtomicWriteOptions, dependencies?: AtomicWriteDependencies): Promise<void>;

package/dist/wallet/fs/atomic.js

@@ -1,6 +1,8 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, open, rename } from "node:fs/promises";
+import { mkdir, open, rename, rm } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
+const WINDOWS_REPLACE_RETRY_DELAY_MS = 25;
+const WINDOWS_REPLACE_RETRY_TIMEOUT_MS = 1_000;
 async function fsyncDirectory(directoryPath) {
     try {
         const directoryHandle = await open(directoryPath, "r");
@@ -21,7 +23,39 @@ async function fsyncDirectory(directoryPath) {
         throw error;
     }
 }
-export async function writeFileAtomic(filePath, data, options = {}) {
+function isRetryableWindowsReplaceError(error) {
+    if (!(error instanceof Error) || !("code" in error)) {
+        return false;
+    }
+    const code = error.code;
+    return code === "EPERM" || code === "EACCES" || code === "EBUSY";
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function replaceFileAtomicWithRetryForTesting(tempPath, filePath, dependencies = {}) {
+    const renameImpl = dependencies.rename ?? rename;
+    if ((dependencies.platform ?? process.platform) !== "win32") {
+        await renameImpl(tempPath, filePath);
+        return;
+    }
+    const nowImpl = dependencies.now ?? Date.now;
+    const sleepImpl = dependencies.sleep ?? sleep;
+    const deadline = nowImpl() + WINDOWS_REPLACE_RETRY_TIMEOUT_MS;
+    while (true) {
+        try {
+            await renameImpl(tempPath, filePath);
+            return;
+        }
+        catch (error) {
+            if (!isRetryableWindowsReplaceError(error) || nowImpl() >= deadline) {
+                throw error;
+            }
+            await sleepImpl(WINDOWS_REPLACE_RETRY_DELAY_MS);
+        }
+    }
+}
+export async function writeFileAtomic(filePath, data, options = {}, dependencies = {}) {
     const directoryPath = dirname(filePath);
     const tempPath = join(directoryPath, `${basename(filePath)}.tmp-${randomUUID()}`);
     await mkdir(directoryPath, { recursive: true });
@@ -38,9 +72,15 @@ export async function writeFileAtomic(filePath, data, options = {}) {
     finally {
         await handle.close();
     }
-    await rename(tempPath, filePath);
+    try {
+        await replaceFileAtomicWithRetryForTesting(tempPath, filePath, dependencies);
+    }
+    catch (error) {
+        await (dependencies.rm ?? rm)(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
     await fsyncDirectory(directoryPath);
 }
-export async function writeJsonFileAtomic(filePath, value, options = {}) {
-    await writeFileAtomic(filePath, `${JSON.stringify(value, null, 2)}\n`, options);
+export async function writeJsonFileAtomic(filePath, value, options = {}, dependencies = {}) {
+    await writeFileAtomic(filePath, `${JSON.stringify(value, null, 2)}\n`, options, dependencies);
 }

package/dist/wallet/mining/cycle.js

@@ -10,7 +10,7 @@ import { MiningProviderRequestError } from "./sentences.js";
 import { isInsufficientFundsError } from "../tx/common.js";
 import { attachOrStartManagedBitcoindService } from "../../bitcoind/service.js";
 import { createRpcClient } from "../../bitcoind/node.js";
-import { buildPrePublishStatusOverrides, } from "./projection.js";
+import { buildPrePublishStatusOverrides, resolveWaitingProviderNote, } from "./projection.js";
 function createInitialState(options) {
     return {
         phase: "idle",
@@ -149,7 +149,7 @@ export async function runMiningPhaseMachine(options) {
                             currentPublishDecision: null,
                             providerState: options.loopState.providerWaitState,
                             lastError: options.loopState.providerWaitLastError,
-                            note: "Mining is waiting for the sentence provider to recover.",
+                            note: resolveWaitingProviderNote(options.loopState.providerWaitState),
                         });
                         return;
                     }
@@ -162,7 +162,7 @@ export async function runMiningPhaseMachine(options) {
                             currentPublishDecision: null,
                             providerState: options.loopState.providerWaitState,
                             lastError: options.loopState.providerWaitLastError,
-                            note: "Mining is waiting for the sentence provider to recover.",
+                            note: resolveWaitingProviderNote(options.loopState.providerWaitState),
                         });
                         return;
                     }
@@ -231,7 +231,7 @@ export async function runMiningPhaseMachine(options) {
                             currentPublishDecision: null,
                             providerState: options.loopState.providerWaitState ?? error.providerState,
                             lastError: error.message,
-                            note: "Mining is waiting for the sentence provider to recover.",
+                            note: resolveWaitingProviderNote(options.loopState.providerWaitState ?? error.providerState),
                         });
                         await options.appendEvent(createMiningEventRecord("publish-paused-provider", error.message, {
                             level: "warn",

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

@@ -37,6 +37,7 @@ export interface MiningRuntimeStatusOverrides {
     note?: string | null;
     livePublishInMempool?: boolean | null;
 }
+export declare function resolveWaitingProviderNote(providerState: MiningRuntimeStatusV1["providerState"] | null): string;
 export declare function buildPrePublishStatusOverrides(options: {
     state: WalletStateV1;
     candidate: MiningCandidate;

package/dist/wallet/mining/projection.js

@@ -1,6 +1,20 @@
 import { livePublishTargetsCandidateTip } from "./engine-state.js";
 import { normalizeMiningPublishState, normalizeMiningStateRecord } from "./state.js";
 import { MINING_WORKER_API_VERSION, MINING_WORKER_HEARTBEAT_STALE_MS, } from "./constants.js";
+export function resolveWaitingProviderNote(providerState) {
+    switch (providerState) {
+        case "backoff":
+            return "Mining is waiting because the sentence provider had a transient failure and will be retried automatically.";
+        case "rate-limited":
+            return "Mining is waiting because the sentence provider is rate limited and will be retried automatically.";
+        case "auth-error":
+            return "Mining is waiting because the sentence provider rejected the configured API key.";
+        case "not-found":
+            return "Mining is waiting because the configured sentence-provider model was not found.";
+        default:
+            return "Mining is waiting for the sentence provider to recover.";
+    }
+}
 export function buildPrePublishStatusOverrides(options) {
     const replacing = options.state.miningState.currentTxid !== null;
     const replacingAcrossTips = replacing && !livePublishTargetsCandidateTip({
@@ -249,7 +263,7 @@ export async function buildMiningRuntimeStatusSnapshot(options) {
             : existing?.currentPhase === "resuming"
                 ? "Mining discarded stale in-flight work after a large local runtime gap and is rechecking health."
                 : reuseExistingProviderWait
-                    ? "Mining is waiting for the sentence provider to recover."
+                    ? resolveWaitingProviderNote(existing?.providerState ?? providerState)
                     : existing?.currentPhase === "waiting-indexer"
                         ? "Mining is waiting for Bitcoin Core and the indexer to align."
                         : existing?.currentPhase === "waiting-bitcoin-network"

package/dist/wallet/mining/visualizer-sync.js

@@ -1,8 +1,9 @@
 import { getBalance, getBlockWinners, lookupDomainById, } from "@cogcoin/indexer/queries";
 import { displayToInternalBlockhash } from "@cogcoin/scoring";
 import { FOLLOW_VISIBLE_PRIOR_BLOCKS } from "../../bitcoind/client/follow-block-times.js";
+import { readFundingBalanceSummary } from "../read/local-state.js";
 import { buildMiningTipKey, resetMiningUiForTip } from "./engine-state.js";
-import { deriveMiningWordIndices, numberToSats, resolveBip39WordsFromIndices, } from "./engine-utils.js";
+import { deriveMiningWordIndices, resolveBip39WordsFromIndices, } from "./engine-utils.js";
 import { createEmptyMiningFollowVisualizerState } from "./visualizer.js";
 function cloneSettledBoardEntries(entries) {
     return entries.map((entry) => ({
@@ -156,14 +157,11 @@ export function syncMiningUiForCurrentTip(options) {
     };
 }
 export async function resolveFundingDisplaySats(state, rpc) {
-    const utxos = await rpc.listUnspent(state.managedCoreWallet.walletName, 0);
-    return utxos.reduce((sum, entry) => {
-        if (entry.scriptPubKey !== state.funding.scriptPubKeyHex
-            || entry.spendable === false) {
-            return sum;
-        }
-        return sum + numberToSats(entry.amount);
-    }, 0n);
+    const summary = await readFundingBalanceSummary({
+        state,
+        rpc,
+    });
+    return summary.fundingDisplaySats ?? 0n;
 }
 export async function loadMiningVisibleFollowBlockTimes(options) {
     if (options.indexedTipHeight === null || options.indexedTipHashHex === null) {

package/dist/wallet/mining/visualizer.js

@@ -3,6 +3,7 @@ import { centerLine, normalizeInlineText, truncateLine } from "../../bitcoind/pr
 import { advanceFollowSceneState, createFollowSceneState, replaceFollowBlockTimes, syncFollowSceneState, } from "../../bitcoind/progress/follow-scene.js";
 import { DEFAULT_RENDER_CLOCK, resolveTtyRenderPolicy, TtyRenderThrottle, } from "../../bitcoind/progress/render-policy.js";
 import { TtyProgressRenderer } from "../../bitcoind/progress/tty-renderer.js";
+import { resolveWaitingProviderNote } from "./projection.js";
 const MINING_ARTWORK_COG_WIDTH = 22;
 const MINING_SENTENCE_BOARD_SIZE = 5;
 const MINING_SENTENCE_BOARD_WRAP_WIDTH = 80;
@@ -282,7 +283,7 @@ export function describeMiningVisualizerProgress(snapshot) {
         case "resuming":
             return "Mining discarded stale in-flight work after a large local runtime gap and is rechecking health.";
         case "waiting-provider":
-            return "Mining is waiting for the sentence provider to recover.";
+            return resolveWaitingProviderNote(snapshot.providerState);
         case "waiting-indexer":
             return "Mining is waiting for Bitcoin Core and the indexer to align.";
         case "waiting-bitcoin-network":

package/dist/wallet/read/context.js

@@ -5,7 +5,7 @@ import { inspectMiningControlPlane } from "../mining/index.js";
 import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
 import { createDefaultWalletSecretProvider, } from "../state/provider.js";
 import { openManagedWalletReadServiceBundle } from "./managed-services.js";
-import { inspectWalletLocalState, readFundingSpendableSats } from "./local-state.js";
+import { inspectWalletLocalState, readFundingBalanceSummary } from "./local-state.js";
 import { createWalletReadModel } from "./project.js";
 const DEFAULT_SERVICE_START_TIMEOUT_MS = 60_000;
 export async function openWalletReadContext(options) {
@@ -31,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,
     });
@@ -58,6 +58,7 @@ export async function openWalletReadContext(options) {
         model: localState.state === null
             ? null
             : createWalletReadModel(localState.state, managedServices.snapshot),
+        fundingDisplaySats,
         fundingSpendableSats,
         mining,
         async close() {

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

@@ -7,6 +7,10 @@ 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;
@@ -25,4 +29,8 @@ 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

@@ -22,6 +22,10 @@ function isSpendableFundingUtxo(entry, fundingScriptPubKeyHex) {
         && 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);
@@ -217,17 +221,39 @@ 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 null;
+        return {
+            fundingDisplaySats: null,
+            fundingSpendableSats: 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);
+        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 null;
+        return {
+            fundingDisplaySats: null,
+            fundingSpendableSats: null,
+        };
     }
 }

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

@@ -94,6 +94,7 @@ export interface WalletReadContext {
     indexer: WalletIndexerStatus;
     snapshot: WalletSnapshotView | null;
     model: WalletReadModel | null;
+    fundingDisplaySats: bigint | null;
     fundingSpendableSats: bigint | null;
     mining?: MiningControlPlaneView;
     close(): Promise<void>;

package/package.json

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