@cogcoin/client 1.1.16 → 1.2.0

package/README.md

@@ -1,22 +1,15 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@1.1.16` 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.2.0` 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 Cogcoin:
+## Installation
 
 ```bash
 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 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!
-cogcoin mine setup
-cogcoin mine # Use remaining ~0.0005 BTC for mining tx, ~1000 sats per entry (0.00001 BTC)
 ```
 
 ### What The Installer Does
@@ -33,6 +26,16 @@ cogcoin mine # Use remaining ~0.0005 BTC for mining tx, ~1000 sats per entry (0.
 - If you set `COGCOIN_SKIP_INIT=1`, the installer skips `cogcoin init` and prints the exact manual command to run later.
 - If macOS Command Line Tools are still installing, the installer either waits and retries automatically or prints the exact resume command.
 
+## Quick Start
+
+```bash
+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!
+cogcoin mine setup
+cogcoin mine # Use remaining ~0.0005 BTC for mining tx, ~1000 sats per entry (0.00001 BTC)
+```
+
 ## Preview
 
 ```bash
@@ -112,7 +115,7 @@ The published package depends on:
 
 - `@cogcoin/bitcoin@30.2.0`
 - `@cogcoin/genesis@1.0.0`
-- `@cogcoin/indexer@1.0.1`
+- `@cogcoin/indexer@1.0.2`
 - `@cogcoin/scoring@1.0.0`
 - `@scure/base@^2.0.0`
 - `@scure/bip32@^2.0.1`
@@ -121,7 +124,21 @@ The published package depends on:
 - `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.
+`@cogcoin/vectors@1.0.1` is kept as a repository development dependency for conformance tests and is not part of the published runtime dependency surface.
+
+## Upgrade Notes For `1.2.0`
+
+`@cogcoin/client@1.2.0` updates the runtime indexer to `@cogcoin/indexer@1.0.2`. Existing wallet state, mining configuration, Bitcoin Core data, and secrets remain compatible and are not reset.
+
+On the first managed indexer start after upgrading, `cogcoin sync`, `cogcoin mine`, `cogcoin follow`, and related managed-indexer commands automatically clear and replay the local Cogcoin indexer SQLite projection once. This is required so the local index contains the complete explorer history and winner `bip39WordIndices` produced by `@cogcoin/indexer@1.0.2`.
+
+Supabase mirror operators should let the local client replay and catch up first, then run:
+
+```bash
+cogcoin-supabase reset --yes --recreate-schema
+```
+
+Old snapshots may deserialize successfully but can lack historical explorer rows and required winner `bip39WordIndices` for blocks indexed before `@cogcoin/indexer@1.0.2`, so they should not be used as the source for a complete Supabase reset.
 
 ## API
 

package/dist/bitcoind/indexer-daemon/lifecycle.js

@@ -2,12 +2,13 @@ import { spawn } from "node:child_process";
 import { mkdir } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { acquireFileLock, FileLockBusyError } from "../../wallet/fs/lock.js";
-import { buildManagedIndexerStatusFromSnapshotHandle, validateIndexerSnapshotHandle, validateIndexerSnapshotPayload, } from "../managed-runtime/indexer-policy.js";
+import { buildManagedIndexerStatusFromSnapshotHandle, resolveIndexerDaemonProbeDecision, validateIndexerSnapshotHandle, validateIndexerSnapshotPayload, } from "../managed-runtime/indexer-policy.js";
 import { attachOrStartManagedIndexerRuntime } from "../managed-runtime/indexer-runtime.js";
 import { readJsonFileIfPresent } from "../managed-runtime/status.js";
 import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "../service-paths.js";
 import { createIndexerDaemonClient, probeIndexerDaemonAtSocket, } from "./client.js";
 import { DEFAULT_INDEXER_DAEMON_SHUTDOWN_TIMEOUT_MS, DEFAULT_INDEXER_DAEMON_STARTUP_TIMEOUT_MS, clearIndexerDaemonRuntimeArtifacts, isIndexerDaemonProcessAlive, sleep, stopIndexerDaemonService as stopIndexerDaemonServiceInternal, stopIndexerDaemonServiceWithLockHeld, waitForIndexerDaemon, } from "./process.js";
+import { ensureClientReindexRequirementV12, resolveClientReindexRequirementV12, } from "../../sqlite/reindex-requirement.js";
 import { openIndexerDaemonStartupLog, recordIndexerDaemonStartupFailure, waitForIndexerDaemonStartup, } from "./startup.js";
 export const INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED = "indexer_daemon_background_follow_recovery_failed";
 const INDEXER_DAEMON_BACKGROUND_FOLLOW_NOT_ACTIVE = "indexer_daemon_background_follow_not_active";
@@ -67,6 +68,93 @@ export async function readObservedIndexerDaemonStatus(options) {
     const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
     return readJsonFileIfPresent(paths.indexerDaemonStatusPath);
 }
+async function ensureV12ReindexRequirementBeforeIndexerStart(options) {
+    const readRequirement = async () => {
+        try {
+            return await resolveClientReindexRequirementV12(options.databasePath);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === "sqlite_store_schema_version_unsupported") {
+                // Let the daemon startup path surface and persist the existing
+                // schema-mismatch status instead of preempting it in this guard.
+                return "applied";
+            }
+            throw error;
+        }
+    };
+    const applyRequirement = async () => {
+        try {
+            await ensureClientReindexRequirementV12(options.databasePath);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === "sqlite_store_schema_version_unsupported") {
+                throw new Error("indexer_daemon_schema_mismatch", { cause: error });
+            }
+            throw error;
+        }
+    };
+    if (await readRequirement() === "applied") {
+        return;
+    }
+    const deadline = Date.now() + options.startupTimeoutMs;
+    while (true) {
+        let lock;
+        try {
+            lock = await acquireFileLock(options.paths.indexerDaemonLockPath, {
+                purpose: "indexer-reindex-v1.2.0",
+                walletRootId: options.walletRootId,
+                dataDir: options.dataDir,
+                databasePath: options.databasePath,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof FileLockBusyError)) {
+                throw error;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error("indexer_daemon_start_timeout");
+            }
+            await sleep(250);
+            if (await readRequirement() === "applied") {
+                return;
+            }
+            continue;
+        }
+        try {
+            const requirement = await readRequirement();
+            if (requirement === "applied") {
+                return;
+            }
+            const probe = await probeIndexerDaemonForStart({
+                dataDir: options.dataDir,
+                walletRootId: options.walletRootId,
+                paths: options.paths,
+            });
+            const decision = resolveIndexerDaemonProbeDecision({
+                probe,
+                expectedBinaryVersion: options.expectedBinaryVersion,
+            });
+            await probe.client?.close().catch(() => undefined);
+            if (decision.action === "reject") {
+                throw new Error(decision.error ?? "indexer_daemon_protocol_error");
+            }
+            if (decision.action === "replace" || requirement === "reset-required") {
+                await stopIndexerDaemonServiceWithLockHeld({
+                    dataDir: options.dataDir,
+                    walletRootId: options.walletRootId,
+                    shutdownTimeoutMs: options.shutdownTimeoutMs,
+                    paths: options.paths,
+                    processId: probe.status?.processId ?? null,
+                });
+            }
+            await applyRequirement();
+            return;
+        }
+        finally {
+            await lock.release();
+        }
+    }
+}
 export async function attachOrStartIndexerDaemon(options) {
     const requestBackgroundFollow = async (client, observedStatus = null) => {
         if (options.ensureBackgroundFollow !== true) {
@@ -87,6 +175,15 @@ export async function attachOrStartIndexerDaemon(options) {
     const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_INDEXER_DAEMON_STARTUP_TIMEOUT_MS;
     const serviceLifetime = options.serviceLifetime ?? "persistent";
     const expectedBinaryVersion = options.expectedBinaryVersion ?? null;
+    await ensureV12ReindexRequirementBeforeIndexerStart({
+        dataDir: options.dataDir,
+        databasePath: options.databasePath,
+        walletRootId,
+        paths,
+        startupTimeoutMs,
+        shutdownTimeoutMs: options.shutdownTimeoutMs,
+        expectedBinaryVersion,
+    });
     const startDaemon = async () => {
         await mkdir(paths.indexerServiceRoot, { recursive: true });
         const startupLog = await openIndexerDaemonStartupLog(paths);

package/dist/bitcoind/managed-bitcoind-service-config.js

@@ -158,6 +158,7 @@ export async function writeBitcoinConfForTesting(filePath, options, runtimeConfi
         `rpcport=${runtimeConfig.rpc.port}`,
         `port=${runtimeConfig.p2pPort}`,
         `zmqpubhashblock=tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
+        `zmqpubrawtx=tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
         `walletdir=${walletDir}`,
     ];
     await writeFileAtomic(filePath, `${lines.join("\n")}\n`, { mode: 0o600 });
@@ -172,6 +173,7 @@ export function buildManagedServiceArgsForTesting(options, runtimeConfig) {
         `-rpcport=${runtimeConfig.rpc.port}`,
         `-port=${runtimeConfig.p2pPort}`,
         `-zmqpubhashblock=tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
+        `-zmqpubrawtx=tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
         `-walletdir=${walletDir}`,
         "-server=1",
         "-prune=0",

package/dist/bitcoind/managed-bitcoind-service-lifecycle.js

@@ -173,6 +173,7 @@ export async function attachOrStartManagedBitcoindService(options) {
                     const zmqConfig = {
                         endpoint: `tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
                         topic: "hashblock",
+                        rawTxTopic: "rawtx",
                         port: runtimeConfig.zmqPort,
                         pollIntervalMs: startOptions.pollIntervalMs ?? DEFAULT_MANAGED_BITCOIND_FOLLOW_POLL_INTERVAL_MS,
                     };
@@ -193,7 +194,9 @@ export async function attachOrStartManagedBitcoindService(options) {
                     const rpc = createRpcClient(rpcConfig);
                     try {
                         await waitForManagedBitcoindRpcReady(rpc, rpcConfig.cookieFile, startOptions.chain, startupTimeoutMs);
-                        await validateNodeConfigForTesting(rpc, startOptions.chain, zmqConfig.endpoint);
+                        await validateNodeConfigForTesting(rpc, startOptions.chain, zmqConfig.endpoint, {
+                            requireRawTxZmq: true,
+                        });
                     }
                     catch (error) {
                         if (child.pid !== undefined) {

package/dist/bitcoind/node.d.ts

@@ -3,6 +3,8 @@ import { BitcoinRpcClient, type RpcTransportOptions } from "./rpc.js";
 import type { BitcoindRpcConfig, InternalManagedBitcoindOptions, ManagedBitcoindNodeHandle } from "./types.js";
 export { resolveDefaultBitcoindDataDirForTesting };
 export declare function buildBitcoindArgsForTesting(options: InternalManagedBitcoindOptions, rpcPort: number, zmqPort: number, p2pPort: number): string[];
-export declare function validateNodeConfigForTesting(rpcClient: BitcoinRpcClient, expectedChain: "main" | "regtest", zmqEndpoint: string): Promise<void>;
+export declare function validateNodeConfigForTesting(rpcClient: BitcoinRpcClient, expectedChain: "main" | "regtest", zmqEndpoint: string, options?: {
+    requireRawTxZmq?: boolean;
+}): Promise<void>;
 export declare function launchManagedBitcoindNode(options: InternalManagedBitcoindOptions): Promise<ManagedBitcoindNodeHandle>;
 export declare function createRpcClient(config: BitcoindRpcConfig, options?: RpcTransportOptions): BitcoinRpcClient;

package/dist/bitcoind/node.js

@@ -71,6 +71,7 @@ export function buildBitcoindArgsForTesting(options, rpcPort, zmqPort, p2pPort)
         `-rpcport=${rpcPort}`,
         `-port=${p2pPort}`,
         `-zmqpubhashblock=tcp://${LOCAL_HOST}:${zmqPort}`,
+        `-zmqpubrawtx=tcp://${LOCAL_HOST}:${zmqPort}`,
         "-server=1",
         "-disablewallet=1",
         "-prune=0",
@@ -120,7 +121,7 @@ async function waitForRpcReady(rpcClient, cookieFile, expectedChain, timeoutMs)
     }
     throw lastError instanceof Error ? lastError : new Error("bitcoind_rpc_timeout");
 }
-export async function validateNodeConfigForTesting(rpcClient, expectedChain, zmqEndpoint) {
+export async function validateNodeConfigForTesting(rpcClient, expectedChain, zmqEndpoint, options = {}) {
     const info = await rpcClient.getBlockchainInfo();
     if (info.chain !== expectedChain) {
         throw new Error(`bitcoind_chain_expected_${expectedChain}_got_${info.chain}`);
@@ -133,6 +134,12 @@ export async function validateNodeConfigForTesting(rpcClient, expectedChain, zmq
     if (!hasHashBlock) {
         throw new Error("bitcoind_zmq_hashblock_missing");
     }
+    if (options.requireRawTxZmq === true) {
+        const hasRawTx = notifications.some((notification) => notification.type === "pubrawtx" && notification.address === zmqEndpoint);
+        if (!hasRawTx) {
+            throw new Error("bitcoind_zmq_rawtx_missing");
+        }
+    }
 }
 export async function launchManagedBitcoindNode(options) {
     const resolvedOptions = resolveManagedBitcoindOptions(options);
@@ -156,6 +163,7 @@ export async function launchManagedBitcoindNode(options) {
     const zmqConfig = {
         endpoint: zmqEndpoint,
         topic: "hashblock",
+        rawTxTopic: "rawtx",
         port: zmqPort,
         pollIntervalMs: options.pollIntervalMs ?? DEFAULT_MANAGED_BITCOIND_FOLLOW_POLL_INTERVAL_MS,
     };
@@ -170,7 +178,9 @@ export async function launchManagedBitcoindNode(options) {
     child.stderr?.resume();
     try {
         await waitForRpcReady(rpcClient, cookieFile, resolvedOptions.chain, startupTimeoutMs);
-        await validateNodeConfigForTesting(rpcClient, resolvedOptions.chain, zmqEndpoint);
+        await validateNodeConfigForTesting(rpcClient, resolvedOptions.chain, zmqEndpoint, {
+            requireRawTxZmq: true,
+        });
     }
     catch (error) {
         child.kill("SIGTERM");
@@ -186,7 +196,9 @@ export async function launchManagedBitcoindNode(options) {
         getblockArchiveEndHeight: null,
         getblockArchiveSha256: null,
         async validate() {
-            await validateNodeConfigForTesting(rpcClient, resolvedOptions.chain, zmqEndpoint);
+            await validateNodeConfigForTesting(rpcClient, resolvedOptions.chain, zmqEndpoint, {
+                requireRawTxZmq: true,
+            });
         },
         async stop() {
             if (stopped) {

package/dist/bitcoind/types.d.ts

@@ -75,6 +75,7 @@ export interface BitcoindRpcConfig {
 export interface BitcoindZmqConfig {
     endpoint: string;
     topic: "hashblock";
+    rawTxTopic?: "rawtx";
     port: number;
     pollIntervalMs: number;
 }

package/dist/sqlite/reindex-requirement.d.ts

@@ -0,0 +1,8 @@
+export declare const CLIENT_REINDEX_REQUIREMENT_V1_2_0_KEY = "client_reindex_requirement_v1_2_0";
+export type ClientReindexRequirementAction = "already-applied" | "marked-empty" | "marked-current" | "reset-and-marked";
+export type ClientReindexRequirementStatus = "applied" | "mark-current" | "mark-empty" | "reset-required";
+export declare function isClientReindexRequirementV12Applied(databasePath: string): Promise<boolean>;
+export declare function resolveClientReindexRequirementV12(databasePath: string): Promise<ClientReindexRequirementStatus>;
+export declare function ensureClientReindexRequirementV12(databasePath: string): Promise<{
+    action: ClientReindexRequirementAction;
+}>;

package/dist/sqlite/reindex-requirement.js

@@ -0,0 +1,100 @@
+import { encodeText } from "../bytes.js";
+import { openSqliteDatabase } from "./driver.js";
+import { migrateSqliteStore } from "./migrate.js";
+import { clearTipMeta, TIP_META_KEYS } from "./tip-meta.js";
+export const CLIENT_REINDEX_REQUIREMENT_V1_2_0_KEY = "client_reindex_requirement_v1_2_0";
+const textDecoder = new TextDecoder();
+async function hasRows(database, sql, params = []) {
+    return (await database.get(sql, params)) !== null;
+}
+async function hasIndexerRows(database) {
+    const hasTipMeta = await hasRows(database, `SELECT 1 AS count FROM meta WHERE key = ? LIMIT 1`, [TIP_META_KEYS.tipHeight]);
+    if (hasTipMeta) {
+        return true;
+    }
+    if (await hasRows(database, `SELECT 1 AS count FROM checkpoints LIMIT 1`)) {
+        return true;
+    }
+    return await hasRows(database, `SELECT 1 AS count FROM block_records LIMIT 1`);
+}
+async function loadLatestStateBytes(database) {
+    const tipStateRow = await database.get(`SELECT value FROM meta WHERE key = ? LIMIT 1`, [TIP_META_KEYS.tipStateBytes]);
+    if (tipStateRow?.value !== undefined) {
+        return tipStateRow.value;
+    }
+    const checkpointRow = await database.get(`SELECT state_bytes FROM checkpoints ORDER BY height DESC LIMIT 1`);
+    return checkpointRow?.state_bytes ?? null;
+}
+function serializedStateIncludesV12HistoryShape(stateBytes) {
+    const serialized = textDecoder.decode(stateBytes);
+    return serialized.includes("\"explorerBlocksByHeight\"")
+        && serialized.includes("\"explorerTransactionsByHeight\"");
+}
+async function isRequirementApplied(database) {
+    const marker = await database.get(`SELECT value FROM meta WHERE key = ?`, [CLIENT_REINDEX_REQUIREMENT_V1_2_0_KEY]);
+    return marker !== null;
+}
+async function writeRequirementMarker(database) {
+    await database.run(`INSERT INTO meta (key, value) VALUES (?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`, [CLIENT_REINDEX_REQUIREMENT_V1_2_0_KEY, encodeText("applied")]);
+}
+export async function isClientReindexRequirementV12Applied(databasePath) {
+    const database = await openSqliteDatabase({ filename: databasePath });
+    try {
+        await migrateSqliteStore(database);
+        return await isRequirementApplied(database);
+    }
+    finally {
+        await database.close();
+    }
+}
+async function resolveRequirementStatus(database) {
+    if (await isRequirementApplied(database)) {
+        return "applied";
+    }
+    if (!await hasIndexerRows(database)) {
+        return "mark-empty";
+    }
+    const stateBytes = await loadLatestStateBytes(database);
+    if (stateBytes !== null && serializedStateIncludesV12HistoryShape(stateBytes)) {
+        return "mark-current";
+    }
+    return "reset-required";
+}
+export async function resolveClientReindexRequirementV12(databasePath) {
+    const database = await openSqliteDatabase({ filename: databasePath });
+    try {
+        await migrateSqliteStore(database);
+        return await resolveRequirementStatus(database);
+    }
+    finally {
+        await database.close();
+    }
+}
+export async function ensureClientReindexRequirementV12(databasePath) {
+    const database = await openSqliteDatabase({ filename: databasePath });
+    try {
+        await migrateSqliteStore(database);
+        return await database.transaction(async () => {
+            switch (await resolveRequirementStatus(database)) {
+                case "applied":
+                    return { action: "already-applied" };
+                case "mark-empty":
+                    await writeRequirementMarker(database);
+                    return { action: "marked-empty" };
+                case "mark-current":
+                    await writeRequirementMarker(database);
+                    return { action: "marked-current" };
+                case "reset-required":
+                    await clearTipMeta(database);
+                    await database.run(`DELETE FROM checkpoints`);
+                    await database.run(`DELETE FROM block_records`);
+                    await writeRequirementMarker(database);
+                    return { action: "reset-and-marked" };
+            }
+        });
+    }
+    finally {
+        await database.close();
+    }
+}

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

@@ -25,5 +25,10 @@ export declare function runCompetitivenessGate(options: {
     cooperativeYieldEvery?: number;
     throwIfStopping?: () => void;
     onWarmupProgress?: (progress: MiningGateWarmupProgress) => Promise<void> | void;
+    mempoolIndex?: {
+        rawTxSupported: boolean;
+        cachePath: string;
+        serviceIdentity: string;
+    };
 }): Promise<CompetitivenessDecision>;
 export {};