# warp-id/solana-trading-bot architecture

> Architecture diagram of the GitHub repository warp-id/solana-trading-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/warp-id/solana-trading-bot
- Repository: https://github.com/warp-id/solana-trading-bot

## Overview

##### Project type and purpose
- This is a single-process, full-stack automation tool—a Solana Trading Bot—that connects to the Solana network via HTTP/WebSocket RPCs (and optionally third-party services like Jito or Warp) to monitor on-chain market events, apply filters/strategies, and execute buy/sell transactions automatically.

##### File structure
- Top-level entrypoints:
- bot.ts / index.ts – bootstraps the bot, loads config, starts listeners
- Configuration:
- .env-based config loader via helpers/constants.ts
- Modules:
- cache/ – in-memory caches for markets, pools, snipe-lists
- filters/ – individual pool or token filters (burned, mutable, renounced, pool size, etc.)
- helpers/ – RPC wrappers, logging, wallet operations, common constants
- listeners/ – WebSocket subscriptions for new pools or market events
- transactions/ – TransactionExecutor interface + implementations (default RPC, Jito, Warp)
- Other assets:
- snipe-list.txt – optional static watchlist of mint addresses
- readme assets for CLI output

##### Key insights from README
- Configurable parameters for wallet, RPC endpoints (HTTP & WS), logging, caching, filtering thresholds, buy/sell strategies, slippage, retry logic, and transaction executor choice (default/Jito/Warp).
- Emphasis on real-time WebSocket listeners + filters pipeline + strategy module + pluggable transaction executors.

##### Components
a. Main components
1. Configuration Loader (reads .env into Constants)
2. Bot Engine (orchestrator)
3. Market Listener (Solana WS)
4. Cache Manager (market.cache, pool.cache, snipe-list.cache)
5. Filter Pipeline (chain of pool/token filters)
6. Snipe List Service (optional watchlist loader)
7. Transaction Executor (Strategy pattern):
– Default RPC executor
– Jito RPC executor
– Warp API executor
8. Helpers & Logger (shared utilities)
9. External Services:
– Solana HTTP RPC endpoint
– Solana WebSocket RPC endpoint
– Jito RPC endpoint
– Warp transactions API

b. Relationships & data flows
- On startup: Config Loader → Bot Engine
- Bot Engine → initializes Market Listener → subscribes to new pool events via Solana WS
- Incoming events → Cache Manager updates caches → Event passed to Filter Pipeline
- Filter Pipeline → if passes N filters → Bot Engine enqueues buy/sell job
- Bot Engine → calls Transaction Executor (selected at runtime)
- Transaction Executor → serializes & sends transaction via Solana HTTP RPC or 3rd-party endpoint
- Helpers/Logger used throughout for retries, fee calculations, error handling

c. Architectural patterns & principles
- Observer pattern – listeners subscribe to on-chain events via WebSocket
- Strategy pattern – interchangeable TransactionExecutor implementations
- Chain-of-responsibility – sequential filters in filters/
- Single responsibility – clear separation: caching, filtering, listening, executing

d. Key technologies & frameworks
- TypeScript + Node.js runtime
- Solana Web3.js (under helpers)
- HTTP & WebSocket RPC protocols
- Optional third-party services: Jito RPC, Warp API

##### Detail
- Filter modules by name or group them under “Filter Pipeline.”
- TransactionExecutor implementation branching off the interface.
- Snipe List refresh path: Timer → SnipeList Service → Cache Manager.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Modules
    subgraph "Internal Modules"
        direction TB
        ConfigLoader["Configuration Loader"]:::internal
        BotEngine["Bot Engine (Orchestrator)"]:::internal
        MarketListener["Market Listener"]:::internal
        CacheManager["Cache Manager"]:::internal
        subgraph "Caches"
            direction TB
            MarketCache["market.cache"]:::cache
            PoolCache["pool.cache"]:::cache
            SnipeCache["snipe-list.cache"]:::cache
        end
        subgraph "Filter Pipeline"
            direction TB
            BurnFilter["burn.filter"]:::filter
            MutableFilter["mutable.filter"]:::filter
            PoolFilters["pool-filters"]:::filter
            PoolSizeFilter["pool-size.filter"]:::filter
            RenouncedFilter["renounced.filter"]:::filter
        end
        SnipeService["Snipe List Service"]:::internal
        subgraph "Transaction Executor (Strategy)"
            direction TB
            ExecInterface["transaction-executor.interface"]:::executor
            DefaultExec["default-transaction-executor"]:::executor
            JitoExec["jito-rpc-transaction-executor"]:::executor
            WarpExec["warp-transaction-executor"]:::executor
        end
        HelpersLogger["Helpers & Logger"]:::helper
        Entrypoint["Entrypoint / Bootstrap"]:::internal
        EnvConfig["Env Config (.env loader)"]:::internal
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        SolanaHTTP["Solana HTTP RPC"]:::external
        SolanaWS["Solana WebSocket RPC"]:::external
        JitoRPC["Jito RPC Endpoint"]:::external
        WarpAPI["Warp Transactions API"]:::external
    end

    %% Data Flows
    ConfigLoader -->|loads config| BotEngine
    ConfigLoader -->|loads config| MarketListener
    ConfigLoader -->|loads config| CacheManager
    ConfigLoader -->|loads config| FilterPipeline
    ConfigLoader -->|loads config| SnipeService
    ConfigLoader -->|loads config| HelpersLogger

    BotEngine -->|init| MarketListener
    MarketListener -->|subscribe| SolanaWS
    MarketListener -->|event| CacheManager

    CacheManager -->|update caches| MarketCache
    CacheManager -->|update caches| PoolCache
    CacheManager -->|update caches| SnipeCache
    CacheManager -->|emit event| BurnFilter
    BurnFilter -->|pass| MutableFilter
    MutableFilter -->|pass| PoolFilters
    PoolFilters -->|pass| PoolSizeFilter
    PoolSizeFilter -->|pass| RenouncedFilter
    RenouncedFilter -->|filter pass event| BotEngine

    BotEngine -->|enqueue job| ExecInterface
    ExecInterface -->|strategy| DefaultExec
    ExecInterface -->|strategy| JitoExec
    ExecInterface -->|strategy| WarpExec

    DefaultExec -->|send tx| SolanaHTTP
    JitoExec -->|send tx| JitoRPC
    WarpExec -->|send tx| WarpAPI

    HelpersLogger -->|utilities| BotEngine
    HelpersLogger -->|utilities| MarketListener
    HelpersLogger -->|utilities| CacheManager
    HelpersLogger -->|utilities| ExecInterface

    %% Snipe List refresh
    Entrypoint -->|timer| SnipeService
    SnipeService -->|load list| SnipeCache

    Entrypoint -->|bootstrap| BotEngine
    Entrypoint -->|bootstrap| ConfigLoader
    EnvConfig -->|template| ConfigLoader

    %% Click Events
    click ConfigLoader "https://github.com/warp-id/solana-trading-bot/blob/master/helpers/constants.ts"
    click BotEngine "https://github.com/warp-id/solana-trading-bot/blob/master/bot.ts"
    click BotEngine "https://github.com/warp-id/solana-trading-bot/blob/master/index.ts"
    click MarketListener "https://github.com/warp-id/solana-trading-bot/blob/master/listeners/listeners.ts"
    click MarketListener "https://github.com/warp-id/solana-trading-bot/blob/master/listeners/index.ts"
    click MarketCache "https://github.com/warp-id/solana-trading-bot/blob/master/cache/market.cache.ts"
    click PoolCache "https://github.com/warp-id/solana-trading-bot/blob/master/cache/pool.cache.ts"
    click SnipeCache "https://github.com/warp-id/solana-trading-bot/blob/master/cache/snipe-list.cache.ts"
    click BurnFilter "https://github.com/warp-id/solana-trading-bot/blob/master/filters/burn.filter.ts"
    click MutableFilter "https://github.com/warp-id/solana-trading-bot/blob/master/filters/mutable.filter.ts"
    click PoolFilters "https://github.com/warp-id/solana-trading-bot/blob/master/filters/pool-filters.ts"
    click PoolSizeFilter "https://github.com/warp-id/solana-trading-bot/blob/master/filters/pool-size.filter.ts"
    click RenouncedFilter "https://github.com/warp-id/solana-trading-bot/blob/master/filters/renounced.filter.ts"
    click SnipeService "https://github.com/warp-id/solana-trading-bot/blob/master/cache/snipe-list.cache.ts"
    click SnipeService "https://github.com/warp-id/solana-trading-bot/blob/master/snipe-list.txt"
    click ExecInterface "https://github.com/warp-id/solana-trading-bot/blob/master/transactions/transaction-executor.interface.ts"
    click DefaultExec "https://github.com/warp-id/solana-trading-bot/blob/master/transactions/default-transaction-executor.ts"
    click JitoExec "https://github.com/warp-id/solana-trading-bot/blob/master/transactions/jito-rpc-transaction-executor.ts"
    click WarpExec "https://github.com/warp-id/solana-trading-bot/blob/master/transactions/warp-transaction-executor.ts"
    click HelpersLogger "https://github.com/warp-id/solana-trading-bot/blob/master/helpers/index.ts"
    click HelpersLogger "https://github.com/warp-id/solana-trading-bot/blob/master/helpers/logger.ts"
    click HelpersLogger "https://github.com/warp-id/solana-trading-bot/blob/master/helpers/market.ts"
    click HelpersLogger "https://github.com/warp-id/solana-trading-bot/blob/master/helpers/token.ts"
    click HelpersLogger "https://github.com/warp-id/solana-trading-bot/blob/master/helpers/liquidity.ts"
    click HelpersLogger "https://github.com/warp-id/solana-trading-bot/blob/master/helpers/wallet.ts"
    click HelpersLogger "https://github.com/warp-id/solana-trading-bot/blob/master/helpers/promises.ts"
    click Entrypoint "https://github.com/warp-id/solana-trading-bot/blob/master/index.ts"
    click EnvConfig "https://github.com/warp-id/solana-trading-bot/blob/master/.env.copy"

    %% Styles
    classDef internal fill:#d0ebff,stroke:#74c0fc
    classDef cache fill:#d9f7be,stroke:#52c41a
    classDef external fill:#fff1b8,stroke:#faad14
    classDef filter fill:#ffd8bf,stroke:#fa8c16
    classDef executor fill:#e6fcff,stroke:#13c2c2
    classDef helper fill:#f9f0ff,stroke:#9254de
```
