@cogcoin/client 1.1.11 → 1.1.13

package/README.md

@@ -1,16 +1,19 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@1.1.10` is the reference 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@1.1.13` is the reference 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.
 
 ## Quick Start
 
-Install the package:
+Install Cogcoin:
 
 ```bash
-npm install -g @cogcoin/client
-cogcoin init
+curl -fsSL https://cogcoin.org/install.sh | bash
+# or on Windows PowerShell:
+powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://cogcoin.org/install.ps1 | iex"
+
+# `cogcoin init` starts automatically in an interactive terminal and continues into sync.
 cogcoin address  # Send 0.0015 BTC to address
 cogcoin register <domainname> # 6+ character domain for 0.001 BTC
 cogcoin anchor <domainname> # You can leave a founding message permanently on Bitcoin!

package/dist/bitcoind/rpc.d.ts

@@ -1,4 +1,4 @@
-import type { RpcBlock, RpcBlockchainInfo, RpcChainStatesResponse, RpcCreateWalletResult, RpcDecodedPsbt, RpcDescriptorInfo, RpcEstimateSmartFeeResult, RpcFinalizePsbtResult, RpcImportDescriptorRequest, RpcImportDescriptorResult, RpcListUnspentEntry, RpcMempoolEntry, RpcMempoolInfo, RpcRawMempoolVerbose, RpcListDescriptorsResult, RpcLockedUnspent, RpcLoadTxOutSetResult, RpcLoadWalletResult, RpcNetworkInfo, RpcTestMempoolAcceptResult, RpcWalletInfo, RpcWalletCreateFundedPsbtResult, RpcWalletProcessPsbtResult, RpcTransaction, RpcWalletTransaction, RpcZmqNotification } from "./types.js";
+import type { RpcBlock, RpcBlockchainInfo, RpcChainStatesResponse, RpcCreateWalletResult, RpcDecodedPsbt, RpcDescriptorInfo, RpcEstimateSmartFeeResult, RpcFinalizePsbtResult, RpcImportDescriptorRequest, RpcImportDescriptorResult, RpcListUnspentEntry, RpcMempoolEntry, RpcMempoolInfo, RpcRawMempoolVerbose, RpcRawMempoolEntries, RpcListDescriptorsResult, RpcLockedUnspent, RpcLoadTxOutSetResult, RpcLoadWalletResult, RpcNetworkInfo, RpcTestMempoolAcceptResult, RpcWalletInfo, RpcWalletCreateFundedPsbtResult, RpcWalletProcessPsbtResult, RpcTransaction, RpcWalletTransaction, RpcZmqNotification } from "./types.js";
 interface RpcRequestPayload {
     readonly body: string;
     readonly headers: Record<string, string>;
@@ -62,6 +62,7 @@ export declare class BitcoinRpcClient {
     sendRawTransaction(hex: string): Promise<string>;
     getRawMempool(): Promise<string[]>;
     getRawMempoolVerbose(): Promise<RpcRawMempoolVerbose>;
+    getRawMempoolEntries(): Promise<RpcRawMempoolEntries>;
     getMempoolInfo(): Promise<RpcMempoolInfo>;
     getMempoolEntry(txid: string): Promise<RpcMempoolEntry>;
     estimateSmartFee(confirmTarget: number, mode: "conservative" | "economical"): Promise<RpcEstimateSmartFeeResult>;

package/dist/bitcoind/rpc.js

@@ -351,6 +351,9 @@ export class BitcoinRpcClient {
     getRawMempoolVerbose() {
         return this.call("getrawmempool", [false, true]);
     }
+    getRawMempoolEntries() {
+        return this.call("getrawmempool", [true]);
+    }
     getMempoolInfo() {
         return this.call("getmempoolinfo");
     }

package/dist/bitcoind/types.d.ts

@@ -313,6 +313,7 @@ export interface RpcRawMempoolVerbose {
     txids: string[];
     mempool_sequence: string | number;
 }
+export type RpcRawMempoolEntries = Record<string, RpcMempoolEntry>;
 export interface RpcWalletTransaction {
     txid: string;
     walletconflicts?: string[];

package/dist/cli/commands/mining-runtime.js

@@ -23,7 +23,9 @@ async function ensureMiningProviderSetup(options) {
         paths: options.runtimePaths,
     });
     if (!setupReady) {
-        throw new Error("Built-in mining provider is not configured. Run `cogcoin mine setup`.");
+        throw new Error(options.prompter.isInteractive
+            ? "Built-in mining provider is not configured. Run `cogcoin mine setup`."
+            : "mine_setup_requires_tty");
     }
 }
 function sleep(ms, signal) {

package/dist/wallet/mining/competitiveness.d.ts

@@ -1,6 +1,10 @@
 import { assaySentences } from "@cogcoin/scoring";
 import type { WalletReadContext } from "../read/index.js";
 import type { CompetitivenessDecision, MiningCandidate, MiningCooperativeYield, MiningRpcClient } from "./engine-types.js";
+interface MiningGateWarmupProgress {
+    processed: number;
+    total: number;
+}
 export declare function clearMiningGateCache(walletRootId: string | null | undefined): void;
 export declare function topologicallyOrderAncestorTxidsForTesting(options: {
     txid: string;
@@ -20,4 +24,6 @@ export declare function runCompetitivenessGate(options: {
     cooperativeYield?: MiningCooperativeYield;
     cooperativeYieldEvery?: number;
     throwIfStopping?: () => void;
+    onWarmupProgress?: (progress: MiningGateWarmupProgress) => Promise<void> | void;
 }): Promise<CompetitivenessDecision>;
+export {};

package/dist/wallet/mining/competitiveness.js

@@ -6,6 +6,8 @@ import { extractOpReturnPayloadFromScriptHex } from "../tx/register.js";
 import { compareLexicographically, numberToSats, resolveBip39WordsFromIndices, rootDomain, tieBreakHash, } from "./engine-utils.js";
 import { getIndexerTruthKey } from "./candidate.js";
 const MINING_MEMPOOL_COOPERATIVE_YIELD_EVERY = 25;
+const MINING_MEMPOOL_RAW_TX_FETCH_CONCURRENCY = 8;
+const MINING_MEMPOOL_PROGRESS_REPORT_EVERY = 25;
 const miningGateCache = new Map();
 function defaultMiningCooperativeYield() {
     return new Promise((resolve) => {
@@ -19,6 +21,98 @@ async function maybeYieldDuringMempoolScan(options) {
     }
     await (options.cooperativeYield ?? defaultMiningCooperativeYield)();
 }
+function getOrCreateMiningGateCacheState(walletRootId) {
+    const existing = miningGateCache.get(walletRootId);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const created = {
+        rawTxContexts: new Map(),
+        decisionReuse: null,
+    };
+    miningGateCache.set(walletRootId, created);
+    return created;
+}
+function pruneRawTxContextsToVisibleTxids(options) {
+    const visibleSet = new Set(options.visibleTxids);
+    for (const txid of [...options.rawTxContexts.keys()]) {
+        if (!visibleSet.has(txid)) {
+            options.rawTxContexts.delete(txid);
+        }
+    }
+}
+function resolveEffectiveFeeRate(mempoolEntry) {
+    return Number([
+        mempoolEntry.vsize > 0 ? (numberToSats(mempoolEntry.fees.base) / BigInt(mempoolEntry.vsize)) : 0n,
+        (mempoolEntry.ancestorsize ?? 0) > 0
+            ? (numberToSats(mempoolEntry.fees.ancestor) / BigInt(mempoolEntry.ancestorsize ?? 1))
+            : 0n,
+        (mempoolEntry.descendantsize ?? 0) > 0
+            ? (numberToSats(mempoolEntry.fees.descendant) / BigInt(mempoolEntry.descendantsize ?? 1))
+            : 0n,
+    ].reduce((best, candidate) => (candidate > best ? candidate : best), 0n));
+}
+async function warmMissingRawTxContexts(options) {
+    const missingTxids = options.visibleTxids.filter((txid) => !options.rawTxContexts.has(txid));
+    if (missingTxids.length === 0) {
+        return;
+    }
+    let completed = 0;
+    let nextIndex = 0;
+    let lastReportedProcessed = -1;
+    let reportPromise = Promise.resolve();
+    const reportProgress = async (processed, force = false) => {
+        if (options.onWarmupProgress === undefined) {
+            return;
+        }
+        if (!force && processed !== missingTxids.length && (processed % MINING_MEMPOOL_PROGRESS_REPORT_EVERY) !== 0) {
+            return;
+        }
+        if (processed === lastReportedProcessed) {
+            return;
+        }
+        lastReportedProcessed = processed;
+        reportPromise = reportPromise.then(async () => {
+            await options.onWarmupProgress?.({
+                processed,
+                total: missingTxids.length,
+            });
+        });
+        await reportPromise;
+    };
+    await reportProgress(0, true);
+    const workerCount = Math.min(MINING_MEMPOOL_RAW_TX_FETCH_CONCURRENCY, missingTxids.length);
+    const workers = Array.from({ length: workerCount }, async () => {
+        while (true) {
+            const iteration = nextIndex;
+            if (iteration >= missingTxids.length) {
+                return;
+            }
+            nextIndex += 1;
+            await maybeYieldDuringMempoolScan({
+                iteration,
+                cooperativeYield: options.cooperativeYield,
+                cooperativeYieldEvery: options.cooperativeYieldEvery,
+            });
+            options.throwIfStopping?.();
+            const txid = missingTxids[iteration];
+            const tx = await options.rpc.getRawTransaction(txid, true).catch(() => null);
+            options.throwIfStopping?.();
+            if (tx !== null) {
+                const payloadHex = tx.vout.find((entry) => entry.scriptPubKey?.hex?.startsWith("6a") === true)?.scriptPubKey?.hex;
+                options.rawTxContexts.set(txid, {
+                    txid,
+                    senderScriptHex: tx.vin[0]?.prevout?.scriptPubKey?.hex ?? null,
+                    rawTransaction: tx,
+                    payload: payloadHex === undefined ? null : extractOpReturnPayloadFromScriptHex(payloadHex),
+                });
+            }
+            completed += 1;
+            await reportProgress(completed, completed === missingTxids.length);
+        }
+    });
+    await Promise.all(workers);
+}
 export function clearMiningGateCache(walletRootId) {
     if (walletRootId === null || walletRootId === undefined) {
         miningGateCache.clear();
@@ -368,9 +462,25 @@ export async function runCompetitivenessGate(options) {
         options.candidate.canonicalBlend.toString(),
         options.candidate.sender.scriptPubKeyHex,
     ].join(":");
+    const cacheState = getOrCreateMiningGateCacheState(walletRootId);
+    const setDecisionReuse = (decision) => {
+        cacheState.decisionReuse = {
+            indexerDaemonInstanceId: indexerTruthKey?.daemonInstanceId ?? "none",
+            indexerSnapshotSeq: indexerTruthKey?.snapshotSeq ?? "none",
+            referencedBlockHashDisplay: options.candidate.referencedBlockHashDisplay,
+            localAssayTupleKey,
+            excludedTxidsKey: excludedTxids.join(","),
+            mempoolSequence,
+            decision,
+        };
+    };
     let mempoolVerbose;
+    let mempoolEntries;
     try {
-        mempoolVerbose = await options.rpc.getRawMempoolVerbose();
+        [mempoolVerbose, mempoolEntries] = await Promise.all([
+            options.rpc.getRawMempoolVerbose(),
+            options.rpc.getRawMempoolEntries(),
+        ]);
         options.throwIfStopping?.();
     }
     catch {
@@ -379,17 +489,17 @@ export async function runCompetitivenessGate(options) {
         });
     }
     const mempoolSequence = String(mempoolVerbose.mempool_sequence);
-    const cached = miningGateCache.get(walletRootId);
-    const cachedTruthMatches = cached !== undefined
+    const cached = cacheState.decisionReuse;
+    const cachedTruthMatches = cached !== null
         && indexerTruthKey !== null
         && cached.indexerDaemonInstanceId === indexerTruthKey.daemonInstanceId
         && cached.indexerSnapshotSeq === indexerTruthKey.snapshotSeq;
-    const cachedReferencedBlockMatches = cached !== undefined
+    const cachedReferencedBlockMatches = cached !== null
         && cached.referencedBlockHashDisplay === options.candidate.referencedBlockHashDisplay;
-    if (cached !== undefined && (!cachedTruthMatches || !cachedReferencedBlockMatches)) {
-        clearMiningGateCache(walletRootId);
+    if (cached !== null && (!cachedTruthMatches || !cachedReferencedBlockMatches)) {
+        cacheState.decisionReuse = null;
     }
-    if (cached !== undefined
+    if (cached !== null
         && cachedTruthMatches
         && cachedReferencedBlockMatches
         && cached.localAssayTupleKey === localAssayTupleKey
@@ -402,47 +512,19 @@ export async function runCompetitivenessGate(options) {
     }
     const referencedPrefix = Buffer.from(options.candidate.referencedBlockHashInternal.subarray(0, 4)).toString("hex");
     const visibleTxids = mempoolVerbose.txids.filter((txid) => !excludedTxids.includes(txid));
-    const txContexts = cachedTruthMatches && cachedReferencedBlockMatches
-        ? (cached?.txContexts ?? new Map())
-        : new Map();
-    for (const txid of [...txContexts.keys()]) {
-        if (!visibleTxids.includes(txid)) {
-            txContexts.delete(txid);
-        }
-    }
-    for (let index = 0; index < visibleTxids.length; index += 1) {
-        await maybeYieldDuringMempoolScan({
-            iteration: index,
-            cooperativeYield: options.cooperativeYield,
-            cooperativeYieldEvery: options.cooperativeYieldEvery,
-        });
-        options.throwIfStopping?.();
-        const txid = visibleTxids[index];
-        if (txContexts.has(txid)) {
-            continue;
-        }
-        const [tx, mempoolEntry] = await Promise.all([
-            options.rpc.getRawTransaction(txid, true).catch(() => null),
-            options.rpc.getMempoolEntry(txid).catch(() => null),
-        ]);
-        options.throwIfStopping?.();
-        if (tx === null || mempoolEntry === null) {
-            continue;
-        }
-        const effectiveFeeRate = Number([
-            mempoolEntry.vsize > 0 ? (numberToSats(mempoolEntry.fees.base) / BigInt(mempoolEntry.vsize)) : 0n,
-            (mempoolEntry.ancestorsize ?? 0) > 0 ? (numberToSats(mempoolEntry.fees.ancestor) / BigInt(mempoolEntry.ancestorsize ?? 1)) : 0n,
-            (mempoolEntry.descendantsize ?? 0) > 0 ? (numberToSats(mempoolEntry.fees.descendant) / BigInt(mempoolEntry.descendantsize ?? 1)) : 0n,
-        ].reduce((best, candidate) => (candidate > best ? candidate : best), 0n));
-        const payloadHex = tx.vout.find((entry) => entry.scriptPubKey?.hex?.startsWith("6a") === true)?.scriptPubKey?.hex;
-        txContexts.set(txid, {
-            txid,
-            effectiveFeeRate,
-            senderScriptHex: tx.vin[0]?.prevout?.scriptPubKey?.hex ?? null,
-            rawTransaction: tx,
-            payload: payloadHex === undefined ? null : extractOpReturnPayloadFromScriptHex(payloadHex),
-        });
-    }
+    pruneRawTxContextsToVisibleTxids({
+        rawTxContexts: cacheState.rawTxContexts,
+        visibleTxids,
+    });
+    await warmMissingRawTxContexts({
+        rpc: options.rpc,
+        rawTxContexts: cacheState.rawTxContexts,
+        visibleTxids,
+        cooperativeYield: options.cooperativeYield,
+        cooperativeYieldEvery: options.cooperativeYieldEvery,
+        throwIfStopping: options.throwIfStopping,
+        onWarmupProgress: options.onWarmupProgress,
+    });
     const entries = new Map();
     for (let index = 0; index < visibleTxids.length; index += 1) {
         await maybeYieldDuringMempoolScan({
@@ -452,8 +534,9 @@ export async function runCompetitivenessGate(options) {
         });
         options.throwIfStopping?.();
         const txid = visibleTxids[index];
-        const context = txContexts.get(txid);
-        if (context === undefined || context.payload === null || context.senderScriptHex === null) {
+        const context = cacheState.rawTxContexts.get(txid);
+        const mempoolEntry = mempoolEntries[txid];
+        if (context === undefined || context.payload === null || context.senderScriptHex === null || mempoolEntry === undefined) {
             continue;
         }
         const decoded = decodeMinePayload(context.payload);
@@ -463,7 +546,7 @@ export async function runCompetitivenessGate(options) {
         const overlayDomain = await resolveOverlayAuthorizedMiningDomain({
             readContext: options.readContext,
             txid,
-            txContexts,
+            txContexts: cacheState.rawTxContexts,
             domainId: decoded.domainId,
             senderScriptHex: context.senderScriptHex,
         });
@@ -475,17 +558,7 @@ export async function runCompetitivenessGate(options) {
                 mempoolSequenceCacheStatus: "refreshed",
                 lastMempoolSequence: mempoolSequence,
             });
-            miningGateCache.set(walletRootId, {
-                indexerDaemonInstanceId: indexerTruthKey?.daemonInstanceId ?? "none",
-                indexerSnapshotSeq: indexerTruthKey?.snapshotSeq ?? "none",
-                referencedBlockHashDisplay: options.candidate.referencedBlockHashDisplay,
-                localAssayTupleKey,
-                excludedTxidsKey: excludedTxids.join(","),
-                mempoolSequence,
-                txids: [...visibleTxids],
-                txContexts,
-                decision,
-            });
+            setDecisionReuse(decision);
             return decision;
         }
         if (overlayDomain === null || overlayDomain.name === null || !rootDomain(overlayDomain.name)) {
@@ -499,7 +572,7 @@ export async function runCompetitivenessGate(options) {
         }
         entries.set(txid, {
             txid,
-            effectiveFeeRate: context.effectiveFeeRate,
+            effectiveFeeRate: resolveEffectiveFeeRate(mempoolEntry),
             domainId: decoded.domainId,
             domainName: overlayDomain.name,
             sentence: Buffer.from(decoded.sentenceBytes).toString("utf8"),
@@ -631,16 +704,6 @@ export async function runCompetitivenessGate(options) {
             });
         }
     }
-    miningGateCache.set(walletRootId, {
-        indexerDaemonInstanceId: indexerTruthKey?.daemonInstanceId ?? "none",
-        indexerSnapshotSeq: indexerTruthKey?.snapshotSeq ?? "none",
-        referencedBlockHashDisplay: options.candidate.referencedBlockHashDisplay,
-        localAssayTupleKey,
-        excludedTxidsKey: excludedTxids.join(","),
-        mempoolSequence,
-        txids: [...visibleTxids],
-        txContexts,
-        decision,
-    });
+    setDecisionReuse(decision);
     return decision;
 }

package/dist/wallet/mining/cycle.js

@@ -339,6 +339,9 @@ export async function runMiningPhaseMachine(options) {
                     score: best.canonicalBlend.toString(),
                     runId: options.backgroundWorkerRunId,
                 }));
+                let lastScoringProgressProcessed = -1;
+                let lastScoringProgressSavedAtUnixMs = 0;
+                let scoringProgressWrite = Promise.resolve();
                 const gate = await runGateImpl({
                     rpc: options.rpc,
                     readContext: options.readContext,
@@ -348,7 +351,32 @@ export async function runMiningPhaseMachine(options) {
                     cooperativeYield: options.cooperativeYieldImpl,
                     cooperativeYieldEvery: options.cooperativeYieldEvery,
                     throwIfStopping: options.throwIfStopping,
+                    onWarmupProgress: async (progress) => {
+                        if (progress.total <= 0) {
+                            return;
+                        }
+                        const nowUnixMs = now();
+                        if (progress.processed === lastScoringProgressProcessed
+                            || (progress.processed !== 0
+                                && progress.processed !== progress.total
+                                && (nowUnixMs - lastScoringProgressSavedAtUnixMs) < 500)) {
+                            return;
+                        }
+                        lastScoringProgressProcessed = progress.processed;
+                        lastScoringProgressSavedAtUnixMs = nowUnixMs;
+                        scoringProgressWrite = scoringProgressWrite.then(async () => {
+                            await options.saveCycleStatus(options.readContext, {
+                                runMode: options.runMode,
+                                currentPhase: "scoring",
+                                currentPublishDecision: null,
+                                lastError: null,
+                                note: `Scoring mining candidates for the current tip (mempool ${progress.processed}/${progress.total}).`,
+                            });
+                        });
+                        await scoringProgressWrite;
+                    },
                 });
+                await scoringProgressWrite;
                 throwIfInterrupted();
                 state.gateSnapshot = {
                     higherRankedCompetitorDomainCount: gate.higherRankedCompetitorDomainCount,

package/dist/wallet/mining/engine-types.d.ts

@@ -28,6 +28,16 @@ export type MiningRpcClient = WalletMutationRpcClient & {
         txids: string[];
         mempool_sequence: string | number;
     }>;
+    getRawMempoolEntries(): Promise<Record<string, {
+        vsize: number;
+        fees: {
+            base: number;
+            ancestor: number;
+            descendant: number;
+        };
+        ancestorsize?: number;
+        descendantsize?: number;
+    }>>;
     getMempoolEntry(txid: string): Promise<{
         vsize: number;
         fees: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogcoin/client",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "description": "Store-backed Cogcoin client with wallet flows, SQLite persistence, and managed Bitcoin Core integration.",
   "license": "MIT",
   "type": "module",