@cogcoin/client 1.1.4 → 1.1.6

package/dist/cli/runner.js

@@ -1,6 +1,6 @@
 import { createDefaultContext } from "./context.js";
 import { writeLine } from "./io.js";
-import { classifyCliError, createCommandJsonErrorEnvelope, createErrorEnvelope, formatCliTextError, inferOutputMode, isStructuredOutputMode, writeJsonValue, } from "./output.js";
+import { classifyCliError, formatCliTextError } from "./output.js";
 import { HELP_TEXT, parseCliArgs } from "./parse.js";
 import { runFollowCommand } from "./commands/follow.js";
 import { runClientAdminCommand } from "./commands/client-admin.js";
@@ -15,14 +15,6 @@ import { runWalletAdminCommand } from "./commands/wallet-admin.js";
 import { runWalletMutationCommand } from "./commands/wallet-mutation.js";
 import { runWalletReadCommand } from "./commands/wallet-read.js";
 import { maybeNotifyAboutCliUpdate } from "./update-notifier.js";
-import { findWalletSeedRecord, loadWalletSeedIndex } from "../wallet/state/seed-index.js";
-function commandUsesExistingWalletSeed(parsed) {
-    return parsed.seedName !== null
-        && parsed.seedName !== "main"
-        && parsed.command !== "restore"
-        && parsed.command !== "wallet-delete"
-        && parsed.command !== "wallet-restore";
-}
 export async function runCli(argv, contextOverrides = {}) {
     const context = createDefaultContext(contextOverrides);
     let parsed;
@@ -31,10 +23,6 @@ export async function runCli(argv, contextOverrides = {}) {
     }
     catch (error) {
         const classified = classifyCliError(error);
-        if (isStructuredOutputMode(inferOutputMode(argv))) {
-            writeJsonValue(context.stdout, createErrorEnvelope("cogcoin/cli/v1", `cogcoin ${argv.join(" ")}`.trim(), classified.errorCode, classified.message));
-            return classified.exitCode;
-        }
         writeLine(context.stderr, classified.message);
         writeLine(context.stderr, HELP_TEXT.trimEnd());
         return classified.exitCode;
@@ -44,115 +32,42 @@ export async function runCli(argv, contextOverrides = {}) {
         return 0;
     }
     if (parsed.help || parsed.command === null) {
-        if (parsed.command === null && isStructuredOutputMode(parsed.outputMode)) {
-            writeJsonValue(context.stdout, createErrorEnvelope("cogcoin/cli/v1", "cogcoin", "cli_missing_command", "cli_missing_command"));
-            return 2;
-        }
         writeLine(context.stdout, HELP_TEXT.trimEnd());
         return parsed.help ? 0 : 2;
     }
     await maybeNotifyAboutCliUpdate(parsed, context);
     try {
-        if (parsed.command === "update") {
-            return runUpdateCommand(parsed, context);
-        }
-        if (commandUsesExistingWalletSeed(parsed)) {
-            const mainPaths = context.resolveWalletRuntimePaths("main");
-            const seedIndex = await loadWalletSeedIndex({
-                paths: mainPaths,
-            });
-            if (seedIndex.seeds.length > 0 && findWalletSeedRecord(seedIndex, parsed.seedName) === null) {
-                throw new Error("wallet_seed_not_found");
-            }
-        }
-        if (parsed.command === "sync") {
-            return runSyncCommand(parsed, context);
-        }
-        if (parsed.command === "follow") {
-            return runFollowCommand(parsed, context);
-        }
-        if (parsed.command === "status") {
-            return runStatusCommand(parsed, context);
+        switch (parsed.commandFamily) {
+            case "update":
+                return runUpdateCommand(parsed, context);
+            case "sync":
+                return runSyncCommand(parsed, context);
+            case "follow":
+                return runFollowCommand(parsed, context);
+            case "status":
+                return runStatusCommand(parsed, context);
+            case "client-admin":
+                return runClientAdminCommand(parsed, context);
+            case "service-runtime":
+                return runServiceRuntimeCommand(parsed, context);
+            case "wallet-admin":
+                return runWalletAdminCommand(parsed, context);
+            case "wallet-mutation":
+                return runWalletMutationCommand(parsed, context);
+            case "wallet-read":
+                return runWalletReadCommand(parsed, context);
+            case "mining-admin":
+                return runMiningAdminCommand(parsed, context);
+            case "mining-runtime":
+                return runMiningRuntimeCommand(parsed, context);
+            case "mining-read":
+                return runMiningReadCommand(parsed, context);
+            default:
+                return runWalletReadCommand(parsed, context);
         }
-        if (parsed.command === "client-lock"
-            || parsed.command === "client-unlock"
-            || parsed.command === "client-change-password") {
-            return runClientAdminCommand(parsed, context);
-        }
-        if (parsed.command === "bitcoin-start"
-            || parsed.command === "bitcoin-stop"
-            || parsed.command === "bitcoin-status"
-            || parsed.command === "indexer-start"
-            || parsed.command === "indexer-stop"
-            || parsed.command === "indexer-status") {
-            return runServiceRuntimeCommand(parsed, context);
-        }
-        if (parsed.command === "mine"
-            || parsed.command === "mine-start"
-            || parsed.command === "mine-stop") {
-            return runMiningRuntimeCommand(parsed, context);
-        }
-        if (parsed.command === "mine-setup"
-            || parsed.command === "mine-prompt") {
-            return runMiningAdminCommand(parsed, context);
-        }
-        if (parsed.command === "init"
-            || parsed.command === "restore"
-            || parsed.command === "reset"
-            || parsed.command === "repair"
-            || parsed.command === "wallet-init"
-            || parsed.command === "wallet-delete"
-            || parsed.command === "wallet-restore"
-            || parsed.command === "wallet-show-mnemonic") {
-            return runWalletAdminCommand(parsed, context);
-        }
-        if (parsed.command === "anchor"
-            || parsed.command === "domain-anchor"
-            || parsed.command === "register"
-            || parsed.command === "domain-register"
-            || parsed.command === "transfer"
-            || parsed.command === "domain-transfer"
-            || parsed.command === "sell"
-            || parsed.command === "domain-sell"
-            || parsed.command === "unsell"
-            || parsed.command === "domain-unsell"
-            || parsed.command === "buy"
-            || parsed.command === "domain-buy"
-            || parsed.command === "domain-endpoint-set"
-            || parsed.command === "domain-endpoint-clear"
-            || parsed.command === "domain-delegate-set"
-            || parsed.command === "domain-delegate-clear"
-            || parsed.command === "domain-miner-set"
-            || parsed.command === "domain-miner-clear"
-            || parsed.command === "domain-canonical"
-            || parsed.command === "field-create"
-            || parsed.command === "field-set"
-            || parsed.command === "field-clear"
-            || parsed.command === "bitcoin-transfer"
-            || parsed.command === "send"
-            || parsed.command === "claim"
-            || parsed.command === "reclaim"
-            || parsed.command === "cog-send"
-            || parsed.command === "cog-claim"
-            || parsed.command === "cog-reclaim"
-            || parsed.command === "cog-lock"
-            || parsed.command === "rep-give"
-            || parsed.command === "rep-revoke") {
-            return runWalletMutationCommand(parsed, context);
-        }
-        if (parsed.command === "mine-prompt-list"
-            || parsed.command === "mine-status"
-            || parsed.command === "mine-log") {
-            return runMiningReadCommand(parsed, context);
-        }
-        return runWalletReadCommand(parsed, context);
     }
     catch (error) {
         const classified = classifyCliError(error);
-        if (isStructuredOutputMode(parsed.outputMode)) {
-            writeJsonValue(context.stdout, createCommandJsonErrorEnvelope(parsed, error));
-            return classified.exitCode;
-        }
         const formatted = formatCliTextError(error);
         if (formatted !== null) {
             for (const line of formatted) {

package/dist/cli/types.d.ts

@@ -7,15 +7,15 @@ import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopM
 import { openSqliteStore } from "../sqlite/index.js";
 import type { ClientStoreAdapter } from "../types.js";
 import type { WalletRuntimePaths } from "../wallet/runtime.js";
-import type { WalletPrompter, initializeWallet, deleteImportedWalletSeed, previewResetWallet, repairWallet, resetWallet, restoreWalletFromMnemonic, showWalletMnemonic } from "../wallet/lifecycle.js";
+import type { WalletPrompter, initializeWallet, previewResetWallet, repairWallet, resetWallet, showWalletMnemonic } from "../wallet/lifecycle.js";
 import type { openWalletReadContext } from "../wallet/read/index.js";
 import { loadRawWalletStateEnvelope, loadWalletState } from "../wallet/state/storage.js";
 import type { WalletSecretProvider } from "../wallet/state/provider.js";
 import type { ensureBuiltInMiningSetupIfNeeded, followMiningLog, inspectMiningControlPlane, inspectMiningDomainPromptState, readMiningLog, runForegroundMining, setupBuiltInMining, startBackgroundMining, stopBackgroundMining, updateMiningDomainPrompt } from "../wallet/mining/index.js";
 import type { anchorDomain, transferBitcoin, buyDomain, claimCogLock, clearDomainDelegate, clearDomainEndpoint, clearDomainMiner, clearField, createField, giveReputation, lockCogToDomain, registerDomain, reclaimCogLock, revokeReputation, sendCog, setField, setDomainCanonical, setDomainDelegate, setDomainEndpoint, setDomainMiner, sellDomain, transferDomain } from "../wallet/tx/index.js";
+import type { CommandHandlerFamily, CommandName } from "./command-registry.js";
+export type { CommandHandlerFamily, CommandName } from "./command-registry.js";
 export type ProgressOutput = "auto" | "tty" | "none";
-export type OutputMode = "text" | "json" | "preview-json";
-export type CommandName = "init" | "restore" | "reset" | "repair" | "update" | "sync" | "status" | "client-lock" | "client-change-password" | "client-unlock" | "follow" | "bitcoin-start" | "bitcoin-stop" | "bitcoin-status" | "bitcoin-transfer" | "indexer-start" | "indexer-stop" | "indexer-status" | "anchor" | "domain-anchor" | "register" | "domain-register" | "transfer" | "domain-transfer" | "sell" | "domain-sell" | "unsell" | "domain-unsell" | "buy" | "domain-buy" | "domain-endpoint-set" | "domain-endpoint-clear" | "domain-delegate-set" | "domain-delegate-clear" | "domain-miner-set" | "domain-miner-clear" | "domain-canonical" | "field-list" | "field-show" | "field-create" | "field-set" | "field-clear" | "send" | "claim" | "reclaim" | "cog-send" | "cog-claim" | "cog-reclaim" | "cog-lock" | "rep-give" | "rep-revoke" | "cog-balance" | "cog-locks" | "mine" | "mine-start" | "mine-stop" | "mine-setup" | "mine-prompt" | "mine-prompt-list" | "mine-status" | "mine-log" | "wallet-init" | "wallet-delete" | "wallet-restore" | "wallet-show-mnemonic" | "wallet-status" | "wallet-address" | "wallet-ids" | "address" | "ids" | "balance" | "locks" | "domain-list" | "domains" | "domain-show" | "show" | "fields" | "field";
 export interface WritableLike {
     isTTY?: boolean;
     write(chunk: string): void;
@@ -29,14 +29,15 @@ export interface SignalSource {
 }
 export interface ParsedCliArgs {
     command: CommandName | null;
+    commandFamily: CommandHandlerFamily | null;
+    invokedCommandTokens: readonly string[] | null;
+    invokedCommandPath: string | null;
     args: string[];
     help: boolean;
     version: boolean;
-    outputMode: OutputMode;
     dbPath: string | null;
     dataDir: string | null;
     progressOutput: ProgressOutput;
-    seedName: string | null;
     unlockFor: string | null;
     assumeYes: boolean;
     force: boolean;
@@ -125,9 +126,7 @@ export interface CliRunnerContext {
     loadWalletState?: typeof loadWalletState;
     loadRawWalletStateEnvelope?: typeof loadRawWalletStateEnvelope;
     initializeWallet?: typeof initializeWallet;
-    restoreWalletFromMnemonic?: typeof restoreWalletFromMnemonic;
     previewResetWallet?: typeof previewResetWallet;
-    deleteImportedWalletSeed?: typeof deleteImportedWalletSeed;
     showWalletMnemonic?: typeof showWalletMnemonic;
     registerDomain?: typeof registerDomain;
     anchorDomain?: typeof anchorDomain;
@@ -170,7 +169,7 @@ export interface CliRunnerContext {
     resolveDefaultBitcoindDataDir?: () => string;
     resolveDefaultClientDatabasePath?: () => string;
     resolveUpdateCheckStatePath?: () => string;
-    resolveWalletRuntimePaths?: (seedName?: string | null) => WalletRuntimePaths;
+    resolveWalletRuntimePaths?: () => WalletRuntimePaths;
 }
 export interface StopSignalWatcher {
     cleanup(): void;

package/dist/cli/update-notifier.js

@@ -4,7 +4,7 @@ function isEligibleForUpdateNotification(parsed, context) {
     if (parsed.command === "update") {
         return false;
     }
-    if (parsed.outputMode !== "text" || parsed.help || parsed.version) {
+    if (parsed.help || parsed.version) {
         return false;
     }
     return context.stdout.isTTY === true || context.stderr.isTTY === true;

package/dist/cli/wallet-format.js

@@ -88,7 +88,7 @@ export function getRepairRecommendation(context) {
         return null;
     }
     if (context.localState.availability === "uninitialized") {
-        return "Run `cogcoin init` to create a new local wallet root.";
+        return "Run `cogcoin init` to create or restore a wallet.";
     }
     if (context.localState.availability === "local-state-corrupt") {
         return "Run `cogcoin repair` to recover local wallet state.";

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

@@ -0,0 +1,5 @@
+import type { WalletAccessContext, WalletLoadedState } from "./types.js";
+export declare function isWalletSecretAccessError(error: unknown): boolean;
+export declare function mapWalletReadAccessError(error: unknown): Error;
+export declare function normalizeLoadedWalletStateIfNeeded(options: WalletAccessContext & WalletLoadedState): Promise<WalletLoadedState>;
+export declare function loadWalletStateForAccess(options: WalletAccessContext): Promise<WalletLoadedState>;

package/dist/wallet/lifecycle/access.js

@@ -0,0 +1,79 @@
+import { normalizeWalletStateRecord, persistWalletCoinControlStateIfNeeded, } from "../coin-control.js";
+import { persistNormalizedWalletDescriptorStateIfNeeded } from "../descriptor-normalization.js";
+import { normalizeMiningStateRecord } from "../mining/state.js";
+import { createWalletSecretReference } from "../state/provider.js";
+import { loadWalletState } from "../state/storage.js";
+export function isWalletSecretAccessError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.startsWith("wallet_secret_missing_")
+        || message.startsWith("wallet_secret_provider_");
+}
+export function mapWalletReadAccessError(error) {
+    if (isWalletSecretAccessError(error)) {
+        return new Error("wallet_secret_provider_unavailable");
+    }
+    return new Error("local-state-corrupt");
+}
+export async function normalizeLoadedWalletStateIfNeeded(options) {
+    let state = options.state;
+    let source = options.source;
+    if (options.dataDir !== undefined) {
+        const node = await options.attachService({
+            dataDir: options.dataDir,
+            chain: "main",
+            startHeight: 0,
+            walletRootId: state.walletRootId,
+        });
+        try {
+            const normalizedDescriptorState = await persistNormalizedWalletDescriptorStateIfNeeded({
+                state,
+                access: {
+                    provider: options.provider,
+                    secretReference: createWalletSecretReference(state.walletRootId),
+                },
+                paths: options.paths,
+                nowUnixMs: options.nowUnixMs,
+                replacePrimary: source === "backup",
+                rpc: options.rpcFactory(node.rpc),
+            });
+            state = normalizedDescriptorState.state;
+            source = normalizedDescriptorState.changed ? "primary" : source;
+            const reconciledCoinControl = await persistWalletCoinControlStateIfNeeded({
+                state,
+                access: {
+                    provider: options.provider,
+                    secretReference: createWalletSecretReference(state.walletRootId),
+                },
+                paths: options.paths,
+                nowUnixMs: options.nowUnixMs,
+                replacePrimary: source === "backup",
+                rpc: options.rpcFactory(node.rpc),
+            });
+            state = reconciledCoinControl.state;
+            source = reconciledCoinControl.changed ? "primary" : source;
+        }
+        finally {
+            await node.stop?.().catch(() => undefined);
+        }
+    }
+    return {
+        state: normalizeWalletStateRecord({
+            ...state,
+            miningState: normalizeMiningStateRecord(state.miningState),
+        }),
+        source,
+    };
+}
+export async function loadWalletStateForAccess(options) {
+    const loaded = await loadWalletState({
+        primaryPath: options.paths.walletStatePath,
+        backupPath: options.paths.walletStateBackupPath,
+    }, {
+        provider: options.provider,
+    });
+    return await normalizeLoadedWalletStateIfNeeded({
+        ...options,
+        state: loaded.state,
+        source: loaded.source,
+    });
+}

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

@@ -0,0 +1,26 @@
+import { type WalletRuntimePaths } from "../runtime.js";
+import { type WalletSecretProvider } from "../state/provider.js";
+import type { WalletManagedCoreContext, WalletManagedCoreDependencies, WalletPrompter, WalletRepairContext, WalletRepairDependencies, WalletSetupContext, WalletSetupDependencies } from "./types.js";
+export declare function pathExists(path: string): Promise<boolean>;
+export declare function walletStateExists(paths: WalletRuntimePaths): Promise<boolean>;
+export declare function resolveWalletManagedCoreContext(options: {
+    provider?: WalletSecretProvider;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+} & WalletManagedCoreDependencies): WalletManagedCoreContext;
+export declare function resolveWalletSetupContext(options: {
+    dataDir: string;
+    prompter: WalletPrompter;
+    provider?: WalletSecretProvider;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+} & WalletSetupDependencies): WalletSetupContext;
+export declare function resolveWalletRepairContext(options: {
+    dataDir: string;
+    databasePath: string;
+    provider?: WalletSecretProvider;
+    assumeYes?: boolean;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+} & WalletRepairDependencies): WalletRepairContext;
+export declare function acquireWalletControlLock(paths: WalletRuntimePaths, purpose: "wallet-init" | "wallet-show-mnemonic" | "wallet-repair"): Promise<import("../fs/lock.js").FileLockHandle>;

package/dist/wallet/lifecycle/context.js

@@ -0,0 +1,58 @@
+import { access, constants } from "node:fs/promises";
+import { attachOrStartIndexerDaemon, probeIndexerDaemon, } from "../../bitcoind/indexer-daemon.js";
+import { createRpcClient } from "../../bitcoind/node.js";
+import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, } from "../../bitcoind/service.js";
+import { acquireFileLock } from "../fs/lock.js";
+import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
+import { createDefaultWalletSecretProvider, } from "../state/provider.js";
+export async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function walletStateExists(paths) {
+    const [hasPrimaryState, hasBackupState] = await Promise.all([
+        pathExists(paths.walletStatePath),
+        pathExists(paths.walletStateBackupPath),
+    ]);
+    return hasPrimaryState || hasBackupState;
+}
+export function resolveWalletManagedCoreContext(options) {
+    return {
+        provider: options.provider ?? createDefaultWalletSecretProvider(),
+        paths: options.paths ?? resolveWalletRuntimePathsForTesting(),
+        nowUnixMs: options.nowUnixMs ?? Date.now(),
+        attachService: options.attachService ?? attachOrStartManagedBitcoindService,
+        rpcFactory: options.rpcFactory ?? createRpcClient,
+    };
+}
+export function resolveWalletSetupContext(options) {
+    return {
+        ...resolveWalletManagedCoreContext(options),
+        dataDir: options.dataDir,
+        prompter: options.prompter,
+    };
+}
+export function resolveWalletRepairContext(options) {
+    return {
+        ...resolveWalletManagedCoreContext(options),
+        dataDir: options.dataDir,
+        databasePath: options.databasePath,
+        assumeYes: options.assumeYes ?? false,
+        probeBitcoindService: options.probeBitcoindService ?? probeManagedBitcoindService,
+        attachIndexerDaemon: options.attachIndexerDaemon ?? attachOrStartIndexerDaemon,
+        probeIndexerDaemon: options.probeIndexerDaemon ?? probeIndexerDaemon,
+        requestMiningPreemption: options.requestMiningPreemption,
+        startBackgroundMining: options.startBackgroundMining,
+    };
+}
+export async function acquireWalletControlLock(paths, purpose) {
+    return await acquireFileLock(paths.walletControlLockPath, {
+        purpose,
+        walletRootId: null,
+    });
+}

package/dist/wallet/lifecycle/managed-core.d.ts

@@ -0,0 +1,15 @@
+import { attachOrStartManagedBitcoindService } from "../../bitcoind/service.js";
+import { createRpcClient } from "../../bitcoind/node.js";
+import type { ManagedCoreWalletReplicaStatus } from "../../bitcoind/types.js";
+import type { WalletRuntimePaths } from "../runtime.js";
+import { type WalletSecretProvider } from "../state/provider.js";
+import type { WalletStateV1 } from "../types.js";
+import type { WalletLifecycleRpcClient, WalletManagedCoreDependencies } from "./types.js";
+export declare function sanitizeWalletName(walletRootId: string): string;
+export declare function importDescriptorIntoManagedCoreWallet(state: WalletStateV1, provider: WalletSecretProvider, paths: WalletRuntimePaths, dataDir: string, nowUnixMs: number, attachService?: typeof attachOrStartManagedBitcoindService, rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletLifecycleRpcClient): Promise<WalletStateV1>;
+export declare function recreateManagedCoreWalletReplica(state: WalletStateV1, provider: WalletSecretProvider, paths: WalletRuntimePaths, dataDir: string, nowUnixMs: number, options?: WalletManagedCoreDependencies): Promise<WalletStateV1>;
+export declare function verifyManagedCoreWalletReplica(state: WalletStateV1, dataDir: string, dependencies?: WalletManagedCoreDependencies & {
+    nodeHandle?: {
+        rpc: Parameters<typeof createRpcClient>[0];
+    };
+}): Promise<ManagedCoreWalletReplicaStatus>;

package/dist/wallet/lifecycle/managed-core.js

@@ -0,0 +1,197 @@
+import { rename } from "node:fs/promises";
+import { join } from "node:path";
+import { attachOrStartManagedBitcoindService, createManagedWalletReplica } from "../../bitcoind/service.js";
+import { createRpcClient } from "../../bitcoind/node.js";
+import { resolveNormalizedWalletDescriptorState, } from "../descriptor-normalization.js";
+import { createWalletSecretReference } from "../state/provider.js";
+import { saveWalletState } from "../state/storage.js";
+import { withUnlockedManagedCoreWallet } from "../managed-core-wallet.js";
+import { pathExists } from "./context.js";
+export function sanitizeWalletName(walletRootId) {
+    return `cogcoin-${walletRootId}`.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 63);
+}
+export async function importDescriptorIntoManagedCoreWallet(state, provider, paths, dataDir, nowUnixMs, attachService = attachOrStartManagedBitcoindService, rpcFactory = createRpcClient) {
+    const node = await attachService({
+        dataDir,
+        chain: "main",
+        startHeight: 0,
+        walletRootId: state.walletRootId,
+        managedWalletPassphrase: state.managedCoreWallet.internalPassphrase,
+    });
+    const rpc = rpcFactory(node.rpc);
+    await createManagedWalletReplica(rpc, state.walletRootId, {
+        managedWalletPassphrase: state.managedCoreWallet.internalPassphrase,
+    });
+    const normalizedDescriptors = await resolveNormalizedWalletDescriptorState(state, rpc);
+    const walletName = sanitizeWalletName(state.walletRootId);
+    await withUnlockedManagedCoreWallet({
+        rpc,
+        walletName,
+        internalPassphrase: state.managedCoreWallet.internalPassphrase,
+        run: async () => {
+            const importResults = await rpc.importDescriptors(walletName, [{
+                    desc: normalizedDescriptors.privateExternal,
+                    timestamp: state.walletBirthTime,
+                    active: false,
+                    internal: false,
+                    range: [0, state.descriptor.rangeEnd],
+                }]);
+            if (!importResults.every((result) => result.success)) {
+                throw new Error(`wallet_descriptor_import_failed_${JSON.stringify(importResults)}`);
+            }
+        },
+    });
+    const derivedFunding = await rpc.deriveAddresses(normalizedDescriptors.publicExternal, [0, 0]);
+    if (derivedFunding[0] !== state.funding.address) {
+        throw new Error("wallet_funding_address_verification_failed");
+    }
+    const descriptors = await rpc.listDescriptors(walletName);
+    const importedDescriptor = descriptors.descriptors.find((entry) => entry.desc === normalizedDescriptors.publicExternal);
+    if (importedDescriptor == null) {
+        throw new Error("wallet_descriptor_not_present_after_import");
+    }
+    const verifiedReplica = {
+        walletRootId: state.walletRootId,
+        walletName,
+        loaded: true,
+        descriptors: true,
+        privateKeysEnabled: true,
+        created: false,
+        proofStatus: "ready",
+        descriptorChecksum: normalizedDescriptors.checksum,
+        fundingAddress0: state.funding.address,
+        fundingScriptPubKeyHex0: state.funding.scriptPubKeyHex,
+        message: null,
+    };
+    const nextState = {
+        ...state,
+        stateRevision: state.stateRevision + 1,
+        lastWrittenAtUnixMs: nowUnixMs,
+        descriptor: {
+            ...state.descriptor,
+            privateExternal: normalizedDescriptors.privateExternal,
+            publicExternal: normalizedDescriptors.publicExternal,
+            checksum: normalizedDescriptors.checksum,
+        },
+        managedCoreWallet: {
+            ...state.managedCoreWallet,
+            walletName,
+            descriptorChecksum: normalizedDescriptors.checksum,
+            walletAddress: verifiedReplica.fundingAddress0 ?? null,
+            walletScriptPubKeyHex: verifiedReplica.fundingScriptPubKeyHex0 ?? null,
+            proofStatus: "ready",
+            lastImportedAtUnixMs: nowUnixMs,
+            lastVerifiedAtUnixMs: nowUnixMs,
+        },
+    };
+    await saveWalletState({
+        primaryPath: paths.walletStatePath,
+        backupPath: paths.walletStateBackupPath,
+    }, nextState, {
+        provider,
+        secretReference: createWalletSecretReference(state.walletRootId),
+    });
+    return nextState;
+}
+export async function recreateManagedCoreWalletReplica(state, provider, paths, dataDir, nowUnixMs, options = {}) {
+    const walletName = sanitizeWalletName(state.walletRootId);
+    const walletDir = join(dataDir, "wallets", walletName);
+    const quarantineDir = `${walletDir}.quarantine-${nowUnixMs}`;
+    const node = await (options.attachService ?? attachOrStartManagedBitcoindService)({
+        dataDir,
+        chain: "main",
+        startHeight: 0,
+        walletRootId: state.walletRootId,
+        managedWalletPassphrase: state.managedCoreWallet.internalPassphrase,
+    });
+    const rpc = (options.rpcFactory ?? createRpcClient)(node.rpc);
+    if (rpc.unloadWallet != null) {
+        await rpc.unloadWallet(walletName, false).catch(() => undefined);
+    }
+    if (await pathExists(walletDir)) {
+        await rename(walletDir, quarantineDir).catch(() => undefined);
+    }
+    return importDescriptorIntoManagedCoreWallet({
+        ...state,
+        managedCoreWallet: {
+            ...state.managedCoreWallet,
+            proofStatus: "not-proven",
+        },
+    }, provider, paths, dataDir, nowUnixMs, options.attachService, options.rpcFactory);
+}
+export async function verifyManagedCoreWalletReplica(state, dataDir, dependencies = {}) {
+    const walletName = state.managedCoreWallet.walletName;
+    try {
+        const node = dependencies.nodeHandle ?? await (dependencies.attachService ?? attachOrStartManagedBitcoindService)({
+            dataDir,
+            chain: "main",
+            startHeight: 0,
+            walletRootId: state.walletRootId,
+        });
+        const rpc = (dependencies.rpcFactory ?? createRpcClient)(node.rpc);
+        const info = await rpc.getWalletInfo(walletName);
+        const descriptors = await rpc.listDescriptors(walletName);
+        const matchingDescriptor = state.managedCoreWallet.descriptorChecksum === null
+            ? null
+            : descriptors.descriptors.find((entry) => entry.desc.endsWith(`#${state.managedCoreWallet.descriptorChecksum}`));
+        if (matchingDescriptor == null) {
+            return {
+                walletRootId: state.walletRootId,
+                walletName,
+                loaded: true,
+                descriptors: info.descriptors,
+                privateKeysEnabled: info.private_keys_enabled,
+                created: false,
+                proofStatus: "missing",
+                descriptorChecksum: state.managedCoreWallet.descriptorChecksum,
+                fundingAddress0: state.managedCoreWallet.walletAddress,
+                fundingScriptPubKeyHex0: state.managedCoreWallet.walletScriptPubKeyHex,
+                message: "Expected descriptor is missing from the managed Core wallet.",
+            };
+        }
+        const derived = await rpc.deriveAddresses(state.descriptor.publicExternal, [0, 0]);
+        if (derived[0] !== state.funding.address) {
+            return {
+                walletRootId: state.walletRootId,
+                walletName,
+                loaded: true,
+                descriptors: info.descriptors,
+                privateKeysEnabled: info.private_keys_enabled,
+                created: false,
+                proofStatus: "mismatch",
+                descriptorChecksum: state.managedCoreWallet.descriptorChecksum,
+                fundingAddress0: derived[0] ?? null,
+                fundingScriptPubKeyHex0: null,
+                message: "The managed Core wallet funding address does not match the trusted wallet state.",
+            };
+        }
+        return {
+            walletRootId: state.walletRootId,
+            walletName,
+            loaded: true,
+            descriptors: info.descriptors,
+            privateKeysEnabled: info.private_keys_enabled,
+            created: false,
+            proofStatus: "ready",
+            descriptorChecksum: state.managedCoreWallet.descriptorChecksum,
+            fundingAddress0: state.funding.address,
+            fundingScriptPubKeyHex0: state.funding.scriptPubKeyHex,
+            message: null,
+        };
+    }
+    catch (error) {
+        return {
+            walletRootId: state.walletRootId,
+            walletName,
+            loaded: false,
+            descriptors: false,
+            privateKeysEnabled: false,
+            created: false,
+            proofStatus: "not-proven",
+            descriptorChecksum: state.managedCoreWallet.descriptorChecksum,
+            fundingAddress0: state.managedCoreWallet.walletAddress,
+            fundingScriptPubKeyHex0: state.managedCoreWallet.walletScriptPubKeyHex,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/wallet/lifecycle/repair-bitcoind.d.ts

@@ -0,0 +1,10 @@
+import type { ManagedServicePaths } from "../../bitcoind/service-paths.js";
+import type { WalletStateV1 } from "../types.js";
+import type { WalletBitcoindRepairStageResult, WalletRepairContext } from "./types.js";
+export declare function repairManagedBitcoindStage(options: {
+    context: WalletRepairContext;
+    servicePaths: ManagedServicePaths;
+    state: WalletStateV1;
+    recoveredFromBackup: boolean;
+    repairStateNeedsPersist: boolean;
+}): Promise<WalletBitcoindRepairStageResult>;