@hardkas/localnet 0.2.2-alpha → 0.3.0-alpha

package/dist/{chunk-W7ZBGUNK.js → chunk-DPHHOGGK.js}

@@ -2,6 +2,7 @@
 import fs from "fs/promises";
 import path from "path";
 import { existsSync } from "fs";
+import { writeFileAtomic } from "@hardkas/core";
 function getDefaultTracesDir(cwd = process.cwd()) {
   return path.join(cwd, ".hardkas", "traces");
 }
@@ -20,7 +21,7 @@ async function saveSimulatedTrace(trace, options) {
     await fs.mkdir(dir, { recursive: true });
   }
   const filePath = getTracePath(trace.txId, options?.cwd);
-  await fs.writeFile(filePath, JSON.stringify(trace, null, 2), "utf-8");
+  await writeFileAtomic(filePath, JSON.stringify(trace, null, 2), { encoding: "utf-8" });
   return filePath;
 }
 async function loadSimulatedTrace(txId, options) {

package/dist/{chunk-CXDVB3K4.js → chunk-GVBX3TPM.js}

@@ -2,6 +2,7 @@
 import fs from "fs/promises";
 import path from "path";
 import { existsSync } from "fs";
+import { writeFileAtomic } from "@hardkas/core";
 function getDefaultReceiptsDir(cwd = process.cwd()) {
   return path.join(cwd, ".hardkas", "receipts");
 }
@@ -20,7 +21,7 @@ async function saveSimulatedReceipt(receipt, options) {
     await fs.mkdir(dir, { recursive: true });
   }
   const filePath = getReceiptPath(receipt.txId, options?.cwd);
-  await fs.writeFile(filePath, JSON.stringify(receipt, null, 2), "utf-8");
+  await writeFileAtomic(filePath, JSON.stringify(receipt, null, 2), { encoding: "utf-8" });
   return filePath;
 }
 async function loadSimulatedReceipt(txId, options) {

package/dist/index.d.ts

@@ -1,5 +1,8 @@
+import * as _hardkas_artifacts from '@hardkas/artifacts';
 import { HardkasArtifactBase, Snapshot as Snapshot$1, ARTIFACT_SCHEMAS, TxReceipt, TxPlan } from '@hardkas/artifacts';
+import * as _hardkas_simulator from '@hardkas/simulator';
 import { ExecutionMode, NetworkId } from '@hardkas/core';
+import { KaspaRpcClient } from '@hardkas/kaspa-rpc';
 
 interface HardkasAccount {
     readonly name: string;
@@ -32,6 +35,11 @@ declare class SimulatedKaspaChain {
     getBalance(address: string): bigint;
     getUtxos(address: string): readonly SimulatedUtxo[];
     fund(address: string, amountSompi: bigint): SimulatedUtxo;
+    /**
+     * Creates a snapshot of the current chain state.
+     * Snapshot IDs use Date.now() and are intended for session-based
+     * debugging and restore points, not for canonical identity.
+     */
     snapshot(): Snapshot;
     restore(snapshot: Snapshot): void;
 }
@@ -68,6 +76,13 @@ interface LocalnetState extends HardkasArtifactBase {
     utxos: LocalnetUtxo[];
     snapshots?: Snapshot$1[];
     dag?: SimulatedDag;
+    forkSource?: {
+        network: string;
+        rpcUrl: string;
+        daaScore: string;
+        forkedAt: string;
+        addresses: string[];
+    };
 }
 interface SimulatedBlock {
     id: string;
@@ -76,6 +91,12 @@ interface SimulatedBlock {
     daaScore: string;
     acceptedTxIds: string[];
     isGenesis?: boolean;
+    /** GHOSTDAG blue_work for this block (computed by ApproxGhostdagEngine). */
+    blueWork?: string;
+    /** True if GHOSTDAG colored this block blue, false if red. */
+    isBlue?: boolean;
+    /** Full GHOSTDAG data if computed. */
+    ghostdagData?: _hardkas_simulator.GhostdagData;
 }
 interface SimulatedDag {
     blocks: Record<string, SimulatedBlock>;
@@ -88,6 +109,10 @@ interface SimulatedDag {
         winnerTxId: string;
         loserTxIds: string[];
     }>;
+    /** Internal GHOSTDAG store for this DAG session. */
+    ghostdagStore?: _hardkas_simulator.GhostdagStore;
+    /** Internal GHOSTDAG engine for this DAG session. */
+    ghostdagEngine?: _hardkas_simulator.ApproxGhostdagEngine;
 }
 interface StateTransition {
     preStateHash: string;
@@ -97,8 +122,8 @@ interface StateTransition {
 interface SimulationResult {
     ok: boolean;
     state: LocalnetState;
-    receipt: any;
-    planArtifact?: any;
+    receipt: _hardkas_artifacts.TxReceipt;
+    planArtifact?: _hardkas_artifacts.TxPlan;
     errors: string[];
 }
 interface ReplayInvariantResult {
@@ -106,9 +131,25 @@ interface ReplayInvariantResult {
     mismatches: string[];
 }
 interface ReplayVerificationReport {
+    schema: "hardkas.replayReport.v1";
+    txId: string;
     planOk: boolean;
     receiptOk: boolean;
     invariantsOk: boolean;
+    /** Honest check status to avoid overclaiming. */
+    checks: {
+        /** Whether the internal HardKAS workflow (Plan -> Receipt) was reproduced. */
+        workflowDeterministic: "reproduced" | "diverged" | "skipped";
+        /** HardKAS DOES NOT currently validate full Kaspa consensus (GHOSTDAG, etc). */
+        consensusValidation: "unimplemented" | "partial" | "skipped";
+        /** HardKAS DOES NOT currently validate L2 bridge logic. */
+        l2BridgeCorrectness: "unimplemented" | "partial" | "skipped";
+    };
+    divergences: Array<{
+        path: string;
+        expected: any;
+        actual: any;
+    }>;
     errors: string[];
 }
 interface SnapshotVerificationResult {
@@ -210,6 +251,7 @@ options?: {
 interface StoredSimulatedTxReceipt extends HardkasArtifactBase {
     schema: typeof ARTIFACT_SCHEMAS.TX_RECEIPT;
     version: "1.0.0-alpha";
+    hashVersion?: number | string;
     txId: string;
     status: "confirmed" | "failed";
     mode: ExecutionMode;
@@ -259,6 +301,8 @@ type StoredTraceEvent = {
 };
 interface StoredSimulatedTxTrace extends HardkasArtifactBase {
     readonly schema: typeof ARTIFACT_SCHEMAS.TX_TRACE;
+    readonly version: string;
+    readonly hashVersion?: number | string;
     readonly txId: string;
     readonly mode: ExecutionMode;
     readonly networkId: NetworkId;
@@ -291,6 +335,8 @@ interface SimulatedReplaySummary {
 }
 /**
  * Verifies that a transaction replay matches the original artifacts.
+ * Implements an honest replay model that differentiates between
+ * reproduced results and unimplemented consensus/bridge features.
  */
 declare function verifyReplay(state: LocalnetState, originalPlan: TxPlan, originalReceipt: TxReceipt): ReplayVerificationReport;
 /**
@@ -303,7 +349,9 @@ declare function getSimulatedReplaySummary(txId: string, options?: {
 /**
  * Creates a fresh simulated DAG with a genesis block.
  */
-declare function createSimulatedDag(): SimulatedDag;
+declare function createSimulatedDag(options?: {
+    k?: number;
+}): SimulatedDag;
 /**
  * Adds a block to the DAG.
  */
@@ -330,5 +378,30 @@ declare function resolveConflictsDeterministically(txs: Array<{
     displaced: string[];
     conflicts: any[];
 };
+/**
+ * Get the blue/red coloring of all blocks in the DAG.
+ * Returns a map of blockId → { isBlue, blueWork, blueScore }.
+ */
+declare function getDagColoring(dag: SimulatedDag): Map<string, {
+    isBlue: boolean;
+    blueWork: string;
+    blueScore: number;
+}>;
+/**
+ * Get the selected parent chain from sink to genesis.
+ */
+declare function getSelectedChain(dag: SimulatedDag): string[];
+/**
+ * Helper to find the best tip block according to GHOSTDAG.
+ */
+declare function findBestTip(dag: SimulatedDag): string;
+
+interface ForkOptions {
+    network: string;
+    rpcUrl: string;
+    addresses: string[];
+    atDaaScore?: string;
+}
+declare function forkFromNetwork(rpc: KaspaRpcClient, opts: ForkOptions): Promise<LocalnetState>;
 
-export { type CreateInitialStateOptions, DUST_LIMIT_SOMPI, type FundAddressInput, type HardkasAccount, type HardkasDevnet, type LocalnetAccount, type LocalnetState, type LocalnetUtxo, type ReplayInvariantResult, type ReplayVerificationReport, type SimulatedBlock, type SimulatedDag, SimulatedKaspaChain, type SimulatedPaymentInput, type SimulatedReplaySummary, type SimulatedUtxo, type SimulationResult, type Snapshot, type SnapshotRestoreResult, type SnapshotVerificationResult, type StateTransition, type StoredSimulatedTxReceipt, type StoredSimulatedTxTrace, type StoredTraceEvent, addSimulatedBlock, applySimulatedPayment, applySimulatedPlan, calculateAccountsHash, calculateStateHash, calculateUtxoSetHash, createDeterministicAccounts, createInitialLocalnetState, createLocalnetSnapshot, createSimulatedDag, fundAddress, getAccountBalanceSompi, getAddressBalanceSompi, getDefaultLocalnetDir, getDefaultLocalnetStatePath, getDefaultReceiptsDir, getDefaultTracesDir, getReceiptPath, getSimulatedReplaySummary, getSpendableUtxos, getTracePath, listSimulatedReceipts, listSimulatedTraces, loadLocalnetState, loadOrCreateLocalnetState, loadSimulatedReceipt, loadSimulatedTrace, moveSink, resetLocalnetState, resolveAccountAddress, resolveAccountAddressFromState, resolveConflictsDeterministically, restoreLocalnetSnapshot, saveLocalnetState, saveSimulatedReceipt, saveSimulatedTrace, startSimulatedDevnet, verifyReplay, verifySnapshot };
+export { type CreateInitialStateOptions, DUST_LIMIT_SOMPI, type ForkOptions, type FundAddressInput, type HardkasAccount, type HardkasDevnet, type LocalnetAccount, type LocalnetState, type LocalnetUtxo, type ReplayInvariantResult, type ReplayVerificationReport, type SimulatedBlock, type SimulatedDag, SimulatedKaspaChain, type SimulatedPaymentInput, type SimulatedReplaySummary, type SimulatedUtxo, type SimulationResult, type Snapshot, type SnapshotRestoreResult, type SnapshotVerificationResult, type StateTransition, type StoredSimulatedTxReceipt, type StoredSimulatedTxTrace, type StoredTraceEvent, addSimulatedBlock, applySimulatedPayment, applySimulatedPlan, calculateAccountsHash, calculateStateHash, calculateUtxoSetHash, createDeterministicAccounts, createInitialLocalnetState, createLocalnetSnapshot, createSimulatedDag, findBestTip, forkFromNetwork, fundAddress, getAccountBalanceSompi, getAddressBalanceSompi, getDagColoring, getDefaultLocalnetDir, getDefaultLocalnetStatePath, getDefaultReceiptsDir, getDefaultTracesDir, getReceiptPath, getSelectedChain, getSimulatedReplaySummary, getSpendableUtxos, getTracePath, listSimulatedReceipts, listSimulatedTraces, loadLocalnetState, loadOrCreateLocalnetState, loadSimulatedReceipt, loadSimulatedTrace, moveSink, resetLocalnetState, resolveAccountAddress, resolveAccountAddressFromState, resolveConflictsDeterministically, restoreLocalnetSnapshot, saveLocalnetState, saveSimulatedReceipt, saveSimulatedTrace, startSimulatedDevnet, verifyReplay, verifySnapshot };

package/dist/index.js

@@ -4,14 +4,14 @@ import {
   listSimulatedReceipts,
   loadSimulatedReceipt,
   saveSimulatedReceipt
-} from "./chunk-CXDVB3K4.js";
+} from "./chunk-GVBX3TPM.js";
 import {
   getDefaultTracesDir,
   getTracePath,
   listSimulatedTraces,
   loadSimulatedTrace,
   saveSimulatedTrace
-} from "./chunk-W7ZBGUNK.js";
+} from "./chunk-DPHHOGGK.js";
 
 // src/accounts.ts
 function createDeterministicAccounts(input) {
@@ -22,21 +22,21 @@ function createDeterministicAccounts(input) {
     const name = names[index] ?? `account${index}`;
     return {
       name,
-      address: `kaspa:sim_${name}`,
+      address: `kaspasim:${name}`,
       balanceSompi: initialBalanceSompi
     };
   });
 }
 function resolveAccountAddress(input) {
-  if (input.startsWith("kaspa:")) {
+  if (input.startsWith("kaspa:") || input.startsWith("kaspasim:")) {
     return input;
   }
   const aliases = {
-    alice: "kaspa:sim_alice",
-    bob: "kaspa:sim_bob",
-    carol: "kaspa:sim_carol",
-    dave: "kaspa:sim_dave",
-    erin: "kaspa:sim_erin"
+    alice: "kaspasim:alice",
+    bob: "kaspasim:bob",
+    carol: "kaspasim:carol",
+    dave: "kaspasim:dave",
+    erin: "kaspasim:erin"
   };
   const resolved = aliases[input.toLowerCase()];
   if (!resolved) {
@@ -77,7 +77,7 @@ var SimulatedKaspaChain = class {
       throw new Error("Faucet amount must be positive.");
     }
     const utxo = {
-      id: `faucet:${Date.now().toString(36)}:${Math.random().toString(36).slice(2)}`,
+      id: `faucet:${address.slice(-8)}:${this.daaScore}:${this.utxos.length}`,
       address,
       amountSompi,
       spent: false
@@ -86,6 +86,11 @@ var SimulatedKaspaChain = class {
     this.mineBlock();
     return utxo;
   }
+  /**
+   * Creates a snapshot of the current chain state.
+   * Snapshot IDs use Date.now() and are intended for session-based 
+   * debugging and restore points, not for canonical identity.
+   */
   snapshot() {
     return {
       id: `snapshot:${Date.now().toString(36)}`,
@@ -161,6 +166,7 @@ function resolveAccountAddressFromState(state, nameOrAddress) {
 // src/store.ts
 import fs from "fs/promises";
 import path from "path";
+import { writeFileAtomic } from "@hardkas/core";
 function getDefaultLocalnetDir(cwd = process.cwd()) {
   return path.join(cwd, ".hardkas");
 }
@@ -171,7 +177,7 @@ async function saveLocalnetState(state, filePath) {
   const targetPath = filePath ?? getDefaultLocalnetStatePath();
   const dir = path.dirname(targetPath);
   await fs.mkdir(dir, { recursive: true });
-  await fs.writeFile(targetPath, JSON.stringify(state, null, 2), "utf-8");
+  await writeFileAtomic(targetPath, JSON.stringify(state, null, 2), { encoding: "utf-8" });
 }
 async function loadLocalnetState(filePath) {
   const targetPath = filePath ?? getDefaultLocalnetStatePath();
@@ -211,7 +217,7 @@ function fundAddress(state, input) {
   }
   const nextDaaScore = (BigInt(state.daaScore) + 1n).toString();
   const newUtxo = {
-    id: `faucet:${Date.now().toString(36)}:${Math.random().toString(36).slice(2)}`,
+    id: `faucet:${input.address.slice(-8)}:${nextDaaScore}:0`,
     address: input.address,
     amountSompi: input.amountSompi.toString(),
     spent: false,
@@ -339,6 +345,24 @@ import {
   createSimulatedTxReceipt,
   calculateContentHash as calculateContentHash2
 } from "@hardkas/artifacts";
+function buildDagContextFromState(state) {
+  if (state.dag) {
+    return {
+      mode: "dag-light",
+      sink: state.dag.sink,
+      acceptedTxIds: state.dag.acceptedTxIds,
+      displacedTxIds: state.dag.displacedTxIds,
+      conflictSet: state.dag.conflictSet
+    };
+  }
+  return { mode: "linear", sink: "linear-pseudo-sink" };
+}
+function generateDeterministicFailedTxId(preStateHash, errorMessage, daaScore) {
+  const normalized = errorMessage.replace(/[^a-zA-Z0-9_:. -]/g, "");
+  const input = `failed:${preStateHash}:${normalized}:${daaScore}`;
+  const hash = createHash("sha256").update(input).digest("hex").slice(0, 32);
+  return `simtx_failed_${hash}`;
+}
 function generateDeterministicTxId(planArtifact, preStateHash, daaScore) {
   const planHash = planArtifact.contentHash || calculateContentHash2(planArtifact);
   const input = `${planHash}:${preStateHash}:${daaScore}`;
@@ -441,21 +465,11 @@ function applySimulatedPayment(state, input) {
     const receipt = createSimulatedTxReceipt(planArtifact, txId, {
       spentUtxoIds,
       createdUtxoIds,
-      daaScore: nextDaaScore
+      daaScore: nextDaaScore,
+      preStateHash,
+      postStateHash,
+      dagContext: buildDagContextFromState(state)
     });
-    receipt.preStateHash = preStateHash;
-    receipt.postStateHash = postStateHash;
-    if (state.dag) {
-      receipt.dagContext = {
-        mode: "dag-light",
-        sink: state.dag.sink,
-        acceptedTxIds: state.dag.acceptedTxIds,
-        displacedTxIds: state.dag.displacedTxIds,
-        conflictSet: state.dag.conflictSet
-      };
-    } else {
-      receipt.dagContext = { mode: "linear", sink: "linear-pseudo-sink" };
-    }
     return {
       ok: true,
       state: nextState,
@@ -464,16 +478,18 @@ function applySimulatedPayment(state, input) {
       errors
     };
   } catch (error) {
-    const txId = "failed-" + Date.now();
+    const daaScore = state.daaScore || "0";
+    const txId = generateDeterministicFailedTxId(preStateHash, error.message, daaScore);
     const receipt = {
       schema: "hardkas.txReceipt",
       status: "failed",
       mode: "simulated",
       txId,
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      createdAt: "1970-01-01T00:00:00.000Z",
       errors: [error.message],
       preStateHash,
-      postStateHash: preStateHash
+      postStateHash: preStateHash,
+      dagContext: buildDagContextFromState(state)
     };
     return {
       ok: false,
@@ -530,32 +546,25 @@ function applySimulatedPlan(state, planArtifact, options) {
     const receipt = createSimulatedTxReceipt(planArtifact, txId, {
       spentUtxoIds,
       createdUtxoIds,
-      daaScore: nextDaaScore
+      daaScore: nextDaaScore,
+      preStateHash,
+      postStateHash,
+      dagContext: buildDagContextFromState(state)
     });
-    receipt.preStateHash = preStateHash;
-    receipt.postStateHash = postStateHash;
-    if (state.dag) {
-      receipt.dagContext = {
-        mode: "dag-light",
-        sink: state.dag.sink,
-        acceptedTxIds: state.dag.acceptedTxIds,
-        displacedTxIds: state.dag.displacedTxIds,
-        conflictSet: state.dag.conflictSet
-      };
-    } else {
-      receipt.dagContext = { mode: "linear", sink: "linear-pseudo-sink" };
-    }
     return { ok: true, state: nextState, receipt, planArtifact, errors };
   } catch (error) {
+    const daaScore = state.daaScore || "0";
+    const txId = generateDeterministicFailedTxId(preStateHash, error.message, daaScore);
     const receipt = {
       schema: "hardkas.txReceipt",
       status: "failed",
       mode: "simulated",
-      txId: "failed-replay",
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      txId,
+      createdAt: "1970-01-01T00:00:00.000Z",
       errors: [error.message],
       preStateHash,
-      postStateHash: preStateHash
+      postStateHash: preStateHash,
+      dagContext: buildDagContextFromState(state)
     };
     return { ok: false, state, receipt, errors: [error.message] };
   }
@@ -563,61 +572,90 @@ function applySimulatedPlan(state, planArtifact, options) {
 
 // src/replay.ts
 import {
-  calculateContentHash as calculateContentHash3
+  calculateContentHash as calculateContentHash3,
+  diffArtifacts
 } from "@hardkas/artifacts";
 import { coreEvents } from "@hardkas/core";
 function verifyReplay(state, originalPlan, originalReceipt) {
   const errors = [];
+  const reportDivergences = [];
   const currentPlanHash = calculateContentHash3(originalPlan);
+  let planOk = true;
   if (originalPlan.contentHash && currentPlanHash !== originalPlan.contentHash) {
+    planOk = false;
     const errorMsg = `TxPlan contentHash mismatch: expected ${originalPlan.contentHash}, got ${currentPlanHash}`;
     errors.push(errorMsg);
-    coreEvents.normalizeAndEmit({
-      kind: "replay.divergence",
-      txId: originalReceipt.txId,
-      field: "planHash",
-      expected: originalPlan.contentHash,
-      actual: currentPlanHash
+    reportDivergences.push({ path: "plan.contentHash", expected: originalPlan.contentHash, actual: currentPlanHash });
+  }
+  const originalPreState = originalReceipt.preStateHash;
+  if (originalPreState) {
+    const currentStateHash = calculateStateHash(state);
+    if (currentStateHash !== originalPreState) {
+      const errorMsg = `preStateHash mismatch: expected ${originalPreState}, got ${currentStateHash}`;
+      errors.push(errorMsg);
+      reportDivergences.push({
+        path: "preStateHash",
+        expected: originalPreState,
+        actual: currentStateHash
+      });
+    }
+  } else {
+    reportDivergences.push({
+      path: "preStateHash",
+      expected: "present",
+      actual: "missing",
+      severity: "warning"
     });
   }
   const result = applySimulatedPlan(state, originalPlan, { txId: originalReceipt.txId });
   const replayReceipt = result.receipt;
-  const checks = [
-    { field: "status", expected: originalReceipt.status, actual: replayReceipt.status },
-    { field: "mass", expected: String(originalReceipt.mass), actual: String(replayReceipt.mass) },
-    { field: "feeSompi", expected: String(originalReceipt.feeSompi), actual: String(replayReceipt.feeSompi) },
-    { field: "preStateHash", expected: String(originalReceipt.preStateHash), actual: String(replayReceipt.preStateHash) },
-    { field: "postStateHash", expected: String(originalReceipt.postStateHash), actual: String(replayReceipt.postStateHash) },
-    { field: "spentUtxos", expected: String(originalReceipt.spentUtxoIds?.length), actual: String(replayReceipt.spentUtxoIds?.length) }
-  ];
-  for (const check of checks) {
-    if (check.expected !== check.actual) {
-      errors.push(`${check.field} mismatch: expected ${check.expected}, got ${check.actual}`);
-      coreEvents.normalizeAndEmit({
-        kind: "replay.divergence",
-        txId: originalReceipt.txId,
-        field: check.field,
-        expected: check.expected,
-        actual: check.actual
+  const diff = diffArtifacts(originalReceipt, replayReceipt);
+  if (!diff.identical) {
+    for (const entry of diff.entries) {
+      reportDivergences.push({
+        path: `receipt.${entry.path}`,
+        expected: entry.left,
+        actual: entry.right
       });
+      errors.push(`Receipt divergence at ${entry.path}: expected ${JSON.stringify(entry.left)}, got ${JSON.stringify(entry.right)}`);
     }
   }
-  if (errors.length === 0) {
+  for (const div of reportDivergences) {
+    coreEvents.normalizeAndEmit({
+      kind: "replay.divergence",
+      txId: originalReceipt.txId,
+      field: div.path,
+      expected: String(div.expected),
+      actual: String(div.actual)
+    });
+  }
+  const invariantsOk = errors.length === 0;
+  if (invariantsOk) {
     coreEvents.normalizeAndEmit({
       kind: "replay.verified",
       txId: originalReceipt.txId
     });
   }
   return {
-    planOk: !errors.some((e) => e.includes("TxPlan")),
-    receiptOk: !errors.some((e) => e.includes("Status") || e.includes("Hash")),
-    invariantsOk: errors.length === 0,
+    schema: "hardkas.replayReport.v1",
+    txId: originalReceipt.txId,
+    planOk,
+    receiptOk: !diff.entries.some((e) => !e.path.startsWith("plan")),
+    invariantsOk,
+    checks: {
+      workflowDeterministic: invariantsOk ? "reproduced" : "diverged",
+      consensusValidation: "unimplemented",
+      // Explicit trust boundary
+      l2BridgeCorrectness: "unimplemented"
+      // Explicit trust boundary
+    },
+    divergences: reportDivergences,
     errors
   };
 }
 async function getSimulatedReplaySummary(txId, options = {}) {
-  const { loadSimulatedReceipt: loadSimulatedReceipt2 } = await import("./receipts-ICI3GEJW.js");
-  const { loadSimulatedTrace: loadSimulatedTrace2 } = await import("./traces-DSACQ53V.js");
+  const { loadSimulatedReceipt: loadSimulatedReceipt2 } = await import("./receipts-JSTNZMDD.js");
+  const { loadSimulatedTrace: loadSimulatedTrace2 } = await import("./traces-HDVV77MQ.js");
   const receipt = await loadSimulatedReceipt2(txId, options);
   const trace = await loadSimulatedTrace2(txId, options);
   if (!receipt || !trace) {
@@ -638,7 +676,51 @@ async function getSimulatedReplaySummary(txId, options = {}) {
 }
 
 // src/dag.ts
-function createSimulatedDag() {
+import {
+  ApproxGhostdagEngine,
+  GhostdagStore,
+  genesisGhostdagData,
+  findSelectedParent,
+  GENESIS_HASH as SIM_GENESIS_HASH
+} from "@hardkas/simulator";
+var dagIdMaps = /* @__PURE__ */ new WeakMap();
+var dagReverseIdMaps = /* @__PURE__ */ new WeakMap();
+function getIdMap(dag) {
+  let m = dagIdMaps.get(dag);
+  if (!m) {
+    m = /* @__PURE__ */ new Map();
+    m.set("genesis", SIM_GENESIS_HASH);
+    dagIdMaps.set(dag, m);
+  }
+  return m;
+}
+function getReverseIdMap(dag) {
+  let m = dagReverseIdMaps.get(dag);
+  if (!m) {
+    m = /* @__PURE__ */ new Map();
+    m.set(SIM_GENESIS_HASH, "genesis");
+    dagReverseIdMaps.set(dag, m);
+  }
+  return m;
+}
+function toGhostdagSimBlock(block, idMap) {
+  const hash = idMap.get(block.id) || block.id;
+  const parents = block.parents.map((p) => idMap.get(p) || p);
+  return {
+    header: {
+      hash,
+      parents,
+      timestampUs: 0,
+      minerId: 0,
+      bits: 1e3,
+      // Default difficulty for simulation
+      nonce: 0
+    }
+  };
+}
+function createSimulatedDag(options) {
+  const k = options?.k ?? 18;
+  const engine = new ApproxGhostdagEngine(k);
   const genesis = {
     id: "genesis",
     parents: [],
@@ -647,21 +729,70 @@ function createSimulatedDag() {
     acceptedTxIds: [],
     isGenesis: true
   };
-  return {
+  const gdStore = new GhostdagStore();
+  gdStore.insert(SIM_GENESIS_HASH, genesisGhostdagData(SIM_GENESIS_HASH));
+  const dag = {
     blocks: { [genesis.id]: genesis },
     sink: genesis.id,
     selectedPathToSink: [genesis.id],
     acceptedTxIds: [],
     displacedTxIds: [],
-    conflictSet: []
+    conflictSet: [],
+    ghostdagStore: gdStore,
+    ghostdagEngine: engine
   };
+  const idMap = /* @__PURE__ */ new Map();
+  idMap.set("genesis", SIM_GENESIS_HASH);
+  dagIdMaps.set(dag, idMap);
+  const reverseIdMap = /* @__PURE__ */ new Map();
+  reverseIdMap.set(SIM_GENESIS_HASH, "genesis");
+  dagReverseIdMaps.set(dag, reverseIdMap);
+  return dag;
 }
 function addSimulatedBlock(dag, block) {
-  const newBlocks = { ...dag.blocks, [block.id]: block };
-  return {
+  const idMap = getIdMap(dag);
+  const reverseIdMap = getReverseIdMap(dag);
+  const gdBlock = toGhostdagSimBlock(block, idMap);
+  const allGdBlocks = /* @__PURE__ */ new Map();
+  for (const b of Object.values(dag.blocks)) {
+    allGdBlocks.set(idMap.get(b.id) || b.id, toGhostdagSimBlock(b, idMap));
+  }
+  allGdBlocks.set(gdBlock.header.hash, gdBlock);
+  const gdStore = dag.ghostdagStore || new GhostdagStore();
+  const dagEngine = dag.ghostdagEngine || new ApproxGhostdagEngine();
+  const gdData = dagEngine.computeGhostdag(gdBlock, allGdBlocks, gdStore);
+  gdStore.insert(gdBlock.header.hash, gdData);
+  const updatedBlock = {
+    ...block,
+    ghostdagData: gdData,
+    blueWork: gdData.blueWork.toString(),
+    isBlue: true
+    // The block itself is the new tip on its own path
+  };
+  if (!idMap.has(block.id)) {
+    idMap.set(block.id, block.id);
+    reverseIdMap.set(block.id, block.id);
+  }
+  const newBlocks = { ...dag.blocks, [updatedBlock.id]: updatedBlock };
+  for (const blueHash of gdData.mergesetBlues) {
+    const id = reverseIdMap.get(blueHash) || blueHash;
+    if (newBlocks[id]) {
+      newBlocks[id] = { ...newBlocks[id], isBlue: true };
+    }
+  }
+  for (const redHash of gdData.mergesetReds) {
+    const id = reverseIdMap.get(redHash) || redHash;
+    if (newBlocks[id]) {
+      newBlocks[id] = { ...newBlocks[id], isBlue: false };
+    }
+  }
+  const newDag = {
     ...dag,
     blocks: newBlocks
   };
+  dagIdMaps.set(newDag, idMap);
+  dagReverseIdMaps.set(newDag, reverseIdMap);
+  return newDag;
 }
 function moveSink(dag, newSinkId, txProvider) {
   if (!dag.blocks[newSinkId]) {
@@ -670,6 +801,12 @@ function moveSink(dag, newSinkId, txProvider) {
   const selectedPath = calculateSelectedPath(dag, newSinkId);
   const reachableBlocks = identifyReachableBlocks(dag, newSinkId);
   const sortedBlocks = reachableBlocks.sort((a, b) => {
+    if (a.ghostdagData && b.ghostdagData) {
+      const workA = BigInt(a.blueWork || "0");
+      const workB = BigInt(b.blueWork || "0");
+      if (workA !== workB) return workA < workB ? -1 : 1;
+      if (a.isBlue !== b.isBlue) return a.isBlue ? -1 : 1;
+    }
     const daaA = BigInt(a.daaScore);
     const daaB = BigInt(b.daaScore);
     if (daaA !== daaB) return daaA < daaB ? -1 : 1;
@@ -742,14 +879,21 @@ function moveSink(dag, newSinkId, txProvider) {
   };
 }
 function calculateSelectedPath(dag, sinkId) {
+  const reverseIdMap = getReverseIdMap(dag);
   const path2 = [];
   let currentId = sinkId;
   while (currentId) {
     const current = dag.blocks[currentId];
     if (!current) break;
     path2.unshift(current);
-    if (current.parents.length === 0) break;
-    currentId = current.parents[0];
+    if (current.isGenesis) break;
+    if (current.ghostdagData) {
+      const spHash = current.ghostdagData.selectedParent;
+      currentId = reverseIdMap.get(spHash) || spHash;
+    } else {
+      if (current.parents.length === 0) break;
+      currentId = current.parents[0];
+    }
   }
   return path2;
 }
@@ -780,6 +924,12 @@ function resolveConflictsDeterministically(txs, dag) {
     const inPathA = dag.selectedPathToSink.includes(a.blockId);
     const inPathB = dag.selectedPathToSink.includes(b.blockId);
     if (inPathA !== inPathB) return inPathA ? -1 : 1;
+    if (blockA.ghostdagData && blockB.ghostdagData) {
+      if (blockA.isBlue !== blockB.isBlue) return blockA.isBlue ? -1 : 1;
+      const workA = BigInt(blockA.blueWork || "0");
+      const workB = BigInt(blockB.blueWork || "0");
+      if (workA !== workB) return workA < workB ? -1 : 1;
+    }
     const daaA = BigInt(blockA.daaScore);
     const daaB = BigInt(blockB.daaScore);
     if (daaA !== daaB) return daaA < daaB ? -1 : 1;
@@ -816,6 +966,85 @@ function resolveConflictsDeterministically(txs, dag) {
   }
   return { accepted, displaced, conflicts };
 }
+function getDagColoring(dag) {
+  const coloring = /* @__PURE__ */ new Map();
+  for (const [id, block] of Object.entries(dag.blocks)) {
+    coloring.set(id, {
+      isBlue: block.isBlue || false,
+      blueWork: block.blueWork || "0",
+      blueScore: block.ghostdagData?.blueScore || Number(block.blueScore) || 0
+    });
+  }
+  return coloring;
+}
+function getSelectedChain(dag) {
+  return calculateSelectedPath(dag, dag.sink).map((b) => b.id);
+}
+function findBestTip(dag) {
+  const idMap = getIdMap(dag);
+  const allBlockIds = Object.keys(dag.blocks);
+  if (allBlockIds.length === 0) return "genesis";
+  const parentIds = /* @__PURE__ */ new Set();
+  for (const block of Object.values(dag.blocks)) {
+    for (const p of block.parents) {
+      parentIds.add(p);
+    }
+  }
+  const tips = allBlockIds.filter((id) => !parentIds.has(id));
+  if (tips.length === 0) return dag.sink;
+  const tipData = tips.map((id) => ({
+    hash: idMap.get(id) || id,
+    blueWork: BigInt(dag.blocks[id].blueWork || "0")
+  }));
+  const bestTipHash = findSelectedParent(tipData);
+  const bestTip = tips.find((id) => (idMap.get(id) || id) === bestTipHash);
+  return bestTip || tips[0];
+}
+
+// src/fork.ts
+import { ARTIFACT_SCHEMAS as ARTIFACT_SCHEMAS2, HARDKAS_VERSION as HARDKAS_VERSION4, ARTIFACT_VERSION as ARTIFACT_VERSION3 } from "@hardkas/artifacts";
+async function forkFromNetwork(rpc, opts) {
+  const info = await rpc.getInfo();
+  const networkId = info.networkId || opts.network;
+  const currentDaaScore = info.virtualDaaScore?.toString() || "0";
+  const targetDaaScore = opts.atDaaScore || currentDaaScore;
+  const utxos = [];
+  for (const address of opts.addresses) {
+    const rpcUtxos = await rpc.getUtxosByAddress(address);
+    for (const u of rpcUtxos) {
+      utxos.push({
+        id: `${u.outpoint.transactionId}:${u.outpoint.index}`,
+        address: u.address,
+        amountSompi: u.amountSompi.toString(),
+        spent: false,
+        createdAtDaaScore: u.blockDaaScore?.toString() || "0"
+      });
+    }
+  }
+  const state = {
+    schema: ARTIFACT_SCHEMAS2.LOCALNET_STATE,
+    hardkasVersion: HARDKAS_VERSION4,
+    version: ARTIFACT_VERSION3,
+    hashVersion: "sha256-canonical",
+    mode: "simulated",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    networkId,
+    daaScore: targetDaaScore,
+    accounts: opts.addresses.map((addr, i) => ({
+      name: `forked_${i}`,
+      address: addr
+    })),
+    utxos,
+    forkSource: {
+      network: opts.network,
+      rpcUrl: opts.rpcUrl,
+      daaScore: targetDaaScore,
+      forkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      addresses: opts.addresses
+    }
+  };
+  return state;
+}
 export {
   DUST_LIMIT_SOMPI,
   SimulatedKaspaChain,
@@ -829,14 +1058,18 @@ export {
   createInitialLocalnetState,
   createLocalnetSnapshot,
   createSimulatedDag,
+  findBestTip,
+  forkFromNetwork,
   fundAddress,
   getAccountBalanceSompi,
   getAddressBalanceSompi,
+  getDagColoring,
   getDefaultLocalnetDir,
   getDefaultLocalnetStatePath,
   getDefaultReceiptsDir,
   getDefaultTracesDir,
   getReceiptPath,
+  getSelectedChain,
   getSimulatedReplaySummary,
   getSpendableUtxos,
   getTracePath,

package/dist/{receipts-ICI3GEJW.js → receipts-JSTNZMDD.js}

@@ -4,7 +4,7 @@ import {
   listSimulatedReceipts,
   loadSimulatedReceipt,
   saveSimulatedReceipt
-} from "./chunk-CXDVB3K4.js";
+} from "./chunk-GVBX3TPM.js";
 export {
   getDefaultReceiptsDir,
   getReceiptPath,

package/dist/{traces-DSACQ53V.js → traces-HDVV77MQ.js}

@@ -4,7 +4,7 @@ import {
   listSimulatedTraces,
   loadSimulatedTrace,
   saveSimulatedTrace
-} from "./chunk-W7ZBGUNK.js";
+} from "./chunk-DPHHOGGK.js";
 export {
   getDefaultTracesDir,
   getTracePath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/localnet",
-  "version": "0.2.2-alpha",
+  "version": "0.3.0-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -8,12 +8,15 @@
     ".": "./dist/index.js"
   },
   "dependencies": {
-    "@hardkas/artifacts": "0.2.2-alpha",
-    "@hardkas/tx-builder": "0.2.2-alpha",
-    "@hardkas/core": "0.2.2-alpha",
-    "@hardkas/query": "0.2.2-alpha"
+    "@hardkas/artifacts": "0.3.0-alpha",
+    "@hardkas/query": "0.3.0-alpha",
+    "@hardkas/tx-builder": "0.3.0-alpha",
+    "@hardkas/core": "0.3.0-alpha",
+    "@hardkas/kaspa-rpc": "0.3.0-alpha",
+    "@hardkas/simulator": "0.3.0-alpha"
   },
   "devDependencies": {
+    "fast-check": "^4.8.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"