@hardkas/localnet 0.8.14-alpha → 0.8.15-alpha

package/dist/index.d.ts

@@ -0,0 +1,438 @@
+import * as _hardkas_artifacts 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, RuntimeContext } from '@hardkas/core';
+import { KaspaRpcClient, KaspaNodeInfo, KaspaRpcHealth, KaspaAddressBalance, KaspaRpcUtxo, KaspaSubmitTransactionResult, MempoolEntry, BlockDagInfo, ServerInfo } from '@hardkas/kaspa-rpc';
+
+interface HardkasAccount {
+    readonly name: string;
+    readonly address: string;
+    readonly evmAddress: string;
+    readonly balanceSompi: bigint;
+}
+declare function createDeterministicAccounts(input?: {
+    readonly count?: number | undefined;
+    readonly initialBalanceSompi?: bigint | undefined;
+} | undefined): HardkasAccount[];
+declare function resolveAccountAddress(input: string): string;
+
+interface SimulatedUtxo {
+    readonly id: string;
+    readonly address: string;
+    readonly amountSompi: bigint;
+    readonly spent: boolean;
+}
+interface Snapshot {
+    readonly id: string;
+    readonly utxos: readonly SimulatedUtxo[];
+    readonly daaScore: bigint;
+}
+declare class SimulatedKaspaChain {
+    private utxos;
+    private daaScore;
+    constructor(accounts: readonly HardkasAccount[]);
+    getDaaScore(): bigint;
+    mineBlock(): bigint;
+    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;
+}
+
+interface HardkasDevnet {
+    readonly mode: "simulated";
+    readonly accounts: readonly HardkasAccount[];
+    readonly chain: SimulatedKaspaChain;
+    stop(): Promise<void>;
+}
+declare function startSimulatedDevnet(input?: {
+    readonly accounts?: number | undefined;
+    readonly initialBalanceSompi?: bigint | undefined;
+} | undefined): Promise<HardkasDevnet>;
+
+interface LocalnetAccount {
+    name: string;
+    address: string;
+}
+interface LocalnetUtxo {
+    id: string;
+    address: string;
+    amountSompi: string;
+    spent: boolean;
+    createdAtDaaScore: string;
+    spentAtDaaScore?: string;
+}
+interface LocalnetState extends HardkasArtifactBase {
+    schema: "hardkas.localnetState.v1";
+    hardkasVersion: string;
+    version: string;
+    createdAt: string;
+    mode: ExecutionMode;
+    networkId: NetworkId;
+    workflowId?: string;
+    assumptionLevel?: string;
+    daaScore: string;
+    accounts: LocalnetAccount[];
+    utxos: LocalnetUtxo[];
+    snapshots?: Snapshot$1[];
+    dag?: SimulatedDag;
+    forkSource?: {
+        network: string;
+        rpcUrl: string;
+        daaScore: string;
+        forkedAt: string;
+        addresses: string[];
+    };
+}
+interface SimulatedBlock {
+    id: string;
+    parents: string[];
+    blueScore: string;
+    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>;
+    sink: string;
+    selectedPathToSink: string[];
+    acceptedTxIds: string[];
+    displacedTxIds: string[];
+    conflictSet: Array<{
+        outpoint: string;
+        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;
+    postStateHash: string;
+    daaScore: string;
+}
+interface SimulationResult {
+    ok: boolean;
+    state: LocalnetState;
+    receipt: _hardkas_artifacts.TxReceipt;
+    planArtifact?: _hardkas_artifacts.TxPlan;
+    errors: string[];
+}
+interface ReplayInvariantResult {
+    ok: boolean;
+    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 {
+    ok: boolean;
+    hashes: {
+        accountsMatch: boolean;
+        utxoSetMatch: boolean;
+        stateMatch: boolean;
+        contentMatch: boolean;
+    };
+    errors: string[];
+}
+interface SnapshotRestoreResult {
+    ok: boolean;
+    previousStateHash?: string;
+    newStateHash?: string;
+    error?: string;
+}
+
+interface CreateInitialStateOptions {
+    accounts?: number | undefined;
+    initialBalanceSompi?: bigint | undefined;
+}
+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;
+declare function saveLocalnetState(state: LocalnetState, filePath?: string): Promise<void>;
+declare function loadLocalnetState(filePath?: string): Promise<LocalnetState | null>;
+declare function loadOrCreateLocalnetState(options?: {
+    cwd?: string;
+    accounts?: number;
+    initialBalanceSompi?: bigint;
+}): Promise<LocalnetState>;
+declare function resetLocalnetState(options?: {
+    cwd?: string;
+    accounts?: number;
+    initialBalanceSompi?: bigint;
+}): Promise<LocalnetState>;
+
+interface FundAddressInput {
+    address: string;
+    amountSompi: bigint;
+}
+declare function fundAddress(state: LocalnetState, input: FundAddressInput): LocalnetState;
+
+declare function getAddressBalanceSompi(state: LocalnetState, address: string): bigint;
+declare function getAccountBalanceSompi(state: LocalnetState, nameOrAddress: string): bigint;
+declare function getSpendableUtxos(state: LocalnetState, address: string): LocalnetUtxo[];
+
+/**
+ * Calculates hash of the UTXO set (sorted by outpoint).
+ */
+declare function calculateUtxoSetHash(utxos: LocalnetUtxo[]): string;
+/**
+ * Calculates hash of the account set (sorted by address).
+ */
+declare function calculateAccountsHash(accounts: LocalnetAccount[]): string;
+/**
+ * Calculates the state hash (daaScore + accountsHash + utxoSetHash).
+ */
+declare function calculateStateHash(state: LocalnetState): string;
+/**
+ * Creates a canonical deterministic snapshot.
+ */
+declare function createLocalnetSnapshot(state: LocalnetState, name?: string): LocalnetState;
+/**
+ * Verifies the integrity of a snapshot.
+ */
+declare function verifySnapshot(snapshot: Snapshot$1): SnapshotVerificationResult;
+/**
+ * Restores a snapshot with atomic safety and verification.
+ */
+declare function restoreLocalnetSnapshot(state: LocalnetState, snapshotIdOrName: string): LocalnetState;
+
+interface SimulatedPaymentInput {
+    readonly from: string;
+    readonly to: string;
+    readonly amountSompi: bigint;
+    readonly feeRateSompiPerMass?: bigint;
+}
+/**
+ * Standard Kaspa dust limit (approximate).
+ */
+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, ctx: RuntimeContext): SimulationResult;
+/**
+ * Executes a pre-built transaction plan against the simulated state.
+ */
+declare function applySimulatedPlan(state: LocalnetState, planArtifact: TxPlan, ctx: RuntimeContext, options?: {
+    txId?: string;
+}): SimulationResult;
+
+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;
+    networkId: NetworkId;
+    from: {
+        address: string;
+    };
+    to: {
+        address: string;
+    };
+    amountSompi: string;
+    feeSompi: string;
+    changeSompi?: string | undefined;
+    spentUtxoIds: string[];
+    createdUtxoIds: string[];
+    daaScore: string;
+}
+declare function getDefaultReceiptsDir(cwd?: string): string;
+declare function getReceiptPath(txId: string, cwd?: string): string;
+declare function saveSimulatedReceipt(receipt: StoredSimulatedTxReceipt, options?: {
+    cwd?: string;
+}): Promise<string>;
+declare function loadSimulatedReceipt(txId: string, options?: {
+    cwd?: string;
+}): Promise<StoredSimulatedTxReceipt>;
+declare function listSimulatedReceipts(options?: {
+    cwd?: string;
+}): Promise<StoredSimulatedTxReceipt[]>;
+
+type StoredTraceEvent = {
+    readonly type: "phase.started";
+    readonly phase: string;
+    readonly timestamp: number;
+} | {
+    readonly type: "phase.completed";
+    readonly phase: string;
+    readonly timestamp: number;
+} | {
+    readonly type: "note";
+    readonly message: string;
+    readonly timestamp: number;
+} | {
+    readonly type: "tx.failed";
+    readonly phase: string;
+    readonly reason: string;
+    readonly timestamp: number;
+};
+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;
+    readonly events: readonly StoredTraceEvent[];
+    readonly receiptPath?: string | undefined;
+}
+declare function getDefaultTracesDir(cwd?: string): string;
+declare function getTracePath(txId: string, cwd?: string): string;
+declare function saveSimulatedTrace(trace: StoredSimulatedTxTrace, options?: {
+    cwd?: string;
+}): Promise<string>;
+declare function loadSimulatedTrace(txId: string, options?: {
+    cwd?: string;
+}): Promise<StoredSimulatedTxTrace>;
+declare function listSimulatedTraces(options?: {
+    cwd?: string;
+}): Promise<StoredSimulatedTxTrace[]>;
+
+interface SimulatedReplaySummary {
+    receipt: TxReceipt;
+    trace: StoredSimulatedTxTrace;
+    summary: {
+        spentCount: number;
+        createdCount: number;
+        transferredSompi: bigint;
+        feeSompi: bigint;
+        changeSompi: bigint;
+        finalDaaScore: string;
+    };
+}
+/**
+ * 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, ctx: RuntimeContext): ReplayVerificationReport;
+/**
+ * Loads receipt and trace for a transaction and produces a summary.
+ */
+declare function getSimulatedReplaySummary(txId: string, options?: {
+    cwd?: string;
+}): Promise<SimulatedReplaySummary>;
+
+/**
+ * Creates a fresh simulated DAG with a genesis block.
+ */
+declare function createSimulatedDag(options?: {
+    k?: number;
+}): SimulatedDag;
+/**
+ * Adds a block to the DAG.
+ */
+declare function addSimulatedBlock(dag: SimulatedDag, block: SimulatedBlock): SimulatedDag;
+/**
+ * Moves the sink and recomputes the accepted transaction set.
+ */
+declare function moveSink(dag: SimulatedDag, newSinkId: string, txProvider: (txId: string) => {
+    inputs: string[];
+} | undefined): SimulatedDag;
+/**
+ * Deterministic Conflict Resolution (Approximation for 0.8.15-alpha)
+ * Priority:
+ * 1. sink ancestry priority (is part of selectedPathToSink?)
+ * 2. deterministic block order (daaScore then block ID)
+ * 3. txId lexicographic tie-break
+ */
+declare function resolveConflictsDeterministically(txs: Array<{
+    txId: string;
+    blockId: string;
+    inputs: string[];
+}>, dag: SimulatedDag): {
+    accepted: string[];
+    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>;
+
+declare class LocalnetSimulatedProvider implements KaspaRpcClient {
+    private readonly workspacePath;
+    constructor(workspacePath: string);
+    getInfo(): Promise<KaspaNodeInfo>;
+    healthCheck(): Promise<KaspaRpcHealth>;
+    getBalanceByAddress(address: string): Promise<KaspaAddressBalance>;
+    getBalancesByAddresses(addresses: string[]): Promise<KaspaAddressBalance[]>;
+    getUtxosByAddress(address: string): Promise<KaspaRpcUtxo[]>;
+    getUtxosByAddresses(addresses: string[]): Promise<KaspaRpcUtxo[]>;
+    submitTransaction(rawTransaction: string): Promise<KaspaSubmitTransactionResult>;
+    getMempoolEntry(txId: string): Promise<MempoolEntry | null>;
+    getTransaction(txId: string): Promise<unknown | null>;
+    getBlockDagInfo(): Promise<BlockDagInfo>;
+    getServerInfo(): Promise<ServerInfo>;
+    close(): Promise<void>;
+}
+
+export { type CreateInitialStateOptions, DUST_LIMIT_SOMPI, type ForkOptions, type FundAddressInput, type HardkasAccount, type HardkasDevnet, type LocalnetAccount, LocalnetSimulatedProvider, 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

@@ -1143,6 +1143,8 @@ async function forkFromNetwork(rpc, opts) {
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
     // hardkas-determinism-allow: fork state creation timestamp
     networkId,
+    workflowId: "wf_system_bootstrap",
+    assumptionLevel: "default",
     daaScore: targetDaaScore,
     accounts: opts.addresses.map((addr, i) => ({
       name: `forked_${i}`,

package/package.json

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