@cogcoin/client 0.5.0

package/dist/wallet/read/context.js

@@ -0,0 +1,532 @@
+import { access, constants } from "node:fs/promises";
+import { deserializeIndexerState, loadBundledGenesisParameters } from "@cogcoin/indexer";
+import { attachOrStartIndexerDaemon, probeIndexerDaemon, readObservedIndexerDaemonStatus, readSnapshotWithRetry, } from "../../bitcoind/indexer-daemon.js";
+import { createRpcClient } from "../../bitcoind/node.js";
+import { UNINITIALIZED_WALLET_ROOT_ID } from "../../bitcoind/service-paths.js";
+import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, } from "../../bitcoind/service.js";
+import {} from "../../bitcoind/types.js";
+import { loadUnlockedWalletState, verifyManagedCoreWalletReplica, } from "../lifecycle.js";
+import { inspectMiningControlPlane } from "../mining/index.js";
+import { normalizeMiningStateRecord } from "../mining/state.js";
+import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
+import { loadWalletState } from "../state/storage.js";
+import { createDefaultWalletSecretProvider, } from "../state/provider.js";
+import { createWalletReadModel } from "./project.js";
+const DEFAULT_SERVICE_START_TIMEOUT_MS = 10_000;
+const STALE_HEARTBEAT_THRESHOLD_MS = 15_000;
+async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function inspectWalletLocalState(options = {}) {
+    const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
+    const now = options.now ?? Date.now();
+    const [hasPrimaryStateFile, hasBackupStateFile, hasUnlockSessionFile] = await Promise.all([
+        pathExists(paths.walletStatePath),
+        pathExists(paths.walletStateBackupPath),
+        pathExists(paths.walletUnlockSessionPath),
+    ]);
+    if (!hasPrimaryStateFile && !hasBackupStateFile) {
+        return {
+            availability: "uninitialized",
+            walletRootId: null,
+            state: null,
+            source: null,
+            unlockUntilUnixMs: null,
+            hasPrimaryStateFile,
+            hasBackupStateFile,
+            hasUnlockSessionFile,
+            message: "Wallet state has not been initialized yet.",
+        };
+    }
+    if (options.passphrase === undefined) {
+        try {
+            const provider = options.secretProvider ?? createDefaultWalletSecretProvider();
+            const unlocked = await loadUnlockedWalletState({
+                provider,
+                nowUnixMs: now,
+                paths,
+            });
+            if (unlocked === null) {
+                try {
+                    await loadWalletState({
+                        primaryPath: paths.walletStatePath,
+                        backupPath: paths.walletStateBackupPath,
+                    }, {
+                        provider,
+                    });
+                }
+                catch (error) {
+                    return {
+                        availability: "local-state-corrupt",
+                        walletRootId: null,
+                        state: null,
+                        source: null,
+                        unlockUntilUnixMs: null,
+                        hasPrimaryStateFile,
+                        hasBackupStateFile,
+                        hasUnlockSessionFile,
+                        message: error instanceof Error ? error.message : String(error),
+                    };
+                }
+                return {
+                    availability: "locked",
+                    walletRootId: null,
+                    state: null,
+                    source: null,
+                    unlockUntilUnixMs: null,
+                    hasPrimaryStateFile,
+                    hasBackupStateFile,
+                    hasUnlockSessionFile,
+                    message: hasUnlockSessionFile
+                        ? "Wallet state exists but the unlock session is expired, invalid, or belongs to a different wallet root."
+                        : "Wallet state exists but is currently locked.",
+                };
+            }
+            return {
+                availability: "ready",
+                walletRootId: unlocked.state.walletRootId,
+                state: {
+                    ...unlocked.state,
+                    miningState: normalizeMiningStateRecord(unlocked.state.miningState),
+                },
+                source: unlocked.source,
+                unlockUntilUnixMs: unlocked.session.unlockUntilUnixMs,
+                hasPrimaryStateFile,
+                hasBackupStateFile,
+                hasUnlockSessionFile,
+                message: null,
+            };
+        }
+        catch (error) {
+            return {
+                availability: "local-state-corrupt",
+                walletRootId: null,
+                state: null,
+                source: null,
+                unlockUntilUnixMs: null,
+                hasPrimaryStateFile,
+                hasBackupStateFile,
+                hasUnlockSessionFile,
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    try {
+        const loaded = await loadWalletState({
+            primaryPath: paths.walletStatePath,
+            backupPath: paths.walletStateBackupPath,
+        }, options.passphrase);
+        return {
+            availability: "ready",
+            walletRootId: loaded.state.walletRootId,
+            state: {
+                ...loaded.state,
+                miningState: normalizeMiningStateRecord(loaded.state.miningState),
+            },
+            source: loaded.source,
+            unlockUntilUnixMs: null,
+            hasPrimaryStateFile,
+            hasBackupStateFile,
+            hasUnlockSessionFile,
+            message: null,
+        };
+    }
+    catch (error) {
+        return {
+            availability: "local-state-corrupt",
+            walletRootId: null,
+            state: null,
+            source: null,
+            unlockUntilUnixMs: null,
+            hasPrimaryStateFile,
+            hasBackupStateFile,
+            hasUnlockSessionFile,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function mapIndexerStartupError(message) {
+    switch (message) {
+        case "indexer_daemon_start_timeout":
+            return {
+                health: "starting",
+                message: "Indexer daemon is still starting.",
+            };
+        case "indexer_daemon_service_version_mismatch":
+            return {
+                health: "service-version-mismatch",
+                message: "The live indexer daemon is running an incompatible service API version.",
+            };
+        case "indexer_daemon_schema_mismatch":
+            return {
+                health: "schema-mismatch",
+                message: "The live indexer daemon is using an incompatible sqlite schema.",
+            };
+        case "indexer_daemon_wallet_root_mismatch":
+            return {
+                health: "wallet-root-mismatch",
+                message: "The live indexer daemon belongs to a different wallet root.",
+            };
+        case "indexer_daemon_protocol_error":
+            return {
+                health: "unavailable",
+                message: "The live indexer daemon socket responded with an invalid or incomplete protocol exchange.",
+            };
+        default:
+            return {
+                health: "unavailable",
+                message,
+            };
+    }
+}
+function mapBitcoindStartupError(message) {
+    switch (message) {
+        case "managed_bitcoind_service_start_timeout":
+            return {
+                health: "starting",
+                status: null,
+                message: "Managed bitcoind service is still starting.",
+            };
+        case "managed_bitcoind_service_version_mismatch":
+            return {
+                health: "service-version-mismatch",
+                status: null,
+                message: "The live managed bitcoind service is running an incompatible service version.",
+            };
+        case "managed_bitcoind_wallet_root_mismatch":
+            return {
+                health: "wallet-root-mismatch",
+                status: null,
+                message: "The live managed bitcoind service belongs to a different wallet root.",
+            };
+        case "managed_bitcoind_runtime_mismatch":
+            return {
+                health: "runtime-mismatch",
+                status: null,
+                message: "The live managed bitcoind service runtime does not match this wallet's expected data directory or chain.",
+            };
+        case "managed_bitcoind_protocol_error":
+            return {
+                health: "unavailable",
+                status: null,
+                message: "The managed bitcoind runtime artifacts are invalid or incomplete.",
+            };
+        default:
+            return {
+                health: "unavailable",
+                status: null,
+                message,
+            };
+    }
+}
+function deriveBitcoindHealth(options) {
+    if (options.startupError !== null) {
+        const mapped = mapBitcoindStartupError(options.startupError);
+        return {
+            ...mapped,
+            status: options.status,
+        };
+    }
+    if (options.status === null) {
+        return {
+            health: "unavailable",
+            status: null,
+            message: "Managed bitcoind service is unavailable.",
+        };
+    }
+    if (options.status.state === "starting") {
+        return {
+            health: "starting",
+            status: options.status,
+            message: options.status.lastError ?? "Managed bitcoind service is still starting.",
+        };
+    }
+    if (options.status.state === "failed") {
+        return {
+            health: "failed",
+            status: options.status,
+            message: options.status.lastError ?? "Managed bitcoind service refresh failed.",
+        };
+    }
+    const proofStatus = options.nodeStatus?.walletReplica?.proofStatus;
+    if (proofStatus === "missing") {
+        return {
+            health: "replica-missing",
+            status: options.status,
+            message: options.nodeStatus?.walletReplicaMessage ?? "Managed Core wallet replica is missing.",
+        };
+    }
+    if (proofStatus === "mismatch") {
+        return {
+            health: "replica-mismatch",
+            status: options.status,
+            message: options.nodeStatus?.walletReplicaMessage ?? "Managed Core wallet replica does not match trusted wallet state.",
+        };
+    }
+    return {
+        health: "ready",
+        status: options.status,
+        message: options.nodeStatus?.walletReplicaMessage ?? options.status.lastError,
+    };
+}
+function deriveNodeHealth(status, bitcoindHealth) {
+    if (bitcoindHealth !== "ready" || status === null || !status.ready) {
+        return {
+            health: "unavailable",
+            message: "Bitcoin service is unavailable.",
+        };
+    }
+    if (status.nodeBestHeight !== null && status.nodeHeaderHeight !== null && status.nodeBestHeight < status.nodeHeaderHeight) {
+        return {
+            health: "catching-up",
+            message: "Bitcoin Core is still catching up to headers.",
+        };
+    }
+    return {
+        health: "synced",
+        message: null,
+    };
+}
+function deriveIndexerHealth(options) {
+    const daemonStatus = options.source === "lease"
+        ? options.daemonStatus
+        : options.observedStatus ?? options.daemonStatus;
+    const snapshotTip = options.snapshot?.tip ?? null;
+    const daemonInstanceId = options.snapshot?.daemonInstanceId ?? daemonStatus?.daemonInstanceId ?? null;
+    const snapshotSeq = options.snapshot?.snapshotSeq ?? daemonStatus?.snapshotSeq ?? null;
+    const openedAtUnixMs = options.snapshot?.openedAtUnixMs ?? null;
+    const source = daemonStatus === null && options.snapshot === null ? "none" : options.source;
+    const createResult = (health, message) => ({
+        health,
+        status: daemonStatus,
+        message,
+        snapshotTip,
+        source,
+        daemonInstanceId,
+        snapshotSeq,
+        openedAtUnixMs,
+    });
+    if (options.startupError !== null) {
+        const mapped = mapIndexerStartupError(options.startupError);
+        return createResult(mapped.health, mapped.message);
+    }
+    if (daemonStatus === null) {
+        return createResult("unavailable", "Indexer daemon is unavailable.");
+    }
+    if ((options.now - daemonStatus.heartbeatAtUnixMs) > STALE_HEARTBEAT_THRESHOLD_MS) {
+        return createResult("stale-heartbeat", "Indexer daemon heartbeat is stale.");
+    }
+    if (daemonStatus.state === "schema-mismatch") {
+        return createResult("schema-mismatch", daemonStatus.lastError ?? "Indexer daemon sqlite schema is incompatible.");
+    }
+    if (daemonStatus.state === "failed") {
+        return createResult("failed", daemonStatus.lastError ?? "Indexer daemon refresh failed.");
+    }
+    if (daemonStatus.state === "service-version-mismatch") {
+        return createResult("service-version-mismatch", "Indexer daemon service API is incompatible.");
+    }
+    if (options.snapshot === null) {
+        if (daemonStatus.state === "reorging") {
+            return createResult("reorging", "Indexer daemon is replaying a reorg and refreshing the coherent snapshot.");
+        }
+        return createResult(daemonStatus.state === "catching-up" ? "catching-up" : "starting", "Indexer snapshot is not ready yet.");
+    }
+    if (daemonStatus.state === "catching-up") {
+        return createResult("catching-up", "Indexer daemon is still catching up to the managed Bitcoin tip.");
+    }
+    if (daemonStatus.state === "reorging") {
+        return createResult("reorging", "Indexer daemon is replaying a reorg and refreshing the coherent snapshot.");
+    }
+    return createResult("synced", null);
+}
+async function attachNodeStatus(options) {
+    try {
+        const probe = await probeManagedBitcoindService({
+            dataDir: options.dataDir,
+            chain: "main",
+            startHeight: 0,
+            walletRootId: options.walletRootId,
+            startupTimeoutMs: options.startupTimeoutMs,
+        });
+        if (probe.compatibility !== "compatible" && probe.compatibility !== "unreachable") {
+            return {
+                handle: null,
+                status: null,
+                observedStatus: probe.status,
+                error: probe.error,
+            };
+        }
+        const genesis = await loadBundledGenesisParameters();
+        const handle = await attachOrStartManagedBitcoindService({
+            dataDir: options.dataDir,
+            chain: "main",
+            startHeight: genesis.genesisBlock,
+            walletRootId: options.walletRootId,
+            startupTimeoutMs: options.startupTimeoutMs,
+        });
+        const rpc = createRpcClient(handle.rpc);
+        const [chainInfo, serviceStatus] = await Promise.all([
+            rpc.getBlockchainInfo(),
+            handle.refreshServiceStatus?.(),
+        ]);
+        const status = {
+            ready: true,
+            chain: chainInfo.chain,
+            pid: handle.pid,
+            walletRootId: handle.walletRootId ?? null,
+            nodeBestHeight: chainInfo.blocks,
+            nodeBestHashHex: chainInfo.bestblockhash,
+            nodeHeaderHeight: chainInfo.headers,
+            serviceUpdatedAtUnixMs: serviceStatus?.updatedAtUnixMs ?? null,
+            serviceStatus: serviceStatus ?? null,
+            walletReplica: serviceStatus?.walletReplica ?? null,
+            walletReplicaMessage: serviceStatus?.walletReplica?.message ?? null,
+        };
+        return {
+            handle,
+            status,
+            observedStatus: serviceStatus ?? null,
+            error: null,
+        };
+    }
+    catch (error) {
+        return {
+            handle: null,
+            status: null,
+            observedStatus: null,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function openWalletReadContext(options) {
+    const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_SERVICE_START_TIMEOUT_MS;
+    const now = options.now ?? Date.now();
+    const localState = await inspectWalletLocalState({
+        passphrase: options.walletStatePassphrase,
+        secretProvider: options.secretProvider,
+        now,
+        paths: options.paths,
+    });
+    const walletRootId = localState.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const node = await attachNodeStatus({
+        dataDir: options.dataDir,
+        walletRootId,
+        startupTimeoutMs,
+    });
+    if (localState.state !== null && node.status !== null) {
+        const verifiedReplica = await verifyManagedCoreWalletReplica(localState.state, options.dataDir, {
+            nodeHandle: node.handle ?? undefined,
+        });
+        node.status = {
+            ...node.status,
+            walletReplica: verifiedReplica,
+            walletReplicaMessage: verifiedReplica.message ?? null,
+        };
+    }
+    const bitcoind = deriveBitcoindHealth({
+        status: node.observedStatus,
+        nodeStatus: node.status,
+        startupError: node.error,
+    });
+    const nodeDerived = deriveNodeHealth(node.status, bitcoind.health);
+    let daemonClient = null;
+    let daemonStatus = null;
+    let observedDaemonStatus = null;
+    let snapshot = null;
+    let indexerSource = "none";
+    let daemonError = null;
+    try {
+        const probe = await probeIndexerDaemon({
+            dataDir: options.dataDir,
+            walletRootId,
+        });
+        if (probe.compatibility === "compatible") {
+            daemonClient = probe.client;
+            observedDaemonStatus = probe.status;
+            indexerSource = "probe";
+        }
+        else if (probe.compatibility === "unreachable") {
+            daemonClient = await attachOrStartIndexerDaemon({
+                dataDir: options.dataDir,
+                databasePath: options.databasePath,
+                walletRootId,
+                startupTimeoutMs,
+            });
+        }
+        else {
+            observedDaemonStatus = probe.status;
+            indexerSource = probe.status === null ? "none" : "probe";
+            daemonError = probe.error;
+        }
+        if (daemonClient !== null) {
+            const lease = await readSnapshotWithRetry(daemonClient, walletRootId);
+            daemonStatus = lease.status;
+            observedDaemonStatus = lease.status;
+            snapshot = {
+                tip: lease.payload.tip,
+                state: deserializeIndexerState(Buffer.from(lease.payload.stateBase64, "base64")),
+                source: "lease",
+                daemonInstanceId: lease.payload.daemonInstanceId,
+                snapshotSeq: lease.payload.snapshotSeq,
+                openedAtUnixMs: lease.payload.openedAtUnixMs,
+            };
+            indexerSource = "lease";
+        }
+    }
+    catch (error) {
+        daemonError = error instanceof Error ? error.message : String(error);
+        if (observedDaemonStatus === null) {
+            observedDaemonStatus = await readObservedIndexerDaemonStatus({
+                dataDir: options.dataDir,
+                walletRootId,
+            }).catch(() => null);
+            if (observedDaemonStatus !== null) {
+                indexerSource = "status-file";
+            }
+        }
+    }
+    const indexer = deriveIndexerHealth({
+        daemonStatus,
+        observedStatus: observedDaemonStatus,
+        snapshot,
+        source: indexerSource,
+        now,
+        startupError: daemonError,
+    });
+    const mining = await inspectMiningControlPlane({
+        provider: options.secretProvider,
+        localState,
+        bitcoind,
+        nodeStatus: node.status,
+        nodeHealth: nodeDerived.health,
+        indexer,
+        nowUnixMs: now,
+        paths: options.paths,
+    });
+    return {
+        dataDir: options.dataDir,
+        databasePath: options.databasePath,
+        localState,
+        bitcoind,
+        nodeStatus: node.status,
+        nodeHealth: nodeDerived.health,
+        nodeMessage: nodeDerived.message,
+        indexer,
+        snapshot,
+        model: localState.state === null
+            ? null
+            : createWalletReadModel(localState.state, snapshot),
+        mining,
+        async close() {
+            await daemonClient?.close().catch(() => undefined);
+            await node.handle?.stop().catch(() => undefined);
+        },
+    };
+}
+export { inspectWalletLocalState, readSnapshotWithRetry, };

package/dist/wallet/read/filter.d.ts

@@ -0,0 +1,9 @@
+import type { WalletDomainView, WalletReadContext } from "./types.js";
+export interface WalletDomainFilterOptions {
+    anchoredOnly: boolean;
+    listedOnly: boolean;
+    mineableOnly: boolean;
+}
+export declare function isRootDomainName(name: string): boolean;
+export declare function isMineableWalletDomain(context: WalletReadContext, domain: WalletDomainView): boolean;
+export declare function filterWalletDomains(context: WalletReadContext, options: WalletDomainFilterOptions): WalletDomainView[] | null;

package/dist/wallet/read/filter.js

@@ -0,0 +1,42 @@
+import { lookupDomain } from "@cogcoin/indexer/queries";
+export function isRootDomainName(name) {
+    return !name.includes("-");
+}
+export function isMineableWalletDomain(context, domain) {
+    const state = context.localState.state;
+    const model = context.model;
+    const snapshot = context.snapshot;
+    if (state === null || model === null || snapshot === null) {
+        return false;
+    }
+    if (!isRootDomainName(domain.name) || domain.anchored !== true || domain.readOnly || domain.ownerLocalIndex === null || domain.domainId === null) {
+        return false;
+    }
+    const localRecord = state.domains.find((entry) => entry.name === domain.name);
+    const ownerIdentity = model.identities.find((identity) => identity.index === domain.ownerLocalIndex);
+    if (localRecord?.currentCanonicalAnchorOutpoint === null
+        || localRecord?.currentCanonicalAnchorOutpoint === undefined
+        || ownerIdentity?.address == null
+        || ownerIdentity.readOnly) {
+        return false;
+    }
+    const chainDomain = lookupDomain(snapshot.state, domain.name);
+    return chainDomain !== null && chainDomain.anchored;
+}
+export function filterWalletDomains(context, options) {
+    if (context.model === null) {
+        return null;
+    }
+    return context.model.domains.filter((domain) => {
+        if (options.anchoredOnly && domain.anchored !== true) {
+            return false;
+        }
+        if (options.listedOnly && domain.listingPriceCogtoshi === null) {
+            return false;
+        }
+        if (options.mineableOnly && !isMineableWalletDomain(context, domain)) {
+            return false;
+        }
+        return true;
+    });
+}

package/dist/wallet/read/index.d.ts

@@ -0,0 +1,4 @@
+export { openWalletReadContext, inspectWalletLocalState, readSnapshotWithRetry } from "./context.js";
+export { filterWalletDomains, isMineableWalletDomain, isRootDomainName, type WalletDomainFilterOptions, } from "./filter.js";
+export { createFieldPreview, createWalletReadModel, findDomainField, findWalletLock, findWalletDomain, formatFieldFormat, listDomainFields, listWalletLocks, } from "./project.js";
+export type { WalletBitcoindStatus, WalletDomainDetailsView, WalletDomainView, WalletFieldView, WalletIdentityView, WalletIndexerStatus, WalletLocalStateStatus, WalletLockView, WalletNodeStatus, WalletReadContext, WalletReadModel, WalletServiceHealth, WalletSnapshotView, WalletStateAvailability, } from "./types.js";

package/dist/wallet/read/index.js

@@ -0,0 +1,3 @@
+export { openWalletReadContext, inspectWalletLocalState, readSnapshotWithRetry } from "./context.js";
+export { filterWalletDomains, isMineableWalletDomain, isRootDomainName, } from "./filter.js";
+export { createFieldPreview, createWalletReadModel, findDomainField, findWalletLock, findWalletDomain, formatFieldFormat, listDomainFields, listWalletLocks, } from "./project.js";

package/dist/wallet/read/project.d.ts

@@ -0,0 +1,11 @@
+import { getLock } from "@cogcoin/indexer/queries";
+import type { WalletDomainDetailsView, WalletFieldView, WalletLockView, WalletReadContext, WalletReadModel, WalletSnapshotView } from "./types.js";
+import type { WalletStateV1 } from "../types.js";
+export declare function createWalletReadModel(walletState: WalletStateV1, snapshot: WalletSnapshotView | null): WalletReadModel;
+export declare function listWalletLocks(context: WalletReadContext): WalletLockView[] | null;
+export declare function findWalletLock(context: WalletReadContext, lockId: number): ReturnType<typeof getLock>;
+export declare function findWalletDomain(context: WalletReadContext, name: string): WalletDomainDetailsView | null;
+export declare function listDomainFields(context: WalletReadContext, name: string): WalletFieldView[] | null;
+export declare function findDomainField(context: WalletReadContext, domainName: string, fieldName: string): WalletFieldView | null;
+export declare function createFieldPreview(value: Uint8Array, format: number): string;
+export declare function formatFieldFormat(format: number | null): string;