A powerful, fork-based simulation engine for testing Solana blockchain applications, DeFi protocols, and smart contracts in an isolated, fast, and cost-effective environment.
The Solana Simulation Engine provides a lightweight, isolated environment for testing Solana blockchain applications without the need for real SOL or mainnet interactions. It uses LiteSVM to create fork-based simulations that mimic the behavior of the Solana network, enabling developers to test complex DeFi protocols, token operations, and smart contract interactions safely and efficiently.
-
Fork-Based Simulation: Create isolated blockchain states using LiteSVM
-
SOL Operations: Airdrop, transfer, and balance checking
-
Token Operations: USDC/USDT airdrops, transfers, and balance queries
-
Transaction Simulation: Test complex multi-instruction transactions
-
Protocol Testing: DeFi-style deposits, swaps, and interactions
-
Transaction History: Complete audit trail of all operations
-
Auto-Expiration: Forks automatically clean up after 15 minutes
-
User Isolation: Each user gets their own fork with separate state
-
Concurrent Testing: Multiple users can test simultaneously
-
Real-Time Monitoring: Health checks and fork status endpoints
-
Comprehensive Logging: Detailed operation logs for debugging
| Operation | Description | RPC Method |
|---|---|---|
| SOL Airdrop | Drop SOL to any address | requestAirdrop |
| SOL Transfer | Transfer SOL between accounts | sendTransaction |
| Balance Check | Get SOL balance | getBalance |
| Token Airdrop | Mint tokens to accounts | airdropToken |
| Token Balance | Check token balances | getTokenAccountBalance |
| Transaction History | Get operation history | getTransactionHistory |
| Blockhash | Get recent blockhash | getLatestBlockhash |
| Account Info | Get account details | getAccountInfo |
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Solana Simulation Engine - Flow │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────┐ HTTP Request ┌───────────────────┐ Route Method ┌───────────────────┐ │
│ │ Client │────────────────▶│ Express Server │────────────────▶│ RPC Handler │ │
│ │ (Tests) │ (JSON-RPC) │ (server.ts) │ │ (rpcHandler.ts) │ │
│ └───────────┘ └───────────────────┘ └───────────────────┘ │
│ │ │
│ │ Call Handler │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ Handler Modules │ │
│ │ (handlers/*.ts) │ │
│ │ • balance, tokens, transactions... │ │
│ └─────────────────────────────────────┘ │
│ │ │ │
│ Get/Create Fork(userId) │ │ Record TX │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────────────────────┐ ┌─────────────────────┐ ┌────────────────────────────────┐ │
│ │ Fork Service │ │ Transaction Calls │ │ Transaction Recorder │ │
│ │ (ForkService.ts) │◀────│ (sendTransaction, │───▶│ (TransactionRecorder.ts) │ │
│ │ │ │ simulate, etc.) │ │ │ │
│ └───────────────────────────┘ └─────────────────────┘ └────────────────────────────────┘ │
│ │ │ │
│ │ Manages │ Writes to │
│ ▼ ▼ │
│ ┌───────────────────────────┐ ┌────────────────────────────────┐ │
│ │ LiteSVM Instances (Map) │ │ In-Memory History (Map) │ │
│ │ (Isolated States) │ │ (Per-user transaction list) │ │
│ └───────────────────────────┘ └────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
## File Structure
```plaintext
solana-simulation-engine/
├── src/ # Source code directory
│ ├── handlers/ # RPC method handlers
│ │ ├── balance.ts # SOL balance & airdrop operations
│ │ ├── tokens.ts # SPL token operations
│ │ ├── transactions.ts # Transaction processing
│ │ ├── accounts.ts # Account information
│ │ ├── history.ts # Transaction history
│ │ ├── index.ts # Handler exports
│ │ └── types.ts # Handler type definitions
│ ├── services/ # Core business logic
│ │ ├── ForkService.ts # Fork lifecycle management
│ │ └── TransactionRecorder.ts # Transaction recording
│ ├── middleware/ # Express middleware
│ │ └── rpcHandler.ts # RPC request routing
│ └── server.ts # Main Express server
├── tests/ # Test suite
│ ├── test-sol.ts # SOL operations tests
│ ├── test-tokens.ts # Token operations tests
│ ├── test-isolation.ts # Fork isolation tests
│ └── test-protocol-interactions.ts # DeFi protocol tests
├── node_modules/ # Dependencies (git-ignored)
├── dist/ # Compiled JavaScript (git-ignored)
├── package.json # NPM configuration
├── tsconfig.json # TypeScript configuration
├── .gitignore # Git ignore rules
├── README.md # This file
└── LICENSE # MIT License
The Solana Simulation Engine consists of the following key components:
- LiteSVM: The lightweight Solana Virtual Machine that powers the fork-based simulations.
- RPC Server: A JSON-RPC server that handles communication with the Solana tools and clients.
- Fork Manager: Manages the creation, expiration, and cleanup of forks.
- Transaction Processor: Processes and simulates transactions within the forks.
The components of the Solana Simulation Engine interact as follows:
- The RPC Server receives requests from clients and forwards them to the appropriate handler.
- The Fork Manager creates a new fork using LiteSVM for each test or simulation, isolating it from other operations.
- The Transaction Processor executes transactions within the context of the fork, allowing for realistic testing of DeFi protocols and smart contracts.
- The Logger records all actions, errors, and events for debugging and auditing purposes.
Before you begin, ensure you have met the following requirements:
- Node.js: Install Node.js (>=14.0.0) from nodejs.org.
- TypeScript: Install TypeScript globally using npm:
npm install -g typescript
To install the Solana Simulation Engine, follow these steps:
- Clone the repository:
git clone https://github.com/NVN404/solana-simulation.git
- Navigate to the project directory:
cd solana-simulation - Install the dependencies:
npm install
- run the project:
npm run dev
To quickly start using the Solana Simulation Engine, follow these steps:
-
Start the RPC server:
npm run dev
-
In a new terminal, check health (no. of active forks ):
curl http://localhost:3000/health
-
Fund the fork with SOL:
curl -X POST http://localhost:3000/rpc/test-user \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "requestAirdrop", "params": ["11111111111111111111111111111112", 1000000000] }'
-
check the balance :
curl -X POST http://localhost:3000/rpc/test-user \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "getBalance", "params": ["11111111111111111111111111111112"] }'
-
Airdrop USDC tokens:
curl -X POST http://localhost:3000/rpc/test-user \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "airdropToken", "params": [ "11111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "1000000000" ] }'
-
Get Transaction history :
curl -X POST http://localhost:3000/rpc/test-user \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "getTransactionHistory",
"params": []
}'The Solana Simulation Engine provides a JSON-RPC API compatible with the Solana JSON-RPC API. The following methods are supported:
requestAirdrop: Airdrop SOL to a specified address.sendTransaction: Send a transaction to the network.getBalance: Get the SOL balance of an address.airdropToken: Airdrop SPL tokens to a specified address.getTokenAccountBalance: Get the balance of SPL tokens in an account.getTransactionHistory: Get the transaction history of an address.getLatestBlockhash: Get the latest blockhash from the network.getAccountInfo: Get the account information for a specified address.
To run the tests for the Solana Simulation Engine, follow these steps:
- Ensure the RPC server is running.
- Run the tests:
npx tsx tests/test-sol.ts npx tsx tests/test-tokens.ts npx tsx tests/test-isolation.ts npx tsx tests/test-protocol-interactions.ts
If you encounter issues while using the Solana Simulation Engine, try the following solutions:
- Ensure all dependencies are installed and up to date.
- Check the logs for error messages and stack traces.
- Verify that the RPC server is running and accessible.