@hardkas/sdk 0.7.9-alpha → 0.7.11-alpha

package/README.md

@@ -0,0 +1,40 @@
+# `@hardkas/sdk`
+
+The HardKAS SDK acts as the programmatic boundary between developer scripts and the isolated HardKAS runtime engine.
+
+## 1. Bootstrapping Variants
+
+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 });
+```
+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.
+
+## 2. Transaction Flow & Dry-Runs
+
+All SDK transaction methods follow the Plan -> Sign -> Broadcast pipeline.
+
+### 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/`.
+
+### Variant: Dry-Run Execution
+```typescript
+const plan = await sdk.tx.plan({ to, amount, dryRun: true });
+```
+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`.

package/dist/index.d.ts

@@ -79,17 +79,26 @@ 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.
      */
-    send(signedArtifact: SignedTxArtifact, url?: string): Promise<{
+    send(signedArtifact: SignedTxArtifact, urlOrOptions?: string | {
+        persist?: boolean;
+    }): Promise<{
         receipt: TxReceiptArtifact;
-        receiptPath: string;
+        receiptPath?: string;
+        artifactId?: string;
+        mode?: string;
+        simulated?: boolean;
+        submitted?: boolean;
+        txId?: string;
     }>;
     /**
      * Explicitly appends a signature to a partially signed transaction.
@@ -295,6 +304,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,62 @@ 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) {
+        if (targetObj.from && targetObj.to && targetObj.amountSompi) {
+          planArtifact = {
+            schema: "hardkas.txPlan",
+            planId: sourcePlanId,
+            from: targetObj.from,
+            to: targetObj.to,
+            amountSompi: targetObj.amountSompi,
+            estimatedFeeSompi: "0",
+            estimatedMass: "0",
+            inputs: [],
+            outputs: [{ address: targetObj.to.address, amountSompi: targetObj.amountSompi || "0" }],
+            plan: {
+              inputs: [],
+              outputs: [{ address: targetObj.to.address, amountSompi: BigInt(targetObj.amountSompi || 0) }],
+              feeSompi: 0n,
+              mass: 0n,
+              changeSompi: 0n
+            }
+          };
+        } else {
+          throw new Error(`Cannot simulate signed artifact: source plan '${sourcePlanId}' not found in workspace and artifact lacks details.`);
+        }
+      }
+    } 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 +487,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 +512,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 +548,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,22 +576,41 @@ 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.
    */
-  async send(signedArtifact, url) {
+  async send(signedArtifact, urlOrOptions) {
     const verification = verifySignedTxSemantics(signedArtifact);
     if (!verification.ok) {
       throw new Error(
         `Pre-broadcast semantic verification failed: ${verification.issues.map((i) => i.message).join(", ")}`
       );
     }
+    const activeNetwork = this.sdk.config.config.defaultNetwork || "simnet";
+    const isSimulated = activeNetwork === "simulated" || this.sdk.config.config.networks?.[activeNetwork]?.kind === "simulated";
+    if (isSimulated) {
+      const persistOpt = typeof urlOrOptions === "object" ? urlOrOptions.persist : true;
+      const simOpts = persistOpt !== void 0 ? { persist: persistOpt } : {};
+      const simResult = await this.simulate(signedArtifact, simOpts);
+      const result2 = {
+        mode: "simulated",
+        simulated: true,
+        submitted: false,
+        txId: simResult.receipt.txId,
+        artifactId: simResult.receipt.artifactId ?? simResult.artifactId ?? simResult.receipt.contentHash,
+        receipt: simResult.receipt
+      };
+      if (simResult.receiptPath !== void 0) {
+        result2.receiptPath = simResult.receiptPath;
+      }
+      return result2;
+    }
+    const url = typeof urlOrOptions === "string" ? urlOrOptions : void 0;
     const broadcastable = getBroadcastableSignedTransaction(signedArtifact);
     const broadcastRecord = broadcastable.rawTransaction;
     const txId = broadcastRecord.id || "unknown";
@@ -634,29 +711,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 +1320,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 +1731,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.11-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/accounts": "0.7.11-alpha",
+    "@hardkas/artifacts": "0.7.11-alpha",
+    "@hardkas/core": "0.7.11-alpha",
+    "@hardkas/config": "0.7.11-alpha",
+    "@hardkas/kaspa-rpc": "0.7.11-alpha",
+    "@hardkas/localnet": "0.7.11-alpha",
+    "@hardkas/l2": "0.7.11-alpha",
+    "@hardkas/simulator": "0.7.11-alpha",
+    "@hardkas/query": "0.7.11-alpha",
+    "@hardkas/tx-builder": "0.7.11-alpha",
+    "@hardkas/wallet-adapter": "0.7.11-alpha",
+    "@hardkas/query-store": "0.7.11-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",