solana-resilience-kit 1.0.1 → 1.1.0

package/README.md

@@ -3,6 +3,7 @@
 [![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)
+[![coverage ≥90% (CI-enforced)](https://img.shields.io/badge/coverage-%E2%89%A590%25%20CI--gated-brightgreen)](./.github/workflows/ci.yml)
 [![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.
@@ -99,7 +100,7 @@ The pool exposes a real `@solana/kit` `RpcTransport`, so callers build a normal
 npm install solana-resilience-kit @solana/kit
 ```
 
-Requires Node ≥ 20. The package is ESM-only and ships compiled JS with type declarations. `@solana/kit` is a peer of your app and is used directly in the API surface.
+Requires Node ≥ 20. The package is ESM-only and ships compiled JS with type declarations. **`@solana/kit` is a required peer dependency** (`^6.9.0`): install it alongside so your app and the SDK resolve to a *single* kit instance — this keeps kit's branded types (`Address`, `Signature`, `Base64EncodedWireTransaction`, …) compatible across the boundary. `@opentelemetry/api` is an **optional** peer, needed only if you use `OtelMetrics` (and is already pulled in transitively by the OpenTelemetry SDK packages — see [Wiring observability to OpenTelemetry / Datadog](#wiring-observability-to-opentelemetry--datadog)).
 
 ## Quickstart
 
@@ -143,13 +144,14 @@ 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`:
+without writing any code. Run it zero-install with `npx`, or — once the package
+is a dependency — call `solana-resilience-diagnose` directly (it is on your
+`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 \
+npx -p solana-resilience-kit solana-resilience-diagnose probe \
   --rpc https://api.mainnet-beta.solana.com \
   --rpc https://my-backup.rpc
 ```
@@ -167,7 +169,7 @@ Freshest: https://api.mainnet-beta.solana.com  ·  1/2 healthy.
 # 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 \
+npx -p solana-resilience-kit solana-resilience-diagnose explain \
   --rpc https://api.mainnet-beta.solana.com \
   --sig 5xRe...your-signature \
   --lvbh 287654321
@@ -192,6 +194,63 @@ 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`).
 
+## Wiring observability to OpenTelemetry / Datadog
+
+The library depends on **only `@opentelemetry/api`** — `OtelMetrics` writes to the
+*global* OpenTelemetry meter, which is a **no-op until your app registers a real
+`MeterProvider`** with a reader + exporter. The OTel SDK and OTLP exporter are
+your application's dependencies, not the SDK's, so you choose the backend. The
+~10 lines that make exports real:
+
+```ts
+import { metrics } from "@opentelemetry/api";
+import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OtelMetrics, ResilientRpcPool } from "solana-resilience-kit";
+
+// 1. Register a working MeterProvider — without this, OtelMetrics is inert.
+metrics.setGlobalMeterProvider(
+  new MeterProvider({
+    readers: [
+      new PeriodicExportingMetricReader({
+        // Reads OTEL_EXPORTER_OTLP_ENDPOINT, e.g. an OTel Collector or the
+        // Datadog Agent's OTLP intake (http://localhost:4318).
+        exporter: new OTLPMetricExporter(),
+        exportIntervalMillis: 10_000,
+      }),
+    ],
+  }),
+);
+
+// 2. Hand OtelMetrics to the SDK — now every signal below is exported.
+const pool = new ResilientRpcPool({ endpoints, metrics: new OtelMetrics({ serviceName: "my-dapp" }) });
+```
+
+Install the exporter side in your app (devtime/runtime, not in this library):
+
+```bash
+npm install @opentelemetry/sdk-metrics @opentelemetry/exporter-metrics-otlp-http
+```
+
+**For Datadog**, point `OTEL_EXPORTER_OTLP_ENDPOINT` at the Datadog Agent's OTLP
+endpoint (enable OTLP ingestion in the Agent); no separate Collector needed.
+
+The SDK emits a small, fixed set of client-side instruments:
+
+| Instrument | Type | Attributes | Emitted when |
+|---|---|---|---|
+| `rpc.request.latency_ms` | histogram | `endpoint`, `method`, `ok` | every RPC request attempt (per endpoint) |
+| `rpc.request.failures` | counter | `endpoint`, `method` | a request attempt fails |
+| `rpc.rate_limited` | counter | `endpoint` | an attempt is rejected with HTTP 429 |
+| `tx.rebroadcasts` | counter | `signature` | the sender rebroadcasts the signed transaction |
+| `tx.landings` | counter | `signature`, `outcome`, `slots` | a transaction reaches a terminal outcome (`confirmed` / `expired`) |
+| `rpc.endpoint.slot` | gauge | `endpoint` | a `getSlot` response is observed (slot-lag dashboards) |
+
+A runnable end-to-end demo is in [`examples/otel-setup.ts`](./examples/otel-setup.ts):
+`npm run example:otel` wires `OtelMetrics` into a pool + sender, drives simulated
+sends against the harness, and exports all six instruments — with a console
+exporter attached so you see every data point even without a collector running.
+
 ## Testing your own code against the fault harness
 
 The deterministic Solana cluster simulator the SDK is tested with is shipped as a
@@ -238,7 +297,7 @@ npm run test:cov  # coverage with the thresholds enforced
 npm run typecheck # tsc --noEmit
 ```
 
-Coverage thresholds (`vitest.config.ts`) are **lines 90 / functions 90 / branches 85 / statements 90**, and the suite passes them. A fully reproducible Docker environment is available via the [`Makefile`](./Makefile):
+Coverage thresholds (`vitest.config.ts`) are **lines 90 / functions 90 / branches 85 / statements 90**, and the suite passes them. **CI enforces this gate on every push and PR** — the `docker compose run --rm cov` step in [`ci.yml`](./.github/workflows/ci.yml) runs `npm run test:cov`, which exits non-zero (failing the build) if coverage drops below those thresholds. A fully reproducible Docker environment is available via the [`Makefile`](./Makefile):
 
 ```bash
 make verify   # typecheck + always-green harness/metrics tests, in Docker

package/dist/cli/index.js

@@ -19,6 +19,7 @@
  * tx) · 2 a usage error.
  */
 import { createSolanaRpc } from "@solana/kit";
+import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { SdkError } from "../errors.js";
 import { Diagnostics } from "./diagnose.js";
@@ -211,8 +212,11 @@ export async function run(argv, deps = {}) {
     return result.status === "expired" ? 1 : 0;
 }
 /* v8 ignore start -- process bootstrap; only runs when invoked as the binary */
+// Resolve symlinks: npm installs the bin as a symlink in node_modules/.bin, so
+// process.argv[1] is that link while import.meta.url is the real dist file —
+// comparing realpaths is what makes the binary fire when run by name.
 const entry = process.argv[1];
-if (entry !== undefined && import.meta.url === pathToFileURL(entry).href) {
+if (entry !== undefined && import.meta.url === pathToFileURL(realpathSync(entry)).href) {
     run(process.argv.slice(2)).then((code) => {
         process.exitCode = code;
     }, (err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-resilience-kit",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Vendor-neutral, client-side resilience and observability layer for Solana dApps, built on @solana/kit (web3.js v2).",
   "type": "module",
   "license": "MIT",
@@ -58,14 +58,24 @@
     "test:cov": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
     "docs:api": "typedoc",
+    "example:otel": "tsx examples/otel-setup.ts",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
-  "dependencies": {
+  "peerDependencies": {
     "@opentelemetry/api": "^1.9.0",
     "@solana/kit": "^6.9.0"
   },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.219.0",
+    "@opentelemetry/sdk-metrics": "^2.8.0",
     "@solana-program/system": "^0.12.2",
+    "@solana/kit": "^6.9.0",
     "@types/node": "^22.19.21",
     "@vitest/coverage-v8": "^4.1.9",
     "tsx": "^4.22.4",