@hardkas/tx-builder 0.8.20-alpha → 0.9.0-alpha

package/dist/index.d.ts

@@ -108,6 +108,48 @@ declare function verifyTxReceiptSemantics(receipt: any): {
     issues: SemanticVerificationIssue[];
 };
 
+interface UtxoProvider {
+    getUtxos(address: string): Promise<Utxo[]>;
+    getVirtualDaaScore?(): Promise<bigint>;
+}
+interface TxPlanServiceOptions {
+    maxInputsPerTx?: number;
+    warnInputs?: number;
+    marginFeePerInput?: bigint;
+    coinbaseMaturity?: bigint;
+}
+interface PlanTransactionRequest {
+    fromAddress: string;
+    toAddress: string;
+    amountSompi: bigint;
+    feeRate?: bigint;
+}
+interface ConsolidationRequest {
+    fromAddress: string;
+    selectedUtxos: Utxo[];
+    toAddress: string;
+    feeRate?: bigint;
+}
+interface TxPlanResult {
+    plan: TxPlan;
+    utxoSelection: {
+        totalUtxosSeen: number;
+        selectedUtxos: number;
+        selectionStrategy: "largest-first" | "consolidation-smallest-first";
+        purpose?: "wallet-consolidation";
+    };
+}
+declare class TxPlanService {
+    private provider;
+    readonly maxInputsPerTx: number;
+    readonly warnInputs: number;
+    readonly marginFeePerInput: bigint;
+    readonly coinbaseMaturity: bigint;
+    constructor(provider: UtxoProvider, options?: TxPlanServiceOptions);
+    planTransaction(request: PlanTransactionRequest): Promise<TxPlanResult>;
+    planConsolidation(request: ConsolidationRequest): Promise<TxPlanResult>;
+}
+
 type Sompi = bigint;
 
 interface Outpoint {
@@ -155,4 +197,4 @@ declare function createMockUtxo(input: {
     readonly index?: number;
 }): Utxo;
 
-export { DUST_THRESHOLD_SOMPI, KASPA_MASS_CONSTANTS, type MassBreakdown, type MassEstimateResult, type Outpoint, type SemanticVerificationIssue, type SemanticVerificationResult, type SemanticVerificationSeverity, type SemanticVerifyContext, type Sompi, type TxBuildRequest, type TxOutput, type TxPlan, type Utxo, buildPaymentPlan, createMockUtxo, estimateFeeFromMass, estimateMass, estimateTransactionMass, verifySignedTxSemantics, verifyTxPlanSemantics, verifyTxReceiptSemantics };
+export { type ConsolidationRequest, DUST_THRESHOLD_SOMPI, KASPA_MASS_CONSTANTS, type MassBreakdown, type MassEstimateResult, type Outpoint, type PlanTransactionRequest, type SemanticVerificationIssue, type SemanticVerificationResult, type SemanticVerificationSeverity, type SemanticVerifyContext, type Sompi, type TxBuildRequest, type TxOutput, type TxPlan, type TxPlanResult, TxPlanService, type TxPlanServiceOptions, type Utxo, type UtxoProvider, buildPaymentPlan, createMockUtxo, estimateFeeFromMass, estimateMass, estimateTransactionMass, verifySignedTxSemantics, verifyTxPlanSemantics, verifyTxReceiptSemantics };

package/dist/index.js

@@ -278,6 +278,129 @@ function verifyTxReceiptSemantics(receipt) {
   };
 }
 
+// src/service.ts
+var TxPlanService = class {
+  constructor(provider, options = {}) {
+    this.provider = provider;
+    this.maxInputsPerTx = options.maxInputsPerTx ?? 512;
+    this.warnInputs = options.warnInputs ?? 128;
+    this.marginFeePerInput = options.marginFeePerInput ?? 1500n;
+    this.coinbaseMaturity = options.coinbaseMaturity ?? 1000n;
+  }
+  provider;
+  maxInputsPerTx;
+  warnInputs;
+  marginFeePerInput;
+  coinbaseMaturity;
+  async planTransaction(request) {
+    const rpcUtxos = await this.provider.getUtxos(request.fromAddress);
+    let virtualDaaScore;
+    if (this.provider.getVirtualDaaScore) {
+      try {
+        virtualDaaScore = await this.provider.getVirtualDaaScore();
+      } catch {
+      }
+    }
+    const matureUtxos = virtualDaaScore !== void 0 ? rpcUtxos.filter((u) => {
+      if (!u.isCoinbase) return true;
+      const score = u.blockDaaScore;
+      if (score === void 0) return true;
+      return virtualDaaScore - score >= this.coinbaseMaturity;
+    }) : rpcUtxos;
+    const allFetchedUtxos = matureUtxos;
+    const sortedUtxos = [...allFetchedUtxos].sort((a, b) => {
+      if (a.amountSompi > b.amountSompi) return -1;
+      if (a.amountSompi < b.amountSompi) return 1;
+      return 0;
+    });
+    const feeRate = request.feeRate ?? 1n;
+    const marginFee = this.marginFeePerInput * feeRate;
+    let selectedAmount = 0n;
+    let selectedInputsCount = 0;
+    const builderUtxos = [];
+    const HARD_LIMIT = 1e3;
+    for (const utxo of sortedUtxos) {
+      builderUtxos.push(utxo);
+      selectedAmount += utxo.amountSompi;
+      selectedInputsCount++;
+      const requiredTotal = request.amountSompi + BigInt(selectedInputsCount) * marginFee;
+      if (selectedAmount >= requiredTotal) {
+        break;
+      }
+      if (selectedInputsCount >= HARD_LIMIT) {
+        break;
+      }
+    }
+    if (selectedAmount < request.amountSompi) {
+      throw new Error(`Insufficient funds: needed ${request.amountSompi} sompi but only found ${selectedAmount} sompi across ${selectedInputsCount} UTXOs.`);
+    }
+    if (selectedInputsCount > this.maxInputsPerTx) {
+      const err = new Error(`TOO_MANY_INPUTS_FOR_SINGLE_TX: Transaction requires ${selectedInputsCount} inputs to cover the amount, which exceeds the safe limit of ${this.maxInputsPerTx} inputs.
+Hint: Run 'hardkas accounts consolidate' to merge dust UTXOs.`);
+      err.code = "TOO_MANY_INPUTS_FOR_SINGLE_TX";
+      throw err;
+    }
+    if (selectedInputsCount >= this.warnInputs) {
+      console.warn(`\u26A0\uFE0F  WARNING: Transaction requires ${selectedInputsCount} inputs. Consider running 'hardkas accounts consolidate'.`);
+    }
+    const builderPlan = buildPaymentPlan({
+      fromAddress: request.fromAddress,
+      availableUtxos: builderUtxos,
+      outputs: [
+        {
+          address: request.toAddress,
+          amountSompi: request.amountSompi
+        }
+      ],
+      feeRateSompiPerMass: feeRate
+    });
+    return {
+      plan: builderPlan,
+      utxoSelection: {
+        totalUtxosSeen: allFetchedUtxos.length,
+        selectedUtxos: selectedInputsCount,
+        selectionStrategy: "largest-first"
+      }
+    };
+  }
+  async planConsolidation(request) {
+    let totalAmount = 0n;
+    const builderUtxos = request.selectedUtxos.map((u) => {
+      const amount = BigInt(u.amountSompi);
+      totalAmount += amount;
+      return u;
+    });
+    const feeRate = request.feeRate ?? 1n;
+    const massPerInput = 1500n;
+    const estimatedMass = BigInt(request.selectedUtxos.length) * massPerInput + 500n;
+    const expectedFee = estimatedMass * feeRate;
+    if (totalAmount <= expectedFee) {
+      throw new Error(`Consolidation failed: Total selected UTXO amount (${totalAmount}) is less than or equal to the estimated fee (${expectedFee}).`);
+    }
+    const outputAmount = totalAmount - expectedFee;
+    const builderPlan = buildPaymentPlan({
+      fromAddress: request.fromAddress,
+      availableUtxos: builderUtxos,
+      outputs: [
+        {
+          address: request.toAddress,
+          amountSompi: outputAmount
+        }
+      ],
+      feeRateSompiPerMass: feeRate
+    });
+    return {
+      plan: builderPlan,
+      utxoSelection: {
+        totalUtxosSeen: request.selectedUtxos.length,
+        selectedUtxos: request.selectedUtxos.length,
+        selectionStrategy: "consolidation-smallest-first",
+        purpose: "wallet-consolidation"
+      }
+    };
+  }
+};
+
 // src/index.ts
 function buildPaymentPlan(request) {
   if (request.outputs.length === 0) {
@@ -379,6 +502,7 @@ function createMockUtxo(input) {
 export {
   DUST_THRESHOLD_SOMPI,
   KASPA_MASS_CONSTANTS,
+  TxPlanService,
   buildPaymentPlan,
   createMockUtxo,
   estimateFeeFromMass,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/tx-builder",
-  "version": "0.8.20-alpha",
+  "version": "0.9.0-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,7 +12,7 @@
     }
   },
   "dependencies": {
-    "@hardkas/core": "0.8.20-alpha"
+    "@hardkas/core": "0.9.0-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",