solana-resilience-kit 1.0.2 → 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
 
@@ -193,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
@@ -239,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-resilience-kit",
-  "version": "1.0.2",
+  "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",