Transaction Simulator

Simulate Solana transactions before execution to detect potential issues and risks.

Overview

The Transaction Simulator provides a critical safety layer for AI agents handling crypto assets. It simulates transactions before execution to detect:

• Transaction failures via Solana RPC simulation
• High slippage in swaps using Jupiter API
• Token security risks (honeypots, freeze authority) via GoPlus API
• Liquidity issues that could affect trade execution
• Price impact for large trades

Installation

pip install sentinelseed httpx

Quick Start

Basic Swap Simulation

import asyncio
from sentinelseed.integrations.preflight import TransactionSimulator

async def main():
    async with TransactionSimulator(
        rpc_url="https://api.mainnet-beta.solana.com"
    ) as simulator:
        # Simulate SOL -> USDC swap
        result = await simulator.simulate_swap(
            input_mint="So11111111111111111111111111111111111111112",  # SOL
            output_mint="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  # USDC
            amount=1_000_000_000,  # 1 SOL in lamports
        )

        if result.is_safe:
            print(f"Expected output: {result.expected_output / 1e6:.2f} USDC")
            print(f"Slippage: {result.slippage_bps / 100:.2f}%")
        else:
            print(f"Risks detected: {[r.description for r in result.risks]}")

asyncio.run(main())

Token Security Check

from sentinelseed.integrations.preflight import TransactionSimulator

async def check_token():
    async with TransactionSimulator() as simulator:
        result = await simulator.check_token_security("TokenMintAddress...")

        print(f"Is Safe: {result.is_safe}")
        print(f"Has Freeze Authority: {result.has_freeze_authority}")
        print(f"Is Honeypot: {result.is_honeypot}")

        if not result.is_safe:
            for risk in result.risks:
                print(f"  - {risk.description}")

PreflightValidator (Combined)

from sentinelseed.integrations.preflight import PreflightValidator

async def validate():
    # Combines THSP validation + transaction simulation
    async with PreflightValidator(
        max_transfer=100.0,
        max_slippage_bps=500,  # 5%
        require_purpose=True,
    ) as validator:
        result = await validator.validate_swap(
            input_mint="So11...",
            output_mint="Token...",
            amount=1_000_000_000,
            purpose="Converting SOL to stable for savings",
        )

        if result.should_proceed:
            print("Transaction approved!")
            print(f"Expected output: {result.expected_output}")
        else:
            print("Transaction blocked:")
            print(f"  Validation: {result.validation_concerns}")
            print(f"  Simulation: {result.simulation_risks}")

Components

TransactionSimulator

Core simulator with RPC, Jupiter, and GoPlus integration.

Methods:

• simulate_transaction(tx_base64) - Simulate raw transaction
• simulate_swap(input_mint, output_mint, amount) - Simulate token swap
• check_token_security(token_address) - Check token security
• pre_flight_check(action, params) - High-level action validation

PreflightValidator

Combined validator that integrates with Sentinel THSP.

Methods:

• validate_with_simulation(action, **kwargs) - Full validation
• validate_swap(...) - Swap-specific validation
• validate_transfer(...) - Transfer-specific validation
• check_token(token_address) - Token security check

Analyzers

Specialized risk analyzers:

• JupiterAnalyzer - Swap quotes and slippage analysis
• GoPlusAnalyzer - Token security via GoPlus API
• TokenRiskAnalyzer - Comprehensive token analysis
• SlippageAnalyzer - Slippage recommendations
• LiquidityAnalyzer - Pool liquidity analysis

Risk Factors

Risk Levels

LangChain Integration

from sentinelseed.integrations.preflight import create_preflight_tools

# Create tools for LangChain agent
tools = create_preflight_tools()

# Tools available:
# - preflight_check_swap: Simulate swaps
# - preflight_check_token: Check token security

Configuration

simulator = TransactionSimulator(
    # Solana RPC endpoint
    rpc_url="https://api.mainnet-beta.solana.com",

    # GoPlus API key (optional, free tier available)
    goplus_api_key=None,

    # Jupiter API key (optional)
    jupiter_api_key=None,

    # Maximum acceptable slippage (basis points)
    max_slippage_bps=500,  # 5%

    # Cache TTL for token security results
    cache_ttl_seconds=300,  # 5 minutes
)

API References

• Solana RPC simulateTransaction
• Jupiter Swap API
• GoPlus Token Security API