solana-web3-on-steroids 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 solana-web3.js-on_steroids contributors
+
+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,86 @@
+# Solana web3.js on Steroids ⚙️🧱
+
+**A systems-grade resilience layer for `@solana/web3.js`**
+
+Solana UX today is fragile: wallet adapters leak abstractions, RPC behavior is inconsistent, and many integrations fall short of production-grade reliability. **Solana on Steroids** treats crypto UX correctness as a systems problem, making network instability and RPC variability invisible to your users.
+
+[![NPM Version](https://img.shields.io/npm/v/solana-web3-on-steroids)](https://www.npmjs.com/package/solana-web3-on-steroids)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🌩 The Problem: The "Fragile UX" Trap
+
+Standard Solana dApps often suffer from:
+- **Node Lag**: Node A says "confirmed," but Node B (used by the app) says "not found."
+- **Ghost Transactions**: Transactions dropped during congestion with no clear recovery path.
+- **RPC Single-Point-of-Failure**: If your primary RPC provider hiccups, your entire app freezes.
+- **Cryptic Errors**: Raw hex logs and "Simulation failed" messages that confuse users.
+
+## 💊 The Solution: Systems-Grade Resilience
+
+This library wraps `@solana/web3.js` in a robust, automated engine that handles the edge cases of a high-performance blockchain.
+
+### 1. Transparent RPC Failover (Proxy Pattern)
+Uses a JS `Proxy` to wrap the `Connection` object. If a node failure (5xx, network error) is detected, it automatically swaps to a healthy fallback node mid-request. **Your app code stays "dumb" while the infra stays smart.**
+
+### 2. Multi-Node Confirmation Polling
+Doesn't trust a single node's word. It polls multiple RPC providers simultaneously for signature status to bypass node lag and ensure the fastest possible confirmation UI.
+
+### 3. Continuous Re-broadcasting Loop
+Transactions are "babysat" by an engine that refreshes blockhashes and re-broadcasts automatically until a definitive landing or expiration occurs.
+
+### 4. Intelligent Simulation Parsing
+Intercepts simulation logs and translates raw program errors into human-readable insights *before* the user even signs.
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install solana-web3-on-steroids
+```
+
+## 🛠 Quick Start
+
+```typescript
+import { SteroidClient } from 'solana-web3-on-steroids';
+
+const client = new SteroidClient('https://api.mainnet-beta.solana.com', {
+  fallbacks: [
+    'https://solana-mainnet.rpc.extrnode.com',
+    'https://api.alchemy.com/v2/your-key'
+  ],
+  maxRetries: 5,
+  enableLogging: true
+});
+
+// Use it exactly like a standard @solana/web3.js Connection
+const balance = await client.connection.getBalance(myPublicKey);
+
+// Connect a wallet adapter for steroidal transactions
+const steroidWallet = client.connectWallet(walletAdapter);
+const signature = await steroidWallet.signAndSend(transaction);
+```
+
+## 🧬 Core Architecture
+
+### `SteroidConnection`
+A resilient proxy for `web3.js.Connection`.
+- **Health Heartbeat**: Background pings monitor latency and uptime across all fallbacks.
+- **Error classification**: Distinguishes between **Transient** errors (retry same node) and **Node Failures** (failover to next node).
+
+### `SteroidTransaction`
+The heavy-duty engine for submission and confirmation.
+- **Signature Polling**: Parallel checks across `confirmationNodes`.
+- **Blockhash Refresh**: Automatically re-fetches `recentBlockhash` if the transaction has been pending too long, preventing expiration before signing.
+
+---
+
+## 📜 License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## 🤝 Contributing
+
+We treat reliability as a first-class citizen. If you find an edge case where a transaction could be lost or an RPC error could be better handled, please open an issue or PR.

package/dist/client/SteroidClient.d.ts

@@ -0,0 +1,55 @@
+import { SteroidWallet } from '../wallet/SteroidWallet.js';
+import { SteroidTransaction } from '../transaction/SteroidTransaction.js';
+import { SteroidClientConfig, SteroidWalletConfig, ClientStats, RPCHealth, WalletInterface } from '../types/SteroidWalletTypes.js';
+/**
+ * SteroidClient is the main entry point for the Wallet UX Reliability Layer.
+ *
+ * Features:
+ * - Resilient RPC connections with automatic failover
+ * - Smart transaction handling with retries and blockhash refresh
+ * - Normalized wallet error handling
+ * - Production-grade reliability out of the box
+ */
+export declare class SteroidClient {
+    private connection;
+    private transactionEngine;
+    private config;
+    private isDestroyed;
+    /**
+     * Initialize a new SteroidClient.
+     *
+     * @param endpoint The primary Solana RPC endpoint (or array of endpoints)
+     * @param config Optional configuration for connection and wallet behavior
+     */
+    constructor(endpoint: string | string[], config?: SteroidClientConfig);
+    /**
+     * Connect a wallet to the Steroid reliability layer.
+     *
+     * @param wallet A standard Solana wallet adapter
+     * @param walletConfig Optional overrides for this specific wallet
+     * @returns A SteroidWallet instance with enhanced reliability
+     */
+    connectWallet(wallet: WalletInterface, walletConfig?: SteroidWalletConfig): SteroidWallet;
+    /**
+     * Get the underlying transaction engine for advanced use cases.
+     */
+    getTransactionEngine(): SteroidTransaction;
+    /**
+     * Trigger a manual health check across all RPC nodes.
+     */
+    checkAllHealth(): Promise<RPCHealth[]>;
+    /**
+     * Get detailed statistics about RPC performance and failovers.
+     */
+    getStats(): ClientStats;
+    /**
+     * Cleanup resources and stop background monitors.
+     */
+    destroy(): void;
+    private ensureNotDestroyed;
+    private log;
+}
+/**
+ * Convenience factory function to create a SteroidClient.
+ */
+export declare function createSteroidClient(endpoint: string | string[], config?: SteroidClientConfig): SteroidClient;

package/dist/client/SteroidClient.js

@@ -0,0 +1,131 @@
+import { SteroidConnection } from '../connection/SteroidConnection.js';
+import { SteroidWallet } from '../wallet/SteroidWallet.js';
+import { SteroidTransaction } from '../transaction/SteroidTransaction.js';
+import { DEFAULT_CONFIG } from '../types/SteroidWalletTypes.js';
+/**
+ * SteroidClient is the main entry point for the Wallet UX Reliability Layer.
+ *
+ * Features:
+ * - Resilient RPC connections with automatic failover
+ * - Smart transaction handling with retries and blockhash refresh
+ * - Normalized wallet error handling
+ * - Production-grade reliability out of the box
+ */
+export class SteroidClient {
+    connection;
+    transactionEngine;
+    config;
+    isDestroyed = false;
+    /**
+     * Initialize a new SteroidClient.
+     *
+     * @param endpoint The primary Solana RPC endpoint (or array of endpoints)
+     * @param config Optional configuration for connection and wallet behavior
+     */
+    constructor(endpoint, config = {}) {
+        this.config = config;
+        // Initialize resilient connection
+        const endpoints = Array.isArray(endpoint) ? endpoint : [endpoint];
+        const [primary, ...additionalFallbacks] = endpoints;
+        const connectionConfig = {
+            ...DEFAULT_CONFIG.CONNECTION,
+            ...config.connection,
+            fallbacks: [
+                ...(config.connection?.fallbacks || []),
+                ...additionalFallbacks
+            ],
+            enableLogging: config.enableLogging ?? config.connection?.enableLogging ?? DEFAULT_CONFIG.CONNECTION.enableLogging,
+        };
+        this.connection = new SteroidConnection(primary, connectionConfig);
+        this.transactionEngine = new SteroidTransaction(this.connection);
+        this.log('info', 'Initialized with endpoint(s):', endpoint);
+    }
+    /**
+     * Connect a wallet to the Steroid reliability layer.
+     *
+     * @param wallet A standard Solana wallet adapter
+     * @param walletConfig Optional overrides for this specific wallet
+     * @returns A SteroidWallet instance with enhanced reliability
+     */
+    connectWallet(wallet, walletConfig = {}) {
+        this.ensureNotDestroyed();
+        const mergedConfig = {
+            ...DEFAULT_CONFIG.WALLET,
+            ...this.config.wallet,
+            ...walletConfig,
+            enableLogging: this.config.enableLogging ?? walletConfig.enableLogging ?? DEFAULT_CONFIG.WALLET.enableLogging,
+        };
+        return new SteroidWallet(wallet, this.connection, mergedConfig);
+    }
+    /**
+     * Get the underlying transaction engine for advanced use cases.
+     */
+    getTransactionEngine() {
+        this.ensureNotDestroyed();
+        return this.transactionEngine;
+    }
+    /**
+     * Trigger a manual health check across all RPC nodes.
+     */
+    async checkAllHealth() {
+        this.ensureNotDestroyed();
+        return await this.connection.checkHealth();
+    }
+    /**
+     * Get detailed statistics about RPC performance and failovers.
+     */
+    getStats() {
+        this.ensureNotDestroyed();
+        return {
+            activeEndpoint: this.connection.getActiveEndpoint(),
+            allEndpoints: this.connection.getEndpoints(),
+            failoverStats: this.connection.getFailoverStats(),
+            healthStatus: this.connection.getHealthStatus(),
+        };
+    }
+    /**
+     * Cleanup resources and stop background monitors.
+     */
+    destroy() {
+        if (this.isDestroyed)
+            return;
+        this.connection.destroy();
+        this.isDestroyed = true;
+        this.log('info', 'Destroyed');
+    }
+    ensureNotDestroyed() {
+        if (this.isDestroyed) {
+            throw new Error('[SteroidClient] Cannot execute operation: instance is already destroyed');
+        }
+    }
+    log(level, ...args) {
+        if (!this.config.enableLogging)
+            return;
+        const prefix = '[SteroidClient]';
+        const finalArgs = [...args];
+        if (typeof finalArgs[0] === 'string') {
+            finalArgs[0] = `${prefix} ${finalArgs[0]}`;
+        }
+        else {
+            finalArgs.unshift(prefix);
+        }
+        switch (level) {
+            case 'info':
+                console.log(...finalArgs);
+                break;
+            case 'warn':
+                console.warn(...finalArgs);
+                break;
+            case 'error':
+                console.error(...finalArgs);
+                break;
+        }
+    }
+}
+/**
+ * Convenience factory function to create a SteroidClient.
+ */
+export function createSteroidClient(endpoint, config) {
+    return new SteroidClient(endpoint, config);
+}
+//# sourceMappingURL=SteroidClient.js.map

package/dist/client/SteroidClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SteroidClient.js","sourceRoot":"","sources":["../../src/client/SteroidClient.ts"],"names":[],"mappings":"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"}

package/dist/connection/SteroidConnection.d.ts

@@ -0,0 +1,96 @@
+import { SteroidConnectionConfig, RPCHealth } from '../types/SteroidWalletTypes.js';
+/**
+ * SteroidConnection uses a Proxy pattern to wrap a real @solana/web3.js Connection.
+ * This allows swapping the underlying connection (and its internal state/websockets)
+ * transparently when a failover occurs.
+ */
+export declare class SteroidConnection {
+    private static readonly DEFAULT_HEALTH_CHECK_TIMEOUT_MS;
+    private static readonly MAX_BACKOFF_DELAY_MS;
+    private static readonly JITTER_MS;
+    private activeConnection;
+    private urls;
+    private currentUrlIndex;
+    private config;
+    private steroidConfig;
+    private healthStatus;
+    private healthCheckTimer?;
+    private failoverCount;
+    private lastFailoverTime;
+    constructor(endpoint: string, config?: SteroidConnectionConfig);
+    /**
+     * Executes a connection method with intelligent retries and failover.
+     */
+    private executeWithResilience;
+    /**
+     * Internal helper to execute a method with a promise-based timeout and AbortController.
+     * This effectively cancels the underlying network request on timeout.
+     */
+    private callWithTimeout;
+    /**
+     * Updates health status for a specific URL.
+     */
+    private updateHealthStatus;
+    /**
+     * Decides whether to retry or failover based on the error.
+     * @returns true if the loop should continue (retry or failover), false if it should throw.
+     */
+    private handleExecutionError;
+    private parseErrorContext;
+    /**
+     * Identifies transient errors that should be retried on the same node (e.g. rate limits).
+     */
+    private isTransientError;
+    /**
+     * Identifies node-level failures that should trigger a failover to a different RPC.
+     */
+    private isNodeFailure;
+    /**
+     * Switches to the next available RPC node.
+     */
+    private switchToNextRpc;
+    /**
+     * Finds the index of the next healthy RPC, or the very next one if all are unhealthy.
+     */
+    private findNextAvailableRpcIndex;
+    private calculateBackoff;
+    private sleep;
+    private enhanceError;
+    private log;
+    /**
+     * Perform health checks on all RPC endpoints.
+     */
+    private performHealthCheck;
+    /**
+     * Internal helper to check the health of a single RPC node.
+     */
+    private checkNodeHealth;
+    private startHealthChecks;
+    /**
+     * Clean up resources when done.
+     */
+    destroy(): void;
+    /**
+     * Get all endpoints for multi-node verification.
+     */
+    getEndpoints(): string[];
+    /**
+     * Get current active endpoint.
+     */
+    getActiveEndpoint(): string;
+    /**
+     * Get health status of all endpoints.
+     */
+    getHealthStatus(): RPCHealth[];
+    /**
+     * Get failover statistics.
+     */
+    getFailoverStats(): {
+        count: number;
+        lastTime: number;
+    };
+    /**
+     * Manually trigger a health check.
+     */
+    checkHealth(): Promise<RPCHealth[]>;
+}