Waterfall RPC

A universal RPC provider with waterfall fallback mechanism for Ethereum networks. This library automatically fetches and manages RPC endpoints from Chainlist (https://github.com/DefiLlama/chainlist), providing a reliable way to interact with various Ethereum networks.

Features

• Compatibility with EthersJS and Viem
• Can be used for web based wallets
• Automatically fetches and caches RPC endpoints from Chainlist
• Implements a waterfall fallback mechanism for reliable RPC access
• Supports all Ethereum networks listed on Chainlist
• Automatic RPC endpoint health checking
• Weekly automatic updates of RPC endpoints
• Built-in progress display during RPC validation
• Customizable progress tracking

Installation

npm install @smarttokenlabs/waterfall-rpc

Usage

EthersJS

Basic Usage (with built-in progress display)

Display name of USDC

import{WaterfallRpc}from"@smarttokenlabs/waterfall-rpc";import{ethers}from"ethers";consterc20Abi=["function balanceOf(address owner) view returns (uint256 balance)","function name() view returns (string)"];constusdcAddress="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";conststart=async()=>{constprovider=awaitWaterfallRpc.createProvider(1);constcontract=newethers.Contract(usdcAddress,erc20Abi,provider);constusdcName=awaitcontract.name();console.log('USDC Name:',usdcName);};start();

Get blocknumber for Base Sepolia

import{WaterfallRpc}from'@smarttokenlabs/waterfall-rpc';// Create a provider for Base Sepolia (will show progress automatically)constprovider=awaitWaterfallRpc.createProvider(84532);// Use the provider with ethers.jsconstblockNumber=awaitprovider.getBlockNumber();console.log(`Current block number: ${blockNumber}`);

Custom Progress Display

Note: Only shown when the library runs for the first time (per chain). This validates the RPCs given in chainlist.org as some have gone dark.

import{WaterfallRpc,ProgressCallback}from'@smarttokenlabs/waterfall-rpc';// Create a custom progress callbackconstcustomProgress: ProgressCallback=(event)=>{console.log(`Validating RPC ${event.current}/${event.total}: ${event.url}`);console.log(`Status: ${event.status}`);};// Create a provider with custom progress displayconstprovider=awaitWaterfallRpc.createProvider(84532,customProgress);

Disable Progress Display

import{WaterfallRpc}from'@smarttokenlabs/waterfall-rpc';// Create a provider without progress displayconstprovider=awaitWaterfallRpc.createProvider(84532,()=>{});

Viem

import{createWaterfallPublicClient}from'@smarttokenlabs/waterfall-rpc/viem';import{mainnet}from'viem/chains';constclient=awaitcreateWaterfallPublicClient(mainnet,{useWebCache: true,// in the browser, optional});constblock=awaitclient.getBlockNumber();

API Documentation

WaterfallRpc

The main class that provides a reliable RPC connection with fallback support.

Static Methods

• createProvider(chainId: number, onProgress?: ProgressCallback): Promise<WaterfallRpc>
  • Creates a new provider instance for the specified chain ID
  • Automatically checks and filters working RPC endpoints
  • Shows a progress bar by default
  • Optional custom progress callback

Types

interfaceProgressEvent{current: number;// Current RPC being checked (1-based)total: number;// Total number of RPCs to checkurl: string;// URL of the RPC being checkedstatus: 'checking'|'success'|'failed';// Current status of the check}typeProgressCallback=(event: ProgressEvent)=>void;

Instance Methods

• All standard ethers.js provider methods are available
• The provider automatically handles RPC failures and retries with different endpoints

License

MIT