@cogcoin/client 0.5.0

package/dist/cli/workflow-hints.js

@@ -0,0 +1,94 @@
+function isRootDomainName(domainName) {
+    return !domainName.includes("-");
+}
+export function formatNextStepLines(nextSteps) {
+    return nextSteps.map((step) => `Next step: ${step}`);
+}
+export function getFundingQuickstartGuidance() {
+    return "Fund this wallet with about 0.0015 BTC so you can buy a 6+ character domain to start mining and still keep BTC available for mining transaction fees.";
+}
+export function getInitNextSteps() {
+    return ["cogcoin sync", "cogcoin address"];
+}
+function blocksSyncBootstrap(context) {
+    return context.bitcoind.health === "service-version-mismatch"
+        || context.bitcoind.health === "wallet-root-mismatch"
+        || context.bitcoind.health === "runtime-mismatch"
+        || context.bitcoind.health === "replica-missing"
+        || context.bitcoind.health === "replica-mismatch"
+        || context.bitcoind.health === "failed"
+        || context.indexer.health === "schema-mismatch"
+        || context.indexer.health === "service-version-mismatch"
+        || context.indexer.health === "wallet-root-mismatch"
+        || context.indexer.health === "failed";
+}
+export function getBootstrapSyncNextStep(context) {
+    if (blocksSyncBootstrap(context)) {
+        return null;
+    }
+    return context.bitcoind.health !== "ready"
+        || context.indexer.health !== "synced"
+        || context.nodeHealth !== "synced"
+        ? "cogcoin sync"
+        : null;
+}
+export function getRegisterNextSteps(domainName, registerKind) {
+    return registerKind === "root"
+        ? [
+            `cogcoin show ${domainName}`,
+            `cogcoin anchor ${domainName} once it confirms`,
+        ]
+        : [`cogcoin show ${domainName}`];
+}
+export function getAnchorNextSteps(domainName) {
+    const nextSteps = [`cogcoin show ${domainName}`];
+    if (isRootDomainName(domainName)) {
+        nextSteps.push("cogcoin mine", "cogcoin mine start");
+    }
+    return nextSteps;
+}
+export function getHooksEnableMiningNextSteps() {
+    return ["cogcoin mine", "cogcoin mine start"];
+}
+export function getMineSetupNextSteps() {
+    return ["cogcoin mine", "cogcoin mine start"];
+}
+export function getMineStopNextSteps() {
+    return ["cogcoin mine log"];
+}
+export function getAddressNextSteps(context, address) {
+    if (address === null || address === undefined || address.length === 0) {
+        return [];
+    }
+    const nextSteps = [];
+    const bootstrapSync = getBootstrapSyncNextStep(context);
+    if (bootstrapSync !== null) {
+        nextSteps.push(bootstrapSync);
+    }
+    nextSteps.push("fund this wallet, then run cogcoin status");
+    return nextSteps;
+}
+export function getIdsNextSteps(identities) {
+    return identities === null || identities === undefined || identities.length === 0
+        ? []
+        : [
+            "cogcoin register <root> --from <selector>",
+            "cogcoin send ... --from <selector>",
+            "cogcoin cog lock ... --from <selector>",
+        ];
+}
+export function getLocksNextSteps(locks) {
+    if (locks === null || locks === undefined || locks.length === 0) {
+        return [];
+    }
+    const nextSteps = [];
+    const claimable = locks.find((lock) => lock.claimableNow);
+    const reclaimable = locks.find((lock) => lock.reclaimableNow);
+    if (claimable !== undefined) {
+        nextSteps.push(`cogcoin claim ${claimable.lockId} --preimage <32-byte-hex>`);
+    }
+    if (reclaimable !== undefined) {
+        nextSteps.push(`cogcoin reclaim ${reclaimable.lockId}`);
+    }
+    return nextSteps;
+}

package/dist/cli-runner.d.ts

@@ -0,0 +1,3 @@
+export { runCli } from "./cli/runner.js";
+export { parseCliArgs } from "./cli/parse.js";
+export { formatStatusReport } from "./cli/status-format.js";

package/dist/cli-runner.js

@@ -0,0 +1,3 @@
+export { runCli } from "./cli/runner.js";
+export { parseCliArgs } from "./cli/parse.js";
+export { formatStatusReport } from "./cli/status-format.js";

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from "./cli-runner.js";
+const exitCode = await runCli(process.argv.slice(2));
+if (exitCode !== 0) {
+    process.exitCode = exitCode;
+}

package/dist/client/default-client.d.ts

@@ -0,0 +1,11 @@
+import type { BitcoinBlock, GenesisParameters, IndexerState } from "@cogcoin/indexer/types";
+import type { ApplyBlockResult, Client, ClientStoreAdapter, ClientTip } from "../types.js";
+export declare class DefaultClient implements Client {
+    #private;
+    constructor(store: ClientStoreAdapter, genesisParameters: GenesisParameters, state: IndexerState, tip: ClientTip | null, snapshotInterval: number);
+    getTip(): Promise<ClientTip | null>;
+    getState(): Promise<IndexerState>;
+    applyBlock(block: BitcoinBlock): Promise<ApplyBlockResult>;
+    rewindToHeight(height: number): Promise<ClientTip | null>;
+    close(): Promise<void>;
+}

package/dist/client/default-client.js

@@ -0,0 +1,118 @@
+import { applyBlockWithScoring, deserializeBlockRecord, rewindBlock, serializeIndexerState, } from "@cogcoin/indexer";
+import { createCheckpoint, createStoredBlockRecord, createTip } from "./persistence.js";
+export class DefaultClient {
+    #store;
+    #genesisParameters;
+    #snapshotInterval;
+    #state;
+    #tip;
+    #closed = false;
+    #queue = Promise.resolve();
+    constructor(store, genesisParameters, state, tip, snapshotInterval) {
+        this.#store = store;
+        this.#genesisParameters = genesisParameters;
+        this.#state = state;
+        this.#tip = tip;
+        this.#snapshotInterval = snapshotInterval;
+    }
+    async getTip() {
+        await this.#queue;
+        return this.#tip === null ? null : { ...this.#tip };
+    }
+    async getState() {
+        await this.#queue;
+        return this.#state;
+    }
+    async applyBlock(block) {
+        return this.#enqueue(async () => {
+            this.#assertOpen();
+            const applied = await applyBlockWithScoring(this.#state, block, this.#genesisParameters);
+            const tip = createTip(block, applied.stateHashHex);
+            const stateBytes = serializeIndexerState(applied.state);
+            const createdAt = Date.now();
+            const checkpoint = this.#shouldCheckpoint(block.height)
+                ? createCheckpoint(tip, stateBytes, createdAt)
+                : null;
+            const writeEntry = {
+                tip,
+                stateBytes,
+                blockRecord: createStoredBlockRecord(applied.blockRecord, createdAt),
+                checkpoint,
+                deleteAboveHeight: null,
+            };
+            await this.#store.writeAppliedBlock(writeEntry);
+            this.#state = applied.state;
+            this.#tip = tip;
+            return {
+                tip,
+                checkpoint,
+                applied,
+            };
+        });
+    }
+    async rewindToHeight(height) {
+        return this.#enqueue(async () => {
+            this.#assertOpen();
+            if (this.#tip === null) {
+                return null;
+            }
+            if (height >= this.#tip.height) {
+                return { ...this.#tip };
+            }
+            let nextState = this.#state;
+            let nextTip = this.#tip;
+            while (nextTip !== null && nextTip.height > height) {
+                const storedRecord = await this.#store.loadBlockRecord(nextTip.height);
+                if (storedRecord === null) {
+                    throw new Error(`client_store_missing_block_record_${nextTip.height}`);
+                }
+                nextState = rewindBlock(nextState, deserializeBlockRecord(storedRecord.recordBytes));
+                const currentHeight = nextState.history.currentHeight;
+                if (currentHeight === null) {
+                    nextTip = null;
+                    continue;
+                }
+                const currentRecord = await this.#store.loadBlockRecord(currentHeight);
+                nextTip = {
+                    height: currentHeight,
+                    blockHashHex: nextState.history.currentHashHex ?? currentRecord?.blockHashHex ?? "",
+                    previousHashHex: currentRecord?.previousHashHex ?? null,
+                    stateHashHex: nextState.history.stateHashByHeight.get(currentHeight) ?? null,
+                };
+            }
+            const stateBytes = nextTip === null ? null : serializeIndexerState(nextState);
+            await this.#store.writeAppliedBlock({
+                tip: nextTip,
+                stateBytes,
+                blockRecord: null,
+                checkpoint: null,
+                deleteAboveHeight: height,
+            });
+            this.#state = nextState;
+            this.#tip = nextTip;
+            return nextTip === null ? null : { ...nextTip };
+        });
+    }
+    async close() {
+        await this.#enqueue(async () => {
+            if (this.#closed) {
+                return;
+            }
+            this.#closed = true;
+            await this.#store.close();
+        });
+    }
+    #assertOpen() {
+        if (this.#closed) {
+            throw new Error("client_closed");
+        }
+    }
+    #shouldCheckpoint(height) {
+        return this.#snapshotInterval > 0 && height % this.#snapshotInterval === 0;
+    }
+    #enqueue(operation) {
+        const next = this.#queue.then(operation, operation);
+        this.#queue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+}

package/dist/client/factory.d.ts

@@ -0,0 +1,2 @@
+import type { Client, ClientOptions } from "../types.js";
+export declare function openClient(options: ClientOptions): Promise<Client>;

package/dist/client/factory.js

@@ -0,0 +1,15 @@
+import { loadBundledGenesisParameters } from "@cogcoin/indexer";
+import { DefaultClient } from "./default-client.js";
+import { initializeState } from "./initialization.js";
+import { createClientStoreAdapter } from "./store-adapter.js";
+const DEFAULT_SNAPSHOT_INTERVAL = 1000;
+export async function openClient(options) {
+    const store = createClientStoreAdapter(options.store);
+    const genesisParameters = options.genesisParameters ?? await loadBundledGenesisParameters();
+    const snapshotInterval = options.snapshotInterval ?? DEFAULT_SNAPSHOT_INTERVAL;
+    if (!Number.isInteger(snapshotInterval) || snapshotInterval < 1) {
+        throw new RangeError("client_snapshot_interval_invalid");
+    }
+    const { state, tip } = await initializeState(store, genesisParameters);
+    return new DefaultClient(store, genesisParameters, state, tip, snapshotInterval);
+}

package/dist/client/initialization.d.ts

@@ -0,0 +1,6 @@
+import type { GenesisParameters, IndexerState } from "@cogcoin/indexer/types";
+import type { ClientStoreAdapter, ClientTip } from "../types.js";
+export declare function initializeState(store: ClientStoreAdapter, genesisParameters: GenesisParameters): Promise<{
+    state: IndexerState;
+    tip: ClientTip | null;
+}>;

package/dist/client/initialization.js

@@ -0,0 +1,30 @@
+import { createInitialState, deserializeIndexerState, } from "@cogcoin/indexer";
+export async function initializeState(store, genesisParameters) {
+    const tip = await store.loadTip();
+    const snapshot = await store.loadLatestSnapshot();
+    if (snapshot === null) {
+        if (tip !== null) {
+            throw new Error("client_store_tip_without_snapshot");
+        }
+        return {
+            state: createInitialState(genesisParameters),
+            tip: null,
+        };
+    }
+    const state = deserializeIndexerState(snapshot.stateBytes);
+    if (tip === null) {
+        return {
+            state,
+            tip: {
+                height: snapshot.height,
+                blockHashHex: snapshot.blockHashHex,
+                previousHashHex: null,
+                stateHashHex: state.history.stateHashByHeight.get(snapshot.height) ?? null,
+            },
+        };
+    }
+    if (tip.height !== snapshot.height || tip.blockHashHex !== snapshot.blockHashHex) {
+        throw new Error("client_store_snapshot_tip_mismatch");
+    }
+    return { state, tip };
+}

package/dist/client/persistence.d.ts

@@ -0,0 +1,5 @@
+import type { BitcoinBlock, BlockRecord } from "@cogcoin/indexer/types";
+import type { ClientCheckpoint, ClientTip, StoredBlockRecord } from "../types.js";
+export declare function createTip(block: BitcoinBlock, stateHashHex: string | null): ClientTip;
+export declare function createStoredBlockRecord(blockRecord: BlockRecord, createdAt: number): StoredBlockRecord;
+export declare function createCheckpoint(tip: ClientTip, stateBytes: Uint8Array, createdAt: number): ClientCheckpoint;

package/dist/client/persistence.js

@@ -0,0 +1,28 @@
+import { serializeBlockRecord } from "@cogcoin/indexer";
+import { bytesToHex } from "../bytes.js";
+export function createTip(block, stateHashHex) {
+    return {
+        height: block.height,
+        blockHashHex: bytesToHex(block.hash),
+        previousHashHex: block.previousHash === null ? null : bytesToHex(block.previousHash),
+        stateHashHex,
+    };
+}
+export function createStoredBlockRecord(blockRecord, createdAt) {
+    return {
+        height: blockRecord.height,
+        blockHashHex: blockRecord.hashHex,
+        previousHashHex: blockRecord.previousHashHex,
+        stateHashHex: blockRecord.stateHashHex,
+        recordBytes: serializeBlockRecord(blockRecord),
+        createdAt,
+    };
+}
+export function createCheckpoint(tip, stateBytes, createdAt) {
+    return {
+        height: tip.height,
+        blockHashHex: tip.blockHashHex,
+        stateBytes,
+        createdAt,
+    };
+}

package/dist/client/store-adapter.d.ts

@@ -0,0 +1,3 @@
+import type { ClientStoreAdapter } from "../types.js";
+export declare function assertClientStoreAdapter(store: ClientStoreAdapter): ClientStoreAdapter;
+export declare function createClientStoreAdapter(store: ClientStoreAdapter): ClientStoreAdapter;

package/dist/client/store-adapter.js

@@ -0,0 +1,20 @@
+export function assertClientStoreAdapter(store) {
+    const requiredMethods = [
+        "loadTip",
+        "loadLatestSnapshot",
+        "loadBlockRecordsAfter",
+        "writeAppliedBlock",
+        "deleteBlockRecordsAbove",
+        "loadBlockRecord",
+        "close",
+    ];
+    for (const method of requiredMethods) {
+        if (typeof store[method] !== "function") {
+            throw new TypeError(`client_store_adapter_missing_${String(method)}`);
+        }
+    }
+    return store;
+}
+export function createClientStoreAdapter(store) {
+    return assertClientStoreAdapter(store);
+}

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+export { createClientStoreAdapter } from "./client/store-adapter.js";
+export { openClient } from "./client/factory.js";

package/dist/client.js

@@ -0,0 +1,2 @@
+export { createClientStoreAdapter } from "./client/store-adapter.js";
+export { openClient } from "./client/factory.js";

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createClientStoreAdapter, openClient } from "./client.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { createClientStoreAdapter, openClient } from "./client.js";

package/dist/passive-status.d.ts

@@ -0,0 +1,36 @@
+interface PassiveTipStatus {
+    height: number;
+    blockHashHex: string;
+    previousHashHex: string | null;
+    stateHashHex: string | null;
+    updatedAt: number;
+}
+interface PassiveCheckpointStatus {
+    height: number;
+    blockHashHex: string;
+    createdAt: number;
+}
+interface PassiveBootstrapStatus {
+    phase: string;
+    downloadedBytes: number;
+    totalBytes: number;
+    validated: boolean;
+    loadTxOutSetComplete: boolean;
+    baseHeight: number | null;
+    tipHashHex: string | null;
+    lastError: string | null;
+    snapshotHeight: number | null;
+    updatedAt: number | null;
+}
+export interface PassiveClientStatus {
+    dbPath: string;
+    bitcoinDataDir: string;
+    storeInitialized: boolean;
+    storeExists: boolean;
+    indexedTip: PassiveTipStatus | null;
+    latestCheckpoint: PassiveCheckpointStatus | null;
+    bootstrap: PassiveBootstrapStatus | null;
+    storeError: string | null;
+}
+export declare function inspectPassiveClientStatus(dbPath: string, bitcoinDataDir: string): Promise<PassiveClientStatus>;
+export {};

package/dist/passive-status.js

@@ -0,0 +1,100 @@
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { openReadonlySqliteDatabase } from "./sqlite/driver.js";
+import { loadLatestCheckpoint } from "./sqlite/checkpoints.js";
+import { loadTipMeta } from "./sqlite/tip-meta.js";
+function fileExists(path) {
+    return stat(path).then(() => true, () => false);
+}
+function readBootstrapState(raw) {
+    const parsed = JSON.parse(raw);
+    return {
+        phase: parsed.phase ?? "unknown",
+        downloadedBytes: parsed.downloadedBytes ?? 0,
+        totalBytes: parsed.snapshot?.sizeBytes ?? 0,
+        validated: parsed.validated ?? false,
+        loadTxOutSetComplete: parsed.loadTxOutSetComplete ?? false,
+        baseHeight: parsed.baseHeight ?? null,
+        tipHashHex: parsed.tipHashHex ?? null,
+        lastError: parsed.lastError ?? null,
+        snapshotHeight: parsed.snapshot?.height ?? null,
+        updatedAt: parsed.updatedAt ?? null,
+    };
+}
+async function inspectSqliteStore(dbPath) {
+    const database = await openReadonlySqliteDatabase(dbPath);
+    try {
+        const indexedTipMeta = await loadTipMeta(database);
+        const checkpointRow = await loadLatestCheckpoint(database);
+        return {
+            storeInitialized: true,
+            indexedTip: indexedTipMeta === null
+                ? null
+                : {
+                    height: indexedTipMeta.tip.height,
+                    blockHashHex: indexedTipMeta.tip.blockHashHex,
+                    previousHashHex: indexedTipMeta.tip.previousHashHex,
+                    stateHashHex: indexedTipMeta.tip.stateHashHex,
+                    updatedAt: indexedTipMeta.updatedAt,
+                },
+            latestCheckpoint: checkpointRow === null
+                ? null
+                : {
+                    height: checkpointRow.height,
+                    blockHashHex: checkpointRow.blockHashHex,
+                    createdAt: checkpointRow.createdAt,
+                },
+        };
+    }
+    finally {
+        await database.close();
+    }
+}
+export async function inspectPassiveClientStatus(dbPath, bitcoinDataDir) {
+    const storeExists = await fileExists(dbPath);
+    const bootstrapPath = join(bitcoinDataDir, "bootstrap", "state.json");
+    let bootstrap = null;
+    try {
+        bootstrap = readBootstrapState(await readFile(bootstrapPath, "utf8"));
+    }
+    catch {
+        bootstrap = null;
+    }
+    if (!storeExists) {
+        return {
+            dbPath,
+            bitcoinDataDir,
+            storeInitialized: false,
+            storeExists: false,
+            indexedTip: null,
+            latestCheckpoint: null,
+            bootstrap,
+            storeError: null,
+        };
+    }
+    try {
+        const store = await inspectSqliteStore(dbPath);
+        return {
+            dbPath,
+            bitcoinDataDir,
+            storeInitialized: store.storeInitialized,
+            storeExists: true,
+            indexedTip: store.indexedTip,
+            latestCheckpoint: store.latestCheckpoint,
+            bootstrap,
+            storeError: null,
+        };
+    }
+    catch (error) {
+        return {
+            dbPath,
+            bitcoinDataDir,
+            storeInitialized: false,
+            storeExists: true,
+            indexedTip: null,
+            latestCheckpoint: null,
+            bootstrap,
+            storeError: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/sqlite/better-sqlite3.d.ts

@@ -0,0 +1,26 @@
+type BetterSqliteValue = bigint | Buffer | number | string | null;
+export interface BetterSqliteRow {
+    [key: string]: unknown;
+}
+export interface BetterSqliteStatement {
+    run(...params: BetterSqliteValue[]): {
+        changes: bigint | number;
+        lastInsertRowid: bigint | number;
+    };
+    get(...params: BetterSqliteValue[]): BetterSqliteRow | undefined;
+    all(...params: BetterSqliteValue[]): BetterSqliteRow[];
+}
+export interface BetterSqliteDatabaseHandle {
+    exec(sql: string): void;
+    prepare(sql: string): BetterSqliteStatement;
+    close(): void;
+}
+export interface BetterSqliteOpenOptions {
+    fileMustExist?: boolean;
+    readonly?: boolean;
+}
+interface BetterSqliteConstructor {
+    new (filename: string, options?: BetterSqliteOpenOptions): BetterSqliteDatabaseHandle;
+}
+export declare function loadBetterSqlite3(): Promise<BetterSqliteConstructor>;
+export {};

package/dist/sqlite/better-sqlite3.js

@@ -0,0 +1,4 @@
+export async function loadBetterSqlite3() {
+    const imported = await import("better-sqlite3");
+    return (imported.default ?? imported);
+}

package/dist/sqlite/checkpoints.d.ts

@@ -0,0 +1,11 @@
+import type { ClientCheckpoint } from "../types.js";
+import type { SqliteDatabase } from "./driver.js";
+export interface StoredCheckpointRow {
+    height: number;
+    blockHashHex: string;
+    stateBytes: Uint8Array;
+    createdAt: number;
+}
+export declare function loadLatestCheckpoint(database: SqliteDatabase): Promise<StoredCheckpointRow | null>;
+export declare function replaceCheckpoint(database: SqliteDatabase, checkpoint: ClientCheckpoint): Promise<void>;
+export declare function deleteCheckpointsAbove(database: SqliteDatabase, height: number): Promise<void>;

package/dist/sqlite/checkpoints.js

@@ -0,0 +1,27 @@
+import { bytesToHex, cloneBytes, hexToBytes } from "../bytes.js";
+function decodeCheckpointRow(row) {
+    if (row === null) {
+        return null;
+    }
+    return {
+        height: row.height,
+        blockHashHex: bytesToHex(row.block_hash),
+        stateBytes: cloneBytes(row.state_bytes),
+        createdAt: row.created_at,
+    };
+}
+export async function loadLatestCheckpoint(database) {
+    return decodeCheckpointRow(await database.get(`SELECT height, block_hash, state_bytes, created_at FROM checkpoints ORDER BY height DESC LIMIT 1`));
+}
+export async function replaceCheckpoint(database, checkpoint) {
+    await database.run(`INSERT OR REPLACE INTO checkpoints (height, block_hash, state_bytes, created_at)
+     VALUES (?, ?, ?, ?)`, [
+        checkpoint.height,
+        hexToBytes(checkpoint.blockHashHex),
+        checkpoint.stateBytes,
+        checkpoint.createdAt,
+    ]);
+}
+export async function deleteCheckpointsAbove(database, height) {
+    await database.run(`DELETE FROM checkpoints WHERE height > ?`, [height]);
+}

package/dist/sqlite/driver.d.ts

@@ -0,0 +1,17 @@
+import type { SqliteStoreOptions } from "./types.js";
+type SqliteValue = bigint | null | number | string | Uint8Array;
+export interface SqliteRunResult {
+    changes: number;
+    lastInsertRowid: bigint | number | null;
+}
+export interface SqliteDatabase {
+    exec(sql: string): Promise<void>;
+    run(sql: string, params?: readonly SqliteValue[]): Promise<SqliteRunResult>;
+    get<T>(sql: string, params?: readonly SqliteValue[]): Promise<T | null>;
+    all<T>(sql: string, params?: readonly SqliteValue[]): Promise<T[]>;
+    transaction<T>(operation: () => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+export declare function openSqliteDatabase(options: SqliteStoreOptions): Promise<SqliteDatabase>;
+export declare function openReadonlySqliteDatabase(filename: string): Promise<SqliteDatabase>;
+export {};