Simulate a Solana transfer locally

Preview the recipient and amount of a SOL transfer in a local Solana runtime. The exercise uses generated test keys and an in-memory balance.

Before you start

  • Use Node.js 22 or later and a new project directory. The example uses LiteSVM 1.6.2, Solana Kit 8.6.0 and Solana web3.js 1.99.0.
  • Use the generated keys in the example. The local runtime needs no connected wallet, RPC endpoint or funded account.

Data and access

Shared or checked
The local runtime evaluates a signed test transaction against its disposable account balances. It reports the projected transfer result.
Check separately
Simulation leaves the balances unchanged. A submitted transaction needs a valid blockhash, sufficient funds and a network receipt.
  1. Install the local runtime

    In the new project directory, install the versions used for this exercise.

    npm install litesvm@1.6.2 @solana/kit@8.6.0 @solana/web3.js@1.99.0

    Check. Check your Node.js version and confirm the dependencies install in the test directory.

  2. Build and simulate the transfer

    Save this example as rehearse-sol-transfer.mjs. It signs a single System Program transfer with a disposable key, checks the projected recipient balance and confirms that simulation left the stored balance unchanged.

    import assert from 'node:assert/strict';
    import { getTransactionDecoder } from '@solana/kit';
    import { Keypair, SystemProgram, Transaction } from '@solana/web3.js';
    import { LiteSVM } from 'litesvm';
    
    const vm = new LiteSVM().withSigverify(true).withBlockhashCheck(true);
    const sender = Keypair.generate();
    const recipient = Keypair.generate();
    const amount = 10_000_000n;
    vm.airdrop(sender.publicKey.toBase58(), 1_000_000_000n);
    const address = recipient.publicKey.toBase58();
    const before = vm.getBalance(address) ?? 0n;
    
    const tx = new Transaction({
      feePayer: sender.publicKey,
      recentBlockhash: vm.latestBlockhash(),
    }).add(SystemProgram.transfer({
      fromPubkey: sender.publicKey,
      toPubkey: recipient.publicKey,
      lamports: amount,
    }));
    tx.sign(sender);
    const wire = getTransactionDecoder().decode(tx.serialize());
    const result = vm.simulateTransaction(wire);
    if ('err' in result) throw new Error(String(result.err()));
    
    const projected = result.postAccounts().find(account => account.address === address);
    assert.equal(projected.lamports - before, amount);
    assert.equal(vm.getBalance(address) ?? 0n, before);
    console.log(`Recipient would receive ${amount} lamports. Local balance is unchanged.`);

    Check. The example signs the transfer with a disposable local key and reads the projected account from the simulation.

  3. Check the projected amount

    Run the exercise. Compare the displayed amount with the expected 10,000,000 lamports (0.01 SOL). To try a failure, set the transfer to 2,000,000,000 lamports, which exceeds the test sender’s balance, and rerun it.

    node rehearse-sol-transfer.mjs

    Check. The example prints 10,000,000 lamports and confirms the local balance is unchanged. A larger amount than the funded balance fails.

Check your result

The recipient would gain 10,000,000 lamports. Its balance in the local runtime stays unchanged. A successful simulation describes execution against the simulated state. A submitted transaction can still fail if the balance or blockhash changes.

What we tested

Tested on . We ran the published example in a local process with Node.js 26.6.0 and LiteSVM. It projected a gain of 10,000,000 lamports and left the stored balance unchanged. The same code rejected a transfer larger than the test sender’s balance.

How to verify your setup

If you get stuck

The runtime rejects the transfer

Check the test balance and transfer amount, and build the transaction with a fresh blockhash from the same runtime. Leave room for the transaction fee.

Report a problem with this guide

Explore all setup guides →