@cogcoin/client 0.5.5 → 0.5.7

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

@@ -1,7 +1,8 @@
 import { type ManagedIndexerDaemonObservedStatus, type ManagedIndexerDaemonStatus } from "./types.js";
+import { resolveManagedServicePaths } from "./service-paths.js";
 interface DaemonRequest {
     id: string;
-    method: "GetStatus" | "OpenSnapshot" | "ReadSnapshot" | "CloseSnapshot";
+    method: "GetStatus" | "OpenSnapshot" | "ReadSnapshot" | "CloseSnapshot" | "PauseBackgroundFollow" | "ResumeBackgroundFollow";
     token?: string;
 }
 interface DaemonResponse {
@@ -64,6 +65,8 @@ export interface IndexerDaemonClient {
     openSnapshot(): Promise<IndexerSnapshotHandle>;
     readSnapshot(token: string): Promise<IndexerSnapshotPayload>;
     closeSnapshot(token: string): Promise<void>;
+    pauseBackgroundFollow(): Promise<void>;
+    resumeBackgroundFollow(): Promise<void>;
     close(): Promise<void>;
 }
 export type IndexerDaemonCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "schema-mismatch" | "unreachable" | "protocol-error";
@@ -81,6 +84,12 @@ export interface CoherentIndexerSnapshotLease {
     payload: IndexerSnapshotPayload;
     status: ManagedIndexerDaemonStatus;
 }
+export declare function stopIndexerDaemonServiceWithLockHeld(options: {
+    dataDir: string;
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+    paths?: ReturnType<typeof resolveManagedServicePaths>;
+}): Promise<IndexerDaemonStopResult>;
 export declare function probeIndexerDaemon(options: {
     dataDir: string;
     walletRootId?: string;

package/dist/bitcoind/indexer-daemon.js

@@ -53,6 +53,33 @@ async function clearIndexerDaemonRuntimeArtifacts(paths) {
     await rm(paths.indexerDaemonStatusPath, { force: true }).catch(() => undefined);
     await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
 }
+export async function stopIndexerDaemonServiceWithLockHeld(options) {
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const paths = options.paths ?? resolveManagedServicePaths(options.dataDir, walletRootId);
+    const status = await readJsonFile(paths.indexerDaemonStatusPath);
+    const processId = status?.processId ?? null;
+    if (status === null || processId === null || !await isProcessAlive(processId)) {
+        await clearIndexerDaemonRuntimeArtifacts(paths);
+        return {
+            status: "not-running",
+            walletRootId,
+        };
+    }
+    try {
+        process.kill(processId, "SIGTERM");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+            throw error;
+        }
+    }
+    await waitForProcessExit(processId, options.shutdownTimeoutMs ?? 5_000, "indexer_daemon_stop_timeout");
+    await clearIndexerDaemonRuntimeArtifacts(paths);
+    return {
+        status: "stopped",
+        walletRootId,
+    };
+}
 function createIndexerDaemonClient(socketPath) {
     async function sendRequest(request) {
         return new Promise((resolve, reject) => {
@@ -141,6 +168,18 @@ function createIndexerDaemonClient(socketPath) {
                 token,
             });
         },
+        async pauseBackgroundFollow() {
+            await sendRequest({
+                id: randomUUID(),
+                method: "PauseBackgroundFollow",
+            });
+        },
+        async resumeBackgroundFollow() {
+            await sendRequest({
+                id: randomUUID(),
+                method: "ResumeBackgroundFollow",
+            });
+        },
         async close() {
             return;
         },
@@ -150,9 +189,6 @@ function validateIndexerRuntimeIdentity(identity, expectedWalletRootId) {
     if (identity.serviceApiVersion !== INDEXER_DAEMON_SERVICE_API_VERSION) {
         throw new Error("indexer_daemon_service_version_mismatch");
     }
-    if (identity.walletRootId !== expectedWalletRootId) {
-        throw new Error("indexer_daemon_wallet_root_mismatch");
-    }
     if (identity.schemaVersion !== INDEXER_DAEMON_SCHEMA_VERSION || identity.state === "schema-mismatch") {
         throw new Error("indexer_daemon_schema_mismatch");
     }
@@ -244,9 +280,7 @@ async function probeIndexerDaemonAtSocket(socketPath, expectedWalletRootId) {
                 compatibility: error instanceof Error
                     ? error.message === "indexer_daemon_service_version_mismatch"
                         ? "service-version-mismatch"
-                        : error.message === "indexer_daemon_wallet_root_mismatch"
-                            ? "wallet-root-mismatch"
-                            : "schema-mismatch"
+                        : "schema-mismatch"
                     : "protocol-error",
                 status,
                 client: null,
@@ -380,29 +414,11 @@ export async function stopIndexerDaemonService(options) {
         dataDir: options.dataDir,
     });
     try {
-        const status = await readJsonFile(paths.indexerDaemonStatusPath);
-        const processId = status?.processId ?? null;
-        if (status === null || processId === null || !await isProcessAlive(processId)) {
-            await clearIndexerDaemonRuntimeArtifacts(paths);
-            return {
-                status: "not-running",
-                walletRootId,
-            };
-        }
-        try {
-            process.kill(processId, "SIGTERM");
-        }
-        catch (error) {
-            if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
-                throw error;
-            }
-        }
-        await waitForProcessExit(processId, options.shutdownTimeoutMs ?? 5_000, "indexer_daemon_stop_timeout");
-        await clearIndexerDaemonRuntimeArtifacts(paths);
-        return {
-            status: "stopped",
+        return await stopIndexerDaemonServiceWithLockHeld({
+            ...options,
             walletRootId,
-        };
+            paths,
+        });
     }
     finally {
         await lock.release();

package/dist/bitcoind/node.js

@@ -182,6 +182,8 @@ export async function launchManagedBitcoindNode(options) {
         expectedChain: resolvedOptions.chain,
         startHeight: resolvedOptions.startHeight,
         dataDir: resolvedOptions.dataDir,
+        getblockArchiveEndHeight: null,
+        getblockArchiveSha256: null,
         async validate() {
             await validateNodeConfigForTesting(rpcClient, resolvedOptions.chain, zmqEndpoint);
         },

package/dist/bitcoind/processing-start-height.d.ts

@@ -0,0 +1,7 @@
+import type { GenesisParameters } from "@cogcoin/indexer/types";
+export declare function resolveCogcoinProcessingStartHeight(genesisParameters: GenesisParameters): number;
+export declare function assertCogcoinProcessingStartHeight(options: {
+    chain: "main" | "regtest";
+    startHeight: number;
+    genesisParameters: GenesisParameters;
+}): void;

package/dist/bitcoind/processing-start-height.js

@@ -0,0 +1,9 @@
+export function resolveCogcoinProcessingStartHeight(genesisParameters) {
+    return genesisParameters.genesisBlock;
+}
+export function assertCogcoinProcessingStartHeight(options) {
+    const processingStartHeight = resolveCogcoinProcessingStartHeight(options.genesisParameters);
+    if (options.chain === "main" && options.startHeight < processingStartHeight) {
+        throw new Error("cogcoin_processing_start_height_before_genesis");
+    }
+}

package/dist/bitcoind/progress/constants.d.ts

@@ -1,4 +1,5 @@
 export declare const PROGRESS_TICK_MS = 250;
+export declare const HEADLESS_PROGRESS_TICK_MS = 1000;
 export declare const PREPARING_SYNC_LINE = "Preparing managed Cogcoin sync...";
 export declare const ART_WIDTH = 80;
 export declare const ART_HEIGHT = 13;

package/dist/bitcoind/progress/constants.js

@@ -1,4 +1,5 @@
 export const PROGRESS_TICK_MS = 250;
+export const HEADLESS_PROGRESS_TICK_MS = 1_000;
 export const PREPARING_SYNC_LINE = "Preparing managed Cogcoin sync...";
 export const ART_WIDTH = 80;
 export const ART_HEIGHT = 13;

package/dist/bitcoind/progress/controller.d.ts

@@ -1,9 +1,31 @@
+import type { QuoteDisplayPhase } from "../quotes.js";
 import type { BootstrapPhase, BootstrapProgress, ManagedBitcoindProgressEvent, ProgressOutputMode, SnapshotMetadata, WritingQuote } from "../types.js";
+import { type FollowSceneStateForTesting } from "./follow-scene.js";
+import { type RenderClock, type TtyRenderStream } from "./render-policy.js";
+interface QuoteRotatorLike {
+    current(now?: number): Promise<{
+        displayPhase: QuoteDisplayPhase;
+        currentQuote: WritingQuote | null;
+        displayStartedAt: number;
+    }>;
+}
+interface ProgressRendererLike {
+    render(displayPhase: QuoteDisplayPhase, quote: WritingQuote | null, progress: BootstrapProgress, cogcoinSyncHeight: number | null, cogcoinSyncTargetHeight: number | null, introElapsedMs?: number, statusFieldText?: string): void;
+    renderTrainScene(kind: "intro" | "completion", progress: BootstrapProgress, cogcoinSyncHeight: number | null, cogcoinSyncTargetHeight: number | null, elapsedMs: number, statusFieldText?: string): void;
+    renderFollowScene(progress: BootstrapProgress, cogcoinSyncHeight: number | null, cogcoinSyncTargetHeight: number | null, followScene: FollowSceneStateForTesting, statusFieldText?: string): void;
+    close(): void;
+}
 interface ProgressControllerOptions {
     onProgress?: (event: ManagedBitcoindProgressEvent) => void;
     progressOutput?: ProgressOutputMode;
     quoteStatePath: string;
     snapshot: SnapshotMetadata;
+    quoteRotator?: QuoteRotatorLike;
+    rendererFactory?: (stream: TtyRenderStream) => ProgressRendererLike;
+    stream?: TtyRenderStream;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    clock?: RenderClock;
 }
 export declare class ManagedProgressController {
     #private;

package/dist/bitcoind/progress/controller.js

@@ -1,12 +1,17 @@
 import { WritingQuoteRotator as QuoteRotator } from "../quotes.js";
-import { INTRO_TOTAL_MS, PROGRESS_TICK_MS } from "./constants.js";
+import { INTRO_TOTAL_MS } from "./constants.js";
 import { advanceFollowSceneState, createFollowSceneState, replaceFollowBlockTimes, setFollowBlockTime, syncFollowSceneState, } from "./follow-scene.js";
 import { createBootstrapProgress, createDefaultMessage, resolveStatusFieldText, } from "./formatting.js";
+import { DEFAULT_RENDER_CLOCK, resolveTtyRenderPolicy, TtyRenderThrottle, } from "./render-policy.js";
 import { TtyProgressRenderer } from "./tty-renderer.js";
 export class ManagedProgressController {
     #options;
     #snapshot;
     #outputMode;
+    #clock;
+    #renderStream;
+    #renderThrottle;
+    #renderIntervalMs;
     #quoteRotator = null;
     #renderer = null;
     #ticker = null;
@@ -24,26 +29,47 @@ export class ManagedProgressController {
         this.#snapshot = options.snapshot;
         this.#outputMode = options.progressOutput ?? "auto";
         this.#progress = createBootstrapProgress("paused", options.snapshot);
+        this.#clock = options.clock ?? DEFAULT_RENDER_CLOCK;
+        this.#renderStream = options.stream ?? process.stderr;
+        const renderPolicy = resolveTtyRenderPolicy(this.#outputMode, this.#renderStream, {
+            platform: options.platform,
+            env: options.env,
+        });
+        this.#renderIntervalMs = renderPolicy.repaintIntervalMs;
+        this.#renderThrottle = new TtyRenderThrottle({
+            clock: this.#clock,
+            intervalMs: this.#renderIntervalMs,
+            onRender: () => {
+                this.#renderToTty();
+            },
+            throttled: renderPolicy.linuxHeadlessThrottle,
+        });
     }
     async start() {
         if (this.#started) {
             return;
         }
         this.#started = true;
-        this.#quoteRotator = await QuoteRotator.create(this.#options.quoteStatePath);
-        if (this.#shouldRenderToTty()) {
-            this.#renderer = new TtyProgressRenderer();
+        this.#quoteRotator = this.#options.quoteRotator
+            ?? await QuoteRotator.create(this.#options.quoteStatePath);
+        if (resolveTtyRenderPolicy(this.#outputMode, this.#renderStream, {
+            platform: this.#options.platform,
+            env: this.#options.env,
+        }).enabled) {
+            this.#renderer = this.#options.rendererFactory?.(this.#renderStream)
+                ?? new TtyProgressRenderer(this.#renderStream);
         }
         await this.#refresh();
-        this.#ticker = setInterval(() => {
+        this.#ticker = this.#clock.setInterval(() => {
             void this.#refresh();
-        }, PROGRESS_TICK_MS);
+        }, this.#renderIntervalMs);
     }
     async close() {
         if (this.#ticker !== null) {
-            clearInterval(this.#ticker);
+            this.#clock.clearInterval(this.#ticker);
             this.#ticker = null;
         }
+        this.#renderThrottle.flush();
         this.#renderer?.close();
         this.#renderer = null;
         this.#started = false;
@@ -72,19 +98,20 @@ export class ManagedProgressController {
         if (!this.#started || this.#renderer === null) {
             return;
         }
+        this.#renderThrottle.flush();
         if (this.#ticker !== null) {
-            clearInterval(this.#ticker);
+            this.#clock.clearInterval(this.#ticker);
             this.#ticker = null;
         }
-        const startedAt = Date.now();
+        const startedAt = this.#clock.now();
         while (true) {
-            const elapsedMs = Math.min(INTRO_TOTAL_MS, Date.now() - startedAt);
+            const elapsedMs = Math.min(INTRO_TOTAL_MS, this.#clock.now() - startedAt);
             this.#renderer.renderTrainScene("completion", this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, elapsedMs);
             if (elapsedMs >= INTRO_TOTAL_MS) {
                 break;
             }
             await new Promise((resolve) => {
-                setTimeout(resolve, PROGRESS_TICK_MS);
+                this.#clock.setTimeout(resolve, this.#renderIntervalMs);
             });
         }
     }
@@ -117,6 +144,7 @@ export class ManagedProgressController {
             phase: "cogcoin_sync",
             message: createDefaultMessage("cogcoin_sync"),
             etaSeconds,
+            lastError: null,
             updatedAt: Date.now(),
         };
         if (this.#followVisualMode) {
@@ -142,7 +170,7 @@ export class ManagedProgressController {
         if (!this.#started || this.#quoteRotator === null) {
             return;
         }
-        const now = Date.now();
+        const now = this.#clock.now();
         if (this.#followVisualMode) {
             advanceFollowSceneState(this.#followScene, now);
             this.#currentQuote = null;
@@ -169,20 +197,18 @@ export class ManagedProgressController {
         catch {
             // User progress callbacks should never break managed sync.
         }
+        this.#renderThrottle.request();
+    }
+    #renderToTty() {
+        if (!this.#started || this.#renderer === null) {
+            return;
+        }
+        const now = this.#clock.now();
         const statusFieldText = resolveStatusFieldText(this.#progress, this.#snapshot.height, now);
         if (this.#followVisualMode) {
-            this.#renderer?.renderFollowScene(this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, this.#followScene, statusFieldText);
+            this.#renderer.renderFollowScene(this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, this.#followScene, statusFieldText);
             return;
         }
-        this.#renderer?.render(this.#currentDisplayPhase, this.#currentQuote, this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, Math.max(0, now - this.#currentDisplayStartedAt), statusFieldText);
-    }
-    #shouldRenderToTty() {
-        if (this.#outputMode === "none") {
-            return false;
-        }
-        if (this.#outputMode === "tty") {
-            return true;
-        }
-        return process.stderr.isTTY === true;
+        this.#renderer.render(this.#currentDisplayPhase, this.#currentQuote, this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, Math.max(0, now - this.#currentDisplayStartedAt), statusFieldText);
     }
 }

package/dist/bitcoind/progress/formatting.js

@@ -1,10 +1,14 @@
 import { FIELD_LEFT, FIELD_WIDTH, PREPARING_SYNC_LINE, PROGRESS_TICK_MS, SCROLL_WINDOW_LEFT, SCROLL_WINDOW_WIDTH, STATUS_ELLIPSIS_TICK_MS, STATUS_ELLIPSIS_WIDTH, } from "./constants.js";
 export function createDefaultMessage(phase) {
     switch (phase) {
+        case "getblock_archive_download":
+            return "Downloading getblock archive.";
+        case "getblock_archive_import":
+            return "Bitcoin Core is importing getblock archive blocks.";
         case "snapshot_download":
             return "Downloading UTXO snapshot.";
         case "wait_headers_for_snapshot":
-            return "Waiting for Bitcoin headers to reach the snapshot height.";
+            return "Pre-synchronizing blockheaders.";
         case "load_snapshot":
             return "Loading the UTXO snapshot into bitcoind.";
         case "bitcoin_sync":
@@ -121,10 +125,17 @@ function animateStatusEllipsis(now) {
 }
 export function resolveStatusFieldText(progress, snapshotHeight, now = 0) {
     switch (progress.phase) {
+        case "getblock_archive_download":
+            return `Downloading getblock archive${animateStatusEllipsis(now)}`;
+        case "getblock_archive_import":
+            return `Importing getblock archive${animateStatusEllipsis(now)}`;
         case "paused":
         case "snapshot_download":
             return `Downloading snapshot to ${snapshotHeight}${animateStatusEllipsis(now)}`;
         case "wait_headers_for_snapshot":
+            return progress.message === "Waiting for Bitcoin headers to reach the snapshot height."
+                ? `Waiting for Bitcoin headers to reach the snapshot height${animateStatusEllipsis(now)}`
+                : `Pre-synchronizing blockheaders${animateStatusEllipsis(now)}`;
         case "load_snapshot":
         case "bitcoin_sync":
             return `Syncing Bitcoin Blocks${animateStatusEllipsis(now)}`;
@@ -163,6 +174,16 @@ export const formatQuoteLineForTesting = formatQuoteLine;
 export function formatProgressLine(progress, cogcoinSyncHeight, cogcoinSyncTargetHeight, width = 120, now = Date.now()) {
     let line;
     switch (progress.phase) {
+        case "getblock_archive_download": {
+            const current = progress.downloadedBytes ?? 0;
+            const total = progress.totalBytes ?? 0;
+            const bar = renderBar(current, total, 20);
+            const percent = progress.percent ?? (total > 0 ? (current / total) * 100 : 0);
+            const speed = progress.bytesPerSecond === null ? "--" : `${formatBytes(progress.bytesPerSecond)}/s`;
+            const resumed = progress.resumed ? " resumed" : "";
+            line = `${bar} ${percent.toFixed(2)}% ${formatBytes(current)} / ${formatBytes(total)} ${speed} ETA ${formatDuration(progress.etaSeconds)}${resumed}`;
+            break;
+        }
         case "snapshot_download": {
             const current = progress.downloadedBytes ?? 0;
             const total = progress.totalBytes ?? 0;
@@ -187,6 +208,13 @@ export function formatProgressLine(progress, cogcoinSyncHeight, cogcoinSyncTarge
             line = `${bar} Bitcoin ${blocks.toLocaleString()} / ${target.toLocaleString()} ETA ${formatDuration(progress.etaSeconds)} ${progress.message}`;
             break;
         }
+        case "getblock_archive_import": {
+            const blocks = progress.blocks ?? 0;
+            const target = progress.targetHeight ?? blocks;
+            const bar = renderBar(blocks, target, 20);
+            line = `${bar} Bitcoin ${blocks.toLocaleString()} / ${target.toLocaleString()} ${progress.message}`;
+            break;
+        }
         case "cogcoin_sync": {
             const current = cogcoinSyncHeight ?? 0;
             const target = cogcoinSyncTargetHeight ?? current;

package/dist/bitcoind/progress/render-policy.d.ts

@@ -0,0 +1,35 @@
+import type { ProgressOutputMode } from "../types.js";
+export interface TtyRenderStream {
+    isTTY?: boolean;
+    columns?: number;
+    write(chunk: string): boolean | void;
+}
+export interface RenderClock {
+    now(): number;
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+    setInterval: typeof setInterval;
+    clearInterval: typeof clearInterval;
+}
+export interface TtyRenderPolicy {
+    enabled: boolean;
+    linuxHeadlessThrottle: boolean;
+    repaintIntervalMs: number;
+}
+export declare const DEFAULT_RENDER_CLOCK: RenderClock;
+export declare function resolveTtyRenderPolicy(progressOutput: ProgressOutputMode, stream: Pick<TtyRenderStream, "isTTY">, options?: {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+}): TtyRenderPolicy;
+export declare class TtyRenderThrottle {
+    #private;
+    constructor(options: {
+        clock?: RenderClock;
+        intervalMs: number;
+        onRender: () => void;
+        throttled: boolean;
+    });
+    request(): void;
+    flush(): void;
+    cancel(): void;
+}

package/dist/bitcoind/progress/render-policy.js

@@ -0,0 +1,81 @@
+import { HEADLESS_PROGRESS_TICK_MS, PROGRESS_TICK_MS } from "./constants.js";
+export const DEFAULT_RENDER_CLOCK = {
+    now: () => Date.now(),
+    setTimeout,
+    clearTimeout,
+    setInterval,
+    clearInterval,
+};
+export function resolveTtyRenderPolicy(progressOutput, stream, options = {}) {
+    const ttyActive = stream.isTTY === true;
+    const enabled = progressOutput === "none"
+        ? false
+        : progressOutput === "tty"
+            ? true
+            : ttyActive;
+    const env = options.env ?? process.env;
+    const linuxHeadlessThrottle = enabled
+        && ttyActive
+        && (options.platform ?? process.platform) === "linux"
+        && (env.DISPLAY?.trim() ?? "").length === 0
+        && (env.WAYLAND_DISPLAY?.trim() ?? "").length === 0;
+    return {
+        enabled,
+        linuxHeadlessThrottle,
+        repaintIntervalMs: linuxHeadlessThrottle ? HEADLESS_PROGRESS_TICK_MS : PROGRESS_TICK_MS,
+    };
+}
+export class TtyRenderThrottle {
+    #clock;
+    #intervalMs;
+    #onRender;
+    #throttled;
+    #lastRenderAt = null;
+    #pendingTimer = null;
+    constructor(options) {
+        this.#clock = options.clock ?? DEFAULT_RENDER_CLOCK;
+        this.#intervalMs = options.intervalMs;
+        this.#onRender = options.onRender;
+        this.#throttled = options.throttled;
+    }
+    request() {
+        if (!this.#throttled) {
+            this.cancel();
+            this.#renderNow();
+            return;
+        }
+        const now = this.#clock.now();
+        if (this.#lastRenderAt === null || (now - this.#lastRenderAt) >= this.#intervalMs) {
+            this.cancel();
+            this.#renderNow();
+            return;
+        }
+        if (this.#pendingTimer !== null) {
+            return;
+        }
+        const delayMs = Math.max(0, this.#intervalMs - (now - this.#lastRenderAt));
+        this.#pendingTimer = this.#clock.setTimeout(() => {
+            this.#pendingTimer = null;
+            this.#renderNow();
+        }, delayMs);
+    }
+    flush() {
+        if (this.#pendingTimer === null) {
+            return;
+        }
+        this.#clock.clearTimeout(this.#pendingTimer);
+        this.#pendingTimer = null;
+        this.#renderNow();
+    }
+    cancel() {
+        if (this.#pendingTimer === null) {
+            return;
+        }
+        this.#clock.clearTimeout(this.#pendingTimer);
+        this.#pendingTimer = null;
+    }
+    #renderNow() {
+        this.#lastRenderAt = this.#clock.now();
+        this.#onRender();
+    }
+}

package/dist/bitcoind/retryable-rpc.d.ts

@@ -0,0 +1,11 @@
+export declare const MANAGED_RPC_RETRY_BASE_MS = 1000;
+export declare const MANAGED_RPC_RETRY_MAX_MS = 15000;
+export declare const MANAGED_RPC_RETRY_MESSAGE = "Managed Bitcoin RPC temporarily unavailable; retrying until canceled.";
+export interface ManagedRpcRetryState {
+    nextDelayMs: number;
+}
+export declare function createManagedRpcRetryState(): ManagedRpcRetryState;
+export declare function resetManagedRpcRetryState(state: ManagedRpcRetryState): void;
+export declare function consumeManagedRpcRetryDelayMs(state: ManagedRpcRetryState): number;
+export declare function isRetryableManagedRpcError(error: unknown): boolean;
+export declare function describeManagedRpcRetryError(error: unknown): string;

package/dist/bitcoind/retryable-rpc.js

@@ -0,0 +1,30 @@
+export const MANAGED_RPC_RETRY_BASE_MS = 1_000;
+export const MANAGED_RPC_RETRY_MAX_MS = 15_000;
+export const MANAGED_RPC_RETRY_MESSAGE = "Managed Bitcoin RPC temporarily unavailable; retrying until canceled.";
+export function createManagedRpcRetryState() {
+    return {
+        nextDelayMs: MANAGED_RPC_RETRY_BASE_MS,
+    };
+}
+export function resetManagedRpcRetryState(state) {
+    state.nextDelayMs = MANAGED_RPC_RETRY_BASE_MS;
+}
+export function consumeManagedRpcRetryDelayMs(state) {
+    const delayMs = state.nextDelayMs;
+    state.nextDelayMs = Math.min(state.nextDelayMs * 2, MANAGED_RPC_RETRY_MAX_MS);
+    return delayMs;
+}
+export function isRetryableManagedRpcError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message === "bitcoind_rpc_timeout") {
+        return true;
+    }
+    if (message.startsWith("The managed Bitcoin RPC request to ")) {
+        return message.includes(" failed");
+    }
+    return message.startsWith("The managed Bitcoin RPC cookie file is unavailable at ")
+        || message.startsWith("The managed Bitcoin RPC cookie file could not be read at ");
+}
+export function describeManagedRpcRetryError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/bitcoind/service-paths.js

@@ -3,9 +3,6 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { resolveCogcoinPathsForTesting, resolveDefaultBitcoindDataDirForTesting } from "../app-paths.js";
 export const UNINITIALIZED_WALLET_ROOT_ID = "wallet-root-uninitialized";
-function sanitizeWalletRootId(walletRootId) {
-    return walletRootId.replace(/[^a-zA-Z0-9._-]+/g, "-");
-}
 function createDataDirSuffix(dataDir) {
     return createHash("sha256").update(dataDir).digest("hex").slice(0, 12);
 }
@@ -17,7 +14,6 @@ function resolveIndexerDaemonSocketPath(serviceRootId) {
     return join(tmpdir(), `cogcoin-indexer-${socketId}.sock`);
 }
 export function resolveManagedServicePaths(dataDir, walletRootId = UNINITIALIZED_WALLET_ROOT_ID) {
-    const normalizedWalletRootId = sanitizeWalletRootId(walletRootId);
     const defaultPaths = resolveCogcoinPathsForTesting();
     const defaultBitcoindDataDir = resolveDefaultBitcoindDataDirForTesting();
     const useDefaultRoots = dataDir === defaultBitcoindDataDir;
@@ -25,8 +21,8 @@ export function resolveManagedServicePaths(dataDir, walletRootId = UNINITIALIZED
     const runtimeRoot = useDefaultRoots ? defaultPaths.runtimeRoot : join(dataRoot, "runtime");
     const indexerRoot = useDefaultRoots ? defaultPaths.indexerRoot : join(dataRoot, "indexer");
     const serviceRootId = useDefaultRoots
-        ? normalizedWalletRootId
-        : `${normalizedWalletRootId}-${createDataDirSuffix(dataDir)}`;
+        ? "managed"
+        : `managed-${createDataDirSuffix(dataDir)}`;
     const walletRuntimeRoot = join(runtimeRoot, serviceRootId);
     const indexerServiceRoot = join(indexerRoot, serviceRootId);
     return {

package/dist/bitcoind/service.d.ts

@@ -1,4 +1,6 @@
-import type { InternalManagedBitcoindOptions, ManagedBitcoindObservedStatus, ManagedBitcoindNodeHandle, ManagedCoreWalletReplicaStatus } from "./types.js";
+import { resolveManagedServicePaths } from "./service-paths.js";
+import type { InternalManagedBitcoindOptions, ManagedBitcoindObservedStatus, ManagedBitcoindRuntimeConfig, ManagedBitcoindNodeHandle, ManagedCoreWalletReplicaStatus } from "./types.js";
+export declare function resolveManagedBitcoindDbcacheMiB(totalRamBytes: number): number;
 interface ManagedWalletReplicaRpc {
     listWallets(): Promise<string[]>;
     loadWallet(walletName: string, loadOnStartup?: boolean): Promise<{
@@ -18,7 +20,11 @@ interface ManagedWalletReplicaRpc {
     }>;
     walletLock(walletName: string): Promise<null>;
 }
-type ManagedBitcoindServiceOptions = Pick<InternalManagedBitcoindOptions, "dataDir" | "chain" | "startHeight" | "walletRootId" | "rpcPort" | "zmqPort" | "p2pPort" | "pollIntervalMs" | "startupTimeoutMs" | "shutdownTimeoutMs" | "managedWalletPassphrase">;
+type ManagedBitcoindServiceOptions = Pick<InternalManagedBitcoindOptions, "dataDir" | "chain" | "startHeight" | "walletRootId" | "rpcPort" | "zmqPort" | "p2pPort" | "pollIntervalMs" | "startupTimeoutMs" | "shutdownTimeoutMs" | "managedWalletPassphrase"> & {
+    getblockArchivePath?: string | null;
+    getblockArchiveEndHeight?: number | null;
+    getblockArchiveSha256?: string | null;
+};
 export type ManagedBitcoindServiceCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "unreachable" | "protocol-error";
 export interface ManagedBitcoindServiceProbeResult {
     compatibility: ManagedBitcoindServiceCompatibility;
@@ -29,9 +35,22 @@ export interface ManagedBitcoindServiceStopResult {
     status: "stopped" | "not-running";
     walletRootId: string;
 }
+export declare function writeBitcoinConfForTesting(filePath: string, options: ManagedBitcoindServiceOptions, runtimeConfig: ManagedBitcoindRuntimeConfig): Promise<void>;
+export declare function buildManagedServiceArgsForTesting(options: ManagedBitcoindServiceOptions, runtimeConfig: ManagedBitcoindRuntimeConfig): string[];
 export declare function createManagedWalletReplica(rpc: ManagedWalletReplicaRpc, walletRootId: string, options?: {
     managedWalletPassphrase?: string;
 }): Promise<ManagedCoreWalletReplicaStatus>;
+export declare function stopManagedBitcoindServiceWithLockHeld(options: {
+    dataDir: string;
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+    paths?: ReturnType<typeof resolveManagedServicePaths>;
+}): Promise<ManagedBitcoindServiceStopResult>;
+export declare function withClaimedUninitializedManagedRuntime<T>(options: {
+    dataDir: string;
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+}, callback: () => Promise<T>): Promise<T>;
 export declare function probeManagedBitcoindService(options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindServiceProbeResult>;
 export declare function attachOrStartManagedBitcoindService(options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindNodeHandle>;
 export declare function stopManagedBitcoindService(options: {