@hardkas/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,359 @@
+import { z } from 'zod';
+
+/**
+ * Lightweight branded/nominal types for domain-critical strings/numbers.
+ *
+ * These types prevent accidental misuse of raw primitives across the monorepo.
+ * Branded types remain plain strings/numbers at runtime.
+ */
+/**
+ * A Brand type that adds a unique property to a primitive type.
+ */
+type Brand<T, Name extends string> = T & {
+    readonly __brand: Name;
+};
+/**
+ * A canonical 32-byte hash (64 characters hex) representing a Kaspa Transaction.
+ */
+type TxId = Brand<string, "TxId">;
+/**
+ * A unique identifier for a HardKAS Artifact.
+ */
+type ArtifactId = Brand<string, "ArtifactId">;
+/**
+ * A SHA-256 or similar content hash.
+ */
+type ContentHash = Brand<string, "ContentHash">;
+/**
+ * A correlation ID for tracking lineage across operations.
+ */
+type LineageId = Brand<string, "LineageId">;
+/**
+ * A unique identifier for a Workflow execution.
+ */
+type WorkflowId = Brand<string, "WorkflowId">;
+/**
+ * A unique identifier for an Event.
+ */
+type EventId = Brand<string, "EventId">;
+/**
+ * A correlation ID that spans across multiple services/operations.
+ */
+type CorrelationId = Brand<string, "CorrelationId">;
+/**
+ * A Kaspa Address (e.g. kaspa:..., kaspatest:...).
+ */
+type KaspaAddress = Brand<string, "KaspaAddress">;
+/**
+ * A unique identifier for an RPC endpoint.
+ */
+type RpcEndpointId = Brand<string, "RpcEndpointId">;
+/**
+ * A Kaspa Network Identifier (e.g. mainnet, testnet-11).
+ */
+type NetworkId$1 = Brand<string, "NetworkId">;
+/**
+ * A unique sequence number for an event within a stream or store.
+ */
+type EventSequence = Brand<number, "EventSequence">;
+/**
+ * A Difficulty Adjustment Algorithm (DAA) score.
+ * Support both number and bigint for compatibility.
+ */
+type DaaScore = Brand<number | bigint, "DaaScore">;
+declare const asTxId: (id: string) => TxId;
+declare const asArtifactId: (id: string) => ArtifactId;
+declare const asContentHash: (hash: string) => ContentHash;
+declare const asLineageId: (id: string) => LineageId;
+declare const asWorkflowId: (id: string) => WorkflowId;
+declare const asEventId: (id: string) => EventId;
+declare const asCorrelationId: (id: string) => CorrelationId;
+declare const asKaspaAddress: (addr: string) => KaspaAddress;
+declare const asRpcEndpointId: (id: string) => RpcEndpointId;
+declare const asNetworkId: (id: string) => NetworkId$1;
+declare const asEventSequence: (seq: number) => EventSequence;
+declare const asDaaScore: (score: number | bigint) => DaaScore;
+
+/**
+ * HardKAS Core Event Domains.
+ */
+type EventDomain = "workflow" | "integrity" | "rpc" | "dag" | "replay" | "localnet" | "l2";
+/**
+ * HardKAS Core Event Kinds.
+ */
+type EventKind = "workflow.plan.created" | "workflow.signed" | "workflow.submitted" | "workflow.receipt" | "workflow.started" | "workflow.completed" | "workflow.failed" | "integrity.hash_mismatch" | "integrity.schema_violation" | "integrity.lineage_break" | "integrity.violation" | "dag.conflict" | "dag.displacement" | "dag.sink_moved" | "rpc.health" | "rpc.error" | "rpc.stale" | "replay.divergence" | "replay.verified" | "localnet.started" | "localnet.stopped" | "l2.deposit.planned" | "l2.withdrawal.planned";
+/**
+ * Payload mapping for each event kind.
+ */
+interface EventPayloadByKind {
+    "workflow.plan.created": {
+        planId: ArtifactId;
+        network: NetworkId$1;
+        amountSompi: bigint;
+    };
+    "workflow.signed": {
+        signedId: ArtifactId;
+        planId: ArtifactId;
+        txId?: TxId;
+    };
+    "workflow.submitted": {
+        txId: TxId;
+        rpcUrl: string;
+    };
+    "workflow.receipt": {
+        txId: TxId;
+        status: "accepted" | "finalized" | "failed";
+        daaScore?: DaaScore;
+    };
+    "workflow.started": {
+        workflowId: WorkflowId;
+        network: NetworkId$1;
+    };
+    "workflow.completed": {
+        workflowId: WorkflowId;
+    };
+    "workflow.failed": {
+        workflowId: WorkflowId;
+        error: string;
+    };
+    "integrity.hash_mismatch": {
+        artifactId: ArtifactId;
+        expected: string;
+        actual: string;
+    };
+    "integrity.schema_violation": {
+        artifactId: ArtifactId;
+        details: string;
+    };
+    "integrity.lineage_break": {
+        lineageId: LineageId;
+        artifactId: ArtifactId;
+    };
+    "integrity.violation": {
+        violationCode: string;
+        severity: string;
+        message: string;
+        metadata?: Record<string, unknown> | undefined;
+        sourceEventId?: string | undefined;
+    };
+    "dag.conflict": {
+        outpoint: string;
+        winner: TxId;
+        losers: TxId[];
+    };
+    "dag.displacement": {
+        txId: TxId;
+        displacedBy: TxId;
+    };
+    "dag.sink_moved": {
+        oldSink: string;
+        newSink: string;
+        daaScore: DaaScore;
+    };
+    "rpc.health": {
+        endpoint: RpcEndpointId;
+        state: string;
+        latencyMs: number;
+    };
+    "rpc.error": {
+        endpoint: RpcEndpointId;
+        error: string;
+        retriable: boolean;
+    };
+    "rpc.stale": {
+        endpoint: RpcEndpointId;
+        lastDaaScore: DaaScore;
+        currentDaaScore: DaaScore;
+    };
+    "replay.divergence": {
+        txId: TxId;
+        field: string;
+        expected: string;
+        actual: string;
+    };
+    "replay.verified": {
+        txId: TxId;
+        lineageId: LineageId;
+    };
+    "localnet.started": {
+        mode: string;
+        networkId: NetworkId$1;
+    };
+    "localnet.stopped": {
+        reason: string;
+    };
+    "l2.deposit.planned": {
+        asset: string;
+        amount: bigint;
+        to: string;
+    };
+    "l2.withdrawal.planned": {
+        asset: string;
+        amount: bigint;
+        from: string;
+    };
+}
+/**
+ * Formal Event Envelope (v1).
+ *
+ * Standardizes how events are captured and tracked across the system.
+ */
+interface EventEnvelope<K extends EventKind = EventKind> {
+    schema: "hardkas.event";
+    version: "1.0.0";
+    eventId: EventId;
+    domain: EventDomain;
+    kind: K;
+    timestamp: string;
+    sequence?: EventSequence | undefined;
+    workflowId: WorkflowId;
+    correlationId: CorrelationId;
+    causationId?: EventId;
+    artifactId?: ArtifactId;
+    txId?: TxId;
+    networkId: NetworkId$1;
+    payload: EventPayloadByKind[K];
+}
+/**
+ * Compatibility type for listeners.
+ */
+type CoreEvent = EventEnvelope;
+/**
+ * Legacy compatibility type for stamped events.
+ * TODO: Deprecate once all consumers migrate to EventEnvelope.
+ */
+type StampedEvent = EventEnvelope;
+type CoreEventListener = (event: EventEnvelope) => void;
+/**
+ * Lightweight in-memory Event Bus.
+ */
+declare class CoreEventBus {
+    private listeners;
+    on(listener: CoreEventListener): () => void;
+    /**
+     * Emits a formal event envelope.
+     */
+    emit<K extends EventKind>(envelope: EventEnvelope<K>): void;
+    /**
+     * Normalizes and emits an event.
+     * Useful for incremental migration from raw events.
+     */
+    normalizeAndEmit(event: any): void;
+    removeAll(): void;
+}
+declare const coreEvents: CoreEventBus;
+/**
+ * Creates a formal event envelope with required metadata.
+ */
+declare function createEventEnvelope<K extends EventKind>(params: {
+    kind: K;
+    domain: EventDomain;
+    workflowId: WorkflowId;
+    correlationId: CorrelationId;
+    networkId: NetworkId$1;
+    payload: EventPayloadByKind[K];
+    causationId?: EventId;
+    artifactId?: ArtifactId;
+    txId?: TxId;
+    eventId?: EventId;
+    sequence?: EventSequence;
+}): EventEnvelope<K>;
+/**
+ * Lightweight runtime validation for event envelopes.
+ */
+declare function validateEventEnvelope(event: any): boolean;
+/**
+ * Represents an unknown event payload for safety.
+ */
+type UnknownEventPayload = {
+    readonly type: "unknown";
+    readonly data: Record<string, unknown>;
+};
+
+/**
+ * @deprecated Use Brand from domain-types.js instead.
+ * Note: generic parameters are swapped in the new Brand type.
+ */
+type Branded<K, T> = Brand<T, K extends string ? K : string>;
+
+declare const SOMPI_PER_KAS = 100000000n;
+declare const kaspaNetworkIdSchema: z.ZodEnum<["mainnet", "testnet-10", "testnet-11", "testnet-12", "simnet", "simnet-1", "devnet"]>;
+type NetworkId = Brand<z.infer<typeof kaspaNetworkIdSchema>, "NetworkId">;
+declare const executionModeSchema: z.ZodEnum<["simulated", "real", "readonly"]>;
+type ExecutionMode = z.infer<typeof executionModeSchema>;
+declare const artifactTypeSchema: z.ZodEnum<["txPlan", "signedTx", "txReceipt", "txTrace", "snapshot"]>;
+type ArtifactType = z.infer<typeof artifactTypeSchema>;
+declare const NetworkIdSchema: z.ZodEnum<["mainnet", "testnet-10", "testnet-11", "testnet-12", "simnet", "simnet-1", "devnet"]>;
+declare const ExecutionModeSchema: z.ZodEnum<["simulated", "real", "readonly"]>;
+declare const ArtifactTypeSchema: z.ZodEnum<["txPlan", "signedTx", "txReceipt", "txTrace", "snapshot"]>;
+declare const hardkasConfigSchema: z.ZodObject<{
+    project: z.ZodObject<{
+        name: z.ZodString;
+        root: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        root: string;
+    }, {
+        name: string;
+        root: string;
+    }>;
+    network: z.ZodObject<{
+        id: z.ZodEnum<["mainnet", "testnet-10", "testnet-11", "testnet-12", "simnet", "simnet-1", "devnet"]>;
+        rpcUrl: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: "mainnet" | "testnet-10" | "testnet-11" | "testnet-12" | "simnet" | "simnet-1" | "devnet";
+        rpcUrl?: string | undefined;
+    }, {
+        id: "mainnet" | "testnet-10" | "testnet-11" | "testnet-12" | "simnet" | "simnet-1" | "devnet";
+        rpcUrl?: string | undefined;
+    }>;
+    localnet: z.ZodDefault<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<["simulated", "local-node"]>>;
+        dataDir: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "simulated" | "local-node";
+        dataDir?: string | undefined;
+    }, {
+        mode?: "simulated" | "local-node" | undefined;
+        dataDir?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    project: {
+        name: string;
+        root: string;
+    };
+    network: {
+        id: "mainnet" | "testnet-10" | "testnet-11" | "testnet-12" | "simnet" | "simnet-1" | "devnet";
+        rpcUrl?: string | undefined;
+    };
+    localnet: {
+        mode: "simulated" | "local-node";
+        dataDir?: string | undefined;
+    };
+}, {
+    project: {
+        name: string;
+        root: string;
+    };
+    network: {
+        id: "mainnet" | "testnet-10" | "testnet-11" | "testnet-12" | "simnet" | "simnet-1" | "devnet";
+        rpcUrl?: string | undefined;
+    };
+    localnet?: {
+        mode?: "simulated" | "local-node" | undefined;
+        dataDir?: string | undefined;
+    } | undefined;
+}>;
+type HardkasConfig = z.infer<typeof hardkasConfigSchema>;
+declare class HardkasError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare function parseHardkasConfig(input: unknown): HardkasConfig;
+declare function parseKasToSompi(input: string): bigint;
+declare function formatSompi(amountSompi: bigint): string;
+
+export { type ArtifactId, type ArtifactType, ArtifactTypeSchema, type Brand, type Branded, type ContentHash, type CoreEvent, type CoreEventListener, type CorrelationId, type DaaScore, type EventDomain, type EventEnvelope, type EventId, type EventKind, type EventPayloadByKind, type EventSequence, type ExecutionMode, ExecutionModeSchema, type HardkasConfig, HardkasError, type KaspaAddress, type LineageId, type NetworkId, NetworkIdSchema, type RpcEndpointId, SOMPI_PER_KAS, type StampedEvent, type TxId, type UnknownEventPayload, type WorkflowId, artifactTypeSchema, asArtifactId, asContentHash, asCorrelationId, asDaaScore, asEventId, asEventSequence, asKaspaAddress, asLineageId, asNetworkId, asRpcEndpointId, asTxId, asWorkflowId, coreEvents, createEventEnvelope, executionModeSchema, formatSompi, hardkasConfigSchema, kaspaNetworkIdSchema, parseHardkasConfig, parseKasToSompi, validateEventEnvelope };

package/dist/index.js

@@ -0,0 +1,187 @@
+// src/index.ts
+import { z } from "zod";
+
+// src/events.ts
+var CoreEventBus = class {
+  listeners = [];
+  on(listener) {
+    this.listeners.push(listener);
+    return () => {
+      this.listeners = this.listeners.filter((l) => l !== listener);
+    };
+  }
+  /**
+   * Emits a formal event envelope.
+   */
+  emit(envelope) {
+    for (const listener of this.listeners) {
+      try {
+        listener(envelope);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Normalizes and emits an event. 
+   * Useful for incremental migration from raw events.
+   */
+  normalizeAndEmit(event) {
+    if (validateEventEnvelope(event)) {
+      this.emit(event);
+    } else {
+    }
+  }
+  removeAll() {
+    this.listeners = [];
+  }
+};
+var coreEvents = new CoreEventBus();
+function createEventEnvelope(params) {
+  return {
+    schema: "hardkas.event",
+    version: "1.0.0",
+    eventId: params.eventId || crypto.randomUUID(),
+    domain: params.domain,
+    kind: params.kind,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    workflowId: params.workflowId,
+    correlationId: params.correlationId,
+    causationId: params.causationId,
+    artifactId: params.artifactId,
+    txId: params.txId,
+    networkId: params.networkId,
+    payload: params.payload,
+    ...params.sequence !== void 0 ? { sequence: params.sequence } : {}
+  };
+}
+function validateEventEnvelope(event) {
+  if (!event || typeof event !== "object") return false;
+  if (event.schema !== "hardkas.event") return false;
+  if (!event.eventId || !event.domain || !event.kind) return false;
+  if (!event.workflowId || !event.correlationId || !event.networkId) return false;
+  if (typeof event.payload !== "object") return false;
+  return true;
+}
+
+// src/domain-types.ts
+var asTxId = (id) => id;
+var asArtifactId = (id) => id;
+var asContentHash = (hash) => hash;
+var asLineageId = (id) => id;
+var asWorkflowId = (id) => id;
+var asEventId = (id) => id;
+var asCorrelationId = (id) => id;
+var asKaspaAddress = (addr) => addr;
+var asRpcEndpointId = (id) => id;
+var asNetworkId = (id) => id;
+var asEventSequence = (seq) => seq;
+var asDaaScore = (score) => score;
+
+// src/index.ts
+var SOMPI_PER_KAS = 100000000n;
+var kaspaNetworkIdSchema = z.enum([
+  "mainnet",
+  "testnet-10",
+  "testnet-11",
+  "testnet-12",
+  "simnet",
+  "simnet-1",
+  "devnet"
+]);
+var executionModeSchema = z.enum([
+  "simulated",
+  "real",
+  "readonly"
+]);
+var artifactTypeSchema = z.enum([
+  "txPlan",
+  "signedTx",
+  "txReceipt",
+  "txTrace",
+  "snapshot"
+]);
+var NetworkIdSchema = kaspaNetworkIdSchema;
+var ExecutionModeSchema = executionModeSchema;
+var ArtifactTypeSchema = artifactTypeSchema;
+var hardkasConfigSchema = z.object({
+  project: z.object({
+    name: z.string().min(1),
+    root: z.string().min(1)
+  }),
+  network: z.object({
+    id: kaspaNetworkIdSchema,
+    rpcUrl: z.string().url().optional()
+  }),
+  localnet: z.object({
+    mode: z.enum(["simulated", "local-node"]).default("simulated"),
+    dataDir: z.string().optional()
+  }).default({ mode: "simulated" })
+});
+var HardkasError = class extends Error {
+  code;
+  cause;
+  constructor(code, message, options) {
+    super(message);
+    this.name = "HardkasError";
+    this.code = code;
+    this.cause = options?.cause;
+  }
+};
+function parseHardkasConfig(input) {
+  const result = hardkasConfigSchema.safeParse(input);
+  if (!result.success) {
+    throw new HardkasError(
+      "CONFIG_INVALID",
+      result.error.issues.map((issue) => issue.message).join("; "),
+      { cause: result.error }
+    );
+  }
+  return result.data;
+}
+function parseKasToSompi(input) {
+  const trimmed = input.trim();
+  if (!/^\d+(\.\d{1,8})?$/.test(trimmed)) {
+    throw new HardkasError("AMOUNT_INVALID", `Invalid KAS amount: ${input}`);
+  }
+  const [whole, fractional = ""] = trimmed.split(".");
+  if (whole === void 0) {
+    throw new HardkasError("AMOUNT_INVALID", `Invalid KAS amount: ${input}`);
+  }
+  return BigInt(whole) * SOMPI_PER_KAS + BigInt(fractional.padEnd(8, "0"));
+}
+function formatSompi(amountSompi) {
+  const sign = amountSompi < 0n ? "-" : "";
+  const absolute = amountSompi < 0n ? -amountSompi : amountSompi;
+  const whole = absolute / SOMPI_PER_KAS;
+  const fractional = absolute % SOMPI_PER_KAS;
+  return `${sign}${whole}.${fractional.toString().padStart(8, "0")} KAS`;
+}
+export {
+  ArtifactTypeSchema,
+  ExecutionModeSchema,
+  HardkasError,
+  NetworkIdSchema,
+  SOMPI_PER_KAS,
+  artifactTypeSchema,
+  asArtifactId,
+  asContentHash,
+  asCorrelationId,
+  asDaaScore,
+  asEventId,
+  asEventSequence,
+  asKaspaAddress,
+  asLineageId,
+  asNetworkId,
+  asRpcEndpointId,
+  asTxId,
+  asWorkflowId,
+  coreEvents,
+  createEventEnvelope,
+  executionModeSchema,
+  formatSompi,
+  hardkasConfigSchema,
+  kaspaNetworkIdSchema,
+  parseHardkasConfig,
+  parseKasToSompi,
+  validateEventEnvelope
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hardkas/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "pino": "^9.5.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "license": "MIT",
+  "author": "Javier Rodriguez",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jrodrg92/Hardkas.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/jrodrg92/Hardkas/issues"
+  },
+  "homepage": "https://github.com/jrodrg92/Hardkas/tree/main/packages/core#readme",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}