@hardkas/kaspa-rpc 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,293 @@
+import { NetworkId } from '@hardkas/core';
+
+type RpcHealthState = "healthy" | "degraded" | "stale" | "unreachable";
+type RpcConfidence = "high" | "medium" | "low";
+interface RpcTrace {
+    endpoint: string;
+    method: string;
+    latencyMs: number;
+    retries: number;
+    timedOut: boolean;
+    errorClass?: string;
+}
+interface ResilienceReport {
+    state: RpcHealthState;
+    confidence: RpcConfidence;
+    score: number;
+    issues: string[];
+}
+/**
+ * Calculates RPC confidence based on health metrics.
+ */
+declare function calculateConfidence(metrics: {
+    latencyMs: number | null;
+    successRate: number;
+    retries: number;
+    stale: boolean;
+    reachable: boolean;
+    circuitOpen: boolean;
+}): ResilienceReport;
+/**
+ * Classifies an error as transient (retriable) or permanent.
+ */
+declare function classifyRpcError(error: any): {
+    retriable: boolean;
+    category: string;
+};
+
+declare enum CircuitState {
+    CLOSED = "CLOSED",
+    OPEN = "OPEN",
+    HALF_OPEN = "HALF_OPEN"
+}
+interface RetryOptions {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+}
+interface CircuitBreakerOptions {
+    failureThreshold: number;
+    resetTimeoutMs: number;
+}
+interface RpcClientOptions {
+    url: string;
+    timeoutMs?: number | undefined;
+    retry?: Partial<RetryOptions>;
+    circuitBreaker?: Partial<CircuitBreakerOptions>;
+    fetcher?: typeof fetch;
+}
+declare class KaspaJsonRpcClient implements KaspaRpcClient {
+    readonly url: string;
+    private readonly timeoutMs;
+    private readonly retry;
+    private readonly circuitBreaker;
+    private readonly fetcher;
+    private circuitState;
+    private failureCount;
+    private lastFailureTime;
+    private lastError;
+    private lastLatencyMs;
+    private totalRequests;
+    private successfulRequests;
+    private lastDaaScore;
+    private lastDaaCheckTime;
+    private retriesCount;
+    constructor(options: RpcClientOptions);
+    healthCheck(): Promise<KaspaRpcHealth>;
+    getInfo(): Promise<KaspaNodeInfo>;
+    getBlockDagInfo(): Promise<BlockDagInfo>;
+    getUtxosByAddress(address: string): Promise<KaspaRpcUtxo[]>;
+    getBalanceByAddress(address: string): Promise<KaspaAddressBalance>;
+    getMempoolEntry(txId: string): Promise<MempoolEntry | null>;
+    getTransaction(txId: string): Promise<unknown | null>;
+    submitTransaction(rawTx: unknown): Promise<{
+        transactionId: string;
+    }>;
+    getServerInfo(): Promise<ServerInfo>;
+    close(): Promise<void>;
+    private callRpc;
+    private withResilience;
+    private internalCall;
+    private checkCircuit;
+    private onSuccess;
+    private onFailure;
+    private isDeterministicError;
+    private getSuccessRate;
+}
+
+interface RpcHealthCheckOptions {
+    readonly url?: string | undefined;
+    readonly timeoutMs?: number | undefined;
+}
+interface RpcReadinessWaitOptions extends RpcHealthCheckOptions {
+    readonly wait?: boolean | undefined;
+    readonly intervalMs?: number | undefined;
+    readonly maxWaitMs?: number | undefined;
+}
+interface RpcHealthResult {
+    readonly endpoint: string;
+    readonly status: RpcHealthState;
+    readonly ready: boolean;
+    readonly checkedAt: string;
+    readonly latencyMs?: number | undefined;
+    readonly networkId?: string | undefined;
+    readonly virtualDaaScore?: string | undefined;
+    readonly serverVersion?: string | undefined;
+    readonly isSynced?: boolean | undefined;
+    readonly error?: string | undefined;
+    readonly lastError?: string | null | undefined;
+    readonly retries?: number | undefined;
+    readonly circuitState?: string | undefined;
+    readonly stale?: boolean | undefined;
+}
+
+declare function checkKaspaRpcHealth(options?: RpcHealthCheckOptions): Promise<RpcHealthResult>;
+declare function waitForKaspaRpcReady(options?: RpcReadinessWaitOptions): Promise<RpcHealthResult>;
+
+declare class RpcError extends Error {
+    readonly code?: number | undefined;
+    readonly data?: unknown | undefined;
+    readonly isRetriable: boolean;
+    constructor(message: string, code?: number | undefined, data?: unknown | undefined, isRetriable?: boolean);
+}
+declare class RpcTimeoutError extends RpcError {
+    constructor(message?: string);
+}
+declare class RpcUnavailableError extends RpcError {
+    constructor(message?: string, code?: number);
+}
+declare class RpcCircuitOpenError extends RpcError {
+    constructor(message?: string);
+}
+declare class RpcRateLimitError extends RpcError {
+    readonly retryAfterMs?: number | undefined;
+    constructor(message?: string, retryAfterMs?: number | undefined);
+}
+/**
+ * Errors that should NOT be retried (Deterministic/Validation)
+ */
+declare class RpcValidationError extends RpcError {
+    constructor(message: string, code?: number, data?: unknown);
+}
+
+interface LoadBalancerOptions {
+    strategy: "round-robin" | "failover";
+}
+declare class LoadBalancedRpcProvider implements KaspaRpcClient {
+    private readonly clients;
+    private readonly options;
+    private currentIndex;
+    constructor(clients: KaspaRpcClient[], options?: LoadBalancerOptions);
+    getInfo(): Promise<KaspaNodeInfo>;
+    healthCheck(): Promise<KaspaRpcHealth>;
+    getBalanceByAddress(address: string): Promise<KaspaAddressBalance>;
+    getUtxosByAddress(address: 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>;
+    private withFailover;
+}
+
+interface KaspaNodeInfo {
+    serverVersion?: string | undefined;
+    isSynced?: boolean | undefined;
+    isUtxoIndexed?: boolean | undefined;
+    p2pId?: string | undefined;
+    mempoolSize?: number | undefined;
+    virtualDaaScore?: bigint | undefined;
+    networkId?: string | undefined;
+    raw?: unknown | undefined;
+}
+interface KaspaRpcHealth {
+    readonly endpoint: string;
+    readonly status: RpcHealthState;
+    readonly confidence?: RpcConfidence;
+    readonly score?: number;
+    readonly latencyMs?: number | undefined;
+    readonly lastError?: string | null | undefined;
+    readonly retries?: number | undefined;
+    readonly circuitState?: string | undefined;
+    readonly stale?: boolean | undefined;
+    readonly info?: KaspaNodeInfo | undefined;
+    readonly reachable?: boolean | undefined;
+    readonly successRate?: number | undefined;
+}
+
+interface KaspaAddressBalance {
+    address: string;
+    balanceSompi: bigint;
+    raw?: unknown;
+}
+interface KaspaRpcOutpoint {
+    transactionId: string;
+    index: number;
+}
+interface KaspaRpcUtxo {
+    outpoint: KaspaRpcOutpoint;
+    address: string;
+    amountSompi: bigint;
+    scriptPublicKey?: string;
+    blockDaaScore?: bigint | string;
+    isCoinbase?: boolean;
+    raw?: unknown;
+}
+interface JsonWrpcKaspaClientOptions {
+    rpcUrl: string;
+    timeoutMs?: number;
+}
+interface BlockDagInfo {
+    readonly networkId: NetworkId;
+    readonly virtualDaaScore?: bigint;
+    readonly tipHashes?: readonly string[];
+}
+interface ServerInfo {
+    readonly networkId: NetworkId;
+    readonly serverVersion?: string;
+    readonly isSynced?: boolean;
+}
+interface MempoolEntry {
+    readonly txId: string;
+    readonly acceptedAt?: string | undefined;
+}
+interface KaspaSubmitTransactionResult {
+    transactionId?: string;
+    accepted?: boolean;
+    raw?: unknown;
+}
+interface KaspaRpcClient {
+    getInfo(): Promise<KaspaNodeInfo>;
+    healthCheck(): Promise<KaspaRpcHealth>;
+    getBalanceByAddress(address: string): Promise<KaspaAddressBalance>;
+    getUtxosByAddress(address: 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(): void | Promise<void>;
+}
+declare class JsonWrpcKaspaClient implements KaspaRpcClient {
+    private socket;
+    private readonly rpcUrl;
+    private readonly timeoutMs;
+    private requestId;
+    constructor(options: JsonWrpcKaspaClientOptions);
+    getInfo(): Promise<KaspaNodeInfo>;
+    healthCheck(): Promise<KaspaRpcHealth>;
+    getBalanceByAddress(address: string): Promise<KaspaAddressBalance>;
+    getUtxosByAddress(address: 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>;
+    private safeRequest;
+    private request;
+    private connect;
+}
+declare function mapKaspaNodeInfo(result: any): KaspaNodeInfo;
+declare function mapKaspaAddressBalance(result: any, address: string): KaspaAddressBalance;
+declare function mapKaspaRpcUtxos(result: any, address: string): KaspaRpcUtxo[];
+declare function mapKaspaSubmitTransactionResult(result: any): KaspaSubmitTransactionResult;
+declare class MockKaspaRpcClient implements KaspaRpcClient {
+    private readonly networkId;
+    private utxosByAddress;
+    constructor(networkId?: NetworkId);
+    getInfo(): Promise<KaspaNodeInfo>;
+    healthCheck(): Promise<KaspaRpcHealth>;
+    getBalanceByAddress(address: string): Promise<KaspaAddressBalance>;
+    getUtxosByAddress(address: string): Promise<KaspaRpcUtxo[]>;
+    setUtxos(address: string, utxos: KaspaRpcUtxo[]): void;
+    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 BlockDagInfo, type CircuitBreakerOptions, CircuitState, JsonWrpcKaspaClient, type JsonWrpcKaspaClientOptions, type KaspaAddressBalance, KaspaJsonRpcClient, type KaspaNodeInfo, type KaspaRpcClient, type KaspaRpcHealth, type KaspaRpcOutpoint, type KaspaRpcUtxo, type KaspaSubmitTransactionResult, LoadBalancedRpcProvider, type LoadBalancerOptions, type MempoolEntry, MockKaspaRpcClient, type ResilienceReport, type RetryOptions, RpcCircuitOpenError, type RpcClientOptions, type RpcConfidence, RpcError, type RpcHealthCheckOptions, type RpcHealthResult, type RpcHealthState, RpcRateLimitError, type RpcReadinessWaitOptions, RpcTimeoutError, type RpcTrace, RpcUnavailableError, RpcValidationError, type ServerInfo, calculateConfidence, checkKaspaRpcHealth, classifyRpcError, mapKaspaAddressBalance, mapKaspaNodeInfo, mapKaspaRpcUtxos, mapKaspaSubmitTransactionResult, waitForKaspaRpcReady };

package/dist/index.js

@@ -0,0 +1,935 @@
+// src/index.ts
+import { WebSocket } from "ws";
+
+// src/errors.ts
+var RpcError = class extends Error {
+  constructor(message, code, data, isRetriable = true) {
+    super(message);
+    this.code = code;
+    this.data = data;
+    this.isRetriable = isRetriable;
+    this.name = "RpcError";
+  }
+  code;
+  data;
+  isRetriable;
+};
+var RpcTimeoutError = class extends RpcError {
+  constructor(message = "RPC request timed out") {
+    super(message, void 0, void 0, true);
+    this.name = "RpcTimeoutError";
+  }
+};
+var RpcUnavailableError = class extends RpcError {
+  constructor(message = "RPC service unavailable", code) {
+    super(message, code, void 0, true);
+    this.name = "RpcUnavailableError";
+  }
+};
+var RpcCircuitOpenError = class extends RpcError {
+  constructor(message = "RPC circuit is open (too many failures)") {
+    super(message, void 0, void 0, false);
+    this.name = "RpcCircuitOpenError";
+  }
+};
+var RpcRateLimitError = class extends RpcError {
+  constructor(message = "RPC rate limit exceeded", retryAfterMs) {
+    super(message, 429, void 0, true);
+    this.retryAfterMs = retryAfterMs;
+    this.name = "RpcRateLimitError";
+  }
+  retryAfterMs;
+};
+var RpcValidationError = class extends RpcError {
+  constructor(message, code, data) {
+    super(message, code, data, false);
+    this.name = "RpcValidationError";
+  }
+};
+
+// src/resilience.ts
+function calculateConfidence(metrics) {
+  const issues = [];
+  let score = 100;
+  if (!metrics.reachable) {
+    return { state: "unreachable", confidence: "low", score: 0, issues: ["Endpoint is unreachable"] };
+  }
+  if (metrics.circuitOpen) {
+    score -= 50;
+    issues.push("Circuit breaker is OPEN");
+  }
+  if (metrics.stale) {
+    score -= 40;
+    issues.push("Node appears to be STALE (DAA score not advancing)");
+  }
+  if (metrics.latencyMs !== null) {
+    if (metrics.latencyMs > 1e3) {
+      score -= 20;
+      issues.push(`High latency: ${metrics.latencyMs}ms`);
+    } else if (metrics.latencyMs > 500) {
+      score -= 10;
+      issues.push(`Slightly high latency: ${metrics.latencyMs}ms`);
+    }
+  }
+  if (metrics.successRate < 95) {
+    score -= (100 - metrics.successRate) * 2;
+    issues.push(`Low success rate: ${metrics.successRate.toFixed(1)}%`);
+  }
+  if (metrics.retries > 0) {
+    score -= Math.min(metrics.retries * 5, 20);
+    issues.push(`Request stability issues: ${metrics.retries} retries detected`);
+  }
+  score = Math.max(0, Math.min(100, score));
+  let state = "healthy";
+  if (metrics.stale) state = "stale";
+  else if (score < 50) state = "degraded";
+  else if (score < 90) state = "degraded";
+  let confidence = "high";
+  if (score < 40) confidence = "low";
+  else if (score <= 80) confidence = "medium";
+  return { state, confidence, score, issues };
+}
+function classifyRpcError(error) {
+  const msg = (error.message || String(error)).toLowerCase();
+  const permanentMarkers = [
+    "invalid address",
+    "insufficient funds",
+    "dust",
+    "method not found",
+    "already spent",
+    "invalid transaction",
+    "schema validation"
+  ];
+  if (permanentMarkers.some((m) => msg.includes(m))) {
+    return { retriable: false, category: "validation" };
+  }
+  const transientMarkers = [
+    "timeout",
+    "timed out",
+    "abort",
+    "connection refused",
+    "fetch failed",
+    "429",
+    "503",
+    "too many requests",
+    "circuit open"
+  ];
+  if (transientMarkers.some((m) => msg.includes(m))) {
+    return { retriable: true, category: "network" };
+  }
+  return { retriable: true, category: "unknown" };
+}
+
+// src/json-rpc-client.ts
+import { coreEvents } from "@hardkas/core";
+var CircuitState = /* @__PURE__ */ ((CircuitState2) => {
+  CircuitState2["CLOSED"] = "CLOSED";
+  CircuitState2["OPEN"] = "OPEN";
+  CircuitState2["HALF_OPEN"] = "HALF_OPEN";
+  return CircuitState2;
+})(CircuitState || {});
+var KaspaJsonRpcClient = class {
+  url;
+  timeoutMs;
+  retry;
+  circuitBreaker;
+  fetcher;
+  // State & Metrics
+  circuitState = "CLOSED" /* CLOSED */;
+  failureCount = 0;
+  lastFailureTime = 0;
+  lastError = null;
+  lastLatencyMs = null;
+  totalRequests = 0;
+  successfulRequests = 0;
+  lastDaaScore = null;
+  lastDaaCheckTime = 0;
+  retriesCount = 0;
+  constructor(options) {
+    this.url = options.url || "http://127.0.0.1:18210";
+    this.timeoutMs = options.timeoutMs || 1e4;
+    this.retry = {
+      maxRetries: options.retry?.maxRetries ?? 3,
+      baseDelayMs: options.retry?.baseDelayMs ?? 500,
+      maxDelayMs: options.retry?.maxDelayMs ?? 5e3
+    };
+    this.circuitBreaker = {
+      failureThreshold: options.circuitBreaker?.failureThreshold ?? 5,
+      resetTimeoutMs: options.circuitBreaker?.resetTimeoutMs ?? 3e4
+    };
+    this.fetcher = options.fetcher || globalThis.fetch;
+  }
+  async healthCheck() {
+    this.checkCircuit();
+    const start = Date.now();
+    try {
+      const info = await this.getInfo();
+      const latency = Date.now() - start;
+      let stale = false;
+      const now = Date.now();
+      if (this.lastDaaScore !== null && info.virtualDaaScore !== void 0) {
+        if (info.virtualDaaScore <= this.lastDaaScore && now - this.lastDaaCheckTime > 3e4) {
+          stale = true;
+        }
+      }
+      if (info.virtualDaaScore !== void 0) {
+        this.lastDaaScore = info.virtualDaaScore;
+        this.lastDaaCheckTime = now;
+      }
+      const resilience = calculateConfidence({
+        latencyMs: latency,
+        successRate: this.getSuccessRate(),
+        retries: this.retriesCount,
+        stale,
+        reachable: true,
+        circuitOpen: this.circuitState === "OPEN" /* OPEN */
+      });
+      coreEvents.normalizeAndEmit({
+        kind: "rpc.health",
+        endpoint: this.url,
+        state: resilience.state,
+        score: resilience.score,
+        latencyMs: latency,
+        issues: resilience.issues
+      });
+      return {
+        reachable: true,
+        rpcUrl: this.url,
+        status: resilience.state,
+        info,
+        latencyMs: latency,
+        lastError: this.lastError,
+        successRate: this.getSuccessRate(),
+        circuitState: this.circuitState,
+        score: resilience.score,
+        confidence: resilience.confidence,
+        retries: this.retriesCount,
+        stale
+      };
+    } catch (e) {
+      const resilience = calculateConfidence({
+        latencyMs: null,
+        successRate: this.getSuccessRate(),
+        retries: this.retriesCount,
+        stale: false,
+        reachable: false,
+        circuitOpen: this.circuitState === "OPEN" /* OPEN */
+      });
+      coreEvents.normalizeAndEmit({
+        kind: "rpc.health",
+        endpoint: this.url,
+        state: resilience.state,
+        score: resilience.score,
+        latencyMs: -1,
+        issues: resilience.issues
+      });
+      return {
+        reachable: false,
+        rpcUrl: this.url,
+        status: "unavailable",
+        error: e.message,
+        lastError: this.lastError || e.message,
+        successRate: this.getSuccessRate(),
+        circuitState: this.circuitState,
+        confidence: resilience.confidence,
+        score: resilience.score,
+        retries: this.retriesCount
+      };
+    }
+  }
+  async getInfo() {
+    const data = await this.callRpc("getInfoRequest");
+    const info = {
+      serverVersion: String(data.serverVersion),
+      networkId: String(data.networkId),
+      isSynced: Boolean(data.isSynced)
+    };
+    if (data.virtualDaaScore !== void 0) info.virtualDaaScore = BigInt(data.virtualDaaScore);
+    if (data.mempoolSize !== void 0) info.mempoolSize = Number(data.mempoolSize);
+    return info;
+  }
+  async getBlockDagInfo() {
+    const data = await this.callRpc("getBlockDagInfoRequest");
+    const dagInfo = {
+      networkId: data.networkId,
+      tipHashes: data.tipHashes,
+      ...data.virtualDaaScore !== void 0 ? { virtualDaaScore: BigInt(data.virtualDaaScore) } : {}
+    };
+    return dagInfo;
+  }
+  async getUtxosByAddress(address) {
+    const data = await this.callRpc("getUtxosByAddressesRequest", { addresses: [address] });
+    const entries = data.entries || [];
+    return entries.map((e) => ({
+      address: e.address,
+      outpoint: {
+        transactionId: e.outpoint.transactionId,
+        index: e.outpoint.index
+      },
+      amountSompi: BigInt(e.utxoEntry.amount),
+      scriptPublicKey: e.utxoEntry.scriptPublicKey,
+      blockDaaScore: BigInt(e.utxoEntry.blockDaaScore),
+      isCoinbase: e.utxoEntry.isCoinbase
+    }));
+  }
+  async getBalanceByAddress(address) {
+    const data = await this.callRpc("getBalanceByAddressRequest", { address });
+    return {
+      address: data.address,
+      balanceSompi: BigInt(data.balance)
+    };
+  }
+  async getMempoolEntry(txId) {
+    try {
+      const result = await this.callRpc("getMempoolEntryRequest", { txId, includeOrphanPool: true });
+      return {
+        txId,
+        acceptedAt: String(result.entry.acceptedAt)
+      };
+    } catch (e) {
+      return null;
+    }
+  }
+  async getTransaction(txId) {
+    try {
+      const result = await this.callRpc("getTransactionRequest", { transactionId: txId });
+      return result;
+    } catch (e) {
+      return null;
+    }
+  }
+  async submitTransaction(rawTx) {
+    const result = await this.callRpc("submitTransactionRequest", { transaction: rawTx });
+    return { transactionId: result.transactionId };
+  }
+  async getServerInfo() {
+    const info = await this.getInfo();
+    const result = {
+      networkId: info.networkId
+    };
+    if (info.serverVersion !== void 0) result.serverVersion = info.serverVersion;
+    if (info.isSynced !== void 0) result.isSynced = info.isSynced;
+    return result;
+  }
+  async close() {
+  }
+  async callRpc(method, params = {}) {
+    return this.withResilience(() => this.internalCall(method, params));
+  }
+  async withResilience(fn) {
+    this.checkCircuit();
+    if (this.circuitState === "OPEN" /* OPEN */) {
+      throw new RpcCircuitOpenError();
+    }
+    let lastErr;
+    for (let attempt = 0; attempt <= this.retry.maxRetries; attempt++) {
+      const start = Date.now();
+      try {
+        this.totalRequests++;
+        const result = await fn();
+        this.onSuccess(Date.now() - start);
+        return result;
+      } catch (e) {
+        this.onFailure(e);
+        lastErr = e;
+        const isRetriable = e instanceof RpcError ? e.isRetriable : true;
+        coreEvents.normalizeAndEmit({
+          kind: "rpc.error",
+          endpoint: this.url,
+          error: e.message,
+          retriable: isRetriable
+        });
+        if (attempt < this.retry.maxRetries && isRetriable) {
+          this.retriesCount++;
+        }
+        if (e instanceof RpcError && !e.isRetriable) {
+          throw e;
+        }
+        if (this.isDeterministicError(e)) {
+          throw new RpcValidationError(e.message, e.code, e.data);
+        }
+        if (attempt === this.retry.maxRetries) break;
+        const delay = Math.min(
+          this.retry.baseDelayMs * Math.pow(2, attempt),
+          this.retry.maxDelayMs
+        );
+        const jitter = Math.random() * 0.1 * delay;
+        await new Promise((resolve) => setTimeout(resolve, delay + jitter));
+      }
+    }
+    throw lastErr;
+  }
+  async internalCall(method, params) {
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await this.fetcher(this.url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: Date.now(),
+          method,
+          params
+        }),
+        signal: controller.signal
+      });
+      clearTimeout(id);
+      if (response.status === 429) {
+        throw new RpcRateLimitError();
+      }
+      if (!response.ok) {
+        throw new RpcUnavailableError(`HTTP Error ${response.status}`, response.status);
+      }
+      const body = await response.json();
+      if (body.error) {
+        throw new RpcError(body.error.message, body.error.code, body.error.data);
+      }
+      return body.result;
+    } catch (e) {
+      clearTimeout(id);
+      if (e.name === "AbortError") throw new RpcTimeoutError();
+      throw e;
+    }
+  }
+  checkCircuit() {
+    if (this.circuitState === "OPEN" /* OPEN */) {
+      const now = Date.now();
+      if (now - this.lastFailureTime > this.circuitBreaker.resetTimeoutMs) {
+        this.circuitState = "HALF_OPEN" /* HALF_OPEN */;
+      }
+    }
+  }
+  onSuccess(latency) {
+    this.lastLatencyMs = latency;
+    this.successfulRequests++;
+    this.failureCount = 0;
+    this.circuitState = "CLOSED" /* CLOSED */;
+  }
+  onFailure(e) {
+    this.lastError = e.message;
+    if (e instanceof RpcValidationError || e instanceof RpcError && !e.isRetriable) {
+      return;
+    }
+    this.failureCount++;
+    this.lastFailureTime = Date.now();
+    if (this.failureCount >= this.circuitBreaker.failureThreshold) {
+      this.circuitState = "OPEN" /* OPEN */;
+    }
+  }
+  isDeterministicError(e) {
+    const msg = (e.message || "").toLowerCase();
+    const deterministicMarkers = [
+      "invalid address",
+      "insufficient funds",
+      "schema validation",
+      "artifact hash mismatch",
+      "simulation error",
+      "dust",
+      "missing required",
+      "outpoint already spent",
+      "method not found"
+    ];
+    return deterministicMarkers.some((marker) => msg.includes(marker));
+  }
+  getSuccessRate() {
+    if (this.totalRequests === 0) return 100;
+    return this.successfulRequests / this.totalRequests * 100;
+  }
+};
+
+// src/health.ts
+async function checkKaspaRpcHealth(options) {
+  const url = options?.url || "http://127.0.0.1:18210";
+  const client = new KaspaJsonRpcClient({ url, timeoutMs: options?.timeoutMs });
+  const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    const health = await client.healthCheck();
+    return {
+      endpoint: url,
+      status: health.status,
+      ready: health.status === "healthy" || health.status === "degraded",
+      checkedAt,
+      ...health.latencyMs !== void 0 ? { latencyMs: health.latencyMs } : {},
+      ...health.info?.networkId !== void 0 ? { networkId: health.info.networkId } : {},
+      ...health.info?.virtualDaaScore !== void 0 ? { virtualDaaScore: health.info.virtualDaaScore.toString() } : {},
+      ...health.info?.serverVersion !== void 0 ? { serverVersion: health.info.serverVersion } : {},
+      ...health.info?.isSynced !== void 0 ? { isSynced: health.info.isSynced } : {},
+      lastError: health.lastError,
+      ...health.retries !== void 0 ? { retries: health.retries } : {},
+      ...health.circuitState !== void 0 ? { circuitState: health.circuitState } : {},
+      stale: health.stale
+    };
+  } catch (e) {
+    return {
+      endpoint: url,
+      status: "unreachable",
+      ready: false,
+      checkedAt,
+      error: e.message,
+      lastError: e.message
+    };
+  }
+}
+async function waitForKaspaRpcReady(options) {
+  const intervalMs = options?.intervalMs || 1e3;
+  const maxWaitMs = options?.maxWaitMs || 6e4;
+  const start = Date.now();
+  let lastResult;
+  while (Date.now() - start < maxWaitMs) {
+    lastResult = await checkKaspaRpcHealth({
+      url: options?.url,
+      timeoutMs: options?.timeoutMs
+    });
+    if (lastResult.ready) {
+      return lastResult;
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  return lastResult || {
+    endpoint: options?.url || "http://127.0.0.1:18210",
+    status: "unreachable",
+    ready: false,
+    checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    error: "Timed out waiting for RPC to be ready"
+  };
+}
+
+// src/provider.ts
+var LoadBalancedRpcProvider = class {
+  constructor(clients, options = { strategy: "failover" }) {
+    this.clients = clients;
+    this.options = options;
+    if (clients.length === 0) {
+      throw new Error("LoadBalancedRpcProvider requires at least one client");
+    }
+  }
+  clients;
+  options;
+  currentIndex = 0;
+  async getInfo() {
+    return this.withFailover((c) => c.getInfo());
+  }
+  async healthCheck() {
+    const healths = await Promise.all(this.clients.map((c) => c.healthCheck()));
+    const primaryHealth = healths[this.currentIndex];
+    const allHealthy = healths.every((h) => h.status === "healthy");
+    const anyHealthy = healths.some((h) => h.status === "healthy" || h.status === "degraded");
+    return {
+      endpoint: `LoadBalancedProvider(${this.clients.length} nodes)`,
+      status: allHealthy ? "healthy" : anyHealthy ? "degraded" : "unreachable",
+      latencyMs: primaryHealth.latencyMs,
+      lastError: primaryHealth.lastError,
+      retries: healths.reduce((sum, h) => sum + (h.retries || 0), 0),
+      circuitState: primaryHealth.circuitState,
+      stale: healths.some((h) => h.stale),
+      info: primaryHealth.info,
+      reachable: anyHealthy
+    };
+  }
+  async getBalanceByAddress(address) {
+    return this.withFailover((c) => c.getBalanceByAddress(address));
+  }
+  async getUtxosByAddress(address) {
+    return this.withFailover((c) => c.getUtxosByAddress(address));
+  }
+  async submitTransaction(rawTransaction) {
+    return this.withFailover((c) => c.submitTransaction(rawTransaction));
+  }
+  async getMempoolEntry(txId) {
+    return this.withFailover((c) => c.getMempoolEntry(txId));
+  }
+  async getTransaction(txId) {
+    return this.withFailover((c) => c.getTransaction(txId));
+  }
+  async getBlockDagInfo() {
+    return this.withFailover((c) => c.getBlockDagInfo());
+  }
+  async getServerInfo() {
+    return this.withFailover((c) => c.getServerInfo());
+  }
+  async close() {
+    await Promise.all(this.clients.map((c) => c.close()));
+  }
+  async withFailover(fn) {
+    let lastError;
+    for (let i = 0; i < this.clients.length; i++) {
+      const index = (this.currentIndex + i) % this.clients.length;
+      const client = this.clients[index];
+      try {
+        const result = await fn(client);
+        if (this.options.strategy === "round-robin") {
+          this.currentIndex = (index + 1) % this.clients.length;
+        } else {
+          this.currentIndex = index;
+        }
+        return result;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw lastError || new RpcUnavailableError("All RPC endpoints failed");
+  }
+};
+
+// src/index.ts
+var JsonWrpcKaspaClient = class {
+  socket = null;
+  rpcUrl;
+  timeoutMs;
+  requestId = 1;
+  constructor(options) {
+    this.rpcUrl = options.rpcUrl;
+    this.timeoutMs = options.timeoutMs ?? 1e4;
+  }
+  async getInfo() {
+    const response = await this.safeRequest(["GetInfo", "getInfo", "get_info", "getInfoRequest"]);
+    const info = mapKaspaNodeInfo(response);
+    if (info.virtualDaaScore === void 0) {
+      try {
+        const dagResponse = await this.safeRequest(["GetBlockDagInfo", "getBlockDagInfo", "get_block_dag_info"]);
+        const dagData = dagResponse?.params || dagResponse;
+        if (dagData?.virtualDaaScore !== void 0) {
+          info.virtualDaaScore = BigInt(dagData.virtualDaaScore);
+        }
+      } catch (e) {
+      }
+    }
+    return info;
+  }
+  async healthCheck() {
+    try {
+      const info = await this.getInfo();
+      return {
+        endpoint: this.rpcUrl,
+        status: "healthy",
+        info,
+        reachable: true
+      };
+    } catch (error) {
+      return {
+        endpoint: this.rpcUrl,
+        status: "unreachable",
+        lastError: error instanceof Error ? error.message : String(error),
+        reachable: false
+      };
+    }
+  }
+  async getBalanceByAddress(address) {
+    const response = await this.safeRequest(
+      ["GetBalancesByAddresses", "getBalancesByAddresses", "get_balances_by_addresses", "GetBalanceByAddress", "getBalanceByAddress", "get_balance_by_address"],
+      { addresses: [address], address }
+    );
+    return mapKaspaAddressBalance(response, address);
+  }
+  async getUtxosByAddress(address) {
+    const response = await this.safeRequest(
+      ["GetUtxosByAddresses", "getUtxosByAddresses", "get_utxos_by_addresses", "GetUtxosByAddress", "getUtxosByAddress", "get_utxos_by_address"],
+      { addresses: [address], address }
+    );
+    return mapKaspaRpcUtxos(response, address);
+  }
+  async submitTransaction(rawTransaction) {
+    const response = await this.safeRequest(
+      ["SubmitTransaction", "submitTransaction", "submit_transaction"],
+      { transaction: rawTransaction, transactionHex: rawTransaction, rawTransaction }
+    );
+    return mapKaspaSubmitTransactionResult(response);
+  }
+  async getMempoolEntry(txId) {
+    try {
+      const response = await this.safeRequest(
+        ["getMempoolEntryRequest", "getMempoolEntry"],
+        { txId, transactionId: txId }
+      );
+      if (!response) return null;
+      return {
+        txId,
+        acceptedAt: response.acceptedAt || response.accepted_at
+      };
+    } catch (e) {
+      return null;
+    }
+  }
+  async getTransaction(txId) {
+    try {
+      const response = await this.safeRequest(
+        ["getTransactionRequest", "getTransaction"],
+        { txId, transactionId: txId }
+      );
+      return response;
+    } catch (e) {
+      return null;
+    }
+  }
+  async getBlockDagInfo() {
+    const info = await this.getInfo();
+    const result = {
+      networkId: info.networkId || "unknown",
+      tipHashes: []
+    };
+    if (info.virtualDaaScore !== void 0) {
+      result.virtualDaaScore = BigInt(info.virtualDaaScore);
+    }
+    return result;
+  }
+  async getServerInfo() {
+    const info = await this.getInfo();
+    const result = {
+      networkId: info.networkId || "unknown"
+    };
+    if (info.serverVersion !== void 0) result.serverVersion = info.serverVersion;
+    if (info.isSynced !== void 0) result.isSynced = info.isSynced;
+    return result;
+  }
+  async close() {
+    if (this.socket) {
+      this.socket.close();
+      this.socket = null;
+    }
+  }
+  async safeRequest(methods, params = {}) {
+    let lastError = null;
+    for (const method of methods) {
+      try {
+        let actualParams = params;
+        const lowerMethod = method.toLowerCase();
+        if (lowerMethod.includes("addresses") || lowerMethod.endsWith("s")) {
+          if (params.address && !params.addresses) {
+            actualParams = { addresses: [params.address] };
+          } else if (params.addresses) {
+            actualParams = { addresses: params.addresses };
+          }
+        } else if (params.addresses && !params.address) {
+          actualParams = { address: params.addresses[0] };
+        } else if (params.address) {
+          actualParams = { address: params.address };
+        }
+        try {
+          return await this.request(method, actualParams);
+        } catch (e) {
+          if (e.message?.includes("deserialization")) {
+            const arrayParams = Object.values(actualParams);
+            return await this.request(method, arrayParams);
+          }
+          throw e;
+        }
+      } catch (error) {
+        lastError = error;
+        continue;
+      }
+    }
+    throw lastError ?? new Error(`Methods failed: ${methods.join(", ")}`);
+  }
+  async request(method, params = {}) {
+    const ws = await this.connect();
+    const id = this.requestId++;
+    const payload = JSON.stringify({
+      id,
+      method,
+      params
+    });
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        cleanup();
+        reject(new Error(`RPC request timed out after ${this.timeoutMs}ms`));
+      }, this.timeoutMs);
+      const onMessage = (data) => {
+        try {
+          const raw = data.toString();
+          const response = JSON.parse(raw);
+          if (String(response.id) === String(id)) {
+            cleanup();
+            if (response.error) {
+              const err = response.error;
+              const msg = err.message || (typeof err === "string" ? err : JSON.stringify(err));
+              reject(new Error(msg));
+            } else {
+              resolve(response.result !== void 0 ? response.result : response.params);
+            }
+          }
+        } catch (e) {
+        }
+      };
+      const onError = (err) => {
+        cleanup();
+        reject(err);
+      };
+      const cleanup = () => {
+        clearTimeout(timeout);
+        ws.removeListener("message", onMessage);
+        ws.removeListener("error", onError);
+      };
+      ws.on("message", onMessage);
+      ws.on("error", onError);
+      ws.send(payload);
+    });
+  }
+  async connect() {
+    if (this.socket && this.socket.readyState === WebSocket.OPEN) {
+      return this.socket;
+    }
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(this.rpcUrl);
+      const timeout = setTimeout(() => {
+        ws.close();
+        reject(new Error(`Cannot connect to Kaspa RPC at ${this.rpcUrl}. Connection timed out.`));
+      }, this.timeoutMs);
+      ws.on("open", () => {
+        clearTimeout(timeout);
+        this.socket = ws;
+        resolve(ws);
+      });
+      ws.on("error", (err) => {
+        clearTimeout(timeout);
+        let message = `Cannot connect to Kaspa RPC at ${this.rpcUrl}. Is kaspad running with --rpclisten-json?`;
+        if (err.code === "ECONNREFUSED") {
+          message = `Connection refused at ${this.rpcUrl}. Ensure kaspad is running and --rpclisten-json is enabled.`;
+        }
+        reject(new Error(message));
+      });
+    });
+  }
+};
+function mapKaspaNodeInfo(result) {
+  if (!result) return { raw: result };
+  const info = {
+    serverVersion: result.serverVersion || result.server_version,
+    isSynced: result.isSynced !== void 0 ? result.isSynced : result.is_synced,
+    isUtxoIndexed: result.isUtxoIndexed !== void 0 ? result.isUtxoIndexed : result.is_utxo_indexed,
+    p2pId: result.p2pId || result.p2p_id,
+    mempoolSize: result.mempoolSize !== void 0 ? result.mempoolSize : result.mempool_size,
+    networkId: result.networkId || result.network_id,
+    raw: result
+  };
+  const score = result.virtualDaaScore !== void 0 ? result.virtualDaaScore : result.virtual_daa_score !== void 0 ? result.virtual_daa_score : result.params?.virtualDaaScore;
+  if (score !== void 0) {
+    info.virtualDaaScore = BigInt(score);
+  }
+  return info;
+}
+function mapKaspaAddressBalance(result, address) {
+  if (!result) return { address, balanceSompi: 0n, raw: result };
+  let entry = result;
+  if (Array.isArray(result)) {
+    entry = result.find((e) => (e.address || e.addressString || e.address_string) === address) || result[0];
+  } else if (result.entries && Array.isArray(result.entries)) {
+    entry = result.entries.find((e) => (e.address || e.addressString || e.address_string) === address) || result.entries[0];
+  }
+  const balance = entry.balance !== void 0 ? entry.balance : entry.balanceSompi !== void 0 ? entry.balanceSompi : entry.amount;
+  const balanceSompi = balance !== void 0 ? BigInt(balance) : 0n;
+  return {
+    address,
+    balanceSompi,
+    raw: result
+  };
+}
+function mapKaspaRpcUtxos(result, address) {
+  if (!result) return [];
+  let entries = null;
+  if (Array.isArray(result)) {
+    entries = result;
+  } else if (result.result && Array.isArray(result.result)) {
+    entries = result.result;
+  } else if (result.result && (result.result.entries || result.result.utxos)) {
+    entries = result.result.entries || result.result.utxos;
+  } else {
+    entries = result.entries || result.utxos || result;
+  }
+  if (!Array.isArray(entries)) return [];
+  return entries.map((entry) => {
+    const utxoEntry = entry.utxoEntry || entry.utxo_entry || entry.utxo || entry;
+    const outpoint = entry.outpoint || entry;
+    return {
+      outpoint: {
+        transactionId: outpoint.transactionId || outpoint.transaction_id || outpoint.txId || outpoint.tx_id || outpoint.transaction_hash || "",
+        index: Number(outpoint.index !== void 0 ? outpoint.index : outpoint.outputIndex !== void 0 ? outpoint.outputIndex : outpoint.output_index)
+      },
+      address: entry.address || address,
+      amountSompi: BigInt(utxoEntry.amount || utxoEntry.amountSompi || utxoEntry.amount_sompi || 0),
+      scriptPublicKey: utxoEntry.scriptPublicKey || utxoEntry.script_public_key,
+      blockDaaScore: utxoEntry.blockDaaScore || utxoEntry.block_daa_score,
+      isCoinbase: utxoEntry.isCoinbase || utxoEntry.is_coinbase,
+      raw: entry
+    };
+  });
+}
+function mapKaspaSubmitTransactionResult(result) {
+  if (!result) return { raw: result };
+  return {
+    transactionId: result.transactionId || result.transaction_id || result.txId || result.tx_id,
+    accepted: result.accepted !== void 0 ? result.accepted : result.isAccepted || result.success,
+    raw: result
+  };
+}
+var MockKaspaRpcClient = class {
+  constructor(networkId = "simnet") {
+    this.networkId = networkId;
+  }
+  networkId;
+  utxosByAddress = /* @__PURE__ */ new Map();
+  async getInfo() {
+    return { networkId: this.networkId, serverVersion: "mock", isSynced: true, virtualDaaScore: 0n, raw: {} };
+  }
+  async healthCheck() {
+    return {
+      endpoint: "mock://local",
+      status: "healthy",
+      info: await this.getInfo(),
+      reachable: true
+    };
+  }
+  async getBalanceByAddress(address) {
+    const utxos = this.utxosByAddress.get(address) || [];
+    const balanceSompi = utxos.reduce((acc, u) => acc + u.amountSompi, 0n);
+    return { address, balanceSompi };
+  }
+  async getUtxosByAddress(address) {
+    return this.utxosByAddress.get(address) || [];
+  }
+  setUtxos(address, utxos) {
+    this.utxosByAddress.set(address, utxos);
+  }
+  async submitTransaction(rawTransaction) {
+    return {
+      transactionId: "mock-txid",
+      accepted: true,
+      raw: { rawTransaction }
+    };
+  }
+  async getMempoolEntry(_txId) {
+    return null;
+  }
+  async getTransaction(_txId) {
+    return null;
+  }
+  async getBlockDagInfo() {
+    return { networkId: this.networkId, virtualDaaScore: 0n };
+  }
+  async getServerInfo() {
+    return { networkId: this.networkId, serverVersion: "mock", isSynced: true };
+  }
+  async close() {
+  }
+};
+export {
+  CircuitState,
+  JsonWrpcKaspaClient,
+  KaspaJsonRpcClient,
+  LoadBalancedRpcProvider,
+  MockKaspaRpcClient,
+  RpcCircuitOpenError,
+  RpcError,
+  RpcRateLimitError,
+  RpcTimeoutError,
+  RpcUnavailableError,
+  RpcValidationError,
+  calculateConfidence,
+  checkKaspaRpcHealth,
+  classifyRpcError,
+  mapKaspaAddressBalance,
+  mapKaspaNodeInfo,
+  mapKaspaRpcUtxos,
+  mapKaspaSubmitTransactionResult,
+  waitForKaspaRpcReady
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@hardkas/kaspa-rpc",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "ws": "^8.18.0",
+    "@hardkas/core": "0.1.0",
+    "@hardkas/tx-builder": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "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/kaspa-rpc"
+  },
+  "bugs": {
+    "url": "https://github.com/jrodrg92/Hardkas/issues"
+  },
+  "homepage": "https://github.com/jrodrg92/Hardkas/tree/main/packages/kaspa-rpc#readme",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}