@cogcoin/client 1.0.0 → 1.0.2

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

@@ -1,14 +1,17 @@
+import { spawn } from "node:child_process";
 import { attachOrStartManagedBitcoindService } from "../../bitcoind/service.js";
 import { createRpcClient } from "../../bitcoind/node.js";
 import type { ProgressOutputMode } from "../../bitcoind/types.js";
 import { type FixedWalletInput, type MutationSender, type WalletMutationRpcClient } from "../tx/common.js";
+import { readLockMetadata } from "../fs/lock.js";
 import type { WalletPrompter } from "../lifecycle.js";
 import { openWalletReadContext, type WalletReadContext } from "../read/index.js";
 import { type WalletRuntimePaths } from "../runtime.js";
 import { type WalletSecretProvider } from "../state/provider.js";
 import type { MiningStateRecord, OutpointRecord, WalletStateV1 } from "../types.js";
-import type { MiningEventRecord, MiningRuntimeStatusV1 } from "./types.js";
-import { type MiningFollowVisualizerState, type MiningSentenceBoardEntry } from "./visualizer.js";
+import { requestMiningGenerationPreemption } from "./coordination.js";
+import type { MiningControlPlaneView, MiningEventRecord, MiningRuntimeStatusV1 } from "./types.js";
+import { type MiningFollowVisualizerState, type MiningSentenceBoardEntry, MiningFollowVisualizer } from "./visualizer.js";
 type MiningRpcClient = WalletMutationRpcClient & {
     getBlockchainInfo(): Promise<{
         blocks: number;
@@ -72,6 +75,39 @@ type MiningRpcClient = WalletMutationRpcClient & {
     sendRawTransaction(hex: string): Promise<string>;
     saveMempool?(): Promise<null>;
 };
+interface MiningRunnerStatusOverrides {
+    runMode?: MiningRuntimeStatusV1["runMode"];
+    backgroundWorkerPid?: number | null;
+    backgroundWorkerRunId?: string | null;
+    backgroundWorkerHeartbeatAtUnixMs?: number | null;
+    currentPhase?: MiningRuntimeStatusV1["currentPhase"];
+    currentPublishState?: MiningRuntimeStatusV1["currentPublishState"];
+    targetBlockHeight?: number | null;
+    referencedBlockHashDisplay?: string | null;
+    currentDomainId?: number | null;
+    currentDomainName?: string | null;
+    currentSentenceDisplay?: string | null;
+    currentCanonicalBlend?: string | null;
+    currentTxid?: string | null;
+    currentWtxid?: string | null;
+    currentFeeRateSatVb?: number | null;
+    currentAbsoluteFeeSats?: number | null;
+    currentBlockFeeSpentSats?: string;
+    lastSuspendDetectedAtUnixMs?: number | null;
+    providerState?: MiningRuntimeStatusV1["providerState"];
+    corePublishState?: MiningRuntimeStatusV1["corePublishState"];
+    currentPublishDecision?: string | null;
+    sameDomainCompetitorSuppressed?: boolean | null;
+    higherRankedCompetitorDomainCount?: number | null;
+    dedupedCompetitorDomainCount?: number | null;
+    competitivenessGateIndeterminate?: boolean | null;
+    mempoolSequenceCacheStatus?: MiningRuntimeStatusV1["mempoolSequenceCacheStatus"];
+    lastMempoolSequence?: string | null;
+    lastCompetitivenessGateAtUnixMs?: number | null;
+    lastError?: string | null;
+    note?: string | null;
+    livePublishInMempool?: boolean | null;
+}
 interface MiningCandidate {
     domainId: number;
     domainName: string;
@@ -97,8 +133,9 @@ type ReadyMiningReadContext = WalletReadContext & {
 interface MiningPublishSkipResult {
     state: WalletStateV1;
     txid: null;
-    decision: "publish-skipped-stale-candidate";
+    decision: "publish-skipped-stale-candidate" | "publish-paused-insufficient-funds";
     note: string;
+    lastError?: string | null;
     skipped: true;
     retryable?: false;
     candidate: null;
@@ -123,6 +160,13 @@ interface RunnerDependencies {
     attachService?: typeof attachOrStartManagedBitcoindService;
     rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => MiningRpcClient;
     fetchImpl?: typeof fetch;
+    requestMiningPreemption?: typeof requestMiningGenerationPreemption;
+    runMiningLoopImpl?: typeof runMiningLoop;
+    saveStopSnapshotImpl?: typeof saveStopSnapshot;
+    spawnWorkerProcess?: typeof spawn;
+    waitForBackgroundHealthyImpl?: typeof waitForBackgroundHealthy;
+    shutdownGraceMs?: number;
+    sleepImpl?: typeof sleep;
 }
 interface MiningLoopState {
     attemptedTipKey: string | null;
@@ -137,6 +181,7 @@ export interface RunForegroundMiningOptions extends RunnerDependencies {
     databasePath: string;
     provider?: WalletSecretProvider;
     prompter: WalletPrompter;
+    builtInSetupEnsured?: boolean;
     stdout?: {
         write(chunk: string): void;
     };
@@ -154,6 +199,7 @@ export interface StartBackgroundMiningOptions extends RunnerDependencies {
     databasePath: string;
     provider?: WalletSecretProvider;
     prompter: WalletPrompter;
+    builtInSetupEnsured?: boolean;
     paths?: WalletRuntimePaths;
 }
 export interface StopBackgroundMiningOptions extends RunnerDependencies {
@@ -166,6 +212,13 @@ export interface MiningStartResult {
     started: boolean;
     snapshot: MiningRuntimeStatusV1 | null;
 }
+interface MiningRuntimeTakeoverResult {
+    controlLockCleared: boolean;
+    replaced: boolean;
+    snapshot: MiningRuntimeStatusV1 | null;
+    terminatedPids: number[];
+}
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
 export declare function createMiningLoopStateForTesting(): MiningLoopState;
 export declare function resetMiningUiForTipForTesting(loopState: MiningLoopState, targetBlockHeight: number | null): void;
 export declare function resolveSettledBoardForTesting(options: {
@@ -276,6 +329,40 @@ export declare function publishCandidateForTesting(options: {
     publishAttempt?: typeof publishCandidateOnce;
     appendEventFn?: typeof appendEvent;
 }): Promise<MiningPublishOutcome>;
+export declare function ensureBuiltInMiningSetupIfNeeded(options: {
+    provider: WalletSecretProvider;
+    prompter: WalletPrompter;
+    paths: WalletRuntimePaths;
+}): Promise<boolean>;
+declare function saveStopSnapshot(options: {
+    dataDir: string;
+    databasePath: string;
+    provider: WalletSecretProvider;
+    paths: WalletRuntimePaths;
+    runMode: "foreground" | "background";
+    backgroundWorkerPid: number | null;
+    backgroundWorkerRunId: string | null;
+    note: string | null;
+}): Promise<void>;
+declare function runMiningLoop(options: {
+    dataDir: string;
+    databasePath: string;
+    provider: WalletSecretProvider;
+    paths: WalletRuntimePaths;
+    runMode: "foreground" | "background";
+    backgroundWorkerPid: number | null;
+    backgroundWorkerRunId: string | null;
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+    openReadContext: typeof openWalletReadContext;
+    attachService: typeof attachOrStartManagedBitcoindService;
+    rpcFactory: (config: Parameters<typeof createRpcClient>[0]) => MiningRpcClient;
+    stdout?: {
+        write(chunk: string): void;
+    };
+    visualizer?: MiningFollowVisualizer;
+}): Promise<void>;
+declare function waitForBackgroundHealthy(paths: WalletRuntimePaths): Promise<MiningRuntimeStatusV1 | null>;
 export declare function runForegroundMining(options: RunForegroundMiningOptions): Promise<void>;
 export declare function startBackgroundMining(options: StartBackgroundMiningOptions): Promise<MiningStartResult>;
 export declare function stopBackgroundMining(options: StopBackgroundMiningOptions): Promise<MiningRuntimeStatusV1 | null>;
@@ -296,7 +383,17 @@ export declare function handleDetectedMiningRuntimeResumeForTesting(options: {
     backgroundWorkerRunId: string | null;
     detectedAtUnixMs: number;
     openReadContext: typeof openWalletReadContext;
+    visualizer?: MiningFollowVisualizer;
 }): Promise<void>;
+export declare function takeOverMiningRuntimeForTesting(options: {
+    paths: WalletRuntimePaths;
+    reason: string;
+    clearControlLockFile?: boolean;
+    controlLockMetadata?: Awaited<ReturnType<typeof readLockMetadata>>;
+    requestMiningPreemption?: typeof requestMiningGenerationPreemption;
+    shutdownGraceMs?: number;
+    sleepImpl?: typeof sleep;
+}): Promise<MiningRuntimeTakeoverResult>;
 export declare function performMiningCycleForTesting(options: {
     dataDir: string;
     databasePath: string;
@@ -315,6 +412,11 @@ export declare function performMiningCycleForTesting(options: {
     };
     loopState?: MiningLoopState;
 }): Promise<void>;
+export declare function buildPrePublishStatusOverridesForTesting(options: {
+    state: WalletStateV1;
+    candidate: MiningCandidate;
+}): MiningRunnerStatusOverrides;
+export declare function buildStatusSnapshotForTesting(view: MiningControlPlaneView, overrides?: MiningRunnerStatusOverrides): MiningRuntimeStatusV1;
 export declare function shouldKeepCurrentTipLivePublishForTesting(options: {
     liveState: MiningStateRecord;
     candidate: {