solana-resilience-kit 0.1.0 → 1.0.1

package/README.md

@@ -1,5 +1,10 @@
 # solana-resilience-kit
 
+[![npm version](https://img.shields.io/npm/v/solana-resilience-kit.svg)](https://www.npmjs.com/package/solana-resilience-kit)
+[![npm downloads](https://img.shields.io/npm/dm/solana-resilience-kit.svg)](https://www.npmjs.com/package/solana-resilience-kit)
+[![types included](https://img.shields.io/npm/types/solana-resilience-kit.svg)](https://www.npmjs.com/package/solana-resilience-kit)
+[![license: MIT](https://img.shields.io/npm/l/solana-resilience-kit.svg)](./LICENSE)
+
 A vendor-neutral, **client-side resilience and observability layer for Solana dApps**, built on `@solana/kit` (web3.js v2). It unifies the reliability work that is today either left as a do-it-yourself recipe by the official SDK or locked inside a single provider: health-aware multi-RPC failover, a correct transaction send/confirm state machine, simulate-based fee/CU estimation, Jito/MEV routing with automatic RPC fallback, and standardized OpenTelemetry/Datadog telemetry — behind one clean API that works on top of any set of providers.
 
 > **🔬 Live demo: [solana-rpc-sdk.pages.dev](https://solana-rpc-sdk.pages.dev)** — the *RPC Resilience Lab* runs the real SDK in your browser: inject faults against the simulation harness, flip the kit on/off to compare landing rates, or connect a wallet and land a real transaction on devnet. ([source](./demo))
@@ -7,7 +12,7 @@ A vendor-neutral, **client-side resilience and observability layer for Solana dA
 - **Vendor-neutral** — works with any RPC provider; no gateway, no proprietary key required.
 - **Correct by construction** — implements the send/confirm semantics most clients get wrong (no double-charge, bounded by `lastValidBlockHeight`).
 - **Built on `@solana/kit`** — the pool *is* a kit `RpcTransport`, so it drops into existing kit code.
-- **Deterministically tested** — an in-memory fault-injection cluster reproduces drops, expiry, 429s, desync, and MEV failures; 74 specs, coverage-gated.
+- **Deterministically tested** — an in-memory fault-injection cluster reproduces drops, expiry, 429s, desync, and MEV failures; 102 specs, coverage-gated.
 - **Observable** — first-class client telemetry to OpenTelemetry / Datadog.
 
 ## Problem
@@ -61,7 +66,7 @@ The decisive finding: every robust mitigation today is **either a DIY recipe in
 | `JitoRouter` + `TipEstimator` | `src/jito/*` | Bundle routing, dynamic tips, automatic RPC fallback |
 | `OtelMetrics` / `InMemoryMetrics` | `src/observability/metrics.ts` | Client telemetry (latency, failures, slot lag, landings) → OTel/Datadog |
 | `ResilientWalletAdapter` | `src/wallet/adapter.ts` | Wallet-signed transactions through the resilient pipeline |
-| `Diagnostics` | `src/cli/diagnose.ts` | Probe provider health; explain why a transaction did or didn't land |
+| `Diagnostics` + `solana-resilience-diagnose` CLI | `src/cli/diagnose.ts`, `src/cli/index.ts` | Probe provider health; explain why a transaction did or didn't land (see [Diagnostics CLI](#diagnostics-cli)) |
 
 ## Architecture
 
@@ -132,6 +137,61 @@ const result = await sender.sendAndConfirm({
 // resend error on an already-landed tx as non-terminal.
 ```
 
+## Diagnostics CLI
+
+The package ships an executable, `solana-resilience-diagnose`, built on the same
+`Diagnostics` core (`src/cli/diagnose.ts`). It answers the two questions an
+operator asks when a Solana dApp misbehaves — *which of my providers is healthy
+and freshest?* and *did this transaction land, expire, or is it still pending?* —
+without writing any code. Run it with `npx` (no install) or from a dependency's
+`node_modules/.bin`:
+
+```bash
+# Probe provider health across one or more endpoints (reuses the pool's own
+# slot-freshness ranking, so "freshest" matches what routing would pick):
+npx solana-resilience-diagnose probe \
+  --rpc https://api.mainnet-beta.solana.com \
+  --rpc https://my-backup.rpc
+```
+
+```
+ENDPOINT                            HEALTH  SLOT       LATENCY  FRESHEST
+https://api.mainnet-beta.solana.com ok      287654812  142ms    *
+https://my-backup.rpc               down    -          19ms
+
+Freshest: https://api.mainnet-beta.solana.com  ·  1/2 healthy.
+  https://my-backup.rpc: fetch failed
+```
+
+```bash
+# Explain a transaction's outcome point-in-time (no polling loop): it compares
+# the current signature status and block height against lastValidBlockHeight —
+# the canonical Solana rule — and never re-signs.
+npx solana-resilience-diagnose explain \
+  --rpc https://api.mainnet-beta.solana.com \
+  --sig 5xRe...your-signature \
+  --lvbh 287654321
+```
+
+```
+Signature: 5xRe...your-signature
+Verdict: EXPIRED
+block height 287654400 exceeded lastValidBlockHeight 287654321; the blockhash
+expired before the transaction landed (silent drop or congestion). Rebuild with
+a fresh blockhash — do NOT re-sign the same one.
+```
+
+| Flag | Command | Meaning |
+|---|---|---|
+| `--rpc <url>` | both | RPC endpoint URL. Repeat for `probe`; exactly one for `explain`. Accepts `--rpc=<url>` too. |
+| `--sig <sig>` | `explain` | Transaction signature to explain. |
+| `--lvbh <n>` | `explain` | `lastValidBlockHeight` the transaction was built against. |
+
+**Exit codes:** `0` success · `1` a substantive failure (no healthy endpoint, or an
+expired transaction) · `2` a usage error. Run with no command, `help`, or
+`--help` to print usage. The argv parser is a pure, network-free function and is
+unit-tested in isolation (`test/cli/argv.test.ts`).
+
 ## Testing your own code against the fault harness
 
 The deterministic Solana cluster simulator the SDK is tested with is shipped as a
@@ -173,7 +233,7 @@ Solana's failure modes — silent drops, blockhash expiry, 429s, lagging-node de
 - **Injected `sleep`.** Time-based loops take a `sleep` dependency; tests pass one that advances the mock clock, so the whole state machine runs instantly and deterministically.
 
 ```bash
-npm test          # full suite (harness + all modules), 74 specs
+npm test          # full suite (harness + all modules), 102 specs
 npm run test:cov  # coverage with the thresholds enforced
 npm run typecheck # tsc --noEmit
 ```

package/dist/cli/index.d.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import type { Rpc, SolanaRpcApi } from "@solana/kit";
+import { SdkError } from "../errors.js";
+import { Diagnostics } from "./diagnose.js";
+import type { ProbeReport, TxDiagnosis } from "./diagnose.js";
+/** A malformed invocation (unknown command, missing/invalid flag). Message carries usage text. */
+export declare class CliUsageError extends SdkError {
+}
+export interface ProbeCommand {
+    command: "probe";
+    rpcUrls: string[];
+}
+export interface ExplainCommand {
+    command: "explain";
+    rpcUrl: string;
+    signature: string;
+    lastValidBlockHeight: bigint;
+}
+export type ParsedCommand = ProbeCommand | ExplainCommand;
+export declare const USAGE = "solana-resilience-diagnose \u2014 probe RPC health and explain transaction outcomes\n\nUsage:\n  solana-resilience-diagnose probe   --rpc <url> [--rpc <url> ...]\n  solana-resilience-diagnose explain --rpc <url> --sig <signature> --lvbh <lastValidBlockHeight>\n\nCommands:\n  probe     Probe each endpoint's slot / latency / health and report the freshest.\n  explain   Point-in-time verdict (confirmed | expired | pending) for one signature.\n\nFlags:\n  --rpc <url>     RPC endpoint URL. Repeat for probe; exactly one for explain.\n  --sig <sig>     Transaction signature to explain.\n  --lvbh <n>      lastValidBlockHeight the transaction was built against.\n\nExamples:\n  solana-resilience-diagnose probe --rpc https://api.mainnet-beta.solana.com --rpc https://my-backup.rpc\n  solana-resilience-diagnose explain --rpc https://api.mainnet-beta.solana.com --sig 5xRe... --lvbh 287654321";
+/**
+ * Pure argv parser. Accepts argv WITHOUT the `node script` prefix (i.e.
+ * `process.argv.slice(2)`). Supports `--flag value` and `--flag=value`. Throws
+ * {@link CliUsageError} (with help text) on anything malformed. No I/O.
+ */
+export declare function parseArgs(argv: string[]): ParsedCommand;
+/** Render a {@link ProbeReport} as an aligned text table plus a summary line. */
+export declare function formatProbeReport(report: ProbeReport): string;
+/** Render an {@link TxDiagnosis} as a human verdict. */
+export declare function formatDiagnosis(signature: string, diag: TxDiagnosis): string;
+export interface CliDeps {
+    /** Build a kit RPC from a URL. Defaults to `createSolanaRpc`. */
+    createRpc?: (url: string) => Rpc<SolanaRpcApi>;
+    /** Sink for output lines. Defaults to `console.log`. */
+    log?: (line: string) => void;
+    /** Override the diagnostics core (tests inject a shared HealthMonitor here). */
+    diagnostics?: Diagnostics;
+}
+/**
+ * Execute one parsed command. Returns the process exit code. All side effects
+ * (RPC, stdout) go through {@link CliDeps}, so tests run it network-free.
+ */
+export declare function run(argv: string[], deps?: CliDeps): Promise<number>;

package/dist/cli/index.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * solana-resilience-diagnose — the executable CLI over the {@link Diagnostics} core.
+ *
+ * Two commands map 1:1 to the two questions an operator asks when a Solana dApp
+ * misbehaves:
+ *
+ *   probe   --rpc <url> [--rpc <url> ...]            → which providers are healthy, and which is freshest?
+ *   explain --rpc <url> --sig <signature> --lvbh <n> → did this tx land, expire, or is it still pending?
+ *
+ * Layering: {@link parseArgs} is a PURE, network-free function (turns argv into a
+ * typed command or throws {@link CliUsageError}); {@link formatProbeReport} /
+ * {@link formatDiagnosis} are pure renderers; {@link run} wires kit RPC + stdout
+ * through injectable deps so it stays deterministic under the harness. Only the
+ * process bootstrap at the very bottom touches process.argv / real RPC, and is
+ * integration-only — nothing else executes at import time.
+ *
+ * Exit codes: 0 success · 1 a substantive failure (no healthy endpoint / expired
+ * tx) · 2 a usage error.
+ */
+import { createSolanaRpc } from "@solana/kit";
+import { pathToFileURL } from "node:url";
+import { SdkError } from "../errors.js";
+import { Diagnostics } from "./diagnose.js";
+/** A malformed invocation (unknown command, missing/invalid flag). Message carries usage text. */
+export class CliUsageError extends SdkError {
+}
+export const USAGE = `solana-resilience-diagnose — probe RPC health and explain transaction outcomes
+
+Usage:
+  solana-resilience-diagnose probe   --rpc <url> [--rpc <url> ...]
+  solana-resilience-diagnose explain --rpc <url> --sig <signature> --lvbh <lastValidBlockHeight>
+
+Commands:
+  probe     Probe each endpoint's slot / latency / health and report the freshest.
+  explain   Point-in-time verdict (confirmed | expired | pending) for one signature.
+
+Flags:
+  --rpc <url>     RPC endpoint URL. Repeat for probe; exactly one for explain.
+  --sig <sig>     Transaction signature to explain.
+  --lvbh <n>      lastValidBlockHeight the transaction was built against.
+
+Examples:
+  solana-resilience-diagnose probe --rpc https://api.mainnet-beta.solana.com --rpc https://my-backup.rpc
+  solana-resilience-diagnose explain --rpc https://api.mainnet-beta.solana.com --sig 5xRe... --lvbh 287654321`;
+/**
+ * Pure argv parser. Accepts argv WITHOUT the `node script` prefix (i.e.
+ * `process.argv.slice(2)`). Supports `--flag value` and `--flag=value`. Throws
+ * {@link CliUsageError} (with help text) on anything malformed. No I/O.
+ */
+export function parseArgs(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined ||
+        command === "help" ||
+        command === "--help" ||
+        command === "-h") {
+        throw usage();
+    }
+    switch (command) {
+        case "probe":
+            return parseProbe(rest);
+        case "explain":
+            return parseExplain(rest);
+        default:
+            throw usage(`unknown command "${command}".`);
+    }
+}
+function parseProbe(args) {
+    const flags = collectFlags(args);
+    const rpcUrls = flags.get("rpc") ?? [];
+    if (rpcUrls.length === 0) {
+        throw usage('"probe" requires at least one --rpc <url>.');
+    }
+    return { command: "probe", rpcUrls };
+}
+function parseExplain(args) {
+    const flags = collectFlags(args);
+    const rpcUrl = single(flags, "rpc");
+    const signature = single(flags, "sig");
+    const lvbhRaw = single(flags, "lvbh");
+    let lastValidBlockHeight;
+    try {
+        lastValidBlockHeight = BigInt(lvbhRaw);
+    }
+    catch {
+        throw usage(`--lvbh must be an integer, got "${lvbhRaw}".`);
+    }
+    if (lastValidBlockHeight < 0n) {
+        throw usage(`--lvbh must be non-negative, got "${lvbhRaw}".`);
+    }
+    return { command: "explain", rpcUrl, signature, lastValidBlockHeight };
+}
+/** Parse repeated `--flag value` / `--flag=value` tokens into a multimap. */
+function collectFlags(args) {
+    const flags = new Map();
+    const queue = [...args];
+    while (queue.length > 0) {
+        const tok = queue.shift();
+        if (!tok.startsWith("--")) {
+            throw usage(`unexpected argument "${tok}".`);
+        }
+        const body = tok.slice(2);
+        const eq = body.indexOf("=");
+        let key;
+        let value;
+        if (eq >= 0) {
+            key = body.slice(0, eq);
+            value = body.slice(eq + 1);
+        }
+        else {
+            key = body;
+            const next = queue[0];
+            if (next !== undefined && !next.startsWith("--")) {
+                value = queue.shift();
+            }
+        }
+        if (value === undefined || value === "") {
+            throw usage(`flag --${key} requires a value.`);
+        }
+        const list = flags.get(key) ?? [];
+        list.push(value);
+        flags.set(key, list);
+    }
+    return flags;
+}
+/** Read a flag expected exactly once. */
+function single(flags, key) {
+    const values = flags.get(key);
+    if (values === undefined || values.length === 0) {
+        throw usage(`"explain" requires --${key} <value>.`);
+    }
+    if (values.length > 1) {
+        throw usage(`--${key} may be given only once.`);
+    }
+    return values[0];
+}
+function usage(detail) {
+    return new CliUsageError(detail ? `${detail}\n\n${USAGE}` : USAGE);
+}
+/** Render a {@link ProbeReport} as an aligned text table plus a summary line. */
+export function formatProbeReport(report) {
+    const header = ["ENDPOINT", "HEALTH", "SLOT", "LATENCY", "FRESHEST"];
+    const rows = report.endpoints.map((e) => [
+        e.name,
+        e.ok ? "ok" : "down",
+        e.slot === null ? "-" : e.slot.toString(),
+        `${e.latencyMs}ms`,
+        e.ok && e.name === report.freshest ? "*" : "",
+    ]);
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    const fmt = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
+    const lines = [fmt(header), ...rows.map(fmt), ""];
+    lines.push(report.healthyCount === 0
+        ? `No healthy endpoints (0/${report.endpoints.length} up).`
+        : `Freshest: ${report.freshest}  ·  ${report.healthyCount}/${report.endpoints.length} healthy.`);
+    for (const e of report.endpoints) {
+        if (!e.ok && e.error)
+            lines.push(`  ${e.name}: ${e.error}`);
+    }
+    return lines.join("\n");
+}
+/** Render an {@link TxDiagnosis} as a human verdict. */
+export function formatDiagnosis(signature, diag) {
+    const head = `Signature: ${signature}`;
+    switch (diag.status) {
+        case "confirmed":
+            return `${head}\nVerdict: CONFIRMED  (landed in slot ${diag.slot})`;
+        case "expired":
+            return `${head}\nVerdict: EXPIRED\n${diag.reason}`;
+        case "pending":
+            return `${head}\nVerdict: PENDING\n${diag.reason}`;
+    }
+}
+/* v8 ignore start -- real-RPC + stdout wiring; exercised by the installed binary, not unit-tested */
+const defaultCreateRpc = (url) => createSolanaRpc(url);
+const defaultLog = (line) => {
+    console.log(line);
+};
+/* v8 ignore stop */
+/**
+ * Execute one parsed command. Returns the process exit code. All side effects
+ * (RPC, stdout) go through {@link CliDeps}, so tests run it network-free.
+ */
+export async function run(argv, deps = {}) {
+    const log = deps.log ?? defaultLog;
+    /* v8 ignore next -- default RPC factory is real-network, covered via the binary */
+    const createRpc = deps.createRpc ?? defaultCreateRpc;
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+    }
+    catch (err) {
+        if (err instanceof CliUsageError) {
+            log(err.message);
+            return 2;
+        }
+        throw err;
+    }
+    const diag = deps.diagnostics ?? new Diagnostics();
+    if (parsed.command === "probe") {
+        const targets = parsed.rpcUrls.map((url) => ({ name: url, rpc: createRpc(url) }));
+        const report = await diag.probeEndpoints(targets);
+        log(formatProbeReport(report));
+        return report.healthyCount > 0 ? 0 : 1;
+    }
+    const result = await diag.explainTransaction(createRpc(parsed.rpcUrl), {
+        signature: parsed.signature,
+        lastValidBlockHeight: parsed.lastValidBlockHeight,
+    });
+    log(formatDiagnosis(parsed.signature, result));
+    return result.status === "expired" ? 1 : 0;
+}
+/* v8 ignore start -- process bootstrap; only runs when invoked as the binary */
+const entry = process.argv[1];
+if (entry !== undefined && import.meta.url === pathToFileURL(entry).href) {
+    run(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    }, (err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    });
+}
+/* v8 ignore stop */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-resilience-kit",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "Vendor-neutral, client-side resilience and observability layer for Solana dApps, built on @solana/kit (web3.js v2).",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,9 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "solana-resilience-diagnose": "./dist/cli/index.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -54,6 +57,7 @@
     "test:watch": "vitest",
     "test:cov": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
+    "docs:api": "typedoc",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "dependencies": {
@@ -65,6 +69,7 @@
     "@types/node": "^22.19.21",
     "@vitest/coverage-v8": "^4.1.9",
     "tsx": "^4.22.4",
+    "typedoc": "^0.28.19",
     "typescript": "^5.6.0",
     "vitest": "^4.1.9"
   }