@cogcoin/client 0.5.0

package/dist/wallet/mining/runtime-artifacts.d.ts

@@ -0,0 +1,17 @@
+import type { MiningEventRecord, MiningRuntimeStatusV1 } from "./types.js";
+export declare function resolveRotatedMiningEventsPath(eventsPath: string): string;
+export declare function loadMiningRuntimeStatus(statusPath: string): Promise<MiningRuntimeStatusV1 | null>;
+export declare function saveMiningRuntimeStatus(statusPath: string, snapshot: MiningRuntimeStatusV1): Promise<void>;
+export declare function appendMiningEvent(eventsPath: string, event: MiningEventRecord): Promise<void>;
+export declare function readMiningEvents(options: {
+    eventsPath: string;
+    limit?: number | null;
+    all?: boolean;
+}): Promise<MiningEventRecord[]>;
+export declare function getLastMiningEventTimestamp(eventsPath: string): Promise<number | null>;
+export declare function followMiningEvents(options: {
+    eventsPath: string;
+    intervalMs?: number;
+    signal?: AbortSignal;
+    onEvent: (event: MiningEventRecord) => void;
+}): Promise<void>;

package/dist/wallet/mining/runtime-artifacts.js

@@ -0,0 +1,166 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { writeRuntimeStatusFile } from "../fs/status-file.js";
+import { normalizeMiningFamilyStatus, normalizeMiningPublishState } from "./state.js";
+const MAX_EVENT_LOG_BYTES = 10 * 1024 * 1024;
+const MAX_EVENT_LOG_ROTATIONS = 4;
+export function resolveRotatedMiningEventsPath(eventsPath) {
+    return `${eventsPath}.1`;
+}
+function resolveIndexedRotatedMiningEventsPath(eventsPath, index) {
+    return `${eventsPath}.${index}`;
+}
+export async function loadMiningRuntimeStatus(statusPath) {
+    try {
+        const raw = await readFile(statusPath, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            ...parsed,
+            miningState: normalizeMiningFamilyStatus(parsed.miningState),
+            currentPublishState: normalizeMiningPublishState(parsed.currentPublishState),
+            indexerReorgDepth: parsed.indexerReorgDepth ?? null,
+            sameDomainCompetitorSuppressed: parsed.sameDomainCompetitorSuppressed ?? null,
+            dedupedCompetitorDomainCount: parsed.dedupedCompetitorDomainCount ?? null,
+            competitivenessGateIndeterminate: parsed.competitivenessGateIndeterminate ?? null,
+            mempoolSequenceCacheStatus: parsed.mempoolSequenceCacheStatus ?? null,
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function saveMiningRuntimeStatus(statusPath, snapshot) {
+    await writeRuntimeStatusFile(statusPath, snapshot);
+}
+async function rotateMiningEventsIfNeeded(eventsPath, nextEntryBytes) {
+    try {
+        const current = await stat(eventsPath);
+        if ((current.size + nextEntryBytes) <= MAX_EVENT_LOG_BYTES) {
+            return;
+        }
+        for (let index = MAX_EVENT_LOG_ROTATIONS; index >= 1; index -= 1) {
+            const sourcePath = index === 1
+                ? eventsPath
+                : resolveIndexedRotatedMiningEventsPath(eventsPath, index - 1);
+            const destinationPath = resolveIndexedRotatedMiningEventsPath(eventsPath, index);
+            if (index === MAX_EVENT_LOG_ROTATIONS) {
+                await rm(destinationPath, { force: true }).catch(() => undefined);
+            }
+            try {
+                await rename(sourcePath, destinationPath);
+            }
+            catch (error) {
+                if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return;
+        }
+        throw error;
+    }
+}
+export async function appendMiningEvent(eventsPath, event) {
+    const serialized = `${JSON.stringify(event)}\n`;
+    await mkdir(dirname(eventsPath), { recursive: true });
+    await rotateMiningEventsIfNeeded(eventsPath, Buffer.byteLength(serialized));
+    const handle = await open(eventsPath, "a", 0o600);
+    try {
+        await handle.writeFile(serialized, { encoding: "utf8" });
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function parseMiningEventLines(raw) {
+    const hasTrailingNewline = raw.endsWith("\n");
+    const lines = raw.split("\n");
+    const completeLines = hasTrailingNewline ? lines.slice(0, -1) : lines.slice(0, -1);
+    const events = [];
+    for (const line of completeLines) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        try {
+            events.push(JSON.parse(trimmed));
+        }
+        catch {
+            continue;
+        }
+    }
+    return events;
+}
+async function readEventFile(path) {
+    try {
+        const raw = await readFile(path, "utf8");
+        return parseMiningEventLines(raw);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+}
+export async function readMiningEvents(options) {
+    const paths = [];
+    for (let index = MAX_EVENT_LOG_ROTATIONS; index >= 1; index -= 1) {
+        paths.push(resolveIndexedRotatedMiningEventsPath(options.eventsPath, index));
+    }
+    paths.push(options.eventsPath);
+    const chunks = await Promise.all(paths.map((path) => readEventFile(path)));
+    const events = chunks.flat();
+    if (options.all) {
+        return events;
+    }
+    const limit = options.limit ?? 50;
+    return events.slice(Math.max(0, events.length - limit));
+}
+export async function getLastMiningEventTimestamp(eventsPath) {
+    const events = await readMiningEvents({
+        eventsPath,
+        limit: 1,
+    });
+    return events.length === 0 ? null : events[0].timestampUnixMs;
+}
+export async function followMiningEvents(options) {
+    const seen = new Set();
+    const recordEvents = async () => {
+        const events = await readMiningEvents({
+            eventsPath: options.eventsPath,
+            all: true,
+        });
+        for (const event of events) {
+            const digest = createHash("sha256").update(JSON.stringify(event)).digest("hex");
+            if (seen.has(digest)) {
+                continue;
+            }
+            seen.add(digest);
+            options.onEvent(event);
+        }
+    };
+    await recordEvents();
+    while (!options.signal?.aborted) {
+        await new Promise((resolve) => {
+            const timeout = setTimeout(resolve, options.intervalMs ?? 250);
+            options.signal?.addEventListener("abort", () => {
+                clearTimeout(timeout);
+                resolve(undefined);
+            }, { once: true });
+        });
+        if (options.signal?.aborted) {
+            return;
+        }
+        await recordEvents();
+    }
+}

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

@@ -0,0 +1,23 @@
+import type { GenerateSentencesHookCandidateV1, GenerateSentencesHookRequestV1 } from "./hook-protocol.js";
+import type { WalletRuntimePaths } from "../runtime.js";
+import type { HookClientStateRecord } from "../types.js";
+import type { WalletSecretProvider } from "../state/provider.js";
+export type MiningSentenceGenerationRequest = GenerateSentencesHookRequestV1;
+export type MiningSentenceGenerationCandidate = GenerateSentencesHookCandidateV1;
+export interface MiningSentenceSourceOptions {
+    paths: WalletRuntimePaths;
+    provider: WalletSecretProvider;
+    hookState: HookClientStateRecord | null;
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+}
+declare class MiningProviderRequestError extends Error {
+    readonly providerState: "unavailable" | "rate-limited" | "auth-error";
+    constructor(providerState: "unavailable" | "rate-limited" | "auth-error", message: string);
+}
+export declare function generateMiningSentences(request: MiningSentenceGenerationRequest, options: MiningSentenceSourceOptions): Promise<{
+    hookMode: "builtin" | "custom";
+    candidates: GenerateSentencesHookCandidateV1[];
+    providerState: "ready" | "n/a";
+}>;
+export { MiningProviderRequestError, };

package/dist/wallet/mining/sentences.js

@@ -0,0 +1,281 @@
+import { loadClientConfig } from "./config.js";
+import { inspectMiningHookState, runGenerateSentencesHookRequest } from "./hooks.js";
+import { MINING_BUILTIN_TIMEOUT_MS, } from "./constants.js";
+import { normalizeHookResponse, parseStrictJsonValue, stripMarkdownCodeFence, } from "./hook-protocol.js";
+class MiningProviderRequestError extends Error {
+    providerState;
+    constructor(providerState, message) {
+        super(message);
+        this.name = "MiningProviderRequestError";
+        this.providerState = providerState;
+    }
+}
+function buildSystemPrompt(extraPrompt) {
+    const lines = [
+        "You are helping generate candidate Cogcoin mining sentences.",
+        "Return only JSON matching the requested response schema.",
+        "Every sentence must be a single natural-language sentence.",
+        "Do not add commentary, markdown, or code fences.",
+        "Do not invent domain IDs or request IDs.",
+    ];
+    if (extraPrompt !== null && extraPrompt.trim().length > 0) {
+        lines.push(`Extra instruction: ${extraPrompt.trim()}`);
+    }
+    return lines.join("\n");
+}
+function buildUserPrompt(request) {
+    return [
+        "Return a JSON object with:",
+        `- schemaVersion: 1`,
+        `- requestId: ${request.requestId}`,
+        "- candidates: [{ domainId, sentence }]",
+        "Use only domain IDs from rootDomains.",
+        `Keep each sentence within ${request.limits.maxCandidateSentenceUtf8Bytes} UTF-8 bytes after trimming.`,
+        "Mining request JSON:",
+        JSON.stringify(request, null, 2),
+    ].join("\n");
+}
+function annotateProviderCandidates(options) {
+    return options.candidates.map((candidate) => ({
+        ...candidate,
+        attribution: candidate.attribution ?? {
+            provider: options.provider,
+            model: options.model,
+            promptLabel: "built-in",
+        },
+    }));
+}
+function parseProviderJsonResponse(options) {
+    const response = parseStrictJsonValue(stripMarkdownCodeFence(options.raw), `${options.providerLabel} returned invalid JSON.`);
+    try {
+        return normalizeHookResponse({
+            request: options.request,
+            response,
+        }).candidates;
+    }
+    catch (error) {
+        throw new Error(error instanceof Error
+            ? error.message.replace(/^Custom mining hook /, `${options.providerLabel} `)
+            : `${options.providerLabel} returned an invalid response.`);
+    }
+}
+function createProviderSignal(signal, timeoutMs) {
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    return signal === undefined ? timeoutSignal : AbortSignal.any([signal, timeoutSignal]);
+}
+async function requestBuiltInSentences(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const providerSignal = createProviderSignal(options.signal, Math.min(MINING_BUILTIN_TIMEOUT_MS, options.request.limits.timeoutMs));
+    try {
+        if (options.provider === "openai") {
+            const model = options.modelOverride ?? "gpt-5.4-mini";
+            const response = await fetchImpl("https://api.openai.com/v1/responses", {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${options.apiKey}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({
+                    model,
+                    input: [
+                        {
+                            role: "system",
+                            content: buildSystemPrompt(options.extraPrompt),
+                        },
+                        {
+                            role: "user",
+                            content: buildUserPrompt(options.request),
+                        },
+                    ],
+                }),
+                signal: providerSignal,
+            });
+            if (response.status === 401 || response.status === 403) {
+                throw new MiningProviderRequestError("auth-error", "The built-in OpenAI mining provider rejected the configured API key.");
+            }
+            if (response.status === 429) {
+                throw new MiningProviderRequestError("rate-limited", "The built-in OpenAI mining provider is rate limited.");
+            }
+            if (!response.ok) {
+                throw new MiningProviderRequestError("unavailable", `The built-in OpenAI mining provider returned HTTP ${response.status}.`);
+            }
+            return annotateProviderCandidates({
+                candidates: parseProviderJsonResponse({
+                    raw: extractOpenAiText(await response.json()),
+                    request: options.request,
+                    providerLabel: "The built-in OpenAI mining provider",
+                }),
+                provider: options.provider,
+                model,
+            });
+        }
+        const model = options.modelOverride ?? "claude-sonnet-4-20250514";
+        const response = await fetchImpl("https://api.anthropic.com/v1/messages", {
+            method: "POST",
+            headers: {
+                "x-api-key": options.apiKey,
+                "anthropic-version": "2023-06-01",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model,
+                max_tokens: 1_200,
+                system: buildSystemPrompt(options.extraPrompt),
+                messages: [
+                    {
+                        role: "user",
+                        content: buildUserPrompt(options.request),
+                    },
+                ],
+            }),
+            signal: providerSignal,
+        });
+        if (response.status === 401 || response.status === 403) {
+            throw new MiningProviderRequestError("auth-error", "The built-in Anthropic mining provider rejected the configured API key.");
+        }
+        if (response.status === 429) {
+            throw new MiningProviderRequestError("rate-limited", "The built-in Anthropic mining provider is rate limited.");
+        }
+        if (!response.ok) {
+            throw new MiningProviderRequestError("unavailable", `The built-in Anthropic mining provider returned HTTP ${response.status}.`);
+        }
+        return annotateProviderCandidates({
+            candidates: parseProviderJsonResponse({
+                raw: extractAnthropicText(await response.json()),
+                request: options.request,
+                providerLabel: "The built-in Anthropic mining provider",
+            }),
+            provider: options.provider,
+            model,
+        });
+    }
+    catch (error) {
+        if (error instanceof MiningProviderRequestError) {
+            throw error;
+        }
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new MiningProviderRequestError("unavailable", "Mining sentence generation was aborted.");
+        }
+        throw new MiningProviderRequestError("unavailable", error instanceof Error ? error.message : String(error));
+    }
+}
+function extractOpenAiText(payload) {
+    if (payload !== null && typeof payload === "object") {
+        const outputText = payload.output_text;
+        if (typeof outputText === "string" && outputText.trim().length > 0) {
+            return outputText;
+        }
+        const output = payload.output;
+        if (Array.isArray(output)) {
+            const collected = [];
+            for (const item of output) {
+                if (item === null || typeof item !== "object") {
+                    continue;
+                }
+                const content = item.content;
+                if (!Array.isArray(content)) {
+                    continue;
+                }
+                for (const part of content) {
+                    if (part !== null && typeof part === "object") {
+                        const text = part.text;
+                        if (typeof text === "string" && text.trim().length > 0) {
+                            collected.push(text);
+                        }
+                    }
+                }
+            }
+            if (collected.length > 0) {
+                return collected.join("\n");
+            }
+        }
+    }
+    throw new Error("The built-in OpenAI mining provider returned an empty response.");
+}
+function extractAnthropicText(payload) {
+    if (payload !== null && typeof payload === "object") {
+        const content = payload.content;
+        if (Array.isArray(content)) {
+            const parts = content
+                .flatMap((entry) => {
+                if (entry !== null && typeof entry === "object") {
+                    const text = entry.text;
+                    return typeof text === "string" && text.trim().length > 0 ? [text] : [];
+                }
+                return [];
+            });
+            if (parts.length > 0) {
+                return parts.join("\n");
+            }
+        }
+    }
+    throw new Error("The built-in Anthropic mining provider returned an empty response.");
+}
+async function requestCustomHookSentences(options) {
+    const inspection = await inspectMiningHookState({
+        hookRootPath: options.paths.hooksMiningDir,
+        entrypointPath: options.paths.hooksMiningEntrypointPath,
+        packagePath: options.paths.hooksMiningPackageJsonPath,
+        localState: options.hookState,
+        verify: false,
+        nowUnixMs: Date.now(),
+    });
+    if (inspection.mode !== "custom") {
+        throw new Error("Custom mining hooks are not enabled.");
+    }
+    if (inspection.cooldownActive) {
+        throw new Error("Custom mining hook is cooling down after repeated failures. Wait for the cooldown to expire or rerun `cogcoin hooks enable mining`.");
+    }
+    if (inspection.operatorValidationState === "failed"
+        || inspection.operatorValidationState === "stale"
+        || inspection.operatorValidationState === "never") {
+        throw new Error("Custom mining hook validation is stale or failed. Rerun `cogcoin hooks enable mining`.");
+    }
+    if (inspection.trustStatus !== "trusted") {
+        throw new Error(inspection.trustMessage ?? "Custom mining hook trust checks failed.");
+    }
+    return runGenerateSentencesHookRequest({
+        hookRootPath: options.paths.hooksMiningDir,
+        entrypointPath: options.paths.hooksMiningEntrypointPath,
+        request: options.request,
+        signal: options.signal,
+        timeoutMs: options.request.limits.timeoutMs,
+    }).then((result) => result.candidates);
+}
+export async function generateMiningSentences(request, options) {
+    const hookMode = options.hookState?.mode === "custom" ? "custom" : "builtin";
+    if (hookMode === "custom") {
+        return {
+            hookMode,
+            candidates: await requestCustomHookSentences({
+                paths: options.paths,
+                hookState: options.hookState,
+                request,
+                signal: options.signal,
+            }),
+            providerState: "n/a",
+        };
+    }
+    const config = await loadClientConfig({
+        path: options.paths.clientConfigPath,
+        provider: options.provider,
+    });
+    const builtIn = config?.mining.builtIn ?? null;
+    if (builtIn === null) {
+        throw new MiningProviderRequestError("unavailable", "Mining is not configured. Run `cogcoin mine setup`.");
+    }
+    return {
+        hookMode,
+        candidates: await requestBuiltInSentences({
+            provider: builtIn.provider,
+            apiKey: builtIn.apiKey,
+            modelOverride: builtIn.modelOverride,
+            extraPrompt: builtIn.extraPrompt ?? request.extraPrompt,
+            request,
+            fetchImpl: options.fetchImpl,
+            signal: options.signal,
+        }),
+        providerState: "ready",
+    };
+}
+export { MiningProviderRequestError, };

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

@@ -0,0 +1,9 @@
+import type { MiningStateRecord } from "../types.js";
+export type MiningFamilyStatus = MiningStateRecord["state"];
+export type MiningPublishState = MiningStateRecord["currentPublishState"];
+export declare function normalizeMiningFamilyStatus(raw: string | null | undefined): MiningFamilyStatus;
+export declare function normalizeMiningPublishState(raw: string | null | undefined): MiningPublishState;
+export declare function normalizeMiningStateRecord(state: MiningStateRecord): MiningStateRecord;
+export declare function clearMiningFamilyState(state: MiningStateRecord): MiningStateRecord;
+export declare function miningFamilyMayStillExist(state: MiningStateRecord): boolean;
+export declare function miningFamilyIsInMempool(state: MiningStateRecord): boolean;

package/dist/wallet/mining/state.js

@@ -0,0 +1,75 @@
+export function normalizeMiningFamilyStatus(raw) {
+    switch (raw) {
+        case "live":
+        case "paused":
+        case "paused-stale":
+        case "repair-required":
+            return raw;
+        case "waiting-bitcoin-network":
+        case "waiting-indexer":
+        case "waiting-provider":
+        case "resuming":
+            return "paused";
+        case "idle":
+        default:
+            return "idle";
+    }
+}
+export function normalizeMiningPublishState(raw) {
+    switch (raw) {
+        case "broadcasting":
+        case "broadcast-unknown":
+        case "in-mempool":
+            return raw;
+        case "live":
+            return "in-mempool";
+        case "draft":
+        case "idle":
+        case "none":
+        default:
+            return "none";
+    }
+}
+export function normalizeMiningStateRecord(state) {
+    return {
+        ...state,
+        state: normalizeMiningFamilyStatus(state.state),
+        currentPublishState: normalizeMiningPublishState(state.currentPublishState),
+    };
+}
+export function clearMiningFamilyState(state) {
+    return {
+        ...normalizeMiningStateRecord(state),
+        state: "idle",
+        pauseReason: null,
+        currentPublishState: "none",
+        currentDomain: null,
+        currentDomainId: null,
+        currentDomainIndex: null,
+        currentSenderScriptPubKeyHex: null,
+        currentTxid: null,
+        currentWtxid: null,
+        currentFeeRateSatVb: null,
+        currentAbsoluteFeeSats: null,
+        currentScore: null,
+        currentSentence: null,
+        currentEncodedSentenceBytesHex: null,
+        currentBip39WordIndices: null,
+        currentBlendSeedHex: null,
+        currentBlockTargetHeight: null,
+        currentReferencedBlockHashDisplay: null,
+        currentIntentFingerprintHex: null,
+        liveMiningFamilyInMempool: false,
+        currentPublishDecision: null,
+        replacementCount: 0,
+        sharedMiningConflictOutpoint: null,
+    };
+}
+export function miningFamilyMayStillExist(state) {
+    const normalized = normalizeMiningStateRecord(state);
+    return normalized.currentTxid !== null
+        && normalized.currentPublishState !== "none";
+}
+export function miningFamilyIsInMempool(state) {
+    return normalizeMiningStateRecord(state).currentPublishState === "in-mempool";
+}