@cogcoin/client 0.5.1 → 0.5.3

package/README.md

@@ -1,8 +1,8 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@0.5.1` 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.3` 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 24.7.0 or newer.
+Use Node 22 or newer.
 
 ## Links
 
@@ -32,6 +32,8 @@ npx cogcoin sync
 
 Verify the installed genesis artifacts before using the client in a production implementation.
 The installed package provides the `cogcoin` command for local wallet setup, sync, reads, writes, and mining workflows.
+Provider-backed local wallets unlock on demand by default; `cogcoin wallet lock` suppresses that behavior until `cogcoin unlock` is run again.
+Passphrase-wrapped wallet-state flows still require explicit passphrase-based access.
 
 ## Dependency Surface
 
@@ -45,6 +47,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.
@@ -78,6 +81,7 @@ The installed `cogcoin` command covers the first-party local wallet and node wor
 - mining and hook commands such as `mine`, `mine start`, `mine stop`, `mine status`, `mine log`, `mine setup`, and `hooks status`
 
 The CLI also supports stable `--output json` and `--output preview-json` envelopes on the commands that advertise machine-readable output.
+For provider-backed local wallets, normal reads, mutations, export, and mining setup flows auto-materialize a local unlock session when the wallet is not explicitly locked.
 
 ## SQLite Store
 

package/dist/app-paths.d.ts

@@ -18,6 +18,7 @@ export interface CogcoinResolvedPaths {
     walletStatePath: string;
     walletStateBackupPath: string;
     walletUnlockSessionPath: string;
+    walletExplicitLockPath: string;
     walletControlLockPath: string;
     bitcoindLockPath: string;
     bitcoindStatusPath: string;

package/dist/app-paths.js

@@ -64,6 +64,7 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
     const walletStatePath = joinForPlatform(platform, walletStateDirectory, "wallet-state.enc");
     const walletStateBackupPath = joinForPlatform(platform, walletStateDirectory, "wallet-state.enc.bak");
     const walletUnlockSessionPath = joinForPlatform(platform, runtimeRoot, "wallet-unlock-session.enc");
+    const walletExplicitLockPath = joinForPlatform(platform, runtimeRoot, "wallet-explicit-lock.json");
     const walletControlLockPath = joinForPlatform(platform, runtimeRoot, "wallet-control.lock");
     const bitcoindLockPath = joinForPlatform(platform, runtimeRoot, "bitcoind.lock");
     const bitcoindStatusPath = joinForPlatform(platform, runtimeRoot, "bitcoind-status.json");
@@ -91,6 +92,7 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
         walletStatePath,
         walletStateBackupPath,
         walletUnlockSessionPath,
+        walletExplicitLockPath,
         walletControlLockPath,
         bitcoindLockPath,
         bitcoindStatusPath,

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/cli/output.js

@@ -211,7 +211,7 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
     if (errorCode === "wallet_locked") {
         return {
             what: "Wallet is locked.",
-            why: "This command needs access to the unlocked local wallet state before it can continue.",
+            why: "This command needs access to the unlocked local wallet state before it can continue. Provider-backed wallets unlock on demand unless they were explicitly locked or the local secret store is unavailable.",
             next: "Run `cogcoin unlock --for 15m` and retry.",
         };
     }

package/dist/cli/parse.d.ts

@@ -1,3 +1,3 @@
 import type { ParsedCliArgs } from "./types.js";
-export declare const HELP_TEXT = "Usage: cogcoin <command> [options]\n\nCommands:\n  status                  Show wallet-aware local service and chain status\n  status --output json    Emit the stable v1 machine-readable status envelope\n  init                    Initialize a new local wallet root\n  init --output json      Emit the stable v1 machine-readable init result envelope\n  repair                  Recover bounded wallet/indexer/runtime state\n  unlock                  Unlock the local wallet for a limited duration\n  wallet address          Alias for address\n  wallet ids              Alias for ids\n  hooks enable mining     Enable a validated custom mining hook\n  hooks disable mining    Return to built-in mining hooks\n  hooks status            Show mining hook validation and trust status\n  mine                    Run the miner in the foreground\n  mine start              Start the miner as a background worker\n  mine stop               Stop the active background miner\n  mine setup              Configure the built-in mining provider\n  mine setup --output json\n                         Emit the stable v1 machine-readable mine setup result envelope\n  mine status             Show mining control-plane health and readiness\n  mine log                Show recent mining control-plane events\n  anchor <domain>         Anchor an owned unanchored domain with the Tx1/Tx2 family\n  register <domain> [--from <identity>]\n                         Register a root domain or subdomain\n  transfer <domain> --to <btc-target>\n                          Transfer an unanchored domain to another BTC identity\n  sell <domain> <price>   List an unanchored domain for sale in COG\n  unsell <domain>         Clear an active domain listing\n  buy <domain> [--from <identity>]\n                         Buy an unanchored listed domain in COG\n  send <amount> --to <btc-target>\n                         Send COG from one local identity to another BTC target\n  claim <lock-id> --preimage <32-byte-hex>\n                         Claim an active COG lock before timeout\n  reclaim <lock-id>      Reclaim an expired COG lock as the original locker\n  cog lock <amount> --to-domain <domain> (--for <blocks-or-duration> | --until-height <height>) --condition <sha256hex>\n                         Lock COG to an anchored recipient domain\n  wallet status           Show detailed wallet-local status and service health\n  wallet init             Initialize a new local wallet root\n  wallet unlock           Unlock the local wallet for a limited duration\n  wallet lock             Lock the local wallet immediately\n  wallet export <path>    Export a portable encrypted wallet archive\n  wallet import <path>    Import a portable encrypted wallet archive\n  address                 Show the BTC funding identity for this wallet\n  ids                     List locally controlled identities\n  balance                 Show per-identity COG balances\n  locks                   Show locally related active COG locks\n  domain list             Alias for domains\n  domain show <domain>    Alias for show <domain>\n  domains [--anchored] [--listed] [--mineable]\n                         Show locally related domains\n  show <domain>           Show one domain and its local-wallet relationship\n  fields <domain>         List current fields on a domain\n  field <domain> <field>  Show one current field value\n  field create <domain> <field>\n                         Create a new anchored field, optionally with an initial value\n  field set <domain> <field>\n                         Update an existing anchored field value\n  field clear <domain> <field>\n                         Clear an existing anchored field value\n  rep give <source-domain> <target-domain> <amount>\n                         Burn COG as anchored-domain reputation support\n  rep revoke <source-domain> <target-domain> <amount>\n                         Revoke visible support without refunding burned COG\n\nOptions:\n  --db <path>       Override the SQLite database path\n  --data-dir <path> Override the managed bitcoin datadir\n  --for <duration>  Unlock duration like 15m, 2h, or 1d\n  --message <text>  Founding message text for anchor\n  --to <btc-target> Transfer or send target as an address or spk:<hex>\n  --from <identity> Resolve sender identity as id:<n>, domain:<name>, address, or spk:<hex>\n  --to-domain <domain>\n                    Recipient domain for cog lock\n  --condition <sha256hex>\n                    32-byte lock condition hash\n  --until-height <height>\n                    Absolute timeout height for cog lock\n  --preimage <32-byte-hex>\n                    Claim preimage for an active lock\n  --review <text>   Optional public review text for reputation operations\n  --text <utf8>     UTF-8 payload text for endpoint or field writes\n  --json <json>     UTF-8 payload JSON text for endpoint or field writes\n  --bytes <spec>    Payload bytes as hex:<hex> or @<path>\n  --permanent       Create the field as permanent\n  --format <spec>   Advanced field format as raw:<u8>\n  --value <spec>    Advanced field value as hex:<hex>, @<path>, or utf8:<text>\n  --claimable      Show only currently claimable locks\n  --reclaimable    Show only currently reclaimable locks\n  --anchored       Show only anchored domains\n  --listed         Show only currently listed domains\n  --mineable       Show only locally mineable root domains\n  --limit <n>      Limit list rows (1..1000)\n  --all            Show all rows for list commands\n  --verify         Run full custom-hook verification\n  --follow         Follow mining log output\n  --output <mode>  Output mode: text, json, or preview-json\n  --progress <mode> Progress output mode: auto, tty, or none\n  --force-race      Allow a visible root registration race\n  --yes             Approve eligible plain yes/no mutation confirmations non-interactively\n  --help            Show help\n  --version         Show package version\n\nQuickstart:\n  1. Run `cogcoin init` to create the wallet.\n  2. Run `cogcoin sync` to bootstrap assumeutxo and the managed Bitcoin/indexer state.\n  3. Run `cogcoin address`, then fund the wallet with about 0.0015 BTC so you can buy a 6+ character domain to start mining and still keep BTC available for mining transaction fees.\n\nExamples:\n  cogcoin status --output json\n  cogcoin init --output json\n  cogcoin wallet address\n  cogcoin domain list --mineable\n  cogcoin register alpha-child\n  cogcoin register weatherbot --from id:1\n  cogcoin anchor alpha\n  cogcoin buy alpha\n  cogcoin buy alpha --from id:1\n  cogcoin field create alpha bio --text \"hello\"\n  cogcoin rep give alpha beta 10 --review \"great operator\"\n  cogcoin hooks status\n  cogcoin mine setup --output json\n  cogcoin register alpha-child --output preview-json\n  cogcoin mine status\n";
+export declare const HELP_TEXT = "Usage: cogcoin <command> [options]\n\nCommands:\n  status                  Show wallet-aware local service and chain status\n  status --output json    Emit the stable v1 machine-readable status envelope\n  init                    Initialize a new local wallet root\n  init --output json      Emit the stable v1 machine-readable init result envelope\n  repair                  Recover bounded wallet/indexer/runtime state\n  unlock                  Clear an explicit wallet lock and unlock for a limited duration\n  wallet address          Alias for address\n  wallet ids              Alias for ids\n  hooks enable mining     Enable a validated custom mining hook\n  hooks disable mining    Return to built-in mining hooks\n  hooks status            Show mining hook validation and trust status\n  mine                    Run the miner in the foreground\n  mine start              Start the miner as a background worker\n  mine stop               Stop the active background miner\n  mine setup              Configure the built-in mining provider\n  mine setup --output json\n                         Emit the stable v1 machine-readable mine setup result envelope\n  mine status             Show mining control-plane health and readiness\n  mine log                Show recent mining control-plane events\n  anchor <domain>         Anchor an owned unanchored domain with the Tx1/Tx2 family\n  register <domain> [--from <identity>]\n                         Register a root domain or subdomain\n  transfer <domain> --to <btc-target>\n                          Transfer an unanchored domain to another BTC identity\n  sell <domain> <price>   List an unanchored domain for sale in COG\n  unsell <domain>         Clear an active domain listing\n  buy <domain> [--from <identity>]\n                         Buy an unanchored listed domain in COG\n  send <amount> --to <btc-target>\n                         Send COG from one local identity to another BTC target\n  claim <lock-id> --preimage <32-byte-hex>\n                         Claim an active COG lock before timeout\n  reclaim <lock-id>      Reclaim an expired COG lock as the original locker\n  cog lock <amount> --to-domain <domain> (--for <blocks-or-duration> | --until-height <height>) --condition <sha256hex>\n                         Lock COG to an anchored recipient domain\n  wallet status           Show detailed wallet-local status and service health\n  wallet init             Initialize a new local wallet root\n  wallet unlock           Clear an explicit wallet lock and unlock for a limited duration\n  wallet lock             Lock the local wallet and disable on-demand unlock\n  wallet export <path>    Export a portable encrypted wallet archive\n  wallet import <path>    Import a portable encrypted wallet archive\n  address                 Show the BTC funding identity for this wallet\n  ids                     List locally controlled identities\n  balance                 Show per-identity COG balances\n  locks                   Show locally related active COG locks\n  domain list             Alias for domains\n  domain show <domain>    Alias for show <domain>\n  domains [--anchored] [--listed] [--mineable]\n                         Show locally related domains\n  show <domain>           Show one domain and its local-wallet relationship\n  fields <domain>         List current fields on a domain\n  field <domain> <field>  Show one current field value\n  field create <domain> <field>\n                         Create a new anchored field, optionally with an initial value\n  field set <domain> <field>\n                         Update an existing anchored field value\n  field clear <domain> <field>\n                         Clear an existing anchored field value\n  rep give <source-domain> <target-domain> <amount>\n                         Burn COG as anchored-domain reputation support\n  rep revoke <source-domain> <target-domain> <amount>\n                         Revoke visible support without refunding burned COG\n\nOptions:\n  --db <path>       Override the SQLite database path\n  --data-dir <path> Override the managed bitcoin datadir\n  --for <duration>  Unlock duration like 15m, 2h, or 1d when unlocking explicitly\n  --message <text>  Founding message text for anchor\n  --to <btc-target> Transfer or send target as an address or spk:<hex>\n  --from <identity> Resolve sender identity as id:<n>, domain:<name>, address, or spk:<hex>\n  --to-domain <domain>\n                    Recipient domain for cog lock\n  --condition <sha256hex>\n                    32-byte lock condition hash\n  --until-height <height>\n                    Absolute timeout height for cog lock\n  --preimage <32-byte-hex>\n                    Claim preimage for an active lock\n  --review <text>   Optional public review text for reputation operations\n  --text <utf8>     UTF-8 payload text for endpoint or field writes\n  --json <json>     UTF-8 payload JSON text for endpoint or field writes\n  --bytes <spec>    Payload bytes as hex:<hex> or @<path>\n  --permanent       Create the field as permanent\n  --format <spec>   Advanced field format as raw:<u8>\n  --value <spec>    Advanced field value as hex:<hex>, @<path>, or utf8:<text>\n  --claimable      Show only currently claimable locks\n  --reclaimable    Show only currently reclaimable locks\n  --anchored       Show only anchored domains\n  --listed         Show only currently listed domains\n  --mineable       Show only locally mineable root domains\n  --limit <n>      Limit list rows (1..1000)\n  --all            Show all rows for list commands\n  --verify         Run full custom-hook verification\n  --follow         Follow mining log output\n  --output <mode>  Output mode: text, json, or preview-json\n  --progress <mode> Progress output mode: auto, tty, or none\n  --force-race      Allow a visible root registration race\n  --yes             Approve eligible plain yes/no mutation confirmations non-interactively\n  --help            Show help\n  --version         Show package version\n\nQuickstart:\n  1. Run `cogcoin init` to create the wallet.\n  2. Run `cogcoin sync` to bootstrap assumeutxo and the managed Bitcoin/indexer state.\n  3. Run `cogcoin address`, then fund the wallet with about 0.0015 BTC so you can buy a 6+ character domain to start mining and still keep BTC available for mining transaction fees.\n\nExamples:\n  cogcoin status --output json\n  cogcoin init --output json\n  cogcoin wallet address\n  cogcoin domain list --mineable\n  cogcoin register alpha-child\n  cogcoin register weatherbot --from id:1\n  cogcoin anchor alpha\n  cogcoin buy alpha\n  cogcoin buy alpha --from id:1\n  cogcoin field create alpha bio --text \"hello\"\n  cogcoin rep give alpha beta 10 --review \"great operator\"\n  cogcoin hooks status\n  cogcoin mine setup --output json\n  cogcoin register alpha-child --output preview-json\n  cogcoin mine status\n";
 export declare function parseCliArgs(argv: string[]): ParsedCliArgs;

package/dist/cli/parse.js

@@ -7,7 +7,7 @@ Commands:
   init                    Initialize a new local wallet root
   init --output json      Emit the stable v1 machine-readable init result envelope
   repair                  Recover bounded wallet/indexer/runtime state
-  unlock                  Unlock the local wallet for a limited duration
+  unlock                  Clear an explicit wallet lock and unlock for a limited duration
   wallet address          Alias for address
   wallet ids              Alias for ids
   hooks enable mining     Enable a validated custom mining hook
@@ -39,8 +39,8 @@ Commands:
                          Lock COG to an anchored recipient domain
   wallet status           Show detailed wallet-local status and service health
   wallet init             Initialize a new local wallet root
-  wallet unlock           Unlock the local wallet for a limited duration
-  wallet lock             Lock the local wallet immediately
+  wallet unlock           Clear an explicit wallet lock and unlock for a limited duration
+  wallet lock             Lock the local wallet and disable on-demand unlock
   wallet export <path>    Export a portable encrypted wallet archive
   wallet import <path>    Import a portable encrypted wallet archive
   address                 Show the BTC funding identity for this wallet
@@ -68,7 +68,7 @@ Commands:
 Options:
   --db <path>       Override the SQLite database path
   --data-dir <path> Override the managed bitcoin datadir
-  --for <duration>  Unlock duration like 15m, 2h, or 1d
+  --for <duration>  Unlock duration like 15m, 2h, or 1d when unlocking explicitly
   --message <text>  Founding message text for anchor
   --to <btc-target> Transfer or send target as an address or spk:<hex>
   --from <identity> Resolve sender identity as id:<n>, domain:<name>, address, or spk:<hex>

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,19 @@ 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 loadOrAutoUnlockWalletState(options?: {
+    provider?: WalletSecretProvider;
+    nowUnixMs?: number;
+    unlockDurationMs?: number;
+    paths?: WalletRuntimePaths;
+    dataDir?: string;
+    controlLockHeld?: boolean;
+    attachService?: typeof attachOrStartManagedBitcoindService;
+    rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletLifecycleRpcClient;
 }): Promise<LoadedUnlockedWalletState | null>;
 export declare function initializeWallet(options: {
     dataDir: string;
@@ -143,6 +156,7 @@ export declare function unlockWallet(options?: {
 export declare function lockWallet(options: {
     dataDir: string;
     provider?: WalletSecretProvider;
+    nowUnixMs?: number;
     paths?: WalletRuntimePaths;
     attachService?: typeof attachOrStartManagedBitcoindService;
     rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletLifecycleRpcClient;