@cogcoin/client 0.5.0

package/dist/wallet/tx/common.d.ts

@@ -0,0 +1,89 @@
+import type { RpcDecodedPsbt, RpcFinalizePsbtResult, RpcListUnspentEntry, RpcLockedUnspent, RpcTestMempoolAcceptResult, RpcTransaction, RpcWalletCreateFundedPsbtResult, RpcWalletProcessPsbtResult } from "../../bitcoind/types.js";
+import { type WalletSecretProvider } from "../state/provider.js";
+import type { OutpointRecord, PendingMutationRecord, PendingMutationStatus, WalletStateV1 } from "../types.js";
+import type { WalletReadContext } from "../read/index.js";
+import type { WalletRuntimePaths } from "../runtime.js";
+import { type MiningPreemptionHandle } from "../mining/coordination.js";
+export declare const DEFAULT_WALLET_MUTATION_FEE_RATE_SAT_VB = 10;
+export interface MutationSender {
+    localIndex: number;
+    scriptPubKeyHex: string;
+    address: string;
+}
+export interface WalletMutationRpcClient {
+    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>;
+    walletProcessPsbt(walletName: string, psbt: string, sign?: boolean, sighashType?: string): Promise<RpcWalletProcessPsbtResult>;
+    finalizePsbt(psbt: string, extract?: boolean): Promise<RpcFinalizePsbtResult>;
+    decodeRawTransaction(hex: string): Promise<RpcTransaction>;
+    testMempoolAccept(rawTransactions: string[]): Promise<RpcTestMempoolAcceptResult[]>;
+}
+export interface BuiltWalletMutationTransaction {
+    funded: RpcWalletCreateFundedPsbtResult;
+    decoded: RpcDecodedPsbt;
+    psbt: string;
+    rawHex: string;
+    txid: string;
+    wtxid: string | null;
+    temporaryBuilderLockedOutpoints: OutpointRecord[];
+}
+export declare function saveWalletStatePreservingUnlock(options: {
+    state: WalletStateV1;
+    provider: WalletSecretProvider;
+    unlockUntilUnixMs: number;
+    nowUnixMs: number;
+    paths: WalletRuntimePaths;
+}): Promise<void>;
+export declare function formatCogAmount(value: bigint): string;
+export declare function outpointKey(outpoint: OutpointRecord): string;
+export declare function updateMutationRecord(mutation: PendingMutationRecord, status: PendingMutationStatus, nowUnixMs: number, options?: {
+    attemptedTxid?: string | null;
+    attemptedWtxid?: string | null;
+    temporaryBuilderLockedOutpoints?: OutpointRecord[];
+}): PendingMutationRecord;
+export declare function unlockTemporaryBuilderLocks(rpc: Pick<WalletMutationRpcClient, "lockUnspent">, walletName: string, outpoints: OutpointRecord[]): Promise<void>;
+export declare function diffTemporaryLockedOutpoints(before: RpcLockedUnspent[], after: RpcLockedUnspent[]): OutpointRecord[];
+export declare function isBroadcastUnknownError(error: unknown): boolean;
+export declare function isAlreadyAcceptedError(error: unknown): boolean;
+export declare function assertWalletMutationContextReady(context: WalletReadContext, errorPrefix: string): asserts context is WalletReadContext & {
+    localState: {
+        availability: "ready";
+        state: WalletStateV1;
+        unlockUntilUnixMs: number;
+    };
+    snapshot: NonNullable<WalletReadContext["snapshot"]>;
+    model: NonNullable<WalletReadContext["model"]>;
+};
+export declare function pauseMiningForWalletMutation(options: {
+    paths: WalletRuntimePaths;
+    reason: string;
+}): Promise<MiningPreemptionHandle>;
+export declare function buildWalletMutationTransaction<TPlan>(options: {
+    rpc: WalletMutationRpcClient;
+    walletName: string;
+    plan: TPlan & {
+        inputs: Array<{
+            txid: string;
+            vout: number;
+        }>;
+        outputs: unknown[];
+        changeAddress: string;
+        changePosition: number;
+    };
+    validateFundedDraft(decoded: RpcDecodedPsbt, funded: RpcWalletCreateFundedPsbtResult, plan: TPlan): void;
+    finalizeErrorCode: string;
+    mempoolRejectPrefix: string;
+    feeRate?: number;
+    builderOptions?: {
+        addInputs?: boolean;
+        includeUnsafe?: boolean;
+        minConf?: number;
+        lockUnspents?: boolean;
+    };
+}): Promise<BuiltWalletMutationTransaction>;

package/dist/wallet/tx/common.js

@@ -0,0 +1,156 @@
+import { randomBytes } from "node:crypto";
+import { saveUnlockSession } from "../state/session.js";
+import { saveWalletState } from "../state/storage.js";
+import { createWalletSecretReference, } from "../state/provider.js";
+import { requestMiningGenerationPreemption } from "../mining/coordination.js";
+export const DEFAULT_WALLET_MUTATION_FEE_RATE_SAT_VB = 10;
+function createUnlockSessionState(state, unlockUntilUnixMs, nowUnixMs) {
+    return {
+        schemaVersion: 1,
+        walletRootId: state.walletRootId,
+        sessionId: randomBytes(16).toString("hex"),
+        createdAtUnixMs: nowUnixMs,
+        unlockUntilUnixMs,
+        sourceStateRevision: state.stateRevision,
+        wrappedSessionKeyMaterial: createWalletSecretReference(state.walletRootId).keyId,
+    };
+}
+export async function saveWalletStatePreservingUnlock(options) {
+    const secretReference = createWalletSecretReference(options.state.walletRootId);
+    await saveWalletState({
+        primaryPath: options.paths.walletStatePath,
+        backupPath: options.paths.walletStateBackupPath,
+    }, options.state, {
+        provider: options.provider,
+        secretReference,
+    });
+    await saveUnlockSession(options.paths.walletUnlockSessionPath, createUnlockSessionState(options.state, options.unlockUntilUnixMs, options.nowUnixMs), {
+        provider: options.provider,
+        secretReference,
+    });
+}
+export function formatCogAmount(value) {
+    const sign = value < 0n ? "-" : "";
+    const absolute = value < 0n ? -value : value;
+    const whole = absolute / 100000000n;
+    const fraction = absolute % 100000000n;
+    return `${sign}${whole.toString()}.${fraction.toString().padStart(8, "0")} COG`;
+}
+export function outpointKey(outpoint) {
+    return `${outpoint.txid}:${outpoint.vout}`;
+}
+export function updateMutationRecord(mutation, status, nowUnixMs, options = {}) {
+    return {
+        ...mutation,
+        status,
+        lastUpdatedAtUnixMs: nowUnixMs,
+        attemptedTxid: options.attemptedTxid ?? mutation.attemptedTxid,
+        attemptedWtxid: options.attemptedWtxid ?? mutation.attemptedWtxid,
+        temporaryBuilderLockedOutpoints: options.temporaryBuilderLockedOutpoints ?? mutation.temporaryBuilderLockedOutpoints,
+    };
+}
+export async function unlockTemporaryBuilderLocks(rpc, walletName, outpoints) {
+    if (outpoints.length === 0) {
+        return;
+    }
+    await rpc.lockUnspent(walletName, true, outpoints).catch(() => undefined);
+}
+export function diffTemporaryLockedOutpoints(before, after) {
+    const beforeKeys = new Set(before.map((entry) => outpointKey(entry)));
+    return after
+        .filter((entry) => !beforeKeys.has(outpointKey(entry)))
+        .map((entry) => ({
+        txid: entry.txid,
+        vout: entry.vout,
+    }));
+}
+export function isBroadcastUnknownError(error) {
+    const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    return message.includes("timeout")
+        || message.includes("timed out")
+        || message.includes("socket hang up")
+        || message.includes("econnreset")
+        || message.includes("econnrefused")
+        || message.includes("broken pipe")
+        || message.includes("broadcast_unknown");
+}
+export function isAlreadyAcceptedError(error) {
+    const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    return message.includes("already in block chain")
+        || message.includes("already in blockchain")
+        || message.includes("txn-already-known");
+}
+export function assertWalletMutationContextReady(context, errorPrefix) {
+    if (context.localState.availability === "uninitialized") {
+        throw new Error("wallet_uninitialized");
+    }
+    if (context.localState.availability === "local-state-corrupt") {
+        throw new Error("local-state-corrupt");
+    }
+    if (context.localState.availability !== "ready" || context.localState.state === null || context.localState.unlockUntilUnixMs === null) {
+        throw new Error("wallet_locked");
+    }
+    if (context.bitcoind.health !== "ready") {
+        throw new Error(`${errorPrefix}_bitcoind_${context.bitcoind.health.replaceAll("-", "_")}`);
+    }
+    if (context.nodeHealth !== "synced") {
+        throw new Error(`${errorPrefix}_node_${context.nodeHealth.replaceAll("-", "_")}`);
+    }
+    if (context.indexer.health !== "synced" || context.snapshot === null || context.model === null) {
+        throw new Error(`${errorPrefix}_indexer_${context.indexer.health.replaceAll("-", "_")}`);
+    }
+    if (context.nodeStatus?.walletReplica?.proofStatus !== "ready") {
+        throw new Error(`${errorPrefix}_core_replica_not_ready`);
+    }
+}
+export async function pauseMiningForWalletMutation(options) {
+    return requestMiningGenerationPreemption({
+        paths: options.paths,
+        reason: options.reason,
+    });
+}
+export async function buildWalletMutationTransaction(options) {
+    const lockedBefore = await options.rpc.listLockUnspent(options.walletName);
+    let temporaryBuilderLockedOutpoints = [];
+    try {
+        const funded = await options.rpc.walletCreateFundedPsbt(options.walletName, options.plan.inputs, options.plan.outputs, 0, {
+            add_inputs: options.builderOptions?.addInputs ?? true,
+            include_unsafe: options.builderOptions?.includeUnsafe ?? false,
+            minconf: options.builderOptions?.minConf ?? 1,
+            changeAddress: options.plan.changeAddress,
+            changePosition: options.plan.changePosition,
+            lockUnspents: options.builderOptions?.lockUnspents ?? true,
+            fee_rate: options.feeRate ?? DEFAULT_WALLET_MUTATION_FEE_RATE_SAT_VB,
+            replaceable: true,
+            subtractFeeFromOutputs: [],
+        });
+        const lockedAfter = await options.rpc.listLockUnspent(options.walletName);
+        temporaryBuilderLockedOutpoints = diffTemporaryLockedOutpoints(lockedBefore, lockedAfter);
+        const decoded = await options.rpc.decodePsbt(funded.psbt);
+        options.validateFundedDraft(decoded, funded, options.plan);
+        const signed = await options.rpc.walletProcessPsbt(options.walletName, funded.psbt, true, "DEFAULT");
+        const finalized = await options.rpc.finalizePsbt(signed.psbt, true);
+        if (!finalized.complete || finalized.hex == null) {
+            throw new Error(options.finalizeErrorCode);
+        }
+        const decodedRaw = await options.rpc.decodeRawTransaction(finalized.hex);
+        const mempoolResult = await options.rpc.testMempoolAccept([finalized.hex]);
+        const accepted = mempoolResult[0];
+        if (accepted == null || !accepted.allowed) {
+            throw new Error(`${options.mempoolRejectPrefix}_${accepted?.["reject-reason"] ?? "unknown"}`);
+        }
+        return {
+            funded,
+            decoded,
+            psbt: signed.psbt,
+            rawHex: finalized.hex,
+            txid: decodedRaw.txid,
+            wtxid: decodedRaw.hash ?? null,
+            temporaryBuilderLockedOutpoints,
+        };
+    }
+    catch (error) {
+        await unlockTemporaryBuilderLocks(options.rpc, options.walletName, temporaryBuilderLockedOutpoints);
+        throw error;
+    }
+}

package/dist/wallet/tx/confirm.d.ts

@@ -0,0 +1,15 @@
+import type { WalletPrompter } from "../lifecycle.js";
+export declare function confirmYesNo(prompter: WalletPrompter, message: string, options: {
+    assumeYes?: boolean;
+    errorCode: string;
+    requiresTtyErrorCode: string;
+    prompt?: string;
+}): Promise<void>;
+export declare function confirmTypedAcknowledgement(prompter: WalletPrompter, options: {
+    assumeYes?: boolean;
+    expected: string;
+    prompt: string;
+    errorCode: string;
+    requiresTtyErrorCode: string;
+    typedAckRequiredErrorCode: string;
+}): Promise<void>;

package/dist/wallet/tx/confirm.js

@@ -0,0 +1,24 @@
+export async function confirmYesNo(prompter, message, options) {
+    prompter.writeLine(message);
+    if (options.assumeYes === true) {
+        return;
+    }
+    if (!prompter.isInteractive) {
+        throw new Error(options.requiresTtyErrorCode);
+    }
+    const answer = (await prompter.prompt(options.prompt ?? "Continue? [y/N]: ")).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+        throw new Error(options.errorCode);
+    }
+}
+export async function confirmTypedAcknowledgement(prompter, options) {
+    if (!prompter.isInteractive) {
+        throw new Error(options.assumeYes === true
+            ? options.typedAckRequiredErrorCode
+            : options.requiresTtyErrorCode);
+    }
+    const answer = (await prompter.prompt(options.prompt)).trim();
+    if (answer !== options.expected) {
+        throw new Error(options.errorCode);
+    }
+}

package/dist/wallet/tx/domain-admin.d.ts

@@ -0,0 +1,105 @@
+import { attachOrStartManagedBitcoindService } from "../../bitcoind/service.js";
+import { createRpcClient } from "../../bitcoind/node.js";
+import type { RpcTransaction } from "../../bitcoind/types.js";
+import type { WalletPrompter } from "../lifecycle.js";
+import { type WalletRuntimePaths } from "../runtime.js";
+import { type WalletSecretProvider } from "../state/provider.js";
+import { openWalletReadContext } from "../read/index.js";
+import { type WalletMutationRpcClient } from "./common.js";
+type DomainAdminKind = "endpoint" | "delegate" | "miner" | "canonical";
+interface DomainAdminRpcClient extends WalletMutationRpcClient {
+    getBlockchainInfo(): Promise<{
+        blocks: number;
+    }>;
+    sendRawTransaction(hex: string): Promise<string>;
+    getRawTransaction(txid: string, verbose?: boolean): Promise<RpcTransaction>;
+}
+export interface DomainAdminResolvedSenderSummary {
+    selector: string;
+    localIndex: number;
+    scriptPubKeyHex: string;
+    address: string;
+}
+export interface DomainAdminResolvedTargetSummary {
+    scriptPubKeyHex: string;
+    address: string | null;
+    opaque: boolean;
+}
+export type DomainAdminResolvedEffect = {
+    kind: "endpoint-set";
+    byteLength: number;
+} | {
+    kind: "endpoint-clear";
+} | {
+    kind: "delegate-set";
+} | {
+    kind: "delegate-clear";
+} | {
+    kind: "miner-set";
+} | {
+    kind: "miner-clear";
+} | {
+    kind: "canonicalize-owner";
+};
+export interface DomainAdminResolvedSummary {
+    sender: DomainAdminResolvedSenderSummary;
+    target: DomainAdminResolvedTargetSummary | null;
+    effect: DomainAdminResolvedEffect;
+}
+export interface DomainAdminMutationResult {
+    kind: DomainAdminKind;
+    domainName: string;
+    txid: string;
+    status: "live" | "confirmed";
+    reusedExisting: boolean;
+    recipientScriptPubKeyHex?: string | null;
+    endpointValueHex?: string | null;
+    resolved?: DomainAdminResolvedSummary | null;
+}
+interface DomainAdminBaseOptions {
+    domainName: string;
+    dataDir: string;
+    databasePath: string;
+    provider?: WalletSecretProvider;
+    prompter: WalletPrompter;
+    assumeYes?: boolean;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+    openReadContext?: typeof openWalletReadContext;
+    attachService?: typeof attachOrStartManagedBitcoindService;
+    rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => DomainAdminRpcClient;
+}
+export interface SetDomainEndpointOptions extends DomainAdminBaseOptions {
+    source: {
+        kind: "text";
+        value: string;
+    } | {
+        kind: "json";
+        value: string;
+    } | {
+        kind: "bytes";
+        value: string;
+    };
+}
+export interface ClearDomainEndpointOptions extends DomainAdminBaseOptions {
+}
+export interface SetDomainDelegateOptions extends DomainAdminBaseOptions {
+    target: string;
+}
+export interface ClearDomainDelegateOptions extends DomainAdminBaseOptions {
+}
+export interface SetDomainMinerOptions extends DomainAdminBaseOptions {
+    target: string;
+}
+export interface ClearDomainMinerOptions extends DomainAdminBaseOptions {
+}
+export interface SetDomainCanonicalOptions extends DomainAdminBaseOptions {
+}
+export declare function setDomainEndpoint(options: SetDomainEndpointOptions): Promise<DomainAdminMutationResult>;
+export declare function clearDomainEndpoint(options: ClearDomainEndpointOptions): Promise<DomainAdminMutationResult>;
+export declare function setDomainDelegate(options: SetDomainDelegateOptions): Promise<DomainAdminMutationResult>;
+export declare function clearDomainDelegate(options: ClearDomainDelegateOptions): Promise<DomainAdminMutationResult>;
+export declare function setDomainMiner(options: SetDomainMinerOptions): Promise<DomainAdminMutationResult>;
+export declare function clearDomainMiner(options: ClearDomainMinerOptions): Promise<DomainAdminMutationResult>;
+export declare function setDomainCanonical(options: SetDomainCanonicalOptions): Promise<DomainAdminMutationResult>;
+export {};