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

# Transaction Simulation

> Pre-flight checks prevent failed transactions

Bookie simulates every transaction before presenting it for approval, preventing failures and unexpected outcomes.

## How Simulation Works

Before you see a transaction in your wallet, Bookie runs it through Solana's simulation engine:

<Steps>
  <Step title="Build Transaction">
    Construct transaction with all instructions and accounts
  </Step>

  <Step title="Simulate Execution">
    Run transaction against current blockchain state
  </Step>

  <Step title="Analyze Results">
    Check for errors, compute usage, and balance changes
  </Step>

  <Step title="Present to User">
    Only show transaction if simulation succeeds
  </Step>
</Steps>

## What Simulation Catches

<CardGroup cols={2}>
  <Card title="Insufficient Balance" icon="wallet">
    Not enough tokens or SOL for transaction
  </Card>

  <Card title="Slippage Exceeded" icon="chart-line">
    Price moved beyond acceptable range
  </Card>

  <Card title="Account Errors" icon="circle-xmark">
    Missing or invalid token accounts
  </Card>

  <Card title="Program Failures" icon="bug">
    Smart contract execution errors
  </Card>
</CardGroup>

## Simulation API

Bookie uses Solana's `simulateTransaction` RPC method:

```typescript theme={null}
const simulation = await connection.simulateTransaction(
  transaction,
  {
    commitment: 'confirmed',
    sigVerify: false
  }
);

if (simulation.value.err) {
  throw new Error(`Simulation failed: ${simulation.value.err}`);
}

console.log('Compute units used:', simulation.value.unitsConsumed);
console.log('Logs:', simulation.value.logs);
```

## Simulation Response

A successful simulation returns:

| Field           | Description                       |
| --------------- | --------------------------------- |
| `err`           | Error object (null if successful) |
| `logs`          | Program execution logs            |
| `unitsConsumed` | Compute units used                |
| `accounts`      | Post-transaction account states   |

## Error Types

Common simulation errors and their meanings:

### Insufficient Funds

```
Error: Attempt to debit an account but found no record of a prior credit
```

**Cause:** Not enough SOL or tokens in wallet

**Solution:** Add funds before retrying

### Slippage Tolerance Exceeded

```
Error: Slippage tolerance exceeded
```

**Cause:** Price moved more than allowed slippage

**Solution:** Increase slippage or wait for better price

### Account Not Found

```
Error: AccountNotFound
```

**Cause:** Token account doesn't exist

**Solution:** Bookie automatically creates account (adds \~0.002 SOL to cost)

### Blockhash Expired

```
Error: Blockhash not found
```

**Cause:** Transaction took too long to build

**Solution:** Bookie automatically rebuilds with fresh blockhash

## Compute Budget Optimization

Simulation reveals exact compute units needed:

```typescript theme={null}
const simulation = await connection.simulateTransaction(transaction);
const computeUnits = simulation.value.unitsConsumed;

// Add 20% buffer for safety
const computeLimit = Math.ceil(computeUnits * 1.2);

transaction.add(
  ComputeBudgetProgram.setComputeUnitLimit({
    units: computeLimit
  })
);
```

**Benefits:**

* Prevents out-of-compute errors
* Optimizes transaction fees
* Improves success rate

## Balance Change Preview

Simulation shows expected balance changes:

**Before Simulation:**

* SOL: 10.5
* USDC: 100

**Simulated Swap:** 1 SOL → USDC

**After Simulation:**

* SOL: 9.499995 (1 SOL + 0.000005 fee)
* USDC: 250.43 (received from swap)

<Note>
  Actual execution may differ slightly from simulation due to price movements between simulation and execution.
</Note>

## Simulation Limitations

Simulation cannot predict:

* **Price Changes:** Market moves between simulation and execution
* **Network Congestion:** Transaction may fail due to congestion
* **MEV Attacks:** Sandwich attacks happen after simulation
* **Concurrent Transactions:** Other transactions affecting same accounts

<Warning>
  Simulation success does not guarantee execution success. Always monitor transactions after submission.
</Warning>

## Performance

| Metric                | Value |
| --------------------- | ----- |
| Simulation Time (p50) | 12ms  |
| Simulation Time (p99) | 28ms  |
| Success Rate          | 99.7% |
| False Positives       | 0.3%  |

## Advanced Features

### Preflight Commitment

Bookie uses `confirmed` commitment for simulation:

```typescript theme={null}
const simulation = await connection.simulateTransaction(
  transaction,
  { commitment: 'confirmed' }
);
```

**Options:**

* `processed`: Fastest, least reliable
* `confirmed`: Balanced (default)
* `finalized`: Slowest, most reliable

### Signature Verification

Disabled during simulation for speed:

```typescript theme={null}
const simulation = await connection.simulateTransaction(
  transaction,
  { sigVerify: false }
);
```

Signatures are verified during actual execution.

## Debugging Failed Simulations

If simulation fails, Bookie provides detailed logs:

```
Program log: Instruction: Swap
Program log: Input: 5000000000 lamports
Program log: Error: Slippage tolerance exceeded
Program log: Expected minimum: 750000000
Program log: Actual output: 745000000
```

Use these logs to understand why a transaction would fail.

<Card title="Solana RPC Methods" icon="book" href="https://docs.solana.com/api/http#simulatetransaction">
  Learn more about simulateTransaction RPC method
</Card>