@hardkas/testing 0.2.2-alpha → 0.2.2-alpha.1

package/dist/index.d.ts

@@ -1,25 +1,69 @@
-import { MockKaspaRpcClient } from '@hardkas/kaspa-rpc';
+import { Hardkas } from '@hardkas/sdk';
+import { CoreEvent, NetworkId } from '@hardkas/core';
+import { BaseArtifact } from '@hardkas/artifacts';
 
-interface TestWallet {
-    readonly name: string;
-    readonly address: string;
+/**
+ * System Invariant Verifiers
+ *
+ * Instead of just unit tests, these provide "System Guarantees".
+ */
+declare const Invariants: {
+    /**
+     * Guarantee: An artifact's content hash MUST match its current state.
+     */
+    verifyArtifactIntegrity(artifact: BaseArtifact<any>, calculateHash: (a: any) => string): Promise<boolean>;
+    /**
+     * Guarantee: A Lineage chain MUST be strictly monotonic and linked.
+     */
+    verifyLineageContinuity(artifacts: BaseArtifact<any>[]): boolean;
+    /**
+     * Guarantee: Every emission to the event bus MUST have a timestamp.
+     */
+    verifyEventCompliance(event: CoreEvent): boolean;
+};
+/**
+ * Invariant Watcher
+ * Can be hooked into the event bus to detect violations in real-time.
+ */
+declare class InvariantWatcher {
+    private violations;
+    constructor();
+    getViolations(): string[];
+    hasViolations(): boolean;
 }
-interface HardkasTestContext {
-    readonly wallets: {
-        readonly alice: TestWallet;
-        readonly bob: TestWallet;
-        readonly carol: TestWallet;
-        readonly faucet: TestWallet;
-    };
-    readonly rpc: MockKaspaRpcClient;
-    readonly faucet: {
-        fund(address: string, amountSompi: bigint): Promise<void>;
-    };
-    reset(): Promise<void>;
+
+interface FuzzResult {
+    ok: boolean;
+    iterations: number;
+    violations: string[];
 }
-declare function createHardkasTestContext(): Promise<HardkasTestContext>;
-declare const hardkas: {
-    localnet: typeof createHardkasTestContext;
-};
+/**
+ * Custom Scenario Fuzzer for UTXO Invariants.
+ * Verifies that sum(inputs) == sum(outputs) + fee across random transaction sequences.
+ */
+declare function runUtxoFuzzer(iterations?: number): Promise<FuzzResult>;
+
+/**
+ * HardKAS Testing Runtime
+ */
+interface HardkasTestRuntime {
+    readonly hardkas: Hardkas;
+    readonly network: NetworkId;
+    readonly accounts: Hardkas["accounts"];
+    readonly tx: Hardkas["tx"];
+    readonly localnet: Hardkas["localnet"];
+    readonly query: Hardkas["query"];
+}
+interface HardkasTestOptions {
+    cwd?: string;
+    network?: NetworkId;
+    autoStartLocalnet?: boolean;
+    resetBetweenTests?: boolean;
+}
+/**
+ * The main helper for HardKAS tests.
+ * Injects hooks for Vitest and provides access to the SDK.
+ */
+declare function hardkasTest(options?: HardkasTestOptions): HardkasTestRuntime;
 
-export { type HardkasTestContext, type TestWallet, createHardkasTestContext, hardkas };
+export { type FuzzResult, type HardkasTestOptions, type HardkasTestRuntime, InvariantWatcher, Invariants, hardkasTest, runUtxoFuzzer };

package/dist/index.js

@@ -1,50 +1,170 @@
 // src/index.ts
-import { MockKaspaRpcClient } from "@hardkas/kaspa-rpc";
-import { createDeterministicAccounts } from "@hardkas/localnet";
-import { createMockUtxo } from "@hardkas/tx-builder";
-async function createHardkasTestContext() {
-  const rpc = new MockKaspaRpcClient("simnet");
-  const accounts = createDeterministicAccounts({
-    count: 4,
-    initialBalanceSompi: 0n
-  });
-  const alice = accounts[0];
-  const bob = accounts[1];
-  const carol = accounts[2];
-  if (!alice || !bob || !carol) {
-    throw new Error("Failed to create deterministic test accounts.");
+import { Hardkas } from "@hardkas/sdk";
+import { beforeAll, beforeEach } from "vitest";
+
+// src/invariants.ts
+import { coreEvents } from "@hardkas/core";
+var Invariants = {
+  /**
+   * Guarantee: An artifact's content hash MUST match its current state.
+   */
+  async verifyArtifactIntegrity(artifact, calculateHash) {
+    if (!artifact.contentHash) return true;
+    const actual = calculateHash(artifact);
+    return artifact.contentHash === actual;
+  },
+  /**
+   * Guarantee: A Lineage chain MUST be strictly monotonic and linked.
+   */
+  verifyLineageContinuity(artifacts) {
+    if (artifacts.length < 2) return true;
+    const sorted = [...artifacts].sort(
+      (a, b) => (a.lineage?.sequence ?? 0) - (b.lineage?.sequence ?? 0)
+    );
+    for (let i = 1; i < sorted.length; i++) {
+      const prev = sorted[i - 1];
+      const curr = sorted[i];
+      if (!prev || !curr) continue;
+      if (curr.lineage?.parentArtifactId !== prev.lineage?.artifactId) {
+        return false;
+      }
+      if (curr.lineage?.lineageId !== prev.lineage?.lineageId) {
+        return false;
+      }
+    }
+    return true;
+  },
+  /**
+   * Guarantee: Every emission to the event bus MUST have a timestamp.
+   */
+  verifyEventCompliance(event) {
+    return !!event.timestamp;
+  }
+};
+var InvariantWatcher = class {
+  violations = [];
+  constructor() {
+    coreEvents.on((event) => {
+      if (!Invariants.verifyEventCompliance(event)) {
+        this.violations.push(`Event compliance violation: ${event.kind}`);
+      }
+      if (event.kind === "integrity.hash_mismatch") {
+        const payload = event.payload;
+        this.violations.push(`Hash mismatch detected: ${payload.artifactId || event.artifactId}`);
+      }
+    });
   }
-  const wallets = {
-    alice: { name: alice.name, address: alice.address },
-    bob: { name: bob.name, address: bob.address },
-    carol: { name: carol.name, address: carol.address },
-    faucet: { name: "faucet", address: "kaspa:sim_faucet" }
+  getViolations() {
+    return this.violations;
+  }
+  hasViolations() {
+    return this.violations.length > 0;
+  }
+};
+
+// src/utxo-fuzzer.ts
+import { SOMPI_PER_KAS } from "@hardkas/core";
+import { buildPaymentPlan } from "@hardkas/tx-builder";
+import { applySimulatedPayment, createInitialLocalnetState } from "@hardkas/localnet";
+async function runUtxoFuzzer(iterations = 50) {
+  let state = createInitialLocalnetState({ accounts: 5, initialBalanceSompi: 1000n * SOMPI_PER_KAS });
+  const violations = [];
+  for (let i = 0; i < iterations; i++) {
+    const fromIdx = Math.floor(Math.random() * state.accounts.length);
+    let toIdx = Math.floor(Math.random() * state.accounts.length);
+    if (fromIdx === toIdx) toIdx = (toIdx + 1) % state.accounts.length;
+    const fromAccount = state.accounts[fromIdx];
+    const toAccount = state.accounts[toIdx];
+    const amountSompi = BigInt(Math.floor(Math.random() * 10)) * SOMPI_PER_KAS + BigInt(Math.floor(Math.random() * 1e6));
+    try {
+      const unspent = state.utxos.filter((u) => u.address === fromAccount.address && !u.spent);
+      if (unspent.length === 0) continue;
+      const builderUtxos = unspent.map((u) => ({
+        outpoint: { transactionId: u.id.split(":")[0], index: 0 },
+        address: u.address,
+        amountSompi: BigInt(u.amountSompi),
+        scriptPublicKey: "mock"
+      }));
+      const plan = buildPaymentPlan({
+        fromAddress: fromAccount.address,
+        availableUtxos: builderUtxos,
+        outputs: [{ address: toAccount.address, amountSompi }],
+        feeRateSompiPerMass: 1n
+      });
+      const inputSum = plan.inputs.reduce((s, x) => s + x.amountSompi, 0n);
+      const outputSum = plan.outputs.reduce((s, x) => s + x.amountSompi, 0n) + (plan.change?.amountSompi || 0n);
+      const fee = plan.estimatedFeeSompi;
+      if (inputSum !== outputSum + fee) {
+        violations.push(`Iteration ${i}: Planning Invariant Violated! ${inputSum} != ${outputSum} + ${fee}`);
+      }
+      const result = applySimulatedPayment(state, {
+        from: fromAccount.name,
+        to: toAccount.name,
+        amountSompi
+      });
+      state = result.state;
+      const totalInState = state.utxos.filter((u) => !u.spent).reduce((s, x) => s + BigInt(x.amountSompi), 0n);
+      const expectedTotal = BigInt(state.accounts.length) * 1000n * SOMPI_PER_KAS - BigInt(i + 1) * fee;
+      const utxoIds = state.utxos.map((u) => u.id);
+      const uniqueIds = new Set(utxoIds);
+      if (utxoIds.length !== uniqueIds.size) {
+        violations.push(`Iteration ${i}: Duplicate UTXO IDs detected in state!`);
+      }
+    } catch (e) {
+      if (!e.message.includes("Insufficient funds")) {
+        violations.push(`Iteration ${i}: Unexpected Error: ${e.message}`);
+      }
+    }
+  }
+  return {
+    ok: violations.length === 0,
+    iterations,
+    violations
   };
+}
+
+// src/index.ts
+function hardkasTest(options = {}) {
+  const cwd = options.cwd || process.env.HARDKAS_CWD || ".";
+  const network = options.network || process.env.HARDKAS_NETWORK || "simnet";
+  const autoStart = options.autoStartLocalnet ?? true;
+  const autoReset = options.resetBetweenTests ?? true;
+  let sdk;
+  beforeAll(async () => {
+    sdk = await Hardkas.open(cwd);
+    if (autoStart && network === "simnet") {
+      await sdk.localnet.start();
+    }
+  });
+  beforeEach(async () => {
+    if (autoReset && network === "simnet") {
+      await sdk.localnet.reset();
+    }
+  });
   return {
-    wallets,
-    rpc,
-    faucet: {
-      async fund(address, amountSompi) {
-        rpc.setUtxos(address, [
-          createMockUtxo({
-            address,
-            amountSompi,
-            index: 0
-          })
-        ]);
-      }
+    get hardkas() {
+      return sdk;
+    },
+    get network() {
+      return network;
+    },
+    get accounts() {
+      return sdk.accounts;
     },
-    async reset() {
-      rpc.setUtxos(wallets.alice.address, []);
-      rpc.setUtxos(wallets.bob.address, []);
-      rpc.setUtxos(wallets.carol.address, []);
+    get tx() {
+      return sdk.tx;
+    },
+    get localnet() {
+      return sdk.localnet;
+    },
+    get query() {
+      return sdk.query;
     }
   };
 }
-var hardkas = {
-  localnet: createHardkasTestContext
-};
 export {
-  createHardkasTestContext,
-  hardkas
+  InvariantWatcher,
+  Invariants,
+  hardkasTest,
+  runUtxoFuzzer
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/testing",
-  "version": "0.2.2-alpha",
+  "version": "0.2.2-alpha.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -8,12 +8,13 @@
     ".": "./dist/index.js"
   },
   "dependencies": {
-    "@hardkas/artifacts": "0.2.2-alpha",
-    "@hardkas/core": "0.2.2-alpha",
-    "@hardkas/kaspa-rpc": "0.2.2-alpha",
-    "@hardkas/simulator": "0.2.2-alpha",
-    "@hardkas/localnet": "0.2.2-alpha",
-    "@hardkas/tx-builder": "0.2.2-alpha"
+    "@hardkas/artifacts": "0.2.2-alpha.1",
+    "@hardkas/sdk": "0.2.2-alpha.1",
+    "@hardkas/kaspa-rpc": "0.2.2-alpha.1",
+    "@hardkas/core": "0.2.2-alpha.1",
+    "@hardkas/localnet": "0.2.2-alpha.1",
+    "@hardkas/simulator": "0.2.2-alpha.1",
+    "@hardkas/tx-builder": "0.2.2-alpha.1"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
@@ -37,7 +38,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts --format esm --dts --clean --external vitest",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "lint": "eslint ."