@hardkas/sdk 0.7.6-alpha → 0.7.8-alpha

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import * as _hardkas_config from '@hardkas/config';
 import { LoadedHardkasConfig } from '@hardkas/config';
 export { defineHardkasConfig } from '@hardkas/config';
 import { KaspaRpcClient } from '@hardkas/kaspa-rpc';
-import { NetworkId } from '@hardkas/core';
+import { EventEnvelope, NetworkId } from '@hardkas/core';
 export { ArtifactId, HardkasError, KaspaAddress, LineageId, NetworkId, SOMPI_PER_KAS, TxId, formatSompi, parseKasToSompi } from '@hardkas/core';
 import { TxPlanArtifact, SignedTxArtifact, TxReceiptArtifact, HardkasArtifactBase, WorkflowArtifact } from '@hardkas/artifacts';
 export { ARTIFACT_SCHEMAS, HARDKAS_VERSION, SignedTxArtifact, TxPlanArtifact, TxReceiptArtifact, TxTraceArtifact, createTxPlanArtifact, writeArtifact } from '@hardkas/artifacts';
@@ -30,6 +30,24 @@ declare class HardkasAccounts {
         sompi: bigint;
         formatted: string;
     }>;
+    /**
+     * Alias for getBalance.
+     */
+    balance(accountNameOrAddress: string): Promise<{
+        sompi: bigint;
+        formatted: string;
+    }>;
+    /**
+     * Lists all configured account names.
+     */
+    list(): Promise<string[]>;
+    /**
+     * Funds an account from another account (defaults to 'default' account).
+     */
+    fund(accountNameOrAddress: string, options?: {
+        from?: string;
+        amount?: string | bigint;
+    }): Promise<any>;
 }
 
 /**
@@ -73,6 +91,14 @@ declare class HardkasTx {
         receipt: TxReceiptArtifact;
         receiptPath: string;
     }>;
+    /**
+     * Explicitly appends a signature to a partially signed transaction.
+     */
+    appendSignature(plan: SignedTxArtifact, account?: HardkasAccount | string): Promise<SignedTxArtifact>;
+    /**
+     * Fetches the current status of a transaction by ID.
+     */
+    status(txId: string): Promise<any>;
 }
 
 /**
@@ -105,6 +131,21 @@ declare class HardkasQuery {
      * Internal lazy-loaded query engine.
      */
     private getEngine;
+    /**
+     * Synchronizes the query store with the filesystem artifacts.
+     */
+    sync(options?: {
+        force?: boolean;
+    }): Promise<any>;
+    /**
+     * Fetches events from the query store.
+     */
+    events(filter?: {
+        domain?: string;
+        kind?: string;
+        correlationId?: string;
+        artifactId?: string;
+    }): Promise<readonly EventEnvelope[]>;
 }
 
 /**
@@ -147,7 +188,28 @@ declare class HardkasReplay {
      * Verifies the deterministic artifact lineage of a transaction replay
      * against the mathematically reconstructed localnet state.
      */
-    verify(options: ReplayVerifyOptions): Promise<ReplayVerifyResult>;
+    verify(targetOrOptions?: string | {
+        schema?: string;
+        artifactId?: string;
+    } | ReplayVerifyOptions, options?: ReplayVerifyOptions): Promise<ReplayVerifyResult>;
+}
+
+/**
+ * HardKAS Lineage Module
+ * @alpha
+ */
+declare class HardkasLineage {
+    private sdk;
+    constructor(sdk: Hardkas);
+    /**
+     * Traces the lineage of an artifact, identifying ancestors and descendants.
+     */
+    trace(target: string | {
+        artifactId?: string;
+        contentHash?: string;
+    }, options?: {
+        direction?: "ancestors" | "descendants";
+    }): Promise<any>;
 }
 
 /**
@@ -217,6 +279,23 @@ declare class HardkasArtifactsManager {
      * Reads an artifact by path or ID/hash from the workspace.
      */
     read(id: string): Promise<any>;
+    /**
+     * Alias for read().
+     */
+    get(id: string): Promise<any>;
+    /**
+     * Lists all artifacts in the workspace.
+     */
+    list(): Promise<any[]>;
+    /**
+     * Cryptographically verifies the determinism and integrity of an artifact.
+     * Throws an error with details if corruption or mismatch is found.
+     */
+    verify(target: string | {
+        schema?: string;
+        artifactId?: string;
+        contentHash?: string;
+    }): Promise<any>;
 }
 
 interface WorkflowRunOptions {
@@ -256,6 +335,15 @@ interface HardkasOptions {
     cwd?: string;
     configPath?: string;
     mode?: "developer" | "agent";
+    network?: string;
+    autoBootstrap?: boolean;
+    logger?: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+        debug: (msg: string) => void;
+        [key: string]: any;
+    };
     policy?: {
         allowNetwork?: boolean;
         allowMainnet?: boolean;
@@ -279,6 +367,7 @@ declare class Hardkas {
     readonly query: HardkasQuery;
     readonly localnet: HardkasLocalnet;
     readonly replay: HardkasReplay;
+    readonly lineage: HardkasLineage;
     readonly workflow: HardkasWorkflow;
     readonly mode: "developer" | "agent";
     readonly policy: Required<NonNullable<HardkasOptions["policy"]>>;
@@ -306,4 +395,4 @@ declare class Hardkas {
     enforcePolicy(action: "network" | "mainnet" | "external-wallet" | "mutation", context?: string): void;
 }
 
-export { Hardkas, HardkasAccounts, HardkasArtifactsManager, HardkasL2, HardkasLocalnet, type HardkasOptions, HardkasQuery, HardkasReplay, HardkasTx, HardkasWorkspace, type TaskArgs, type TaskContext, defineTask };
+export { Hardkas, HardkasAccounts, HardkasArtifactsManager, HardkasL2, HardkasLineage, HardkasLocalnet, type HardkasOptions, HardkasQuery, HardkasReplay, HardkasTx, HardkasWorkspace, type TaskArgs, type TaskContext, defineTask };

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   loadHardkasConfig as loadConfig
 } from "@hardkas/config";
 import { JsonWrpcKaspaClient } from "@hardkas/kaspa-rpc";
-import { HardkasError as HardkasError2 } from "@hardkas/core";
+import { HardkasError as HardkasError3 } from "@hardkas/core";
 
 // src/accounts.ts
 import { resolveHardkasAccount } from "@hardkas/accounts";
@@ -40,10 +40,55 @@ var HardkasAccounts = class {
       formatted: formatSompi(sompi)
     };
   }
+  /**
+   * Alias for getBalance.
+   */
+  async balance(accountNameOrAddress) {
+    return this.getBalance(accountNameOrAddress);
+  }
+  /**
+   * Lists all configured account names.
+   */
+  async list() {
+    return Object.keys(this.sdk.config.config.accounts || {});
+  }
+  /**
+   * Funds an account from another account (defaults to 'default' account).
+   */
+  async fund(accountNameOrAddress, options) {
+    let from = options?.from;
+    const amount = options?.amount || "1000000000";
+    if (!from) {
+      const accounts = await this.list();
+      if (accounts.includes("faucet")) {
+        from = "faucet";
+      } else if (accounts.includes("simulated_faucet")) {
+        from = "simulated_faucet";
+      } else if (this.sdk.network === "simulated" && accounts.includes("alice")) {
+        from = "alice";
+      } else {
+        throw new Error("No funding account available.\nFor simulated mode, run Hardkas.create({ network: 'simulated', autoBootstrap: true })\nor call accounts.fund(target, { from: 'alice' }).");
+      }
+    }
+    if (from === accountNameOrAddress) {
+      throw new Error(`Cannot fund account '${accountNameOrAddress}' from itself.`);
+    }
+    const plan = await this.sdk.tx.plan({
+      from,
+      to: accountNameOrAddress,
+      amount
+    });
+    const signed = await this.sdk.tx.sign(plan, from);
+    if (this.sdk.network === "simulated") {
+      return this.sdk.tx.simulate(signed);
+    } else {
+      return this.sdk.tx.send(signed);
+    }
+  }
 };
 
 // src/tx.ts
-import { systemRuntimeContext } from "@hardkas/core";
+import { systemRuntimeContext, deterministicCompare } from "@hardkas/core";
 import {
   buildPaymentPlan,
   verifySignedTxSemantics
@@ -78,8 +123,12 @@ var HardkasTx = class {
     if (!toAccount.address)
       throw new Error(`To account ${toAccount.name} has no address.`);
     const amountSompi = typeof options.amount === "string" ? parseKasToSompi(options.amount) : typeof options.amount === "number" ? BigInt(options.amount) : options.amount;
+    if (amountSompi === 0n) {
+      throw new Error("Kaspa value-transfer outputs require amount > 0.\nFor metadata/notary/DID marker transactions use --amount 1.\nFuture: hardkas tx anchor.");
+    }
     let builderUtxos = [];
-    if (this.sdk.network === "simulated") {
+    const activeNetwork = this.sdk.config.config.defaultNetwork || "simnet";
+    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
@@ -119,9 +168,10 @@ var HardkasTx = class {
       ],
       feeRateSompiPerMass: options.feeRate ?? 1n
     });
+    const isSimulated = activeNetwork === "simulated" || this.sdk.config.config.networks?.[activeNetwork]?.kind === "simulated";
     return createTxPlanArtifact({
-      networkId: this.sdk.network,
-      mode: "simulated",
+      networkId: activeNetwork,
+      mode: isSimulated ? "simulated" : "real",
       from: {
         input: fromAccount.name || fromAccount.address,
         address: fromAccount.address,
@@ -160,6 +210,9 @@ var HardkasTx = class {
           "Cannot append signature to an already completed signed transaction."
         );
       }
+      if (options?.append === void 0 && plan.status === "partially_signed") {
+        options = { ...options, append: true };
+      }
       if (!options?.append) {
         throw new Error(
           "Input file is a partially signed transaction. Use the --append flag to add your signature."
@@ -192,7 +245,7 @@ var HardkasTx = class {
         signature: `simulated-signature-of-${signerAddress}`
       };
       const newSignatures = [...sigs, signatureEntry].sort(
-        (a, b) => a.signer.localeCompare(b.signer)
+        (a, b) => deterministicCompare(a.signer, b.signer)
       );
       const newMeta = [
         ...partialTx.signatureMetadata || [],
@@ -247,7 +300,12 @@ var HardkasTx = class {
         if (!signerAddress) {
           throw new Error(`Signer account '${resolvedAccount.name}' has no address.`);
         }
-        const requiredSigners = options?.requiredSigners || [signerAddress];
+        const requiredSignersList = options?.requiredSigners || [signerAddress];
+        const requiredSigners = [];
+        for (const r of requiredSignersList) {
+          const acc = await this.sdk.accounts.resolve(r);
+          requiredSigners.push(acc.address || r);
+        }
         if (!requiredSigners.includes(signerAddress)) {
           throw new Error(
             `Signer '${signerAddress}' is not an authorized signer for this transaction.`
@@ -258,7 +316,7 @@ var HardkasTx = class {
           signature: `simulated-signature-of-${signerAddress}`
         };
         const signatures = [signatureEntry].sort(
-          (a, b) => a.signer.localeCompare(b.signer)
+          (a, b) => deterministicCompare(a.signer, b.signer)
         );
         const signatureMetadata = [
           {
@@ -387,14 +445,16 @@ var HardkasTx = class {
       { cwd: this.sdk.workspace.root }
     );
     const tracePath = receiptPath.replace(".json", ".trace.json");
+    const activeNetwork = this.sdk.config.config.defaultNetwork || "simnet";
+    const isSimulated = activeNetwork === "simulated" || this.sdk.config.config.networks?.[activeNetwork]?.kind === "simulated";
     const receiptBase = {
       schema: ARTIFACT_SCHEMAS.TX_RECEIPT,
       schemaVersion: "hardkas.receipt.v1",
       hardkasVersion: HARDKAS_VERSION,
       version: ARTIFACT_VERSION,
       hashVersion: CURRENT_HASH_VERSION,
-      networkId: this.sdk.network,
-      mode: "simulated",
+      networkId: activeNetwork,
+      mode: isSimulated ? "simulated" : "real",
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
       status: "confirmed",
       txId: simResult.receipt.txId,
@@ -429,8 +489,8 @@ var HardkasTx = class {
       hashVersion: CURRENT_HASH_VERSION,
       createdAt: receipt.createdAt,
       txId: receipt.txId,
-      mode: "simulated",
-      networkId: this.sdk.network,
+      mode: isSimulated ? "simulated" : "real",
+      networkId: activeNetwork,
       steps: traceSteps
     };
     traceBase.contentHash = calculateContentHash(traceBase, CURRENT_HASH_VERSION);
@@ -514,6 +574,23 @@ var HardkasTx = class {
       receiptPath
     };
   }
+  /**
+   * Explicitly appends a signature to a partially signed transaction.
+   */
+  async appendSignature(plan, account) {
+    return this.sign(plan, account, { append: true });
+  }
+  /**
+   * Fetches the current status of a transaction by ID.
+   */
+  async status(txId) {
+    const isLocal = txId.startsWith("simulated-");
+    if (isLocal) {
+      return { status: "simulated_confirmed" };
+    }
+    const result = await this.sdk.rpc.getTransaction(txId);
+    return result;
+  }
 };
 
 // src/l2.ts
@@ -546,11 +623,62 @@ var HardkasQuery = class {
   async getEngine() {
     if (this._engine) return this._engine;
     const { QueryEngine } = await import("@hardkas/query");
-    this._engine = new QueryEngine({
-      artifactDir: this.sdk.config.cwd
+    this._engine = await QueryEngine.create({
+      artifactDir: this.sdk.workspace.root,
+      autoSync: false
+      // We don't auto-sync on every getter
     });
     return this._engine;
   }
+  /**
+   * 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 path4 = await import("path");
+    const dbPath = path4.join(this.sdk.workspace.root, ".hardkas", "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();
+        }
+      }
+    );
+    return stats;
+  }
+  /**
+   * Fetches events from the query store.
+   */
+  async events(filter) {
+    const engine = await this.getEngine();
+    const { createQueryRequest } = await import("@hardkas/query");
+    const filters = [];
+    if (filter) {
+      for (const [k, v] of Object.entries(filter)) {
+        if (v) filters.push({ field: k, op: "eq", value: v });
+      }
+    }
+    const request = createQueryRequest({
+      domain: "events",
+      op: "list",
+      filters
+    });
+    const result = await engine.execute(request);
+    return result.items;
+  }
 };
 
 // src/localnet.ts
@@ -594,6 +722,7 @@ import {
   verifyArtifactIntegrity,
   writeArtifact as writeArtifact2
 } from "@hardkas/artifacts";
+import { deterministicCompare as deterministicCompare2 } from "@hardkas/core";
 function resolveReplayTargets(cwd, options) {
   if (options.path) {
     const fullPath = path.resolve(cwd, options.path);
@@ -670,7 +799,7 @@ function resolveFromDirectory(dir, source) {
   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));
+  plans.sort((a, b) => deterministicCompare2(b.createdAt, a.createdAt));
   for (const plan of plans) {
     const matchingReceipt = receipts.find(
       (r) => (
@@ -721,16 +850,24 @@ var HardkasReplay = class {
    * Verifies the deterministic artifact lineage of a transaction replay
    * against the mathematically reconstructed localnet state.
    */
-  async verify(options) {
-    const targets = resolveReplayTargets(this.sdk.config.cwd, options);
+  async verify(targetOrOptions, options) {
+    let opts = options || {};
+    if (typeof targetOrOptions === "string") {
+      opts.path = targetOrOptions;
+    } else if (targetOrOptions && "artifactId" in targetOrOptions) {
+      opts.path = targetOrOptions.artifactId;
+    } else if (targetOrOptions) {
+      opts = { ...opts, ...targetOrOptions };
+    }
+    const targets = resolveReplayTargets(this.sdk.config.cwd, opts);
     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}`);
     }
     const canonicalDirs = [
-      path.join(artifactDir, ".hardkas", "receipts"),
-      path.join(artifactDir, ".hardkas", "traces"),
-      path.join(artifactDir, ".hardkas", "deployments")
+      path.join(this.sdk.workspace.hardkasDir, "receipts"),
+      path.join(this.sdk.workspace.hardkasDir, "traces"),
+      path.join(this.sdk.workspace.hardkasDir, "deployments")
     ];
     const files = [];
     for (const dir of canonicalDirs) {
@@ -793,9 +930,9 @@ var HardkasReplay = class {
     let receipt;
     let verifyErrorMsg;
     let report = null;
-    if (options.workflowId) {
+    if (opts.workflowId) {
       try {
-        const wfArtifactPath = fs.readdirSync(this.sdk.workspace.artifactsDir).find((f) => f.includes(options.workflowId) && f.endsWith(".json"));
+        const wfArtifactPath = fs.readdirSync(this.sdk.workspace.artifactsDir).find((f) => f.includes(opts.workflowId) && f.endsWith(".json"));
         if (!wfArtifactPath) throw new Error("Workflow artifact not found");
         const wfArtifactStr = fs.readFileSync(
           path.join(this.sdk.workspace.artifactsDir, wfArtifactPath),
@@ -803,7 +940,7 @@ var HardkasReplay = class {
         );
         const wfArtifact = JSON.parse(wfArtifactStr);
         if (wfArtifact.schema !== "hardkas.workflow.v1") {
-          throw new Error(`Artifact ${options.workflowId} is not a workflow artifact`);
+          throw new Error(`Artifact ${opts.workflowId} is not a workflow artifact`);
         }
         const childArtifacts = wfArtifact.producedArtifacts || [];
         for (const childId of childArtifacts) {
@@ -882,6 +1019,33 @@ var HardkasReplay = class {
   }
 };
 
+// src/lineage.ts
+var HardkasLineage = class {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+  sdk;
+  /**
+   * Traces the lineage of an artifact, identifying ancestors and descendants.
+   */
+  async trace(target, options) {
+    const anchor = typeof target === "string" ? target : target.artifactId || target.contentHash || "";
+    if (!anchor) throw new Error("No anchor target provided for lineage trace.");
+    const { createQueryRequest, QueryEngine } = await import("@hardkas/query");
+    const engine = await QueryEngine.create({
+      artifactDir: this.sdk.workspace.root,
+      autoSync: false
+    });
+    const request = createQueryRequest({
+      domain: "lineage",
+      op: "chain",
+      params: { anchor, direction: options?.direction || "ancestors" }
+    });
+    const result = await engine.execute(request);
+    return result.items[0];
+  }
+};
+
 // src/workspace.ts
 import path2 from "path";
 import fs2 from "fs";
@@ -897,7 +1061,7 @@ var HardkasWorkspace = class {
     return path2.join(this.hardkasDir, "artifacts");
   }
   get localnetStatePath() {
-    return path2.join(this.hardkasDir, "localnet-state.json");
+    return path2.join(this.hardkasDir, "localnet.json");
   }
   get keystoreDir() {
     return path2.join(this.hardkasDir, "keystore");
@@ -927,6 +1091,7 @@ var HardkasWorkspace = class {
 // src/artifacts-manager.ts
 import path3 from "path";
 import fs3 from "fs";
+import { HardkasError } from "@hardkas/core";
 var HardkasArtifactsManager = class {
   constructor(workspace) {
     this.workspace = workspace;
@@ -1001,6 +1166,15 @@ var HardkasArtifactsManager = class {
     }
     const { readArtifact } = await import("@hardkas/artifacts");
     let filePath = id;
+    let resolvedPath = path3.resolve(this.workspace.root, filePath);
+    if (fs3.existsSync(resolvedPath)) {
+      resolvedPath = fs3.realpathSync(resolvedPath);
+    }
+    const rootRel = path3.relative(this.workspace.root, resolvedPath);
+    const artifactsRel = path3.relative(this.workspace.artifactsDir, resolvedPath);
+    if ((rootRel.startsWith("..") || path3.isAbsolute(rootRel)) && (artifactsRel.startsWith("..") || path3.isAbsolute(artifactsRel))) {
+      throw new HardkasError("PATH_TRAVERSAL", "Artifact path escapes workspace boundary");
+    }
     if (!fs3.existsSync(filePath)) {
       filePath = path3.join(this.workspace.artifactsDir, `${id}.json`);
       if (!fs3.existsSync(filePath)) {
@@ -1019,11 +1193,53 @@ var HardkasArtifactsManager = class {
     }
     return readArtifact(filePath);
   }
+  /**
+   * Alias for read().
+   */
+  async get(id) {
+    return this.read(id);
+  }
+  /**
+   * Lists all artifacts in the workspace.
+   */
+  async list() {
+    if (!fs3.existsSync(this.workspace.artifactsDir)) {
+      return [];
+    }
+    const { readArtifact } = await import("@hardkas/artifacts");
+    const files = fs3.readdirSync(this.workspace.artifactsDir);
+    const artifacts = [];
+    for (const file of files) {
+      if (file.endsWith(".json")) {
+        try {
+          const artifact = await readArtifact(path3.join(this.workspace.artifactsDir, file));
+          artifacts.push(artifact);
+        } catch (e) {
+        }
+      }
+    }
+    return artifacts;
+  }
+  /**
+   * Cryptographically verifies the determinism and integrity of an artifact.
+   * Throws an error with details if corruption or mismatch is found.
+   */
+  async verify(target) {
+    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);
+    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));
+    }
+    return result;
+  }
 };
 
 // src/workflow.ts
 import { HARDKAS_VERSION as HARDKAS_VERSION2 } from "@hardkas/artifacts";
-import { HardkasError, deterministicCompare } from "@hardkas/core";
+import { HardkasError as HardkasError2, deterministicCompare as deterministicCompare3 } from "@hardkas/core";
 var HardkasWorkflow = class {
   constructor(sdk) {
     this.sdk = sdk;
@@ -1070,12 +1286,12 @@ var HardkasWorkflow = class {
       try {
         if (step.type === "simulate-failure") {
           if (this.sdk.mode === "agent") {
-            throw new HardkasError(
+            throw new HardkasError2(
               "POLICY_DENIED",
               "simulate-failure is strictly prohibited in agent mode"
             );
           }
-          throw new HardkasError("MOCKED_FAIL", "Simulated failure for contract tests");
+          throw new HardkasError2("MOCKED_FAIL", "Simulated failure for contract tests");
         }
         let producedArtifactId = void 0;
         let result = void 0;
@@ -1236,9 +1452,9 @@ var HardkasWorkflow = class {
       artifactId: workflowId,
       status,
       steps: artifactSteps,
-      parentArtifacts: parentArtifacts.sort(deterministicCompare),
+      parentArtifacts: parentArtifacts.sort(deterministicCompare3),
       producedArtifacts: Array.from(new Set(producedArtifacts)).sort(
-        deterministicCompare
+        deterministicCompare3
       ),
       generationRange: {
         start: generationStart,
@@ -1308,7 +1524,7 @@ import {
 } from "@hardkas/artifacts";
 import {
   SOMPI_PER_KAS,
-  HardkasError as HardkasError3,
+  HardkasError as HardkasError4,
   parseKasToSompi as parseKasToSompi2,
   formatSompi as formatSompi2
 } from "@hardkas/core";
@@ -1333,6 +1549,7 @@ var Hardkas = class _Hardkas {
     this.query = new HardkasQuery(this);
     this.localnet = new HardkasLocalnet(this);
     this.replay = new HardkasReplay(this);
+    this.lineage = new HardkasLineage(this);
     this.workflow = new HardkasWorkflow(this);
   }
   config;
@@ -1344,6 +1561,7 @@ var Hardkas = class _Hardkas {
   query;
   localnet;
   replay;
+  lineage;
   workflow;
   mode;
   policy;
@@ -1362,6 +1580,39 @@ var Hardkas = class _Hardkas {
   static async open(dirOrOptions = ".") {
     const options = typeof dirOrOptions === "string" ? { cwd: dirOrOptions } : dirOrOptions;
     const loaded = await loadConfig(options);
+    const activeNetwork = options.network || loaded.config.defaultNetwork || "simnet";
+    const isSimulated = activeNetwork === "simulated" || loaded.config.networks?.[activeNetwork]?.kind === "simulated";
+    const autoBootstrap = options.autoBootstrap ?? (isSimulated ? true : false);
+    const fs4 = await import("fs");
+    const path4 = await import("path");
+    const cwd = options.cwd || process.cwd();
+    const hardkasDir = path4.join(cwd, ".hardkas");
+    if (autoBootstrap) {
+      if (!isSimulated) {
+        if (options.logger) {
+          options.logger.warn("[HardKAS] autoBootstrap ignored for non-simulated network");
+        }
+      } else {
+        if (!fs4.existsSync(hardkasDir)) {
+          if (options.logger) {
+            options.logger.info("[HardKAS] Auto-bootstrapping simulated workspace");
+          }
+          fs4.mkdirSync(hardkasDir, { recursive: true });
+        }
+        try {
+          const { loadOrCreateLocalnetState } = await import("@hardkas/localnet");
+          await loadOrCreateLocalnetState({ cwd });
+        } catch {
+        }
+      }
+    } else {
+      if (!fs4.existsSync(hardkasDir)) {
+        throw new HardkasError3("NOT_INITIALIZED", "Workspace not initialized. Run npx hardkas init . or pass autoBootstrap: true.");
+      }
+    }
+    if (options.network) {
+      loaded.config.defaultNetwork = options.network;
+    }
     return new _Hardkas(loaded, options);
   }
   /**
@@ -1392,19 +1643,19 @@ var Hardkas = class _Hardkas {
     switch (action) {
       case "network":
         if (!this.policy.allowNetwork)
-          throw new HardkasError2("POLICY_VIOLATION", msg("allowNetwork"));
+          throw new HardkasError3("POLICY_VIOLATION", msg("allowNetwork"));
         break;
       case "mainnet":
         if (!this.policy.allowMainnet)
-          throw new HardkasError2("POLICY_VIOLATION", msg("allowMainnet"));
+          throw new HardkasError3("POLICY_VIOLATION", msg("allowMainnet"));
         break;
       case "external-wallet":
         if (!this.policy.allowExternalWallet)
-          throw new HardkasError2("POLICY_VIOLATION", msg("allowExternalWallet"));
+          throw new HardkasError3("POLICY_VIOLATION", msg("allowExternalWallet"));
         break;
       case "mutation":
         if (this.policy.requireDryRun)
-          throw new HardkasError2("POLICY_VIOLATION", msg("requireDryRun"));
+          throw new HardkasError3("POLICY_VIOLATION", msg("requireDryRun"));
         break;
     }
   }
@@ -1415,8 +1666,9 @@ export {
   Hardkas,
   HardkasAccounts,
   HardkasArtifactsManager,
-  HardkasError3 as HardkasError,
+  HardkasError4 as HardkasError,
   HardkasL2,
+  HardkasLineage,
   HardkasLocalnet,
   HardkasQuery,
   HardkasReplay,

package/package.json

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