@cogcoin/client 1.1.3 → 1.1.5

package/dist/wallet/mining/engine-state.js

@@ -0,0 +1,211 @@
+import { createEmptyMiningFollowVisualizerState } from "./visualizer.js";
+import { MiningProviderRequestError } from "./sentences.js";
+import { clearMiningGateCache } from "./competitiveness.js";
+import { MINING_NETWORK_SETTLE_WINDOW_MS, MINING_PROVIDER_BACKOFF_BASE_MS, MINING_PROVIDER_BACKOFF_MAX_MS, MINING_TIP_SETTLE_WINDOW_MS, } from "./constants.js";
+import { miningPublishIsInMempool, normalizeMiningPublishState, normalizeMiningStateRecord, } from "./state.js";
+export function createMiningRuntimeLoopState() {
+    return {
+        attemptedTipKey: null,
+        currentTipKey: null,
+        selectedCandidateTipKey: null,
+        selectedCandidate: null,
+        ui: createEmptyMiningFollowVisualizerState(),
+        waitingNote: null,
+        providerWaitState: null,
+        providerWaitLastError: null,
+        providerWaitNextRetryAtUnixMs: null,
+        providerTransientFailureCount: 0,
+        bitcoinRecoveryFirstFailureAtUnixMs: null,
+        bitcoinRecoveryFirstUnreachableAtUnixMs: null,
+        bitcoinRecoveryLastRestartAttemptAtUnixMs: null,
+        bitcoinRecoveryServiceInstanceId: null,
+        bitcoinRecoveryProcessId: null,
+        reconnectSettledUntilUnixMs: null,
+        tipSettledUntilUnixMs: null,
+    };
+}
+export function cloneMiningState(state) {
+    const normalized = normalizeMiningStateRecord(state);
+    return {
+        ...normalized,
+        currentBip39WordIndices: normalized.currentBip39WordIndices === null ? null : [...normalized.currentBip39WordIndices],
+        sharedMiningConflictOutpoint: normalized.sharedMiningConflictOutpoint === null
+            ? null
+            : { ...normalized.sharedMiningConflictOutpoint },
+    };
+}
+export function defaultMiningStatePatch(state, patch) {
+    return {
+        ...state,
+        miningState: {
+            ...cloneMiningState(state.miningState),
+            ...patch,
+            currentPublishState: normalizeMiningPublishState(patch.currentPublishState ?? state.miningState.currentPublishState),
+        },
+    };
+}
+export function hasBlockingMutation(state) {
+    return (state.pendingMutations ?? []).some((mutation) => mutation.status === "draft"
+        || mutation.status === "broadcasting"
+        || mutation.status === "broadcast-unknown"
+        || mutation.status === "live"
+        || mutation.status === "repair-required");
+}
+export function livePublishTargetsCandidateTip(options) {
+    const liveState = normalizeMiningStateRecord(options.liveState);
+    return liveState.currentTxid !== null
+        && liveState.currentPublishState === "in-mempool"
+        && liveState.livePublishInMempool === true
+        && liveState.currentReferencedBlockHashDisplay === options.candidate.referencedBlockHashDisplay
+        && liveState.currentBlockTargetHeight === options.candidate.targetBlockHeight;
+}
+export function miningCandidateIsCurrent(options) {
+    return options.state.currentReferencedBlockHashDisplay !== null
+        && options.nodeBestHash !== null
+        && options.state.currentReferencedBlockHashDisplay === options.nodeBestHash
+        && options.state.currentBlockTargetHeight !== null
+        && options.nodeBestHeight !== null
+        && options.state.currentBlockTargetHeight === (options.nodeBestHeight + 1);
+}
+export function resolveSharedMiningConflictOutpoint(state) {
+    const normalizedMiningState = normalizeMiningStateRecord(state);
+    if (miningPublishIsInMempool(normalizedMiningState) && normalizedMiningState.sharedMiningConflictOutpoint !== null) {
+        return { ...normalizedMiningState.sharedMiningConflictOutpoint };
+    }
+    return null;
+}
+function resolveMiningProviderBackoffDelayMs(consecutiveFailureCount) {
+    const exponent = Math.max(consecutiveFailureCount - 1, 0);
+    return Math.min(MINING_PROVIDER_BACKOFF_BASE_MS * (2 ** exponent), MINING_PROVIDER_BACKOFF_MAX_MS);
+}
+export function clearMiningProviderWait(loopState, resetTransientFailureCount = true) {
+    loopState.providerWaitState = null;
+    loopState.providerWaitLastError = null;
+    loopState.providerWaitNextRetryAtUnixMs = null;
+    if (resetTransientFailureCount) {
+        loopState.providerTransientFailureCount = 0;
+    }
+}
+export function recordTransientMiningProviderWait(options) {
+    options.loopState.providerTransientFailureCount += 1;
+    options.loopState.providerWaitState = options.error.providerState === "rate-limited"
+        ? "rate-limited"
+        : "backoff";
+    options.loopState.providerWaitLastError = options.error.message;
+    options.loopState.providerWaitNextRetryAtUnixMs = options.nowUnixMs
+        + resolveMiningProviderBackoffDelayMs(options.loopState.providerTransientFailureCount);
+}
+export function recordTerminalMiningProviderWait(options) {
+    clearMiningProviderWait(options.loopState);
+    if (options.error.providerState !== "auth-error" && options.error.providerState !== "not-found") {
+        throw new Error("mining_provider_wait_state_invalid");
+    }
+    options.loopState.providerWaitState = options.error.providerState;
+    options.loopState.providerWaitLastError = options.error.message;
+}
+export function isTransientMiningProviderError(error) {
+    return error.providerState === "unavailable" || error.providerState === "rate-limited";
+}
+export function expireMiningSettleWindows(loopState, nowUnixMs) {
+    if (loopState.reconnectSettledUntilUnixMs !== null
+        && loopState.reconnectSettledUntilUnixMs <= nowUnixMs) {
+        loopState.reconnectSettledUntilUnixMs = null;
+    }
+    if (loopState.tipSettledUntilUnixMs !== null
+        && loopState.tipSettledUntilUnixMs <= nowUnixMs) {
+        loopState.tipSettledUntilUnixMs = null;
+    }
+}
+export function setMiningReconnectSettleWindow(loopState, nowUnixMs) {
+    loopState.reconnectSettledUntilUnixMs = nowUnixMs + MINING_NETWORK_SETTLE_WINDOW_MS;
+}
+export function setMiningTipSettleWindow(loopState, nowUnixMs) {
+    loopState.tipSettledUntilUnixMs = nowUnixMs + MINING_TIP_SETTLE_WINDOW_MS;
+}
+export function buildMiningSettleWindowStatusOverrides(loopState, nowUnixMs) {
+    expireMiningSettleWindows(loopState, nowUnixMs);
+    return {
+        reconnectSettledUntilUnixMs: loopState.reconnectSettledUntilUnixMs,
+        tipSettledUntilUnixMs: loopState.tipSettledUntilUnixMs,
+    };
+}
+export function buildMiningTipKey(bestBlockHash, targetBlockHeight) {
+    if (bestBlockHash === null || targetBlockHeight === null) {
+        return null;
+    }
+    return `${bestBlockHash}:${targetBlockHeight}`;
+}
+export function resetMiningUiForTip(loopState, _targetBlockHeight) {
+    const preservedTxid = loopState.ui.latestTxid;
+    const preservedFundingAddress = loopState.ui.fundingAddress;
+    loopState.ui = {
+        ...createEmptyMiningFollowVisualizerState(),
+        fundingAddress: preservedFundingAddress,
+        latestTxid: preservedTxid,
+    };
+    loopState.selectedCandidateTipKey = null;
+    loopState.selectedCandidate = null;
+    loopState.waitingNote = null;
+}
+function resolveProvisionalBroadcastTxidForCandidate(options) {
+    if (options.liveState === null || options.liveState === undefined) {
+        return null;
+    }
+    const liveState = normalizeMiningStateRecord(options.liveState);
+    if (liveState.currentTxid === null
+        || liveState.currentPublishState !== "in-mempool"
+        || liveState.livePublishInMempool !== true) {
+        return null;
+    }
+    if (liveState.currentDomain !== options.candidate.domainName
+        || liveState.currentDomainId !== options.candidate.domainId
+        || liveState.currentSentence !== options.candidate.sentence
+        || liveState.currentBlockTargetHeight !== options.candidate.targetBlockHeight
+        || liveState.currentReferencedBlockHashDisplay !== options.candidate.referencedBlockHashDisplay) {
+        return null;
+    }
+    return liveState.currentTxid;
+}
+export function setMiningUiCandidate(loopState, candidate, liveState) {
+    loopState.ui.latestSentence = candidate.sentence;
+    loopState.ui.provisionalRequiredWords = [...candidate.bip39Words];
+    loopState.ui.provisionalEntry = {
+        domainName: candidate.domainName,
+        sentence: candidate.sentence,
+    };
+    loopState.ui.provisionalBroadcastTxid = resolveProvisionalBroadcastTxidForCandidate({
+        candidate,
+        liveState,
+    });
+}
+export function getSelectedCandidateForTip(loopState, tipKey) {
+    if (tipKey === null || loopState.selectedCandidateTipKey !== tipKey) {
+        return null;
+    }
+    return loopState.selectedCandidate;
+}
+export function cacheSelectedCandidateForTip(loopState, tipKey, candidate, liveState) {
+    loopState.selectedCandidateTipKey = tipKey;
+    loopState.selectedCandidate = candidate;
+    setMiningUiCandidate(loopState, candidate, liveState);
+}
+export function clearSelectedCandidate(loopState) {
+    loopState.selectedCandidateTipKey = null;
+    loopState.selectedCandidate = null;
+}
+export function clearMiningUiTransientCandidate(loopState) {
+    loopState.ui.provisionalRequiredWords = [];
+    loopState.ui.provisionalEntry = {
+        domainName: null,
+        sentence: null,
+    };
+    loopState.ui.provisionalBroadcastTxid = null;
+    loopState.ui.latestSentence = null;
+}
+export function discardMiningLoopTransientWork(loopState, walletRootId) {
+    clearMiningGateCache(walletRootId);
+    clearSelectedCandidate(loopState);
+    clearMiningUiTransientCandidate(loopState);
+    loopState.waitingNote = null;
+    clearMiningProviderWait(loopState);
+}

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

@@ -0,0 +1,173 @@
+import type { WalletReadContext } from "../read/index.js";
+import type { FixedWalletInput, MutationSender, WalletMutationRpcClient } from "../tx/common.js";
+import type { WalletStateV1 } from "../types.js";
+import type { MiningRuntimeStatusV1 } from "./types.js";
+import type { MiningFollowVisualizerState, MiningRecentWinSummary, MiningSentenceBoardEntry } from "./visualizer.js";
+export 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>;
+};
+export 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;
+}
+export type ReadyMiningReadContext = WalletReadContext & {
+    localState: {
+        availability: "ready";
+        state: WalletStateV1;
+    };
+    snapshot: NonNullable<WalletReadContext["snapshot"]>;
+    model: NonNullable<WalletReadContext["model"]>;
+};
+export 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;
+}
+export interface MiningPublishRetryResult {
+    state: WalletStateV1;
+    txid: null;
+    decision: "publish-retry-pending";
+    note: string;
+    skipped?: false;
+    retryable: true;
+    candidate: MiningCandidate;
+}
+export interface MiningPublishSuccessResult {
+    state: WalletStateV1;
+    txid: string | null;
+    decision: string;
+    note?: null;
+    skipped?: false;
+    retryable?: false;
+    candidate: MiningCandidate;
+}
+export type MiningPublishOutcome = MiningPublishSuccessResult | MiningPublishSkipResult | MiningPublishRetryResult;
+export 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;
+}
+export type MiningCyclePhase = MiningRuntimeStatusV1["currentPhase"];
+export interface MiningCycleGateSnapshot {
+    higherRankedCompetitorDomainCount: number;
+    dedupedCompetitorDomainCount: number;
+    mempoolSequenceCacheStatus: MiningRuntimeStatusV1["mempoolSequenceCacheStatus"];
+    lastMempoolSequence: string | null;
+}
+export interface MiningCycleState {
+    phase: MiningCyclePhase;
+    targetBlockHeight: number | null;
+    tipKey: string | null;
+    selectedCandidate: MiningCandidate | null;
+    gateSnapshot: MiningCycleGateSnapshot;
+}
+export interface MiningCycleContext {
+    currentPhase: MiningCyclePhase;
+    targetBlockHeight: number | null;
+    tipKey: string | null;
+    selectedCandidate: MiningCandidate | null;
+}
+export interface MiningCycleEffects {
+    statusPhase?: MiningCyclePhase;
+    persistState?: WalletStateV1 | null;
+    followUiState?: MiningFollowVisualizerState | null;
+    recentWin?: MiningRecentWinSummary | null;
+}
+export interface MiningMutationPlan {
+    sender: MutationSender;
+    fixedInputs: FixedWalletInput[];
+    outputs: unknown[];
+    changeAddress: string;
+    changePosition: number;
+    expectedOpReturnScriptHex: string;
+    allowedFundingScriptPubKeyHex: string;
+    eligibleFundingOutpointKeys: Set<string>;
+    expectedConflictOutpoint: {
+        txid: string;
+        vout: number;
+    } | null;
+    feeRateSatVb: number;
+}
+export type MiningCooperativeYield = () => Promise<void>;

package/dist/wallet/mining/engine-types.js

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

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

@@ -0,0 +1,7 @@
+export declare function resolveBip39WordsFromIndices(indices: readonly number[] | null | undefined): readonly string[];
+export declare function rootDomain(name: string): boolean;
+export declare function getBlockRewardCogtoshi(height: number): bigint;
+export declare function deriveMiningWordIndices(referencedBlockhash: Uint8Array, miningDomainId: number): number[];
+export declare function numberToSats(value: number | string): bigint;
+export declare function compareLexicographically(left: Uint8Array, right: Uint8Array): number;
+export declare function tieBreakHash(blendSeed: Uint8Array, miningDomainId: number): Uint8Array;

package/dist/wallet/mining/engine-utils.js

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto";
+import { wordlist as englishWordlist } from "@scure/bip39/wordlists/english.js";
+export function resolveBip39WordsFromIndices(indices) {
+    if (indices === null || indices === undefined) {
+        return [];
+    }
+    const words = [];
+    for (const index of indices) {
+        if (!Number.isInteger(index) || index < 0 || index >= englishWordlist.length) {
+            continue;
+        }
+        words.push(englishWordlist[index]);
+    }
+    return words;
+}
+export function rootDomain(name) {
+    return !name.includes("-");
+}
+function uint32BigEndian(value) {
+    const buffer = Buffer.alloc(4);
+    buffer.writeUInt32BE(value >>> 0, 0);
+    return buffer;
+}
+export function getBlockRewardCogtoshi(height) {
+    const halvingEra = Math.floor(height / 210_000);
+    if (halvingEra >= 33) {
+        return 0n;
+    }
+    return 5000000000n >> BigInt(halvingEra);
+}
+export function deriveMiningWordIndices(referencedBlockhash, miningDomainId) {
+    const seed = createHash("sha256")
+        .update(Buffer.from(referencedBlockhash))
+        .update(uint32BigEndian(miningDomainId))
+        .digest();
+    const indices = [];
+    for (let index = 0; index < 5; index += 1) {
+        const chunkOffset = index * 4;
+        let wordIndex = seed.readUInt32BE(chunkOffset) % 2048;
+        while (indices.includes(wordIndex)) {
+            wordIndex = (wordIndex + 1) % 2048;
+        }
+        indices.push(wordIndex);
+    }
+    return indices;
+}
+export function numberToSats(value) {
+    const text = typeof value === "number" ? value.toFixed(8) : value;
+    const match = /^(-?)(\d+)(?:\.(\d{0,8}))?$/.exec(text.trim());
+    if (match == null) {
+        throw new Error(`mining_invalid_amount_${text}`);
+    }
+    const sign = match[1] === "-" ? -1n : 1n;
+    const whole = BigInt(match[2] ?? "0");
+    const fraction = BigInt((match[3] ?? "").padEnd(8, "0"));
+    return sign * ((whole * 100000000n) + fraction);
+}
+export function compareLexicographically(left, right) {
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        if (left[index] !== right[index]) {
+            return left[index] < right[index] ? -1 : 1;
+        }
+    }
+    if (left.length === right.length) {
+        return 0;
+    }
+    return left.length < right.length ? -1 : 1;
+}
+export function tieBreakHash(blendSeed, miningDomainId) {
+    return createHash("sha256")
+        .update(Buffer.from(blendSeed))
+        .update(uint32BigEndian(miningDomainId))
+        .digest();
+}

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

@@ -0,0 +1,2 @@
+import type { MiningEventRecord } from "./types.js";
+export declare function createMiningEventRecord(kind: string, message: string, options?: Partial<MiningEventRecord>): MiningEventRecord;

package/dist/wallet/mining/events.js

@@ -0,0 +1,19 @@
+export function createMiningEventRecord(kind, message, options = {}) {
+    return {
+        schemaVersion: 1,
+        timestampUnixMs: options.timestampUnixMs ?? Date.now(),
+        level: options.level ?? "info",
+        kind,
+        message,
+        targetBlockHeight: options.targetBlockHeight ?? null,
+        referencedBlockHashDisplay: options.referencedBlockHashDisplay ?? null,
+        domainId: options.domainId ?? null,
+        domainName: options.domainName ?? null,
+        txid: options.txid ?? null,
+        feeRateSatVb: options.feeRateSatVb ?? null,
+        feeSats: options.feeSats ?? null,
+        score: options.score ?? null,
+        reason: options.reason ?? null,
+        runId: options.runId ?? null,
+    };
+}

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

@@ -0,0 +1,71 @@
+import { createRpcClient } from "../../bitcoind/node.js";
+import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopManagedBitcoindService } from "../../bitcoind/service.js";
+import 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 MiningRuntimeStatusOverrides } from "./projection.js";
+import { type MiningRuntimeLoopState } from "./engine-state.js";
+import type { MiningRpcClient } from "./engine-types.js";
+import type { MiningRuntimeStatusV1 } from "./types.js";
+import type { MiningFollowVisualizer, MiningFollowVisualizerState } from "./visualizer.js";
+export declare function refreshAndSaveMiningRuntimeStatus(options: {
+    paths: WalletRuntimePaths;
+    provider: WalletSecretProvider;
+    readContext: WalletReadContext;
+    overrides?: MiningRuntimeStatusOverrides;
+    visualizer?: MiningFollowVisualizer;
+    visualizerState?: MiningFollowVisualizerState;
+}): Promise<MiningRuntimeStatusV1>;
+export declare function resetMiningBitcoindRecoveryState(loopState: MiningRuntimeLoopState, value?: {
+    serviceInstanceId?: string | null;
+    processId?: number | null;
+} | {
+    pid?: number | null;
+} | null): boolean;
+export declare function isRecoverableMiningBitcoindError(error: unknown): boolean;
+export declare function handleRecoverableMiningBitcoindFailure(options: {
+    error: unknown;
+    dataDir: string;
+    provider: WalletSecretProvider;
+    paths: WalletRuntimePaths;
+    runMode: "foreground" | "background";
+    readContext: WalletReadContext;
+    loopState: MiningRuntimeLoopState;
+    attachService: typeof attachOrStartManagedBitcoindService;
+    probeService: typeof probeManagedBitcoindService;
+    stopService: typeof stopManagedBitcoindService;
+    nowUnixMs: number;
+    visualizer?: MiningFollowVisualizer;
+}): Promise<void>;
+export declare function handleDetectedMiningRuntimeResume(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: MiningRuntimeLoopState;
+}): Promise<void>;
+export declare function saveStopSnapshot(options: {
+    dataDir: string;
+    databasePath: string;
+    provider: WalletSecretProvider;
+    paths: WalletRuntimePaths;
+    runMode: "foreground" | "background";
+    backgroundWorkerPid: number | null;
+    backgroundWorkerRunId: string | null;
+    note: string | null;
+    openReadContext?: typeof openWalletReadContext;
+    attachService?: typeof attachOrStartManagedBitcoindService;
+    rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => MiningRpcClient;
+}): Promise<void>;
+export declare function attemptSaveMempool(options: {
+    rpc: MiningRpcClient;
+    paths: WalletRuntimePaths;
+    runId: string | null;
+}): Promise<void>;