> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# simulateSolanaTransaction

> Preview a Solana transaction's effects before sending it

Simulates a Solana transaction and returns a breakdown of expected asset changes, security validation
results, and optionally an estimated SOL fee — all before the transaction is sent to the network.

Supports both legacy `Transaction` and `VersionedTransaction` objects. Powered by
[Blockaid](https://blockaid.io) for security validation.

## Installation

```bash theme={"system"}
npm install @dynamic-labs-sdk/solana
```

## Usage

```javascript theme={"system"}
import { simulateSolanaTransaction } from '@dynamic-labs-sdk/solana';
import { isSolanaWalletAccount } from '@dynamic-labs-sdk/solana';
import { getPrimaryWalletAccount } from '@dynamic-labs-sdk/client';
import {
  Transaction,
  SystemProgram,
  PublicKey,
} from '@solana/web3.js';

const walletAccount = getPrimaryWalletAccount();

if (walletAccount && isSolanaWalletAccount(walletAccount)) {
  const transaction = new Transaction().add(
    SystemProgram.transfer({
      fromPubkey: new PublicKey(walletAccount.address),
      toPubkey: new PublicKey(recipientAddress),
      lamports: 1_000_000_000, // 1 SOL
    })
  );

  const result = await simulateSolanaTransaction({
    walletAccount,
    transaction,
  });

  console.log('Assets going out:', result.outAssets);
  console.log('Security check:', result.validation?.result);
}
```

## Parameters

| Parameter       | Type                                  | Description                                             |
| --------------- | ------------------------------------- | ------------------------------------------------------- |
| `walletAccount` | `SolanaWalletAccount`                 | The wallet account initiating the transaction           |
| `transaction`   | `Transaction \| VersionedTransaction` | The Solana transaction to simulate                      |
| `includeFees`   | `boolean` (optional)                  | Whether to include a SOL fee estimate. Default: `false` |
| `client`        | `DynamicClient` (optional)            | Only required when using multiple clients               |

## Returns

`Promise<SolanaSimulationResult>` — an object with the following fields:

| Field                         | Type                                   | Description                                       |
| ----------------------------- | -------------------------------------- | ------------------------------------------------- |
| `inAssets`                    | `AssetDiff[]`                          | Assets the wallet will receive                    |
| `outAssets`                   | `AssetDiff[]`                          | Assets the wallet will send                       |
| `validation`                  | `BlockaidValidation` (optional)        | Security assessment from Blockaid                 |
| `validation.result`           | `'benign' \| 'warning' \| 'malicious'` | Overall security verdict                          |
| `validation.description`      | `string` (optional)                    | Human-readable description                        |
| `validation.reason`           | `string` (optional)                    | Reason for the verdict                            |
| `feeData`                     | `SolanaTransactionFeeData` (optional)  | Present only when `includeFees: true`             |
| `feeData.humanReadableAmount` | `string`                               | Fee in SOL, formatted for display                 |
| `feeData.nativeAmount`        | `bigint`                               | Fee in lamports (`0n` for sponsored transactions) |
| `feeData.usdAmount`           | `string` (optional)                    | Fee in USD if price data is available             |
| `priceData`                   | `PriceData`                            | Price information for the assets involved         |
| `counterparties`              | `string[]` (optional)                  | Other addresses involved in the transaction       |

<Note>
  When the transaction's fee payer is different from the wallet address, `feeData.nativeAmount` is `0n`
  — indicating the transaction fee is sponsored.
</Note>

## Examples

### SOL transfer

```javascript theme={"system"}
const transaction = new Transaction().add(
  SystemProgram.transfer({
    fromPubkey: new PublicKey(walletAccount.address),
    toPubkey: new PublicKey(recipientAddress),
    lamports: 500_000_000, // 0.5 SOL
  })
);

const result = await simulateSolanaTransaction({
  walletAccount,
  transaction,
});

console.log('Assets out:', result.outAssets);
```

### With fee estimation

```javascript theme={"system"}
const result = await simulateSolanaTransaction({
  walletAccount,
  transaction,
  includeFees: true,
});

if (result.feeData) {
  if (result.feeData.nativeAmount === 0n) {
    console.log('Transaction fee is sponsored');
  } else {
    console.log(`Estimated fee: ${result.feeData.humanReadableAmount} SOL`);
  }
}
```

### Versioned transaction

```javascript theme={"system"}
import {
  VersionedTransaction,
  TransactionMessage,
  PublicKey,
} from '@solana/web3.js';

const messageV0 = new TransactionMessage({
  payerKey: new PublicKey(walletAccount.address),
  recentBlockhash: latestBlockhash,
  instructions: [instruction],
}).compileToV0Message();

const versionedTx = new VersionedTransaction(messageV0);

const result = await simulateSolanaTransaction({
  walletAccount,
  transaction: versionedTx,
});
```

### Security validation

```javascript theme={"system"}
const result = await simulateSolanaTransaction({ walletAccount, transaction });

if (result.validation?.result === 'malicious') {
  console.warn('Transaction flagged as malicious. Blocking.');
  return;
}

if (result.validation?.result === 'warning') {
  console.warn('Warning:', result.validation.description);
}
```

### Error handling

```javascript theme={"system"}
import { SimulationFailedError } from '@dynamic-labs-sdk/client';

try {
  const result = await simulateSolanaTransaction({ walletAccount, transaction });
} catch (error) {
  if (error instanceof SimulationFailedError) {
    console.error('Simulation failed:', error.message);
  }
}
```

## React

Call `simulateSolanaTransaction` inside a button handler to preview the transaction before the user confirms:

```tsx theme={"system"}
import { simulateSolanaTransaction, isSolanaWalletAccount } from '@dynamic-labs-sdk/solana';
import { useGetWalletAccounts } from '@dynamic-labs-sdk/react-hooks';
import { useState } from 'react';
import { Transaction, SystemProgram, PublicKey } from '@solana/web3.js';

function SimulateSolanaButton({ recipientAddress }) {
  const { data: walletAccounts = [] } = useGetWalletAccounts();
  const walletAccount = walletAccounts.find(isSolanaWalletAccount);
  const [result, setResult] = useState(null);

  const handleSimulate = async () => {
    if (!walletAccount) return;

    const transaction = new Transaction().add(
      SystemProgram.transfer({
        fromPubkey: new PublicKey(walletAccount.address),
        toPubkey: new PublicKey(recipientAddress),
        lamports: 1_000_000_000,
      }),
    );

    const simulation = await simulateSolanaTransaction({ walletAccount, transaction });
    setResult(simulation);
  };

  return (
    <div>
      <button onClick={handleSimulate} disabled={!walletAccount}>Preview Transaction</button>
      {result && <p>Security: {result.validation?.result ?? 'N/A'}</p>}
    </div>
  );
}
```

## Related functions

* [calculateSolanaTransactionFee](/javascript/reference/solana/calculate-solana-transaction-fee) - Fee estimation only, without asset diffs or security validation
* [simulateEvmTransaction](/javascript/reference/evm/simulate-evm-transaction) - Simulate an EVM transaction
* [simulateZerodevUserOperation](/javascript/reference/zerodev/simulate-zerodev-user-operation) - Simulate a ZeroDev user operation
* [signing-sending-transactions](/javascript/reference/solana/signing-sending-transactions) - Send Solana transactions
* [svm-gas-sponsorship](/javascript/reference/solana/svm-gas-sponsorship) - Solana gas sponsorship