@cogcoin/client 0.5.11 → 0.5.13

package/dist/cli/update-notifier.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedCliArgs, RequiredCliRunnerContext } from "./types.js";
+export declare function maybeNotifyAboutCliUpdate(parsed: ParsedCliArgs, context: RequiredCliRunnerContext): Promise<void>;

package/dist/cli/update-notifier.js

@@ -0,0 +1,276 @@
+import { readFile } from "node:fs/promises";
+import { writeJsonFileAtomic } from "../wallet/fs/atomic.js";
+import { writeLine } from "./io.js";
+const UPDATE_CHECK_CACHE_SCHEMA_VERSION = 1;
+const UPDATE_CHECK_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const UPDATE_CHECK_TIMEOUT_MS = 500;
+const UPDATE_CHECK_URL = "https://registry.npmjs.org/@cogcoin/client/latest";
+function createEmptyUpdateCheckCache() {
+    return {
+        schemaVersion: UPDATE_CHECK_CACHE_SCHEMA_VERSION,
+        lastCheckedAtUnixMs: 0,
+        latestVersion: null,
+        lastNotifiedCurrentVersion: null,
+        lastNotifiedLatestVersion: null,
+        lastNotifiedAtUnixMs: null,
+    };
+}
+function parseSemver(version) {
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(version.trim());
+    if (match === null) {
+        return null;
+    }
+    const prerelease = match[4] === undefined
+        ? []
+        : match[4].split(".").map((raw) => ({
+            raw,
+            numeric: /^(0|[1-9]\d*)$/.test(raw),
+            numericValue: /^(0|[1-9]\d*)$/.test(raw) ? Number(raw) : null,
+        }));
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease,
+    };
+}
+function compareSemver(left, right) {
+    const leftParsed = parseSemver(left);
+    const rightParsed = parseSemver(right);
+    if (leftParsed === null || rightParsed === null) {
+        return null;
+    }
+    if (leftParsed.major !== rightParsed.major) {
+        return leftParsed.major > rightParsed.major ? 1 : -1;
+    }
+    if (leftParsed.minor !== rightParsed.minor) {
+        return leftParsed.minor > rightParsed.minor ? 1 : -1;
+    }
+    if (leftParsed.patch !== rightParsed.patch) {
+        return leftParsed.patch > rightParsed.patch ? 1 : -1;
+    }
+    if (leftParsed.prerelease.length === 0 && rightParsed.prerelease.length === 0) {
+        return 0;
+    }
+    if (leftParsed.prerelease.length === 0) {
+        return 1;
+    }
+    if (rightParsed.prerelease.length === 0) {
+        return -1;
+    }
+    const maxLength = Math.max(leftParsed.prerelease.length, rightParsed.prerelease.length);
+    for (let index = 0; index < maxLength; index += 1) {
+        const leftIdentifier = leftParsed.prerelease[index];
+        const rightIdentifier = rightParsed.prerelease[index];
+        if (leftIdentifier === undefined) {
+            return -1;
+        }
+        if (rightIdentifier === undefined) {
+            return 1;
+        }
+        if (leftIdentifier.numeric && rightIdentifier.numeric) {
+            if (leftIdentifier.numericValue !== rightIdentifier.numericValue) {
+                return leftIdentifier.numericValue > rightIdentifier.numericValue ? 1 : -1;
+            }
+            continue;
+        }
+        if (leftIdentifier.numeric !== rightIdentifier.numeric) {
+            return leftIdentifier.numeric ? -1 : 1;
+        }
+        if (leftIdentifier.raw !== rightIdentifier.raw) {
+            return leftIdentifier.raw > rightIdentifier.raw ? 1 : -1;
+        }
+    }
+    return 0;
+}
+function isUpdateCheckDisabled(env) {
+    const raw = env.COGCOIN_DISABLE_UPDATE_CHECK;
+    if (raw === undefined) {
+        return false;
+    }
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+function isEligibleForUpdateNotification(parsed, context) {
+    if (parsed.outputMode !== "text" || parsed.help || parsed.version) {
+        return false;
+    }
+    return context.stdout.isTTY === true || context.stderr.isTTY === true;
+}
+function normalizeUpdateCheckCache(parsed) {
+    if (typeof parsed !== "object" || parsed === null) {
+        return null;
+    }
+    const candidate = parsed;
+    if (candidate.schemaVersion !== UPDATE_CHECK_CACHE_SCHEMA_VERSION) {
+        return null;
+    }
+    return {
+        schemaVersion: UPDATE_CHECK_CACHE_SCHEMA_VERSION,
+        lastCheckedAtUnixMs: typeof candidate.lastCheckedAtUnixMs === "number" ? candidate.lastCheckedAtUnixMs : 0,
+        latestVersion: typeof candidate.latestVersion === "string" ? candidate.latestVersion : null,
+        lastNotifiedCurrentVersion: typeof candidate.lastNotifiedCurrentVersion === "string"
+            ? candidate.lastNotifiedCurrentVersion
+            : null,
+        lastNotifiedLatestVersion: typeof candidate.lastNotifiedLatestVersion === "string"
+            ? candidate.lastNotifiedLatestVersion
+            : null,
+        lastNotifiedAtUnixMs: typeof candidate.lastNotifiedAtUnixMs === "number"
+            ? candidate.lastNotifiedAtUnixMs
+            : null,
+        lastCheckErrorKind: typeof candidate.lastCheckErrorKind === "string"
+            ? candidate.lastCheckErrorKind
+            : undefined,
+    };
+}
+async function loadUpdateCheckCache(cachePath) {
+    try {
+        const raw = await readFile(cachePath, "utf8");
+        return normalizeUpdateCheckCache(JSON.parse(raw));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        return null;
+    }
+}
+function shouldRefreshUpdateCheck(cache, now) {
+    return now - cache.lastCheckedAtUnixMs >= UPDATE_CHECK_MAX_AGE_MS;
+}
+function shouldNotifyForVersionPair(cache, currentVersion, latestVersion, now) {
+    const versionComparison = compareSemver(latestVersion, currentVersion);
+    if (versionComparison === null || versionComparison <= 0) {
+        return false;
+    }
+    if (cache.lastNotifiedCurrentVersion !== currentVersion
+        || cache.lastNotifiedLatestVersion !== latestVersion) {
+        return true;
+    }
+    if (cache.lastNotifiedAtUnixMs === null) {
+        return true;
+    }
+    return now - cache.lastNotifiedAtUnixMs >= UPDATE_CHECK_MAX_AGE_MS;
+}
+function recordUpdateNotification(cache, currentVersion, latestVersion, now) {
+    return {
+        ...cache,
+        lastNotifiedCurrentVersion: currentVersion,
+        lastNotifiedLatestVersion: latestVersion,
+        lastNotifiedAtUnixMs: now,
+    };
+}
+async function fetchLatestPublishedVersion(fetchImpl) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, UPDATE_CHECK_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(UPDATE_CHECK_URL, {
+            headers: {
+                accept: "application/json",
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return {
+                kind: "failure",
+                errorKind: `http_${response.status}`,
+            };
+        }
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            return {
+                kind: "failure",
+                errorKind: "invalid_json",
+            };
+        }
+        const latestVersion = typeof payload.version === "string"
+            ? payload.version
+            : null;
+        if (latestVersion === null) {
+            return {
+                kind: "failure",
+                errorKind: "invalid_payload",
+            };
+        }
+        if (parseSemver(latestVersion) === null) {
+            return {
+                kind: "failure",
+                errorKind: "invalid_semver",
+            };
+        }
+        return {
+            kind: "success",
+            latestVersion,
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            return {
+                kind: "failure",
+                errorKind: "timeout",
+            };
+        }
+        return {
+            kind: "failure",
+            errorKind: "network",
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function writeUpdateNotice(context, currentVersion, latestVersion) {
+    writeLine(context.stderr, `Update available: Cogcoin ${currentVersion} -> ${latestVersion}`);
+    writeLine(context.stderr, "Run: npm install -g @cogcoin/client");
+}
+async function persistUpdateCheckCache(cachePath, cache) {
+    await writeJsonFileAtomic(cachePath, cache);
+}
+export async function maybeNotifyAboutCliUpdate(parsed, context) {
+    try {
+        if (!isEligibleForUpdateNotification(parsed, context) || isUpdateCheckDisabled(context.env)) {
+            return;
+        }
+        const currentVersion = await context.readPackageVersion();
+        if (parseSemver(currentVersion) === null) {
+            return;
+        }
+        const cachePath = context.resolveUpdateCheckStatePath();
+        const now = context.now();
+        let cache = await loadUpdateCheckCache(cachePath) ?? createEmptyUpdateCheckCache();
+        let cacheChanged = false;
+        if (shouldRefreshUpdateCheck(cache, now)) {
+            const updateResult = await fetchLatestPublishedVersion(context.fetchImpl);
+            cache = {
+                ...cache,
+                lastCheckedAtUnixMs: now,
+                latestVersion: updateResult.kind === "success"
+                    ? updateResult.latestVersion
+                    : cache.latestVersion,
+                lastCheckErrorKind: updateResult.kind === "success"
+                    ? undefined
+                    : updateResult.errorKind,
+            };
+            cacheChanged = true;
+        }
+        if (cache.latestVersion !== null
+            && shouldNotifyForVersionPair(cache, currentVersion, cache.latestVersion, now)) {
+            writeUpdateNotice(context, currentVersion, cache.latestVersion);
+            cache = recordUpdateNotification(cache, currentVersion, cache.latestVersion, now);
+            cacheChanged = true;
+            await persistUpdateCheckCache(cachePath, cache);
+            return;
+        }
+        if (cacheChanged) {
+            await persistUpdateCheckCache(cachePath, cache);
+        }
+    }
+    catch {
+        // Update checks are best-effort only.
+    }
+}

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

@@ -2,7 +2,7 @@ import type { BitcoinBlock, GenesisParameters, IndexerState } from "@cogcoin/ind
 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);
+    constructor(store: ClientStoreAdapter, genesisParameters: GenesisParameters, state: IndexerState, tip: ClientTip | null, snapshotInterval: number, blockRecordRetention: number);
     getTip(): Promise<ClientTip | null>;
     getState(): Promise<IndexerState>;
     applyBlock(block: BitcoinBlock): Promise<ApplyBlockResult>;

package/dist/client/default-client.js

@@ -4,16 +4,18 @@ export class DefaultClient {
     #store;
     #genesisParameters;
     #snapshotInterval;
+    #blockRecordRetention;
     #state;
     #tip;
     #closed = false;
     #queue = Promise.resolve();
-    constructor(store, genesisParameters, state, tip, snapshotInterval) {
+    constructor(store, genesisParameters, state, tip, snapshotInterval, blockRecordRetention) {
         this.#store = store;
         this.#genesisParameters = genesisParameters;
         this.#state = state;
         this.#tip = tip;
         this.#snapshotInterval = snapshotInterval;
+        this.#blockRecordRetention = blockRecordRetention;
     }
     async getTip() {
         await this.#queue;
@@ -39,6 +41,7 @@ export class DefaultClient {
                 blockRecord: createStoredBlockRecord(applied.blockRecord, createdAt),
                 checkpoint,
                 deleteAboveHeight: null,
+                deleteBelowHeight: this.#blockRecordLowerBound(block.height),
             };
             await this.#store.writeAppliedBlock(writeEntry);
             this.#state = applied.state;
@@ -110,6 +113,9 @@ export class DefaultClient {
     #shouldCheckpoint(height) {
         return this.#snapshotInterval > 0 && height % this.#snapshotInterval === 0;
     }
+    #blockRecordLowerBound(height) {
+        return height - this.#blockRecordRetention + 1;
+    }
     #enqueue(operation) {
         const next = this.#queue.then(operation, operation);
         this.#queue = next.then(() => undefined, () => undefined);

package/dist/client/factory.js

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

package/dist/sqlite/store.js

@@ -66,6 +66,9 @@ export function createSqliteStoreAdapter(database) {
                         await database.run(`DELETE FROM block_records WHERE height > ?`, [entry.deleteAboveHeight]);
                         await deleteCheckpointsAbove(database, entry.deleteAboveHeight);
                     }
+                    if (entry.deleteBelowHeight !== null && entry.deleteBelowHeight !== undefined) {
+                        await database.run(`DELETE FROM block_records WHERE height < ?`, [entry.deleteBelowHeight]);
+                    }
                     if (entry.blockRecord !== null && entry.blockRecord !== undefined) {
                         await database.run(`INSERT INTO block_records (height, block_hash, previous_hash, record_bytes, state_hash_hex, created_at)
                VALUES (?, ?, ?, ?, ?, ?)`, [

package/dist/types.d.ts

@@ -25,6 +25,7 @@ export interface WriteAppliedBlockEntry {
     blockRecord?: StoredBlockRecord | null;
     checkpoint?: ClientCheckpoint | null;
     deleteAboveHeight?: number | null;
+    deleteBelowHeight?: number | null;
 }
 export interface ClientStoreAdapter {
     loadTip(): Promise<ClientTip | null>;
@@ -39,6 +40,7 @@ export interface ClientOptions {
     store: ClientStoreAdapter;
     genesisParameters?: GenesisParameters;
     snapshotInterval?: number;
+    blockRecordRetention?: number;
 }
 export interface ApplyBlockResult {
     tip: ClientTip;

package/dist/wallet/archive.js

@@ -1,18 +1,20 @@
 import { readFile } from "node:fs/promises";
 import { writeJsonFileAtomic } from "./fs/atomic.js";
+import { normalizePortableWalletArchivePayload } from "./coin-control.js";
 import { decryptJsonWithPassphrase, encryptJsonWithPassphrase, } from "./state/crypto.js";
 export const PORTABLE_WALLET_ARCHIVE_FORMAT = "cogcoin-portable-wallet-archive";
 function assertPortableWalletArchivePayload(payload) {
-    if (payload.schemaVersion !== 1
-        || payload.walletRootId.trim() === ""
-        || payload.mnemonic.phrase.trim() === ""
-        || payload.expected.accountPath.trim() === ""
-        || payload.expected.publicExternalDescriptor.trim() === ""
-        || payload.expected.fundingAddress0.trim() === ""
-        || payload.expected.fundingScriptPubKeyHex0.trim() === "") {
+    const normalized = normalizePortableWalletArchivePayload(payload);
+    if (normalized.schemaVersion !== 1
+        || normalized.walletRootId.trim() === ""
+        || normalized.mnemonic.phrase.trim() === ""
+        || normalized.expected.accountPath.trim() === ""
+        || normalized.expected.publicExternalDescriptor.trim() === ""
+        || normalized.expected.fundingAddress0.trim() === ""
+        || normalized.expected.fundingScriptPubKeyHex0.trim() === "") {
         throw new Error("wallet_archive_payload_invalid");
     }
-    return payload;
+    return normalized;
 }
 export async function writePortableWalletArchive(path, payload, passphrase) {
     const envelope = await encryptJsonWithPassphrase(assertPortableWalletArchivePayload(payload), passphrase, {

package/dist/wallet/coin-control.d.ts

@@ -0,0 +1,41 @@
+import type { RpcListUnspentEntry, RpcLockedUnspent } from "../bitcoind/types.js";
+import { persistWalletStateUpdate } from "./descriptor-normalization.js";
+import type { WalletRuntimePaths } from "./runtime.js";
+import type { OutpointRecord, PortableWalletArchivePayloadV1, UnlockSessionStateV1, WalletStateV1 } from "./types.js";
+export declare const DEFAULT_PROACTIVE_RESERVE_SATS = 50000;
+export interface WalletCoinControlRpc {
+    listUnspent(walletName: string, minConf?: number): Promise<RpcListUnspentEntry[]>;
+    listLockUnspent(walletName: string): Promise<RpcLockedUnspent[]>;
+    lockUnspent(walletName: string, unlock: boolean, outputs: RpcLockedUnspent[]): Promise<boolean>;
+}
+export declare function outpointKey(outpoint: OutpointRecord): string;
+export declare function normalizeWalletStateRecord(state: WalletStateV1): WalletStateV1;
+export declare function normalizePortableWalletArchivePayload(payload: PortableWalletArchivePayloadV1): PortableWalletArchivePayloadV1;
+export declare function computeDesignatedProactiveReserveOutpoints(state: WalletStateV1, spendableUtxos: readonly RpcListUnspentEntry[]): OutpointRecord[];
+export declare function reconcilePersistentPolicyLocks(options: {
+    rpc: WalletCoinControlRpc;
+    walletName: string;
+    state: WalletStateV1;
+    fixedInputs?: readonly OutpointRecord[];
+    temporarilyUnlockedOutpoints?: readonly OutpointRecord[];
+    cleanupInactiveTemporaryBuilderLocks?: boolean;
+    spendableUtxos?: readonly RpcListUnspentEntry[];
+}): Promise<{
+    state: WalletStateV1;
+    changed: boolean;
+    spendableUtxos: readonly RpcListUnspentEntry[];
+}>;
+export declare function persistWalletCoinControlStateIfNeeded(options: {
+    state: WalletStateV1;
+    access: Parameters<typeof persistWalletStateUpdate>[0]["access"];
+    session?: UnlockSessionStateV1 | null;
+    paths: WalletRuntimePaths;
+    nowUnixMs: number;
+    replacePrimary?: boolean;
+    rpc: WalletCoinControlRpc;
+    cleanupInactiveTemporaryBuilderLocks?: boolean;
+}): Promise<{
+    changed: boolean;
+    session: UnlockSessionStateV1 | null;
+    state: WalletStateV1;
+}>;