@hardkas/sdk 0.7.9-alpha → 0.7.10-alpha

package/dist/index.d.ts

@@ -79,10 +79,12 @@ declare class HardkasTx {
      * Simulates a transaction on the local state without broadcasting to a real Kaspa node.
      * Modifies the local deterministic state and outputs receipt/trace artifacts.
      */
-    simulate(signedArtifact: SignedTxArtifact): Promise<{
+    simulate(target: string | Partial<TxPlanArtifact> | SignedTxArtifact, options?: {
+        persist?: boolean;
+    }): Promise<{
         receipt: TxReceiptArtifact;
-        receiptPath: string;
-        tracePath: string;
+        receiptPath?: string;
+        tracePath?: string;
     }>;
     /**
      * Sends a signed transaction to the real RPC network.
@@ -295,6 +297,8 @@ declare class HardkasArtifactsManager {
         schema?: string;
         artifactId?: string;
         contentHash?: string;
+    }, options?: {
+        throwOnInvalid?: boolean;
     }): Promise<any>;
 }
 

package/dist/index.js

@@ -405,7 +405,8 @@ var HardkasTx = class {
    * Simulates a transaction on the local state without broadcasting to a real Kaspa node.
    * Modifies the local deterministic state and outputs receipt/trace artifacts.
    */
-  async simulate(signedArtifact) {
+  async simulate(target, options = {}) {
+    const persist = options.persist ?? true;
     const {
       loadOrCreateLocalnetState,
       saveLocalnetState,
@@ -420,12 +421,41 @@ var HardkasTx = class {
     const events = [
       { type: "phase.started", phase: "send", timestamp: startTime }
     ];
-    const planArtifact = await this.sdk.artifacts.read(signedArtifact.sourcePlanId);
+    let planArtifact;
+    let signedId = "unknown";
+    let sourcePlanId = "unknown";
+    let txId = `simulated-tx-${Date.now()}`;
+    let targetObj = target;
+    if (typeof target === "string") {
+      try {
+        targetObj = await this.sdk.artifacts.read(target);
+      } catch (e) {
+        throw new Error(`Artifact '${target}' not found. If you already have an in-memory artifact, pass the object directly to tx.simulate(artifact).`);
+      }
+    }
+    if (targetObj.schema === ARTIFACT_SCHEMAS.SIGNED_TX) {
+      signedId = targetObj.signedId || targetObj.id || "unknown";
+      sourcePlanId = targetObj.sourcePlanId || "unknown";
+      txId = targetObj.txId || `simulated-${sourcePlanId}-tx`;
+      try {
+        planArtifact = await this.sdk.artifacts.read(sourcePlanId);
+      } catch (e) {
+        throw new Error(`Cannot simulate signed artifact: source plan '${sourcePlanId}' not found in workspace.`);
+      }
+    } else {
+      planArtifact = targetObj;
+      sourcePlanId = planArtifact.planId || planArtifact.id || "unknown";
+      txId = `simulated-${sourcePlanId}-tx`;
+      if (persist && !planArtifact.planId) {
+        const savedPlanResult = await this.sdk.artifacts.write(planArtifact);
+        sourcePlanId = planArtifact.planId || "unknown";
+      }
+    }
     const simResult = applySimulatedPlan(
       state,
       planArtifact,
       systemRuntimeContext,
-      { txId: signedArtifact.txId || `simulated-${signedArtifact.sourcePlanId}-tx` }
+      { txId }
     );
     if (!simResult.ok) {
       throw new Error(`Strict validation failed: ${simResult.errors?.join(", ")}`);
@@ -436,15 +466,18 @@ var HardkasTx = class {
       endpoint: "simulated://local"
     });
     events.push({ type: "phase.completed", phase: "send", timestamp: Date.now() });
-    await saveLocalnetState(
-      simResult.state,
-      getDefaultLocalnetStatePath(this.sdk.workspace.root)
-    );
-    const receiptPath = await saveSimulatedReceipt(
-      simResult.receipt,
-      { cwd: this.sdk.workspace.root }
-    );
-    const tracePath = receiptPath.replace(".json", ".trace.json");
+    let receiptPath;
+    if (persist) {
+      await saveLocalnetState(
+        simResult.state,
+        getDefaultLocalnetStatePath(this.sdk.workspace.root)
+      );
+      receiptPath = await saveSimulatedReceipt(
+        simResult.receipt,
+        { cwd: this.sdk.workspace.root }
+      );
+    }
+    const tracePath = receiptPath ? receiptPath.replace(".json", ".trace.json") : void 0;
     const activeNetwork = this.sdk.config.config.defaultNetwork || "simnet";
     const isSimulated = activeNetwork === "simulated" || this.sdk.config.config.networks?.[activeNetwork]?.kind === "simulated";
     const receiptBase = {
@@ -458,10 +491,10 @@ var HardkasTx = class {
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
       status: "confirmed",
       txId: simResult.receipt.txId,
-      sourceSignedId: signedArtifact.signedId,
-      from: { address: signedArtifact.from.address },
-      to: { address: signedArtifact.to.address },
-      amountSompi: signedArtifact.amountSompi,
+      sourceSignedId: signedId,
+      from: { address: planArtifact.from?.address || "unknown" },
+      to: { address: planArtifact.to?.address || "unknown" },
+      amountSompi: planArtifact.amountSompi || "0",
       feeSompi: simResult.receipt.feeSompi?.toString() || "0",
       changeSompi: simResult.receipt.changeSompi?.toString() || "0",
       spentUtxoIds: simResult.receipt.spentUtxoIds,
@@ -494,22 +527,26 @@ var HardkasTx = class {
       steps: traceSteps
     };
     traceBase.contentHash = calculateContentHash(traceBase, CURRENT_HASH_VERSION);
-    await saveSimulatedTrace(
-      {
-        ...traceBase,
-        events,
-        receiptPath
-      },
-      { cwd: this.sdk.workspace.root }
-    );
-    coreEvents.normalizeAndEmit({
-      kind: "artifact.created",
-      schema: receipt.schema,
-      artifactId: receipt.txId,
-      network: receipt.networkId,
-      mode: receipt.mode,
-      path: receiptPath
-    });
+    if (persist) {
+      await saveSimulatedTrace(
+        {
+          ...traceBase,
+          events,
+          receiptPath
+        },
+        { cwd: this.sdk.workspace.root }
+      );
+    }
+    if (persist) {
+      coreEvents.normalizeAndEmit({
+        kind: "artifact.created",
+        schema: receipt.schema,
+        artifactId: receipt.txId,
+        network: receipt.networkId,
+        mode: receipt.mode,
+        path: receiptPath
+      });
+    }
     coreEvents.normalizeAndEmit({
       kind: "tx.confirmed",
       txId: receipt.txId,
@@ -518,11 +555,10 @@ var HardkasTx = class {
       amountSompi: receipt.amountSompi,
       feeSompi: receipt.feeSompi
     });
-    return {
-      receipt,
-      receiptPath,
-      tracePath
-    };
+    const result = { receipt };
+    if (receiptPath) result.receiptPath = receiptPath;
+    if (tracePath) result.tracePath = tracePath;
+    return result;
   }
   /**
    * Sends a signed transaction to the real RPC network.
@@ -634,29 +670,48 @@ var HardkasQuery = class {
    * Synchronizes the query store with the filesystem artifacts.
    */
   async sync(options) {
-    const { HardkasStore, HardkasIndexer } = await import("@hardkas/query-store");
-    const { withLock } = await import("@hardkas/core");
+    const fs4 = await import("fs");
     const path4 = await import("path");
-    const dbPath = path4.join(this.sdk.workspace.root, ".hardkas", "store.db");
+    const hardkasDir = path4.join(this.sdk.workspace.root, ".hardkas");
+    if (!fs4.existsSync(hardkasDir)) {
+      throw new Error("Workspace not initialized. Run hardkas init or Hardkas.create({ autoBootstrap:true }).");
+    }
+    let HardkasStore, HardkasIndexer;
+    try {
+      const qs = await import("@hardkas/query-store");
+      HardkasStore = qs.HardkasStore;
+      HardkasIndexer = qs.HardkasIndexer;
+    } catch (e) {
+      throw new Error("Query store backend unavailable. Install @hardkas/query-store or run query.store.rebuild.");
+    }
+    const { withLock } = await import("@hardkas/core");
+    const dbPath = path4.join(hardkasDir, "store.db");
     const store = new HardkasStore({ dbPath });
     let stats;
-    await withLock(
-      {
-        rootDir: this.sdk.workspace.root,
-        name: "query-store",
-        command: "query-sync",
-        wait: true
-      },
-      async () => {
-        store.connect({ autoMigrate: true });
-        const indexer = new HardkasIndexer(store.getDatabase());
-        if (options?.force) {
-          stats = await indexer.rebuild();
-        } else {
-          stats = await indexer.sync();
+    try {
+      await withLock(
+        {
+          rootDir: this.sdk.workspace.root,
+          name: "query-store",
+          command: "query-sync",
+          wait: true
+        },
+        async () => {
+          store.connect({ autoMigrate: true });
+          const indexer = new HardkasIndexer(store.getDatabase());
+          if (options?.force) {
+            stats = await indexer.rebuild();
+          } else {
+            stats = await indexer.sync();
+          }
         }
+      );
+    } catch (e) {
+      if (e.message?.includes("SQLITE") || e.message?.includes("Cannot read properties")) {
+        throw new Error("Query store database is not configured correctly or corrupted. Try running query.sync({ force: true }).");
       }
-    );
+      throw e;
+    }
     return stats;
   }
   /**
@@ -1224,14 +1279,36 @@ var HardkasArtifactsManager = class {
    * Cryptographically verifies the determinism and integrity of an artifact.
    * Throws an error with details if corruption or mismatch is found.
    */
-  async verify(target) {
+  async verify(target, options = {}) {
+    const throwOnInvalid = options.throwOnInvalid ?? true;
     const id = typeof target === "string" ? target : target.artifactId || target.contentHash || "";
-    if (!id) throw new Error("No artifact target provided for verification.");
-    const artifact = await this.read(id);
+    if (!id) {
+      if (throwOnInvalid) throw new Error("No artifact target provided for verification.");
+      return { valid: false, reason: "unknown", message: "No artifact target provided for verification." };
+    }
+    let artifact;
+    try {
+      artifact = await this.read(id);
+    } catch (e) {
+      if (throwOnInvalid) throw e;
+      return { valid: false, reason: "missing_artifact", message: e.message, artifactId: id };
+    }
     const { verifyArtifactIntegrity: verifyArtifactIntegrity2 } = await import("@hardkas/artifacts");
     const result = await verifyArtifactIntegrity2(artifact);
     if (!result.ok) {
-      throw new Error(`Artifact ${id} corrupted or invalid: ` + JSON.stringify(result.issues, null, 2));
+      if (throwOnInvalid) {
+        throw new Error(`Artifact ${id} corrupted or invalid: ` + JSON.stringify(result.issues, null, 2));
+      }
+      return {
+        valid: false,
+        reason: result.issues[0]?.code === "HASH_MISMATCH" ? "hash_mismatch" : result.issues[0]?.code === "MISSING_SIGNATURE" ? "missing_signature" : "schema_invalid",
+        message: result.issues.map((i) => i.message).join(", "),
+        artifactId: id,
+        details: result.issues
+      };
+    }
+    if (!throwOnInvalid) {
+      return { valid: true, artifactId: id, details: result };
     }
     return result;
   }
@@ -1613,7 +1690,12 @@ var Hardkas = class _Hardkas {
     if (options.network) {
       loaded.config.defaultNetwork = options.network;
     }
-    return new _Hardkas(loaded, options);
+    let provider;
+    if (isSimulated) {
+      const { LocalnetSimulatedProvider } = await import("@hardkas/localnet");
+      provider = new LocalnetSimulatedProvider(cwd);
+    }
+    return new _Hardkas(loaded, options, provider);
   }
   /**
    * Alias for open(). Used in most examples.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/sdk",
-  "version": "0.7.9-alpha",
+  "version": "0.7.10-alpha",
   "type": "module",
   "files": [
     "dist",
@@ -23,18 +23,18 @@
     }
   },
   "dependencies": {
-    "@hardkas/config": "0.7.9-alpha",
-    "@hardkas/artifacts": "0.7.9-alpha",
-    "@hardkas/accounts": "0.7.9-alpha",
-    "@hardkas/core": "0.7.9-alpha",
-    "@hardkas/kaspa-rpc": "0.7.9-alpha",
-    "@hardkas/l2": "0.7.9-alpha",
-    "@hardkas/query": "0.7.9-alpha",
-    "@hardkas/localnet": "0.7.9-alpha",
-    "@hardkas/tx-builder": "0.7.9-alpha",
-    "@hardkas/simulator": "0.7.9-alpha",
-    "@hardkas/wallet-adapter": "0.7.9-alpha",
-    "@hardkas/query-store": "0.7.9-alpha"
+    "@hardkas/config": "0.7.10-alpha",
+    "@hardkas/accounts": "0.7.10-alpha",
+    "@hardkas/artifacts": "0.7.10-alpha",
+    "@hardkas/l2": "0.7.10-alpha",
+    "@hardkas/simulator": "0.7.10-alpha",
+    "@hardkas/core": "0.7.10-alpha",
+    "@hardkas/localnet": "0.7.10-alpha",
+    "@hardkas/kaspa-rpc": "0.7.10-alpha",
+    "@hardkas/query": "0.7.10-alpha",
+    "@hardkas/tx-builder": "0.7.10-alpha",
+    "@hardkas/query-store": "0.7.10-alpha",
+    "@hardkas/wallet-adapter": "0.7.10-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",