@hardkas/toolkit 0.11.2-alpha → 0.11.6-alpha

package/src/utxos.ts

@@ -1,451 +0,0 @@
-import { Utxo } from "@hardkas/query";
-
-export interface UtxoStatistics {
-  totalUtxos: number;
-  availableUtxos: number;
-  frozenUtxos: number;
-  totalValue: bigint;
-  availableValue: bigint;
-  frozenValue: bigint;
-  averageValue: bigint;
-  largest: bigint;
-  smallest: bigint;
-  includeFrozen: boolean;
-}
-
-export interface DustAnalysis {
-  dustUtxos: Utxo[];
-  normalUtxos: Utxo[];
-  totalDustValue: bigint;
-  dustPercentage: number;
-}
-
-export type Recommendation = "consolidate" | "mergeDust" | "splitLarge" | "none";
-
-export interface WalletAnalysis {
-  utxoCount: number;
-  fragmentationScore: number; // 0.0 to 1.0 (e.g. dustCount / totalUtxos)
-  dustCount: number;
-  totalValue: bigint;
-  recommendedActions: Recommendation[];
-}
-
-export interface ConsolidationPlan {
-  strategy: string;
-  inputs: Utxo[];
-  outputs: any[]; // Target outputs (usually one consolidated output back to the wallet)
-  estimatedFee: bigint;
-  estimatedSavings: bigint; // Approximated future fee savings
-  warnings: string[];
-}
-
-export interface SplitPlan extends ConsolidationPlan {
-  strategy: "split";
-}
-
-export interface MergePlan extends ConsolidationPlan {
-  strategy: "merge";
-}
-
-export interface SweepPlan extends ConsolidationPlan {
-  strategy: "sweep";
-}
-
-import { UtxoControlStore, UtxoControlState } from './stores/utxo-control-store.js';
-
-export interface UtxoListOpts { includeFrozen?: boolean | undefined }
-
-export class WalletUtxoApi {
-  constructor(
-    private readonly fetchUtxos: () => Promise<Utxo[]>,
-    private readonly address: () => Promise<string>,
-    private readonly estimateFee: (inputs: number, outputs: number) => Promise<bigint>,
-    private readonly store: UtxoControlStore
-  ) {}
-
-  /**
-   * List UTXOs currently available in the wallet.
-   * Frozen UTXOs are excluded by default unless includeFrozen: true.
-   */
-  async list(opts?: UtxoListOpts): Promise<Utxo[]> {
-    const all = await this.fetchUtxos();
-    const state = this.store.getState();
-    if (opts?.includeFrozen) {
-      return all;
-    }
-    return all.filter(u => !state.frozen[u.transactionId] && !state.frozen[`${u.transactionId}:${u.outputIndex}`]);
-  }
-
-  /**
-   * Return basic statistics about the UTXO set.
-   */
-  async statistics(opts?: UtxoListOpts): Promise<UtxoStatistics> {
-    const allUtxos = await this.fetchUtxos();
-    const state = this.store.getState();
-    
-    let totalUtxos = 0;
-    let availableUtxos = 0;
-    let frozenUtxos = 0;
-    
-    let totalValue = 0n;
-    let availableValue = 0n;
-    let frozenValue = 0n;
-    
-    let largest = -1n;
-    let smallest = -1n;
-
-    const includeFrozen = opts?.includeFrozen ?? false;
-
-    for (const u of allUtxos) {
-      const amt = BigInt(u.amountSompi);
-      const isFrozen = !!(state.frozen[u.transactionId] || state.frozen[`${u.transactionId}:${u.outputIndex}`]);
-
-      totalUtxos++;
-      totalValue += amt;
-
-      if (isFrozen) {
-        frozenUtxos++;
-        frozenValue += amt;
-      } else {
-        availableUtxos++;
-        availableValue += amt;
-      }
-
-      // Largest/smallest only counts what is included
-      if (includeFrozen || !isFrozen) {
-        if (largest === -1n || amt > largest) largest = amt;
-        if (smallest === -1n || amt < smallest) smallest = amt;
-      }
-    }
-
-    const countForAvg = includeFrozen ? totalUtxos : availableUtxos;
-    const valueForAvg = includeFrozen ? totalValue : availableValue;
-
-    return {
-      totalUtxos,
-      availableUtxos,
-      frozenUtxos,
-      totalValue,
-      availableValue,
-      frozenValue,
-      averageValue: countForAvg === 0 ? 0n : valueForAvg / BigInt(countForAvg),
-      largest: largest === -1n ? 0n : largest,
-      smallest: smallest === -1n ? 0n : smallest,
-      includeFrozen
-    };
-  }
-
-  /**
-   * Classify UTXOs into dust and normal based on a threshold.
-   * Default threshold: 10 KAS (1_000_000_000 sompi).
-   */
-  async analyzeDust(opts?: { thresholdSompi?: bigint, includeFrozen?: boolean | undefined }): Promise<DustAnalysis> {
-    const threshold = opts?.thresholdSompi ?? 1_000_000_000n;
-    const utxos = await this.list({ includeFrozen: opts?.includeFrozen });
-
-    const dustUtxos: Utxo[] = [];
-    const normalUtxos: Utxo[] = [];
-    let totalDustValue = 0n;
-
-    for (const u of utxos) {
-      const amt = BigInt(u.amountSompi);
-      if (amt < threshold) {
-        dustUtxos.push(u);
-        totalDustValue += amt;
-      } else {
-        normalUtxos.push(u);
-      }
-    }
-
-    return {
-      dustUtxos,
-      normalUtxos,
-      totalDustValue,
-      dustPercentage: utxos.length > 0 ? dustUtxos.length / utxos.length : 0
-    };
-  }
-
-  /**
-   * High-level diagnostic analysis of the wallet's UTXO health.
-   */
-  async analyze(opts?: UtxoListOpts): Promise<WalletAnalysis> {
-    const stats = await this.statistics(opts);
-    const dust = await this.analyzeDust(opts);
-
-    const fragmentationScore = dust.dustPercentage; 
-    const actions: Recommendation[] = [];
-    
-    // We base actions on available counts
-    const activeUtxoCount = opts?.includeFrozen ? stats.totalUtxos : stats.availableUtxos;
-
-    if (fragmentationScore > 0.5 && activeUtxoCount > 10) {
-      actions.push("consolidate");
-    } else if (dust.dustUtxos.length > 5) {
-      actions.push("mergeDust");
-    }
-    
-    // Simplistic threshold for splitLarge: if there are very few UTXOs but high value
-    if (activeUtxoCount < 3 && stats.largest > 10_000_000_000n) {
-      actions.push("splitLarge");
-    }
-
-    if (actions.length === 0) {
-      actions.push("none");
-    }
-
-    return {
-      utxoCount: activeUtxoCount,
-      fragmentationScore,
-      dustCount: dust.dustUtxos.length,
-      totalValue: opts?.includeFrozen ? stats.totalValue : stats.availableValue,
-      recommendedActions: actions
-    };
-  }
-
-  /**
-   * Plan a UTXO management operation without executing it.
-   */
-  async plan(opts: { strategy: "consolidation" | "split" | "sweep", includeFrozen?: boolean | undefined }): Promise<ConsolidationPlan> {
-    const utxos = await this.list({ includeFrozen: opts.includeFrozen });
-    const myAddress = await this.address();
-
-    if (opts.strategy === "consolidation") {
-      // In a real scenario, the CoinSelector would chunk this to respect mass limits.
-      // For Phase 1A, we will just select up to 84 (a safe mass limit approximation for Kaspa).
-      const MAX_INPUTS = 84;
-      
-      // Sort smallest first to consolidate dust
-      const sorted = [...utxos].sort((a, b) => (BigInt(a.amountSompi) < BigInt(b.amountSompi) ? -1 : 1));
-      const inputs = sorted.slice(0, MAX_INPUTS);
-
-      const estimatedFee = await this.estimateFee(inputs.length, 1);
-      
-      const totalInputValue = inputs.reduce((sum, u) => sum + BigInt(u.amountSompi), 0n);
-
-      const warnings: string[] = [];
-      if (inputs.length < 2) {
-        warnings.push("Not enough UTXOs to consolidate.");
-      }
-      if (totalInputValue <= estimatedFee) {
-        warnings.push("Consolidation fee exceeds the value of the selected UTXOs.");
-      }
-
-      // If we spent these 84 UTXOs individually in the future, we would pay for 1 input each time.
-      // 84 txs with 1 input vs 1 tx with 84 inputs.
-      // This is a naive calculation for "estimated savings".
-      const individualFee = await this.estimateFee(1, 2); 
-      const estimatedSavings = (individualFee * BigInt(inputs.length)) - estimatedFee;
-
-      return {
-        strategy: opts.strategy,
-        inputs,
-        outputs: [{ address: myAddress, amount: totalInputValue - estimatedFee }],
-        estimatedFee,
-        estimatedSavings: estimatedSavings > 0n ? estimatedSavings : 0n,
-        warnings
-      };
-    }
-
-    throw new Error(`Strategy '${opts.strategy}' not fully implemented yet.`);
-  }
-
-  /**
-   * Convenience alias for planning a consolidation.
-   */
-  async consolidate(opts?: { includeFrozen?: boolean | undefined }): Promise<ConsolidationPlan> {
-    return this.plan({ strategy: "consolidation", includeFrozen: opts?.includeFrozen });
-  }
-
-  private _assertNotFrozen(utxoId: string, includeFrozen?: boolean) {
-    if (!includeFrozen && this.store.getState().frozen[utxoId]) {
-      throw new Error(`UTXO ${utxoId} is frozen and cannot be planned for execution`);
-    }
-  }
-
-  /**
-   * Plans the splitting of a specific large UTXO.
-   * Supports symmetric splits (intoCount) OR asymmetric splits (outputs).
-   */
-  async splitPlan(opts: { 
-    utxoId: string;
-    intoCount?: number;
-    outputs?: { amountSompi: bigint }[];
-    includeFrozen?: boolean | undefined;
-  }): Promise<SplitPlan> {
-    this._assertNotFrozen(opts.utxoId, opts.includeFrozen);
-    const utxos = await this.list({ includeFrozen: opts.includeFrozen });
-    const targetUtxo = utxos.find(u => u.transactionId === opts.utxoId || `${u.transactionId}:${u.outputIndex}` === opts.utxoId);
-    
-    if (!targetUtxo) {
-      throw new Error(`UTXO ${opts.utxoId} not found in wallet.`);
-    }
-
-    const myAddress = await this.address();
-    const warnings: string[] = [];
-    const planOutputs: { address: string, amount: bigint }[] = [];
-    
-    const targetAmount = BigInt(targetUtxo.amountSompi);
-    let outputCount = 0;
-
-    if (opts.intoCount !== undefined && opts.outputs === undefined) {
-      outputCount = opts.intoCount;
-      if (outputCount < 2) throw new Error("splitPlan requires intoCount >= 2.");
-      
-      const estimatedFee = await this.estimateFee(1, outputCount);
-      const remainingAmount = targetAmount - estimatedFee;
-      
-      if (remainingAmount <= 0n) {
-        throw new Error("Target UTXO does not have enough funds to cover the split and fees.");
-      }
-
-      const chunkAmount = remainingAmount / BigInt(outputCount);
-      for (let i = 0; i < outputCount; i++) {
-        planOutputs.push({ address: myAddress, amount: chunkAmount });
-      }
-    } else if (opts.outputs !== undefined && opts.intoCount === undefined) {
-      outputCount = opts.outputs.length;
-      if (outputCount < 2) throw new Error("splitPlan requires outputs.length >= 2.");
-      
-      const estimatedFee = await this.estimateFee(1, outputCount + 1); // +1 for change
-      let sumOutputs = 0n;
-
-      for (const out of opts.outputs) {
-        sumOutputs += out.amountSompi;
-        planOutputs.push({ address: myAddress, amount: out.amountSompi });
-      }
-
-      const changeAmount = targetAmount - sumOutputs - estimatedFee;
-      if (changeAmount < 0n) {
-        throw new Error("Target UTXO does not have enough funds to cover the requested outputs and fees.");
-      }
-      
-      if (changeAmount > 0n) {
-        // Add change output
-        planOutputs.push({ address: myAddress, amount: changeAmount });
-      }
-    } else {
-      throw new Error("splitPlan requires exactly one of 'intoCount' or 'outputs' to be defined.");
-    }
-
-    const estimatedFee = await this.estimateFee(1, planOutputs.length);
-    
-    return {
-      strategy: "split",
-      inputs: [targetUtxo],
-      outputs: planOutputs,
-      estimatedFee,
-      estimatedSavings: 0n,
-      warnings
-    };
-  }
-
-  /**
-   * Plans the explicit merging of specific UTXOs.
-   */
-  async mergePlan(opts: { 
-    utxoIds: string[];
-    includeFrozen?: boolean | undefined;
-  }): Promise<MergePlan> {
-    for (const id of opts.utxoIds) {
-      this._assertNotFrozen(id, opts.includeFrozen);
-    }
-    const utxos = await this.list({ includeFrozen: opts.includeFrozen });
-    const inputs: Utxo[] = [];
-    
-    for (const id of opts.utxoIds) {
-      const u = utxos.find(utxo => utxo.transactionId === id || `${utxo.transactionId}:${utxo.outputIndex}` === id);
-      if (!u) {
-        throw new Error(`UTXO ${id} not found in wallet.`);
-      }
-      inputs.push(u);
-    }
-
-    if (inputs.length < 2) {
-      throw new Error("mergePlan requires at least 2 UTXOs to merge.");
-    }
-
-    const estimatedFee = await this.estimateFee(inputs.length, 1);
-    const totalInputValue = inputs.reduce((sum, u) => sum + BigInt(u.amountSompi), 0n);
-    const myAddress = await this.address();
-
-    const warnings: string[] = [];
-    if (totalInputValue <= estimatedFee) {
-      warnings.push("Merge fee exceeds the value of the selected UTXOs.");
-    }
-
-    const individualFee = await this.estimateFee(1, 2);
-    const estimatedSavings = (individualFee * BigInt(inputs.length)) - estimatedFee;
-
-    return {
-      strategy: "merge",
-      inputs,
-      outputs: [{ address: myAddress, amount: totalInputValue > estimatedFee ? totalInputValue - estimatedFee : 0n }],
-      estimatedFee,
-      estimatedSavings: estimatedSavings > 0n ? estimatedSavings : 0n,
-      warnings
-    };
-  }
-
-  /**
-   * Plans sweeping the entire wallet to a single destination address.
-   */
-  async sweepPlan(opts: { 
-    destinationAddress: string; 
-    includeFrozen?: boolean | undefined;
-  }): Promise<SweepPlan> {
-    const utxos = await this.list({ includeFrozen: opts.includeFrozen });
-    
-    if (utxos.length === 0) {
-      throw new Error("Cannot sweep an empty wallet.");
-    }
-
-    const estimatedFee = await this.estimateFee(utxos.length, 1);
-    const totalInputValue = utxos.reduce((sum, u) => sum + BigInt(u.amountSompi), 0n);
-    const warnings: string[] = [];
-
-    if (totalInputValue <= estimatedFee) {
-      warnings.push("Sweep fee exceeds the entire wallet balance.");
-    }
-
-    return {
-      strategy: "sweep",
-      inputs: utxos,
-      outputs: [{ address: opts.destinationAddress, amount: totalInputValue > estimatedFee ? totalInputValue - estimatedFee : 0n }],
-      estimatedFee,
-      estimatedSavings: 0n,
-      warnings
-    };
-  }
-
-  // --- Coin Control Persistence ---
-
-  async controlState(): Promise<UtxoControlState> {
-    return this.store.getState();
-  }
-
-  async freeze(utxoId: string, reason?: string): Promise<void> {
-    this.store.freeze(utxoId, reason);
-  }
-
-  async unfreeze(utxoId: string): Promise<void> {
-    this.store.unfreeze(utxoId);
-  }
-
-  public labels = {
-    set: async (utxoId: string, label: string): Promise<void> => {
-      this.store.setLabel(utxoId, label);
-    },
-    get: async (utxoId: string): Promise<string | undefined> => {
-      return this.store.getLabel(utxoId);
-    }
-  };
-
-  public notes = {
-    set: async (utxoId: string, note: string): Promise<void> => {
-      this.store.setNote(utxoId, note);
-    },
-    get: async (utxoId: string): Promise<string | undefined> => {
-      return this.store.getNote(utxoId);
-    }
-  };
-}

package/src/wallet.ts

@@ -1,158 +0,0 @@
-import { WalletManagerImpl, WalletStateStoreJson, AddressManager } from '@hardkas/accounts';
-import { WalletQuery, WalletQueryProvider } from '@hardkas/query';
-import { selectCoins, estimateFee, buildPaymentPlan } from '@hardkas/tx-builder';
-import { WalletUtxoApi } from './utxos.js';
-import { UtxoControlStore } from './stores/utxo-control-store.js';
-import { logger, metrics, tracer } from '@hardkas/observability';
-
-metrics.register({
-    name: "wallet_tx_generated_total",
-    help: "Total tx generated by wallet",
-    type: "counter"
-});
-metrics.register({
-    name: "wallet_tx_submitted_total",
-    help: "Total tx submitted by wallet",
-    type: "counter"
-});
-metrics.register({
-    name: "wallet_tx_failed_total",
-    help: "Total tx failed by wallet",
-    type: "counter"
-});
-
-export interface WalletToolkitOptions {
-    storePath?: string;
-    network?: "simnet" | "testnet" | "mainnet";
-    provider?: WalletQueryProvider;
-}
-
-export class WalletToolkit {
-    private walletManager: WalletManagerImpl;
-    private addressManager: typeof AddressManager;
-    private walletQuery: WalletQuery;
-
-    private _utxosApi: WalletUtxoApi;
-
-    private constructor(
-        public readonly name: string,
-        private readonly store: WalletStateStoreJson,
-        private readonly options: WalletToolkitOptions
-    ) {
-        this.walletManager = new WalletManagerImpl();
-        this.addressManager = AddressManager;
-        
-        const dummyProvider: WalletQueryProvider = {
-            source: "dummy",
-            async getBalances() { return {}; },
-            async getUtxos() { return {}; },
-            async getHistory() { return { items: [] }; }
-        };
-
-        this.walletQuery = new WalletQuery({ provider: options.provider || dummyProvider, network: options.network || "simnet" });
-        
-        const utxoControlPath = options.storePath 
-            ? options.storePath.replace('.json', '-utxo-control.json')
-            : 'default-utxo-control.json';
-        const utxoStore = new UtxoControlStore(utxoControlPath);
-
-        this._utxosApi = new WalletUtxoApi(
-            async () => {
-                const addr = await this.address();
-                const res = await this.walletQuery.getUtxos([addr]);
-                if (!res.ok) throw new Error(res.error || "Degraded query result");
-                return res.utxos[addr] || [];
-            },
-            async () => this.address(),
-            async (inputs: number, outputs: number) => BigInt(inputs * 1000 + outputs * 1000), // Dummy fee estimation
-            utxoStore
-        );
-    }
-
-    public static open(name: string, options: WalletToolkitOptions = {}): WalletToolkit {
-        const store = new WalletStateStoreJson({ filePath: options.storePath || 'default.json' });
-        return new WalletToolkit(name, store, options);
-    }
-
-    public async create(): Promise<void> {
-        this.walletManager.create({ walletId: this.name });
-    }
-
-    public async address(): Promise<string> {
-        // High level facade: gets receive address
-        const seedRef = this.walletManager.getSeedRef(this.name);
-        return this.addressManager.derive({ 
-            seedRef, 
-            accountIndex: 0,
-            chain: 'receive', 
-            addressIndex: 0, 
-            network: this.options.network || 'simnet' 
-        }).address;
-    }
-
-    public async balance(): Promise<bigint> {
-        const addr = await this.address();
-        return (await this.walletQuery.getBalance([addr])) as any;
-    }
-
-    public get utxos(): WalletUtxoApi {
-        return this._utxosApi;
-    }
-
-    public async history(): Promise<any[]> {
-        const addr = await this.address();
-        return (await this.walletQuery.getHistory({ addresses: [addr] })) as any;
-    }
-
-    public async estimateFee(opts: { to: string; amount: bigint; feeRate?: bigint }): Promise<{ fee: bigint; totalOut: bigint; plan: any }> {
-        const addr = await this.address();
-        const availableUtxos = await this.utxos.list();
-        
-        const plan = buildPaymentPlan({
-            fromAddress: addr,
-            outputs: [{ address: opts.to, amountSompi: opts.amount }],
-            availableUtxos: availableUtxos as any[],
-            feeRateSompiPerMass: opts.feeRate || 1n,
-            changeAddress: addr
-        });
-
-        return {
-            fee: plan.estimatedFeeSompi,
-            totalOut: opts.amount + plan.estimatedFeeSompi,
-            plan
-        };
-    }
-
-    public async planSend(opts: { to: string; amount: bigint; feeRate?: bigint }): Promise<any> {
-        try {
-            const { plan } = await this.estimateFee(opts);
-            metrics.inc("wallet_tx_generated_total");
-            logger.info("Wallet tx planned", { to: opts.to });
-            return plan;
-        } catch (e: any) {
-            metrics.inc("wallet_tx_failed_total");
-            logger.error("Wallet tx planning failed", { error: e.message });
-            throw e;
-        }
-    }
-
-    public async sendSimulated(opts: { to: string; amount: bigint; feeRate?: bigint }): Promise<string> {
-        const span = tracer.start("wallet.send", { to: opts.to });
-        try {
-            const plan = await this.planSend(opts);
-            const hashStr = `sim_tx_${Date.now()}_${plan.inputs.length}_${plan.outputs.length}`;
-            for (const u of plan.inputs) {
-                await this.utxos.freeze(`${u.outpoint.transactionId}:${u.outpoint.index}`, 'simulated_send');
-            }
-            metrics.inc("wallet_tx_submitted_total");
-            logger.info("Wallet tx simulated successfully", { txid: hashStr });
-            span.end({ txid: hashStr });
-            return hashStr;
-        } catch (e: any) {
-            metrics.inc("wallet_tx_failed_total");
-            logger.error("Wallet sendSimulated failed", { error: e.message });
-            span.fail(e);
-            throw e;
-        }
-    }
-}

package/test/silver.test.ts

@@ -1,59 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { SilverToolkit } from '../src/index.js';
-
-describe('SilverToolkit', () => {
-    it('should list all templates', () => {
-        const silver = SilverToolkit.open();
-        const templates = silver.templates();
-        expect(templates).toContain('htlc');
-        expect(templates).toContain('op-true');
-        expect(templates).toContain('multisig');
-    });
-
-    it('should extract template parameters', () => {
-        const silver = SilverToolkit.open();
-        const tpl = silver.template('htlc');
-        const params = tpl.parameters();
-        expect(params).toEqual(expect.arrayContaining(['secret_hash', 'receiver_pubkey', 'locktime', 'sender_pubkey']));
-    });
-
-    it('should fill template with parameters', () => {
-        const silver = SilverToolkit.open();
-        const tpl = silver.template('timelock');
-        const source = tpl.fill({ locktime: 500000, pubkey: 'abcd123' });
-        expect(source).toContain('500000 OP_CHECKLOCKTIMEVERIFY OP_DROP');
-        expect(source).toContain('abcd123 OP_CHECKSIG');
-    });
-
-    it('should throw if missing parameters during fill', () => {
-        const silver = SilverToolkit.open();
-        const tpl = silver.template('timelock');
-        expect(() => tpl.fill({ locktime: 500000 })).toThrow(/Missing parameter/);
-    });
-
-    it('should enforce restrictive claims on build', async () => {
-        const silver = SilverToolkit.open();
-        const build = await silver.build('OP_TRUE');
-        expect(build.bytecode).toBeDefined();
-        expect(build.claims.realSilverCompiler).toBe(false);
-        expect(build.claims.simulatedOnly).toBe(true);
-    });
-
-    it('should enforce restrictive claims on simulate, artifact, and evidence', async () => {
-        const silver = SilverToolkit.open();
-        const build = await silver.build('OP_TRUE');
-        
-        const simulation = await silver.simulate(build);
-        expect(simulation.claims.vmConsensusEquivalence).toBe(false);
-
-        const artifact = await silver.artifact(build, "test-script");
-        expect(artifact.claims.productionSafe).toBe(false);
-        expect(artifact.name).toBe("test-script");
-
-        const evidence = await silver.evidence(build, simulation);
-        expect(evidence.claims.mainnetReady).toBe(false);
-        expect(evidence.schema).toBe("hardkas.script-evidence.v1");
-        expect(evidence.simulationResult).not.toHaveProperty('claims'); // internal property
-        expect(evidence.simulationResult.success).toBe(true);
-    });
-});