@cogcoin/client 1.1.9 → 1.1.11

package/dist/bitcoind/indexer-daemon/process.js

@@ -0,0 +1,140 @@
+import { mkdir, rm } from "node:fs/promises";
+import { acquireFileLock } from "../../wallet/fs/lock.js";
+import { writeRuntimeStatusFile } from "../../wallet/fs/status-file.js";
+import { readJsonFileIfPresent } from "../managed-runtime/status.js";
+import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "../service-paths.js";
+import { probeIndexerDaemonAtSocket } from "./client.js";
+export const DEFAULT_INDEXER_DAEMON_STARTUP_TIMEOUT_MS = 30_000;
+export const DEFAULT_INDEXER_DAEMON_SHUTDOWN_TIMEOUT_MS = 5_000;
+const FORCE_KILL_TIMEOUT_MS = 5_000;
+export function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export async function isIndexerDaemonProcessAlive(pid) {
+    if (pid === null) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+            return false;
+        }
+        return true;
+    }
+}
+export async function waitForIndexerDaemonProcessExit(pid, timeoutMs, errorCode) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!await isIndexerDaemonProcessAlive(pid)) {
+            return;
+        }
+        await sleep(50);
+    }
+    throw new Error(errorCode);
+}
+export async function clearIndexerDaemonRuntimeArtifacts(paths) {
+    await rm(paths.indexerDaemonStatusPath, { force: true }).catch(() => undefined);
+    await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
+}
+export function ignoreIndexerDaemonProcessNotFound(error) {
+    if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+        throw error;
+    }
+}
+export async function stopIndexerDaemonServiceWithLockHeld(options) {
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const paths = options.paths ?? resolveManagedServicePaths(options.dataDir, walletRootId);
+    const status = await readJsonFileIfPresent(paths.indexerDaemonStatusPath);
+    const processId = options.processId ?? status?.processId ?? null;
+    if (status === null || processId === null || !await isIndexerDaemonProcessAlive(processId)) {
+        await clearIndexerDaemonRuntimeArtifacts(paths);
+        return {
+            status: "not-running",
+            walletRootId,
+        };
+    }
+    try {
+        process.kill(processId, "SIGTERM");
+    }
+    catch (error) {
+        ignoreIndexerDaemonProcessNotFound(error);
+    }
+    try {
+        await waitForIndexerDaemonProcessExit(processId, options.shutdownTimeoutMs ?? DEFAULT_INDEXER_DAEMON_SHUTDOWN_TIMEOUT_MS, "indexer_daemon_stop_timeout");
+    }
+    catch (error) {
+        if (!(error instanceof Error) || error.message !== "indexer_daemon_stop_timeout") {
+            throw error;
+        }
+        try {
+            process.kill(processId, "SIGKILL");
+        }
+        catch (killError) {
+            ignoreIndexerDaemonProcessNotFound(killError);
+        }
+        await waitForIndexerDaemonProcessExit(processId, FORCE_KILL_TIMEOUT_MS, "indexer_daemon_stop_timeout");
+    }
+    await clearIndexerDaemonRuntimeArtifacts(paths);
+    return {
+        status: "stopped",
+        walletRootId,
+    };
+}
+export async function waitForIndexerDaemon(dataDir, walletRootId, timeoutMs) {
+    const paths = resolveManagedServicePaths(dataDir, walletRootId);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const probe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
+        if (probe.compatibility === "compatible" && probe.client !== null) {
+            await probe.client.close().catch(() => undefined);
+            return;
+        }
+        if (probe.compatibility !== "unreachable") {
+            throw new Error(probe.error ?? "indexer_daemon_protocol_error");
+        }
+        await sleep(250);
+    }
+    throw new Error("indexer_daemon_start_timeout");
+}
+export async function stopIndexerDaemonService(options) {
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
+    const lock = await acquireFileLock(paths.indexerDaemonLockPath, {
+        purpose: "indexer-daemon-stop",
+        walletRootId,
+        dataDir: options.dataDir,
+    });
+    try {
+        return await stopIndexerDaemonServiceWithLockHeld({
+            ...options,
+            walletRootId,
+            paths,
+        });
+    }
+    finally {
+        await lock.release();
+    }
+}
+export async function shutdownIndexerDaemonForTesting(options) {
+    await stopIndexerDaemonService(options).catch(async () => {
+        const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+        const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
+        await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
+    });
+}
+export async function readIndexerDaemonStatusForTesting(options) {
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
+    return readJsonFileIfPresent(paths.indexerDaemonStatusPath);
+}
+export async function writeIndexerDaemonStatusForTesting(options, status) {
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
+    await mkdir(paths.indexerServiceRoot, { recursive: true });
+    await writeRuntimeStatusFile(paths.indexerDaemonStatusPath, status);
+}

package/dist/bitcoind/indexer-daemon/runtime.d.ts

@@ -0,0 +1,23 @@
+import type { GenesisParameters } from "@cogcoin/indexer/types";
+import { resolveManagedServicePaths } from "../service-paths.js";
+import type { ManagedIndexerDaemonStatus } from "../types.js";
+export interface ManagedIndexerDaemonRuntime {
+    start(): Promise<void>;
+    shutdown(): Promise<void>;
+    getStatus(): ManagedIndexerDaemonStatus;
+}
+export declare function createIndexerDaemonRuntime(options: {
+    dataDir: string;
+    databasePath: string;
+    walletRootId?: string;
+    paths?: ReturnType<typeof resolveManagedServicePaths>;
+    binaryVersion: string;
+    genesisParameters: GenesisParameters;
+    daemonInstanceId?: string;
+    startedAtUnixMs?: number;
+    snapshotTtlMs?: number;
+    heartbeatIntervalMs?: number;
+    backgroundFollowResumeTimeoutMs?: number;
+    backgroundFollowResumeTimeoutError?: string;
+    forceResumeErrorEnv?: string;
+}): ManagedIndexerDaemonRuntime;

package/dist/bitcoind/indexer-daemon/runtime.js

@@ -0,0 +1,204 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, rm } from "node:fs/promises";
+import { DEFAULT_SNAPSHOT_METADATA } from "../bootstrap.js";
+import { createBootstrapProgress } from "../progress/formatting.js";
+import { resolveManagedServicePaths } from "../service-paths.js";
+import { UNINITIALIZED_WALLET_ROOT_ID } from "../service-paths.js";
+import { pauseBackgroundFollow, recordBackgroundFollowFailure, resumeBackgroundFollow, withTimeout, } from "./background-follow.js";
+import { createIndexerDaemonServer } from "./server.js";
+import { buildIndexerDaemonStatus, deriveIndexerDaemonLeaseState, observeIndexerAppliedTip, readCoreTipStatus, refreshIndexerDaemonStatus, writeIndexerDaemonStatus, } from "./status.js";
+import { closeSnapshotLease, createSnapshotHandle, loadSnapshotMaterial, pruneExpiredSnapshotLeases, readSnapshotLease, storeSnapshotLease, } from "./snapshot-leases.js";
+const SNAPSHOT_TTL_MS = 30_000;
+const HEARTBEAT_INTERVAL_MS = 1_000;
+const FORCE_RESUME_ERROR_ENV = "COGCOIN_TEST_INDEXER_DAEMON_FORCE_RESUME_ERROR";
+const BACKGROUND_FOLLOW_RESUME_TIMEOUT_MS = 30_000;
+const BACKGROUND_FOLLOW_RESUME_TIMEOUT_ERROR = "indexer_daemon_background_follow_resume_timeout";
+export function createIndexerDaemonRuntime(options) {
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const paths = options.paths ?? resolveManagedServicePaths(options.dataDir, walletRootId);
+    const snapshotTtlMs = options.snapshotTtlMs ?? SNAPSHOT_TTL_MS;
+    const heartbeatIntervalMs = options.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
+    const backgroundFollowResumeTimeoutMs = options.backgroundFollowResumeTimeoutMs ?? BACKGROUND_FOLLOW_RESUME_TIMEOUT_MS;
+    const backgroundFollowResumeTimeoutError = options.backgroundFollowResumeTimeoutError
+        ?? BACKGROUND_FOLLOW_RESUME_TIMEOUT_ERROR;
+    const forceResumeErrorEnv = options.forceResumeErrorEnv ?? FORCE_RESUME_ERROR_ENV;
+    const startedAtUnixMs = options.startedAtUnixMs ?? Date.now();
+    const state = {
+        daemonInstanceId: options.daemonInstanceId ?? randomUUID(),
+        binaryVersion: options.binaryVersion,
+        startedAtUnixMs,
+        walletRootId,
+        snapshots: new Map(),
+        state: "starting",
+        heartbeatAtUnixMs: startedAtUnixMs,
+        updatedAtUnixMs: startedAtUnixMs,
+        rpcReachable: false,
+        coreBestHeight: null,
+        coreBestHash: null,
+        appliedTipHeight: null,
+        appliedTipHash: null,
+        snapshotSeqCounter: 0,
+        snapshotSeq: null,
+        lastSnapshotKey: undefined,
+        lastAppliedAtUnixMs: null,
+        lastError: null,
+        hasSuccessfulCoreTipRefresh: false,
+        backgroundStore: null,
+        backgroundClient: null,
+        backgroundResumePromise: null,
+        backgroundFollowError: null,
+        backgroundFollowActive: false,
+        bootstrapPhase: "paused",
+        bootstrapProgress: createBootstrapProgress("paused", DEFAULT_SNAPSHOT_METADATA),
+        cogcoinSyncHeight: null,
+        cogcoinSyncTargetHeight: null,
+    };
+    let heartbeat = null;
+    let server = null;
+    let shutdownPromise = null;
+    const writeStatus = async () => writeIndexerDaemonStatus(paths, state);
+    const openSnapshot = async () => {
+        const [snapshotMaterial, coreStatus] = await Promise.all([
+            loadSnapshotMaterial(options.databasePath, snapshotTtlMs),
+            readCoreTipStatus(paths),
+        ]);
+        const now = Date.now();
+        state.heartbeatAtUnixMs = now;
+        state.updatedAtUnixMs = now;
+        state.rpcReachable = coreStatus.rpcReachable;
+        state.coreBestHeight = coreStatus.coreBestHeight;
+        state.coreBestHash = coreStatus.coreBestHash;
+        observeIndexerAppliedTip(state, snapshotMaterial.tip, now);
+        const leaseState = deriveIndexerDaemonLeaseState({
+            coreStatus,
+            appliedTip: snapshotMaterial.tip,
+            hasSuccessfulCoreTipRefresh: state.hasSuccessfulCoreTipRefresh,
+        });
+        state.hasSuccessfulCoreTipRefresh = leaseState.hasSuccessfulCoreTipRefresh;
+        state.state = leaseState.state;
+        state.lastError = leaseState.lastError;
+        const snapshot = storeSnapshotLease({
+            state,
+            material: snapshotMaterial,
+            nowUnixMs: now,
+        });
+        const status = await writeStatus();
+        return createSnapshotHandle({
+            snapshot,
+            status,
+            binaryVersion: state.binaryVersion,
+        });
+    };
+    const readSnapshot = async (token) => {
+        const result = readSnapshotLease({
+            state,
+            token,
+        });
+        if (result.changed) {
+            await writeStatus();
+        }
+        if (result.error !== null || result.payload === null) {
+            throw new Error(result.error ?? "indexer_daemon_snapshot_invalid");
+        }
+        return result.payload;
+    };
+    const closeSnapshot = async (token) => {
+        if (closeSnapshotLease(state, token)) {
+            await writeStatus();
+        }
+    };
+    const resumeFollow = async () => {
+        try {
+            await withTimeout(resumeBackgroundFollow({
+                dataDir: options.dataDir,
+                databasePath: options.databasePath,
+                walletRootId,
+                paths,
+                state,
+                genesisParameters: options.genesisParameters,
+                forceResumeErrorEnv,
+                writeStatus,
+            }), backgroundFollowResumeTimeoutMs, backgroundFollowResumeTimeoutError);
+        }
+        catch (error) {
+            if (error instanceof Error
+                && error.message === backgroundFollowResumeTimeoutError) {
+                await recordBackgroundFollowFailure({
+                    state,
+                    message: error.message,
+                    writeStatus,
+                }).catch(() => undefined);
+            }
+            throw error;
+        }
+    };
+    const tick = () => {
+        void refreshIndexerDaemonStatus({
+            databasePath: options.databasePath,
+            paths,
+            state,
+        }).catch(() => undefined);
+        const now = Date.now();
+        if (pruneExpiredSnapshotLeases(state, now)) {
+            void writeStatus();
+        }
+    };
+    return {
+        getStatus() {
+            return buildIndexerDaemonStatus(state);
+        },
+        async start() {
+            if (server !== null) {
+                return;
+            }
+            await mkdir(paths.indexerServiceRoot, { recursive: true });
+            await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
+            server = createIndexerDaemonServer({
+                getStatus: () => buildIndexerDaemonStatus(state),
+                openSnapshot,
+                readSnapshot,
+                closeSnapshot,
+                resumeBackgroundFollow: resumeFollow,
+            });
+            heartbeat = setInterval(tick, heartbeatIntervalMs);
+            heartbeat.unref();
+            await new Promise((resolve, reject) => {
+                server?.once("error", reject);
+                server?.listen(paths.indexerDaemonSocketPath, async () => {
+                    server?.off("error", reject);
+                    await writeStatus();
+                    await refreshIndexerDaemonStatus({
+                        databasePath: options.databasePath,
+                        paths,
+                        state,
+                    }).catch(() => undefined);
+                    resolve();
+                });
+            });
+        },
+        async shutdown() {
+            if (shutdownPromise !== null) {
+                return shutdownPromise;
+            }
+            shutdownPromise = (async () => {
+                if (heartbeat !== null) {
+                    clearInterval(heartbeat);
+                    heartbeat = null;
+                }
+                await pauseBackgroundFollow({ state }).catch(() => undefined);
+                state.state = "stopping";
+                state.heartbeatAtUnixMs = Date.now();
+                state.updatedAtUnixMs = state.heartbeatAtUnixMs;
+                await writeStatus().catch(() => undefined);
+                if (server !== null) {
+                    await new Promise((resolve) => {
+                        server?.close(() => resolve());
+                    });
+                    server = null;
+                }
+                await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
+            })();
+            return shutdownPromise;
+        },
+    };
+}

package/dist/bitcoind/indexer-daemon/server.d.ts

@@ -0,0 +1,12 @@
+import net from "node:net";
+import type { IndexerSnapshotHandle, IndexerSnapshotPayload } from "./types.js";
+import type { ManagedIndexerDaemonStatus } from "../types.js";
+interface IndexerDaemonRequestHandlers {
+    getStatus(): ManagedIndexerDaemonStatus | Promise<ManagedIndexerDaemonStatus>;
+    openSnapshot(): Promise<IndexerSnapshotHandle>;
+    readSnapshot(token?: string): Promise<IndexerSnapshotPayload>;
+    closeSnapshot(token?: string): Promise<void>;
+    resumeBackgroundFollow(): Promise<void>;
+}
+export declare function createIndexerDaemonServer(handlers: IndexerDaemonRequestHandlers): net.Server;
+export {};

package/dist/bitcoind/indexer-daemon/server.js

@@ -0,0 +1,87 @@
+import net from "node:net";
+export function createIndexerDaemonServer(handlers) {
+    return net.createServer((socket) => {
+        let buffer = "";
+        const writeResponse = (response) => {
+            socket.write(`${JSON.stringify(response)}\n`);
+        };
+        socket.on("data", (chunk) => {
+            buffer += chunk.toString("utf8");
+            let newlineIndex = buffer.indexOf("\n");
+            while (newlineIndex >= 0) {
+                const line = buffer.slice(0, newlineIndex);
+                buffer = buffer.slice(newlineIndex + 1);
+                if (line.trim().length === 0) {
+                    newlineIndex = buffer.indexOf("\n");
+                    continue;
+                }
+                let request;
+                try {
+                    request = JSON.parse(line);
+                }
+                catch (error) {
+                    writeResponse({
+                        id: "invalid",
+                        ok: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    newlineIndex = buffer.indexOf("\n");
+                    continue;
+                }
+                void (async () => {
+                    try {
+                        switch (request.method) {
+                            case "GetStatus":
+                                writeResponse({
+                                    id: request.id,
+                                    ok: true,
+                                    result: await handlers.getStatus(),
+                                });
+                                return;
+                            case "OpenSnapshot":
+                                writeResponse({
+                                    id: request.id,
+                                    ok: true,
+                                    result: await handlers.openSnapshot(),
+                                });
+                                return;
+                            case "ReadSnapshot":
+                                writeResponse({
+                                    id: request.id,
+                                    ok: true,
+                                    result: await handlers.readSnapshot(request.token),
+                                });
+                                return;
+                            case "CloseSnapshot":
+                                await handlers.closeSnapshot(request.token);
+                                writeResponse({
+                                    id: request.id,
+                                    ok: true,
+                                    result: null,
+                                });
+                                return;
+                            case "ResumeBackgroundFollow":
+                                await handlers.resumeBackgroundFollow();
+                                writeResponse({
+                                    id: request.id,
+                                    ok: true,
+                                    result: null,
+                                });
+                                return;
+                            default:
+                                throw new Error(`indexer_daemon_unknown_method_${request.method}`);
+                        }
+                    }
+                    catch (error) {
+                        writeResponse({
+                            id: request.id,
+                            ok: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                })();
+                newlineIndex = buffer.indexOf("\n");
+            }
+        });
+    });
+}

package/dist/bitcoind/indexer-daemon/snapshot-leases.d.ts

@@ -0,0 +1,23 @@
+import type { ManagedIndexerDaemonStatus } from "../types.js";
+import type { IndexerDaemonRuntimeState, IndexerSnapshotHandle, IndexerSnapshotPayload, LoadedSnapshot, LoadedSnapshotMaterial } from "./types.js";
+export declare function loadSnapshotMaterial(databasePath: string, snapshotTtlMs: number): Promise<LoadedSnapshotMaterial>;
+export declare function storeSnapshotLease(options: {
+    state: IndexerDaemonRuntimeState;
+    material: LoadedSnapshotMaterial;
+    nowUnixMs: number;
+}): LoadedSnapshot;
+export declare function createSnapshotHandle(options: {
+    snapshot: LoadedSnapshot;
+    status: ManagedIndexerDaemonStatus;
+    binaryVersion: string;
+}): IndexerSnapshotHandle;
+export declare function readSnapshotLease(options: {
+    state: IndexerDaemonRuntimeState;
+    token?: string;
+}): {
+    changed: boolean;
+    payload: IndexerSnapshotPayload | null;
+    error: string | null;
+};
+export declare function closeSnapshotLease(state: IndexerDaemonRuntimeState, token?: string): boolean;
+export declare function pruneExpiredSnapshotLeases(state: IndexerDaemonRuntimeState, nowUnixMs: number): boolean;

package/dist/bitcoind/indexer-daemon/snapshot-leases.js

@@ -0,0 +1,139 @@
+import { randomUUID } from "node:crypto";
+import { serializeIndexerState } from "@cogcoin/indexer";
+import { openClient } from "../../client.js";
+import { openSqliteStore } from "../../sqlite/index.js";
+export async function loadSnapshotMaterial(databasePath, snapshotTtlMs) {
+    const store = await openSqliteStore({ filename: databasePath });
+    try {
+        const client = await openClient({ store });
+        try {
+            const [tip, state] = await Promise.all([client.getTip(), client.getState()]);
+            return {
+                token: randomUUID(),
+                stateBase64: Buffer.from(serializeIndexerState(state)).toString("base64"),
+                tip,
+                expiresAtUnixMs: Date.now() + snapshotTtlMs,
+            };
+        }
+        finally {
+            await client.close();
+        }
+    }
+    finally {
+        await store.close().catch(() => undefined);
+    }
+}
+export function storeSnapshotLease(options) {
+    const snapshot = {
+        ...options.material,
+        serviceApiVersion: "cogcoin/indexer-ipc/v1",
+        schemaVersion: "cogcoin/indexer-db/v1",
+        walletRootId: options.state.walletRootId,
+        daemonInstanceId: options.state.daemonInstanceId,
+        processId: process.pid ?? null,
+        startedAtUnixMs: options.state.startedAtUnixMs,
+        snapshotSeq: options.state.snapshotSeq,
+        tipHeight: options.material.tip?.height ?? null,
+        tipHash: options.material.tip?.blockHashHex ?? null,
+        openedAtUnixMs: options.nowUnixMs,
+    };
+    options.state.snapshots.set(snapshot.token, snapshot);
+    return snapshot;
+}
+export function createSnapshotHandle(options) {
+    return {
+        token: options.snapshot.token,
+        expiresAtUnixMs: options.snapshot.expiresAtUnixMs,
+        serviceApiVersion: options.snapshot.serviceApiVersion,
+        binaryVersion: options.binaryVersion,
+        buildId: null,
+        walletRootId: options.snapshot.walletRootId,
+        daemonInstanceId: options.snapshot.daemonInstanceId,
+        schemaVersion: options.snapshot.schemaVersion,
+        processId: options.snapshot.processId,
+        startedAtUnixMs: options.snapshot.startedAtUnixMs,
+        state: options.status.state,
+        heartbeatAtUnixMs: options.status.heartbeatAtUnixMs,
+        rpcReachable: options.status.rpcReachable,
+        coreBestHeight: options.status.coreBestHeight,
+        coreBestHash: options.status.coreBestHash,
+        appliedTipHeight: options.status.appliedTipHeight,
+        appliedTipHash: options.status.appliedTipHash,
+        snapshotSeq: options.snapshot.snapshotSeq,
+        backlogBlocks: options.status.backlogBlocks,
+        reorgDepth: options.status.reorgDepth,
+        lastAppliedAtUnixMs: options.status.lastAppliedAtUnixMs,
+        activeSnapshotCount: options.status.activeSnapshotCount,
+        lastError: options.status.lastError,
+        backgroundFollowActive: options.status.backgroundFollowActive ?? false,
+        bootstrapPhase: options.status.bootstrapPhase ?? null,
+        bootstrapProgress: options.status.bootstrapProgress ?? null,
+        cogcoinSyncHeight: options.status.cogcoinSyncHeight ?? null,
+        cogcoinSyncTargetHeight: options.status.cogcoinSyncTargetHeight ?? null,
+        tipHeight: options.snapshot.tipHeight,
+        tipHash: options.snapshot.tipHash,
+        openedAtUnixMs: options.snapshot.openedAtUnixMs,
+    };
+}
+export function readSnapshotLease(options) {
+    const snapshot = options.token ? options.state.snapshots.get(options.token) : null;
+    if (!snapshot || snapshot.expiresAtUnixMs <= Date.now()) {
+        if (options.token) {
+            options.state.snapshots.delete(options.token);
+            return {
+                changed: true,
+                payload: null,
+                error: "indexer_daemon_snapshot_invalid",
+            };
+        }
+        return {
+            changed: false,
+            payload: null,
+            error: "indexer_daemon_snapshot_invalid",
+        };
+    }
+    if (snapshot.snapshotSeq !== options.state.snapshotSeq) {
+        options.state.snapshots.delete(snapshot.token);
+        return {
+            changed: true,
+            payload: null,
+            error: "indexer_daemon_snapshot_rotated",
+        };
+    }
+    return {
+        changed: false,
+        payload: {
+            token: snapshot.token,
+            stateBase64: snapshot.stateBase64,
+            serviceApiVersion: snapshot.serviceApiVersion,
+            schemaVersion: snapshot.schemaVersion,
+            walletRootId: snapshot.walletRootId,
+            daemonInstanceId: snapshot.daemonInstanceId,
+            processId: snapshot.processId,
+            startedAtUnixMs: snapshot.startedAtUnixMs,
+            snapshotSeq: snapshot.snapshotSeq,
+            tipHeight: snapshot.tipHeight,
+            tipHash: snapshot.tipHash,
+            openedAtUnixMs: snapshot.openedAtUnixMs,
+            tip: snapshot.tip,
+            expiresAtUnixMs: snapshot.expiresAtUnixMs,
+        },
+        error: null,
+    };
+}
+export function closeSnapshotLease(state, token) {
+    if (!token) {
+        return false;
+    }
+    return state.snapshots.delete(token);
+}
+export function pruneExpiredSnapshotLeases(state, nowUnixMs) {
+    let changed = false;
+    for (const [token, snapshot] of state.snapshots.entries()) {
+        if (snapshot.expiresAtUnixMs <= nowUnixMs) {
+            state.snapshots.delete(token);
+            changed = true;
+        }
+    }
+    return changed;
+}

package/dist/bitcoind/indexer-daemon/status.d.ts

@@ -0,0 +1,23 @@
+import type { ClientTip } from "../../types.js";
+import { resolveManagedServicePaths } from "../service-paths.js";
+import type { ManagedBitcoindObservedStatus, ManagedIndexerDaemonStatus } from "../types.js";
+import type { CoreTipStatus, IndexedTipStatus, IndexerDaemonLeaseStateResult, IndexerDaemonRuntimeState } from "./types.js";
+export declare function readJsonFile<T>(filePath: string): Promise<T | null>;
+export declare function readManagedBitcoindStatus(paths: ReturnType<typeof resolveManagedServicePaths>): Promise<ManagedBitcoindObservedStatus | null>;
+export declare function createIndexerSnapshotKey(appliedTip: ClientTip | null): string;
+export declare function createManagedBitcoindCookieUnavailableMessage(cookieFile: string): string;
+export declare function readCoreTipStatus(paths: ReturnType<typeof resolveManagedServicePaths>): Promise<CoreTipStatus>;
+export declare function readAppliedTipStatus(databasePath: string): Promise<IndexedTipStatus>;
+export declare function observeIndexerAppliedTip(state: IndexerDaemonRuntimeState, appliedTip: ClientTip | null, nowUnixMs: number): void;
+export declare function deriveIndexerDaemonLeaseState(options: {
+    coreStatus: CoreTipStatus;
+    appliedTip: ClientTip | null;
+    hasSuccessfulCoreTipRefresh: boolean;
+}): IndexerDaemonLeaseStateResult;
+export declare function buildIndexerDaemonStatus(state: IndexerDaemonRuntimeState): ManagedIndexerDaemonStatus;
+export declare function writeIndexerDaemonStatus(paths: ReturnType<typeof resolveManagedServicePaths>, state: IndexerDaemonRuntimeState): Promise<ManagedIndexerDaemonStatus>;
+export declare function refreshIndexerDaemonStatus(options: {
+    databasePath: string;
+    paths: ReturnType<typeof resolveManagedServicePaths>;
+    state: IndexerDaemonRuntimeState;
+}): Promise<ManagedIndexerDaemonStatus>;