@cogcoin/client 0.5.5 → 0.5.6

package/dist/wallet/reset.d.ts

@@ -1,9 +1,12 @@
+import { createRpcClient } from "../bitcoind/node.js";
+import { attachOrStartManagedBitcoindService } from "../bitcoind/service.js";
 import { type WalletRuntimePaths } from "./runtime.js";
 import { type WalletSecretProvider } from "./state/provider.js";
 import type { WalletPrompter } from "./lifecycle.js";
-export type WalletResetAction = "not-present" | "kept-unchanged" | "reset-base-entropy" | "deleted";
+export type WalletResetAction = "not-present" | "kept-unchanged" | "retain-mnemonic" | "deleted";
 export type WalletResetSecretCleanupStatus = "deleted" | "not-found" | "failed" | "unknown";
 export type WalletResetSnapshotResultStatus = "not-present" | "invalid-removed" | "deleted" | "preserved";
+export type WalletResetBitcoinDataDirResultStatus = "not-present" | "preserved" | "deleted" | "outside-reset-scope";
 export interface WalletResetResult {
     dataRoot: string;
     factoryResetReady: true;
@@ -24,13 +27,17 @@ export interface WalletResetResult {
         status: WalletResetSnapshotResultStatus;
         path: string;
     };
+    bitcoinDataDir: {
+        status: WalletResetBitcoinDataDirResultStatus;
+        path: string;
+    };
     removedPaths: string[];
 }
 export interface WalletResetPreview {
     dataRoot: string;
     confirmationPhrase: "permanently reset";
     walletPrompt: null | {
-        defaultAction: "reset-base-entropy";
+        defaultAction: "retain-mnemonic";
         acceptedInputs: ["", "skip", "delete wallet"];
         entropyRetainingResetAvailable: boolean;
         requiresPassphrase: boolean;
@@ -41,10 +48,59 @@ export interface WalletResetPreview {
         path: string;
         defaultAction: "preserve" | "delete";
     };
+    bitcoinDataDir: {
+        status: "not-present" | "within-reset-scope" | "outside-reset-scope";
+        path: string;
+        conditionalPrompt: null | {
+            prompt: "Delete managed Bitcoin datadir too? [y/N]: ";
+            defaultAction: "preserve";
+            acceptedInputs: ["", "n", "no", "y", "yes"];
+        };
+    };
     trackedProcessKinds: Array<"managed-bitcoind" | "indexer-daemon" | "background-mining">;
     willDeleteOsSecrets: boolean;
     removedPaths: string[];
 }
+interface ResetWalletRpcClient {
+    getDescriptorInfo(descriptor: string): Promise<{
+        descriptor: string;
+        checksum: string;
+    }>;
+    createWallet(walletName: string, options: {
+        blank: boolean;
+        descriptors: boolean;
+        disablePrivateKeys: boolean;
+        loadOnStartup: boolean;
+        passphrase: string;
+    }): Promise<unknown>;
+    walletPassphrase(walletName: string, passphrase: string, timeoutSeconds: number): Promise<null>;
+    importDescriptors(walletName: string, requests: Array<{
+        desc: string;
+        timestamp: string | number;
+        active?: boolean;
+        internal?: boolean;
+        range?: number | [number, number];
+    }>): Promise<Array<{
+        success: boolean;
+    }>>;
+    walletLock(walletName: string): Promise<null>;
+    deriveAddresses(descriptor: string, range?: number | [number, number]): Promise<string[]>;
+    listDescriptors(walletName: string, privateOnly?: boolean): Promise<{
+        descriptors: Array<{
+            desc: string;
+        }>;
+    }>;
+    getWalletInfo(walletName: string): Promise<{
+        walletname: string;
+        private_keys_enabled: boolean;
+        descriptors: boolean;
+    }>;
+    loadWallet(walletName: string, loadOnStartup?: boolean): Promise<{
+        name: string;
+        warning: string;
+    }>;
+    listWallets(): Promise<string[]>;
+}
 export declare function previewResetWallet(options: {
     dataDir: string;
     provider?: WalletSecretProvider;
@@ -58,4 +114,7 @@ export declare function resetWallet(options: {
     nowUnixMs?: number;
     paths?: WalletRuntimePaths;
     validateSnapshotFile?: (path: string) => Promise<void>;
+    attachService?: typeof attachOrStartManagedBitcoindService;
+    rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => ResetWalletRpcClient;
 }): Promise<WalletResetResult>;
+export {};

package/dist/wallet/reset.js

@@ -2,15 +2,18 @@ import { randomBytes } from "node:crypto";
 import { access, constants, copyFile, mkdir, mkdtemp, readFile, readdir, rename, rm } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import { DEFAULT_SNAPSHOT_METADATA } from "../bitcoind/bootstrap/constants.js";
+import { createRpcClient } from "../bitcoind/node.js";
 import { resolveBootstrapPathsForTesting } from "../bitcoind/bootstrap/paths.js";
 import { validateSnapshotFileForTesting } from "../bitcoind/bootstrap/snapshot-file.js";
+import { attachOrStartManagedBitcoindService, createManagedWalletReplica, } from "../bitcoind/service.js";
+import { resolveNormalizedWalletDescriptorState } from "./descriptor-normalization.js";
 import { acquireFileLock } from "./fs/lock.js";
 import { createInternalCoreWalletPassphrase, deriveWalletIdentityMaterial, deriveWalletMaterialFromMnemonic, } from "./material.js";
 import { loadMiningRuntimeStatus } from "./mining/runtime-artifacts.js";
 import { resolveWalletRuntimePathsForTesting } from "./runtime.js";
 import { loadWalletExplicitLock } from "./state/explicit-lock.js";
 import { createDefaultWalletSecretProvider, createWalletRootId, createWalletSecretReference, } from "./state/provider.js";
-import { loadWalletState, saveWalletState } from "./state/storage.js";
+import { extractWalletRootIdHintFromWalletStateEnvelope, loadRawWalletStateEnvelope, loadWalletState, saveWalletState, } from "./state/storage.js";
 import { confirmTypedAcknowledgement } from "./tx/confirm.js";
 function sanitizeWalletName(walletRootId) {
     return `cogcoin-${walletRootId}`.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 63);
@@ -42,41 +45,6 @@ async function readJsonFileOrNull(path) {
         return null;
     }
 }
-async function readWalletEnvelope(path) {
-    try {
-        return JSON.parse(await readFile(path, "utf8"));
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-            return null;
-        }
-        return null;
-    }
-}
-async function loadRawWalletEnvelope(paths) {
-    const primary = await readWalletEnvelope(paths.walletStatePath);
-    if (primary !== null) {
-        return {
-            source: "primary",
-            envelope: primary,
-        };
-    }
-    const backup = await readWalletEnvelope(paths.walletStateBackupPath);
-    if (backup !== null) {
-        return {
-            source: "backup",
-            envelope: backup,
-        };
-    }
-    return null;
-}
-function extractWalletRootIdFromSecretKeyId(keyId) {
-    if (keyId === null) {
-        return null;
-    }
-    const prefix = "wallet-state:";
-    return keyId.startsWith(prefix) ? keyId.slice(prefix.length) : null;
-}
 async function isProcessAlive(pid) {
     if (pid === null) {
         return false;
@@ -300,6 +268,72 @@ function createEntropyRetainedWalletState(previousState, nowUnixMs) {
         pendingMutations: [],
     };
 }
+async function recreateManagedCoreWalletReplicaForReset(options) {
+    const node = await (options.attachService ?? attachOrStartManagedBitcoindService)({
+        dataDir: options.dataDir,
+        chain: "main",
+        startHeight: 0,
+        walletRootId: options.state.walletRootId,
+        managedWalletPassphrase: options.state.managedCoreWallet.internalPassphrase,
+    });
+    const rpc = (options.rpcFactory ?? createRpcClient)(node.rpc);
+    await createManagedWalletReplica(rpc, options.state.walletRootId, {
+        managedWalletPassphrase: options.state.managedCoreWallet.internalPassphrase,
+    });
+    const normalizedDescriptors = await resolveNormalizedWalletDescriptorState(options.state, rpc);
+    const walletName = sanitizeWalletName(options.state.walletRootId);
+    await rpc.walletPassphrase(walletName, options.state.managedCoreWallet.internalPassphrase, 10);
+    try {
+        const importResults = await rpc.importDescriptors(walletName, [{
+                desc: normalizedDescriptors.privateExternal,
+                timestamp: options.state.walletBirthTime,
+                active: false,
+                internal: false,
+                range: [0, options.state.descriptor.rangeEnd],
+            }]);
+        if (!importResults.every((result) => result.success)) {
+            throw new Error(`wallet_descriptor_import_failed_${JSON.stringify(importResults)}`);
+        }
+    }
+    finally {
+        await rpc.walletLock(walletName).catch(() => undefined);
+    }
+    const derivedFunding = await rpc.deriveAddresses(normalizedDescriptors.publicExternal, [0, 0]);
+    if (derivedFunding[0] !== options.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 nextState = {
+        ...options.state,
+        stateRevision: options.state.stateRevision + 1,
+        lastWrittenAtUnixMs: options.nowUnixMs,
+        descriptor: {
+            ...options.state.descriptor,
+            privateExternal: normalizedDescriptors.privateExternal,
+            publicExternal: normalizedDescriptors.publicExternal,
+            checksum: normalizedDescriptors.checksum,
+        },
+        managedCoreWallet: {
+            ...options.state.managedCoreWallet,
+            walletName,
+            descriptorChecksum: normalizedDescriptors.checksum,
+            fundingAddress0: options.state.funding.address,
+            fundingScriptPubKeyHex0: options.state.funding.scriptPubKeyHex,
+            proofStatus: "ready",
+            lastImportedAtUnixMs: options.nowUnixMs,
+            lastVerifiedAtUnixMs: options.nowUnixMs,
+        },
+    };
+    await saveWalletState({
+        primaryPath: options.paths.walletStatePath,
+        backupPath: options.paths.walletStateBackupPath,
+    }, nextState, options.access);
+    return nextState;
+}
 async function promptHiddenOrVisible(prompter, message) {
     if (typeof prompter.promptHidden === "function") {
         return await prompter.promptHidden(message);
@@ -421,22 +455,53 @@ async function collectTrackedManagedProcesses(paths) {
         serviceLockPaths: [...serviceLockPaths].sort(),
     };
 }
-function resolveRemovedRoots(paths) {
+function dedupeSortedPaths(candidates) {
+    return [...new Set(candidates)].sort((left, right) => right.length - left.length);
+}
+function resolveDefaultRemovedRoots(paths) {
+    const configRoot = dirname(paths.clientConfigPath);
+    return dedupeSortedPaths([
+        paths.dataRoot,
+        paths.stateRoot,
+        paths.runtimeRoot,
+        configRoot,
+    ]);
+}
+function resolveBitcoindPreservingRemovedRoots(paths) {
     const configRoot = dirname(paths.clientConfigPath);
-    return [...new Set([
-            paths.dataRoot,
-            paths.stateRoot,
-            paths.runtimeRoot,
-            configRoot,
-        ])].sort((left, right) => right.length - left.length);
+    return dedupeSortedPaths([
+        paths.clientDataDir,
+        paths.indexerRoot,
+        paths.stateRoot,
+        paths.runtimeRoot,
+        configRoot,
+        paths.hooksRoot,
+    ]);
+}
+function resolveRemovedRoots(paths, options = {
+    preserveBitcoinDataDir: false,
+}) {
+    return options.preserveBitcoinDataDir
+        ? resolveBitcoindPreservingRemovedRoots(paths)
+        : resolveDefaultRemovedRoots(paths);
+}
+function isDeletedByRemovalPlan(removedRoots, targetPath) {
+    return removedRoots.some((root) => isPathWithin(root, targetPath));
 }
 async function preflightReset(options) {
-    const rawEnvelope = await loadRawWalletEnvelope(options.paths);
+    const removedRoots = resolveRemovedRoots(options.paths);
+    const rawEnvelope = await loadRawWalletStateEnvelope({
+        primaryPath: options.paths.walletStatePath,
+        backupPath: options.paths.walletStateBackupPath,
+    });
     const explicitLock = await loadWalletExplicitLock(options.paths.walletExplicitLockPath).catch(() => null);
     const snapshotPaths = resolveBootstrapPathsForTesting(options.dataDir, DEFAULT_SNAPSHOT_METADATA);
     const validateSnapshot = options.validateSnapshotFile
         ?? ((path) => validateSnapshotFileForTesting(path, DEFAULT_SNAPSHOT_METADATA));
     const hasWalletState = await pathExists(options.paths.walletStatePath) || await pathExists(options.paths.walletStateBackupPath);
+    const hasBitcoinDataDir = await pathExists(options.dataDir);
+    const bitcoinDataDirWithinResetScope = hasBitcoinDataDir
+        && isDeletedByRemovalPlan(removedRoots, options.dataDir);
     const hasSnapshot = await pathExists(snapshotPaths.snapshotPath);
     const hasPartialSnapshot = await pathExists(snapshotPaths.partialSnapshotPath);
     let snapshotStatus = "not-present";
@@ -456,7 +521,7 @@ async function preflightReset(options) {
     const secretProviderKeyId = rawEnvelope?.envelope.secretProvider?.keyId ?? null;
     return {
         dataRoot: options.paths.dataRoot,
-        removedRoots: resolveRemovedRoots(options.paths),
+        removedRoots,
         wallet: {
             present: hasWalletState,
             mode: rawEnvelope == null
@@ -473,8 +538,16 @@ async function preflightReset(options) {
             status: snapshotStatus,
             path: snapshotPaths.snapshotPath,
             shouldPrompt: snapshotStatus === "valid",
-            shouldStageForPreserve: snapshotStatus === "valid"
-                && resolveRemovedRoots(options.paths).some((root) => isPathWithin(root, snapshotPaths.snapshotPath)),
+            withinResetScope: isDeletedByRemovalPlan(removedRoots, snapshotPaths.snapshotPath),
+        },
+        bitcoinDataDir: {
+            status: !hasBitcoinDataDir
+                ? "not-present"
+                : bitcoinDataDirWithinResetScope
+                    ? "within-reset-scope"
+                    : "outside-reset-scope",
+            path: options.dataDir,
+            shouldPrompt: bitcoinDataDirWithinResetScope,
         },
         trackedProcesses: tracked.trackedProcesses,
         trackedProcessKinds: tracked.trackedProcessKinds,
@@ -515,6 +588,18 @@ async function deleteRemovedRoots(roots) {
         throw new Error("reset_data_root_delete_failed");
     }
 }
+async function deleteBootstrapSnapshotArtifacts(dataDir) {
+    const snapshotPaths = resolveBootstrapPathsForTesting(dataDir, DEFAULT_SNAPSHOT_METADATA);
+    await Promise.all([
+        snapshotPaths.snapshotPath,
+        snapshotPaths.partialSnapshotPath,
+        snapshotPaths.statePath,
+        snapshotPaths.quoteStatePath,
+    ].map(async (path) => rm(path, {
+        recursive: false,
+        force: true,
+    })));
+}
 async function resolveResetExecutionDecision(options) {
     if (!options.prompter.isInteractive) {
         throw new Error("reset_requires_tty");
@@ -544,13 +629,19 @@ async function resolveResetExecutionDecision(options) {
         }
     }
     let deleteSnapshot = false;
+    let deleteBitcoinDataDir = false;
     if (options.preflight.snapshot.shouldPrompt) {
         const answer = (await options.prompter.prompt("Delete downloaded 910000 UTXO snapshot too? [y/N]: ")).trim().toLowerCase();
         deleteSnapshot = answer === "y" || answer === "yes";
+        if (!deleteSnapshot && options.preflight.bitcoinDataDir.shouldPrompt) {
+            const bitcoindAnswer = (await options.prompter.prompt("Delete managed Bitcoin datadir too? [y/N]: ")).trim().toLowerCase();
+            deleteBitcoinDataDir = bitcoindAnswer === "y" || bitcoindAnswer === "yes";
+        }
     }
     return {
         walletChoice,
         deleteSnapshot,
+        deleteBitcoinDataDir,
         loadedWalletForEntropyReset,
     };
 }
@@ -564,7 +655,7 @@ function determineWalletAction(walletPresent, walletChoice) {
     if (walletChoice === "delete wallet") {
         return "deleted";
     }
-    return "reset-base-entropy";
+    return "retain-mnemonic";
 }
 function determineSnapshotResultStatus(options) {
     if (options.snapshotStatus === "not-present") {
@@ -575,6 +666,18 @@ function determineSnapshotResultStatus(options) {
     }
     return options.deleteSnapshot ? "deleted" : "preserved";
 }
+function determineBitcoinDataDirResultStatus(options) {
+    if (options.bitcoinDataDirStatus === "not-present") {
+        return "not-present";
+    }
+    if (options.bitcoinDataDirStatus === "outside-reset-scope") {
+        return "outside-reset-scope";
+    }
+    if (options.deleteSnapshot || options.deleteBitcoinDataDir) {
+        return "deleted";
+    }
+    return "preserved";
+}
 export async function previewResetWallet(options) {
     const provider = options.provider ?? createDefaultWalletSecretProvider();
     const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
@@ -584,12 +687,15 @@ export async function previewResetWallet(options) {
         paths,
         validateSnapshotFile: options.validateSnapshotFile,
     });
+    const removedPaths = resolveRemovedRoots(paths, {
+        preserveBitcoinDataDir: preflight.snapshot.status === "valid" && preflight.bitcoinDataDir.shouldPrompt,
+    });
     return {
         dataRoot: preflight.dataRoot,
         confirmationPhrase: "permanently reset",
         walletPrompt: preflight.wallet.present
             ? {
-                defaultAction: "reset-base-entropy",
+                defaultAction: "retain-mnemonic",
                 acceptedInputs: ["", "skip", "delete wallet"],
                 entropyRetainingResetAvailable: preflight.wallet.mode !== "unknown",
                 requiresPassphrase: preflight.wallet.mode === "passphrase-wrapped",
@@ -601,9 +707,20 @@ export async function previewResetWallet(options) {
             path: preflight.snapshot.path,
             defaultAction: preflight.snapshot.status === "valid" ? "preserve" : "delete",
         },
+        bitcoinDataDir: {
+            status: preflight.bitcoinDataDir.status,
+            path: preflight.bitcoinDataDir.path,
+            conditionalPrompt: preflight.bitcoinDataDir.shouldPrompt
+                ? {
+                    prompt: "Delete managed Bitcoin datadir too? [y/N]: ",
+                    defaultAction: "preserve",
+                    acceptedInputs: ["", "n", "no", "y", "yes"],
+                }
+                : null,
+        },
         trackedProcessKinds: preflight.trackedProcessKinds,
         willDeleteOsSecrets: preflight.wallet.secretProviderKeyId !== null,
-        removedPaths: preflight.removedRoots,
+        removedPaths,
     };
 }
 export async function resetWallet(options) {
@@ -627,6 +744,14 @@ export async function resetWallet(options) {
         snapshotStatus: preflight.snapshot.status,
         deleteSnapshot: decision.deleteSnapshot,
     });
+    const bitcoinDataDirResultStatus = determineBitcoinDataDirResultStatus({
+        bitcoinDataDirStatus: preflight.bitcoinDataDir.status,
+        deleteSnapshot: decision.deleteSnapshot,
+        deleteBitcoinDataDir: decision.deleteBitcoinDataDir,
+    });
+    const removedPaths = resolveRemovedRoots(paths, {
+        preserveBitcoinDataDir: bitcoinDataDirResultStatus === "preserved",
+    });
     const locks = await acquireResetLocks(paths, preflight.serviceLockPaths);
     await mkdir(dirname(paths.dataRoot), { recursive: true });
     const stagingRoot = await mkdtemp(join(dirname(paths.dataRoot), ".cogcoin-reset-"));
@@ -647,13 +772,13 @@ export async function resetWallet(options) {
     const deletedSecretRefs = [];
     const failedSecretRefs = [];
     const preservedSecretRefs = [];
-    let walletOldRootId = extractWalletRootIdFromSecretKeyId(preflight.wallet.secretProviderKeyId)
+    let walletOldRootId = extractWalletRootIdHintFromWalletStateEnvelope(preflight.wallet.rawEnvelope?.envelope ?? null)
         ?? preflight.wallet.explicitLock?.walletRootId
         ?? null;
     let walletNewRootId = null;
     try {
         stoppedProcesses = await terminateTrackedProcesses(preflight.trackedProcesses);
-        if (walletAction === "kept-unchanged" || walletAction === "reset-base-entropy") {
+        if (walletAction === "kept-unchanged" || walletAction === "retain-mnemonic") {
             const stagedPrimary = await stageArtifact(paths.walletStatePath, stagingRoot, "wallet/wallet-state.enc");
             const stagedBackup = await stageArtifact(paths.walletStateBackupPath, stagingRoot, "wallet/wallet-state.enc.bak");
             const stagedExplicitLock = await stageArtifact(paths.walletExplicitLockPath, stagingRoot, "wallet/wallet-explicit-lock.json");
@@ -667,43 +792,59 @@ export async function resetWallet(options) {
                 stagedWalletArtifacts.push(stagedExplicitLock);
             }
         }
-        if (snapshotResultStatus === "preserved" && preflight.snapshot.shouldStageForPreserve) {
+        if (snapshotResultStatus === "preserved" && isDeletedByRemovalPlan(removedPaths, preflight.snapshot.path)) {
             const stagedSnapshot = await stageArtifact(preflight.snapshot.path, stagingRoot, "snapshot/utxo-910000.dat");
             if (stagedSnapshot !== null) {
                 stagedSnapshotArtifacts.push(stagedSnapshot);
             }
         }
-        await deleteRemovedRoots(preflight.removedRoots);
+        await deleteRemovedRoots(removedPaths);
         rootsDeleted = true;
+        if ((snapshotResultStatus === "deleted" || snapshotResultStatus === "invalid-removed")
+            && !isDeletedByRemovalPlan(removedPaths, preflight.snapshot.path)) {
+            await deleteBootstrapSnapshotArtifacts(options.dataDir);
+        }
         if (walletAction === "kept-unchanged") {
             await restoreStagedArtifacts(stagedWalletArtifacts);
         }
-        else if (walletAction === "reset-base-entropy") {
+        else if (walletAction === "retain-mnemonic") {
             if (decision.loadedWalletForEntropyReset === null) {
                 throw new Error("reset_wallet_entropy_reset_unavailable");
             }
-            const nextState = createEntropyRetainedWalletState(decision.loadedWalletForEntropyReset.loaded.state, nowUnixMs);
+            let nextState = createEntropyRetainedWalletState(decision.loadedWalletForEntropyReset.loaded.state, nowUnixMs);
             walletOldRootId = decision.loadedWalletForEntropyReset.loaded.state.walletRootId;
             walletNewRootId = nextState.walletRootId;
+            let nextAccess;
             if (decision.loadedWalletForEntropyReset.access.kind === "provider") {
                 const secretReference = createWalletSecretReference(nextState.walletRootId);
                 newProviderKeyId = secretReference.keyId;
                 await provider.storeSecret(secretReference.keyId, randomBytes(32));
+                nextAccess = {
+                    provider,
+                    secretReference,
+                };
                 await saveWalletState({
                     primaryPath: paths.walletStatePath,
                     backupPath: paths.walletStateBackupPath,
-                }, nextState, {
-                    provider,
-                    secretReference,
-                });
+                }, nextState, nextAccess);
                 preservedSecretRefs.push(secretReference.keyId);
             }
             else {
+                nextAccess = decision.loadedWalletForEntropyReset.access.passphrase;
                 await saveWalletState({
                     primaryPath: paths.walletStatePath,
                     backupPath: paths.walletStateBackupPath,
-                }, nextState, decision.loadedWalletForEntropyReset.access.passphrase);
+                }, nextState, nextAccess);
             }
+            nextState = await recreateManagedCoreWalletReplicaForReset({
+                state: nextState,
+                access: nextAccess,
+                paths,
+                dataDir: options.dataDir,
+                nowUnixMs,
+                attachService: options.attachService,
+                rpcFactory: options.rpcFactory,
+            });
         }
         if (snapshotResultStatus === "preserved") {
             await restoreStagedArtifacts(stagedSnapshotArtifacts);
@@ -723,7 +864,7 @@ export async function resetWallet(options) {
                 }
             }
         }
-        else if (walletAction === "reset-base-entropy" && preflight.wallet.secretProviderKeyId !== null) {
+        else if (walletAction === "retain-mnemonic" && preflight.wallet.secretProviderKeyId !== null) {
             try {
                 if (preflight.wallet.secretProviderKeyId !== newProviderKeyId) {
                     await provider.deleteSecret(preflight.wallet.secretProviderKeyId);
@@ -761,7 +902,11 @@ export async function resetWallet(options) {
                 status: snapshotResultStatus,
                 path: preflight.snapshot.path,
             },
-            removedPaths: preflight.removedRoots,
+            bitcoinDataDir: {
+                status: bitcoinDataDirResultStatus,
+                path: preflight.bitcoinDataDir.path,
+            },
+            removedPaths,
         };
     }
     catch (error) {

package/dist/wallet/root-resolution.d.ts

@@ -0,0 +1,20 @@
+import type { WalletRuntimePaths } from "./runtime.js";
+import { loadWalletExplicitLock } from "./state/explicit-lock.js";
+import type { WalletSecretProvider } from "./state/provider.js";
+import { loadUnlockSession } from "./state/session.js";
+import { type RawWalletStateEnvelope } from "./state/storage.js";
+export type WalletRootResolutionSource = "wallet-state" | "unlock-session" | "explicit-lock" | "default-uninitialized";
+export interface WalletRootResolution {
+    walletRootId: string;
+    source: WalletRootResolutionSource;
+}
+export declare function resolveWalletRootIdFromLocalArtifacts(options: {
+    paths: WalletRuntimePaths;
+    provider: WalletSecretProvider;
+    loadRawWalletStateEnvelope?: (paths: {
+        primaryPath: string;
+        backupPath: string;
+    }) => Promise<RawWalletStateEnvelope | null>;
+    loadUnlockSession?: typeof loadUnlockSession;
+    loadWalletExplicitLock?: typeof loadWalletExplicitLock;
+}): Promise<WalletRootResolution>;

package/dist/wallet/root-resolution.js

@@ -0,0 +1,37 @@
+import { UNINITIALIZED_WALLET_ROOT_ID } from "../bitcoind/service-paths.js";
+import { loadWalletExplicitLock } from "./state/explicit-lock.js";
+import { loadUnlockSession } from "./state/session.js";
+import { extractWalletRootIdHintFromWalletStateEnvelope, loadRawWalletStateEnvelope, } from "./state/storage.js";
+export async function resolveWalletRootIdFromLocalArtifacts(options) {
+    const rawEnvelope = await (options.loadRawWalletStateEnvelope ?? loadRawWalletStateEnvelope)({
+        primaryPath: options.paths.walletStatePath,
+        backupPath: options.paths.walletStateBackupPath,
+    }).catch(() => null);
+    const walletStateRootId = extractWalletRootIdHintFromWalletStateEnvelope(rawEnvelope?.envelope ?? null);
+    if (walletStateRootId !== null) {
+        return {
+            walletRootId: walletStateRootId,
+            source: "wallet-state",
+        };
+    }
+    const session = await (options.loadUnlockSession ?? loadUnlockSession)(options.paths.walletUnlockSessionPath, {
+        provider: options.provider,
+    }).catch(() => null);
+    if (session !== null) {
+        return {
+            walletRootId: session.walletRootId,
+            source: "unlock-session",
+        };
+    }
+    const explicitLock = await (options.loadWalletExplicitLock ?? loadWalletExplicitLock)(options.paths.walletExplicitLockPath).catch(() => null);
+    if (explicitLock?.walletRootId) {
+        return {
+            walletRootId: explicitLock.walletRootId,
+            source: "explicit-lock",
+        };
+    }
+    return {
+        walletRootId: UNINITIALIZED_WALLET_ROOT_ID,
+        source: "default-uninitialized",
+    };
+}

package/dist/wallet/runtime.d.ts

@@ -1,6 +1,7 @@
 import type { CogcoinPathResolution } from "../app-paths.js";
 export interface WalletRuntimePaths {
     dataRoot: string;
+    clientDataDir: string;
     clientConfigPath: string;
     runtimeRoot: string;
     hooksRoot: string;

package/dist/wallet/runtime.js

@@ -3,6 +3,7 @@ export function resolveWalletRuntimePathsForTesting(resolution = {}) {
     const paths = resolveCogcoinPathsForTesting(resolution);
     return {
         dataRoot: paths.dataRoot,
+        clientDataDir: paths.clientDataDir,
         clientConfigPath: paths.clientConfigPath,
         runtimeRoot: paths.runtimeRoot,
         hooksRoot: paths.hooksRoot,

package/dist/wallet/state/crypto.d.ts

@@ -15,6 +15,7 @@ export declare function rederiveKeyFromEnvelope(passphrase: Uint8Array | string,
 export declare function encryptBytesWithKey(plaintext: Uint8Array, key: Uint8Array, metadata: {
     format: string;
     wrappedBy: string;
+    walletRootIdHint?: string | null;
     argon2id?: Argon2EnvelopeParams | null;
     secretProvider?: WalletSecretReference | null;
 }): EncryptedEnvelopeV1;
@@ -22,10 +23,12 @@ export declare function decryptBytesWithKey(envelope: EncryptedEnvelopeV1, key:
 export declare function encryptJsonWithPassphrase<T>(value: T, passphrase: Uint8Array | string, metadata: {
     format: string;
     wrappedBy?: string;
+    walletRootIdHint?: string | null;
 }): Promise<EncryptedEnvelopeV1>;
 export declare function encryptJsonWithSecretProvider<T>(value: T, provider: WalletSecretProvider, secretReference: WalletSecretReference, metadata: {
     format: string;
     wrappedBy?: string;
+    walletRootIdHint?: string | null;
 }): Promise<EncryptedEnvelopeV1>;
 export declare function decryptJsonWithPassphrase<T>(envelope: EncryptedEnvelopeV1, passphrase: Uint8Array | string): Promise<T>;
 export declare function decryptJsonWithSecretProvider<T>(envelope: EncryptedEnvelopeV1, provider: WalletSecretProvider): Promise<T>;

package/dist/wallet/state/crypto.js

@@ -76,6 +76,7 @@ export function encryptBytesWithKey(plaintext, key, metadata) {
         version: 1,
         cipher: "aes-256-gcm",
         wrappedBy: metadata.wrappedBy,
+        walletRootIdHint: metadata.walletRootIdHint ?? null,
         argon2id: metadata.argon2id ?? null,
         secretProvider: metadata.secretProvider ?? null,
         nonce: nonce.toString("base64"),
@@ -96,6 +97,7 @@ export async function encryptJsonWithPassphrase(value, passphrase, metadata) {
     return encryptBytesWithKey(Buffer.from(JSON.stringify(value, jsonReplacer)), derived.key, {
         format: metadata.format,
         wrappedBy: metadata.wrappedBy ?? "passphrase",
+        walletRootIdHint: metadata.walletRootIdHint ?? null,
         argon2id: derived.params,
     });
 }
@@ -104,6 +106,7 @@ export async function encryptJsonWithSecretProvider(value, provider, secretRefer
     return encryptBytesWithKey(Buffer.from(JSON.stringify(value, jsonReplacer)), key, {
         format: metadata.format,
         wrappedBy: metadata.wrappedBy ?? "secret-provider",
+        walletRootIdHint: metadata.walletRootIdHint ?? null,
         secretProvider: secretReference,
     });
 }