@hardkas/sdk 0.7.4-alpha → 0.7.6-alpha

package/dist/index.d.ts

@@ -207,6 +207,7 @@ interface WriteArtifactResult {
  */
 declare class HardkasArtifactsManager {
     private workspace;
+    private cache;
     constructor(workspace: HardkasWorkspace);
     /**
      * Writes a valid artifact to disk (canonical or custom path).

package/dist/index.js

@@ -351,7 +351,8 @@ var HardkasTx = class {
     const {
       loadOrCreateLocalnetState,
       saveLocalnetState,
-      applySimulatedPayment,
+      getDefaultLocalnetStatePath,
+      applySimulatedPlan,
       saveSimulatedReceipt,
       saveSimulatedTrace
     } = await import("@hardkas/localnet");
@@ -361,24 +362,29 @@ var HardkasTx = class {
     const events = [
       { type: "phase.started", phase: "send", timestamp: startTime }
     ];
-    const simResult = applySimulatedPayment(
+    const planArtifact = await this.sdk.artifacts.read(signedArtifact.sourcePlanId);
+    const simResult = applySimulatedPlan(
       state,
-      {
-        from: signedArtifact.from.input || signedArtifact.from.address,
-        to: signedArtifact.to.input || signedArtifact.to.address,
-        amountSompi: BigInt(signedArtifact.amountSompi)
-      },
-      systemRuntimeContext
+      planArtifact,
+      systemRuntimeContext,
+      { txId: signedArtifact.txId || `simulated-${signedArtifact.sourcePlanId}-tx` }
     );
+    if (!simResult.ok) {
+      throw new Error(`Strict validation failed: ${simResult.errors?.join(", ")}`);
+    }
     coreEvents.normalizeAndEmit({
       kind: "workflow.submitted",
       txId: simResult.receipt.txId,
       endpoint: "simulated://local"
     });
     events.push({ type: "phase.completed", phase: "send", timestamp: Date.now() });
-    await saveLocalnetState(simResult.state);
+    await saveLocalnetState(
+      simResult.state,
+      getDefaultLocalnetStatePath(this.sdk.workspace.root)
+    );
     const receiptPath = await saveSimulatedReceipt(
-      simResult.receipt
+      simResult.receipt,
+      { cwd: this.sdk.workspace.root }
     );
     const tracePath = receiptPath.replace(".json", ".trace.json");
     const receiptBase = {
@@ -428,11 +434,14 @@ var HardkasTx = class {
       steps: traceSteps
     };
     traceBase.contentHash = calculateContentHash(traceBase, CURRENT_HASH_VERSION);
-    await saveSimulatedTrace({
-      ...traceBase,
-      events,
-      receiptPath
-    });
+    await saveSimulatedTrace(
+      {
+        ...traceBase,
+        events,
+        receiptPath
+      },
+      { cwd: this.sdk.workspace.root }
+    );
     coreEvents.normalizeAndEmit({
       kind: "artifact.created",
       schema: receipt.schema,
@@ -585,6 +594,124 @@ import {
   verifyArtifactIntegrity,
   writeArtifact as writeArtifact2
 } from "@hardkas/artifacts";
+function resolveReplayTargets(cwd, options) {
+  if (options.path) {
+    const fullPath = path.resolve(cwd, options.path);
+    if (!fs.existsSync(fullPath)) {
+      throw new Error(`Path not found: ${options.path}`);
+    }
+    if (fs.statSync(fullPath).isFile()) {
+      const dir = path.dirname(fullPath);
+      let planId = "";
+      try {
+        const data = JSON.parse(fs.readFileSync(fullPath, "utf-8"));
+        planId = data.planId || "";
+      } catch {
+      }
+      let receiptPath = "";
+      if (planId) {
+        receiptPath = findReceiptByPlanId(dir, planId);
+      }
+      return {
+        planPath: fullPath,
+        receiptPath,
+        artifactDir: dir,
+        source: "explicit-file"
+      };
+    }
+    return resolveFromDirectory(fullPath, "explicit-dir");
+  }
+  if (options.workflowId) {
+    return {
+      planPath: path.join(cwd, "tx-plan.json"),
+      receiptPath: path.join(cwd, "tx-receipt.json"),
+      artifactDir: cwd,
+      source: "workflow-id"
+    };
+  }
+  const artifactsDir = path.join(cwd, ".hardkas", "artifacts");
+  if (!fs.existsSync(artifactsDir) || !fs.statSync(artifactsDir).isDirectory()) {
+    throw new Error(
+      `No .hardkas/artifacts/ directory found.
+  Hint: Run 'hardkas init' first, then execute a transaction.`
+    );
+  }
+  return resolveFromDirectory(artifactsDir, "artifact-scan");
+}
+function resolveFromDirectory(dir, source) {
+  const allFiles = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+  const plans = [];
+  const receipts = [];
+  for (const f of allFiles) {
+    try {
+      const raw = fs.readFileSync(path.join(dir, f), "utf-8");
+      const data = JSON.parse(raw);
+      if (!data || !data.schema) continue;
+      if (data.schema === "hardkas.txPlan") {
+        plans.push({
+          file: f,
+          planId: data.planId || "",
+          createdAt: data.createdAt || ""
+        });
+      } else if (data.schema === "hardkas.txReceipt") {
+        receipts.push({
+          file: f,
+          sourcePlanId: data.sourcePlanId || data.lineage?.parentArtifactId || data.lineage?.rootArtifactId || "",
+          txId: data.txId || "",
+          createdAt: data.createdAt || ""
+        });
+      }
+    } catch {
+    }
+  }
+  if (plans.length === 0) {
+    throw new Error(
+      `No plan artifacts found in ${dir}.
+  Hint: Run a transaction first: hardkas tx send --from alice --to bob --amount 10 --network simulated --yes`
+    );
+  }
+  plans.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  for (const plan of plans) {
+    const matchingReceipt = receipts.find(
+      (r) => (
+        // Direct sourcePlanId match
+        r.sourcePlanId && r.sourcePlanId === plan.planId || // txId derived from planId (e.g., "simulated-plan-xxx-tx" contains "plan-xxx")
+        r.txId && plan.planId && r.txId.includes(plan.planId)
+      )
+    );
+    if (matchingReceipt) {
+      return {
+        planPath: path.join(dir, plan.file),
+        receiptPath: path.join(dir, matchingReceipt.file),
+        artifactDir: dir,
+        source
+      };
+    }
+  }
+  const bestPlan = plans[0];
+  return {
+    planPath: path.join(dir, bestPlan.file),
+    receiptPath: "",
+    // Will trigger actionable error downstream
+    artifactDir: dir,
+    source
+  };
+}
+function findReceiptByPlanId(dir, planId) {
+  if (!fs.existsSync(dir)) return "";
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+  for (const f of files) {
+    try {
+      const raw = fs.readFileSync(path.join(dir, f), "utf-8");
+      const data = JSON.parse(raw);
+      if (data && data.schema === "hardkas.txReceipt" && (data.sourcePlanId && data.sourcePlanId === planId || data.lineage?.parentArtifactId && data.lineage.parentArtifactId === planId || data.lineage?.rootArtifactId && data.lineage.rootArtifactId === planId || data.txId && data.txId.includes(planId))) {
+        return path.join(dir, f);
+      }
+    } catch {
+    }
+  }
+  return "";
+}
 var HardkasReplay = class {
   constructor(sdk) {
     this.sdk = sdk;
@@ -595,36 +722,8 @@ var HardkasReplay = class {
    * against the mathematically reconstructed localnet state.
    */
   async verify(options) {
-    let artifactDir = this.sdk.config.cwd;
-    let planPath = path.join(artifactDir, "tx-plan.json");
-    let receiptPath = path.join(artifactDir, "tx-receipt.json");
-    if (options.path) {
-      const fullPath = path.resolve(this.sdk.config.cwd, options.path);
-      if (fs.existsSync(fullPath)) {
-        if (fs.statSync(fullPath).isFile()) {
-          planPath = fullPath;
-          artifactDir = path.dirname(fullPath);
-          receiptPath = fullPath.replace("tx-plan", "tx-receipt");
-          try {
-            let content = fs.readFileSync(fullPath, "utf-8");
-            if (content.charCodeAt(0) === 65279) {
-              content = content.slice(1);
-            }
-            const json = JSON.parse(content);
-            if (json && json.schema === "hardkas.workflow.v1" && json.workflowId) {
-              options.workflowId = json.workflowId;
-            }
-          } catch (e) {
-          }
-        } else {
-          artifactDir = fullPath;
-          planPath = path.join(artifactDir, "tx-plan.json");
-          receiptPath = path.join(artifactDir, "tx-receipt.json");
-        }
-      } else {
-        throw new Error(`Path not found: ${options.path}`);
-      }
-    }
+    const targets = resolveReplayTargets(this.sdk.config.cwd, options);
+    let { planPath, receiptPath, artifactDir } = targets;
     if (!fs.existsSync(path.join(this.sdk.config.cwd, "hardkas.config.ts"))) {
       throw new Error(`Workspace not found at ${this.sdk.config.cwd}`);
     }
@@ -734,12 +833,15 @@ var HardkasReplay = class {
         lineageOk = false;
         determinismOk = false;
       }
-    } else if (options.path) {
+    } else if (targets.source !== "none") {
       try {
         if (!fs.existsSync(planPath))
           throw new Error(`Transaction plan artifact is missing at: ${planPath}`);
-        if (!fs.existsSync(receiptPath))
-          throw new Error(`Transaction receipt artifact is missing at: ${receiptPath}`);
+        if (!receiptPath || !fs.existsSync(receiptPath))
+          throw new Error(
+            `No matching receipt artifact found for plan at: ${planPath}
+  Hint: Run 'hardkas tx send --from alice --to bob --amount 10 --network simulated --yes' to create a complete plan\u2192sign\u2192send chain.`
+          );
         plan = await readTxPlanArtifact(planPath);
         receipt = await readTxReceiptArtifact2(receiptPath);
       } catch (err) {
@@ -830,12 +932,17 @@ var HardkasArtifactsManager = class {
     this.workspace = workspace;
   }
   workspace;
+  cache = /* @__PURE__ */ new Map();
   /**
    * Writes a valid artifact to disk (canonical or custom path).
    */
   async write(artifact, options = {}) {
     const record = artifact;
     const hash = record.contentHash || "unknown";
+    if (record.planId) this.cache.set(record.planId, artifact);
+    if (record.signedId) this.cache.set(record.signedId, artifact);
+    if (record.txId) this.cache.set(record.txId, artifact);
+    this.cache.set(hash, artifact);
     if (options.dryRun) {
       return {
         dryRun: true,
@@ -889,6 +996,9 @@ var HardkasArtifactsManager = class {
    * Reads an artifact by path or ID/hash from the workspace.
    */
   async read(id) {
+    if (this.cache.has(id)) {
+      return this.cache.get(id);
+    }
     const { readArtifact } = await import("@hardkas/artifacts");
     let filePath = id;
     if (!fs3.existsSync(filePath)) {
@@ -983,9 +1093,7 @@ var HardkasWorkflow = class {
                   );
                 }
                 const plan = await this.sdk.tx.plan({ ...opts, workflowId });
-                if (!options.dryRun) {
-                  await this.sdk.artifacts.write(plan);
-                }
+                await this.sdk.artifacts.write(plan, { dryRun: options.dryRun ?? false });
                 const planRecord = plan;
                 const id = planRecord.contentHash || planRecord.artifactId || plan.planId;
                 if (id) producedArtifacts.push(id);
@@ -994,9 +1102,9 @@ var HardkasWorkflow = class {
               },
               sign: async (plan, account) => {
                 const signed = await this.sdk.tx.sign(plan, account);
-                if (!options.dryRun) {
-                  await this.sdk.artifacts.write(signed);
-                }
+                await this.sdk.artifacts.write(signed, {
+                  dryRun: options.dryRun ?? false
+                });
                 const signedRecord = signed;
                 const id = signedRecord.contentHash || signedRecord.artifactId || signed.signedId;
                 if (id) producedArtifacts.push(id);
@@ -1009,7 +1117,9 @@ var HardkasWorkflow = class {
                   "Workflow script requested real broadcast"
                 );
                 const res = this.sdk.network === "simulated" ? await this.sdk.tx.simulate(signed) : await this.sdk.tx.send(signed);
-                if (!options.dryRun) await this.sdk.artifacts.write(res.receipt);
+                await this.sdk.artifacts.write(res.receipt, {
+                  dryRun: options.dryRun ?? false
+                });
                 const receiptRecord = res.receipt;
                 const id = receiptRecord.contentHash || receiptRecord.artifactId || receiptRecord.txId;
                 if (id) producedArtifacts.push(id);
@@ -1017,7 +1127,9 @@ var HardkasWorkflow = class {
               },
               simulate: async (signed) => {
                 const res = await this.sdk.tx.simulate(signed);
-                if (!options.dryRun) await this.sdk.artifacts.write(res.receipt);
+                await this.sdk.artifacts.write(res.receipt, {
+                  dryRun: options.dryRun ?? false
+                });
                 const receiptRecord = res.receipt;
                 const id = receiptRecord.contentHash || receiptRecord.artifactId || receiptRecord.txId;
                 if (id) producedArtifacts.push(id);
@@ -1045,9 +1157,7 @@ var HardkasWorkflow = class {
             amount: step.args?.amount || step.amount,
             workflowId
           });
-          if (!options.dryRun) {
-            await this.sdk.artifacts.write(lastPlan);
-          }
+          await this.sdk.artifacts.write(lastPlan, { dryRun: options.dryRun ?? false });
           const planRecord = lastPlan;
           producedArtifactId = planRecord.contentHash || planRecord.artifactId || lastPlan.planId;
           if (producedArtifactId) producedArtifacts.push(producedArtifactId);
@@ -1062,22 +1172,20 @@ var HardkasWorkflow = class {
             );
           }
           lastSigned = await this.sdk.tx.sign(lastPlan);
-          if (!options.dryRun) {
-            await this.sdk.artifacts.write(lastSigned);
-          }
+          await this.sdk.artifacts.write(lastSigned, { dryRun: options.dryRun ?? false });
           const signedRecord = lastSigned;
           const signedId = signedRecord.contentHash || signedRecord.artifactId || lastSigned.signedId;
           if (signedId) producedArtifacts.push(signedId);
           if (step.type === "tx.simulate") {
             const { receipt } = await this.sdk.tx.simulate(lastSigned);
-            if (!options.dryRun) await this.sdk.artifacts.write(receipt);
+            await this.sdk.artifacts.write(receipt, { dryRun: options.dryRun ?? false });
             const receiptRecord = receipt;
             producedArtifactId = receiptRecord.contentHash || receiptRecord.artifactId || receiptRecord.txId;
             if (producedArtifactId) producedArtifacts.push(producedArtifactId);
             result = receipt;
           } else {
             const { receipt } = this.sdk.network === "simulated" ? await this.sdk.tx.simulate(lastSigned) : await this.sdk.tx.send(lastSigned);
-            if (!options.dryRun) await this.sdk.artifacts.write(receipt);
+            await this.sdk.artifacts.write(receipt, { dryRun: options.dryRun ?? false });
             const receiptRecord = receipt;
             producedArtifactId = receiptRecord.contentHash || receiptRecord.artifactId || receiptRecord.txId;
             if (producedArtifactId) producedArtifacts.push(producedArtifactId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/sdk",
-  "version": "0.7.4-alpha",
+  "version": "0.7.6-alpha",
   "type": "module",
   "files": [
     "dist",
@@ -23,23 +23,23 @@
     }
   },
   "dependencies": {
-    "@hardkas/accounts": "0.7.4-alpha",
-    "@hardkas/config": "0.7.4-alpha",
-    "@hardkas/core": "0.7.4-alpha",
-    "@hardkas/artifacts": "0.7.4-alpha",
-    "@hardkas/kaspa-rpc": "0.7.4-alpha",
-    "@hardkas/l2": "0.7.4-alpha",
-    "@hardkas/simulator": "0.7.4-alpha",
-    "@hardkas/localnet": "0.7.4-alpha",
-    "@hardkas/tx-builder": "0.7.4-alpha",
-    "@hardkas/query": "0.7.4-alpha",
-    "@hardkas/wallet-adapter": "0.7.4-alpha"
+    "@hardkas/config": "0.7.6-alpha",
+    "@hardkas/artifacts": "0.7.6-alpha",
+    "@hardkas/accounts": "0.7.6-alpha",
+    "@hardkas/core": "0.7.6-alpha",
+    "@hardkas/l2": "0.7.6-alpha",
+    "@hardkas/simulator": "0.7.6-alpha",
+    "@hardkas/localnet": "0.7.6-alpha",
+    "@hardkas/query": "0.7.6-alpha",
+    "@hardkas/tx-builder": "0.7.6-alpha",
+    "@hardkas/wallet-adapter": "0.7.6-alpha",
+    "@hardkas/kaspa-rpc": "0.7.6-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8",
-    "@hardkas/query-store": "0.7.4-alpha"
+    "@hardkas/query-store": "0.7.6-alpha"
   },
   "license": "MIT",
   "author": "Javier Rodriguez",