@hardkas/sdk 0.7.10-alpha → 0.7.12-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

@@ -89,9 +89,16 @@ declare class HardkasTx {
     /**
      * 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.

package/dist/index.js

@@ -440,7 +440,28 @@ var HardkasTx = class {
       try {
         planArtifact = await this.sdk.artifacts.read(sourcePlanId);
       } catch (e) {
-        throw new Error(`Cannot simulate signed artifact: source plan '${sourcePlanId}' not found in workspace.`);
+        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;
@@ -563,13 +584,60 @@ var HardkasTx = class {
   /**
    * 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 } : {};
+      let simResult;
+      try {
+        simResult = await this.simulate(signedArtifact, simOpts);
+      } catch (e) {
+        if (e.message && e.message.includes("invalid simulated input")) {
+          try {
+            const { loadSimulatedReceipt, getReceiptPath } = await import("@hardkas/localnet");
+            const txIdToLoad = signedArtifact.txId || `simulated-${signedArtifact.sourcePlanId}-tx`;
+            const existingReceipt = await loadSimulatedReceipt(txIdToLoad, { cwd: this.sdk.workspace.root });
+            if (existingReceipt) {
+              if (existingReceipt.schema === ARTIFACT_SCHEMAS.TX_RECEIPT && (existingReceipt.status === "confirmed" || existingReceipt.status === "accepted")) {
+                return {
+                  mode: "simulated",
+                  simulated: true,
+                  submitted: false,
+                  txId: existingReceipt.txId,
+                  artifactId: existingReceipt.txId,
+                  // simulated receipts use txId as artifactId
+                  receipt: existingReceipt,
+                  receiptPath: getReceiptPath(existingReceipt.txId, this.sdk.workspace.root)
+                };
+              }
+            }
+          } catch (err) {
+          }
+        }
+        throw e;
+      }
+      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";

package/package.json

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