@cogcoin/client 1.1.3 → 1.1.5

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

@@ -3,174 +3,18 @@ import { assaySentences } from "@cogcoin/scoring";
 import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopManagedBitcoindService } 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 { openWalletReadContext } 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 { generateCandidatesForDomains as generateCandidatesForDomainsModule } from "./candidate.js";
+import { runCompetitivenessGate as runCompetitivenessGateModule } from "./competitiveness.js";
+import { type MiningRuntimeLoopState } from "./engine-state.js";
+import { saveStopSnapshot } from "./lifecycle.js";
+import type { CompetitivenessDecision, MiningCandidate, MiningCooperativeYield, MiningRpcClient } from "./engine-types.js";
 import { requestMiningGenerationPreemption } from "./coordination.js";
-import { type MiningSentenceGenerationRequest } from "./sentences.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;
-        bestblockhash: string;
-        initialblockdownload?: boolean;
-    }>;
-    getNetworkInfo(): Promise<{
-        networkactive: boolean;
-        connections_out?: number;
-    }>;
-    getBlockHash(height: number): Promise<string>;
-    getBlock(hashHex: string): Promise<{
-        hash: string;
-        previousblockhash?: string;
-        height: number;
-        time?: number;
-    }>;
-    getMempoolInfo(): Promise<{
-        loaded: boolean;
-    }>;
-    getRawMempool(): Promise<string[]>;
-    getRawMempoolVerbose(): Promise<{
-        txids: string[];
-        mempool_sequence: string | number;
-    }>;
-    getMempoolEntry(txid: string): Promise<{
-        vsize: number;
-        fees: {
-            base: number;
-            ancestor: number;
-            descendant: number;
-        };
-        ancestorsize?: number;
-        descendantsize?: number;
-    }>;
-    getRawTransaction(txid: string, verbose?: boolean): Promise<{
-        txid: string;
-        hash?: string;
-        vin: Array<{
-            txid?: string;
-            prevout?: {
-                scriptPubKey?: {
-                    hex?: string;
-                };
-            };
-        }>;
-        vout: Array<{
-            n: number;
-            value: number | string;
-            scriptPubKey?: {
-                hex?: string;
-            };
-        }>;
-    }>;
-    getTransaction(walletName: string, txid: string): Promise<{
-        txid: string;
-        confirmations: number;
-        blockhash?: string;
-        walletconflicts?: string[];
-    }>;
-    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;
-    reconnectSettledUntilUnixMs?: number | null;
-    tipSettledUntilUnixMs?: 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;
-    localIndex: number;
-    sender: MutationSender;
-    sentence: string;
-    encodedSentenceBytes: Uint8Array;
-    bip39WordIndices: number[];
-    bip39Words: readonly string[];
-    canonicalBlend: bigint;
-    referencedBlockHashDisplay: string;
-    referencedBlockHashInternal: Uint8Array;
-    targetBlockHeight: number;
-}
-type ReadyMiningReadContext = WalletReadContext & {
-    localState: {
-        availability: "ready";
-        state: WalletStateV1;
-    };
-    snapshot: NonNullable<WalletReadContext["snapshot"]>;
-    model: NonNullable<WalletReadContext["model"]>;
-};
-interface MiningPublishSkipResult {
-    state: WalletStateV1;
-    txid: null;
-    decision: "publish-skipped-stale-candidate" | "publish-paused-insufficient-funds";
-    note: string;
-    lastError?: string | null;
-    skipped: true;
-    retryable?: false;
-    candidate: null;
-}
-interface MiningPublishRetryResult {
-    state: WalletStateV1;
-    txid: null;
-    decision: "publish-retry-pending";
-    note: string;
-    skipped?: false;
-    retryable: true;
-    candidate: MiningCandidate;
-}
-type MiningPublishOutcome = ({
-    skipped?: false;
-    retryable?: false;
-    note?: null;
-    candidate: MiningCandidate;
-} & Awaited<ReturnType<typeof publishCandidateOnce>>) | MiningPublishSkipResult | MiningPublishRetryResult;
-interface CompetitivenessDecision {
-    allowed: boolean;
-    decision: string;
-    sameDomainCompetitorSuppressed: boolean;
-    higherRankedCompetitorDomainCount: number;
-    dedupedCompetitorDomainCount: number;
-    competitivenessGateIndeterminate: boolean;
-    mempoolSequenceCacheStatus: MiningRuntimeStatusV1["mempoolSequenceCacheStatus"];
-    lastMempoolSequence: string | null;
-    visibleBoardEntries: MiningSentenceBoardEntry[];
-    candidateRank: number | null;
-}
+import type { MiningRuntimeStatusV1 } from "./types.js";
+import { MiningFollowVisualizer } from "./visualizer.js";
 interface RunnerDependencies {
     openReadContext?: typeof openWalletReadContext;
     attachService?: typeof attachOrStartManagedBitcoindService;
@@ -184,30 +28,7 @@ interface RunnerDependencies {
     shutdownGraceMs?: number;
     sleepImpl?: typeof sleep;
 }
-interface IndexerTruthKey {
-    walletRootId: string;
-    daemonInstanceId: string;
-    snapshotSeq: string;
-}
-interface MiningLoopState {
-    attemptedTipKey: string | null;
-    currentTipKey: string | null;
-    selectedCandidateTipKey: string | null;
-    selectedCandidate: MiningCandidate | null;
-    ui: MiningFollowVisualizerState;
-    waitingNote: string | null;
-    providerWaitState: "backoff" | "rate-limited" | "auth-error" | "not-found" | null;
-    providerWaitLastError: string | null;
-    providerWaitNextRetryAtUnixMs: number | null;
-    providerTransientFailureCount: number;
-    bitcoinRecoveryFirstFailureAtUnixMs: number | null;
-    bitcoinRecoveryFirstUnreachableAtUnixMs: number | null;
-    bitcoinRecoveryLastRestartAttemptAtUnixMs: number | null;
-    bitcoinRecoveryServiceInstanceId: string | null;
-    bitcoinRecoveryProcessId: number | null;
-    reconnectSettledUntilUnixMs: number | null;
-    tipSettledUntilUnixMs: number | null;
-}
+type MiningLoopState = MiningRuntimeLoopState;
 interface MiningSuspendDetector {
     lastHeartbeatMonotonicMs: number;
     detectedAtUnixMs: number | null;
@@ -221,7 +42,6 @@ interface MiningSuspendHeartbeatHandle {
 interface MiningSuspendScheduler {
     every(intervalMs: number, callback: () => void): MiningSuspendHeartbeatHandle;
 }
-type MiningCooperativeYield = () => Promise<void>;
 export interface RunForegroundMiningOptions extends RunnerDependencies {
     dataDir: string;
     databasePath: string;
@@ -241,6 +61,7 @@ export interface RunForegroundMiningOptions extends RunnerDependencies {
     signal?: AbortSignal;
     progressOutput?: ProgressOutputMode;
     paths?: WalletRuntimePaths;
+    visualizer?: MiningFollowVisualizer;
 }
 export interface StartBackgroundMiningOptions extends RunnerDependencies {
     dataDir: string;
@@ -260,186 +81,14 @@ 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: {
-    snapshotState: NonNullable<WalletReadContext["snapshot"]>["state"] | null | undefined;
-    snapshotTipHeight: number | null;
-    snapshotTipPreviousHashHex?: string | null;
-    nodeBestHeight: number | null;
-}): {
-    settledBlockHeight: number | null;
-    settledBoardEntries: MiningSentenceBoardEntry[];
-};
-export declare function getSelectedCandidateForTipForTesting(loopState: MiningLoopState, tipKey: string | null): MiningCandidate | null;
-export declare function cacheSelectedCandidateForTipForTesting(loopState: MiningLoopState, tipKey: string | null, candidate: MiningCandidate, liveState?: MiningStateRecord | null): void;
-export declare function resolveFundingDisplaySatsForTesting(state: WalletStateV1, rpc: MiningRpcClient): Promise<bigint>;
-export declare function loadMiningVisibleFollowBlockTimesForTesting(options: {
-    rpc: MiningRpcClient;
-    indexedTipHeight: number | null;
-    indexedTipHashHex: string | null;
-}): Promise<Record<number, number>>;
-export declare function syncMiningVisualizerBlockTimesForTesting(loopState: MiningLoopState, blockTimesByHeight: Record<number, number>): void;
-declare function appendEvent(paths: WalletRuntimePaths, event: MiningEventRecord): Promise<void>;
-declare function createMiningPlan(options: {
-    state: WalletStateV1;
-    candidate: MiningCandidate;
-    conflictOutpoint: OutpointRecord | null;
-    allUtxos: Awaited<ReturnType<MiningRpcClient["listUnspent"]>>;
-    feeRateSatVb: number;
-}): {
-    sender: MutationSender;
-    fixedInputs: FixedWalletInput[];
-    outputs: unknown[];
-    changeAddress: string;
-    changePosition: number;
-    expectedOpReturnScriptHex: string;
-    allowedFundingScriptPubKeyHex: string;
-    eligibleFundingOutpointKeys: Set<string>;
-    expectedConflictOutpoint: OutpointRecord | null;
-    feeRateSatVb: number;
-};
-export declare function createMiningPlanForTesting(options: {
-    state: WalletStateV1;
-    candidate: {
-        domainId: number;
-        domainName: string;
-        localIndex: number;
-        sender: MutationSender;
-        sentence: string;
-        encodedSentenceBytes: Uint8Array;
-        bip39WordIndices: number[];
-        bip39Words: readonly string[];
-        canonicalBlend: bigint;
-        referencedBlockHashDisplay: string;
-        referencedBlockHashInternal: Uint8Array;
-        targetBlockHeight: number;
-    };
-    conflictOutpoint: OutpointRecord | null;
-    allUtxos: Awaited<ReturnType<MiningRpcClient["listUnspent"]>>;
-    feeRateSatVb: number;
-}): {
-    sender: MutationSender;
-    fixedInputs: FixedWalletInput[];
-    outputs: unknown[];
-    changeAddress: string;
-    changePosition: number;
-    expectedOpReturnScriptHex: string;
-    allowedFundingScriptPubKeyHex: string;
-    eligibleFundingOutpointKeys: Set<string>;
-    expectedConflictOutpoint: OutpointRecord | null;
-    feeRateSatVb: number;
-};
-export declare function validateMiningDraftForTesting(decoded: Awaited<ReturnType<MiningRpcClient["decodePsbt"]>>, funded: Awaited<ReturnType<MiningRpcClient["walletCreateFundedPsbt"]>>, plan: ReturnType<typeof createMiningPlan>): void;
-declare function resolveEligibleAnchoredRoots(context: WalletReadContext): Array<{
-    domainId: number;
-    domainName: string;
-    localIndex: number;
-    sender: MutationSender;
-}>;
-export declare function refreshMiningCandidateFromCurrentStateForTesting(context: ReadyMiningReadContext, candidate: MiningCandidate): MiningCandidate | null;
-export declare function resolveMiningConflictOutpointForTesting(options: {
-    state: WalletStateV1;
-    allUtxos: Awaited<ReturnType<MiningRpcClient["listUnspent"]>>;
-}): OutpointRecord | null;
-export declare function buildMiningGenerationRequestForTesting(options: {
-    targetBlockHeight: number;
-    referencedBlockHashDisplay: string;
-    generatedAtUnixMs?: number;
-    requestId?: string;
-    domains: Array<{
-        domainId: number;
-        domainName: string;
-        requiredWords: [string, string, string, string, string];
-    }>;
-    domainExtraPrompts?: Record<string, string>;
-    extraPrompt?: string | null;
-}): MiningSentenceGenerationRequest;
-declare function generateCandidatesForDomains(options: {
-    rpc: MiningRpcClient;
-    readContext: WalletReadContext & {
-        localState: {
-            availability: "ready";
-            state: WalletStateV1;
-        };
-        snapshot: NonNullable<WalletReadContext["snapshot"]>;
-        model: NonNullable<WalletReadContext["model"]>;
-    };
-    domains: ReturnType<typeof resolveEligibleAnchoredRoots>;
-    provider: WalletSecretProvider;
-    paths: WalletRuntimePaths;
-    indexerTruthKey: IndexerTruthKey | null;
-    runId?: string | null;
-    fetchImpl?: typeof fetch;
-}): Promise<MiningCandidate[]>;
-declare function runCompetitivenessGate(options: {
-    rpc: MiningRpcClient;
-    readContext: WalletReadContext & {
-        snapshot: NonNullable<WalletReadContext["snapshot"]>;
-    };
-    candidate: MiningCandidate;
-    currentTxid: string | null;
-    assaySentencesImpl?: typeof assaySentences;
-    cooperativeYield?: MiningCooperativeYield;
-    cooperativeYieldEvery?: number;
-}): Promise<CompetitivenessDecision>;
-declare function publishCandidateOnce(options: {
-    readContext: WalletReadContext & {
-        localState: {
-            availability: "ready";
-            state: WalletStateV1;
-        };
-        snapshot: NonNullable<WalletReadContext["snapshot"]>;
-        model: NonNullable<WalletReadContext["model"]>;
-    };
-    candidate: MiningCandidate;
-    dataDir: string;
-    provider: WalletSecretProvider;
-    paths: WalletRuntimePaths;
-    attachService: typeof attachOrStartManagedBitcoindService;
-    rpcFactory: (config: Parameters<typeof createRpcClient>[0]) => MiningRpcClient;
-    runId: string | null;
-}): Promise<{
-    state: WalletStateV1;
-    txid: string | null;
-    decision: string;
-}>;
-export declare function publishCandidateForTesting(options: {
-    candidate: MiningCandidate;
-    dataDir: string;
-    databasePath: string;
-    provider: WalletSecretProvider;
-    paths: WalletRuntimePaths;
-    fallbackState: WalletStateV1;
-    openReadContext: typeof openWalletReadContext;
-    attachService: typeof attachOrStartManagedBitcoindService;
-    rpcFactory: (config: Parameters<typeof createRpcClient>[0]) => MiningRpcClient;
-    runId: string | null;
-    publishAttempt?: typeof publishCandidateOnce;
-    appendEventFn?: typeof appendEvent;
-}): Promise<MiningPublishOutcome>;
+declare function generateCandidatesForDomains(options: Parameters<typeof generateCandidatesForDomainsModule>[0]): Promise<MiningCandidate[]>;
+declare function runCompetitivenessGate(options: Parameters<typeof runCompetitivenessGateModule>[0]): Promise<CompetitivenessDecision>;
 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;
@@ -481,28 +130,6 @@ export declare function runBackgroundMiningWorker(options: RunnerDependencies &
     provider?: WalletSecretProvider;
     paths?: WalletRuntimePaths;
 }): Promise<void>;
-export declare function handleDetectedMiningRuntimeResumeForTesting(options: {
-    dataDir: string;
-    databasePath: string;
-    provider: WalletSecretProvider;
-    paths: WalletRuntimePaths;
-    runMode: "foreground" | "background";
-    backgroundWorkerPid: number | null;
-    backgroundWorkerRunId: string | null;
-    detectedAtUnixMs: number;
-    openReadContext: typeof openWalletReadContext;
-    visualizer?: MiningFollowVisualizer;
-    loopState?: MiningLoopState;
-}): 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;
@@ -559,43 +186,10 @@ export declare function runMiningLoopForTesting(options: {
     cooperativeYieldImpl?: MiningCooperativeYield;
     cooperativeYieldEvery?: number;
 }): Promise<void>;
-export declare function runCompetitivenessGateForTesting(options: {
-    rpc: MiningRpcClient;
-    readContext: WalletReadContext & {
-        snapshot: NonNullable<WalletReadContext["snapshot"]>;
-    };
-    candidate: MiningCandidate;
-    currentTxid: string | null;
-    assaySentencesImpl?: typeof assaySentences;
-    cooperativeYieldImpl?: MiningCooperativeYield;
-    cooperativeYieldEvery?: number;
-}): Promise<CompetitivenessDecision>;
 export declare function createMiningSuspendDetectorForTesting(options?: {
     monotonicNow?: () => number;
     nowUnixMs?: () => number;
     scheduler?: MiningSuspendScheduler;
 }): MiningSuspendDetector;
 export declare function throwIfMiningSuspendDetectedForTesting(detector: MiningSuspendDetector): void;
-export declare function topologicallyOrderAncestorTxidsForTesting(options: {
-    txid: string;
-    txContexts: Map<string, {
-        txid: string;
-        rawTransaction: Awaited<ReturnType<MiningRpcClient["getRawTransaction"]>>;
-    }>;
-}): string[] | null;
-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: {
-        domainId: number;
-        sender: MutationSender;
-        encodedSentenceBytes: Uint8Array;
-        referencedBlockHashDisplay: string;
-        targetBlockHeight: number;
-    };
-}): boolean;
 export {};