@cogcoin/client 0.5.0 → 0.5.2

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@0.5.0` is the store-backed Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
+`@cogcoin/client@0.5.2` is the store-backed Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
 
 Use Node 22 or newer.
 
@@ -45,6 +45,7 @@ The published package depends on:
 - `@scure/bip32@^2.0.1`
 - `@scure/bip39@^2.0.1`
 - `better-sqlite3@12.8.0`
+- `hash-wasm@^4.12.0`
 - `zeromq@6.5.0`
 
 `@cogcoin/vectors` is kept as a repository development dependency for conformance tests and is not part of the published runtime dependency surface.

package/dist/bitcoind/client/follow-loop.d.ts

@@ -1,10 +1,9 @@
-import { Subscriber } from "zeromq";
-import type { FollowLoopControlDependencies, FollowLoopResources, ScheduleSyncDependencies, StartFollowingTipLoopDependencies } from "./internal-types.js";
+import type { FollowLoopControlDependencies, FollowLoopSubscriber, FollowLoopResources, ScheduleSyncDependencies, StartFollowingTipLoopDependencies } from "./internal-types.js";
 export declare function startFollowingTipLoop(dependencies: StartFollowingTipLoopDependencies): Promise<FollowLoopResources>;
-export declare function consumeZmq(subscriber: Subscriber, dependencies: FollowLoopControlDependencies): Promise<void>;
+export declare function consumeZmq(subscriber: FollowLoopSubscriber, dependencies: FollowLoopControlDependencies): Promise<void>;
 export declare function scheduleSync(dependencies: ScheduleSyncDependencies): void;
 export declare function closeFollowLoopResources(resources: {
-    subscriber: Subscriber | null;
+    subscriber: FollowLoopSubscriber | null;
     followLoop: Promise<void> | null;
     pollTimer: ReturnType<typeof setInterval> | null;
 }): Promise<void>;

package/dist/bitcoind/client/follow-loop.js

@@ -1,9 +1,23 @@
-import { Subscriber } from "zeromq";
+async function loadZeroMqModule() {
+    return await import("zeromq");
+}
+async function createSubscriber(loadZeroMq) {
+    try {
+        const zeroMq = loadZeroMq === undefined
+            ? await loadZeroMqModule()
+            : await loadZeroMq();
+        return new zeroMq.Subscriber();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Managed tip following could not initialize \`zeromq\`: ${detail}`, { cause: error instanceof Error ? error : undefined });
+    }
+}
 export async function startFollowingTipLoop(dependencies) {
+    const subscriber = await createSubscriber(dependencies.loadZeroMq);
     const currentTip = await dependencies.client.getTip();
     await dependencies.progress.enableFollowVisualMode(currentTip?.height ?? null, await dependencies.loadVisibleFollowBlockTimes(currentTip));
     await dependencies.syncToTip();
-    const subscriber = new Subscriber();
     subscriber.connect(dependencies.node.zmq.endpoint);
     subscriber.subscribe(dependencies.node.zmq.topic);
     const followLoop = consumeZmq(subscriber, {

package/dist/bitcoind/client/internal-types.d.ts

@@ -1,4 +1,3 @@
-import type { Subscriber } from "zeromq";
 import type { Client, ClientStoreAdapter } from "../../types.js";
 import type { AssumeUtxoBootstrapController } from "../bootstrap.js";
 import type { ManagedProgressController } from "../progress.js";
@@ -27,8 +26,16 @@ export interface SyncEngineDependencies {
     isFollowing(): boolean;
     loadVisibleFollowBlockTimes(tip: Awaited<ReturnType<Client["getTip"]>>): Promise<Record<number, number>>;
 }
+export interface FollowLoopSubscriber extends AsyncIterable<unknown> {
+    close(): void;
+    connect(endpoint: string): void;
+    subscribe(topic: string): void;
+}
+export interface ZeroMqModuleLike {
+    Subscriber: new () => FollowLoopSubscriber;
+}
 export interface FollowLoopResources {
-    subscriber: Subscriber;
+    subscriber: FollowLoopSubscriber;
     followLoop: Promise<void>;
     pollTimer: ReturnType<typeof setInterval>;
 }
@@ -40,6 +47,7 @@ export interface StartFollowingTipLoopDependencies {
     scheduleSync(): void;
     shouldContinue(): boolean;
     loadVisibleFollowBlockTimes(tip: Awaited<ReturnType<Client["getTip"]>>): Promise<Record<number, number>>;
+    loadZeroMq?(): Promise<ZeroMqModuleLike>;
 }
 export interface ScheduleSyncDependencies {
     syncDebounceMs: number;

package/dist/bitcoind/client/managed-client.js

@@ -1,6 +1,6 @@
 import { closeFollowLoopResources, scheduleSync, startFollowingTipLoop } from "./follow-loop.js";
 import { loadVisibleFollowBlockTimes } from "./follow-block-times.js";
-import { createBlockRateTracker, createInitialSyncResult } from "./internal-types.js";
+import { createBlockRateTracker, createInitialSyncResult, } from "./internal-types.js";
 import { syncToTip as runManagedSync } from "./sync-engine.js";
 export class DefaultManagedBitcoindClient {
     #client;

package/dist/wallet/descriptor-normalization.d.ts

@@ -0,0 +1,42 @@
+import { type WalletStateSaveAccess } from "./state/storage.js";
+import type { WalletRuntimePaths } from "./runtime.js";
+import type { UnlockSessionStateV1, WalletStateV1 } from "./types.js";
+export interface WalletDescriptorInfoRpc {
+    getDescriptorInfo(descriptor: string): Promise<{
+        descriptor: string;
+        checksum: string;
+    }>;
+}
+export interface NormalizedWalletDescriptorState {
+    privateExternal: string;
+    publicExternal: string;
+    checksum: string;
+}
+export declare function stripDescriptorChecksum(descriptor: string): string;
+export declare function buildDescriptorWithChecksum(descriptor: string, checksum: string): string;
+export declare function resolveNormalizedWalletDescriptorState(state: WalletStateV1, rpc: WalletDescriptorInfoRpc): Promise<NormalizedWalletDescriptorState>;
+export declare function applyNormalizedWalletDescriptorState(state: WalletStateV1, normalized: NormalizedWalletDescriptorState): WalletStateV1;
+export declare function normalizeWalletDescriptorState(state: WalletStateV1, rpc: WalletDescriptorInfoRpc): Promise<{
+    changed: boolean;
+    state: WalletStateV1;
+}>;
+export declare function persistWalletStateUpdate(options: {
+    state: WalletStateV1;
+    access: WalletStateSaveAccess;
+    paths: WalletRuntimePaths;
+    nowUnixMs: number;
+    replacePrimary?: boolean;
+}): Promise<WalletStateV1>;
+export declare function persistNormalizedWalletDescriptorStateIfNeeded(options: {
+    state: WalletStateV1;
+    access: WalletStateSaveAccess;
+    session?: UnlockSessionStateV1 | null;
+    paths: WalletRuntimePaths;
+    nowUnixMs: number;
+    replacePrimary?: boolean;
+    rpc: WalletDescriptorInfoRpc;
+}): Promise<{
+    changed: boolean;
+    session: UnlockSessionStateV1 | null;
+    state: WalletStateV1;
+}>;

package/dist/wallet/descriptor-normalization.js

@@ -0,0 +1,108 @@
+import { rm } from "node:fs/promises";
+import { deriveWalletMaterialFromMnemonic } from "./material.js";
+import { saveUnlockSession } from "./state/session.js";
+import { saveWalletState } from "./state/storage.js";
+export function stripDescriptorChecksum(descriptor) {
+    return descriptor.replace(/#[A-Za-z0-9]+$/, "");
+}
+export function buildDescriptorWithChecksum(descriptor, checksum) {
+    return `${stripDescriptorChecksum(descriptor)}#${checksum}`;
+}
+function assertWalletDescriptorStateRecoverable(state) {
+    const material = deriveWalletMaterialFromMnemonic(state.mnemonic.phrase);
+    if (material.keys.masterFingerprintHex !== state.keys.masterFingerprintHex
+        || material.keys.accountPath !== state.keys.accountPath
+        || material.keys.accountXprv !== state.keys.accountXprv
+        || material.keys.accountXpub !== state.keys.accountXpub
+        || material.funding.address !== state.funding.address
+        || material.funding.scriptPubKeyHex !== state.funding.scriptPubKeyHex) {
+        throw new Error("wallet_descriptor_state_unrecoverable");
+    }
+}
+export async function resolveNormalizedWalletDescriptorState(state, rpc) {
+    assertWalletDescriptorStateRecoverable(state);
+    const material = deriveWalletMaterialFromMnemonic(state.mnemonic.phrase);
+    const privateDescriptor = await rpc.getDescriptorInfo(stripDescriptorChecksum(material.descriptor.privateExternal));
+    const publicDescriptor = await rpc.getDescriptorInfo(stripDescriptorChecksum(material.descriptor.publicExternal));
+    return {
+        privateExternal: buildDescriptorWithChecksum(material.descriptor.privateExternal, privateDescriptor.checksum),
+        publicExternal: buildDescriptorWithChecksum(publicDescriptor.descriptor, publicDescriptor.checksum),
+        checksum: publicDescriptor.checksum,
+    };
+}
+export function applyNormalizedWalletDescriptorState(state, normalized) {
+    return {
+        ...state,
+        descriptor: {
+            ...state.descriptor,
+            privateExternal: normalized.privateExternal,
+            publicExternal: normalized.publicExternal,
+            checksum: normalized.checksum,
+        },
+        managedCoreWallet: {
+            ...state.managedCoreWallet,
+            descriptorChecksum: normalized.checksum,
+        },
+    };
+}
+export async function normalizeWalletDescriptorState(state, rpc) {
+    const normalized = await resolveNormalizedWalletDescriptorState(state, rpc);
+    const changed = state.descriptor.privateExternal !== normalized.privateExternal
+        || state.descriptor.publicExternal !== normalized.publicExternal
+        || state.descriptor.checksum !== normalized.checksum
+        || state.managedCoreWallet.descriptorChecksum !== normalized.checksum;
+    return {
+        changed,
+        state: changed ? applyNormalizedWalletDescriptorState(state, normalized) : state,
+    };
+}
+export async function persistWalletStateUpdate(options) {
+    const nextState = {
+        ...options.state,
+        stateRevision: options.state.stateRevision + 1,
+        lastWrittenAtUnixMs: options.nowUnixMs,
+    };
+    if (options.replacePrimary) {
+        await rm(options.paths.walletStatePath, { force: true }).catch(() => undefined);
+    }
+    await saveWalletState({
+        primaryPath: options.paths.walletStatePath,
+        backupPath: options.paths.walletStateBackupPath,
+    }, nextState, options.access);
+    return nextState;
+}
+export async function persistNormalizedWalletDescriptorStateIfNeeded(options) {
+    const normalized = await normalizeWalletDescriptorState(options.state, options.rpc);
+    if (!normalized.changed) {
+        return {
+            changed: false,
+            session: options.session ?? null,
+            state: options.state,
+        };
+    }
+    const nextState = await persistWalletStateUpdate({
+        state: normalized.state,
+        access: options.access,
+        paths: options.paths,
+        nowUnixMs: options.nowUnixMs,
+        replacePrimary: options.replacePrimary,
+    });
+    if (options.session === undefined || options.session === null) {
+        return {
+            changed: true,
+            session: options.session ?? null,
+            state: nextState,
+        };
+    }
+    const nextSession = {
+        ...options.session,
+        walletRootId: nextState.walletRootId,
+        sourceStateRevision: nextState.stateRevision,
+    };
+    await saveUnlockSession(options.paths.walletUnlockSessionPath, nextSession, options.access);
+    return {
+        changed: true,
+        session: nextSession,
+        state: nextState,
+    };
+}

package/dist/wallet/lifecycle.d.ts

@@ -123,6 +123,9 @@ export declare function loadUnlockedWalletState(options?: {
     provider?: WalletSecretProvider;
     nowUnixMs?: number;
     paths?: WalletRuntimePaths;
+    dataDir?: string;
+    attachService?: typeof attachOrStartManagedBitcoindService;
+    rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletLifecycleRpcClient;
 }): Promise<LoadedUnlockedWalletState | null>;
 export declare function initializeWallet(options: {
     dataDir: string;

package/dist/wallet/lifecycle.js

@@ -8,6 +8,7 @@ import { resolveManagedServicePaths } from "../bitcoind/service-paths.js";
 import { createRpcClient } from "../bitcoind/node.js";
 import { openSqliteStore } from "../sqlite/index.js";
 import { readPortableWalletArchive, writePortableWalletArchive } from "./archive.js";
+import { normalizeWalletDescriptorState, persistNormalizedWalletDescriptorStateIfNeeded, persistWalletStateUpdate, resolveNormalizedWalletDescriptorState, stripDescriptorChecksum, } from "./descriptor-normalization.js";
 import { acquireFileLock } from "./fs/lock.js";
 import { createInternalCoreWalletPassphrase, createMnemonicConfirmationChallenge, deriveWalletMaterialFromMnemonic, generateWalletMaterial, } from "./material.js";
 import { resolveWalletRuntimePathsForTesting } from "./runtime.js";
@@ -23,9 +24,6 @@ export const DEFAULT_UNLOCK_DURATION_MS = 15 * 60 * 1000;
 function sanitizeWalletName(walletRootId) {
     return `cogcoin-${walletRootId}`.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 63);
 }
-function stripDescriptorChecksum(descriptor) {
-    return descriptor.replace(/#[A-Za-z0-9]+$/, "");
-}
 async function pathExists(path) {
     try {
         await access(path, constants.F_OK);
@@ -518,22 +516,16 @@ function createStoppedBackgroundRuntimeSnapshot(snapshot, nowUnixMs) {
     };
 }
 async function persistRepairState(options) {
-    const nextState = {
-        ...options.state,
-        stateRevision: options.state.stateRevision + 1,
-        lastWrittenAtUnixMs: options.nowUnixMs,
-    };
-    if (options.replacePrimary) {
-        await rm(options.paths.walletStatePath, { force: true }).catch(() => undefined);
-    }
-    await saveWalletState({
-        primaryPath: options.paths.walletStatePath,
-        backupPath: options.paths.walletStateBackupPath,
-    }, nextState, {
-        provider: options.provider,
-        secretReference: createWalletSecretReference(nextState.walletRootId),
+    return await persistWalletStateUpdate({
+        state: options.state,
+        access: {
+            provider: options.provider,
+            secretReference: createWalletSecretReference(options.state.walletRootId),
+        },
+        paths: options.paths,
+        nowUnixMs: options.nowUnixMs,
+        replacePrimary: options.replacePrimary,
     });
-    return nextState;
 }
 async function stopBackgroundMiningForRepair(options) {
     const pid = options.snapshot.backgroundWorkerPid;
@@ -630,13 +622,12 @@ async function importDescriptorIntoManagedCoreWallet(state, provider, paths, dat
     await createManagedWalletReplica(rpc, state.walletRootId, {
         managedWalletPassphrase: state.managedCoreWallet.internalPassphrase,
     });
-    const privateDescriptor = await rpc.getDescriptorInfo(state.descriptor.privateExternal);
-    const publicDescriptor = await rpc.getDescriptorInfo(state.descriptor.publicExternal);
+    const normalizedDescriptors = await resolveNormalizedWalletDescriptorState(state, rpc);
     const walletName = sanitizeWalletName(state.walletRootId);
     await rpc.walletPassphrase(walletName, state.managedCoreWallet.internalPassphrase, 10);
     try {
         const importResults = await rpc.importDescriptors(walletName, [{
-                desc: privateDescriptor.descriptor,
+                desc: normalizedDescriptors.privateExternal,
                 timestamp: state.walletBirthTime,
                 active: false,
                 internal: false,
@@ -649,12 +640,12 @@ async function importDescriptorIntoManagedCoreWallet(state, provider, paths, dat
     finally {
         await rpc.walletLock(walletName).catch(() => undefined);
     }
-    const derivedFunding = await rpc.deriveAddresses(publicDescriptor.descriptor, [0, 0]);
+    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 === privateDescriptor.descriptor);
+    const importedDescriptor = descriptors.descriptors.find((entry) => entry.desc === normalizedDescriptors.publicExternal);
     if (importedDescriptor == null) {
         throw new Error("wallet_descriptor_not_present_after_import");
     }
@@ -666,7 +657,7 @@ async function importDescriptorIntoManagedCoreWallet(state, provider, paths, dat
         privateKeysEnabled: true,
         created: false,
         proofStatus: "ready",
-        descriptorChecksum: privateDescriptor.checksum,
+        descriptorChecksum: normalizedDescriptors.checksum,
         fundingAddress0: state.funding.address,
         fundingScriptPubKeyHex0: state.funding.scriptPubKeyHex,
         message: null,
@@ -677,14 +668,14 @@ async function importDescriptorIntoManagedCoreWallet(state, provider, paths, dat
         lastWrittenAtUnixMs: nowUnixMs,
         descriptor: {
             ...state.descriptor,
-            privateExternal: privateDescriptor.descriptor,
-            publicExternal: publicDescriptor.descriptor,
-            checksum: privateDescriptor.checksum,
+            privateExternal: normalizedDescriptors.privateExternal,
+            publicExternal: normalizedDescriptors.publicExternal,
+            checksum: normalizedDescriptors.checksum,
         },
         managedCoreWallet: {
             ...state.managedCoreWallet,
             walletName,
-            descriptorChecksum: privateDescriptor.checksum,
+            descriptorChecksum: normalizedDescriptors.checksum,
             fundingAddress0: verifiedReplica.fundingAddress0 ?? null,
             fundingScriptPubKeyHex0: verifiedReplica.fundingScriptPubKeyHex0 ?? null,
             proofStatus: "ready",
@@ -782,7 +773,7 @@ export async function loadUnlockedWalletState(options = {}) {
     const nowUnixMs = options.nowUnixMs ?? Date.now();
     const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
     try {
-        const session = await loadUnlockSession(paths.walletUnlockSessionPath, {
+        let session = await loadUnlockSession(paths.walletUnlockSessionPath, {
             provider,
         });
         if (session.unlockUntilUnixMs <= nowUnixMs) {
@@ -800,13 +791,43 @@ export async function loadUnlockedWalletState(options = {}) {
             await clearUnlockSession(paths.walletUnlockSessionPath);
             return null;
         }
+        let state = loaded.state;
+        let source = loaded.source;
+        if (options.dataDir !== undefined) {
+            const node = await (options.attachService ?? attachOrStartManagedBitcoindService)({
+                dataDir: options.dataDir,
+                chain: "main",
+                startHeight: 0,
+                walletRootId: state.walletRootId,
+            });
+            try {
+                const normalized = await persistNormalizedWalletDescriptorStateIfNeeded({
+                    state,
+                    access: {
+                        provider,
+                        secretReference: createWalletSecretReference(state.walletRootId),
+                    },
+                    session,
+                    paths,
+                    nowUnixMs,
+                    replacePrimary: loaded.source === "backup",
+                    rpc: (options.rpcFactory ?? createRpcClient)(node.rpc),
+                });
+                state = normalized.state;
+                session = normalized.session ?? session;
+                source = normalized.changed ? "primary" : loaded.source;
+            }
+            finally {
+                await node.stop?.().catch(() => undefined);
+            }
+        }
         return {
             session,
             state: {
-                ...loaded.state,
-                miningState: normalizeMiningStateRecord(loaded.state.miningState),
+                ...state,
+                miningState: normalizeMiningStateRecord(state.miningState),
             },
-            source: loaded.source,
+            source,
         };
     }
     catch {
@@ -1242,6 +1263,11 @@ export async function repairWallet(options) {
                 walletRootId: repairedState.walletRootId,
             });
             const bitcoindRpc = (options.rpcFactory ?? createRpcClient)(bitcoindHandle.rpc);
+            const normalizedDescriptorState = await normalizeWalletDescriptorState(repairedState, bitcoindRpc);
+            if (normalizedDescriptorState.changed) {
+                repairedState = normalizedDescriptorState.state;
+                repairStateNeedsPersist = true;
+            }
             let replica = await verifyManagedCoreWalletReplica(repairedState, options.dataDir, {
                 nodeHandle: bitcoindHandle,
                 attachService: options.attachService,

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

@@ -3,6 +3,7 @@ import { type WalletSecretProvider } from "../state/provider.js";
 import type { WalletLocalStateStatus, WalletReadContext } from "./types.js";
 import type { WalletRuntimePaths } from "../runtime.js";
 declare function inspectWalletLocalState(options?: {
+    dataDir?: string;
     passphrase?: Uint8Array | string;
     secretProvider?: WalletSecretProvider;
     now?: number;

package/dist/wallet/read/context.js

@@ -6,11 +6,12 @@ import { UNINITIALIZED_WALLET_ROOT_ID } from "../../bitcoind/service-paths.js";
 import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, } from "../../bitcoind/service.js";
 import {} from "../../bitcoind/types.js";
 import { loadUnlockedWalletState, verifyManagedCoreWalletReplica, } from "../lifecycle.js";
+import { persistNormalizedWalletDescriptorStateIfNeeded } from "../descriptor-normalization.js";
 import { inspectMiningControlPlane } from "../mining/index.js";
 import { normalizeMiningStateRecord } from "../mining/state.js";
 import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
 import { loadWalletState } from "../state/storage.js";
-import { createDefaultWalletSecretProvider, } from "../state/provider.js";
+import { createDefaultWalletSecretProvider, createWalletSecretReference, } from "../state/provider.js";
 import { createWalletReadModel } from "./project.js";
 const DEFAULT_SERVICE_START_TIMEOUT_MS = 10_000;
 const STALE_HEARTBEAT_THRESHOLD_MS = 15_000;
@@ -23,6 +24,40 @@ async function pathExists(path) {
         return false;
     }
 }
+async function normalizeLoadedWalletStateForRead(options) {
+    if (options.dataDir === undefined) {
+        return options.loaded;
+    }
+    const node = await attachOrStartManagedBitcoindService({
+        dataDir: options.dataDir,
+        chain: "main",
+        startHeight: 0,
+        walletRootId: options.loaded.state.walletRootId,
+    });
+    try {
+        const access = typeof options.access === "string" || options.access instanceof Uint8Array
+            ? options.access
+            : {
+                provider: options.access.provider,
+                secretReference: createWalletSecretReference(options.loaded.state.walletRootId),
+            };
+        const normalized = await persistNormalizedWalletDescriptorStateIfNeeded({
+            state: options.loaded.state,
+            access,
+            paths: options.paths,
+            nowUnixMs: options.now,
+            replacePrimary: options.loaded.source === "backup",
+            rpc: createRpcClient(node.rpc),
+        });
+        return {
+            source: normalized.changed ? "primary" : options.loaded.source,
+            state: normalized.state,
+        };
+    }
+    finally {
+        await node.stop?.().catch(() => undefined);
+    }
+}
 async function inspectWalletLocalState(options = {}) {
     const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
     const now = options.now ?? Date.now();
@@ -51,15 +86,23 @@ async function inspectWalletLocalState(options = {}) {
                 provider,
                 nowUnixMs: now,
                 paths,
+                dataDir: options.dataDir,
             });
             if (unlocked === null) {
                 try {
-                    await loadWalletState({
+                    const loaded = await loadWalletState({
                         primaryPath: paths.walletStatePath,
                         backupPath: paths.walletStateBackupPath,
                     }, {
                         provider,
                     });
+                    await normalizeLoadedWalletStateForRead({
+                        loaded,
+                        access: { provider },
+                        dataDir: options.dataDir,
+                        now,
+                        paths,
+                    });
                 }
                 catch (error) {
                     return {
@@ -118,10 +161,16 @@ async function inspectWalletLocalState(options = {}) {
         }
     }
     try {
-        const loaded = await loadWalletState({
-            primaryPath: paths.walletStatePath,
-            backupPath: paths.walletStateBackupPath,
-        }, options.passphrase);
+        const loaded = await normalizeLoadedWalletStateForRead({
+            loaded: await loadWalletState({
+                primaryPath: paths.walletStatePath,
+                backupPath: paths.walletStateBackupPath,
+            }, options.passphrase),
+            access: options.passphrase,
+            dataDir: options.dataDir,
+            now,
+            paths,
+        });
         return {
             availability: "ready",
             walletRootId: loaded.state.walletRootId,
@@ -408,6 +457,7 @@ export async function openWalletReadContext(options) {
     const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_SERVICE_START_TIMEOUT_MS;
     const now = options.now ?? Date.now();
     const localState = await inspectWalletLocalState({
+        dataDir: options.dataDir,
         passphrase: options.walletStatePassphrase,
         secretProvider: options.secretProvider,
         now,

package/dist/wallet/state/crypto.js

@@ -1,4 +1,5 @@
-import { argon2, createCipheriv, createDecipheriv, randomBytes, } from "node:crypto";
+import { argon2id } from "hash-wasm";
+import { createCipheriv, createDecipheriv, randomBytes, } from "node:crypto";
 const DEFAULT_ARGON2_MEMORY_KIB = 65_536;
 const DEFAULT_ARGON2_ITERATIONS = 3;
 const DEFAULT_ARGON2_PARALLELISM = 1;
@@ -23,23 +24,17 @@ function jsonReviver(_key, value) {
     }
     return value;
 }
-function deriveArgon2Key(message, nonce, memoryKib, iterations, parallelism) {
-    return new Promise((resolve, reject) => {
-        argon2("argon2id", {
-            message,
-            nonce,
-            memory: memoryKib,
-            passes: iterations,
-            parallelism,
-            tagLength: DERIVED_KEY_LENGTH,
-        }, (error, derivedKey) => {
-            if (error) {
-                reject(error);
-                return;
-            }
-            resolve(Buffer.from(derivedKey));
-        });
+async function deriveArgon2Key(message, nonce, memoryKib, iterations, parallelism) {
+    const derivedKey = await argon2id({
+        password: message,
+        salt: nonce,
+        memorySize: memoryKib,
+        iterations,
+        parallelism,
+        hashLength: DERIVED_KEY_LENGTH,
+        outputType: "binary",
     });
+    return Buffer.from(derivedKey);
 }
 export async function deriveKeyFromPassphrase(passphrase, options = {}) {
     const salt = Buffer.from(options.salt ?? randomBytes(ARGON2_SALT_BYTES));

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@cogcoin/client",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Store-backed Cogcoin client with wallet flows, SQLite persistence, and managed Bitcoin Core integration.",
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.0.0"
   },
   "homepage": "https://cogcoin.org",
   "repository": {
@@ -68,6 +68,7 @@
     "@scure/bip32": "^2.0.1",
     "@scure/bip39": "^2.0.1",
     "better-sqlite3": "12.8.0",
+    "hash-wasm": "^4.12.0",
     "zeromq": "6.5.0"
   },
   "devDependencies": {