@hardkas/sdk 0.8.20-alpha → 0.9.0-alpha

package/README.md

@@ -1,40 +1,51 @@
 # `@hardkas/sdk`
 
-The HardKAS SDK acts as the programmatic boundary between developer scripts and the isolated HardKAS runtime engine.
+The HardKas SDK is the programmatic API for local-first transaction workflows. It exposes the same core model as the CLI: plan, sign, simulate or send, then inspect artifacts and lineage.
 
-## 1. Bootstrapping Variants
+## 1. Create A Local SDK
 
-The SDK injects dependencies via a `RuntimeContext` container. This container abstracts the filesystem, logging, and RPC configurations.
-
-### Flow: Auto-Bootstrap
 ```typescript
-const sdk = await Hardkas.create({ autoBootstrap: true });
+import { Hardkas } from "@hardkas/sdk";
+
+const sdk = await Hardkas.create({
+  cwd: process.cwd(),
+  autoBootstrap: true,
+  network: "simulated"
+});
 ```
-1. The engine scans upward from `process.cwd()` to find `.hardkas/`.
-2. It acquires necessary read/write workspace locks.
-3. If the workspace does not exist, it automatically creates it, generating a new developer identity and local configuration.
 
-### Variant: Manual Policy Engine
-When running inside an AI agent (like KI) or CI environment, `autoBootstrap` is disabled.
-1. The SDK enforces the 4 Policy Dimensions (Local isolation, Determinism, Replayability, Mainnet Guards).
-2. It calls `hardkas doctor --json` internally before initializing.
-3. If the environment fails policy checks (e.g., trying to write to mainnet without the explicit `--unsafe-mainnet` flag), the instantiation throws synchronously.
+`autoBootstrap: true` is the easiest local path. It creates or loads the workspace data needed for simulated accounts, artifacts, and local execution.
+
+## 2. Transaction Flow
 
-## 2. Transaction Flow & Dry-Runs
+```typescript
+const plan = await sdk.tx.plan({
+  from: "alice",
+  to: "bob",
+  amount: "1",
+  network: "simulated"
+});
+
+const signed = await sdk.tx.sign(plan, {
+  account: "alice"
+});
+
+const receipt = await sdk.tx.simulate(signed);
+```
 
-All SDK transaction methods follow the Plan -> Sign -> Broadcast pipeline.
+For a real RPC-backed node, create the SDK with an explicit network/provider configuration and treat the send step as network-state dependent. Mainnet should remain outside the default local development flow.
 
-### Flow: `sdk.tx.plan`
-1. The SDK calculates the deterministic payload size.
-2. It interacts with the `Query Store` to fetch available UXTOs (for L1) or Nonces (for L2).
-3. It emits a `PlanCreated` event to the `events.jsonl` ledger.
-4. It persists a `TxPlan` artifact in `.hardkas/artifacts/`.
+## 3. Artifacts And Queries
+
+The SDK can read artifacts, trace lineage, replay local records, and query the local projection:
 
-### Variant: Dry-Run Execution
 ```typescript
-const plan = await sdk.tx.plan({ to, amount, dryRun: true });
+const artifacts = await sdk.query.artifacts.list();
+const trace = await sdk.lineage.trace(receipt.txId);
 ```
-1. The SDK skips steps 3 and 4.
-2. No locks are acquired.
-3. No events are emitted to the append-only ledger.
-4. The plan is returned purely in-memory as a preview object, which throws an exception if you attempt to pass it into `sdk.tx.sign`.
+
+The SQLite query store is rebuildable. The durable source of truth is the workspace artifact and event data.
+
+## 4. Boundary
+
+The SDK should be used from Node.js. Browser applications should talk to the dev server through `@hardkas/client`, not import `@hardkas/sdk` directly.

package/dist/index.js

@@ -90,7 +90,6 @@ var HardkasAccounts = class {
 // src/tx.ts
 import { systemRuntimeContext, deterministicCompare } from "@hardkas/core";
 import {
-  buildPaymentPlan,
   verifySignedTxSemantics
 } from "@hardkas/tx-builder";
 import {
@@ -108,6 +107,7 @@ import {
 import { coreEvents } from "@hardkas/core";
 import { signTxPlanArtifact, validateAddressNetwork } from "@hardkas/accounts";
 import { parseKasToSompi } from "@hardkas/core";
+import { TxPlanService } from "@hardkas/tx-builder";
 function normalizeSimulatedPlanInput(target, fallbackId) {
   if (target.schema === ARTIFACT_SCHEMAS.TX_PLAN && Array.isArray(target.inputs)) {
     return target;
@@ -165,96 +165,55 @@ var HardkasTx = class {
     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);
-      allFetchedUtxos = unspent.map((u) => {
-        const parts = u.id.split(":");
-        const index = Number(parts[parts.length - 1]);
-        const transactionId = parts.slice(0, -1).join(":");
-        return {
-          outpoint: { transactionId, index },
-          address: u.address,
-          amountSompi: BigInt(u.amountSompi),
-          scriptPublicKey: "mock-script"
-        };
-      });
-    } else {
-      const rpcUtxos = await this.sdk.rpc.getUtxosByAddress(fromAccount.address);
-      const COINBASE_MATURITY = 1000n;
-      let virtualDaaScore;
-      try {
-        const dagInfo = await this.sdk.rpc.getBlockDagInfo();
-        virtualDaaScore = dagInfo.virtualDaaScore;
-      } catch {
-      }
-      const matureUtxos = virtualDaaScore !== void 0 ? rpcUtxos.filter((u) => {
-        if (!u.isCoinbase) return true;
-        const score = u.blockDaaScore !== void 0 ? BigInt(u.blockDaaScore) : void 0;
-        if (score === void 0) return true;
-        return virtualDaaScore - score >= COINBASE_MATURITY;
-      }) : rpcUtxos;
-      allFetchedUtxos = matureUtxos.map((u) => ({
-        outpoint: {
-          transactionId: u.outpoint.transactionId,
-          index: u.outpoint.index
-        },
-        address: u.address,
-        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;
+    const utxoProvider = {
+      getUtxos: async (address) => {
+        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, address);
+          return unspent.map((u) => {
+            const parts = u.id.split(":");
+            const index = Number(parts[parts.length - 1]);
+            const transactionId = parts.slice(0, -1).join(":");
+            return {
+              outpoint: { transactionId, index },
+              address: u.address,
+              amountSompi: BigInt(u.amountSompi),
+              scriptPublicKey: "mock-script"
+            };
+          });
+        } else {
+          const rpcUtxos = await this.sdk.rpc.getUtxosByAddress(address);
+          return rpcUtxos.map((u) => ({
+            outpoint: {
+              transactionId: u.outpoint.transactionId,
+              index: u.outpoint.index
+            },
+            address: u.address,
+            amountSompi: BigInt(u.amountSompi),
+            scriptPublicKey: u.scriptPublicKey || "",
+            blockDaaScore: u.blockDaaScore !== void 0 ? BigInt(u.blockDaaScore) : void 0,
+            isCoinbase: u.isCoinbase
+          }));
+        }
+      },
+      getVirtualDaaScore: async () => {
+        try {
+          const dagInfo = await this.sdk.rpc.getBlockDagInfo();
+          return dagInfo.virtualDaaScore;
+        } catch {
+          return void 0;
+        }
       }
-    }
-    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({
+    };
+    const planService = new TxPlanService(utxoProvider);
+    const result = await planService.planTransaction({
       fromAddress: fromAccount.address,
-      availableUtxos: builderUtxos,
-      outputs: [
-        {
-          address: toAccount.address,
-          amountSompi
-        }
-      ],
-      feeRateSompiPerMass: options.feeRate ?? 1n
+      toAddress: toAccount.address,
+      amountSompi,
+      ...options.feeRate !== void 0 ? { feeRate: options.feeRate } : {}
     });
+    const builderPlan = result.plan;
     const isSimulated = activeNetwork === "simulated" || this.sdk.config.config.networks?.[activeNetwork]?.kind === "simulated";
     let resolvedAssumptionLevel = options.assumption;
     if (!resolvedAssumptionLevel) {
@@ -284,11 +243,7 @@ Hint: Run 'hardkas accounts consolidate' to merge dust UTXOs.`);
         ...systemRuntimeContext,
         ...options.workflowId ? { workflowId: options.workflowId } : {},
         assumptionLevel: resolvedAssumptionLevel,
-        utxoSelection: {
-          totalUtxosSeen: allFetchedUtxos.length,
-          selectedUtxos: selectedInputsCount,
-          selectionStrategy: "largest-first"
-        }
+        utxoSelection: result.utxoSelection
       }
     });
     if (options.policy || options.policies) {
@@ -357,39 +312,22 @@ Hint: Run 'hardkas accounts consolidate' to merge dust UTXOs.`);
     }
     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({
+    const dummyProvider = {
+      getUtxos: async () => []
+    };
+    const planService = new TxPlanService(dummyProvider);
+    const result = await planService.planConsolidation({
       fromAddress: resolvedAccount.address,
-      availableUtxos: builderUtxos,
-      outputs: [
-        {
-          address: options.destination,
-          amountSompi: outputAmount
-        }
-      ],
-      feeRateSompiPerMass: feeRate
+      selectedUtxos: options.selectedUtxos,
+      toAddress: options.destination,
+      ...options.feeRate !== void 0 ? { feeRate: options.feeRate } : {}
     });
+    const builderPlan = result.plan;
+    const firstOutput = builderPlan.outputs[0];
+    if (!firstOutput) {
+      throw new Error("Consolidation failed: transaction builder produced no outputs.");
+    }
+    const outputAmount = firstOutput.amountSompi;
     let resolvedAssumptionLevel = isSimulated ? "local-simulated" : "local-rpc";
     const basePlan = createTxPlanArtifact({
       networkId: activeNetwork,
@@ -409,10 +347,10 @@ Hint: Run 'hardkas accounts consolidate' to merge dust UTXOs.`);
         ...systemRuntimeContext,
         assumptionLevel: resolvedAssumptionLevel,
         utxoSelection: {
-          strategy: "consolidation-smallest-first",
+          strategy: result.utxoSelection.selectionStrategy,
           totalUtxosSeen: options.totalUtxosSeen ?? options.selectedUtxos.length,
-          selectedUtxos: options.selectedUtxos.length,
-          purpose: "wallet-consolidation"
+          selectedUtxos: result.utxoSelection.selectedUtxos,
+          purpose: result.utxoSelection.purpose
         }
       }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/sdk",
-  "version": "0.8.20-alpha",
+  "version": "0.9.0-alpha",
   "type": "module",
   "files": [
     "dist",
@@ -24,18 +24,18 @@
   },
   "dependencies": {
     "@kaspa/core-lib": "^1.6.5",
-    "@hardkas/config": "0.8.20-alpha",
-    "@hardkas/artifacts": "0.8.20-alpha",
-    "@hardkas/accounts": "0.8.20-alpha",
-    "@hardkas/core": "0.8.20-alpha",
-    "@hardkas/localnet": "0.8.20-alpha",
-    "@hardkas/query": "0.8.20-alpha",
-    "@hardkas/l2": "0.8.20-alpha",
-    "@hardkas/query-store": "0.8.20-alpha",
-    "@hardkas/simulator": "0.8.20-alpha",
-    "@hardkas/tx-builder": "0.8.20-alpha",
-    "@hardkas/kaspa-rpc": "0.8.20-alpha",
-    "@hardkas/wallet-adapter": "0.8.20-alpha"
+    "@hardkas/config": "0.9.0-alpha",
+    "@hardkas/artifacts": "0.9.0-alpha",
+    "@hardkas/accounts": "0.9.0-alpha",
+    "@hardkas/kaspa-rpc": "0.9.0-alpha",
+    "@hardkas/localnet": "0.9.0-alpha",
+    "@hardkas/query": "0.9.0-alpha",
+    "@hardkas/core": "0.9.0-alpha",
+    "@hardkas/l2": "0.9.0-alpha",
+    "@hardkas/tx-builder": "0.9.0-alpha",
+    "@hardkas/wallet-adapter": "0.9.0-alpha",
+    "@hardkas/query-store": "0.9.0-alpha",
+    "@hardkas/simulator": "0.9.0-alpha"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",