solana-resilience-kit 0.1.0

package/dist/rpc/pool.d.ts

@@ -0,0 +1,66 @@
+/**
+ * ResilientRpcPool — the heart of the RPC layer. Wraps N endpoints behind a
+ * single `@solana/kit`-compatible RpcTransport that:
+ *   - routes to the freshest healthy endpoint (via HealthMonitor),
+ *   - fails over to the next endpoint on 429 / transport error,
+ *   - meters weighted credits to pre-empt 429s (CreditRateLimiter),
+ *   - emits per-request metrics.
+ *
+ * Because it exposes a real RpcTransport, callers build a normal kit RPC with
+ * `pool.rpc()` and use it exactly like any kit RPC — that is the web3.js-v2
+ * compatibility guarantee plus DX win.
+ */
+import type { RpcTransport } from "@solana/rpc-spec";
+import { type Rpc, type SolanaRpcApi } from "@solana/kit";
+import { HealthMonitor, type EndpointHealth } from "./health.js";
+import type { CreditRateLimiter } from "./rate-limit.js";
+import type { Metrics } from "../observability/metrics.js";
+export interface ResilientEndpoint {
+    name: string;
+    /** A kit-compatible transport (HTTP transport in prod, MockEndpoint in tests). */
+    transport: RpcTransport;
+    /** Relative routing weight among equally-fresh endpoints (default 1). */
+    weight?: number;
+}
+export interface ResilientRpcConfig {
+    endpoints: ResilientEndpoint[];
+    /** Max endpoint attempts per logical request (default = endpoints.length). */
+    maxAttempts?: number;
+    /** Route to the freshest healthy node first (default true). */
+    freshnessAware?: boolean;
+    /** Send the same read to N endpoints and take the first response (default 1). */
+    hedge?: number;
+    healthMonitor?: HealthMonitor;
+    rateLimiter?: CreditRateLimiter;
+    metrics?: Metrics;
+}
+export declare class ResilientRpcPool {
+    private readonly endpoints;
+    private readonly endpointNames;
+    private readonly byName;
+    private readonly healthMonitor;
+    private readonly rateLimiter?;
+    private readonly metrics?;
+    private readonly freshnessAware;
+    private readonly maxAttempts;
+    constructor(config: ResilientRpcConfig);
+    /** The failover transport. Plug into `createSolanaRpcFromTransport`. */
+    get transport(): RpcTransport;
+    /** A ready-to-use kit RPC backed by the resilient transport. */
+    rpc(): Rpc<SolanaRpcApi>;
+    /** Current per-endpoint health snapshot (for monitoring / CLI). */
+    health(): EndpointHealth[];
+    /**
+     * Builds the per-request attempt order. When freshness-aware, probe every
+     * endpoint's slot first so the HealthMonitor can rank fresh nodes ahead of
+     * laggards, then fall back to any configured endpoint not in the ranking
+     * (so unhealthy nodes stay as a last resort). Probe errors never escape.
+     *
+     * NOTE: this minimal form double-counts getSlot traffic (one probe + one
+     * serve per logical request). A real deployment would gate probing behind a
+     * refresh interval; the contract only requires correct routing here.
+     */
+    private attemptOrder;
+    /** Probe a single endpoint's getSlot, feeding health/metrics. Never throws. */
+    private probe;
+}

package/dist/rpc/pool.js

@@ -0,0 +1,126 @@
+import { createSolanaRpcFromTransport } from "@solana/kit";
+import { AllEndpointsFailedError } from "../errors.js";
+import { HealthMonitor } from "./health.js";
+/** True when an error is an HTTP 429 (rate-limit) carrying a numeric statusCode. */
+function isRateLimited(err) {
+    return (err !== null &&
+        typeof err === "object" &&
+        err.statusCode === 429);
+}
+/** Defensively read a bigint slot off a getSlot response (result is the slot). */
+function slotFromResponse(response) {
+    return typeof response.result === "bigint" ? response.result : undefined;
+}
+export class ResilientRpcPool {
+    endpoints;
+    endpointNames;
+    byName;
+    healthMonitor;
+    rateLimiter;
+    metrics;
+    freshnessAware;
+    maxAttempts;
+    constructor(config) {
+        this.endpoints = config.endpoints;
+        this.endpointNames = config.endpoints.map((e) => e.name);
+        this.byName = new Map(config.endpoints.map((e) => [e.name, e]));
+        this.healthMonitor =
+            config.healthMonitor ??
+                new HealthMonitor({ endpointNames: this.endpointNames, maxSlotLag: 150n });
+        this.rateLimiter = config.rateLimiter;
+        this.metrics = config.metrics;
+        this.freshnessAware = config.freshnessAware ?? true;
+        this.maxAttempts = config.maxAttempts ?? config.endpoints.length;
+    }
+    /** The failover transport. Plug into `createSolanaRpcFromTransport`. */
+    get transport() {
+        const transport = async (config) => {
+            const payload = config.payload;
+            const method = payload.method;
+            const order = await this.attemptOrder();
+            const attempts = [];
+            let used = 0;
+            for (const name of order) {
+                if (used >= this.maxAttempts)
+                    break;
+                const endpoint = this.byName.get(name);
+                if (endpoint === undefined)
+                    continue;
+                used += 1;
+                // Optional credit gating: a dry bucket is a soft failure — advance on.
+                if (this.rateLimiter !== undefined && !this.rateLimiter.tryAcquire(method)) {
+                    attempts.push({ endpoint: name, error: new Error("rate limiter: no credits") });
+                    continue;
+                }
+                // Date.now() here is a metric value, not loop control — acceptable.
+                const start = Date.now();
+                try {
+                    const response = (await endpoint.transport(config));
+                    const latencyMs = Date.now() - start;
+                    const slot = method === "getSlot" ? slotFromResponse(response) : undefined;
+                    this.healthMonitor.recordSuccess(name, latencyMs, slot);
+                    if (slot !== undefined)
+                        this.metrics?.recordSlot(name, slot);
+                    this.metrics?.recordRequest(name, method, latencyMs, true);
+                    return response;
+                }
+                catch (err) {
+                    const latencyMs = Date.now() - start;
+                    if (isRateLimited(err))
+                        this.metrics?.recordRateLimited(name);
+                    this.healthMonitor.recordFailure(name, err);
+                    this.metrics?.recordRequest(name, method, latencyMs, false);
+                    attempts.push({ endpoint: name, error: err });
+                }
+            }
+            throw new AllEndpointsFailedError(attempts);
+        };
+        return transport;
+    }
+    /** A ready-to-use kit RPC backed by the resilient transport. */
+    rpc() {
+        return createSolanaRpcFromTransport(this.transport);
+    }
+    /** Current per-endpoint health snapshot (for monitoring / CLI). */
+    health() {
+        return this.healthMonitor.snapshot();
+    }
+    /**
+     * Builds the per-request attempt order. When freshness-aware, probe every
+     * endpoint's slot first so the HealthMonitor can rank fresh nodes ahead of
+     * laggards, then fall back to any configured endpoint not in the ranking
+     * (so unhealthy nodes stay as a last resort). Probe errors never escape.
+     *
+     * NOTE: this minimal form double-counts getSlot traffic (one probe + one
+     * serve per logical request). A real deployment would gate probing behind a
+     * refresh interval; the contract only requires correct routing here.
+     */
+    async attemptOrder() {
+        if (!this.freshnessAware)
+            return this.endpointNames;
+        await Promise.all(this.endpoints.map((e) => this.probe(e)));
+        const ranked = this.healthMonitor.rankByFreshness();
+        if (ranked.length === 0)
+            return this.endpointNames;
+        const seen = new Set(ranked);
+        const fallback = this.endpointNames.filter((n) => !seen.has(n));
+        return [...ranked, ...fallback];
+    }
+    /** Probe a single endpoint's getSlot, feeding health/metrics. Never throws. */
+    async probe(endpoint) {
+        const probePayload = { jsonrpc: "2.0", id: 1, method: "getSlot", params: [] };
+        const start = Date.now();
+        try {
+            const response = (await endpoint.transport({ payload: probePayload }));
+            const latencyMs = Date.now() - start;
+            const slot = slotFromResponse(response);
+            this.healthMonitor.recordSuccess(endpoint.name, latencyMs, slot);
+            if (slot !== undefined)
+                this.metrics?.recordSlot(endpoint.name, slot);
+        }
+        catch (err) {
+            // Swallow: a probe failure must never abort the real request path.
+            this.healthMonitor.recordFailure(endpoint.name, err);
+        }
+    }
+}

package/dist/rpc/rate-limit.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CreditRateLimiter — token-bucket limiter that meters by *weighted credits*,
+ * not raw request count, because providers charge heavy methods (e.g.
+ * getProgramAccounts) many times a getBalance. Avoiding 429s requires modeling
+ * that weighting client-side.
+ */
+/** Default method weights, modeled on common provider credit tables. */
+export declare const DEFAULT_METHOD_WEIGHTS: Readonly<Record<string, number>>;
+export interface RateLimiterConfig {
+    /** Credits replenished per window. */
+    creditsPerWindow: number;
+    /** Window length in ms. */
+    windowMs: number;
+    /** Per-method weights; falls back to 1 for unknown methods. */
+    weights?: Record<string, number>;
+    /** Clock injection for deterministic tests. */
+    now?: () => number;
+}
+export declare class CreditRateLimiter {
+    private readonly weights;
+    private readonly creditsPerWindow;
+    private readonly windowMs;
+    private readonly now;
+    private availableCredits;
+    private windowStart;
+    constructor(config: RateLimiterConfig);
+    /** Credit cost of a method under the configured weights. */
+    cost(method: string): number;
+    /**
+     * Lazily replenishes the bucket: if a full window has elapsed since
+     * `windowStart`, reset credits and anchor a new window. No timers.
+     */
+    private refill;
+    /** Attempts to spend credits for `method`; returns false if the bucket is dry. */
+    tryAcquire(method: string): boolean;
+    /** Credits currently available (after refill). */
+    available(): number;
+}

package/dist/rpc/rate-limit.js

@@ -0,0 +1,65 @@
+/**
+ * CreditRateLimiter — token-bucket limiter that meters by *weighted credits*,
+ * not raw request count, because providers charge heavy methods (e.g.
+ * getProgramAccounts) many times a getBalance. Avoiding 429s requires modeling
+ * that weighting client-side.
+ */
+/** Default method weights, modeled on common provider credit tables. */
+export const DEFAULT_METHOD_WEIGHTS = {
+    getBalance: 1,
+    getSlot: 1,
+    getBlockHeight: 1,
+    getLatestBlockhash: 1,
+    getSignatureStatuses: 1,
+    sendTransaction: 1,
+    simulateTransaction: 10,
+    getRecentPrioritizationFees: 10,
+    getProgramAccounts: 10,
+    getSignaturesForAddress: 10,
+};
+export class CreditRateLimiter {
+    weights;
+    creditsPerWindow;
+    windowMs;
+    now;
+    availableCredits;
+    windowStart;
+    constructor(config) {
+        this.weights = { ...DEFAULT_METHOD_WEIGHTS, ...config.weights };
+        this.creditsPerWindow = config.creditsPerWindow;
+        this.windowMs = config.windowMs;
+        this.now = config.now ?? Date.now;
+        this.availableCredits = config.creditsPerWindow;
+        this.windowStart = this.now();
+    }
+    /** Credit cost of a method under the configured weights. */
+    cost(method) {
+        return this.weights[method] ?? 1;
+    }
+    /**
+     * Lazily replenishes the bucket: if a full window has elapsed since
+     * `windowStart`, reset credits and anchor a new window. No timers.
+     */
+    refill() {
+        const elapsed = this.now() - this.windowStart;
+        if (elapsed >= this.windowMs) {
+            this.availableCredits = this.creditsPerWindow;
+            this.windowStart = this.now();
+        }
+    }
+    /** Attempts to spend credits for `method`; returns false if the bucket is dry. */
+    tryAcquire(method) {
+        this.refill();
+        const c = this.cost(method);
+        if (this.availableCredits >= c) {
+            this.availableCredits -= c;
+            return true;
+        }
+        return false;
+    }
+    /** Credits currently available (after refill). */
+    available() {
+        this.refill();
+        return this.availableCredits;
+    }
+}

package/dist/testing/base58.d.ts

@@ -0,0 +1,11 @@
+export declare function base58Encode(bytes: Uint8Array): string;
+/** Reads a Solana compact-u16 (shortvec) length prefix. */
+export declare function readShortU16(bytes: Uint8Array, offset: number): {
+    value: number;
+    length: number;
+};
+/**
+ * Extracts the first signature (base58) from a base64-encoded wire transaction.
+ * Wire layout: [compact-u16 signature count][sig0 (64 bytes)]...[message].
+ */
+export declare function firstSignatureFromWireBase64(wireBase64: string): string;

package/dist/testing/base58.js

@@ -0,0 +1,53 @@
+/**
+ * Minimal, dependency-free base58 (Bitcoin alphabet) encoder plus a wire-format
+ * signature extractor. Used so the mock cluster can derive the same transaction
+ * signature that `@solana/kit`'s `getSignatureFromTransaction` produces, letting
+ * tests build/sign a real kit transaction and assert against the mock.
+ */
+const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+export function base58Encode(bytes) {
+    let zeros = 0;
+    while (zeros < bytes.length && bytes[zeros] === 0)
+        zeros++;
+    const digits = [];
+    for (let i = zeros; i < bytes.length; i++) {
+        let carry = bytes[i];
+        for (let j = 0; j < digits.length; j++) {
+            carry += digits[j] << 8;
+            digits[j] = carry % 58;
+            carry = (carry / 58) | 0;
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = (carry / 58) | 0;
+        }
+    }
+    let out = "1".repeat(zeros);
+    for (let i = digits.length - 1; i >= 0; i--)
+        out += ALPHABET[digits[i]];
+    return out;
+}
+/** Reads a Solana compact-u16 (shortvec) length prefix. */
+export function readShortU16(bytes, offset) {
+    let value = 0;
+    let shift = 0;
+    let length = 0;
+    for (;;) {
+        const byte = bytes[offset + length];
+        value |= (byte & 0x7f) << shift;
+        length++;
+        if ((byte & 0x80) === 0)
+            break;
+        shift += 7;
+    }
+    return { value, length };
+}
+/**
+ * Extracts the first signature (base58) from a base64-encoded wire transaction.
+ * Wire layout: [compact-u16 signature count][sig0 (64 bytes)]...[message].
+ */
+export function firstSignatureFromWireBase64(wireBase64) {
+    const bytes = Uint8Array.from(Buffer.from(wireBase64, "base64"));
+    const { length } = readShortU16(bytes, 0);
+    return base58Encode(bytes.slice(length, length + 64));
+}

package/dist/testing/faults.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Fault model for a single simulated RPC endpoint. Every field is optional;
+ * an empty profile is a perfectly healthy node. These map 1:1 to the real
+ * failure modes documented in the problem analysis (drops, 429s, lag, etc.).
+ */
+export interface EndpointFaultProfile {
+    /** Artificial latency in ms. A tuple draws uniformly in [min, max]. */
+    latencyMs?: number | [number, number];
+    /** Probability (0..1) a `sendTransaction` is silently dropped (never lands). */
+    dropRate?: number;
+    /** Probability (0..1) any request fails with a generic transport error. */
+    errorRate?: number;
+    /** Probability (0..1) any request fails with an HTTP 429 rate-limit error. */
+    rate429Rate?: number;
+    /** Slots this node lags behind cluster truth (models a stale/lagging node). */
+    slotLag?: number;
+    /** When true, every request rejects immediately (node down). */
+    offline?: boolean;
+}
+/** Transport-level error carrying an HTTP-style status, like a provider gateway 429/5xx. */
+export declare class HttpTransportError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message?: string);
+}
+/** A request that never produced a response (connection dropped / node offline). */
+export declare class TransportDroppedError extends Error {
+    constructor(message?: string);
+}

package/dist/testing/faults.js

@@ -0,0 +1,16 @@
+/** Transport-level error carrying an HTTP-style status, like a provider gateway 429/5xx. */
+export class HttpTransportError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message ?? `HTTP ${statusCode}`);
+        this.statusCode = statusCode;
+        this.name = "HttpTransportError";
+    }
+}
+/** A request that never produced a response (connection dropped / node offline). */
+export class TransportDroppedError extends Error {
+    constructor(message = "transport request dropped") {
+        super(message);
+        this.name = "TransportDroppedError";
+    }
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public surface of the simulation harness. Tests (and, after handoff, the
+ * Claude Code implementation runs) import everything they need from here.
+ */
+export { MockCluster } from "./mock-cluster.js";
+export type { MockClusterOptions, BlockhashRecord, Commitment } from "./mock-cluster.js";
+export { MockEndpoint } from "./mock-endpoint.js";
+export type { MockEndpointOptions } from "./mock-endpoint.js";
+export { MockJitoEngine, bundleId } from "./mock-jito.js";
+export type { MockJitoOptions, BundleState } from "./mock-jito.js";
+export { type EndpointFaultProfile, HttpTransportError, TransportDroppedError, } from "./faults.js";
+export { makeRng, chance, randInt, type Rng } from "./rng.js";
+export { base58Encode, firstSignatureFromWireBase64 } from "./base58.js";

package/dist/testing/index.js

@@ -0,0 +1,10 @@
+/**
+ * Public surface of the simulation harness. Tests (and, after handoff, the
+ * Claude Code implementation runs) import everything they need from here.
+ */
+export { MockCluster } from "./mock-cluster.js";
+export { MockEndpoint } from "./mock-endpoint.js";
+export { MockJitoEngine, bundleId } from "./mock-jito.js";
+export { HttpTransportError, TransportDroppedError, } from "./faults.js";
+export { makeRng, chance, randInt } from "./rng.js";
+export { base58Encode, firstSignatureFromWireBase64 } from "./base58.js";

package/dist/testing/mock-cluster.d.ts

@@ -0,0 +1,86 @@
+export type Commitment = "processed" | "confirmed" | "finalized";
+export interface MockClusterOptions {
+    initialSlot?: bigint;
+    initialBlockHeight?: bigint;
+    /** Slots between when a tx is accepted and when it lands (default 1). */
+    defaultLandingDelaySlots?: number;
+    /** Seed used to mint deterministic blockhash strings. */
+    blockhashSeed?: number;
+}
+interface PendingTx {
+    signature: string;
+    acceptedAtBlockHeight: bigint;
+    deadlineBlockHeight: bigint;
+    landAtBlockHeight: bigint;
+    dropped: boolean;
+    landedSlot: bigint | null;
+    status: "pending" | "landed" | "expired";
+    err: unknown | null;
+}
+export interface BlockhashRecord {
+    blockhash: string;
+    lastValidBlockHeight: bigint;
+    issuedAtSlot: bigint;
+}
+export declare class MockCluster {
+    slot: bigint;
+    blockHeight: bigint;
+    private readonly defaultLandingDelaySlots;
+    private blockhashCounter;
+    private readonly blockhashSeed;
+    private latest;
+    private readonly txs;
+    /** Per-signature override of landing delay; -1 means "never lands". */
+    private readonly landingOverrides;
+    private prioritizationFees;
+    constructor(opts?: MockClusterOptions);
+    /** Advances the cluster by `n` slots, processing tx landings and expiries. */
+    advanceSlots(n: number): void;
+    /** Force the next tx with this signature to land after `slots` (or never if <0). */
+    scheduleLanding(signature: string, slots: number): void;
+    setPrioritizationFees(fees: bigint[]): void;
+    getTx(signature: string): PendingTx | undefined;
+    private mintBlockhash;
+    rpcGetSlot(): bigint;
+    rpcGetBlockHeight(): bigint;
+    rpcGetLatestBlockhash(): {
+        context: {
+            slot: bigint;
+        };
+        value: {
+            blockhash: string;
+            lastValidBlockHeight: bigint;
+        };
+    };
+    /** Accepts a base64 wire tx (or a raw signature string for low-level tests). */
+    rpcSendTransaction(rawTxOrSig: string, opts?: {
+        dropped?: boolean;
+    }): string;
+    rpcGetSignatureStatuses(signatures: string[]): {
+        context: {
+            slot: bigint;
+        };
+        value: Array<null | {
+            slot: bigint;
+            confirmations: number | null;
+            err: unknown | null;
+            confirmationStatus: Commitment;
+        }>;
+    };
+    rpcSimulateTransaction(): {
+        context: {
+            slot: bigint;
+        };
+        value: {
+            err: unknown | null;
+            logs: string[];
+            unitsConsumed: bigint;
+        };
+    };
+    rpcGetRecentPrioritizationFees(): Array<{
+        slot: bigint;
+        prioritizationFee: bigint;
+    }>;
+    private looksLikeBase64WireTx;
+}
+export {};

package/dist/testing/mock-cluster.js

@@ -0,0 +1,160 @@
+/**
+ * MockCluster — an in-memory, deterministic model of a Solana cluster's RPC
+ * surface, sufficient to exercise the resilience SDK's real behavior offline.
+ *
+ * Design notes:
+ *  - The clock is fully manual: nothing advances unless a test calls
+ *    `advanceSlots()`. This makes blockhash-expiry and rebroadcast timing
+ *    deterministic instead of wall-clock dependent.
+ *  - u64 fields (slot, blockHeight, lastValidBlockHeight, unitsConsumed) are
+ *    returned as `bigint`, matching `@solana/kit` response types.
+ *  - `sendTransaction` accepts the base64 wire tx and derives the signature the
+ *    same way kit does, so a test can sign a real kit transaction and assert.
+ *  - Landing semantics model the two terminal failure modes precisely:
+ *      * silent drop  -> tx stays pending forever, status is always null
+ *      * blockhash expiry -> once blockHeight passes the tx deadline it can
+ *        never land (status stays null); the SDK must give up at
+ *        lastValidBlockHeight rather than poll forever.
+ */
+import { base58Encode, firstSignatureFromWireBase64 } from "./base58.js";
+const BLOCKHASH_VALIDITY_BLOCKS = 150n;
+export class MockCluster {
+    slot;
+    blockHeight;
+    defaultLandingDelaySlots;
+    blockhashCounter = 0;
+    blockhashSeed;
+    latest;
+    txs = new Map();
+    /** Per-signature override of landing delay; -1 means "never lands". */
+    landingOverrides = new Map();
+    prioritizationFees = [10000n, 25000n, 50000n, 75000n, 95000n];
+    constructor(opts = {}) {
+        this.slot = opts.initialSlot ?? 1000n;
+        this.blockHeight = opts.initialBlockHeight ?? 1000n;
+        this.defaultLandingDelaySlots = opts.defaultLandingDelaySlots ?? 1;
+        this.blockhashSeed = opts.blockhashSeed ?? 1;
+        this.latest = this.mintBlockhash();
+    }
+    // --- clock control -------------------------------------------------------
+    /** Advances the cluster by `n` slots, processing tx landings and expiries. */
+    advanceSlots(n) {
+        for (let i = 0; i < n; i++) {
+            this.slot += 1n;
+            this.blockHeight += 1n;
+            for (const tx of this.txs.values()) {
+                if (tx.status !== "pending")
+                    continue;
+                if (tx.dropped)
+                    continue; // silently dropped: never lands
+                if (this.blockHeight > tx.deadlineBlockHeight) {
+                    tx.status = "expired";
+                    continue;
+                }
+                if (tx.landAtBlockHeight >= 0n && this.blockHeight >= tx.landAtBlockHeight) {
+                    tx.status = "landed";
+                    tx.landedSlot = this.slot;
+                }
+            }
+        }
+    }
+    // --- test scripting ------------------------------------------------------
+    /** Force the next tx with this signature to land after `slots` (or never if <0). */
+    scheduleLanding(signature, slots) {
+        this.landingOverrides.set(signature, slots);
+    }
+    setPrioritizationFees(fees) {
+        this.prioritizationFees = fees;
+    }
+    getTx(signature) {
+        return this.txs.get(signature);
+    }
+    // --- internal ------------------------------------------------------------
+    mintBlockhash() {
+        this.blockhashCounter += 1;
+        // Deterministic 32-byte hash -> base58 string.
+        const bytes = new Uint8Array(32);
+        let x = (this.blockhashSeed + this.blockhashCounter * 2654435761) >>> 0;
+        for (let i = 0; i < 32; i++) {
+            x = (x * 1664525 + 1013904223) >>> 0;
+            bytes[i] = x & 0xff;
+        }
+        return {
+            blockhash: base58Encode(bytes),
+            lastValidBlockHeight: this.blockHeight + BLOCKHASH_VALIDITY_BLOCKS,
+            issuedAtSlot: this.slot,
+        };
+    }
+    // --- RPC method implementations (return the JSON-RPC `result` value) ------
+    rpcGetSlot() {
+        return this.slot;
+    }
+    rpcGetBlockHeight() {
+        return this.blockHeight;
+    }
+    rpcGetLatestBlockhash() {
+        this.latest = this.mintBlockhash();
+        return {
+            context: { slot: this.slot },
+            value: {
+                blockhash: this.latest.blockhash,
+                lastValidBlockHeight: this.latest.lastValidBlockHeight,
+            },
+        };
+    }
+    /** Accepts a base64 wire tx (or a raw signature string for low-level tests). */
+    rpcSendTransaction(rawTxOrSig, opts) {
+        const signature = this.looksLikeBase64WireTx(rawTxOrSig)
+            ? firstSignatureFromWireBase64(rawTxOrSig)
+            : rawTxOrSig;
+        const override = this.landingOverrides.get(signature);
+        const delay = override ?? this.defaultLandingDelaySlots;
+        const dropped = opts?.dropped === true || override === -1;
+        if (!this.txs.has(signature)) {
+            this.txs.set(signature, {
+                signature,
+                acceptedAtBlockHeight: this.blockHeight,
+                deadlineBlockHeight: this.latest.lastValidBlockHeight,
+                landAtBlockHeight: dropped ? -1n : this.blockHeight + BigInt(Math.max(0, delay)),
+                dropped,
+                landedSlot: null,
+                status: "pending",
+                err: null,
+            });
+        }
+        return signature;
+    }
+    rpcGetSignatureStatuses(signatures) {
+        return {
+            context: { slot: this.slot },
+            value: signatures.map((sig) => {
+                const tx = this.txs.get(sig);
+                if (!tx || tx.status !== "landed" || tx.landedSlot === null)
+                    return null;
+                const age = Number(this.slot - tx.landedSlot);
+                return {
+                    slot: tx.landedSlot,
+                    confirmations: age >= 32 ? null : age,
+                    err: tx.err,
+                    confirmationStatus: age >= 32 ? "finalized" : "confirmed",
+                };
+            }),
+        };
+    }
+    rpcSimulateTransaction() {
+        return {
+            context: { slot: this.slot },
+            value: { err: null, logs: [], unitsConsumed: 6000n },
+        };
+    }
+    rpcGetRecentPrioritizationFees() {
+        return this.prioritizationFees.map((fee, i) => ({
+            slot: this.slot - BigInt(this.prioritizationFees.length - i),
+            prioritizationFee: fee,
+        }));
+    }
+    looksLikeBase64WireTx(s) {
+        // A base58 signature is <=88 chars; a base64 wire transaction is far longer.
+        return s.length > 100;
+    }
+}