@cogcoin/client 1.1.3 → 1.1.5

package/dist/wallet/lifecycle/setup.js

@@ -0,0 +1,430 @@
+import { randomBytes } from "node:crypto";
+import { access, constants } from "node:fs/promises";
+import { withClaimedUninitializedManagedRuntime } from "../../bitcoind/service.js";
+import { acquireFileLock } from "../fs/lock.js";
+import { createInternalCoreWalletPassphrase, createMnemonicConfirmationChallenge, deriveWalletMaterialFromMnemonic, generateWalletMaterial, isEnglishMnemonicWord, validateEnglishMnemonic, } from "../material.js";
+import { renderWalletMnemonicRevealArt } from "../mnemonic-art.js";
+import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
+import { clearWalletPendingInitializationState, loadWalletPendingInitializationStateOrNull, saveWalletPendingInitializationState, } from "../state/pending-init.js";
+import { createDefaultWalletSecretProvider, createWalletPendingInitSecretReference, createWalletRootId, createWalletSecretReference, ensureClientPasswordConfigured, withInteractiveWalletSecretProvider, } from "../state/provider.js";
+import { clearLegacyWalletLockArtifacts, } from "../managed-core-wallet.js";
+import { loadWalletState, saveWalletState } from "../state/storage.js";
+import { importDescriptorIntoManagedCoreWallet, normalizeLoadedWalletStateIfNeeded, sanitizeWalletName, } from "./managed-core.js";
+function resolvePendingInitializationStoragePaths(paths) {
+    return {
+        primaryPath: paths.walletInitPendingPath,
+        backupPath: paths.walletInitPendingBackupPath,
+    };
+}
+async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function clearPendingInitialization(paths, provider) {
+    await clearWalletPendingInitializationState(resolvePendingInitializationStoragePaths(paths), {
+        provider,
+        secretReference: createWalletPendingInitSecretReference(paths.walletStateRoot),
+    });
+}
+async function loadOrCreatePendingInitializationMaterial(options) {
+    try {
+        const loaded = await loadWalletPendingInitializationStateOrNull(resolvePendingInitializationStoragePaths(options.paths), {
+            provider: options.provider,
+        });
+        if (loaded !== null) {
+            return deriveWalletMaterialFromMnemonic(loaded.state.mnemonic.phrase);
+        }
+    }
+    catch {
+        await clearPendingInitialization(options.paths, options.provider);
+    }
+    const material = generateWalletMaterial();
+    const secretReference = createWalletPendingInitSecretReference(options.paths.walletStateRoot);
+    const pendingState = {
+        schemaVersion: 1,
+        createdAtUnixMs: options.nowUnixMs,
+        mnemonic: {
+            phrase: material.mnemonic.phrase,
+            language: material.mnemonic.language,
+        },
+    };
+    await options.provider.storeSecret(secretReference.keyId, randomBytes(32));
+    try {
+        await saveWalletPendingInitializationState(resolvePendingInitializationStoragePaths(options.paths), pendingState, {
+            provider: options.provider,
+            secretReference,
+        });
+    }
+    catch (error) {
+        await options.provider.deleteSecret(secretReference.keyId).catch(() => undefined);
+        throw error;
+    }
+    return material;
+}
+function createInitialWalletState(options) {
+    return {
+        schemaVersion: 5,
+        stateRevision: 1,
+        lastWrittenAtUnixMs: options.nowUnixMs,
+        walletRootId: options.walletRootId,
+        network: "mainnet",
+        localScriptPubKeyHexes: [options.material.funding.scriptPubKeyHex],
+        mnemonic: {
+            phrase: options.material.mnemonic.phrase,
+            language: options.material.mnemonic.language,
+        },
+        keys: {
+            masterFingerprintHex: options.material.keys.masterFingerprintHex,
+            accountPath: options.material.keys.accountPath,
+            accountXprv: options.material.keys.accountXprv,
+            accountXpub: options.material.keys.accountXpub,
+        },
+        descriptor: {
+            privateExternal: options.material.descriptor.privateExternal,
+            publicExternal: options.material.descriptor.publicExternal,
+            checksum: options.material.descriptor.checksum,
+            rangeEnd: options.material.descriptor.rangeEnd,
+            safetyMargin: options.material.descriptor.safetyMargin,
+        },
+        funding: {
+            address: options.material.funding.address,
+            scriptPubKeyHex: options.material.funding.scriptPubKeyHex,
+        },
+        walletBirthTime: Math.floor(options.nowUnixMs / 1000),
+        managedCoreWallet: {
+            walletName: sanitizeWalletName(options.walletRootId),
+            internalPassphrase: options.internalCoreWalletPassphrase,
+            descriptorChecksum: null,
+            walletAddress: null,
+            walletScriptPubKeyHex: null,
+            proofStatus: "not-proven",
+            lastImportedAtUnixMs: null,
+            lastVerifiedAtUnixMs: null,
+        },
+        domains: [],
+        miningState: {
+            runMode: "stopped",
+            state: "idle",
+            pauseReason: null,
+            currentPublishState: "none",
+            currentDomain: null,
+            currentDomainId: null,
+            currentDomainIndex: null,
+            currentSenderScriptPubKeyHex: null,
+            currentTxid: null,
+            currentWtxid: null,
+            currentFeeRateSatVb: null,
+            currentAbsoluteFeeSats: null,
+            currentScore: null,
+            currentSentence: null,
+            currentEncodedSentenceBytesHex: null,
+            currentBip39WordIndices: null,
+            currentBlendSeedHex: null,
+            currentBlockTargetHeight: null,
+            currentReferencedBlockHashDisplay: null,
+            currentIntentFingerprintHex: null,
+            livePublishInMempool: null,
+            currentPublishDecision: null,
+            replacementCount: 0,
+            currentBlockFeeSpentSats: "0",
+            sessionFeeSpentSats: "0",
+            lifetimeFeeSpentSats: "0",
+            sharedMiningConflictOutpoint: null,
+        },
+        pendingMutations: [],
+    };
+}
+async function promptRequiredValue(prompter, message) {
+    const value = (await prompter.prompt(message)).trim();
+    if (value === "") {
+        throw new Error("wallet_prompt_value_required");
+    }
+    return value;
+}
+async function promptForRestoreMnemonic(prompter) {
+    const words = [];
+    for (let index = 0; index < 24; index += 1) {
+        const word = (await promptRequiredValue(prompter, `Word ${index + 1} of 24: `)).toLowerCase();
+        if (!isEnglishMnemonicWord(word)) {
+            throw new Error("wallet_restore_mnemonic_invalid");
+        }
+        words.push(word);
+    }
+    const phrase = words.join(" ");
+    if (!validateEnglishMnemonic(phrase)) {
+        throw new Error("wallet_restore_mnemonic_invalid");
+    }
+    return phrase;
+}
+async function promptForInitializationMode(prompter) {
+    if (prompter.selectOption != null) {
+        return await prompter.selectOption({
+            message: "How should Cogcoin set up this wallet?",
+            options: [
+                {
+                    label: "Create new wallet",
+                    description: "Generate a fresh 24-word recovery phrase.",
+                    value: "generated",
+                },
+                {
+                    label: "Restore existing wallet",
+                    description: "Enter an existing 24-word recovery phrase.",
+                    value: "restored",
+                },
+            ],
+            initialValue: "generated",
+        });
+    }
+    prompter.writeLine("How should Cogcoin set up this wallet?");
+    prompter.writeLine("1. Create new wallet");
+    prompter.writeLine("2. Restore existing wallet");
+    while (true) {
+        const answer = (await prompter.prompt("Choice [1-2]: ")).trim();
+        if (answer === "1") {
+            return "generated";
+        }
+        if (answer === "2") {
+            return "restored";
+        }
+        prompter.writeLine("Enter 1 or 2.");
+    }
+}
+async function confirmTypedAcknowledgement(prompter, expected, message, errorCode = "wallet_typed_confirmation_rejected") {
+    const answer = (await prompter.prompt(message)).trim();
+    if (answer !== expected) {
+        throw new Error(errorCode);
+    }
+}
+function isWalletSecretAccessError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.startsWith("wallet_secret_missing_")
+        || message.startsWith("wallet_secret_provider_");
+}
+async function persistInitializedWallet(options) {
+    const walletRootId = createWalletRootId();
+    const internalCoreWalletPassphrase = createInternalCoreWalletPassphrase();
+    const secretReference = createWalletSecretReference(walletRootId);
+    await options.provider.storeSecret(secretReference.keyId, randomBytes(32));
+    const initialState = createInitialWalletState({
+        walletRootId,
+        nowUnixMs: options.nowUnixMs,
+        material: options.material,
+        internalCoreWalletPassphrase,
+    });
+    const verifiedState = await withClaimedUninitializedManagedRuntime({
+        dataDir: options.dataDir,
+        walletRootId,
+    }, async () => {
+        await saveWalletState({
+            primaryPath: options.paths.walletStatePath,
+            backupPath: options.paths.walletStateBackupPath,
+        }, initialState, {
+            provider: options.provider,
+            secretReference,
+        });
+        return importDescriptorIntoManagedCoreWallet(initialState, options.provider, options.paths, options.dataDir, options.nowUnixMs, options.attachService, options.rpcFactory);
+    });
+    await clearLegacyWalletLockArtifacts(options.paths.walletRuntimeRoot);
+    await clearPendingInitialization(options.paths, options.provider);
+    return {
+        walletRootId,
+        state: verifiedState,
+    };
+}
+function writeMnemonicReveal(prompter, phrase, introLines) {
+    const words = phrase.trim().split(/\s+/);
+    for (const line of introLines) {
+        prompter.writeLine(line);
+    }
+    for (const line of renderWalletMnemonicRevealArt(words)) {
+        prompter.writeLine(line);
+    }
+    prompter.writeLine("Single-line copy:");
+    prompter.writeLine(phrase);
+}
+async function confirmMnemonic(prompter, words) {
+    const challenge = createMnemonicConfirmationChallenge(words);
+    for (const entry of challenge) {
+        const answer = (await prompter.prompt(`Confirm word #${entry.index + 1}: `)).trim().toLowerCase();
+        if (answer !== entry.word) {
+            throw new Error(`wallet_init_confirmation_failed_word_${entry.index + 1}`);
+        }
+    }
+}
+async function loadWalletStateForAccess(options = {}) {
+    const provider = options.provider ?? createDefaultWalletSecretProvider();
+    const nowUnixMs = options.nowUnixMs ?? Date.now();
+    const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
+    const loaded = await loadWalletState({
+        primaryPath: paths.walletStatePath,
+        backupPath: paths.walletStateBackupPath,
+    }, {
+        provider,
+    });
+    return normalizeLoadedWalletStateIfNeeded({
+        provider,
+        state: loaded.state,
+        source: loaded.source,
+        nowUnixMs,
+        paths,
+        dataDir: options.dataDir,
+        attachService: options.attachService,
+        rpcFactory: options.rpcFactory,
+    });
+}
+export async function initializeWallet(options) {
+    if (!options.prompter.isInteractive) {
+        throw new Error("wallet_init_requires_tty");
+    }
+    const provider = options.provider ?? createDefaultWalletSecretProvider();
+    const interactiveProvider = withInteractiveWalletSecretProvider(provider, options.prompter);
+    const nowUnixMs = options.nowUnixMs ?? Date.now();
+    const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
+    const controlLock = await acquireFileLock(paths.walletControlLockPath, {
+        purpose: "wallet-init",
+        walletRootId: null,
+    });
+    try {
+        const passwordAction = await ensureClientPasswordConfigured(provider, options.prompter);
+        const hasWalletState = await pathExists(paths.walletStatePath) || await pathExists(paths.walletStateBackupPath);
+        if (hasWalletState) {
+            await clearPendingInitialization(paths, interactiveProvider);
+            const loaded = await loadWalletStateForAccess({
+                provider: interactiveProvider,
+                nowUnixMs,
+                paths,
+                dataDir: options.dataDir,
+                attachService: options.attachService,
+                rpcFactory: options.rpcFactory,
+            });
+            return {
+                setupMode: "existing",
+                passwordAction,
+                walletAction: "already-initialized",
+                walletRootId: loaded.state.walletRootId,
+                fundingAddress: loaded.state.funding.address,
+                state: loaded.state,
+            };
+        }
+        const setupMode = await promptForInitializationMode(options.prompter);
+        let material;
+        if (setupMode === "generated") {
+            material = await loadOrCreatePendingInitializationMaterial({
+                provider: interactiveProvider,
+                paths,
+                nowUnixMs,
+            });
+            let mnemonicRevealed = false;
+            writeMnemonicReveal(options.prompter, material.mnemonic.phrase, [
+                "Cogcoin Wallet Initialization",
+                "Write down this 24-word recovery phrase.",
+                "The same phrase will be shown again until confirmation succeeds:",
+                "",
+            ]);
+            mnemonicRevealed = true;
+            try {
+                await confirmMnemonic(options.prompter, material.mnemonic.words);
+            }
+            finally {
+                if (mnemonicRevealed) {
+                    await Promise.resolve()
+                        .then(() => options.prompter.clearSensitiveDisplay?.("mnemonic-reveal"))
+                        .catch(() => undefined);
+                }
+            }
+        }
+        else {
+            let promptPhaseStarted = false;
+            let mnemonicPhrase;
+            try {
+                promptPhaseStarted = true;
+                mnemonicPhrase = await promptForRestoreMnemonic(options.prompter);
+            }
+            finally {
+                if (promptPhaseStarted) {
+                    await options.prompter.clearSensitiveDisplay?.("restore-mnemonic-entry");
+                }
+            }
+            await clearPendingInitialization(paths, interactiveProvider);
+            material = deriveWalletMaterialFromMnemonic(mnemonicPhrase);
+        }
+        const initialized = await persistInitializedWallet({
+            dataDir: options.dataDir,
+            provider: interactiveProvider,
+            material,
+            nowUnixMs,
+            paths,
+            attachService: options.attachService,
+            rpcFactory: options.rpcFactory,
+        });
+        return {
+            setupMode,
+            passwordAction,
+            walletAction: "initialized",
+            walletRootId: initialized.walletRootId,
+            fundingAddress: initialized.state.funding.address,
+            state: initialized.state,
+        };
+    }
+    finally {
+        await controlLock.release();
+    }
+}
+export async function showWalletMnemonic(options) {
+    if (!options.prompter.isInteractive) {
+        throw new Error("wallet_show_mnemonic_requires_tty");
+    }
+    const provider = options.provider ?? createDefaultWalletSecretProvider();
+    const interactiveProvider = withInteractiveWalletSecretProvider(provider, options.prompter);
+    const nowUnixMs = options.nowUnixMs ?? Date.now();
+    const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
+    const controlLock = await acquireFileLock(paths.walletControlLockPath, {
+        purpose: "wallet-show-mnemonic",
+        walletRootId: null,
+    });
+    try {
+        const [hasPrimaryStateFile, hasBackupStateFile] = await Promise.all([
+            pathExists(paths.walletStatePath),
+            pathExists(paths.walletStateBackupPath),
+        ]);
+        if (!hasPrimaryStateFile && !hasBackupStateFile) {
+            throw new Error("wallet_uninitialized");
+        }
+        const loaded = await loadWalletStateForAccess({
+            provider: interactiveProvider,
+            nowUnixMs,
+            paths,
+        }).catch((error) => {
+            if (isWalletSecretAccessError(error)) {
+                throw new Error("wallet_secret_provider_unavailable");
+            }
+            throw new Error("local-state-corrupt");
+        });
+        await confirmTypedAcknowledgement(options.prompter, "show mnemonic", "Type \"show mnemonic\" to continue: ", "wallet_show_mnemonic_typed_ack_required");
+        let mnemonicRevealed = false;
+        writeMnemonicReveal(options.prompter, loaded.state.mnemonic.phrase, [
+            "Cogcoin Wallet Recovery Phrase",
+            "This 24-word recovery phrase controls the wallet.",
+            "",
+        ]);
+        mnemonicRevealed = true;
+        try {
+            await options.prompter.prompt("Press Enter to clear the recovery phrase from the screen: ");
+        }
+        finally {
+            if (mnemonicRevealed) {
+                await Promise.resolve()
+                    .then(() => options.prompter.clearSensitiveDisplay?.("mnemonic-reveal"))
+                    .catch(() => undefined);
+            }
+        }
+    }
+    finally {
+        await controlLock.release();
+    }
+}

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

@@ -0,0 +1,125 @@
+import type { attachOrStartIndexerDaemon, probeIndexerDaemon } from "../../bitcoind/indexer-daemon.js";
+import type { createRpcClient } from "../../bitcoind/node.js";
+import type { attachOrStartManagedBitcoindService, probeManagedBitcoindService } from "../../bitcoind/service.js";
+import type { RpcListUnspentEntry } from "../../bitcoind/types.js";
+import type { requestMiningGenerationPreemption } from "../mining/coordination.js";
+import type { startBackgroundMining } from "../mining/runner.js";
+import type { WalletRuntimePaths } from "../runtime.js";
+import type { WalletSecretProvider } from "../state/provider.js";
+import type { WalletStateV1 } from "../types.js";
+export interface WalletPrompter {
+    readonly isInteractive: boolean;
+    writeLine(message: string): void;
+    prompt(message: string): Promise<string>;
+    promptHidden?(message: string): Promise<string>;
+    selectOption?(options: {
+        message: string;
+        options: Array<{
+            label: string;
+            description?: string | null;
+            value: string;
+        }>;
+        initialValue?: string | null;
+        footer?: string | null;
+    }): Promise<string>;
+    clearSensitiveDisplay?(scope: "mnemonic-reveal" | "restore-mnemonic-entry"): void | Promise<void>;
+}
+export interface WalletInitializationResult {
+    setupMode: "generated" | "restored" | "existing";
+    passwordAction: "created" | "migrated" | "already-configured";
+    walletAction: "initialized" | "already-initialized";
+    walletRootId: string;
+    fundingAddress: string;
+    state: WalletStateV1;
+}
+export interface WalletRepairResult {
+    walletRootId: string;
+    recoveredFromBackup: boolean;
+    recreatedManagedCoreWallet: boolean;
+    resetIndexerDatabase: boolean;
+    bitcoindServiceAction: "none" | "cleared-stale-artifacts" | "stopped-incompatible-service" | "restarted-compatible-service";
+    bitcoindCompatibilityIssue: "none" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch";
+    managedCoreReplicaAction: "none" | "recreated";
+    bitcoindPostRepairHealth: "ready" | "catching-up" | "starting" | "failed" | "unavailable";
+    indexerDaemonAction: "none" | "cleared-stale-artifacts" | "stopped-incompatible-daemon" | "restarted-compatible-daemon";
+    indexerCompatibilityIssue: "none" | "service-version-mismatch" | "wallet-root-mismatch" | "schema-mismatch";
+    indexerPostRepairHealth: "starting" | "catching-up" | "synced" | "failed";
+    miningPreRepairRunMode: "stopped" | "foreground" | "background";
+    miningResumeAction: "none" | "skipped-not-resumable" | "skipped-post-repair-blocked" | "resumed-background" | "resume-failed";
+    miningPostRepairRunMode: "stopped" | "background";
+    miningResumeError: string | null;
+    note: string | null;
+}
+export interface WalletLifecycleRpcClient {
+    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;
+    }>;
+    unloadWallet?(walletName: string, loadOnStartup?: boolean): Promise<null>;
+    listWallets(): Promise<string[]>;
+    listUnspent(walletName: string, minConf?: number): Promise<RpcListUnspentEntry[]>;
+    getBlockchainInfo(): Promise<{
+        blocks: number;
+        headers: number;
+    }>;
+}
+export interface WalletManagedCoreDependencies {
+    attachService?: typeof attachOrStartManagedBitcoindService;
+    rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletLifecycleRpcClient;
+}
+export interface WalletSetupDependencies extends WalletManagedCoreDependencies {
+}
+export interface WalletLifecycleResolvedContext {
+    provider: WalletSecretProvider;
+    paths: WalletRuntimePaths;
+    nowUnixMs: number;
+}
+export interface WalletSetupContext extends WalletLifecycleResolvedContext, WalletSetupDependencies {
+    dataDir: string;
+    prompter: WalletPrompter;
+}
+export interface WalletRepairDependencies extends WalletManagedCoreDependencies {
+    probeBitcoindService?: typeof probeManagedBitcoindService;
+    attachIndexerDaemon?: typeof attachOrStartIndexerDaemon;
+    probeIndexerDaemon?: typeof probeIndexerDaemon;
+    requestMiningPreemption?: typeof requestMiningGenerationPreemption;
+    startBackgroundMining?: typeof startBackgroundMining;
+}
+export interface WalletRepairContext extends WalletLifecycleResolvedContext, WalletRepairDependencies {
+    dataDir: string;
+    databasePath: string;
+    assumeYes: boolean;
+}

package/dist/wallet/lifecycle/types.js

@@ -0,0 +1 @@
+export {};