@hardkas/localnet 0.5.4-alpha → 0.6.0-alpha

package/dist/{chunk-DPHHOGGK.js → chunk-6AICYLVR.js}

@@ -3,8 +3,9 @@ import fs from "fs/promises";
 import path from "path";
 import { existsSync } from "fs";
 import { writeFileAtomic } from "@hardkas/core";
+import { deterministicCompare } from "@hardkas/core";
 function getDefaultTracesDir(cwd = process.cwd()) {
-  return path.join(cwd, ".hardkas", "traces");
+  return path.join(cwd, ".hardkas", "artifacts");
 }
 function getTracePath(txId, cwd) {
   validateTxId(txId);
@@ -49,7 +50,7 @@ async function listSimulatedTraces(options) {
       }
     }
   }
-  return traces.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  return traces.sort((a, b) => deterministicCompare(b.createdAt, a.createdAt));
 }
 
 export {

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

@@ -3,8 +3,9 @@ import fs from "fs/promises";
 import path from "path";
 import { existsSync } from "fs";
 import { writeFileAtomic } from "@hardkas/core";
+import { deterministicCompare } from "@hardkas/core";
 function getDefaultReceiptsDir(cwd = process.cwd()) {
-  return path.join(cwd, ".hardkas", "receipts");
+  return path.join(cwd, ".hardkas", "artifacts");
 }
 function getReceiptPath(txId, cwd) {
   validateTxId(txId);
@@ -49,7 +50,7 @@ async function listSimulatedReceipts(options) {
       }
     }
   }
-  return receipts.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  return receipts.sort((a, b) => deterministicCompare(b.createdAt, a.createdAt));
 }
 
 export {

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 import * as _hardkas_artifacts from '@hardkas/artifacts';
-import { HardkasArtifactBase, Snapshot as Snapshot$1, ARTIFACT_SCHEMAS, TxReceipt, TxPlan } from '@hardkas/artifacts';
+import { HardkasArtifactBase, Snapshot as Snapshot$1, TxPlan, ARTIFACT_SCHEMAS, TxReceipt } from '@hardkas/artifacts';
 import * as _hardkas_simulator from '@hardkas/simulator';
-import { ExecutionMode, NetworkId } from '@hardkas/core';
+import { ExecutionMode, NetworkId, RuntimeContext } from '@hardkas/core';
 import { KaspaRpcClient } from '@hardkas/kaspa-rpc';
 
 interface HardkasAccount {
     readonly name: string;
     readonly address: string;
+    readonly evmAddress: string;
     readonly balanceSompi: bigint;
 }
 declare function createDeterministicAccounts(input?: {
@@ -175,6 +176,15 @@ interface CreateInitialStateOptions {
 }
 declare function createInitialLocalnetState(options?: CreateInitialStateOptions): LocalnetState;
 declare function resolveAccountAddressFromState(state: LocalnetState, nameOrAddress: string): string;
+/**
+ * Mathematically reconstructs the deterministc localnet state at a specific past DAA score.
+ * Annoys UTXOs created after the target DAA and revives UTXOs spent after the target DAA.
+ *
+ * @param state The current localnet state
+ * @param targetDaa The block DAG score to revert to
+ * @returns A new immutable localnet state representing the exact state at the target DAA
+ */
+declare function reconstructStateAtDaa(state: LocalnetState, targetDaa: bigint | string): LocalnetState;
 
 declare function getDefaultLocalnetDir(cwd?: string): string;
 declare function getDefaultLocalnetStatePath(cwd?: string): string;
@@ -220,7 +230,7 @@ declare function createLocalnetSnapshot(state: LocalnetState, name?: string): Lo
 /**
  * Verifies the integrity of a snapshot.
  */
-declare function verifySnapshot(snapshot: any): SnapshotVerificationResult;
+declare function verifySnapshot(snapshot: Snapshot$1): SnapshotVerificationResult;
 /**
  * Restores a snapshot with atomic safety and verification.
  */
@@ -239,12 +249,11 @@ declare const DUST_LIMIT_SOMPI = 600n;
 /**
  * Applies a simulated payment to the localnet state with atomic safety and validation.
  */
-declare function applySimulatedPayment(state: LocalnetState, input: SimulatedPaymentInput): SimulationResult;
+declare function applySimulatedPayment(state: LocalnetState, input: SimulatedPaymentInput, ctx: RuntimeContext): SimulationResult;
 /**
  * Executes a pre-built transaction plan against the simulated state.
  */
-declare function applySimulatedPlan(state: LocalnetState, planArtifact: any, // TxPlanArtifact
-options?: {
+declare function applySimulatedPlan(state: LocalnetState, planArtifact: TxPlan, ctx: RuntimeContext, options?: {
     txId?: string;
 }): SimulationResult;
 
@@ -338,7 +347,7 @@ interface SimulatedReplaySummary {
  * 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;
+declare function verifyReplay(state: LocalnetState, originalPlan: TxPlan, originalReceipt: TxReceipt, ctx: RuntimeContext): ReplayVerificationReport;
 /**
  * Loads receipt and trace for a transaction and produces a summary.
  */
@@ -404,4 +413,4 @@ interface ForkOptions {
 }
 declare function forkFromNetwork(rpc: KaspaRpcClient, opts: ForkOptions): Promise<LocalnetState>;
 
-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 };
+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, reconstructStateAtDaa, resetLocalnetState, resolveAccountAddress, resolveAccountAddressFromState, resolveConflictsDeterministically, restoreLocalnetSnapshot, saveLocalnetState, saveSimulatedReceipt, saveSimulatedTrace, startSimulatedDevnet, verifyReplay, verifySnapshot };

package/dist/index.js

@@ -4,16 +4,28 @@ import {
   listSimulatedReceipts,
   loadSimulatedReceipt,
   saveSimulatedReceipt
-} from "./chunk-GVBX3TPM.js";
+} from "./chunk-M5T6T465.js";
 import {
   getDefaultTracesDir,
   getTracePath,
   listSimulatedTraces,
   loadSimulatedTrace,
   saveSimulatedTrace
-} from "./chunk-DPHHOGGK.js";
+} from "./chunk-6AICYLVR.js";
 
 // src/accounts.ts
+var DEFAULT_EVM_ADDRESSES = [
+  "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
+  // alice
+  "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
+  // bob
+  "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
+  // carol
+  "0x90F79bf6EB2c4f870365E785982E1f101E93b906",
+  // dave
+  "0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65"
+  // erin
+];
 function createDeterministicAccounts(input) {
   const count = input?.count ?? 5;
   const initialBalanceSompi = input?.initialBalanceSompi ?? 1000n * 100000000n;
@@ -23,6 +35,7 @@ function createDeterministicAccounts(input) {
     return {
       name,
       address: `kaspa:sim_${name}`,
+      evmAddress: DEFAULT_EVM_ADDRESSES[index] || `0x000000000000000000000000000000000000000${index}`,
       balanceSompi: initialBalanceSompi
     };
   });
@@ -162,6 +175,21 @@ function resolveAccountAddressFromState(state, nameOrAddress) {
   }
   return nameOrAddress;
 }
+function reconstructStateAtDaa(state, targetDaa) {
+  const target = typeof targetDaa === "string" ? BigInt(targetDaa) : targetDaa;
+  const reconstructedUtxos = state.utxos.filter((u) => BigInt(u.createdAtDaaScore || "0") <= target).map((u) => {
+    if (u.spent && u.spentAtDaaScore && BigInt(u.spentAtDaaScore) > target) {
+      const { spentAtDaaScore: _, ...rest } = u;
+      return { ...rest, spent: false };
+    }
+    return u;
+  });
+  return {
+    ...state,
+    daaScore: target.toString(),
+    utxos: reconstructedUtxos
+  };
+}
 
 // src/store.ts
 import fs from "fs/promises";
@@ -249,12 +277,13 @@ import {
   calculateContentHash,
   sortUtxosByOutpoint
 } from "@hardkas/artifacts";
+import { deterministicCompare } from "@hardkas/core";
 function calculateUtxoSetHash(utxos) {
   const sorted = sortUtxosByOutpoint(utxos);
   return calculateContentHash(sorted);
 }
 function calculateAccountsHash(accounts) {
-  const sorted = [...accounts].sort((a, b) => a.address.localeCompare(b.address));
+  const sorted = [...accounts || []].sort((a, b) => deterministicCompare(a.address, b.address));
   return calculateContentHash(sorted);
 }
 function calculateStateHash(state) {
@@ -270,7 +299,7 @@ function createLocalnetSnapshot(state, name) {
   const accountsHash = calculateAccountsHash(state.accounts);
   const utxoSetHash = calculateUtxoSetHash(state.utxos);
   const stateHash = calculateStateHash(state);
-  const snapshot = {
+  const snapshotDraft = {
     schema: "hardkas.snapshot",
     hardkasVersion: HARDKAS_VERSION2,
     version: ARTIFACT_VERSION,
@@ -281,9 +310,14 @@ function createLocalnetSnapshot(state, name) {
     utxoSetHash,
     stateHash,
     accounts: JSON.parse(JSON.stringify(state.accounts)),
-    utxos: JSON.parse(JSON.stringify(sortUtxosByOutpoint(state.utxos)))
+    utxos: JSON.parse(JSON.stringify(sortUtxosByOutpoint(state.utxos))),
+    networkId: state.networkId,
+    mode: state.mode
+  };
+  const snapshot = {
+    ...snapshotDraft,
+    contentHash: calculateContentHash(snapshotDraft)
   };
-  snapshot.contentHash = calculateContentHash(snapshot);
   return {
     ...state,
     snapshots: [...state.snapshots || [], snapshot]
@@ -343,7 +377,9 @@ import { buildPaymentPlan } from "@hardkas/tx-builder";
 import {
   createTxPlanArtifact,
   createSimulatedTxReceipt,
-  calculateContentHash as calculateContentHash2
+  calculateContentHash as calculateContentHash2,
+  HARDKAS_VERSION as HARDKAS_VERSION3,
+  ARTIFACT_VERSION as ARTIFACT_VERSION2
 } from "@hardkas/artifacts";
 function buildDagContextFromState(state) {
   if (state.dag) {
@@ -370,12 +406,18 @@ function generateDeterministicTxId(planArtifact, preStateHash, daaScore) {
   return `simtx_${hash}`;
 }
 var DUST_LIMIT_SOMPI = 600n;
-function applySimulatedPayment(state, input) {
+function applySimulatedPayment(state, input, ctx) {
   const errors = [];
   const preStateHash = calculateStateHash(state);
   try {
     const fromAddress = resolveAccountAddressFromState(state, input.from);
+    if (!fromAddress) {
+      throw new Error(`Sender account/address not found: ${input.from}`);
+    }
     const toAddress = resolveAccountAddressFromState(state, input.to);
+    if (!toAddress) {
+      throw new Error(`Recipient account/address not found: ${input.to}`);
+    }
     const amountSompi = input.amountSompi;
     const feeRateSompiPerMass = input.feeRateSompiPerMass ?? 1n;
     if (amountSompi <= 0n) {
@@ -421,7 +463,8 @@ function applySimulatedPayment(state, input) {
       from: { input: input.from, address: fromAddress },
       to: { input: input.to, address: toAddress },
       amountSompi,
-      plan
+      plan,
+      ctx
     });
     const nextDaaScore = (BigInt(state.daaScore) + 1n).toString();
     const txId = generateDeterministicTxId(planArtifact, preStateHash, nextDaaScore);
@@ -462,7 +505,7 @@ function applySimulatedPayment(state, input) {
       utxos: nextUtxos
     };
     const postStateHash = calculateStateHash(nextState);
-    const receipt = createSimulatedTxReceipt(planArtifact, txId, {
+    const receipt = createSimulatedTxReceipt(planArtifact, txId, ctx, {
       spentUtxoIds,
       createdUtxoIds,
       daaScore: nextDaaScore,
@@ -478,29 +521,37 @@ function applySimulatedPayment(state, input) {
       errors
     };
   } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
     const daaScore = state.daaScore || "0";
-    const txId = generateDeterministicFailedTxId(preStateHash, error.message, daaScore);
+    const txId = generateDeterministicFailedTxId(preStateHash, errorMessage, daaScore);
     const receipt = {
       schema: "hardkas.txReceipt",
+      hardkasVersion: HARDKAS_VERSION3,
+      version: ARTIFACT_VERSION2,
       status: "failed",
       mode: "simulated",
+      networkId: state.networkId,
       txId,
       createdAt: "1970-01-01T00:00:00.000Z",
-      errors: [error.message],
+      errors: [errorMessage],
       preStateHash,
       postStateHash: preStateHash,
-      dagContext: buildDagContextFromState(state)
+      dagContext: buildDagContextFromState(state),
+      from: { address: "" },
+      to: { address: "" },
+      amountSompi: "0",
+      feeSompi: "0"
     };
     return {
       ok: false,
       state,
       // No mutation
       receipt,
-      errors: [error.message]
+      errors: [errorMessage]
     };
   }
 }
-function applySimulatedPlan(state, planArtifact, options) {
+function applySimulatedPlan(state, planArtifact, ctx, options) {
   const errors = [];
   const preStateHash = calculateStateHash(state);
   try {
@@ -543,7 +594,7 @@ function applySimulatedPlan(state, planArtifact, options) {
     }
     const nextState = { ...state, daaScore: nextDaaScore, utxos: nextUtxos };
     const postStateHash = calculateStateHash(nextState);
-    const receipt = createSimulatedTxReceipt(planArtifact, txId, {
+    const receipt = createSimulatedTxReceipt(planArtifact, txId, ctx, {
       spentUtxoIds,
       createdUtxoIds,
       daaScore: nextDaaScore,
@@ -553,20 +604,28 @@ function applySimulatedPlan(state, planArtifact, options) {
     });
     return { ok: true, state: nextState, receipt, planArtifact, errors };
   } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
     const daaScore = state.daaScore || "0";
-    const txId = generateDeterministicFailedTxId(preStateHash, error.message, daaScore);
+    const txId = generateDeterministicFailedTxId(preStateHash, errorMessage, daaScore);
     const receipt = {
       schema: "hardkas.txReceipt",
+      hardkasVersion: HARDKAS_VERSION3,
+      version: ARTIFACT_VERSION2,
       status: "failed",
       mode: "simulated",
+      networkId: state.networkId,
       txId,
       createdAt: "1970-01-01T00:00:00.000Z",
-      errors: [error.message],
+      errors: [errorMessage],
       preStateHash,
       postStateHash: preStateHash,
-      dagContext: buildDagContextFromState(state)
+      dagContext: buildDagContextFromState(state),
+      from: { address: "" },
+      to: { address: "" },
+      amountSompi: "0",
+      feeSompi: "0"
     };
-    return { ok: false, state, receipt, errors: [error.message] };
+    return { ok: false, state, receipt, errors: [errorMessage] };
   }
 }
 
@@ -576,7 +635,7 @@ import {
   diffArtifacts
 } from "@hardkas/artifacts";
 import { coreEvents } from "@hardkas/core";
-function verifyReplay(state, originalPlan, originalReceipt) {
+function verifyReplay(state, originalPlan, originalReceipt, ctx) {
   const errors = [];
   const reportDivergences = [];
   const currentPlanHash = calculateContentHash3(originalPlan);
@@ -607,7 +666,7 @@ function verifyReplay(state, originalPlan, originalReceipt) {
       severity: "warning"
     });
   }
-  const result = applySimulatedPlan(state, originalPlan, { txId: originalReceipt.txId });
+  const result = applySimulatedPlan(state, originalPlan, ctx, { txId: originalReceipt.txId });
   const replayReceipt = result.receipt;
   const diff = diffArtifacts(originalReceipt, replayReceipt);
   if (!diff.identical) {
@@ -654,8 +713,8 @@ function verifyReplay(state, originalPlan, originalReceipt) {
   };
 }
 async function getSimulatedReplaySummary(txId, options = {}) {
-  const { loadSimulatedReceipt: loadSimulatedReceipt2 } = await import("./receipts-JSTNZMDD.js");
-  const { loadSimulatedTrace: loadSimulatedTrace2 } = await import("./traces-HDVV77MQ.js");
+  const { loadSimulatedReceipt: loadSimulatedReceipt2 } = await import("./receipts-7RMJMXXG.js");
+  const { loadSimulatedTrace: loadSimulatedTrace2 } = await import("./traces-ZUBWSXYB.js");
   const receipt = await loadSimulatedReceipt2(txId, options);
   const trace = await loadSimulatedTrace2(txId, options);
   if (!receipt || !trace) {
@@ -683,6 +742,7 @@ import {
   findSelectedParent,
   GENESIS_HASH as SIM_GENESIS_HASH
 } from "@hardkas/simulator";
+import { deterministicCompare as deterministicCompare2 } from "@hardkas/core";
 var dagIdMaps = /* @__PURE__ */ new WeakMap();
 var dagReverseIdMaps = /* @__PURE__ */ new WeakMap();
 function getIdMap(dag) {
@@ -810,7 +870,7 @@ function moveSink(dag, newSinkId, txProvider) {
     const daaA = BigInt(a.daaScore);
     const daaB = BigInt(b.daaScore);
     if (daaA !== daaB) return daaA < daaB ? -1 : 1;
-    return a.id.localeCompare(b.id);
+    return deterministicCompare2(a.id, b.id);
   });
   const acceptedTxIds = [];
   const displacedTxIds = [];
@@ -918,7 +978,7 @@ function resolveConflictsDeterministically(txs, dag) {
     const blockA = dag.blocks[a.blockId];
     const blockB = dag.blocks[b.blockId];
     if (!blockA || !blockB) {
-      if (!blockA && !blockB) return a.txId.localeCompare(b.txId);
+      if (!blockA && !blockB) return deterministicCompare2(a.txId, b.txId);
       return !blockA ? 1 : -1;
     }
     const inPathA = dag.selectedPathToSink.includes(a.blockId);
@@ -933,8 +993,8 @@ function resolveConflictsDeterministically(txs, dag) {
     const daaA = BigInt(blockA.daaScore);
     const daaB = BigInt(blockB.daaScore);
     if (daaA !== daaB) return daaA < daaB ? -1 : 1;
-    if (a.blockId !== b.blockId) return a.blockId.localeCompare(b.blockId);
-    return a.txId.localeCompare(b.txId);
+    if (a.blockId !== b.blockId) return deterministicCompare2(a.blockId, b.blockId);
+    return deterministicCompare2(a.txId, b.txId);
   });
   const accepted = [];
   const displaced = [];
@@ -1080,6 +1140,7 @@ export {
   loadSimulatedReceipt,
   loadSimulatedTrace,
   moveSink,
+  reconstructStateAtDaa,
   resetLocalnetState,
   resolveAccountAddress,
   resolveAccountAddressFromState,

package/dist/{receipts-JSTNZMDD.js → receipts-7RMJMXXG.js}

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/localnet",
-  "version": "0.5.4-alpha",
+  "version": "0.6.0-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -8,12 +8,12 @@
     ".": "./dist/index.js"
   },
   "dependencies": {
-    "@hardkas/artifacts": "0.5.4-alpha",
-    "@hardkas/core": "0.5.4-alpha",
-    "@hardkas/simulator": "0.5.4-alpha",
-    "@hardkas/query": "0.5.4-alpha",
-    "@hardkas/tx-builder": "0.5.4-alpha",
-    "@hardkas/kaspa-rpc": "0.5.4-alpha"
+    "@hardkas/artifacts": "0.6.0-alpha",
+    "@hardkas/core": "0.6.0-alpha",
+    "@hardkas/query": "0.6.0-alpha",
+    "@hardkas/simulator": "0.6.0-alpha",
+    "@hardkas/kaspa-rpc": "0.6.0-alpha",
+    "@hardkas/tx-builder": "0.6.0-alpha"
   },
   "devDependencies": {
     "fast-check": "^4.8.0",