@cogcoin/client 0.5.0

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

@@ -0,0 +1,141 @@
+import type { ManagedBitcoindHealth, ManagedIndexerTruthSource } from "../../bitcoind/types.js";
+import type { MiningHookOperatorValidationState } from "./hook-protocol.js";
+export type MiningServiceHealth = "synced" | "catching-up" | "reorging" | "starting" | "stale-heartbeat" | "failed" | "schema-mismatch" | "service-version-mismatch" | "wallet-root-mismatch" | "unavailable";
+export type MiningProviderKind = "openai" | "anthropic";
+export interface MiningProviderConfigRecord {
+    provider: MiningProviderKind;
+    apiKey: string;
+    extraPrompt: string | null;
+    modelOverride: string | null;
+    updatedAtUnixMs: number;
+}
+export interface ClientConfigV1 {
+    schemaVersion: 1;
+    mining: {
+        builtIn: MiningProviderConfigRecord | null;
+    };
+}
+export interface MiningEventRecord {
+    schemaVersion: 1;
+    timestampUnixMs: number;
+    level: "info" | "warn" | "error";
+    kind: string;
+    message: string;
+    targetBlockHeight?: number | null;
+    referencedBlockHashDisplay?: string | null;
+    domainId?: number | null;
+    domainName?: string | null;
+    txid?: string | null;
+    feeRateSatVb?: number | null;
+    feeSats?: string | null;
+    score?: string | null;
+    reason?: string | null;
+    runId?: string | null;
+}
+export interface MiningRuntimeStatusV1 {
+    schemaVersion: 1;
+    walletRootId: string | null;
+    workerApiVersion: "cogcoin/mining-worker/v1" | null;
+    workerBinaryVersion: string | null;
+    workerBuildId: string | null;
+    updatedAtUnixMs: number;
+    runMode: "stopped" | "foreground" | "background";
+    backgroundWorkerPid: number | null;
+    backgroundWorkerRunId: string | null;
+    backgroundWorkerHeartbeatAtUnixMs: number | null;
+    backgroundWorkerHealth: "healthy" | "stale-pid" | "stale-heartbeat" | "version-mismatch" | null;
+    indexerDaemonState: "unavailable" | "starting" | "catching-up" | "reorging" | "synced" | "stale-heartbeat" | "failed" | "schema-mismatch" | "service-version-mismatch" | "wallet-root-mismatch" | null;
+    indexerDaemonInstanceId: string | null;
+    indexerSnapshotSeq?: string | null;
+    indexerSnapshotOpenedAtUnixMs?: number | null;
+    indexerTruthSource?: ManagedIndexerTruthSource;
+    indexerHeartbeatAtUnixMs: number | null;
+    coreBestHeight: number | null;
+    coreBestHash: string | null;
+    indexerTipHeight: number | null;
+    indexerTipHash: string | null;
+    indexerReorgDepth: number | null;
+    indexerTipAligned: boolean | null;
+    corePublishState: "unknown" | "network-inactive" | "no-outbound-peers" | "ibd" | "mempool-loading" | "healthy" | null;
+    providerState: "n/a" | "ready" | "backoff" | "unavailable" | "rate-limited" | "auth-error" | "hook-error" | null;
+    lastSuspendDetectedAtUnixMs: number | null;
+    reconnectSettledUntilUnixMs: number | null;
+    tipSettledUntilUnixMs: number | null;
+    miningState: "idle" | "live" | "paused" | "paused-stale" | "repair-required";
+    currentPhase: "idle" | "generating" | "scoring" | "publishing" | "replacing" | "waiting" | "waiting-provider" | "waiting-bitcoin-network" | "waiting-indexer" | "resuming";
+    currentPublishState: "none" | "broadcasting" | "broadcast-unknown" | "in-mempool";
+    targetBlockHeight: number | null;
+    referencedBlockHashDisplay: string | null;
+    currentDomainId: number | null;
+    currentDomainName: string | null;
+    currentSentenceDisplay: string | null;
+    currentCanonicalBlend: string | null;
+    currentTxid: string | null;
+    currentWtxid: string | null;
+    liveMiningFamilyInMempool: boolean | null;
+    currentFeeRateSatVb: number | null;
+    currentAbsoluteFeeSats: number | null;
+    currentBlockFeeSpentSats: string;
+    sessionFeeSpentSats: string;
+    lifetimeFeeSpentSats: string;
+    sameDomainCompetitorSuppressed: boolean | null;
+    higherRankedCompetitorDomainCount: number | null;
+    dedupedCompetitorDomainCount: number | null;
+    competitivenessGateIndeterminate: boolean | null;
+    mempoolSequenceCacheStatus: "reused" | "refreshed" | null;
+    currentPublishDecision: string | null;
+    lastMempoolSequence: string | null;
+    lastCompetitivenessGateAtUnixMs: number | null;
+    pauseReason: string | null;
+    hookMode: "builtin" | "custom";
+    providerConfigured: boolean;
+    providerKind: MiningProviderKind | null;
+    bitcoindHealth: ManagedBitcoindHealth;
+    bitcoindServiceState: "starting" | "ready" | "stopping" | "failed" | null;
+    bitcoindReplicaStatus: "not-proven" | "ready" | "missing" | "mismatch" | null;
+    nodeHealth: MiningServiceHealth;
+    indexerHealth: MiningServiceHealth;
+    tipsAligned: boolean | null;
+    lastValidationState: "unknown" | "validated" | "stale" | "failed" | null;
+    lastOperatorValidationState: MiningHookOperatorValidationState | null;
+    lastValidationAtUnixMs: number | null;
+    lastEventAtUnixMs: number | null;
+    lastError: string | null;
+    note: string | null;
+}
+export interface MiningHookInspection {
+    mode: "builtin" | "custom" | "disabled" | "unavailable";
+    entrypointPath: string;
+    packagePath: string;
+    entrypointExists: boolean;
+    packageStatus: "valid" | "missing" | "invalid";
+    packageMessage: string | null;
+    trustStatus: "trusted" | "untrusted" | "missing";
+    trustMessage: string | null;
+    validationState: "unknown" | "validated" | "stale" | "failed" | "unavailable";
+    operatorValidationState: MiningHookOperatorValidationState;
+    validationError: string | null;
+    validatedAtUnixMs: number | null;
+    validatedLaunchFingerprint: string | null;
+    validatedFullFingerprint: string | null;
+    currentLaunchFingerprint: string | null;
+    currentFullFingerprint: string | null;
+    verifyUsed: boolean;
+    cooldownUntilUnixMs: number | null;
+    cooldownActive: boolean;
+    consecutiveFailureCount: number;
+}
+export interface MiningProviderInspection {
+    configured: boolean;
+    provider: MiningProviderKind | null;
+    status: "ready" | "missing" | "error";
+    message: string | null;
+    modelOverride: string | null;
+    extraPromptConfigured: boolean;
+}
+export interface MiningControlPlaneView {
+    runtime: MiningRuntimeStatusV1;
+    hook: MiningHookInspection;
+    provider: MiningProviderInspection;
+    lastEventAtUnixMs: number | null;
+}

package/dist/wallet/mining/types.js

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

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

@@ -0,0 +1,19 @@
+import type { ProgressOutputMode } from "../../bitcoind/types.js";
+import type { MiningRuntimeStatusV1 } from "./types.js";
+interface RenderStream {
+    isTTY?: boolean;
+    columns?: number;
+    write(chunk: string): boolean | void;
+}
+export declare function describeMiningVisualizerStatus(snapshot: MiningRuntimeStatusV1): string;
+export declare function describeMiningVisualizerProgress(snapshot: MiningRuntimeStatusV1): string;
+export declare class MiningFollowVisualizer {
+    #private;
+    constructor(options?: {
+        progressOutput?: ProgressOutputMode;
+        stream?: RenderStream;
+    });
+    update(snapshot: MiningRuntimeStatusV1): void;
+    close(): void;
+}
+export {};

package/dist/wallet/mining/visualizer.js

@@ -0,0 +1,134 @@
+import { createBootstrapProgress } from "../../bitcoind/progress/formatting.js";
+import { createFollowSceneState, syncFollowSceneState, } from "../../bitcoind/progress/follow-scene.js";
+import { TtyProgressRenderer } from "../../bitcoind/progress/tty-renderer.js";
+const VISUALIZER_PROGRESS_SNAPSHOT = {
+    url: "",
+    filename: "mining-follow-visualizer",
+    height: 0,
+    sha256: "",
+    sizeBytes: 1,
+};
+function shouldRenderToTty(progressOutput, stream) {
+    if (progressOutput === "none") {
+        return false;
+    }
+    if (progressOutput === "tty") {
+        return true;
+    }
+    return stream.isTTY === true;
+}
+export function describeMiningVisualizerStatus(snapshot) {
+    switch (snapshot.currentPhase) {
+        case "resuming":
+            return "Resuming after suspend";
+        case "waiting-provider":
+            return snapshot.providerState === "hook-error"
+                ? "Waiting for hook"
+                : "Waiting for provider";
+        case "waiting-indexer":
+            return snapshot.indexerDaemonState === "reorging"
+                ? "Indexer replaying reorg"
+                : "Waiting for indexer";
+        case "waiting-bitcoin-network":
+            return "Waiting for Bitcoin node";
+        case "generating":
+            return "Generating candidates";
+        case "scoring":
+            return "Scoring candidates";
+        case "publishing":
+            return snapshot.currentPublishDecision === "fee-bump"
+                ? "Fee-bumping mining tx"
+                : snapshot.currentPublishDecision === "replacing"
+                    || snapshot.currentPublishDecision === "replaced"
+                    ? "Replacing mining tx"
+                    : "Broadcasting mining tx";
+        case "replacing":
+            return "Replacing mining tx";
+        default:
+            break;
+    }
+    if (snapshot.miningState === "repair-required") {
+        return "Mining repair required";
+    }
+    if (snapshot.pauseReason === "zero-reward") {
+        return "Zero-reward height";
+    }
+    if (snapshot.currentPublishDecision === "suppressed-same-domain-mempool") {
+        return "Same-domain tx already live";
+    }
+    if (snapshot.currentPublishDecision === "suppressed-top5-mempool") {
+        return "Stronger mempool roots live";
+    }
+    if (snapshot.currentPublishDecision === "indeterminate-mempool-gate") {
+        return "Mempool gate indeterminate";
+    }
+    if (snapshot.liveMiningFamilyInMempool) {
+        return "Waiting for next block";
+    }
+    return "Waiting for next block";
+}
+export function describeMiningVisualizerProgress(snapshot) {
+    if (snapshot.note !== null && snapshot.note !== undefined && snapshot.note.length > 0) {
+        return snapshot.note;
+    }
+    switch (snapshot.currentPhase) {
+        case "resuming":
+            return "Mining discarded stale in-flight work after a large local runtime gap and is rechecking health.";
+        case "waiting-provider":
+            return "Mining is waiting for the sentence provider to recover.";
+        case "waiting-indexer":
+            return "Mining is waiting for Bitcoin Core and the indexer to align.";
+        case "waiting-bitcoin-network":
+            return "Mining is waiting for the local Bitcoin node to become publishable.";
+        case "generating":
+            return "Generating mining sentences for eligible root domains.";
+        case "scoring":
+            return "Scoring mining candidates for the current tip.";
+        case "publishing":
+            return snapshot.currentPublishDecision === "fee-bump"
+                ? "Publishing a fee bump for the live mining family."
+                : snapshot.currentPublishDecision === "replacing"
+                    || snapshot.currentPublishDecision === "replaced"
+                    ? "Replacing the live mining transaction for the current tip."
+                    : "Broadcasting the best mining candidate for the current tip.";
+        case "replacing":
+            return "Replacing the live mining transaction for the current tip.";
+        default:
+            return "Waiting for the next block while mining stays ready on the current tip.";
+    }
+}
+export class MiningFollowVisualizer {
+    #renderer;
+    #progress = createBootstrapProgress("follow_tip", VISUALIZER_PROGRESS_SNAPSHOT);
+    #scene = createFollowSceneState();
+    constructor(options = {}) {
+        const stream = options.stream ?? process.stderr;
+        const progressOutput = options.progressOutput ?? "auto";
+        this.#renderer = shouldRenderToTty(progressOutput, stream)
+            ? new TtyProgressRenderer(stream)
+            : null;
+    }
+    update(snapshot) {
+        if (this.#renderer === null) {
+            return;
+        }
+        const indexedHeight = snapshot.indexerTipHeight ?? snapshot.coreBestHeight ?? null;
+        const nodeHeight = snapshot.coreBestHeight ?? indexedHeight;
+        this.#progress.phase = "follow_tip";
+        this.#progress.message = describeMiningVisualizerProgress(snapshot);
+        this.#progress.updatedAt = Date.now();
+        this.#progress.blocks = nodeHeight;
+        this.#progress.targetHeight = nodeHeight;
+        this.#progress.etaSeconds = null;
+        this.#progress.lastError = snapshot.lastError;
+        syncFollowSceneState(this.#scene, {
+            indexedHeight,
+            nodeHeight,
+            liveActivated: true,
+        });
+        this.#renderer.renderFollowScene(this.#progress, indexedHeight, nodeHeight, this.#scene, describeMiningVisualizerStatus(snapshot));
+    }
+    close() {
+        this.#renderer?.close();
+    }
+}

package/dist/wallet/mining/worker-main.d.ts

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

package/dist/wallet/mining/worker-main.js

@@ -0,0 +1,17 @@
+import { runBackgroundMiningWorker } from "./runner.js";
+function readFlag(name) {
+    const prefix = `--${name}=`;
+    const match = process.argv.find((entry) => entry.startsWith(prefix));
+    return match === undefined ? null : match.slice(prefix.length);
+}
+const dataDir = readFlag("data-dir");
+const databasePath = readFlag("database-path");
+const runId = readFlag("run-id");
+if (dataDir === null || databasePath === null || runId === null) {
+    throw new Error("mining_worker_missing_args");
+}
+await runBackgroundMiningWorker({
+    dataDir,
+    databasePath,
+    runId,
+});

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

@@ -0,0 +1,20 @@
+import { readSnapshotWithRetry } from "../../bitcoind/indexer-daemon.js";
+import { type WalletSecretProvider } from "../state/provider.js";
+import type { WalletLocalStateStatus, WalletReadContext } from "./types.js";
+import type { WalletRuntimePaths } from "../runtime.js";
+declare function inspectWalletLocalState(options?: {
+    passphrase?: Uint8Array | string;
+    secretProvider?: WalletSecretProvider;
+    now?: number;
+    paths?: WalletRuntimePaths;
+}): Promise<WalletLocalStateStatus>;
+export declare function openWalletReadContext(options: {
+    dataDir: string;
+    databasePath: string;
+    walletStatePassphrase?: Uint8Array | string;
+    secretProvider?: WalletSecretProvider;
+    startupTimeoutMs?: number;
+    now?: number;
+    paths?: WalletRuntimePaths;
+}): Promise<WalletReadContext>;
+export { inspectWalletLocalState, readSnapshotWithRetry, };