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