@hardkas/simulator 0.2.2-alpha → 0.3.0-alpha

package/dist/index.d.ts

@@ -24,6 +24,354 @@ interface SimulationResult {
 declare class TxSimulator {
     simulate(phases: readonly TxLifecyclePhase[], run?: (phase: TxLifecyclePhase) => Promise<void>): Promise<SimulationResult>;
 }
+/**
+ * Creates a non-deterministic trace ID for debug purposes.
+ * Intentionally uses Date.now() + Math.random().
+ * Trace IDs are debug metadata only — they do NOT enter
+ * canonical hashing or artifact identity.
+ */
 declare function createTraceId(prefix?: string): string;
 
-export { type SimulationResult, type TxLifecyclePhase, TxSimulator, type TxTraceEvent, createTraceId };
+/**
+ * Block hash as 64-char hex string.
+ * In simulation, derived via SHA-256 of block parameters.
+ * NOT a real Kaspa block hash — simulation IDs only.
+ */
+type BlockHash = string;
+/**
+ * Accumulated PoW work as bigint.
+ * rusty-kaspa uses U256; we use bigint (arbitrary precision in JS).
+ */
+type BlueWorkType = bigint;
+declare const GENESIS_HASH: BlockHash;
+/**
+ * Full GHOSTDAG data for a block.
+ *
+ * Source: consensus/src/model/stores/ghostdag.rs lines 22-30
+ * [UNVALIDATED]: field semantics are structurally plausible
+ * but not fixture-validated against rusty-kaspa.
+ */
+interface GhostdagData {
+    /** Count of blue blocks in the causal past, including this block's mergeset blues. */
+    readonly blueScore: number;
+    /** Cumulative PoW work of all blue blocks in causal past. */
+    readonly blueWork: BlueWorkType;
+    /** Parent with highest (blueWork, hash). */
+    readonly selectedParent: BlockHash;
+    /** Blue blocks in mergeset, ascending (blueWork, hash). First = selected parent. */
+    readonly mergesetBlues: readonly BlockHash[];
+    /** Red blocks in mergeset, ascending (blueWork, hash). */
+    readonly mergesetReds: readonly BlockHash[];
+    /** Anticone sizes for each blue in mergesetBlues. */
+    readonly bluesAnticoneSizes: readonly number[];
+}
+/**
+ * Compact projection for chain-walking.
+ * Source: consensus/src/model/stores/ghostdag.rs lines 32-37
+ */
+interface CompactGhostdagData {
+    readonly blueScore: number;
+    readonly blueWork: BlueWorkType;
+    readonly selectedParent: BlockHash;
+}
+/**
+ * Simulated block header (simulation layer only — not Kaspa wire format).
+ */
+interface SimBlockHeader {
+    readonly hash: BlockHash;
+    readonly parents: readonly BlockHash[];
+    readonly timestampUs: number;
+    readonly minerId: number;
+    /** Compact difficulty target. Work = BigInt(2**128) / BigInt(bits + 1). */
+    readonly bits: number;
+    readonly nonce: number;
+}
+/**
+ * A block as seen by the simulation (header + optional GHOSTDAG result).
+ */
+interface SimBlock {
+    readonly header: SimBlockHeader;
+    readonly ghostdag?: GhostdagData;
+}
+declare function blockHash(block: SimBlock): BlockHash;
+declare function blockParents(block: SimBlock): readonly BlockHash[];
+declare function blockBlueWork(block: SimBlock): BlueWorkType;
+declare function blockBlueScore(block: SimBlock): number;
+declare function headerWork(header: SimBlockHeader): BlueWorkType;
+declare function compactFromFull(g: GhostdagData): CompactGhostdagData;
+
+/**
+ * Pairs a block hash with its blueWork for ordering.
+ * Mirrors SortableBlock in rusty-kaspa ordering.rs lines 14-24.
+ */
+interface SortableBlock {
+    readonly hash: BlockHash;
+    readonly blueWork: BlueWorkType;
+}
+/**
+ * Compare two SortableBlocks: ascending by (blueWork, hash).
+ * Returns negative if a < b, positive if a > b, 0 if equal.
+ *
+ * Source: ordering.rs lines 38-42
+ */
+declare function compareSortableBlocks(a: SortableBlock, b: SortableBlock): number;
+/**
+ * Sort blocks in ascending (blueWork, hash) order.
+ * Source: ordering.rs lines 44-51 sort_blocks()
+ *
+ * Returns a NEW sorted array (does not mutate input).
+ */
+declare function sortBlocks(blocks: readonly SortableBlock[]): SortableBlock[];
+/**
+ * Find the selected parent: argmax over parents of (blueWork, hash).
+ * Source: protocol.rs lines 99-106 find_selected_parent()
+ *
+ *   selected_parent = parents
+ *     .map(p => SortableBlock { hash: p.hash, blueWork: p.blueWork })
+ *     .max()
+ *
+ * Returns undefined only if parents is empty (invalid for any non-genesis block).
+ */
+declare function findSelectedParent(parents: ReadonlyArray<{
+    hash: BlockHash;
+    blueWork: BlueWorkType;
+}>): BlockHash | undefined;
+
+/**
+ * In-memory GHOSTDAG data store.
+ * Mirrors MemoryGhostdagStore in rusty-kaspa.
+ */
+declare class GhostdagStore {
+    private readonly full;
+    private readonly compact;
+    private readonly parents;
+    /**
+     * Insert full + compact entries atomically.
+     * Source: ghostdag.rs insert_batch() / update_batch() write both.
+     */
+    insert(hash: BlockHash, data: GhostdagData, parents?: BlockHash[]): void;
+    getData(hash: BlockHash): GhostdagData | undefined;
+    getBlueScore(hash: BlockHash): number | undefined;
+    getBlueWork(hash: BlockHash): BlueWorkType | undefined;
+    getSelectedParent(hash: BlockHash): BlockHash | undefined;
+    has(hash: BlockHash): boolean;
+    getParents(hash: BlockHash): BlockHash[] | undefined;
+    get size(): number;
+}
+/**
+ * Genesis GHOSTDAG data.
+ * [UNVALIDATED]: genesis blue_score=0, blue_work=0, selected_parent=genesis.
+ */
+declare function genesisGhostdagData(genesisHash?: BlockHash): GhostdagData;
+
+/**
+ * Compute the full past set of `start` via BFS.
+ * [RESEARCH_EXPERIMENTAL]: O(|past(start)|) per call.
+ * rusty-kaspa uses O(1) reachability interval tree.
+ */
+declare function pastSet(start: BlockHash, allBlocks: ReadonlyMap<BlockHash, SimBlock>): Set<BlockHash>;
+/**
+ * Check if `ancestorCandidate` is in the causal past of `descendant`.
+ * [RESEARCH_EXPERIMENTAL]: BFS approximation of ReachabilityService.
+ */
+declare function isDagAncestorOf(ancestorCandidate: BlockHash, descendant: BlockHash, allBlocks: ReadonlyMap<BlockHash, SimBlock>): boolean;
+/**
+ * Compute the unordered mergeset of `block`, excluding its `selectedParent`.
+ *
+ * Mergeset = blocks in past(block) that are NOT in past(selectedParent).
+ * Genesis is never in the mergeset.
+ *
+ * [RESEARCH_EXPERIMENTAL]: BFS-based. Source: mergeset.rs lines 9-40
+ */
+declare function unorderedMergesetWithoutSelectedParent(block: SimBlock, selectedParent: BlockHash, allBlocks: ReadonlyMap<BlockHash, SimBlock>): BlockHash[];
+/**
+ * Compute the mergeset sorted in ascending (blueWork, hash) order.
+ * Source: mergeset.rs lines 43-45 ordered_mergeset_without_selected_parent()
+ *
+ * [RESEARCH_EXPERIMENTAL]: sorting semantics correct, blue_work values approximate.
+ */
+declare function orderedMergesetWithoutSelectedParent(block: SimBlock, selectedParent: BlockHash, allBlocks: ReadonlyMap<BlockHash, SimBlock>, gdStore: GhostdagStore): SortableBlock[];
+
+/** The GHOSTDAG K parameter. Post-Crescendo mainnet (10 BPS): K = 18. */
+declare const DEFAULT_K = 18;
+type CandidateColor = "blue" | "red";
+/**
+ * Approximate GHOSTDAG engine.
+ *
+ * Computes GhostdagData for each block given its DAG context.
+ * Uses BFS-based reachability and pairwise anticone checks.
+ *
+ * [RESEARCH_EXPERIMENTAL]: suitable for simulation, NOT for consensus equivalence.
+ */
+declare class ApproxGhostdagEngine {
+    readonly k: number;
+    readonly genesisHash: BlockHash;
+    constructor(k?: number, genesisHash?: BlockHash);
+    /**
+     * Compute GhostdagData for `block`.
+     *
+     * Intentionally non-deterministic for TEMP_INDEXING_HASH as it uses Date.now()
+     * for dummy block headers.
+     *
+     * Source: protocol.rs lines 126-166 ghostdag()
+     *
+     * Steps:
+     *   1. findSelectedParent()
+     *   2. orderedMergeset()
+     *   3. color each candidate (check_blue_candidate)
+     *   4. blueScore = sp.blueScore + |mergesetBlues|
+     *   5. blueWork = sp.blueWork + Σ work(blues)
+     *
+     * All steps are [RESEARCH_EXPERIMENTAL].
+     */
+    ghostdag(parents: BlockHash[], gdStore: GhostdagStore): GhostdagData;
+    /**
+     * Compute GhostdagData for `block`.
+     */
+    computeGhostdag(block: SimBlock, allBlocks: ReadonlyMap<BlockHash, SimBlock>, gdStore: GhostdagStore): GhostdagData;
+}
+
+interface DagMetrics {
+    /** Total blocks in the DAG (excluding genesis). */
+    totalBlocks: number;
+    /** Number of blue blocks. */
+    blueBlocks: number;
+    /** Number of red blocks. */
+    redBlocks: number;
+    /** red / (blue + red). */
+    redRatio: number;
+    /** Average number of parents per block. */
+    meanParents: number;
+    /** Number of tip blocks (no children). */
+    dagWidth: number;
+    /** Highest blueScore in the DAG. */
+    maxBlueScore: number;
+    /** Highest blueWork in the DAG. */
+    maxBlueWork: bigint;
+    /** Length of the selected parent chain from sink to genesis. */
+    selectedChainLength: number;
+    /** Block IDs on the selected chain. */
+    selectedChain: string[];
+}
+declare function computeDagMetrics(allBlocks: Map<BlockHash, SimBlock>, gdStore: GhostdagStore, genesisHash: BlockHash): DagMetrics;
+
+interface ScenarioConfig {
+    /** Scenario name. */
+    name: string;
+    /** GHOSTDAG K parameter. */
+    k?: number;
+    /** Number of blocks to generate (excluding genesis). */
+    blockCount: number;
+    /** Difficulty bits for all blocks. */
+    bits?: number;
+}
+interface ScenarioResult {
+    name: string;
+    config: ScenarioConfig;
+    metrics: DagMetrics;
+    /** Time to compute in milliseconds. */
+    computeTimeMs: number;
+}
+declare function runLinearChain(config: ScenarioConfig): ScenarioResult;
+declare function runWideDag(config: ScenarioConfig): ScenarioResult;
+declare function runForkResolution(config: ScenarioConfig & {
+    forkPoint: number;
+}): ScenarioResult;
+declare function runDiamondDag(config: ScenarioConfig): ScenarioResult;
+declare function runAllScenarios(config: ScenarioConfig): ScenarioResult[];
+
+declare function formatScenarioReport(results: ScenarioResult[]): string;
+
+interface MassBreakdown {
+    /** Total estimated mass. */
+    totalMass: bigint;
+    /** Mass contributed by inputs. */
+    inputMass: bigint;
+    /** Mass contributed by outputs. */
+    outputMass: bigint;
+    /** Mass contributed by payload/metadata. */
+    payloadMass: bigint;
+    /** Estimated fee in sompi at the given fee rate. */
+    estimatedFeeSompi: bigint;
+    /** Fee rate used (sompi per mass unit). */
+    feeRate: bigint;
+    /** Number of inputs. */
+    inputCount: number;
+    /** Number of outputs. */
+    outputCount: number;
+    /** Payload size in bytes. */
+    payloadBytes: number;
+}
+interface MassComparison {
+    /** Current profile. */
+    current: MassBreakdown;
+    /** Previous profile to compare against. */
+    previous: MassBreakdown;
+    /** Absolute difference in total mass. */
+    massDelta: bigint;
+    /** Absolute difference in fee. */
+    feeDelta: bigint;
+    /** Percentage change in mass (positive = increase). */
+    massChangePercent: number;
+    /** Percentage change in fee. */
+    feeChangePercent: number;
+    /** True if mass increased (potential regression). */
+    isRegression: boolean;
+    /** Regression severity: "none" | "minor" (<10%) | "major" (>=10%) */
+    severity: "none" | "minor" | "major";
+}
+/**
+ * Profiles transaction mass based on counts and sizes.
+ */
+declare function profileMass(opts: {
+    inputCount: number;
+    outputCount: number;
+    payloadBytes?: number;
+    feeRate?: bigint;
+}): MassBreakdown;
+/**
+ * Compares two mass profiles and detects regressions.
+ */
+declare function compareMassProfiles(current: MassBreakdown, previous: MassBreakdown): MassComparison;
+/**
+ * Formats a mass breakdown into a readable report.
+ */
+declare function formatMassProfile(breakdown: MassBreakdown): string;
+/**
+ * Formats a comparison report.
+ */
+declare function formatMassComparison(comparison: MassComparison): string;
+
+interface MassSnapshot {
+    /** Snapshot label (e.g., "basic-transfer", "multi-output"). */
+    label: string;
+    /** When the snapshot was taken. */
+    timestamp: string;
+    /** The mass breakdown. */
+    breakdown: MassBreakdown;
+}
+interface MassSnapshotStore {
+    snapshots: MassSnapshot[];
+}
+/**
+ * Saves a mass breakdown to a persistent snapshot.
+ */
+declare function saveMassSnapshot(dir: string, label: string, breakdown: MassBreakdown): void;
+/**
+ * Loads a saved mass snapshot.
+ */
+declare function loadMassSnapshot(dir: string, label: string): MassSnapshot | undefined;
+/**
+ * Profiles current mass, compares with previous if exists, and saves new snapshot.
+ */
+declare function profileAndCompare(opts: {
+    inputCount: number;
+    outputCount: number;
+    payloadBytes?: number;
+    feeRate?: bigint;
+}, snapshotDir: string, label: string): {
+    breakdown: MassBreakdown;
+    comparison?: MassComparison;
+};
+
+export { ApproxGhostdagEngine, type BlockHash, type BlueWorkType, type CandidateColor, type CompactGhostdagData, DEFAULT_K, type DagMetrics, GENESIS_HASH, type GhostdagData, GhostdagStore, type MassBreakdown, type MassComparison, type MassSnapshot, type MassSnapshotStore, type ScenarioConfig, type ScenarioResult, type SimBlock, type SimBlockHeader, type SimulationResult, type SortableBlock, type TxLifecyclePhase, TxSimulator, type TxTraceEvent, blockBlueScore, blockBlueWork, blockHash, blockParents, compactFromFull, compareMassProfiles, compareSortableBlocks, computeDagMetrics, createTraceId, findSelectedParent, formatMassComparison, formatMassProfile, formatScenarioReport, genesisGhostdagData, headerWork, isDagAncestorOf, loadMassSnapshot, orderedMergesetWithoutSelectedParent, pastSet, profileAndCompare, profileMass, runAllScenarios, runDiamondDag, runForkResolution, runLinearChain, runWideDag, saveMassSnapshot, sortBlocks, unorderedMergesetWithoutSelectedParent };

package/dist/index.js

@@ -1,17 +1,11 @@
-// src/index.ts
+// src/tx-simulator.ts
 var TxSimulator = class {
   async simulate(phases, run) {
     const events = [];
     for (const phase of phases) {
-      events.push({
-        type: "phase.started",
-        phase,
-        timestamp: Date.now()
-      });
+      events.push({ type: "phase.started", phase, timestamp: Date.now() });
       try {
-        if (run) {
-          await run(phase);
-        }
+        if (run) await run(phase);
       } catch (error) {
         events.push({
           type: "tx.failed",
@@ -19,27 +13,776 @@ var TxSimulator = class {
           reason: error instanceof Error ? error.message : "Unknown error",
           timestamp: Date.now()
         });
-        return {
-          ok: false,
-          events
-        };
+        return { ok: false, events };
       }
-      events.push({
-        type: "phase.completed",
-        phase,
-        timestamp: Date.now()
-      });
+      events.push({ type: "phase.completed", phase, timestamp: Date.now() });
     }
-    return {
-      ok: true,
-      events
-    };
+    return { ok: true, events };
   }
 };
 function createTraceId(prefix = "trace") {
   return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 }
+
+// src/ghostdag-types.ts
+var GENESIS_HASH = "0".repeat(64);
+function blockHash(block) {
+  return block.header.hash;
+}
+function blockParents(block) {
+  return block.header.parents;
+}
+function blockBlueWork(block) {
+  return block.ghostdag?.blueWork ?? 0n;
+}
+function blockBlueScore(block) {
+  return block.ghostdag?.blueScore ?? 0;
+}
+var MAX_WORK = 2n ** 128n;
+function headerWork(header) {
+  return MAX_WORK / (BigInt(header.bits) + 1n);
+}
+function compactFromFull(g) {
+  return {
+    blueScore: g.blueScore,
+    blueWork: g.blueWork,
+    selectedParent: g.selectedParent
+  };
+}
+
+// src/ordering.ts
+function compareSortableBlocks(a, b) {
+  if (a.blueWork < b.blueWork) return -1;
+  if (a.blueWork > b.blueWork) return 1;
+  if (a.hash < b.hash) return -1;
+  if (a.hash > b.hash) return 1;
+  return 0;
+}
+function sortBlocks(blocks) {
+  return [...blocks].sort(compareSortableBlocks);
+}
+function findSelectedParent(parents) {
+  if (parents.length === 0) return void 0;
+  let best = { hash: parents[0].hash, blueWork: parents[0].blueWork };
+  for (let i = 1; i < parents.length; i++) {
+    const candidate = { hash: parents[i].hash, blueWork: parents[i].blueWork };
+    if (compareSortableBlocks(candidate, best) > 0) {
+      best = candidate;
+    }
+  }
+  return best.hash;
+}
+
+// src/ghostdag-store.ts
+var GhostdagStore = class {
+  full = /* @__PURE__ */ new Map();
+  compact = /* @__PURE__ */ new Map();
+  parents = /* @__PURE__ */ new Map();
+  /**
+   * Insert full + compact entries atomically.
+   * Source: ghostdag.rs insert_batch() / update_batch() write both.
+   */
+  insert(hash, data, parents = []) {
+    this.compact.set(hash, compactFromFull(data));
+    this.full.set(hash, data);
+    this.parents.set(hash, parents);
+  }
+  getData(hash) {
+    return this.full.get(hash);
+  }
+  getBlueScore(hash) {
+    return this.compact.get(hash)?.blueScore;
+  }
+  getBlueWork(hash) {
+    return this.compact.get(hash)?.blueWork;
+  }
+  getSelectedParent(hash) {
+    return this.compact.get(hash)?.selectedParent;
+  }
+  has(hash) {
+    return this.compact.has(hash);
+  }
+  getParents(hash) {
+    return this.parents.get(hash);
+  }
+  get size() {
+    return this.full.size;
+  }
+};
+function genesisGhostdagData(genesisHash = GENESIS_HASH) {
+  return {
+    blueScore: 0,
+    blueWork: 0n,
+    selectedParent: genesisHash,
+    mergesetBlues: [genesisHash],
+    mergesetReds: [],
+    bluesAnticoneSizes: [0]
+  };
+}
+
+// src/reachability.ts
+function pastSet(start, allBlocks) {
+  const past = /* @__PURE__ */ new Set();
+  const queue = [start];
+  past.add(start);
+  while (queue.length > 0) {
+    const h = queue.shift();
+    const block = allBlocks.get(h);
+    if (!block) continue;
+    for (const p of block.header.parents) {
+      if (!past.has(p)) {
+        past.add(p);
+        queue.push(p);
+      }
+    }
+  }
+  return past;
+}
+function isDagAncestorOf(ancestorCandidate, descendant, allBlocks) {
+  if (ancestorCandidate === GENESIS_HASH) return true;
+  return pastSet(descendant, allBlocks).has(ancestorCandidate);
+}
+function unorderedMergesetWithoutSelectedParent(block, selectedParent, allBlocks) {
+  const spPast = pastSet(selectedParent, allBlocks);
+  const mergeset = /* @__PURE__ */ new Set();
+  const queue = [];
+  const visited = /* @__PURE__ */ new Set();
+  for (const parent of block.header.parents) {
+    if (parent === selectedParent) continue;
+    if (spPast.has(parent)) continue;
+    if (!visited.has(parent)) {
+      visited.add(parent);
+      mergeset.add(parent);
+      queue.push(parent);
+    }
+  }
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const currentBlock = allBlocks.get(current);
+    if (!currentBlock) continue;
+    for (const parent of currentBlock.header.parents) {
+      if (parent === GENESIS_HASH) continue;
+      if (visited.has(parent)) continue;
+      visited.add(parent);
+      if (spPast.has(parent)) continue;
+      mergeset.add(parent);
+      queue.push(parent);
+    }
+  }
+  return Array.from(mergeset);
+}
+function orderedMergesetWithoutSelectedParent(block, selectedParent, allBlocks, gdStore) {
+  const unordered = unorderedMergesetWithoutSelectedParent(
+    block,
+    selectedParent,
+    allBlocks
+  );
+  const sortable = unordered.map((hash) => ({
+    hash,
+    blueWork: gdStore.getBlueWork(hash) ?? 0n
+  }));
+  return sortBlocks(sortable);
+}
+
+// src/ghostdag-engine.ts
+var DEFAULT_K = 18;
+var ApproxGhostdagEngine = class {
+  k;
+  genesisHash;
+  constructor(k = DEFAULT_K, genesisHash = GENESIS_HASH) {
+    this.k = k;
+    this.genesisHash = genesisHash;
+  }
+  /**
+   * Compute GhostdagData for `block`.
+   * 
+   * Intentionally non-deterministic for TEMP_INDEXING_HASH as it uses Date.now() 
+   * for dummy block headers.
+   *
+   * Source: protocol.rs lines 126-166 ghostdag()
+   *
+   * Steps:
+   *   1. findSelectedParent()
+   *   2. orderedMergeset()
+   *   3. color each candidate (check_blue_candidate)
+   *   4. blueScore = sp.blueScore + |mergesetBlues|
+   *   5. blueWork = sp.blueWork + Σ work(blues)
+   *
+   * All steps are [RESEARCH_EXPERIMENTAL].
+   */
+  ghostdag(parents, gdStore) {
+    const block = {
+      header: {
+        hash: "TEMP_INDEXING_HASH",
+        // Not used for internal GHOSTDAG logic
+        parents,
+        timestampUs: Date.now() * 1e3,
+        minerId: 0,
+        bits: 1,
+        // Minimum work contribution
+        nonce: 0
+      }
+    };
+    const allBlocksProxy = {
+      get: (hash) => {
+        const data = gdStore.getData(hash);
+        if (data) {
+          const parents2 = gdStore.getParents(hash) || [];
+          return {
+            header: {
+              hash,
+              parents: parents2,
+              timestampUs: 0,
+              minerId: 0,
+              bits: 1e3,
+              nonce: 0
+            },
+            ghostdag: data
+          };
+        }
+        return void 0;
+      },
+      has: (hash) => gdStore.has(hash)
+    };
+    return this.computeGhostdag(block, allBlocksProxy, gdStore);
+  }
+  /**
+   * Compute GhostdagData for `block`.
+   */
+  computeGhostdag(block, allBlocks, gdStore) {
+    const hash = block.header.hash;
+    if (hash === this.genesisHash) {
+      return genesisGhostdagData(this.genesisHash);
+    }
+    if (block.header.parents.length === 0) {
+      throw new Error(
+        `Non-genesis block ${hash.slice(0, 8)} has no parents \u2014 undefined in GHOSTDAG`
+      );
+    }
+    const parentBlueWorks = block.header.parents.map((p) => ({
+      hash: p,
+      blueWork: gdStore.getBlueWork(p) ?? 0n
+    }));
+    const selectedParent = findSelectedParent(parentBlueWorks);
+    if (selectedParent === void 0) {
+      throw new Error(
+        `findSelectedParent returned undefined for block ${hash.slice(0, 8)}`
+      );
+    }
+    const orderedMerge = orderedMergesetWithoutSelectedParent(
+      block,
+      selectedParent,
+      allBlocks,
+      gdStore
+    );
+    const mergesetBlues = [];
+    const bluesAnticoneSizes = [];
+    const mergesetReds = [];
+    const coloringContext = [selectedParent];
+    const contextAnticoneSizes = [0];
+    for (const candidate of orderedMerge) {
+      if (mergesetBlues.length > this.k) {
+        mergesetReds.push(candidate.hash);
+        continue;
+      }
+      const color = checkBlueCandidateApprox(
+        candidate.hash,
+        this.k,
+        coloringContext,
+        contextAnticoneSizes,
+        allBlocks
+      );
+      if (color === "blue") {
+        mergesetBlues.push(candidate.hash);
+        coloringContext.push(candidate.hash);
+        contextAnticoneSizes.push(0);
+      } else {
+        mergesetReds.push(candidate.hash);
+      }
+    }
+    const spBlueScore = gdStore.getBlueScore(selectedParent) ?? 0;
+    const blueScore = spBlueScore + 1 + mergesetBlues.length;
+    const spBlueWork = gdStore.getBlueWork(selectedParent) ?? 0n;
+    let addedBlueWork = headerWork(allBlocks.get(selectedParent).header);
+    for (const h of mergesetBlues) {
+      const b = allBlocks.get(h);
+      if (b) addedBlueWork += headerWork(b.header);
+    }
+    const blueWork = spBlueWork + addedBlueWork;
+    return {
+      blueScore,
+      blueWork,
+      selectedParent,
+      mergesetBlues: [selectedParent, ...mergesetBlues],
+      mergesetReds,
+      bluesAnticoneSizes: [0, ...bluesAnticoneSizes]
+    };
+  }
+};
+function checkBlueCandidateApprox(candidate, k, currentBlues, bluesAnticoneSizes, allBlocks) {
+  let candidateAnticoneSize = 0;
+  const toIncrement = [];
+  for (let i = 0; i < currentBlues.length; i++) {
+    const blue = currentBlues[i];
+    const blueInPast = isDagAncestorOf(blue, candidate, allBlocks);
+    const candidateInPast = isDagAncestorOf(candidate, blue, allBlocks);
+    if (blueInPast || candidateInPast) {
+      continue;
+    }
+    candidateAnticoneSize++;
+    if (candidateAnticoneSize > k) {
+      return "red";
+    }
+    const existing = bluesAnticoneSizes[i] ?? 0;
+    if (existing >= k) {
+      return "red";
+    }
+    toIncrement.push(i);
+  }
+  for (const idx of toIncrement) {
+    bluesAnticoneSizes[idx]++;
+  }
+  bluesAnticoneSizes.push(candidateAnticoneSize);
+  return "blue";
+}
+
+// src/metrics.ts
+function computeDagMetrics(allBlocks, gdStore, genesisHash) {
+  const totalBlocks = allBlocks.size - 1;
+  const parentIds = /* @__PURE__ */ new Set();
+  let totalParentLinks = 0;
+  for (const block of allBlocks.values()) {
+    for (const p of block.header.parents) {
+      parentIds.add(p);
+    }
+    if (!block.header.parents.includes(genesisHash) && block.header.hash !== genesisHash) {
+    }
+    totalParentLinks += block.header.parents.length;
+  }
+  const tips = Array.from(allBlocks.keys()).filter((id) => !parentIds.has(id));
+  const dagWidth = tips.length;
+  const meanParents = totalBlocks > 0 ? totalParentLinks / (totalBlocks + 1) : 0;
+  const tipData = tips.map((id) => ({
+    hash: id,
+    blueWork: gdStore.getBlueWork(id) ?? 0n
+  }));
+  const sink = findSelectedParent(tipData) || genesisHash;
+  const selectedChain = [];
+  let currentId = sink;
+  while (currentId) {
+    selectedChain.unshift(currentId);
+    if (currentId === genesisHash) break;
+    currentId = gdStore.getSelectedParent(currentId);
+  }
+  let blueBlocks = 0;
+  let redBlocks = 0;
+  let maxBlueScore = 0;
+  let maxBlueWork = 0n;
+  const sinkData = gdStore.getData(sink);
+  if (sinkData) {
+    blueBlocks = sinkData.blueScore;
+  }
+  for (const id of allBlocks.keys()) {
+    if (id === genesisHash) continue;
+    const score = gdStore.getBlueScore(id) || 0;
+    const work = gdStore.getBlueWork(id) || 0n;
+    if (score > maxBlueScore) maxBlueScore = score;
+    if (work > maxBlueWork) maxBlueWork = work;
+  }
+  if (sinkData) {
+    const past = identifyReachableBlocks(allBlocks, sink);
+    const totalInPast = past.size - 1;
+    blueBlocks = sinkData.blueScore + 1;
+    redBlocks = Math.max(0, totalInPast - blueBlocks);
+  }
+  return {
+    totalBlocks,
+    blueBlocks,
+    redBlocks,
+    redRatio: blueBlocks + redBlocks > 0 ? redBlocks / (blueBlocks + redBlocks) : 0,
+    meanParents,
+    dagWidth,
+    maxBlueScore,
+    maxBlueWork,
+    selectedChainLength: selectedChain.length,
+    selectedChain
+  };
+}
+function identifyReachableBlocks(allBlocks, sinkId) {
+  const reachable = /* @__PURE__ */ new Set();
+  const stack = [sinkId];
+  while (stack.length > 0) {
+    const id = stack.pop();
+    if (reachable.has(id)) continue;
+    reachable.add(id);
+    const block = allBlocks.get(id);
+    if (block) {
+      for (const p of block.header.parents) {
+        stack.push(p);
+      }
+    }
+  }
+  return reachable;
+}
+
+// src/scenarios.ts
+import { createHash } from "crypto";
+function scenarioBlockHash(scenario, index) {
+  return createHash("sha256").update(`${scenario}:${index}`).digest("hex");
+}
+function createBlock(hash, parents, bits) {
+  return {
+    header: {
+      hash,
+      parents,
+      timestampUs: Date.now() * 1e3,
+      // Not deterministic but used for simulation
+      minerId: 0,
+      bits,
+      nonce: 0
+    }
+  };
+}
+function runLinearChain(config) {
+  const start = performance.now();
+  const blocks = /* @__PURE__ */ new Map();
+  const store = new GhostdagStore();
+  const engine = new ApproxGhostdagEngine(config.k ?? 18);
+  const bits = config.bits ?? 1e3;
+  const genesis = createBlock(GENESIS_HASH, [], bits);
+  blocks.set(GENESIS_HASH, genesis);
+  store.insert(GENESIS_HASH, genesisGhostdagData(GENESIS_HASH));
+  let prevHash = GENESIS_HASH;
+  for (let i = 0; i < config.blockCount; i++) {
+    const hash = scenarioBlockHash(config.name, i);
+    const block = createBlock(hash, [prevHash], bits);
+    blocks.set(hash, block);
+    const gdData = engine.computeGhostdag(block, blocks, store);
+    store.insert(hash, gdData);
+    prevHash = hash;
+  }
+  const metrics = computeDagMetrics(blocks, store, GENESIS_HASH);
+  return {
+    name: config.name,
+    config,
+    metrics,
+    computeTimeMs: performance.now() - start
+  };
+}
+function runWideDag(config) {
+  const start = performance.now();
+  const blocks = /* @__PURE__ */ new Map();
+  const store = new GhostdagStore();
+  const engine = new ApproxGhostdagEngine(config.k ?? 18);
+  const bits = config.bits ?? 1e3;
+  blocks.set(GENESIS_HASH, createBlock(GENESIS_HASH, [], bits));
+  store.insert(GENESIS_HASH, genesisGhostdagData(GENESIS_HASH));
+  const siblingCount = config.blockCount - 1;
+  for (let i = 0; i < siblingCount; i++) {
+    const hash = scenarioBlockHash(config.name, i);
+    const block = createBlock(hash, [GENESIS_HASH], bits);
+    blocks.set(hash, block);
+    const gdData = engine.computeGhostdag(block, blocks, store);
+    store.insert(hash, gdData);
+  }
+  const siblingHashes = Array.from(blocks.keys()).filter((h) => h !== GENESIS_HASH);
+  const mergerHash = scenarioBlockHash(config.name, 9999);
+  const mergerBlock = createBlock(mergerHash, siblingHashes, bits);
+  blocks.set(mergerHash, mergerBlock);
+  store.insert(mergerHash, engine.computeGhostdag(mergerBlock, blocks, store));
+  const metrics = computeDagMetrics(blocks, store, GENESIS_HASH);
+  return {
+    name: config.name,
+    config,
+    metrics,
+    computeTimeMs: performance.now() - start
+  };
+}
+function runForkResolution(config) {
+  const start = performance.now();
+  const blocks = /* @__PURE__ */ new Map();
+  const store = new GhostdagStore();
+  const engine = new ApproxGhostdagEngine(config.k ?? 18);
+  const bits = config.bits ?? 1e3;
+  blocks.set(GENESIS_HASH, createBlock(GENESIS_HASH, [], bits));
+  store.insert(GENESIS_HASH, genesisGhostdagData(GENESIS_HASH));
+  let forkHash = GENESIS_HASH;
+  for (let i = 0; i < config.forkPoint; i++) {
+    const hash = scenarioBlockHash(config.name + "-trunk", i);
+    const block = createBlock(hash, [forkHash], bits);
+    blocks.set(hash, block);
+    const gdData = engine.computeGhostdag(block, blocks, store);
+    store.insert(hash, gdData);
+    forkHash = hash;
+  }
+  const branchLength = Math.floor((config.blockCount - config.forkPoint) / 2);
+  let prevA = forkHash;
+  for (let i = 0; i < branchLength; i++) {
+    const hash = scenarioBlockHash(config.name + "-forkA", i);
+    const block = createBlock(hash, [prevA], bits);
+    blocks.set(hash, block);
+    const gdData = engine.computeGhostdag(block, blocks, store);
+    store.insert(hash, gdData);
+    prevA = hash;
+  }
+  let prevB = forkHash;
+  const branchBLength = config.blockCount - config.forkPoint - branchLength;
+  for (let i = 0; i < branchBLength; i++) {
+    const hash = scenarioBlockHash(config.name + "-forkB", i);
+    const block = createBlock(hash, [prevB], bits);
+    blocks.set(hash, block);
+    const gdData = engine.computeGhostdag(block, blocks, store);
+    store.insert(hash, gdData);
+    prevB = hash;
+  }
+  const metrics = computeDagMetrics(blocks, store, GENESIS_HASH);
+  return {
+    name: config.name,
+    config,
+    metrics,
+    computeTimeMs: performance.now() - start
+  };
+}
+function runDiamondDag(config) {
+  const start = performance.now();
+  const blocks = /* @__PURE__ */ new Map();
+  const store = new GhostdagStore();
+  const engine = new ApproxGhostdagEngine(config.k ?? 18);
+  const bits = config.bits ?? 1e3;
+  blocks.set(GENESIS_HASH, createBlock(GENESIS_HASH, [], bits));
+  store.insert(GENESIS_HASH, genesisGhostdagData(GENESIS_HASH));
+  let prevMerge = GENESIS_HASH;
+  const cycles = Math.floor(config.blockCount / 3);
+  for (let i = 0; i < cycles; i++) {
+    const hashA = scenarioBlockHash(config.name + "-A", i);
+    const blockA = createBlock(hashA, [prevMerge], bits);
+    blocks.set(hashA, blockA);
+    store.insert(hashA, engine.computeGhostdag(blockA, blocks, store));
+    const hashB = scenarioBlockHash(config.name + "-B", i);
+    const blockB = createBlock(hashB, [prevMerge], bits);
+    blocks.set(hashB, blockB);
+    store.insert(hashB, engine.computeGhostdag(blockB, blocks, store));
+    const hashM = scenarioBlockHash(config.name + "-M", i);
+    const blockM = createBlock(hashM, [hashA, hashB], bits);
+    blocks.set(hashM, blockM);
+    store.insert(hashM, engine.computeGhostdag(blockM, blocks, store));
+    prevMerge = hashM;
+  }
+  const metrics = computeDagMetrics(blocks, store, GENESIS_HASH);
+  return {
+    name: config.name,
+    config,
+    metrics,
+    computeTimeMs: performance.now() - start
+  };
+}
+function runAllScenarios(config) {
+  return [
+    runLinearChain({ ...config, name: config.name + ":linear" }),
+    runWideDag({ ...config, name: config.name + ":wide" }),
+    runForkResolution({ ...config, name: config.name + ":fork", forkPoint: Math.floor(config.blockCount / 2) }),
+    runDiamondDag({ ...config, name: config.name + ":diamond" })
+  ];
+}
+
+// src/report.ts
+function formatScenarioReport(results) {
+  let report = "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n";
+  report += " GHOSTDAG Simulation Report\n";
+  report += "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n";
+  for (const res of results) {
+    const m = res.metrics;
+    report += `Scenario: ${res.name} (K=${res.config.k ?? 18}, ${res.config.blockCount} blocks)
+`;
+    report += `  Total blocks    : ${m.totalBlocks}
+`;
+    report += `  Blue / Red      : ${m.blueBlocks} / ${m.redBlocks}
+`;
+    report += `  Red ratio       : ${m.redRatio.toFixed(4)}
+`;
+    report += `  DAG width       : ${m.dagWidth}
+`;
+    report += `  Mean parents    : ${m.meanParents.toFixed(2)}
+`;
+    report += `  Selected chain  : ${m.selectedChainLength} blocks
+`;
+    report += `  Max blueScore   : ${m.maxBlueScore}
+`;
+    report += `  Compute time    : ${res.computeTimeMs.toFixed(0)}ms
+
+`;
+  }
+  return report;
+}
+
+// src/mass-profile.ts
+import { estimateTransactionMass, estimateFeeFromMass } from "@hardkas/tx-builder";
+function formatBigInt(n) {
+  return n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function profileMass(opts) {
+  const inputCount = opts.inputCount;
+  const outputCount = opts.outputCount;
+  const payloadBytes = opts.payloadBytes ?? 0;
+  const feeRate = opts.feeRate ?? 1n;
+  const result = estimateTransactionMass({
+    inputCount,
+    outputs: Array(outputCount).fill({ address: "kaspa:qplaceholder" }),
+    payloadBytes,
+    hasChange: false
+  });
+  const breakdown = result.breakdown;
+  return {
+    totalMass: breakdown.total,
+    inputMass: breakdown.inputs + breakdown.base,
+    // Base overhead is often grouped with inputs or just kept as total
+    outputMass: breakdown.outputs,
+    payloadMass: breakdown.payload,
+    estimatedFeeSompi: estimateFeeFromMass(breakdown.total, feeRate),
+    feeRate,
+    inputCount,
+    outputCount,
+    payloadBytes
+  };
+}
+function compareMassProfiles(current, previous) {
+  const massDelta = current.totalMass - previous.totalMass;
+  const feeDelta = current.estimatedFeeSompi - previous.estimatedFeeSompi;
+  const massChangePercent = previous.totalMass > 0n ? Number(massDelta * 10000n / previous.totalMass) / 100 : 0;
+  const feeChangePercent = previous.estimatedFeeSompi > 0n ? Number(feeDelta * 10000n / previous.estimatedFeeSompi) / 100 : 0;
+  const isRegression = massDelta > 0n;
+  let severity = "none";
+  if (isRegression) {
+    if (massChangePercent >= 10) {
+      severity = "major";
+    } else {
+      severity = "minor";
+    }
+  }
+  return {
+    current,
+    previous,
+    massDelta,
+    feeDelta,
+    massChangePercent,
+    feeChangePercent,
+    isRegression,
+    severity
+  };
+}
+function formatMassProfile(breakdown) {
+  const kasAmount = Number(breakdown.estimatedFeeSompi) / 1e8;
+  return [
+    "\u2550\u2550\u2550 Mass Profile \u2550\u2550\u2550",
+    `  Inputs     : ${breakdown.inputCount} inputs \u2192 ${formatBigInt(breakdown.inputMass)} mass`,
+    `  Outputs    : ${breakdown.outputCount} outputs \u2192 ${formatBigInt(breakdown.outputMass)} mass`,
+    `  Payload    : ${breakdown.payloadBytes} bytes \u2192 ${formatBigInt(breakdown.payloadMass)} mass`,
+    `  Total mass : ${formatBigInt(breakdown.totalMass)}`,
+    `  Fee rate   : ${formatBigInt(breakdown.feeRate)} sompi/mass`,
+    `  Est. fee   : ${formatBigInt(breakdown.estimatedFeeSompi)} sompi (${kasAmount.toFixed(8)} KAS)`
+  ].join("\n");
+}
+function formatMassComparison(comparison) {
+  const massSign = comparison.massDelta >= 0n ? "+" : "";
+  const feeSign = comparison.feeDelta >= 0n ? "+" : "";
+  const statusLine = comparison.isRegression ? comparison.severity === "major" ? "\u26A0\uFE0F MAJOR REGRESSION (\u226510% increase)" : "\u2139\uFE0F MINOR REGRESSION (<10% increase)" : "\u2705 NO REGRESSION";
+  return [
+    "\u2550\u2550\u2550 Mass Comparison \u2550\u2550\u2550",
+    `  Previous   : ${formatBigInt(comparison.previous.totalMass)} mass \u2192 ${formatBigInt(comparison.previous.estimatedFeeSompi)} sompi`,
+    `  Current    : ${formatBigInt(comparison.current.totalMass)} mass \u2192 ${formatBigInt(comparison.current.estimatedFeeSompi)} sompi`,
+    `  Delta      : ${massSign}${formatBigInt(comparison.massDelta)} mass (${massSign}${comparison.massChangePercent.toFixed(1)}%)`,
+    `  Fee delta  : ${feeSign}${formatBigInt(comparison.feeDelta)} sompi (${feeSign}${comparison.feeChangePercent.toFixed(1)}%)`,
+    `  Status     : ${statusLine}`
+  ].join("\n");
+}
+
+// src/mass-snapshot.ts
+import { resolve, join } from "path";
+import { existsSync, readFileSync } from "fs";
+import { writeFileAtomicSync } from "@hardkas/core";
+function saveMassSnapshot(dir, label, breakdown) {
+  const snapshotDir = resolve(dir, ".hardkas", "mass-snapshots");
+  const snapshot = {
+    label,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    breakdown
+  };
+  const filePath = join(snapshotDir, `${label}.json`);
+  writeFileAtomicSync(filePath, JSON.stringify(snapshot, null, 2));
+}
+function loadMassSnapshot(dir, label) {
+  const filePath = resolve(dir, ".hardkas", "mass-snapshots", `${label}.json`);
+  if (!existsSync(filePath)) {
+    return void 0;
+  }
+  try {
+    const data = readFileSync(filePath, "utf8");
+    const snapshot = JSON.parse(data);
+    return reviveSnapshot(snapshot);
+  } catch (err) {
+    console.warn(`Failed to load mass snapshot "${label}":`, err);
+    return void 0;
+  }
+}
+function profileAndCompare(opts, snapshotDir, label) {
+  const currentBreakdown = profileMass(opts);
+  const previousSnapshot = loadMassSnapshot(snapshotDir, label);
+  let comparison;
+  if (previousSnapshot) {
+    comparison = compareMassProfiles(currentBreakdown, previousSnapshot.breakdown);
+  }
+  saveMassSnapshot(snapshotDir, label, currentBreakdown);
+  return {
+    breakdown: currentBreakdown,
+    ...comparison ? { comparison } : {}
+  };
+}
+function reviveSnapshot(snapshot) {
+  const b = snapshot.breakdown;
+  snapshot.breakdown = {
+    ...b,
+    totalMass: BigInt(b.totalMass),
+    inputMass: BigInt(b.inputMass),
+    outputMass: BigInt(b.outputMass),
+    payloadMass: BigInt(b.payloadMass),
+    estimatedFeeSompi: BigInt(b.estimatedFeeSompi),
+    feeRate: BigInt(b.feeRate)
+  };
+  return snapshot;
+}
 export {
+  ApproxGhostdagEngine,
+  DEFAULT_K,
+  GENESIS_HASH,
+  GhostdagStore,
   TxSimulator,
-  createTraceId
+  blockBlueScore,
+  blockBlueWork,
+  blockHash,
+  blockParents,
+  compactFromFull,
+  compareMassProfiles,
+  compareSortableBlocks,
+  computeDagMetrics,
+  createTraceId,
+  findSelectedParent,
+  formatMassComparison,
+  formatMassProfile,
+  formatScenarioReport,
+  genesisGhostdagData,
+  headerWork,
+  isDagAncestorOf,
+  loadMassSnapshot,
+  orderedMergesetWithoutSelectedParent,
+  pastSet,
+  profileAndCompare,
+  profileMass,
+  runAllScenarios,
+  runDiamondDag,
+  runForkResolution,
+  runLinearChain,
+  runWideDag,
+  saveMassSnapshot,
+  sortBlocks,
+  unorderedMergesetWithoutSelectedParent
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/simulator",
-  "version": "0.2.2-alpha",
+  "version": "0.3.0-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -8,7 +8,8 @@
     ".": "./dist/index.js"
   },
   "dependencies": {
-    "@hardkas/tx-builder": "0.2.2-alpha"
+    "@hardkas/core": "0.3.0-alpha",
+    "@hardkas/tx-builder": "0.3.0-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",