RPC Test Suite

A comprehensive CLI tool for stress testing and benchmarking Solana RPC endpoints with customizable concurrency and account inputs. This tool helps developers evaluate the performance of different RPC endpoints, optimize applications, and identify potential bottlenecks -- especially when configuring Lantern.

🚀 Features

• Comprehensive Test Suite: Run all RPC methods simultaneously with the runall command
• Dynamic Configuration: Generate and load test configurations with API keys
• Smart Progress Tracking: Real-time progress bars and detailed statistics with dynamic updates
• Dynamic Latency Display: Automatic unit selection (μs, ms, s) based on performance
• Test different Solana RPC methods (getAccountInfo, getProgramAccounts, getMultipleAccounts)
• Configure concurrency level for parallel requests
• Specify test duration
• Provide accounts/programs individually or from a file
• Seed account addresses from programs for testing purposes
• Comprehensive performance metrics (requests/second, latency statistics)
• Limit the number of accounts/programs to process
• Real-time progress tracking with visual progress bars during testing
• Dual RPC architecture for seeding vs testing separation

📋 Table of Contents

• Installation
• Quick Start
• Project Structure
• Architecture Overview
• Usage
• Configuration
• API Reference
• Examples
• Troubleshooting

🛠️ Installation

Prerequisites

• Go 1.24.2 or higher
• Git

Run the Benchmark Server

This will run a local server that the Lantern configuration tool can connect to and use.

# Clone the repository
git clone https://github.com/alphabatem/RPC_tests
cd rpc_test

# Install Prerequisites
go mod tidy

# Build the application
go run server.go

Build from Source

# Clone the repository
git clone https://github.com/alphabatem/RPC_tests
cd rpc_test

# Build the application
go build -o rpc_test

# Make it executable (Linux/macOS)
chmod +x rpc_test

Verify Installation

# Check if the binary was created successfully
./rpc_test --help

🚀 Quick Start

Comprehensive Testing with runall

The runall command provides a complete testing workflow:

# Run comprehensive test suite with API key and target RPC
./rpc_test runall --api-key YOUR_API_KEY --url https://your-target-rpc.com

# Run with custom settings
./rpc_test runall --api-key YOUR_API_KEY --url https://your-target-rpc.com --concurrency 10 --duration 30

# Limit accounts used for testing
./rpc_test runall --api-key YOUR_API_KEY --url https://your-target-rpc.com --limit 50

What runall does:

1. Generates test configuration with your API key
2. Creates data directory (./data/) for storing test files
3. Seeds 100 accounts from the specified program using remote RPC and gPA
4. Runs all RPC methods concurrently against your target RPC, using seeded accounts as needed
5. Provides comprehensive statistics with dynamic latency display and real-time progress tracking

📁 Project Structure

rpc_test/
├── main.go                 # Application entry point
├── go.mod                  # Go module dependencies
├── go.sum                  # Dependency checksums
├── README.md              # This file
├── config-template.json   # Template configuration file
├── config.json            # Generated configuration (gitignored)
├── .gitignore             # Git ignore rules
├── rpc_test               # Compiled binary (gitignored)
├── cmd/                   # Command implementations
│   ├── root.go           # Root command and global flags
│   ├── common.go         # Shared utilities and variables
│   ├── runall.go         # Comprehensive test suite command
│   ├── getAccountInfo.go # getAccountInfo RPC testing
│   ├── getMultipleAccounts.go # getMultipleAccounts RPC testing
│   ├── getProgramAccounts.go # getProgramAccounts RPC testing
│   └── seed.go           # Account seeding functionality
├── methods/               # RPC method implementations
│   ├── rpc.go            # Base RPC client wrapper
│   ├── getAccountInfo.go # getAccountInfo implementation
│   ├── getMultipleAccounts.go # getMultipleAccounts implementation
│   ├── getProgramAccounts.go # getProgramAccounts implementation
│   └── seed.go           # Account seeding logic
├── data/                  # Test data and generated files
│   └── test_accounts.txt # Generated test accounts
└── *.txt                 # Example account/program files

🏗️ Architecture Overview

Core Components

1. Command Layer (cmd/): Implements CLI commands using Cobra framework
2. Method Layer (methods/): Contains RPC method implementations using solana-go
3. Configuration Management: Dynamic config generation and loading
4. Progress Tracking: Real-time progress monitoring with visual feedback
5. Statistics: Comprehensive metrics calculation and reporting

Dual RPC Architecture

The runall command uses a uses two RPCs. This lets you get program accounts from one RPC (the "remote" RPC), then use those to build tests against another (the "target"). This is mainly useful in testing Lantern, by setting Lantern as the target RPC.

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Remote RPC    │    │   Target RPC    │    │   Local Files   │
│   (Config)      │    │   (--url flag)  │    │   (data/)       │
├─────────────────┤    ├─────────────────┤    ├─────────────────┤
│ • Seeding       │    │ • Testing       │    │ • Account lists │
│ • Data fetch    │    │ • Benchmarking  │    │ • Config files  │
│ • Reliable      │    │ • Performance   │    │ • Results       │
│ • API key auth  │    │ • Load testing  │    │ • Logs          │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Execution Steps

1. Configuration Phase: Generate/load config with API keys
2. Seeding Phase: Fetch account data from reliable remote RPC
3. Testing Phase: Run tests against target RPC endpoint
4. Analysis Phase: Calculate and display comprehensive statistics

📖 Usage

Comprehensive Testing

# Basic comprehensive test (requires --url flag)
./rpc_test runall --api-key YOUR_API_KEY --url https://your-target-rpc.com

# Advanced comprehensive test
./rpc_test runall --api-key YOUR_API_KEY --url https://your-target-rpc.com --concurrency 15 --duration 45 --limit 200

Individual Method Testing

# Basic usage for getAccountInfo
./rpc_test getAccountInfo --account <ACCOUNT_ADDRESS> --concurrency 10 --duration 30

# Using an account file for getAccountInfo
./rpc_test getAccountInfo --account-file accounts.txt --concurrency 10 --duration 30

# Basic usage for getMultipleAccounts
./rpc_test getMultipleAccounts --account <ACCOUNT_ADDRESS> --concurrency 10 --duration 30

# Using multiple accounts for getMultipleAccounts (will batch 5-15 accounts randomly)
./rpc_test getMultipleAccounts --account addr1 --account addr2 --account addr3 --concurrency 10 --duration 30

# Basic usage for getProgramAccounts
./rpc_test getProgramAccounts --program <PROGRAM_ADDRESS> --concurrency 50 --duration 60

# Using a program file for getProgramAccounts
./rpc_test getProgramAccounts --program-file programs.txt --concurrency 50 --duration 60

# Seed account data from a program for testing
./rpc_test seed --program <PROGRAM_ADDRESS> --output accounts.txt

# Seed account data with a limit of 1000 accounts
./rpc_test seed --program <PROGRAM_ADDRESS> --output accounts.txt --limit 1000

# Test with limited number of accounts
./rpc_test getAccountInfo --account-file accounts.txt --limit 100 --concurrency 10

Available Commands

• runall: Execute comprehensive test suite with all methods
• getAccountInfo: Run tests against the getAccountInfo RPC method
• getMultipleAccounts: Run tests against the getMultipleAccounts RPC method
• getProgramAccounts: Run tests against the getProgramAccounts RPC method
• seed: Fetch program accounts and save their addresses to a file for testing purposes

Global Flags (applicable to all commands)

• -u, --url: RPC endpoint URL (default: "https://api.mainnet-beta.solana.com")
• -c, --concurrency: Number of concurrent requests (default: 1)
• -d, --duration: Test duration in seconds (default: 10)
• -a, --account: Account addresses to use in tests (can be specified multiple times)
• -f, --account-file: File containing account addresses (one per line)
• -l, --limit: Limit the number of accounts/programs to process (0 for no limit)
• -k, --api-key: API key for RPC endpoint (available globally, saved in config by runall)

Command-specific Flags

runall

• -k, --api-key: API key for RPC endpoint (will be saved in config) REQUIRED
• -u, --url: Target RPC endpoint URL for testing REQUIRED
• -c, --concurrency: Number of concurrent requests per method (default: 5)
• -d, --duration: Test duration in seconds per method (default: 15)
• -l, --limit: Limit the number of accounts to use (0 for no limit)

Note: Both --api-key and --url flags are REQUIRED for runall command.

getAccountInfo

• -a, --account: Accounts to use in tests (accepts multiple accounts, will rotate between them)
• -f, --account-file: File containing accounts (one per line, requests sent will rotate between them)

getMultipleAccounts

• -a, --account: Accounts to use in tests (will rotate between specified accounts in blocks of 5-15, randomly selected)
• -f, --account-file: File containing accounts (one per line, will rotate between them)

Note: getMultipleAccounts automatically batches accounts (5-15 per request) from your provided account list.

getProgramAccounts

• -p, --program: Program accounts to use in tests (can specify more than one)
• -f, --program-file: File containing program accounts (one per line)

Note: For getProgramAccounts, the -f flag uses --program-file instead of --account-file.

seed

• -p, --program: Program accounts to fetch accounts from (can specify multiple programs)
• -f, --program-file: File containing program accounts (one per line)
• -o, --output: Output file to store program accounts for future tests (default: "accounts.txt")

⚙️ Configuration

Configuration File Structure

The application generates a config.json file with the following structure:

Account File (for getAccountInfo and getMultipleAccounts)

9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin
6ycRTkj1RM3L4sZcKHk8HULaFvEBaLGAiQpVpC9MPcKm
7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2

Program File (for getProgramAccounts and seed)

2wT8Yq49kHgDzXuPxZSaeLaH1qbmGXtEyPy64bL7aD3c
FLUXubRmkEi2q6K3Y9kBPg9248ggaZVsoSFhtJHSrm1X
whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc

Generated Config File (runall command)

{
  "maximum_ram": 8,
  "maximum_disk": 10,
  "location": "./data/",
  "mode": "normal",
  "cache_requests": false,
  "monitoring": false,
  "monitoring_url": "",
  "log_level": "INFO",
  "rpc_url": "https://us.rpc.fluxbeam.xyz",
  "rpc_apikey": "YOUR_API_KEY_HERE",
  "programs": {
    "2wT8Yq49kHgDzXuPxZSaeLaH1qbmGXtEyPy64bL7aD3c": {
      "discriminator": 2,
      "filters": []
    }
  }
}

Configuration Management

1. Auto-generation: The runall command automatically generates a default configuration
2. API Key Storage: API keys are securely stored in the config file
3. Template-based: Uses config-template.json as a base template
4. Dynamic Loading: Configuration is loaded at runtime
5. Data Directory: Automatically creates ./data/ directory for storing test files and results

📊 API Reference

RPC Methods Supported

getAccountInfo

• Purpose: Fetch account information for specific addresses
• Use Case: Testing account data retrieval performance
• Parameters: Account addresses (single or multiple)
• Rotation: Cycles through provided accounts for load distribution

getMultipleAccounts

• Purpose: Fetch information for multiple accounts in a single request
• Use Case: Testing batch account data retrieval
• Parameters: Multiple account addresses
• Batching: Automatically groups 5-15 accounts per request (randomized)

getProgramAccounts

• Purpose: Fetch all accounts owned by a specific program
• Use Case: Testing program account enumeration
• Parameters: Program addresses

Performance Metrics

The test suite reports comprehensive metrics:

Basic Metrics

• Total Duration: Actual time taken to complete the test
• Total Requests: Number of requests processed
• Successful Requests: Count and percentage of successful requests
• Failed Requests: Count and percentage of failed requests
• Requests per second: Average number of requests processed per second

Enhanced Latency Statistics (Dynamic Units)

• Min Latency: Minimum request latency (auto-formatted: μs, ms, or s)
• Max Latency: Maximum request latency (auto-formatted: μs, ms, or s)
• Avg Latency: Average request latency (auto-formatted: μs, ms, or s)

Real-time Progress Tracking

• Visual Progress Bars: Real-time progress display with completion percentage
• Live Statistics: Current RPS, request counts, and elapsed time
• Method-specific Progress: Individual progress tracking for each RPC method in runall

Comprehensive Test Results (runall command)

• Individual Method Results: Detailed stats for each RPC method
• Overall Test Summary: Combined statistics across all methods
• Performance Insights: Best/worst performing methods with ratios
• Latency Comparison: Fastest vs slowest methods with performance ratios

📝 Examples

Example File Format

Account File (for getAccountInfo and getMultipleAccounts)

9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin
6ycRTkj1RM3L4sZcKHk8HULaFvEBaLGAiQpVpC9MPcKm
7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2

Program File (for getProgramAccounts and seed)

2wT8Yq49kHgDzXuPxZSaeLaH1qbmGXtEyPy64bL7aD3c
FLUXubRmkEi2q6K3Y9kBPg9248ggaZVsoSFhtJHSrm1X
whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc

Example Output

runall Command Output

🚀 Starting comprehensive RPC test suite...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Step 1: Generating test configuration...
[██████████████████████████████] Config generated... ✅
✅ Test configuration saved to: ./config.json

📂 Step 1.5: Loading configuration with API key...
[██████████████████████████████] Config loaded... ✅
✅ Configuration loaded successfully

🌱 Step 2: Seeding accounts from program...
  🔍 Using remote RPC for seeding: https://us.rpc.fluxbeam.xyz
  🔍 Fetching accounts from program 2wT8Yq49k...
  ✅ Successfully seeded accounts
✅ Accounts seeded to: ./data/test_accounts.txt

⚡ Step 3: Running all RPC methods...
  🎯 Using target RPC for testing: https://your-target-rpc.com
  📊 Testing 3 methods with 100 accounts
  ⚙️  Concurrency: 5, Duration: 15s per method
  🔄 [1/3] Starting getAccountInfo test...
  🔄 [2/3] Starting getMultipleAccounts test...
  🔄 [3/3] Starting getProgramAccounts test...
    [████████████████░░░░] getAccountInfo: 80.0% | 12s/15s | Requests: 1250 | RPS: 104.2
    [███████████████░░░░░] getMultipleAccounts: 73.3% | 11s/15s | Requests: 1100 | RPS: 100.0
    [█████████████████░░░] getProgramAccounts: 86.7% | 13s/15s | Requests: 1300 | RPS: 100.0
    ✅ getAccountInfo completed successfully
    ✅ getMultipleAccounts completed successfully
    ✅ getProgramAccounts completed successfully

📊 Step 4: Generating comprehensive statistics...
[██████████████████████████████] Statistics calculated... ✅

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 COMPREHENSIVE TEST RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔍 INDIVIDUAL METHOD RESULTS:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📈 GETACCOUNTINFO:
   Duration:         15.00 seconds
   Total Requests:    1250
   Successful:        1245 (99.60%)
   Failed:            5 (0.40%)
   Requests/second:   83.00
   Min Latency:       45.23 μs
   Max Latency:       125.67 μs
   Avg Latency:       78.45 μs

🎯 OVERALL TEST SUMMARY:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🕒 Total Duration:     45.00 seconds
🔢 Total Requests:      3650
✅ Total Successful:    3635 (99.59%)
❌ Total Failed:        15 (0.41%)
⚡ Overall RPS:         81.11
📊 Methods Tested:      3

💡 PERFORMANCE INSIGHTS:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🏆 Best Performing:    getAccountInfo (83.00 RPS)
🐌 Worst Performing:   getProgramAccounts (80.00 RPS)
📊 Performance Ratio:  96.4% (worst/best)

⏱️  LATENCY COMPARISON:
⚡ Fastest Method:     getAccountInfo (78.45 μs avg)
🐌 Slowest Method:     getProgramAccounts (245.12 μs avg)
📊 Latency Ratio:      3.1x (slowest/fastest)

✅ Comprehensive test suite completed successfully!

🔧 Troubleshooting

Common Issues

1. API Key Authentication Errors

Error: authentication failed

Solution: Ensure your API key is valid and has the necessary permissions. You can get a free API key at FluxRPC

2. RPC Endpoint Connection Issues

Error: connection refused

Solution: Verify the RPC endpoint URL and check network connectivity. FluxRPC endpoints are available by logging in and navigating to the "API Keys" page.

3. Rate Limiting

Error: rate limit exceeded

Solution: Reduce concurrency or increase delays between requests.

4. Insufficient Account Data

Error: no accounts found

Solution: Check if the program address is valid and contains accounts.

Debug Mode

Enable verbose logging for debugging:

# Set log level to DEBUG
export LOG_LEVEL=DEBUG
./rpc_test runall --api-key YOUR_API_KEY --url https://your-target-rpc.com

Performance Optimization

1. Concurrency Tuning: Start with low concurrency and gradually increase
2. Duration Adjustment: Use longer durations for more accurate metrics
3. Account Limits: Limit accounts for faster testing iterations
4. Network Optimization: Use RPC endpoints closer to your location (https://configurator.fluxrpc.com/ will try and auto-detect this for you)

🛠️ Development

Prerequisites

• Go 1.24.2+
• Git
• Make (optional, for build scripts)

Development Setup

# Clone the repository
git clone <repository-url>
cd rpc_test

# Install dependencies
go mod download

# Run tests
go test ./...

# Build for development
go build -o rpc_test

# Run with development flags
./rpc_test --help

Project Dependencies

Key dependencies used in this project:

• github.com/spf13/cobra: CLI framework
• github.com/gagliardetto/solana-go: Solana blockchain interaction
• go.uber.org/zap: Structured logging
• github.com/fatih/color: Colored terminal output

Code Structure

Command Layer (cmd/)

• root.go: Main command setup and global flags
• common.go: Shared utilities and variables
• runall.go: Comprehensive test suite implementation
• getAccountInfo.go: getAccountInfo command
• getMultipleAccounts.go: getMultipleAccounts command
• getProgramAccounts.go: getProgramAccounts command
• seed.go: Account seeding command

Method Layer (methods/)

• rpc.go: Base RPC client wrapper
• getAccountInfo.go: getAccountInfo RPC implementation
• getMultipleAccounts.go: getMultipleAccounts RPC implementation
• getProgramAccounts.go: getProgramAccounts RPC implementation
• seed.go: Account seeding logic

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific test
go test ./methods -v

# Run benchmarks
go test -bench=. ./...

Building

# Build for current platform
go build -o rpc_test

# Build for specific platform
GOOS=linux GOARCH=amd64 go build -o rpc_test_linux
GOOS=darwin GOARCH=amd64 go build -o rpc_test_macos
GOOS=windows GOARCH=amd64 go build -o rpc_test_windows.exe

🙏 Acknowledgments

• Solana Labs for the Solana blockchain
• Gagliardetto for the excellent solana-go library
• The Solana community for feedback and contributions