# chainstacklabs/pump-fun-bot architecture

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

- Interactive diagram: https://gitdiagram.com/chainstacklabs/pump-fun-bot
- Repository: https://github.com/chainstacklabs/pump-fun-bot

## Overview

##### Project type and purpose
- Type: An event-driven, CLI-based trading/sniping tool (open-source bot)
- Purpose: Listen to on-chain events (new token mint, migrations), calculate bonding-curve details, and automatically submit buy/sell transactions on Solana.

##### File structure
- Top-level folders:
– bots/ (YAML configuration templates for each bot instance)
– idl/ (JSON IDL definitions for interacting with Solana programs)
– src/
· bot_runner.py (entry point)
· config_loader.py (loads .env and YAML)
· core/ (RPC client, curve math, wallet abstraction, priority-fee management)
· monitoring/ (listeners & event processors for blockSubscribe, logsSubscribe, Geyser)
· trading/ (buyer, seller, trader orchestration)
· cleanup/ (post-trade account cleanup manager)
· utils/ (logging)
– learning-examples/ (sample scripts and deep-dive code; not part of core runtime)
– tests/ (unit tests for listeners)

##### Key external dependencies
- Solana RPC endpoints (e.g., Chainstack Solana Trader nodes)
- Geyser gRPC streams (via proto in src/geyser)
- YAML bot definitions (configure strategy, endpoints, keys)

##### Main components & relationships
A. Configuration Layer
– .env loader & bots/*.yaml → config_loader
– Supplies RPC URLs, private key, RPS settings, strategy parameters
B. Bot Runner (Orchestrator)
– Reads configuration
– Initializes Monitoring, Trading, and Cleanup subsystems
C. Monitoring Subsystem (Event Sources)
– BlockListener (uses blockSubscribe via RPC)
– LogsListener (uses logsSubscribe via RPC)
– GeyserListener (gRPC subscription)
→ Each listener pushes raw events to its corresponding EventProcessor
D. Event Processing Layer
– block_event_processor, logs_event_processor, geyser_event_processor
– Decode events, parse relevant data (e.g., token mint, bonding curve address) via IDL
– Emit standardized “TokenMinted” or “CurveMigrated” events
E. Trading Engine
– Trader class subscribes to processed events
– Computes on-the-fly PDAs (compute_associated_bonding_curve)
– Buyer/Seller modules build and sign transactions via core.client & core.wallet
– PriorityFeeManager adjusts dynamic or fixed fees
– Sends transactions to RPC endpoints
F. Cleanup Manager
– Runs in parallel or post-trade
– Closes or reclaims associated accounts upon failures
G. Logging & Metrics
– utils.logger captures debug/trade logs → trades/trades.log
– (Optional) Extend to Prometheus or external monitoring

##### Architectural patterns & design principles
- Modular, layered architecture (Config → Source → Process → Act → Cleanup)
- Event-driven pipeline with interchangeable listeners (Strategy pattern)
- Separation of concerns: core Solana math & client abstracted from trading logic
- Plugin-like extensibility: add new listeners or trading strategies via subclassing

##### Final checklist
– [ ] Clear labels: component names & responsibility

## Diagram (Mermaid)

```mermaid
graph TB
    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        ENV[".env (.env.example)"]:::config
        YAML1["bots/bot-sniper-1-geyser.yaml"]:::config
        YAML2["bots/bot-sniper-2-logs.yaml"]:::config
        YAML3["bots/bot-sniper-3-blocks.yaml"]:::config
        CONFIG_LOADER["Configuration Loader"]:::config
    end

    %% Orchestrator
    BOT_RUNNER["Bot Runner\n(src/bot_runner.py)"]:::orchestrator

    %% Monitoring Subsystem
    subgraph "Monitoring Subsystem"
        direction TB
        BLOCK_LISTENER["BlockListener\n(src/monitoring/block_listener.py)"]:::monitor
        LOGS_LISTENER["LogsListener\n(src/monitoring/logs_listener.py)"]:::monitor
        GEYSER_LISTENER["GeyserListener\n(src/monitoring/geyser_listener.py)"]:::monitor
    end

    %% Event Processing Layer
    subgraph "Event Processing Layer"
        direction TB
        BLOCK_PROC["block_event_processor\n(src/monitoring/block_event_processor.py)"]:::processor
        LOGS_PROC["logs_event_processor\n(src/monitoring/logs_event_processor.py)"]:::processor
        GEYSER_PROC["geyser_event_processor\n(src/monitoring/geyser_event_processor.py)"]:::processor
    end

    %% Trading Engine
    subgraph "Trading Engine"
        direction TB
        TRADER["Trader Orchestration\n(src/trading/trader.py)"]:::trading
        BUYER["Buyer Module\n(src/trading/buyer.py)"]:::trading
        SELLER["Seller Module\n(src/trading/seller.py)"]:::trading
        BASE["Common Base\n(src/trading/base.py)"]:::trading
    end

    %% Cleanup Manager
    subgraph "Cleanup Manager"
        direction TB
        CLEANUP_MGR["Cleanup Manager\n(src/cleanup/manager.py)"]:::cleanup
        CLEANUP_MODES["Cleanup Modes\n(src/cleanup/modes.py)"]:::cleanup
    end

    %% Core Abstractions
    subgraph "Core"
        direction TB
        CLIENT["Core Client\n(src/core/client.py)"]:::core
        WALLET["Core Wallet\n(src/core/wallet.py)"]:::core
        CURVE["Core Curve Math\n(src/core/curve.py)"]:::core
        PUBKEYS["Public Keys\n(src/core/pubkeys.py)"]:::core
        subgraph "Priority Fee Management"
            direction TB
            PF_MANAGER["Manager\n(src/core/priority_fee/manager.py)"]:::core
            PF_DYNAMIC["Dynamic Fee\n(src/core/priority_fee/dynamic_fee.py)"]:::core
            PF_FIXED["Fixed Fee\n(src/core/priority_fee/fixed_fee.py)"]:::core
        end
    end

    %% IDL Definitions
    subgraph "IDL Definitions"
        direction TB
        IDL1["pump_fun_idl.json\n(idl/pump_fun_idl.json)"]:::external
        IDL2["pump_swap_idl.json\n(idl/pump_swap_idl.json)"]:::external
        IDL3["raydium_amm_idl.json\n(idl/raydium_amm_idl.json)"]:::external
    end

    %% Geyser Protos & Generated Code
    subgraph "Geyser gRPC"
        direction TB
        GEY_PROTO1["geyser.proto\n(src/geyser/proto/geyser.proto)"]:::external
        GEY_PROTO2["solana-storage.proto\n(src/geyser/proto/solana-storage.proto)"]:::external
        GEN1["geyser_pb2.py\n(src/geyser/generated/geyser_pb2.py)"]:::external
        GEN2["geyser_pb2_grpc.py\n(src/geyser/generated/geyser_pb2_grpc.py)"]:::external
        GEN3["solana_storage_pb2.py\n(src/geyser/generated/solana_storage_pb2.py)"]:::external
        GEN4["solana_storage_pb2_grpc.py\n(src/geyser/generated/solana_storage_pb2_grpc.py)"]:::external
    end

    %% Logging & Metrics
    LOGGER["Logger Utility\n(src/utils/logger.py)"]:::util
    TRADE_LOGS["trades/trades.log"]:::util

    %% External Services
    RPC["Solana RPC Endpoint"]:::externalSvc
    GEY_GRPC["Geyser gRPC Stream"]:::externalSvc

    %% Connections
    ENV -->|reads| CONFIG_LOADER
    YAML1 -->|reads| CONFIG_LOADER
    YAML2 -->|reads| CONFIG_LOADER
    YAML3 -->|reads| CONFIG_LOADER
    CONFIG_LOADER -->|provides config| BOT_RUNNER:::green

    BOT_RUNNER -->|instantiates| BLOCK_LISTENER
    BOT_RUNNER -->|instantiates| LOGS_LISTENER
    BOT_RUNNER -->|instantiates| GEYSER_LISTENER
    BOT_RUNNER -->|starts| TRADER
    BOT_RUNNER -->|starts| CLEANUP_MGR

    BLOCK_LISTENER -->|RawSubscribeEvent| BLOCK_PROC
    LOGS_LISTENER -->|RawSubscribeEvent| LOGS_PROC
    GEYSER_LISTENER -->|RawSubscribeEvent| GEYSER_PROC

    BLOCK_PROC -->|TokenMinted/C.migrated| TRADER
    LOGS_PROC -->|TokenMinted/C.migrated| TRADER
    GEYSER_PROC -->|TokenMinted/C.migrated| TRADER

    TRADER -->|uses| BUYER
    TRADER -->|uses| SELLER
    BUYER -->|extends| BASE
    SELLER -->|extends| BASE

    TRADER -->|compute PDA| CURVE
    TRADER -->|sign tx| WALLET
    TRADER -->|build tx| CLIENT
    TRADER -->|adjust fee| PF_MANAGER
    PF_MANAGER -->|calls| PF_DYNAMIC
    PF_MANAGER -->|calls| PF_FIXED
    TRADER -->|send SignedTransaction| RPC:::red

    RPC -->|feedback| BLOCK_LISTENER
    RPC -->|feedback| LOGS_LISTENER

    CLEANUP_MGR -->|cleanup accounts| CLIENT
    CLEANUP_MGR -->|modes| CLEANUP_MODES

    TRADER -->|logs| LOGGER
    LOGGER -->|writes| TRADE_LOGS

    %% IDL and Protos Usage
    BLOCK_PROC -->|uses IDL| IDL1
    BLOCK_PROC -->|uses IDL| IDL2
    LOGS_PROC -->|uses IDL| IDL3
    GEYSER_PROC -->|uses| GEY_PROTO1
    GEYSER_PROC -->|uses| GEY_PROTO2
    GEY_PROTO1 --> GEN1
    GEY_PROTO1 --> GEN2
    GEY_PROTO2 --> GEN3
    GEY_PROTO2 --> GEN4

    %% External Streams
    GEYSER_LISTENER -->|gRPC stream| GEY_GRPC

    %% Click Events
    click CONFIG_LOADER "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/config_loader.py"
    click YAML1 "https://github.com/chainstacklabs/pump-fun-bot/blob/main/bots/bot-sniper-1-geyser.yaml"
    click YAML2 "https://github.com/chainstacklabs/pump-fun-bot/blob/main/bots/bot-sniper-2-logs.yaml"
    click YAML3 "https://github.com/chainstacklabs/pump-fun-bot/blob/main/bots/bot-sniper-3-blocks.yaml"
    click ENV "https://github.com/chainstacklabs/pump-fun-bot/blob/main/.env.example"
    click BOT_RUNNER "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/bot_runner.py"
    click BLOCK_LISTENER "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/monitoring/block_listener.py"
    click LOGS_LISTENER "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/monitoring/logs_listener.py"
    click GEYSER_LISTENER "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/monitoring/geyser_listener.py"
    click BLOCK_PROC "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/monitoring/block_event_processor.py"
    click LOGS_PROC "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/monitoring/logs_event_processor.py"
    click GEYSER_PROC "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/monitoring/geyser_event_processor.py"
    click TRADER "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/trading/trader.py"
    click BUYER "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/trading/buyer.py"
    click SELLER "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/trading/seller.py"
    click BASE "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/trading/base.py"
    click CLEANUP_MGR "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/cleanup/manager.py"
    click CLEANUP_MODES "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/cleanup/modes.py"
    click CLIENT "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/core/client.py"
    click WALLET "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/core/wallet.py"
    click CURVE "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/core/curve.py"
    click PF_MANAGER "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/core/priority_fee/manager.py"
    click PF_DYNAMIC "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/core/priority_fee/dynamic_fee.py"
    click PF_FIXED "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/core/priority_fee/fixed_fee.py"
    click PUBKEYS "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/core/pubkeys.py"
    click IDL1 "https://github.com/chainstacklabs/pump-fun-bot/blob/main/idl/pump_fun_idl.json"
    click IDL2 "https://github.com/chainstacklabs/pump-fun-bot/blob/main/idl/pump_swap_idl.json"
    click IDL3 "https://github.com/chainstacklabs/pump-fun-bot/blob/main/idl/raydium_amm_idl.json"
    click GEY_PROTO1 "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/geyser/proto/geyser.proto"
    click GEY_PROTO2 "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/geyser/proto/solana-storage.proto"
    click GEN1 "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/geyser/generated/geyser_pb2.py"
    click GEN2 "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/geyser/generated/geyser_pb2_grpc.py"
    click GEN3 "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/geyser/generated/solana_storage_pb2.py"
    click GEN4 "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/geyser/generated/solana_storage_pb2_grpc.py"
    click LOGGER "https://github.com/chainstacklabs/pump-fun-bot/blob/main/src/utils/logger.py"

    %% Styles
    classDef config fill:#e3f2fd,stroke:#90caf9;
    classDef orchestrator fill:#fff3e0,stroke:#ffb74d;
    classDef monitor fill:#e8f5e9,stroke:#66bb6a;
    classDef processor fill:#f3e5f5,stroke:#ab47bc;
    classDef trading fill:#ede7f6,stroke:#7e57c2;
    classDef cleanup fill:#ffebee,stroke:#ef5350;
    classDef core fill:#e0f7fa,stroke:#26c6da;
    classDef util fill:#fffde7,stroke:#ffee58;
    classDef external fill:#eeeeee,stroke:#bdbdbd,stroke-dasharray: 5 5;
    classDef externalSvc fill:#ffe0b2,stroke:#ff9800,stroke-dasharray: 5 5;
    class config_loader,ENV,YAML1,YAML2,YAML3 config
    class BOT_RUNNER orchestrator
    class BLOCK_LISTENER,LOGS_LISTENER,GEYSER_LISTENER monitor
    class BLOCK_PROC,LOGS_PROC,GEYSER_PROC processor
    class TRADER,BUYER,SELLER,BASE trading
    class CLEANUP_MGR,CLEANUP_MODES cleanup
    class CLIENT,WALLET,CURVE,PUBKEYS,PF_MANAGER,PF_DYNAMIC,PF_FIXED core
    class LOGGER,TRADE_LOGS util
```
