@axvn-vn/kit-plugin-litesvm

Kit Plugins ➤ LiteSVM

This package provides a plugin that adds LiteSVM functionality to your Kit clients.

Installation

pnpm install @solana/kit-plugin-litesvm

litesvm plugin

The litesvm plugin sets up a full LiteSVM client in a single call. It installs an SVM connection, airdrop support, minimum balance computation, transaction planning, and transaction execution on the client.

The client must have a payer set before applying this plugin.

[!IMPORTANT] This plugin is only available in Node.js builds. Browser and React Native builds throw an error when calling litesvm().

Installation

import { createClient } from '@solana/kit';
import { litesvm } from '@solana/kit-plugin-litesvm';
import { payer } from '@solana/kit-plugin-signer';

const client = createClient().use(payer(myPayer)).use(litesvm());

Options

All options are provided via a LiteSvmConfig object:

• transactionConfig: Options to configure how transaction messages are created. See the litesvmTransactionPlanner options below.

Features

• svm: Access the underlying LiteSVM instance.
• rpc: Call a subset of Solana RPC methods against the LiteSVM instance.
• airdrop: Request SOL from the LiteSVM faucet.
• getMinimumBalance: Compute minimum lamports for rent exemption.
• planTransaction(s): Plan instructions into transaction messages without executing them.
• sendTransaction(s): Plan and execute instructions, instruction plans, or transaction messages in one call.
• transactionPlanner / transactionPlanExecutor (deprecated): Fields kept for backward compatibility. Use planTransaction(s) / sendTransaction(s) instead.

litesvmConnection plugin

The LiteSVM plugin starts a new LiteSVM instance within your Kit client, allowing you to simulate Solana programs and accounts locally. Additionally, it derives a small RPC subset that interacts with the LiteSVM instance instead of making network requests.

[!IMPORTANT] This plugin is only available in Node.js builds. Browser and React Native builds throw an error when calling litesvmConnection().

Installation

import { createClient } from '@solana/kit';
import { litesvmConnection } from '@solana/kit-plugin-litesvm';

const client = createClient().use(litesvmConnection());

Features

• svm: Access the underlying LiteSVM instance.

  client.svm.setAccount(myAccount);
  client.svm.addProgramFromFile(myProgramAddress, 'my_program.so');
  

• rpc: Call a subset of Solana RPC methods against the LiteSVM instance. Currently supported methods are: getAccountInfo, getBalance, getEpochSchedule, getLatestBlockhash, getMinimumBalanceForRentExemption, getMultipleAccounts, getProgramAccounts, getSlot, and requestAirdrop.

  const { value: latestBlockhash } = await client.rpc.getLatestBlockhash().send();
  

litesvmAirdrop plugin

This plugin adds an airdrop method to your Kit client that airdrops SOL using the underlying LiteSVM instance. It performs error handling and returns the transaction signature on success.

Installation

The client must have the litesvmConnection plugin installed before applying this plugin.

import { createClient } from '@solana/kit';
import { litesvmConnection, litesvmAirdrop } from '@solana/kit-plugin-litesvm';

const client = createClient().use(litesvmConnection()).use(litesvmAirdrop());

Features

• airdrop: An asynchronous helper function that airdrops a specified amount of lamports to a given address.

  await client.airdrop(address('HQVxiMVDoV9jzG4tpoxmDZsNfWvaHXm8DGGv93Gka75v'), lamports(1_000_000_000n));
  

litesvmGetMinimumBalance plugin

This plugin adds a getMinimumBalance method to your Kit client that computes the minimum lamports required for an account with a given data size, using the underlying LiteSVM instance.

Installation

The client must have the litesvmConnection plugin installed before applying this plugin.

import { createClient } from '@solana/kit';
import { litesvmConnection, litesvmGetMinimumBalance } from '@solana/kit-plugin-litesvm';

const client = createClient().use(litesvmConnection()).use(litesvmGetMinimumBalance());

Features

• getMinimumBalance: An asynchronous helper that returns the minimum lamports required for an account with the given data size. By default, the 128-byte account header is included on top of the provided space.

  // Minimum balance for an account with 100 bytes of data (plus header).
  const balance = await client.getMinimumBalance(100);
  
  // Minimum balance for exactly 100 bytes (without adding the header).
  const rawBalance = await client.getMinimumBalance(100, { withoutHeader: true });
  

litesvmTransactionPlanner plugin

Adds planTransaction and planTransactions to the client, using a planner that plans instructions into transaction messages with a fee payer and optional priority fees. The fee payer is read from client.payer lazily, at plan time, so a dynamic payer (such as a connected wallet) is always respected.

Usage

The client must have a payer set before installing the plugin.

import { createClient } from '@solana/kit';
import {
    litesvmConnection,
    litesvmTransactionPlanSendingExecutor,
    litesvmTransactionPlanner,
} from '@solana/kit-plugin-litesvm';
import { generatedPayer } from '@solana/kit-plugin-signer';

const client = await createClient()
    .use(litesvmConnection())
    .use(generatedPayer())
    .use(litesvmTransactionPlanner())
    .use(litesvmTransactionPlanSendingExecutor());

const transactionPlan = await client.planTransactions(myInstructionPlan);

Options

All options are provided via a TransactionPlannerConfig object. Its shape is discriminated by the transaction version.

For legacy and version 0 transactions:

• version: The transaction message version to use. Accepts 0 or 'legacy'. Defaults to 0.
• microLamportsPerComputeUnit: The priority fee in micro-lamports per compute unit, added as a setComputeUnitPrice instruction. Defaults to no priority fees.

Unlike the RPC planner, the LiteSVM planner does not estimate resource limits, since LiteSVM executes transactions locally without a simulation-based estimation step.

Version 1 transactions are defined for forward compatibility but are not yet buildable by @solana/kit; passing version: 1 currently throws. When available, version 1 will accept priorityFeeLamports (a flat total in lamports) instead of microLamportsPerComputeUnit.

litesvmTransactionPlanSendingExecutor plugin

Adds sendTransaction and sendTransactions to the client, using an executor that signs and sends transactions to the LiteSVM instance. When a transaction fails, it throws a SolanaError with the same error codes the RPC executor would produce. The executor stores the LiteSVM transaction metadata (FailedTransactionMetadata or TransactionMetadata) on context.transactionMetadata, so consumers can inspect logs, compute units consumed, and return data from the plan result.

Usage

The client must have an svm instance configured, and a transaction planner installed, before installing this plugin — sending plans through the client's planning functions.

import { createClient } from '@solana/kit';
import {
    litesvmConnection,
    litesvmTransactionPlanSendingExecutor,
    litesvmTransactionPlanner,
} from '@solana/kit-plugin-litesvm';
import { generatedPayer } from '@solana/kit-plugin-signer';

const client = await createClient()
    .use(litesvmConnection())
    .use(generatedPayer())
    .use(litesvmTransactionPlanner())
    .use(litesvmTransactionPlanSendingExecutor());

const transactionPlanResult = await client.sendTransactions(myInstructionPlan);

Result context

As it works through a transaction, the executor records the planned message (once its blockhash lifetime is set), the fully signed transaction, the signature it was sent under, and the LiteSVM metadata the send produced. A successful plan result carries all four on its context, and the exported LiteSvmSendContext type names that shape so you can annotate results yourself.

import { SuccessfulSingleTransactionPlanResult } from '@solana/kit';
import { isFailedTransaction, LiteSvmSendContext } from '@solana/kit-plugin-litesvm';

function logComputeUnits(result: SuccessfulSingleTransactionPlanResult<LiteSvmSendContext>) {
    const { signature, transactionMetadata } = result.context;
    if (!isFailedTransaction(transactionMetadata)) {
        console.log(`${signature} consumed ${transactionMetadata.computeUnitsConsumed()} compute units`);
    }
}

Because the context is filled in as execution progresses, a transaction that fails or is canceled part way through carries only what was recorded before it stopped. Failed and canceled results therefore type the context as partial — only successful results guarantee every field.

The sendTransaction and sendTransactions functions installed by this plugin propagate this context type, so their results carry a typed LiteSvmSendContext without any annotation needed.

Deprecated plugins

The following plugins are still exported for backward compatibility but are deprecated.

• litesvmTransactionPlanExecutor(): Only sets the deprecated client.transactionPlanExecutor field. Use litesvmTransactionPlanSendingExecutor instead, which installs sendTransaction and sendTransactions alongside the executor.

  // Before
  const client = await createClient()
      .use(litesvmTransactionPlanner())
      .use(litesvmTransactionPlanExecutor())
      .use(planAndSendTransactions());
  
  // After
  const client = await createClient().use(litesvmTransactionPlanner()).use(litesvmTransactionPlanSendingExecutor());