@hardkas/sdk 0.8.15-alpha → 0.8.18-alpha

package/dist/index.d.ts

@@ -70,6 +70,18 @@ declare class HardkasTx {
         networkProfile?: string;
         assumption?: string;
     }): Promise<TxPlanArtifact>;
+    /**
+     * Creates a transaction plan explicitly for consolidation.
+     * This overrides normal selection logic and uses precisely the provided UTXOs.
+     */
+    createConsolidationPlan(options: {
+        account: HardkasAccount | string;
+        selectedUtxos: any[];
+        destination: string;
+        network?: string;
+        feeRate?: bigint;
+        totalUtxosSeen?: number;
+    }): Promise<TxPlanArtifact>;
     /**
      * Signs a transaction plan.
      */

package/dist/index.js

@@ -23,7 +23,7 @@ var HardkasAccounts = class {
   async resolve(nameOrAddress) {
     return resolveHardkasAccount({
       nameOrAddress,
-      config: this.sdk.config.config
+      config: { ...this.sdk.config.config, cwd: this.sdk.workspace.root }
     });
   }
   /**
@@ -106,7 +106,7 @@ import {
   getBroadcastableSignedTransaction
 } from "@hardkas/artifacts";
 import { coreEvents } from "@hardkas/core";
-import { signTxPlanArtifact } from "@hardkas/accounts";
+import { signTxPlanArtifact, validateAddressNetwork } from "@hardkas/accounts";
 import { parseKasToSompi } from "@hardkas/core";
 function normalizeSimulatedPlanInput(target, fallbackId) {
   if (target.schema === ARTIFACT_SCHEMAS.TX_PLAN && Array.isArray(target.inputs)) {
@@ -158,15 +158,21 @@ var HardkasTx = class {
     if (amountSompi === 0n) {
       throw new Error("Kaspa value-transfer outputs require amount > 0.\nFor metadata/notary/DID marker transactions use --amount 1.\nFuture: hardkas tx anchor.");
     }
-    let builderUtxos = [];
     const activeNetwork = this.sdk.config.config.defaultNetwork || "simnet";
+    const allowMainnet = this.sdk.config.config.networks?.mainnet?.allowMainnet === true;
+    validateAddressNetwork(fromAccount.address, activeNetwork, allowMainnet);
+    validateAddressNetwork(toAccount.address, activeNetwork, allowMainnet);
+    if (options.changeAddress) {
+      validateAddressNetwork(options.changeAddress, activeNetwork, allowMainnet);
+    }
+    let allFetchedUtxos = [];
     if (activeNetwork === "simulated" || this.sdk.config.config.networks?.[activeNetwork]?.kind === "simulated") {
       const { loadOrCreateLocalnetState, getSpendableUtxos } = await import("@hardkas/localnet");
       const localState = await loadOrCreateLocalnetState({
         cwd: this.sdk.workspace.root
       });
       const unspent = getSpendableUtxos(localState, fromAccount.address);
-      builderUtxos = unspent.map((u) => {
+      allFetchedUtxos = unspent.map((u) => {
         const parts = u.id.split(":");
         const index = Number(parts[parts.length - 1]);
         const transactionId = parts.slice(0, -1).join(":");
@@ -179,16 +185,52 @@ var HardkasTx = class {
       });
     } else {
       const rpcUtxos = await this.sdk.rpc.getUtxosByAddress(fromAccount.address);
-      builderUtxos = rpcUtxos.map((u) => ({
+      allFetchedUtxos = rpcUtxos.map((u) => ({
         outpoint: {
           transactionId: u.outpoint.transactionId,
           index: u.outpoint.index
         },
         address: u.address,
-        amountSompi: u.amountSompi,
+        amountSompi: BigInt(u.amountSompi),
         scriptPublicKey: u.scriptPublicKey || ""
       }));
     }
+    const sortedUtxos = [...allFetchedUtxos].sort((a, b) => {
+      if (a.amountSompi > b.amountSompi) return -1;
+      if (a.amountSompi < b.amountSompi) return 1;
+      return 0;
+    });
+    const MAX_INPUTS_PER_TX = 512;
+    const WARN_INPUTS = 128;
+    const HARD_LIMIT = 1e3;
+    const MARGIN_FEE_PER_INPUT = 1500n * (options.feeRate ?? 1n);
+    let selectedAmount = 0n;
+    let selectedInputsCount = 0;
+    const builderUtxos = [];
+    for (const utxo of sortedUtxos) {
+      builderUtxos.push(utxo);
+      selectedAmount += utxo.amountSompi;
+      selectedInputsCount++;
+      const requiredTotal = amountSompi + BigInt(selectedInputsCount) * MARGIN_FEE_PER_INPUT;
+      if (selectedAmount >= requiredTotal) {
+        break;
+      }
+      if (selectedInputsCount >= HARD_LIMIT) {
+        break;
+      }
+    }
+    if (selectedAmount < amountSompi) {
+      throw new Error(`Insufficient funds: needed ${amountSompi} sompi but only found ${selectedAmount} sompi across ${selectedInputsCount} UTXOs.`);
+    }
+    if (selectedInputsCount > MAX_INPUTS_PER_TX) {
+      const err = new Error(`TOO_MANY_INPUTS_FOR_SINGLE_TX: Transaction requires ${selectedInputsCount} inputs to cover the amount, which exceeds the safe limit of ${MAX_INPUTS_PER_TX} inputs.
+Hint: Run 'hardkas accounts consolidate' to merge dust UTXOs.`);
+      err.code = "TOO_MANY_INPUTS_FOR_SINGLE_TX";
+      throw err;
+    }
+    if (selectedInputsCount >= WARN_INPUTS) {
+      console.warn(`\u26A0\uFE0F  WARNING: Transaction requires ${selectedInputsCount} inputs. Consider running 'hardkas accounts consolidate'.`);
+    }
     const builderPlan = buildPaymentPlan({
       fromAddress: fromAccount.address,
       availableUtxos: builderUtxos,
@@ -228,7 +270,12 @@ var HardkasTx = class {
       ctx: {
         ...systemRuntimeContext,
         ...options.workflowId ? { workflowId: options.workflowId } : {},
-        assumptionLevel: resolvedAssumptionLevel
+        assumptionLevel: resolvedAssumptionLevel,
+        utxoSelection: {
+          totalUtxosSeen: allFetchedUtxos.length,
+          selectedUtxos: selectedInputsCount,
+          selectionStrategy: "largest-first"
+        }
       }
     });
     if (options.policy || options.policies) {
@@ -281,6 +328,96 @@ var HardkasTx = class {
     }
     return basePlan;
   }
+  /**
+   * Creates a transaction plan explicitly for consolidation.
+   * This overrides normal selection logic and uses precisely the provided UTXOs.
+   */
+  async createConsolidationPlan(options) {
+    let resolvedAccount;
+    if (typeof options.account === "string") {
+      resolvedAccount = await this.sdk.accounts.resolve(options.account);
+    } else {
+      resolvedAccount = options.account;
+    }
+    if (!resolvedAccount.address) {
+      throw new Error(`Account '${resolvedAccount.name || options.account}' has no address.`);
+    }
+    const activeNetwork = options.network || this.sdk.config.config.defaultNetwork || "simnet";
+    const isSimulated = activeNetwork === "simulated" || this.sdk.config.config.networks?.[activeNetwork]?.kind === "simulated";
+    let totalAmount = 0n;
+    const builderUtxos = options.selectedUtxos.map((u) => {
+      const amount = BigInt(u.amountSompi);
+      totalAmount += amount;
+      return {
+        outpoint: {
+          transactionId: u.outpoint.transactionId,
+          index: u.outpoint.index
+        },
+        address: u.address,
+        amountSompi: amount,
+        scriptPublicKey: u.scriptPublicKey || ""
+      };
+    });
+    const feeRate = options.feeRate ?? 1n;
+    const massPerInput = 1500n;
+    const estimatedMass = BigInt(options.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: resolvedAccount.address,
+      availableUtxos: builderUtxos,
+      outputs: [
+        {
+          address: options.destination,
+          amountSompi: outputAmount
+        }
+      ],
+      feeRateSompiPerMass: feeRate
+    });
+    let resolvedAssumptionLevel = isSimulated ? "local-simulated" : "local-rpc";
+    const basePlan = createTxPlanArtifact({
+      networkId: activeNetwork,
+      mode: isSimulated ? "simulated" : "real",
+      from: {
+        input: resolvedAccount.name || resolvedAccount.address,
+        address: resolvedAccount.address,
+        accountName: resolvedAccount.name
+      },
+      to: {
+        input: options.destination,
+        address: options.destination
+      },
+      amountSompi: outputAmount,
+      plan: builderPlan,
+      ctx: {
+        ...systemRuntimeContext,
+        assumptionLevel: resolvedAssumptionLevel,
+        utxoSelection: {
+          strategy: "consolidation-smallest-first",
+          totalUtxosSeen: options.totalUtxosSeen ?? options.selectedUtxos.length,
+          selectedUtxos: options.selectedUtxos.length,
+          purpose: "wallet-consolidation"
+        }
+      }
+    });
+    const { CURRENT_HASH_VERSION: CURRENT_HASH_VERSION2, calculateContentHash: calculateContentHash2 } = await import("@hardkas/artifacts");
+    const newHash = calculateContentHash2(basePlan, CURRENT_HASH_VERSION2);
+    basePlan.contentHash = newHash;
+    if (basePlan.lineage) {
+      basePlan.lineage.lineageId = newHash;
+      basePlan.lineage.parentArtifactId = "";
+      basePlan.lineage.rootArtifactId = newHash;
+      const finalHash = calculateContentHash2(basePlan, CURRENT_HASH_VERSION2);
+      basePlan.contentHash = finalHash;
+      basePlan.lineage.artifactId = finalHash;
+      basePlan.planId = `plan-${finalHash.slice(0, 16)}`;
+    }
+    this.sdk.artifacts.cacheArtifact(basePlan);
+    return basePlan;
+  }
   /**
    * Signs a transaction plan.
    */
@@ -652,6 +789,9 @@ var HardkasTx = class {
       tracePath,
       ...planArtifact.workflowId ? { workflowId: planArtifact.workflowId } : {},
       ...planArtifact.assumptionLevel ? { assumptionLevel: planArtifact.assumptionLevel } : {},
+      ...planArtifact.policyRefs ? { policyRefs: planArtifact.policyRefs } : {},
+      ...planArtifact.networkProfileRef ? { networkProfileRef: planArtifact.networkProfileRef } : {},
+      ...planArtifact.assumptionRef ? { assumptionRef: planArtifact.assumptionRef } : {},
       lineage: {
         artifactId: "",
         // To be computed
@@ -814,6 +954,10 @@ var HardkasTx = class {
       submittedAt: (/* @__PURE__ */ new Date()).toISOString(),
       ...url ? { rpcUrl: url } : {},
       ...signedArtifact.workflowId ? { workflowId: signedArtifact.workflowId } : {},
+      ...signedArtifact.assumptionLevel ? { assumptionLevel: signedArtifact.assumptionLevel } : {},
+      ...signedArtifact.policyRefs ? { policyRefs: signedArtifact.policyRefs } : {},
+      ...signedArtifact.networkProfileRef ? { networkProfileRef: signedArtifact.networkProfileRef } : {},
+      ...signedArtifact.assumptionRef ? { assumptionRef: signedArtifact.assumptionRef } : {},
       tracePath: void 0,
       lineage: createLineageTransition(signedArtifact, "hardkas.txReceipt")
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/sdk",
-  "version": "0.8.15-alpha",
+  "version": "0.8.18-alpha",
   "type": "module",
   "files": [
     "dist",
@@ -24,22 +24,22 @@
   },
   "dependencies": {
     "@kaspa/core-lib": "^1.6.5",
-    "@hardkas/accounts": "0.8.15-alpha",
-    "@hardkas/artifacts": "0.8.15-alpha",
-    "@hardkas/config": "0.8.15-alpha",
-    "@hardkas/kaspa-rpc": "0.8.15-alpha",
-    "@hardkas/core": "0.8.15-alpha",
-    "@hardkas/l2": "0.8.15-alpha",
-    "@hardkas/localnet": "0.8.15-alpha",
-    "@hardkas/query": "0.8.15-alpha",
-    "@hardkas/query-store": "0.8.15-alpha",
-    "@hardkas/tx-builder": "0.8.15-alpha",
-    "@hardkas/simulator": "0.8.15-alpha",
-    "@hardkas/wallet-adapter": "0.8.15-alpha"
+    "@hardkas/artifacts": "0.8.18-alpha",
+    "@hardkas/core": "0.8.18-alpha",
+    "@hardkas/config": "0.8.18-alpha",
+    "@hardkas/accounts": "0.8.18-alpha",
+    "@hardkas/kaspa-rpc": "0.8.18-alpha",
+    "@hardkas/l2": "0.8.18-alpha",
+    "@hardkas/query": "0.8.18-alpha",
+    "@hardkas/localnet": "0.8.18-alpha",
+    "@hardkas/query-store": "0.8.18-alpha",
+    "@hardkas/simulator": "0.8.18-alpha",
+    "@hardkas/tx-builder": "0.8.18-alpha",
+    "@hardkas/wallet-adapter": "0.8.18-alpha"
   },
   "devDependencies": {
-    "tsup": "^8.3.5",
     "@types/node": "^20.12.7",
+    "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
   },