solana-ts

A zero-idle-CPU local Solana RPC simulator powered by LiteSVM. Drop-in replacement for solana-test-validator that starts instantly, uses no CPU when idle, and persists state to a SQLite file.

Why

solana-test-validator ships a full validator binary — PoH, gossip, turbine, replay, leader schedule, voting — and burns CPU even when nothing is happening. This project strips all of that away and keeps only what matters for local app testing: an in-process SVM execution engine behind a Solana-compatible JSON-RPC server.

• Starts in under a second
• Zero CPU at idle (no slot ticking, no block production loop)
• Transactions execute synchronously and are immediately "confirmed"
• State persists to a single SQLite file across restarts
• Wire-compatible with @solana/web3.js v1 Connection

Quick start

# Node 22.13+ is required for the built-in `node:sqlite` module
pnpm install
pnpm dev

The server listens on http://127.0.0.1:8899 (HTTP JSON-RPC) and ws://127.0.0.1:8900 (WebSocket PubSub).

Connect from any Solana app:

import { Connection } from "@solana/web3.js";

const connection = new Connection("http://localhost:8899", "confirmed");

CLI

solana-ts [options]

Options:
  -H, --host <address>             Bind address (default: "127.0.0.1")
  -p, --port <number>              HTTP/WS port (default: 8899)
  -l, --ledger <path>              SQLite database path (default: ~/.solana-ts/ledger.db)
      --reset                      Clear ledger on start
      --transaction-history <n>    Max transactions to retain (default: 5000)
      --log-level <level>          error | warn | info | debug (default: "info")
  -q, --quiet                      Suppress all output except errors
  -V, --version                    Output version number
  -h, --help                       Display help

Examples:

# Start with default settings
pnpm dev

# Bind to all interfaces on port 9000, fresh ledger each time
pnpm dev -- --host 0.0.0.0 --port 9000 --reset

# Use a specific ledger file
pnpm dev -- --ledger ./my-ledger.db

Supported RPC methods

| Method | Notes | |---|---| | getVersion | | | getHealth | | | getSlot | | | getBlockHeight | | | getLatestBlockhash | | | isBlockhashValid | | | getBalance | | | getAccountInfo | base64 encoding | | getMultipleAccounts | base64 encoding | | getMinimumBalanceForRentExemption | | | requestAirdrop | | | sendTransaction | base58 and base64 encoding | | simulateTransaction | | | getSignatureStatuses | | | getTransaction | JSON-decoded format | | getEpochInfo | | | getGenesisHash | Static value | | getRecentBlockhash | Legacy compat | | getFeeForMessage | Returns 5000 | | getIdentity | |

WebSocket subscriptions:

| Method | Notes | |---|---| | signatureSubscribe / signatureUnsubscribe | Required by confirmTransaction |

Architecture

@solana/web3.js  ─── HTTP JSON-RPC ──→  RPC Dispatcher  ──→  Method Handlers
                 ─── WebSocket ──────→  Subscription Mgr ─┘        │
                                                               SVM Engine
                                                              ┌────┴────┐
                                                          LiteSVM    SQLite

Transactions execute synchronously inside LiteSVM. After each transaction, modified account state is persisted to SQLite via Node's built-in node:sqlite module. On restart, accounts and slot counter are restored from the database.

WebSocket runs on port+1 (e.g. 8900) to match the convention used by @solana/web3.js, which derives the WS URL as rpc_port + 1.

Persistence

State is stored in a single SQLite file (default ~/.solana-ts/ledger.db):

• accounts — address, lamports, data, owner, executable flag, rent epoch
• transactions — signature, slot, raw bytes, JSON metadata, block time
• metadata — key-value pairs (slot counter, etc.)

Use --reset to clear all state on startup.

Tests

pnpm test

Runs 36 tests covering basic RPC methods, airdrop/transfer flows, and persistence across server restarts (balance restore, slot resume, transaction history, --reset behavior, transacting on restored state).

Project structure

src/
  index.ts              CLI entry point
  server.ts             HTTP + WebSocket server
  engine.ts             LiteSVM wrapper with persistence
  persistence.ts        SQLite storage layer
  types.ts              Shared types and logger
  rpc/
    dispatcher.ts       JSON-RPC 2.0 routing
    methods.ts          RPC method handlers
    subscriptions.ts    WebSocket subscription manager
  test.ts               Integration tests