@cogcoin/client 0.5.0

package/dist/wallet/material.d.ts

@@ -0,0 +1,45 @@
+import type { WalletMnemonicLanguage } from "./types.js";
+export declare const WALLET_ACCOUNT_PATH = "m/84'/0'/0'";
+export declare const DEFAULT_DESCRIPTOR_RANGE_END = 4095;
+export declare const DEFAULT_DESCRIPTOR_SAFETY_MARGIN = 128;
+export interface WalletMaterial {
+    mnemonic: {
+        phrase: string;
+        words: string[];
+        language: WalletMnemonicLanguage;
+    };
+    keys: {
+        masterFingerprintHex: string;
+        accountPath: string;
+        accountXprv: string;
+        accountXpub: string;
+    };
+    descriptor: {
+        privateExternal: string;
+        publicExternal: string;
+        checksum: string | null;
+        rangeEnd: number;
+        safetyMargin: number;
+    };
+    funding: {
+        index: 0;
+        address: string;
+        scriptPubKeyHex: string;
+    };
+}
+export interface WalletDerivedIdentity {
+    index: number;
+    address: string;
+    scriptPubKeyHex: string;
+    ethereumAddress: string;
+    nostrPublicKeyHex: string;
+    nostrNpub: string;
+}
+export declare function generateWalletMaterial(): WalletMaterial;
+export declare function deriveWalletMaterialFromMnemonic(phrase: string): WalletMaterial;
+export declare function deriveWalletIdentityMaterial(accountKey: string, index: number): WalletDerivedIdentity;
+export declare function createInternalCoreWalletPassphrase(): string;
+export declare function createMnemonicConfirmationChallenge(words: string[], count?: number): Array<{
+    index: number;
+    word: string;
+}>;

package/dist/wallet/material.js

@@ -0,0 +1,118 @@
+import { createHash, randomBytes } from "node:crypto";
+import { bech32 } from "@scure/base";
+import { HDKey } from "@scure/bip32";
+import { generateMnemonic, mnemonicToSeedSync } from "@scure/bip39";
+import { wordlist as englishWordlist } from "@scure/bip39/wordlists/english.js";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { keccak_256 } from "@noble/hashes/sha3.js";
+export const WALLET_ACCOUNT_PATH = "m/84'/0'/0'";
+export const DEFAULT_DESCRIPTOR_RANGE_END = 4095;
+export const DEFAULT_DESCRIPTOR_SAFETY_MARGIN = 128;
+function hash160(value) {
+    const sha256 = createHash("sha256").update(value).digest();
+    return createHash("ripemd160").update(sha256).digest();
+}
+function formatFingerprint(fingerprint) {
+    return fingerprint.toString(16).padStart(8, "0");
+}
+function encodeSegwitV0Address(program) {
+    return bech32.encode("bc", [0, ...bech32.toWords(program)]);
+}
+function encodeNostrNpub(xOnlyPublicKey) {
+    return bech32.encode("npub", bech32.toWords(xOnlyPublicKey));
+}
+function buildExternalDescriptor(fingerprintHex, accountKey) {
+    return `wpkh([${fingerprintHex}/84h/0h/0h]${accountKey}/0/*)`;
+}
+function deriveFundingAddress(root) {
+    const fundingNode = root.derive("m/84'/0'/0'/0/0");
+    if (fundingNode.publicKey == null) {
+        throw new Error("wallet_material_missing_funding_public_key");
+    }
+    const pubkeyHash = hash160(fundingNode.publicKey);
+    return {
+        address: encodeSegwitV0Address(pubkeyHash),
+        scriptPubKeyHex: `0014${Buffer.from(pubkeyHash).toString("hex")}`,
+    };
+}
+function deriveIdentityFromNode(index, node) {
+    if (node.publicKey == null || node.privateKey == null) {
+        throw new Error("wallet_material_missing_identity_key");
+    }
+    const compressedPublicKey = secp256k1.getPublicKey(node.privateKey, true);
+    const uncompressedPublicKey = secp256k1.getPublicKey(node.privateKey, false);
+    const pubkeyHash = hash160(compressedPublicKey);
+    const ethereumAddress = `0x${Buffer.from(keccak_256(uncompressedPublicKey.subarray(1)).subarray(-20)).toString("hex")}`;
+    const nostrPublicKey = compressedPublicKey.subarray(1, 33);
+    return {
+        index,
+        address: encodeSegwitV0Address(pubkeyHash),
+        scriptPubKeyHex: `0014${Buffer.from(pubkeyHash).toString("hex")}`,
+        ethereumAddress,
+        nostrPublicKeyHex: Buffer.from(nostrPublicKey).toString("hex"),
+        nostrNpub: encodeNostrNpub(nostrPublicKey),
+    };
+}
+export function generateWalletMaterial() {
+    const phrase = generateMnemonic(englishWordlist, 256);
+    return deriveWalletMaterialFromMnemonic(phrase);
+}
+export function deriveWalletMaterialFromMnemonic(phrase) {
+    const words = phrase.trim().split(/\s+/);
+    const seed = mnemonicToSeedSync(phrase);
+    const root = HDKey.fromMasterSeed(seed);
+    const accountNode = root.derive(WALLET_ACCOUNT_PATH);
+    if (accountNode.privateExtendedKey == null || accountNode.publicExtendedKey == null) {
+        throw new Error("wallet_material_missing_account_keys");
+    }
+    const masterFingerprintHex = formatFingerprint(root.fingerprint);
+    const funding = deriveFundingAddress(root);
+    return {
+        mnemonic: {
+            phrase,
+            words,
+            language: "english",
+        },
+        keys: {
+            masterFingerprintHex,
+            accountPath: WALLET_ACCOUNT_PATH,
+            accountXprv: accountNode.privateExtendedKey,
+            accountXpub: accountNode.publicExtendedKey,
+        },
+        descriptor: {
+            privateExternal: buildExternalDescriptor(masterFingerprintHex, accountNode.privateExtendedKey),
+            publicExternal: buildExternalDescriptor(masterFingerprintHex, accountNode.publicExtendedKey),
+            checksum: null,
+            rangeEnd: DEFAULT_DESCRIPTOR_RANGE_END,
+            safetyMargin: DEFAULT_DESCRIPTOR_SAFETY_MARGIN,
+        },
+        funding: {
+            index: 0,
+            address: funding.address,
+            scriptPubKeyHex: funding.scriptPubKeyHex,
+        },
+    };
+}
+export function deriveWalletIdentityMaterial(accountKey, index) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error("wallet_material_invalid_identity_index");
+    }
+    const accountNode = HDKey.fromExtendedKey(accountKey);
+    const identityNode = accountNode.deriveChild(0).deriveChild(index);
+    return deriveIdentityFromNode(index, identityNode);
+}
+export function createInternalCoreWalletPassphrase() {
+    return randomBytes(32).toString("hex");
+}
+export function createMnemonicConfirmationChallenge(words, count = 4) {
+    const selected = new Set();
+    while (selected.size < Math.min(count, words.length)) {
+        selected.add(randomBytes(1)[0] % words.length);
+    }
+    return [...selected]
+        .sort((left, right) => left - right)
+        .map((index) => ({
+        index,
+        word: words[index],
+    }));
+}

package/dist/wallet/mining/config.d.ts

@@ -0,0 +1,18 @@
+import type { WalletSecretProvider, WalletSecretReference } from "../state/provider.js";
+import type { ClientConfigV1, MiningProviderConfigRecord } from "./types.js";
+export declare function loadClientConfig(options: {
+    path: string;
+    provider: WalletSecretProvider;
+}): Promise<ClientConfigV1 | null>;
+export declare function saveClientConfig(options: {
+    path: string;
+    provider: WalletSecretProvider;
+    secretReference: WalletSecretReference;
+    config: ClientConfigV1;
+}): Promise<void>;
+export declare function saveBuiltInMiningProviderConfig(options: {
+    path: string;
+    provider: WalletSecretProvider;
+    secretReference: WalletSecretReference;
+    config: MiningProviderConfigRecord;
+}): Promise<ClientConfigV1>;

package/dist/wallet/mining/config.js

@@ -0,0 +1,44 @@
+import { readFile } from "node:fs/promises";
+import { writeJsonFileAtomic } from "../fs/atomic.js";
+import { decryptJsonWithSecretProvider, encryptJsonWithSecretProvider } from "../state/crypto.js";
+function createEmptyClientConfig() {
+    return {
+        schemaVersion: 1,
+        mining: {
+            builtIn: null,
+        },
+    };
+}
+export async function loadClientConfig(options) {
+    try {
+        const raw = await readFile(options.path, "utf8");
+        return await decryptJsonWithSecretProvider(JSON.parse(raw), options.provider);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function saveClientConfig(options) {
+    const envelope = await encryptJsonWithSecretProvider(options.config, options.provider, options.secretReference, {
+        format: "cogcoin-client-config",
+    });
+    await writeJsonFileAtomic(options.path, envelope, { mode: 0o600 });
+}
+export async function saveBuiltInMiningProviderConfig(options) {
+    const existing = await loadClientConfig({
+        path: options.path,
+        provider: options.provider,
+    }).catch(() => null);
+    const nextConfig = existing ?? createEmptyClientConfig();
+    nextConfig.mining.builtIn = options.config;
+    await saveClientConfig({
+        path: options.path,
+        provider: options.provider,
+        secretReference: options.secretReference,
+        config: nextConfig,
+    });
+    return nextConfig;
+}

package/dist/wallet/mining/constants.d.ts

@@ -0,0 +1,24 @@
+export declare const MINING_WORKER_API_VERSION: "cogcoin/mining-worker/v1";
+export declare const MINING_STATUS_HEARTBEAT_INTERVAL_MS = 5000;
+export declare const MINING_WORKER_HEARTBEAT_STALE_MS = 15000;
+export declare const MINING_SUSPEND_GAP_THRESHOLD_MS = 15000;
+export declare const MINING_NETWORK_SETTLE_WINDOW_MS = 5000;
+export declare const MINING_TIP_SETTLE_WINDOW_MS = 2000;
+export declare const MINING_PROVIDER_BACKOFF_BASE_MS = 30000;
+export declare const MINING_PROVIDER_BACKOFF_MAX_MS = 900000;
+export declare const MINING_LOOP_INTERVAL_MS = 2000;
+export declare const MINING_BUILTIN_TIMEOUT_MS = 30000;
+export declare const MINING_HOOK_SCHEMA_VERSION: 1;
+export declare const MINING_HOOK_MAX_CANDIDATE_SENTENCE_UTF8_BYTES = 512;
+export declare const MINING_HOOK_MAX_CANDIDATES_PER_ROOT_DOMAIN = 8;
+export declare const MINING_HOOK_MAX_CANDIDATES_TOTAL = 64;
+export declare const MINING_HOOK_TIMEOUT_MS = 30000;
+export declare const MINING_CUSTOM_HOOK_TIMEOUT_MS = 30000;
+export declare const MINING_HOOK_STDOUT_MAX_BYTES = 262144;
+export declare const MINING_HOOK_STDERR_MAX_BYTES = 65536;
+export declare const MINING_HOOK_VALIDATION_TIMEOUT_MS = 10000;
+export declare const MINING_HOOK_TERMINATE_GRACE_MS = 2000;
+export declare const MINING_HOOK_FAILURE_THRESHOLD = 3;
+export declare const MINING_HOOK_COOLDOWN_MS = 300000;
+export declare const MINING_SHUTDOWN_GRACE_MS = 15000;
+export declare const MINING_SETTLEMENT_DUMMY_REWARD = 100n;

package/dist/wallet/mining/constants.js

@@ -0,0 +1,24 @@
+export const MINING_WORKER_API_VERSION = "cogcoin/mining-worker/v1";
+export const MINING_STATUS_HEARTBEAT_INTERVAL_MS = 5_000;
+export const MINING_WORKER_HEARTBEAT_STALE_MS = 15_000;
+export const MINING_SUSPEND_GAP_THRESHOLD_MS = 15_000;
+export const MINING_NETWORK_SETTLE_WINDOW_MS = 5_000;
+export const MINING_TIP_SETTLE_WINDOW_MS = 2_000;
+export const MINING_PROVIDER_BACKOFF_BASE_MS = 30_000;
+export const MINING_PROVIDER_BACKOFF_MAX_MS = 900_000;
+export const MINING_LOOP_INTERVAL_MS = 2_000;
+export const MINING_BUILTIN_TIMEOUT_MS = 30_000;
+export const MINING_HOOK_SCHEMA_VERSION = 1;
+export const MINING_HOOK_MAX_CANDIDATE_SENTENCE_UTF8_BYTES = 512;
+export const MINING_HOOK_MAX_CANDIDATES_PER_ROOT_DOMAIN = 8;
+export const MINING_HOOK_MAX_CANDIDATES_TOTAL = 64;
+export const MINING_HOOK_TIMEOUT_MS = 30_000;
+export const MINING_CUSTOM_HOOK_TIMEOUT_MS = MINING_HOOK_TIMEOUT_MS;
+export const MINING_HOOK_STDOUT_MAX_BYTES = 262_144;
+export const MINING_HOOK_STDERR_MAX_BYTES = 65_536;
+export const MINING_HOOK_VALIDATION_TIMEOUT_MS = 10_000;
+export const MINING_HOOK_TERMINATE_GRACE_MS = 2_000;
+export const MINING_HOOK_FAILURE_THRESHOLD = 3;
+export const MINING_HOOK_COOLDOWN_MS = 300_000;
+export const MINING_SHUTDOWN_GRACE_MS = 15_000;
+export const MINING_SETTLEMENT_DUMMY_REWARD = 100n;

package/dist/wallet/mining/control.d.ts

@@ -0,0 +1,53 @@
+import { type WalletPrompter } from "../lifecycle.js";
+import { type WalletRuntimePaths } from "../runtime.js";
+import { type WalletSecretProvider } from "../state/provider.js";
+import type { WalletBitcoindStatus, WalletIndexerStatus, WalletLocalStateStatus, WalletNodeStatus } from "../read/types.js";
+import type { MiningControlPlaneView, MiningEventRecord, MiningRuntimeStatusV1 } from "./types.js";
+export declare function inspectMiningControlPlane(options: {
+    provider?: WalletSecretProvider;
+    localState: WalletLocalStateStatus;
+    bitcoind: WalletBitcoindStatus;
+    nodeStatus: WalletNodeStatus | null;
+    nodeHealth: MiningRuntimeStatusV1["nodeHealth"];
+    indexer: WalletIndexerStatus;
+    verify?: boolean;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+}): Promise<MiningControlPlaneView>;
+export declare function refreshMiningRuntimeStatus(options: {
+    provider?: WalletSecretProvider;
+    localState: WalletLocalStateStatus;
+    bitcoind: WalletBitcoindStatus;
+    nodeStatus: WalletNodeStatus | null;
+    nodeHealth: MiningRuntimeStatusV1["nodeHealth"];
+    indexer: WalletIndexerStatus;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+}): Promise<MiningControlPlaneView>;
+export declare function enableMiningHooks(options: {
+    provider?: WalletSecretProvider;
+    prompter: WalletPrompter;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+}): Promise<MiningControlPlaneView>;
+export declare function disableMiningHooks(options: {
+    provider?: WalletSecretProvider;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+}): Promise<MiningControlPlaneView>;
+export declare function setupBuiltInMining(options: {
+    provider?: WalletSecretProvider;
+    prompter: WalletPrompter;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+}): Promise<MiningControlPlaneView>;
+export declare function readMiningLog(options: {
+    paths?: WalletRuntimePaths;
+    limit?: number | null;
+    all?: boolean;
+}): Promise<MiningEventRecord[]>;
+export declare function followMiningLog(options: {
+    paths?: WalletRuntimePaths;
+    signal?: AbortSignal;
+    onEvent: (event: MiningEventRecord) => void;
+}): Promise<void>;