@cogcoin/client 0.5.0

package/dist/bitcoind/rpc.d.ts

@@ -0,0 +1,71 @@
+import type { RpcBlock, RpcBlockchainInfo, RpcChainStatesResponse, RpcCreateWalletResult, RpcDecodedPsbt, RpcDescriptorInfo, RpcFinalizePsbtResult, RpcImportDescriptorRequest, RpcImportDescriptorResult, RpcListUnspentEntry, RpcMempoolEntry, RpcMempoolInfo, RpcRawMempoolVerbose, RpcListDescriptorsResult, RpcLockedUnspent, RpcLoadTxOutSetResult, RpcLoadWalletResult, RpcNetworkInfo, RpcTestMempoolAcceptResult, RpcWalletInfo, RpcWalletCreateFundedPsbtResult, RpcWalletProcessPsbtResult, RpcTransaction, RpcWalletTransaction, RpcZmqNotification } from "./types.js";
+interface RpcRequestPayload {
+    readonly body: string;
+    readonly headers: Record<string, string>;
+}
+interface RpcResponsePayload {
+    readonly statusCode: number;
+    readonly bodyText: string;
+}
+interface RpcTransportOptions {
+    fetchImpl?: typeof fetch;
+    requestTimeoutMs?: number;
+    requestImpl?: (request: {
+        url: URL;
+        payload: RpcRequestPayload;
+    }) => Promise<RpcResponsePayload>;
+}
+export declare class BitcoinRpcClient {
+    #private;
+    constructor(url: string, cookieFile: string, options?: RpcTransportOptions);
+    call<T>(method: string, params?: unknown[]): Promise<T>;
+    callWallet<T>(walletName: string, method: string, params?: unknown[]): Promise<T>;
+    getBlockchainInfo(): Promise<RpcBlockchainInfo>;
+    getNetworkInfo(): Promise<RpcNetworkInfo>;
+    getBestBlockHash(): Promise<string>;
+    getBlockHash(height: number): Promise<string>;
+    getBlock(hashHex: string): Promise<RpcBlock>;
+    getChainStates(): Promise<RpcChainStatesResponse>;
+    loadTxOutSet(snapshotPath: string): Promise<RpcLoadTxOutSetResult>;
+    getZmqNotifications(): Promise<RpcZmqNotification[]>;
+    createWallet(walletName: string, options?: {
+        disablePrivateKeys?: boolean;
+        blank?: boolean;
+        passphrase?: string;
+        avoidReuse?: boolean;
+        descriptors?: boolean;
+        loadOnStartup?: boolean;
+    }): Promise<RpcCreateWalletResult>;
+    loadWallet(walletName: string, loadOnStartup?: boolean): Promise<RpcLoadWalletResult>;
+    unloadWallet(walletName: string, loadOnStartup?: boolean): Promise<null>;
+    listWallets(): Promise<string[]>;
+    getDescriptorInfo(descriptor: string): Promise<RpcDescriptorInfo>;
+    deriveAddresses(descriptor: string, range?: number | [number, number]): Promise<string[]>;
+    listDescriptors(walletName: string, privateOnly?: boolean): Promise<RpcListDescriptorsResult>;
+    importDescriptors(walletName: string, requests: RpcImportDescriptorRequest[]): Promise<RpcImportDescriptorResult[]>;
+    getWalletInfo(walletName: string): Promise<RpcWalletInfo>;
+    walletLock(walletName: string): Promise<null>;
+    walletPassphrase(walletName: string, passphrase: string, timeoutSeconds: number): Promise<null>;
+    walletProcessPsbt(walletName: string, psbt: string, sign?: boolean, sighashType?: string): Promise<RpcWalletProcessPsbtResult>;
+    listUnspent(walletName: string, minConf?: number): Promise<RpcListUnspentEntry[]>;
+    listLockUnspent(walletName: string): Promise<RpcLockedUnspent[]>;
+    lockUnspent(walletName: string, unlock: boolean, outputs: RpcLockedUnspent[]): Promise<boolean>;
+    walletCreateFundedPsbt(walletName: string, inputs: Array<{
+        txid: string;
+        vout: number;
+    }>, outputs: unknown[], locktime: number, options: Record<string, unknown>, bip32Derivs?: boolean): Promise<RpcWalletCreateFundedPsbtResult>;
+    decodePsbt(psbt: string): Promise<RpcDecodedPsbt>;
+    finalizePsbt(psbt: string, extract?: boolean): Promise<RpcFinalizePsbtResult>;
+    decodeRawTransaction(hex: string): Promise<RpcTransaction>;
+    testMempoolAccept(rawTransactions: string[]): Promise<RpcTestMempoolAcceptResult[]>;
+    sendRawTransaction(hex: string): Promise<string>;
+    getRawMempool(): Promise<string[]>;
+    getRawMempoolVerbose(): Promise<RpcRawMempoolVerbose>;
+    getMempoolInfo(): Promise<RpcMempoolInfo>;
+    getMempoolEntry(txid: string): Promise<RpcMempoolEntry>;
+    saveMempool(): Promise<null>;
+    getRawTransaction(txid: string, verbose?: boolean): Promise<RpcTransaction>;
+    getTransaction(walletName: string, txid: string): Promise<RpcWalletTransaction>;
+    stop(): Promise<string>;
+}
+export {};

package/dist/bitcoind/rpc.js

@@ -0,0 +1,322 @@
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { readFile } from "node:fs/promises";
+export class BitcoinRpcClient {
+    #url;
+    #cookieFile;
+    #fetchImpl;
+    #requestTimeoutMs;
+    #requestImpl;
+    constructor(url, cookieFile, options = {}) {
+        this.#url = url;
+        this.#cookieFile = cookieFile;
+        this.#fetchImpl = options.fetchImpl ?? fetch;
+        this.#requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
+        this.#requestImpl = options.requestImpl ?? this.#sendNodeRequest.bind(this);
+    }
+    async call(method, params = []) {
+        return this.#callAtUrl(this.#url, method, params);
+    }
+    async callWallet(walletName, method, params = []) {
+        const url = new URL(this.#url);
+        url.pathname = `${url.pathname.replace(/\/$/, "")}/wallet/${encodeURIComponent(walletName)}`;
+        return this.#callAtUrl(url.toString(), method, params);
+    }
+    async #callAtUrl(urlString, method, params = []) {
+        const payload = await this.#buildRequestPayload(method, params);
+        let response;
+        const abortSignal = AbortSignal.timeout(this.#requestTimeoutMs);
+        try {
+            response = await this.#fetchImpl(urlString, {
+                method: "POST",
+                headers: payload.headers,
+                body: payload.body,
+                signal: abortSignal,
+            });
+        }
+        catch (error) {
+            throw new Error(this.#describeTransportError(urlString, method, error), { cause: error });
+        }
+        return this.#parseResponse(method, response.status, await response.text());
+    }
+    async #buildRequestPayload(method, params) {
+        let cookie;
+        try {
+            cookie = (await readFile(this.#cookieFile, "utf8")).trim();
+        }
+        catch (error) {
+            throw new Error(this.#describeCookieReadError(method, error), { cause: error });
+        }
+        return {
+            headers: {
+                "content-type": "application/json",
+                authorization: `Basic ${Buffer.from(cookie).toString("base64")}`,
+            },
+            body: JSON.stringify({
+                jsonrpc: "1.0",
+                id: method,
+                method,
+                params,
+            }),
+        };
+    }
+    #parseResponse(method, statusCode, bodyText) {
+        let payload = null;
+        try {
+            payload = JSON.parse(bodyText);
+        }
+        catch (error) {
+            if (statusCode < 200 || statusCode >= 300) {
+                throw new Error(`bitcoind_rpc_http_${statusCode}`);
+            }
+            throw new Error(this.#describeInvalidResponseError(method), { cause: error });
+        }
+        if (payload?.error) {
+            throw new Error(`bitcoind_rpc_${method}_${payload.error.code}_${payload.error.message}`);
+        }
+        if (statusCode < 200 || statusCode >= 300) {
+            throw new Error(`bitcoind_rpc_http_${statusCode}`);
+        }
+        return payload.result;
+    }
+    #describeTransportError(urlString, method, error) {
+        const endpoint = new URL(urlString).host;
+        const detail = this.#extractErrorDetail(error);
+        if (detail === null) {
+            return `The managed Bitcoin RPC request to ${endpoint} for ${method} failed.`;
+        }
+        return `The managed Bitcoin RPC request to ${endpoint} for ${method} failed: ${detail}.`;
+    }
+    #describeInvalidResponseError(method) {
+        const endpoint = new URL(this.#url).host;
+        return `The managed Bitcoin RPC request to ${endpoint} for ${method} returned an invalid JSON response.`;
+    }
+    #describeCookieReadError(method, error) {
+        const detail = this.#extractErrorDetail(error);
+        if (this.#isMissingFileError(error)) {
+            return `The managed Bitcoin RPC cookie file is unavailable at ${this.#cookieFile} while preparing ${method}. The managed node is not running or is shutting down.`;
+        }
+        if (detail === null) {
+            return `The managed Bitcoin RPC cookie file could not be read at ${this.#cookieFile} while preparing ${method}.`;
+        }
+        return `The managed Bitcoin RPC cookie file could not be read at ${this.#cookieFile} while preparing ${method}: ${detail}.`;
+    }
+    #extractErrorDetail(error) {
+        const parts = [];
+        let current = error;
+        while (current instanceof Error) {
+            const message = current.message.trim();
+            if (message.length > 0 && message !== "fetch failed" && !parts.includes(message)) {
+                parts.push(message);
+            }
+            const next = current.cause;
+            if (next === undefined || next === current) {
+                break;
+            }
+            current = next;
+        }
+        return parts.length > 0 ? parts.join(" Caused by: ") : null;
+    }
+    #isMissingFileError(error) {
+        return error instanceof Error
+            && "code" in error
+            && error.code === "ENOENT";
+    }
+    async #callWithNodeRequest(method, params = []) {
+        const url = new URL(this.#url);
+        const payload = await this.#buildRequestPayload(method, params);
+        let response;
+        try {
+            response = await this.#requestImpl({ url, payload });
+        }
+        catch (error) {
+            throw new Error(this.#describeTransportError(this.#url, method, error), { cause: error });
+        }
+        return this.#parseResponse(method, response.statusCode, response.bodyText);
+    }
+    async #sendNodeRequest(request) {
+        const requester = request.url.protocol === "https:" ? httpsRequest : httpRequest;
+        const contentLength = Buffer.byteLength(request.payload.body);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (handler) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                handler();
+            };
+            const req = requester(request.url, {
+                method: "POST",
+                agent: false,
+                headers: {
+                    ...request.payload.headers,
+                    "content-length": String(contentLength),
+                },
+            }, (response) => {
+                const chunks = [];
+                response.on("data", (chunk) => {
+                    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                });
+                response.on("end", () => {
+                    finish(() => {
+                        resolve({
+                            statusCode: response.statusCode ?? 0,
+                            bodyText: Buffer.concat(chunks).toString("utf8"),
+                        });
+                    });
+                });
+                response.on("aborted", () => {
+                    finish(() => {
+                        reject(new Error("The managed Bitcoin RPC response was aborted."));
+                    });
+                });
+                response.on("error", (error) => {
+                    finish(() => {
+                        reject(error);
+                    });
+                });
+            });
+            req.setTimeout(this.#requestTimeoutMs);
+            req.on("socket", (socket) => {
+                socket.setTimeout(this.#requestTimeoutMs);
+            });
+            req.on("error", (error) => {
+                finish(() => {
+                    reject(error);
+                });
+            });
+            req.end(request.payload.body);
+        });
+    }
+    getBlockchainInfo() {
+        return this.call("getblockchaininfo");
+    }
+    getNetworkInfo() {
+        return this.call("getnetworkinfo");
+    }
+    getBestBlockHash() {
+        return this.call("getbestblockhash");
+    }
+    getBlockHash(height) {
+        return this.call("getblockhash", [height]);
+    }
+    getBlock(hashHex) {
+        return this.call("getblock", [hashHex, 3]);
+    }
+    getChainStates() {
+        return this.call("getchainstates");
+    }
+    loadTxOutSet(snapshotPath) {
+        return this.#callWithNodeRequest("loadtxoutset", [snapshotPath]);
+    }
+    getZmqNotifications() {
+        return this.call("getzmqnotifications");
+    }
+    createWallet(walletName, options = {}) {
+        return this.call("createwallet", [
+            walletName,
+            options.disablePrivateKeys ?? false,
+            options.blank ?? true,
+            options.passphrase ?? "",
+            options.avoidReuse ?? false,
+            options.descriptors ?? true,
+            options.loadOnStartup ?? true,
+        ]);
+    }
+    loadWallet(walletName, loadOnStartup = true) {
+        return this.call("loadwallet", [walletName, loadOnStartup]);
+    }
+    unloadWallet(walletName, loadOnStartup = true) {
+        return this.call("unloadwallet", [walletName, loadOnStartup]);
+    }
+    listWallets() {
+        return this.call("listwallets");
+    }
+    getDescriptorInfo(descriptor) {
+        return this.call("getdescriptorinfo", [descriptor]);
+    }
+    deriveAddresses(descriptor, range) {
+        const params = range === undefined ? [descriptor] : [descriptor, range];
+        return this.call("deriveaddresses", params);
+    }
+    listDescriptors(walletName, privateOnly = false) {
+        return this.callWallet(walletName, "listdescriptors", [privateOnly]);
+    }
+    importDescriptors(walletName, requests) {
+        return this.callWallet(walletName, "importdescriptors", [requests]);
+    }
+    getWalletInfo(walletName) {
+        return this.callWallet(walletName, "getwalletinfo");
+    }
+    walletLock(walletName) {
+        return this.callWallet(walletName, "walletlock");
+    }
+    walletPassphrase(walletName, passphrase, timeoutSeconds) {
+        return this.callWallet(walletName, "walletpassphrase", [passphrase, timeoutSeconds]);
+    }
+    walletProcessPsbt(walletName, psbt, sign = true, sighashType = "DEFAULT") {
+        return this.callWallet(walletName, "walletprocesspsbt", [
+            psbt,
+            sign,
+            sighashType,
+        ]);
+    }
+    listUnspent(walletName, minConf = 1) {
+        return this.callWallet(walletName, "listunspent", [minConf]);
+    }
+    listLockUnspent(walletName) {
+        return this.callWallet(walletName, "listlockunspent");
+    }
+    lockUnspent(walletName, unlock, outputs) {
+        return this.callWallet(walletName, "lockunspent", [unlock, outputs]);
+    }
+    walletCreateFundedPsbt(walletName, inputs, outputs, locktime, options, bip32Derivs = true) {
+        return this.callWallet(walletName, "walletcreatefundedpsbt", [
+            inputs,
+            outputs,
+            locktime,
+            options,
+            bip32Derivs,
+        ]);
+    }
+    decodePsbt(psbt) {
+        return this.call("decodepsbt", [psbt]);
+    }
+    finalizePsbt(psbt, extract = true) {
+        return this.call("finalizepsbt", [psbt, extract]);
+    }
+    decodeRawTransaction(hex) {
+        return this.call("decoderawtransaction", [hex]);
+    }
+    testMempoolAccept(rawTransactions) {
+        return this.call("testmempoolaccept", [rawTransactions]);
+    }
+    sendRawTransaction(hex) {
+        return this.call("sendrawtransaction", [hex]);
+    }
+    getRawMempool() {
+        return this.call("getrawmempool");
+    }
+    getRawMempoolVerbose() {
+        return this.call("getrawmempool", [false, true]);
+    }
+    getMempoolInfo() {
+        return this.call("getmempoolinfo");
+    }
+    getMempoolEntry(txid) {
+        return this.call("getmempoolentry", [txid]);
+    }
+    saveMempool() {
+        return this.call("savemempool");
+    }
+    getRawTransaction(txid, verbose = true) {
+        return this.call("getrawtransaction", [txid, verbose]);
+    }
+    getTransaction(walletName, txid) {
+        return this.callWallet(walletName, "gettransaction", [txid, true, true]);
+    }
+    stop() {
+        return this.call("stop");
+    }
+}

package/dist/bitcoind/service-paths.d.ts

@@ -0,0 +1,19 @@
+export declare const UNINITIALIZED_WALLET_ROOT_ID = "wallet-root-uninitialized";
+export interface ManagedServicePaths {
+    dataRoot: string;
+    runtimeRoot: string;
+    walletRuntimeRoot: string;
+    bitcoindLockPath: string;
+    bitcoindStatusPath: string;
+    bitcoindPidPath: string;
+    bitcoindReadyPath: string;
+    bitcoindRuntimeConfigPath: string;
+    bitcoindWalletStatusPath: string;
+    bitcoinConfPath: string;
+    indexerRoot: string;
+    indexerServiceRoot: string;
+    indexerDaemonLockPath: string;
+    indexerDaemonStatusPath: string;
+    indexerDaemonSocketPath: string;
+}
+export declare function resolveManagedServicePaths(dataDir: string, walletRootId?: string): ManagedServicePaths;

package/dist/bitcoind/service-paths.js

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+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);
+}
+function resolveIndexerDaemonSocketPath(serviceRootId) {
+    const socketId = createHash("sha256").update(serviceRootId).digest("hex").slice(0, 20);
+    if (process.platform === "win32") {
+        return `\\\\.\\pipe\\cogcoin-indexer-${socketId}`;
+    }
+    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;
+    const dataRoot = useDefaultRoots ? defaultPaths.dataRoot : dirname(dataDir);
+    const runtimeRoot = useDefaultRoots ? defaultPaths.runtimeRoot : join(dataRoot, "runtime");
+    const indexerRoot = useDefaultRoots ? defaultPaths.indexerRoot : join(dataRoot, "indexer");
+    const serviceRootId = useDefaultRoots
+        ? normalizedWalletRootId
+        : `${normalizedWalletRootId}-${createDataDirSuffix(dataDir)}`;
+    const walletRuntimeRoot = join(runtimeRoot, serviceRootId);
+    const indexerServiceRoot = join(indexerRoot, serviceRootId);
+    return {
+        dataRoot,
+        runtimeRoot,
+        walletRuntimeRoot,
+        bitcoindLockPath: join(walletRuntimeRoot, "bitcoind.lock"),
+        bitcoindStatusPath: join(walletRuntimeRoot, "bitcoind-status.json"),
+        bitcoindPidPath: join(walletRuntimeRoot, "bitcoind.pid"),
+        bitcoindReadyPath: join(walletRuntimeRoot, "bitcoind.ready"),
+        bitcoindRuntimeConfigPath: join(walletRuntimeRoot, "bitcoind-config.json"),
+        bitcoindWalletStatusPath: join(walletRuntimeRoot, "bitcoind-wallet.json"),
+        bitcoinConfPath: join(dataDir, "bitcoin.conf"),
+        indexerRoot,
+        indexerServiceRoot,
+        indexerDaemonLockPath: join(walletRuntimeRoot, "indexer-daemon.lock"),
+        indexerDaemonStatusPath: join(indexerServiceRoot, "status.json"),
+        indexerDaemonSocketPath: resolveIndexerDaemonSocketPath(serviceRootId),
+    };
+}

package/dist/bitcoind/service.d.ts

@@ -0,0 +1,40 @@
+import type { InternalManagedBitcoindOptions, ManagedBitcoindObservedStatus, ManagedBitcoindNodeHandle, ManagedCoreWalletReplicaStatus } from "./types.js";
+interface ManagedWalletReplicaRpc {
+    listWallets(): Promise<string[]>;
+    loadWallet(walletName: string, loadOnStartup?: boolean): Promise<{
+        name: string;
+        warning: string;
+    }>;
+    createWallet(walletName: string, options: {
+        blank: boolean;
+        descriptors: boolean;
+        disablePrivateKeys: boolean;
+        loadOnStartup: boolean;
+        passphrase: string;
+    }): Promise<unknown>;
+    getWalletInfo(walletName: string): Promise<{
+        descriptors: boolean;
+        private_keys_enabled: boolean;
+    }>;
+    walletLock(walletName: string): Promise<null>;
+}
+type ManagedBitcoindServiceOptions = Pick<InternalManagedBitcoindOptions, "dataDir" | "chain" | "startHeight" | "walletRootId" | "rpcPort" | "zmqPort" | "p2pPort" | "pollIntervalMs" | "startupTimeoutMs" | "shutdownTimeoutMs" | "managedWalletPassphrase">;
+export type ManagedBitcoindServiceCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "unreachable" | "protocol-error";
+export interface ManagedBitcoindServiceProbeResult {
+    compatibility: ManagedBitcoindServiceCompatibility;
+    status: ManagedBitcoindObservedStatus | null;
+    error: string | null;
+}
+export declare function createManagedWalletReplica(rpc: ManagedWalletReplicaRpc, walletRootId: string, options?: {
+    managedWalletPassphrase?: string;
+}): Promise<ManagedCoreWalletReplicaStatus>;
+export declare function probeManagedBitcoindService(options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindServiceProbeResult>;
+export declare function attachOrStartManagedBitcoindService(options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindNodeHandle>;
+export declare function readManagedBitcoindServiceStatusForTesting(dataDir: string, walletRootId?: string): Promise<ManagedBitcoindObservedStatus | null>;
+export declare function shutdownManagedBitcoindServiceForTesting(options: {
+    dataDir: string;
+    chain?: "main" | "regtest";
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+}): Promise<void>;
+export {};