solana-resilience-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mihail Shumilov
+
+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/README.md

@@ -0,0 +1,210 @@
+# solana-resilience-kit
+
+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))
+
+- **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.
+- **Observable** — first-class client telemetry to OpenTelemetry / Datadog.
+
+## Problem
+
+Solana's reliability failures are not random bugs — they are direct consequences of four structural facts, and each needs a distinct client-side mitigation:
+
+1. **No mempool.** RPC nodes forward a transaction straight to the upcoming leader over QUIC; there is no shared pending pool, so a dropped transaction leaves no trace and gets no automatic retry. ([Solana — Retry](https://solana.com/developers/guides/advanced/retry))
+2. **Blockhash expiry.** A recent blockhash is valid for only ~150 blocks (~60–90 s); after that the transaction is permanently rejected. Re-signing *before* expiry can land both copies and **double-charge the user** — safe resend only happens once block height passes `lastValidBlockHeight`. ([Solana — Confirmation](https://solana.com/developers/guides/advanced/confirmation))
+3. **Stake-weighted QoS (SWQoS).** Leaders reserve ~80% of inbound QUIC connections for staked validators and ~20% shared across all unstaked nodes, so unstaked submission is structurally disadvantaged under congestion. ([Helius — SWQoS](https://www.helius.dev/blog/stake-weighted-quality-of-service-everything-you-need-to-know))
+4. **Localized fee markets.** Contention attaches to specific write-locked accounts, so a global fee number is a poor proxy for what *your* transaction needs. ([Helius — local fee markets](https://www.helius.dev/blog/solana-local-fee-markets))
+
+These modes are dormant in calm conditions and resurface on every demand spike — the March–April 2024 congestion drove non-vote failure rates near 75%. ([Cointelegraph](https://cointelegraph.com/news/solana-struggling-record-seventy-five-percent-trasnactions-fail-memecoin-mania)) Reliability therefore has to be engineered around each fact explicitly, not treated as best-effort.
+
+## Pain points
+
+| Pain | Who it hits | What this SDK does |
+|---|---|---|
+| Silent transaction drop (no error, no trace) | end users, dApp devs | `TransactionSender` with bounded rebroadcast and block-height confirmation |
+| Blockhash expiry / double-charge on resign | end users, dApp devs | outcome bounded by `lastValidBlockHeight`; never re-signs the transaction |
+| 429 / credit exhaustion | anyone on public/shared RPC, indexers, bots | `CreditRateLimiter` (per-method weights) + pool failover |
+| Node desync inside an RPC pool | every multi-provider dApp | `HealthMonitor` (slot-freshness ranking), routes to a fresh node |
+| Priority-fee / compute-unit estimation | all devs, wallets, traders | `simulate → unitsConsumed + ~10%`, percentile fee oracle |
+| MEV / frontrunning | DEX/memecoin swappers, bots | `JitoRouter` + dynamic tip + automatic fallback to RPC |
+| Observability blind spot | infra/frontend engineers, wallets | client telemetry exported to OpenTelemetry / Datadog |
+
+## Existing solutions & their shortcomings
+
+The decisive finding: every robust mitigation today is **either a DIY recipe in the official SDK, or locked inside one provider's walled garden.**
+
+| Tool / layer | Solves | Falls short |
+|---|---|---|
+| **`@solana/kit`** (web3.js v2) | Composable transports, better confirmation primitives, tree-shakable | Failover / round-robin / retry shipped only as **copy-paste recipes**; no Jito routing, no health-aware multi-RPC, no telemetry |
+| **Helius / QuickNode / Triton** | Excellent landing (staked send), priority-fee & bundle APIs | **Provider lock-in** — needs their key and their gateway; server-side; doesn't unify across providers |
+| **Jito** (bundles, low-latency send) | MEV protection, atomicity, tips | A provider service; a `bundle_id` is a receipt, **not a landing guarantee** — needs fallback + tip logic the dev must build |
+| **`@solana/wallet-adapter`** | Wallet connect / sign / send handoff | **No resilience** — failover/retry/confirmation are explicitly the app's job |
+| **OSS multi-RPC libs** | Thin failover wrappers | Narrow; none combine retry + confirmation + Jito + observability |
+| **OpenTelemetry / Datadog** | Generic JSON-RPC spans, OTLP ingest | **No Solana-specific client instrumentation exists** |
+
+**The white space:** a *vendor-neutral, client-side, systems-grade* layer that unifies all of the above behind one API on top of `@solana/kit` — which is exactly what this package provides.
+
+## Modules
+
+| Module | File | Responsibility |
+|---|---|---|
+| `ResilientRpcPool` | `src/rpc/pool.ts` | Failover + freshness-aware routing behind one kit `RpcTransport`; per-request metrics |
+| `HealthMonitor` | `src/rpc/health.ts` | Per-endpoint freshness/latency/error tracking; ejects laggards beyond `maxSlotLag` |
+| `CreditRateLimiter` | `src/rpc/rate-limit.ts` | Weighted-credit token bucket to pre-empt 429s |
+| `TransactionSender` | `src/tx/sender.ts` | Send/confirm state machine: `maxRetries:0`, bounded rebroadcast, **no re-sign** |
+| `ConfirmationTracker` | `src/tx/confirmation.ts` | Decides outcome by block height vs `lastValidBlockHeight`, never polls forever |
+| `FeeEstimator` + `NativeFeeOracle` / `HeliusFeeOracle` | `src/fees/*` | Simulate-based CU sizing + pluggable percentile fee oracle (native or Helius) |
+| `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 |
+
+## Architecture
+
+```mermaid
+flowchart LR
+  dApp[dApp] --> WA[ResilientWalletAdapter]
+  WA -->|signed wire tx| TS[TransactionSender]
+  TS <-->|send / confirm| POOL[ResilientRpcPool]
+  subgraph POOL_INTERNALS [ResilientRpcPool]
+    HM[HealthMonitor]
+    RL[CreditRateLimiter]
+    FO[failover + freshness routing]
+  end
+  POOL --> EP[(RPC endpoints)]
+  FE[FeeEstimator] -.priority fee / CU.-> TS
+
+  dApp --> JR[JitoRouter]
+  JR -->|bundle + tip| BE[Jito Block Engine]
+  JR -.fallback when bundle does not land.-> TS
+
+  TS --> M[OtelMetrics → OpenTelemetry / Datadog]
+  POOL --> M
+```
+
+The pool exposes a real `@solana/kit` `RpcTransport`, so callers build a normal kit RPC with `pool.rpc()` and use it like any other — failover, freshness routing, and metrics happen underneath. The Jito path runs in parallel and **always falls back** to the resilient sender when a bundle does not land.
+
+## Install
+
+```bash
+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.
+
+## Quickstart
+
+Build a failover pool from two RPC endpoints and use it as a normal kit RPC:
+
+```ts
+import { createDefaultRpcTransport } from "@solana/kit";
+import { ResilientRpcPool, TransactionSender } from "solana-resilience-kit";
+
+const pool = new ResilientRpcPool({
+  endpoints: [
+    { name: "primary", transport: createDefaultRpcTransport({ url: PRIMARY_URL }) },
+    { name: "backup",  transport: createDefaultRpcTransport({ url: BACKUP_URL }) },
+  ],
+});
+
+const rpc = pool.rpc();                 // a normal @solana/kit RPC, failover underneath
+const slot = await rpc.getSlot().send();
+```
+
+Send a signed transaction with correct confirmation semantics:
+
+```ts
+const sender = new TransactionSender(rpc);
+
+const result = await sender.sendAndConfirm({
+  wireTransaction,        // base64, already signed (from getBase64EncodedWireTransaction)
+  signature,              // from getSignatureFromTransaction
+  lastValidBlockHeight,   // from the blockhash the tx was built with
+});
+
+// result.outcome is "confirmed" or "expired" — decided by block height,
+// not a timeout. The sender uses maxRetries:0, rebroadcasts the *same*
+// signed bytes, never re-signs (so it can never double-charge), and treats a
+// resend error on an already-landed tx as non-terminal.
+```
+
+## Testing your own code against the fault harness
+
+The deterministic Solana cluster simulator the SDK is tested with is shipped as a
+secondary entry point, so you can drive *your* code through the same injected
+faults (drops, expiry, 429s, slot lag) — no network, fully reproducible:
+
+```ts
+import { MockCluster, MockEndpoint } from "solana-resilience-kit/testing";
+import { createSolanaRpcFromTransport } from "@solana/kit";
+
+const cluster = new MockCluster({ initialBlockHeight: 700n });
+const endpoint = new MockEndpoint(cluster, { name: "sim" });
+endpoint.faults = { dropRate: 1 };               // silently drop every send
+const rpc = createSolanaRpcFromTransport(endpoint.transport);
+
+// ...exercise your sender; advance time deterministically:
+cluster.advanceSlots(160);                        // push past lastValidBlockHeight
+```
+
+## Interactive demo
+
+**Live at [solana-rpc-sdk.pages.dev](https://solana-rpc-sdk.pages.dev)** · source in [`demo/`](./demo)
+
+**RPC Resilience Lab** is a backend-free Vite + React app that runs the *real* SDK in your browser. In **simulation** mode it drives the fault harness (inject drops / 429s / lag / Jito failure and flip the SDK on/off to compare landing rates against a naive client); in **devnet** mode it connects a standard wallet (`@solana/wallet-adapter`), signs a real transfer, and lands it through the SDK with an explorer link.
+
+```bash
+cd demo && npm install && npm run dev
+```
+
+A headless Node example is in [`examples/devnet-demo.ts`](./examples/devnet-demo.ts) (`npx tsx examples/devnet-demo.ts`).
+
+## Testing & simulation
+
+Solana's failure modes — silent drops, blockhash expiry, 429s, lagging-node desync, MEV — cannot be reproduced reliably against live infrastructure, so the SDK is tested against an in-memory, deterministic model of a Solana cluster that injects exactly these faults.
+
+- **Real `@solana/kit` integration.** Each simulated endpoint exposes a real kit `RpcTransport`; a harness self-test signs an actual kit transaction and verifies our wire-format signature extraction matches `getSignatureFromTransaction` — so web3.js-v2 compatibility is *proven*, not assumed.
+- **Manual clock.** Nothing advances unless a test calls `cluster.advanceSlots(n)`, making blockhash-expiry and rebroadcast timing deterministic.
+- **Seeded faults.** A seeded PRNG drives drops / 429s / latency / slot lag, so every failing sequence is reproducible.
+- **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 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):
+
+```bash
+make verify   # typecheck + always-green harness/metrics tests, in Docker
+make test     # typecheck + full suite, in Docker
+make cov      # coverage report (writes ./coverage)
+```
+
+## Building from source
+
+```bash
+npm run build   # emit dist/ — compiled JS + .d.ts for `.` and `./testing`
+```
+
+The published package contains only `dist/`, `README.md`, and `LICENSE`. `prepublishOnly` re-runs typecheck + tests + build before any publish.
+
+## Project layout
+
+```
+src/        public API — the SDK modules
+test/       behavioral specs + test/harness/ (the simulation cluster)
+demo/       RPC Resilience Lab (Vite + React browser app)
+examples/   headless devnet example
+```
+
+## License
+
+[MIT](./LICENSE)
+</content>
+</invoke>

package/dist/cli/diagnose.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Diagnostics — the injectable, deterministic core behind the `diagnose` CLI.
+ *
+ * It answers the two questions an operator asks when a Solana dApp misbehaves:
+ *   1. probeEndpoints — which providers are healthy and which is freshest?
+ *      (reuses HealthMonitor so the freshness ranking matches the pool's own
+ *       routing logic — the "fresh blockhash from an advanced node sent to a
+ *       lagging node drops the tx" failure mode is judged the same way here.)
+ *   2. explainTransaction — point-in-time, did a transaction land, expire, or is
+ *      it still in its validity window? The verdict is the canonical Solana rule
+ *      (current block height vs lastValidBlockHeight), mirrored from
+ *      ConfirmationTracker, with NO polling loop.
+ *
+ * The argv/console/real-RPC wiring of the binary is integration-only; nothing in
+ * this module executes at import time.
+ */
+import type { Rpc, SolanaRpcApi } from "@solana/kit";
+import { HealthMonitor } from "../rpc/health.js";
+export interface ProbeTarget {
+    name: string;
+    rpc: Rpc<SolanaRpcApi>;
+}
+export interface EndpointProbe {
+    name: string;
+    ok: boolean;
+    slot: bigint | null;
+    latencyMs: number;
+    error?: string;
+}
+export interface ProbeReport {
+    endpoints: EndpointProbe[];
+    /** Name of the freshest healthy endpoint, or null when none are healthy. */
+    freshest: string | null;
+    /** Endpoints that responded successfully in this probe round. */
+    healthyCount: number;
+}
+export type TxDiagnosis = {
+    status: "confirmed";
+    slot: bigint;
+} | {
+    status: "expired";
+    reason: string;
+} | {
+    status: "pending";
+    reason: string;
+};
+export interface DiagnosticsDeps {
+    /** Inject a shared HealthMonitor to fold probe results into existing state. */
+    healthMonitor?: HealthMonitor;
+}
+export interface ExplainTxOptions {
+    signature: string;
+    lastValidBlockHeight: bigint;
+    /** Target commitment (informational; landing is decided by status presence). */
+    commitment?: "confirmed" | "finalized";
+}
+export declare class Diagnostics {
+    private readonly deps?;
+    constructor(deps?: DiagnosticsDeps | undefined);
+    /**
+     * Probes every target's current slot, recording latency and health into a
+     * HealthMonitor so the freshness ranking is identical to the pool's. An
+     * endpoint that throws (offline / errored) is flagged ok:false with slot null
+     * and never ranked.
+     */
+    probeEndpoints(targets: ProbeTarget[]): Promise<ProbeReport>;
+    /**
+     * Point-in-time verdict on a transaction. No polling: it inspects the current
+     * signature status and current block height once.
+     *
+     * Order matters — a status check wins over the expiry bound, because a tx can
+     * land exactly at the deadline block (same precedence as ConfirmationTracker).
+     */
+    explainTransaction(rpc: Rpc<SolanaRpcApi>, opts: ExplainTxOptions): Promise<TxDiagnosis>;
+}

package/dist/cli/diagnose.js

@@ -0,0 +1,70 @@
+import { HealthMonitor } from "../rpc/health.js";
+export class Diagnostics {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Probes every target's current slot, recording latency and health into a
+     * HealthMonitor so the freshness ranking is identical to the pool's. An
+     * endpoint that throws (offline / errored) is flagged ok:false with slot null
+     * and never ranked.
+     */
+    async probeEndpoints(targets) {
+        const hm = this.deps?.healthMonitor ??
+            new HealthMonitor({ endpointNames: targets.map((t) => t.name) });
+        const endpoints = await Promise.all(targets.map(async (target) => {
+            const startedAt = Date.now();
+            try {
+                const slot = await target.rpc.getSlot().send();
+                const latencyMs = Date.now() - startedAt;
+                hm.recordSuccess(target.name, latencyMs, slot);
+                return { name: target.name, ok: true, slot, latencyMs };
+            }
+            catch (err) {
+                const latencyMs = Date.now() - startedAt;
+                hm.recordFailure(target.name, err);
+                return {
+                    name: target.name,
+                    ok: false,
+                    slot: null,
+                    latencyMs,
+                    error: String(err?.message ?? err),
+                };
+            }
+        }));
+        const freshest = hm.rankByFreshness()[0] ?? null;
+        const healthyCount = endpoints.filter((e) => e.ok).length;
+        return { endpoints, freshest, healthyCount };
+    }
+    /**
+     * Point-in-time verdict on a transaction. No polling: it inspects the current
+     * signature status and current block height once.
+     *
+     * Order matters — a status check wins over the expiry bound, because a tx can
+     * land exactly at the deadline block (same precedence as ConfirmationTracker).
+     */
+    async explainTransaction(rpc, opts) {
+        const signature = opts.signature;
+        const status = (await rpc.getSignatureStatuses([signature]).send()).value[0];
+        if (status != null &&
+            status.confirmationStatus != null &&
+            status.err == null) {
+            return { status: "confirmed", slot: status.slot };
+        }
+        const blockHeight = await rpc.getBlockHeight().send();
+        if (blockHeight > opts.lastValidBlockHeight) {
+            return {
+                status: "expired",
+                reason: `block height ${blockHeight} exceeded lastValidBlockHeight ${opts.lastValidBlockHeight}; ` +
+                    "the blockhash expired before the transaction landed (silent drop or congestion). " +
+                    "Rebuild with a fresh blockhash — do NOT re-sign the same one.",
+            };
+        }
+        return {
+            status: "pending",
+            reason: `still within the validity window (height ${blockHeight} <= ${opts.lastValidBlockHeight}); ` +
+                "keep rebroadcasting the same signed transaction until it lands or expires.",
+        };
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/** Error taxonomy for the resilience kit. Distinct types so callers can branch. */
+export declare class SdkError extends Error {
+    constructor(message: string);
+}
+/** Thrown by every stub until the implementation phase fills it in. */
+export declare class NotImplementedError extends SdkError {
+    constructor(what?: string);
+}
+/** A transaction's blockhash expired before it landed (terminal, not retryable). */
+export declare class TransactionExpiredError extends SdkError {
+    readonly signature: string;
+    readonly lastValidBlockHeight: bigint;
+    constructor(signature: string, lastValidBlockHeight: bigint);
+}
+/** Every endpoint in the pool failed for a single logical request. */
+export declare class AllEndpointsFailedError extends SdkError {
+    readonly attempts: ReadonlyArray<{
+        endpoint: string;
+        error: unknown;
+    }>;
+    constructor(attempts: ReadonlyArray<{
+        endpoint: string;
+        error: unknown;
+    }>);
+}
+/** A Jito bundle did not land before its deadline; caller should fall back. */
+export declare class BundleNotLandedError extends SdkError {
+    readonly bundleId: string;
+    constructor(bundleId: string);
+}

package/dist/errors.js

@@ -0,0 +1,39 @@
+/** Error taxonomy for the resilience kit. Distinct types so callers can branch. */
+export class SdkError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** Thrown by every stub until the implementation phase fills it in. */
+export class NotImplementedError extends SdkError {
+    constructor(what = "not implemented") {
+        super(what);
+    }
+}
+/** A transaction's blockhash expired before it landed (terminal, not retryable). */
+export class TransactionExpiredError extends SdkError {
+    signature;
+    lastValidBlockHeight;
+    constructor(signature, lastValidBlockHeight) {
+        super(`transaction ${signature} expired at block height ${lastValidBlockHeight}`);
+        this.signature = signature;
+        this.lastValidBlockHeight = lastValidBlockHeight;
+    }
+}
+/** Every endpoint in the pool failed for a single logical request. */
+export class AllEndpointsFailedError extends SdkError {
+    attempts;
+    constructor(attempts) {
+        super(`all ${attempts.length} endpoint attempt(s) failed`);
+        this.attempts = attempts;
+    }
+}
+/** A Jito bundle did not land before its deadline; caller should fall back. */
+export class BundleNotLandedError extends SdkError {
+    bundleId;
+    constructor(bundleId) {
+        super(`bundle ${bundleId} did not land`);
+        this.bundleId = bundleId;
+    }
+}

package/dist/fees/estimator.d.ts

@@ -0,0 +1,47 @@
+/**
+ * FeeEstimator — turns a transaction into a (compute-unit limit, priority-fee
+ * price) pair. CU limit comes from simulation (unitsConsumed) plus a safety
+ * margin; the priority-fee price comes from a pluggable FeeOracle. Correct CU
+ * sizing matters because the fee is charged on the *requested* limit.
+ */
+import type { Rpc, SolanaRpcApi } from "@solana/kit";
+import type { FeeOracle, FeeLevel } from "./oracles.js";
+export interface ComputeBudget {
+    /** Recommended setComputeUnitLimit value. */
+    computeUnitLimit: number;
+    /** Recommended setComputeUnitPrice value (micro-lamports per CU). */
+    computeUnitPrice: number;
+    /** Resulting priority fee in lamports = ceil(limit * price / 1e6). */
+    priorityFeeLamports: number;
+}
+export interface EstimateConfig {
+    /** Base64 wire transaction to simulate for unitsConsumed. */
+    wireTransaction: string;
+    writableAccounts: string[];
+    level?: FeeLevel;
+    /** Multiplier applied to simulated CU (default 1.1 = +10% margin). */
+    cuMargin?: number;
+}
+export declare class FeeEstimator {
+    private readonly rpc;
+    private readonly oracle;
+    constructor(rpc: Rpc<SolanaRpcApi>, oracle: FeeOracle);
+    /**
+     * Simulates the tx and returns unitsConsumed (no margin applied).
+     *
+     * We use `replaceRecentBlockhash: true` so the simulation does not fail on a
+     * stale/expired blockhash, and we never verify signatures — the only thing we
+     * care about here is the compute-unit count the program would burn.
+     */
+    simulateComputeUnits(wireTransaction: string): Promise<number>;
+    /**
+     * Full compute-budget recommendation (CU limit + price + resulting fee).
+     *
+     * The CU limit is the simulated consumption scaled by a safety margin
+     * (`Math.round`, not `ceil` — `6000 * 1.1` is `6600.000000000001` in IEEE-754,
+     * and rounding lands on the intended 6600). The price comes from the oracle at
+     * the requested level. The resulting fee is `ceil(limit * price / 1e6)` because
+     * the network charges priority fee on the *requested* limit in micro-lamports.
+     */
+    estimate(config: EstimateConfig): Promise<ComputeBudget>;
+}

package/dist/fees/estimator.js

@@ -0,0 +1,43 @@
+export class FeeEstimator {
+    rpc;
+    oracle;
+    constructor(rpc, oracle) {
+        this.rpc = rpc;
+        this.oracle = oracle;
+    }
+    /**
+     * Simulates the tx and returns unitsConsumed (no margin applied).
+     *
+     * We use `replaceRecentBlockhash: true` so the simulation does not fail on a
+     * stale/expired blockhash, and we never verify signatures — the only thing we
+     * care about here is the compute-unit count the program would burn.
+     */
+    async simulateComputeUnits(wireTransaction) {
+        const { value } = await this.rpc
+            .simulateTransaction(wireTransaction, {
+            encoding: "base64",
+            replaceRecentBlockhash: true,
+        })
+            .send();
+        return Number(value.unitsConsumed ?? 0);
+    }
+    /**
+     * Full compute-budget recommendation (CU limit + price + resulting fee).
+     *
+     * The CU limit is the simulated consumption scaled by a safety margin
+     * (`Math.round`, not `ceil` — `6000 * 1.1` is `6600.000000000001` in IEEE-754,
+     * and rounding lands on the intended 6600). The price comes from the oracle at
+     * the requested level. The resulting fee is `ceil(limit * price / 1e6)` because
+     * the network charges priority fee on the *requested* limit in micro-lamports.
+     */
+    async estimate(config) {
+        const units = await this.simulateComputeUnits(config.wireTransaction);
+        const cuMargin = config.cuMargin ?? 1.1;
+        const computeUnitLimit = Math.round(units * cuMargin);
+        const level = config.level ?? "medium";
+        const est = await this.oracle.getPriorityFee(config.writableAccounts);
+        const computeUnitPrice = est.levels[level];
+        const priorityFeeLamports = Math.ceil((computeUnitLimit * computeUnitPrice) / 1_000_000);
+        return { computeUnitLimit, computeUnitPrice, priorityFeeLamports };
+    }
+}

package/dist/fees/oracles.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Fee oracles — pluggable sources of priority-fee estimates. The native oracle
+ * uses `getRecentPrioritizationFees` (free, backward-looking minimum); the
+ * Helius/QuickNode oracles call account-aware percentile APIs. Vendor neutrality
+ * means the SDK works with any of them behind one interface.
+ */
+import type { Rpc, SolanaRpcApi } from "@solana/kit";
+export type FeeLevel = "min" | "low" | "medium" | "high" | "veryHigh";
+export interface PriorityFeeEstimate {
+    /** micro-lamports per compute unit, keyed by level. */
+    levels: Record<FeeLevel, number>;
+}
+export interface FeeOracle {
+    /** Estimate priority fee given the writable accounts the tx will touch. */
+    getPriorityFee(writableAccounts: string[]): Promise<PriorityFeeEstimate>;
+}
+/** Native estimate from getRecentPrioritizationFees over recent slots. */
+export declare class NativeFeeOracle implements FeeOracle {
+    private readonly rpc;
+    constructor(rpc: Rpc<SolanaRpcApi>);
+    /**
+     * Derives micro-lamports-per-CU percentiles from the cluster's recent
+     * prioritization-fee samples (`getRecentPrioritizationFees`). This is the
+     * free, backward-looking source: the node returns the smallest fee paid by a
+     * landed tx per recent slot. We sort the samples and pick percentiles by
+     * nearest-rank so the levels are monotonic.
+     */
+    getPriorityFee(writableAccounts: string[]): Promise<PriorityFeeEstimate>;
+}
+export interface HttpFeeOracleConfig {
+    url: string;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Helius `getPriorityFeeEstimate` — account-aware percentile estimates. Helius
+ * already returns micro-lamports-per-CU figures keyed by the same level names we
+ * expose (`priorityFeeLevels`), so the mapping is direct. `fetchImpl` is
+ * injectable for deterministic tests and defaults to the global `fetch`; the
+ * API key, when provided, is appended to the request URL.
+ */
+export declare class HeliusFeeOracle implements FeeOracle {
+    private readonly config;
+    constructor(config: HttpFeeOracleConfig);
+    getPriorityFee(writableAccounts: string[]): Promise<PriorityFeeEstimate>;
+}