mirror of
https://github.com/chainstacklabs/pumpfun-bonkfun-bot.git
synced 2026-07-27 23:37:45 +00:00
wip(core): platform aware trading
This commit is contained in:
smypmsa
@@ -1,130 +0,0 @@
|
||||
---
|
||||
description: Comprehensive configuration guide for trading bots in the pump-bot system. Apply when configuring bots.
|
||||
globs: bots/*.yaml
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Bot Configuration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
- YAML files in the `bots/` directory define configurations for different bot strategies and behaviors.
|
||||
- Each file specifies parameters for a specific bot instance or strategy.
|
||||
- Configurations control execution parameters, trading strategies, risk management, and connection settings.
|
||||
|
||||
## Required Configuration Sections
|
||||
|
||||
### Bot Identification and Connection Settings
|
||||
|
||||
```yaml
|
||||
name: "bot-name" # Unique identifier for the bot
|
||||
env_file: ".env" # Environment file for secrets
|
||||
rpc_endpoint: "${ENV_VAR}" # Solana RPC endpoint
|
||||
wss_endpoint: "${ENV_VAR}" # Solana WebSocket endpoint
|
||||
private_key: "${ENV_VAR}" # Private key for transactions
|
||||
enabled: true # Enable/disable bot without removing config
|
||||
separate_process: true # Run in a separate process
|
||||
```
|
||||
|
||||
### Trading Parameters
|
||||
|
||||
```yaml
|
||||
trade:
|
||||
buy_amount: 0.0001 # Amount of SOL to spend (in SOL)
|
||||
buy_slippage: 0.3 # Maximum price deviation for buys (0.3 = 30%)
|
||||
sell_slippage: 0.3 # Maximum price deviation for sells (0.3 = 30%)
|
||||
|
||||
# Exit strategy
|
||||
exit_strategy: "time_based" # Options: "time_based", "tp_sl", "manual"
|
||||
take_profit_percentage: 0.2 # Required for "tp_sl" strategy (0.2 = 20%)
|
||||
stop_loss_percentage: 0.2 # Required for "tp_sl" strategy (0.2 = 20%)
|
||||
max_hold_time: 60 # Maximum hold time in seconds
|
||||
```
|
||||
|
||||
### Listener Configuration
|
||||
|
||||
Specify one of the following listener types:
|
||||
|
||||
#### Geyser (Fastest Updates)
|
||||
|
||||
```yaml
|
||||
geyser:
|
||||
endpoint: "${ENV_VAR}"
|
||||
api_token: "${ENV_VAR}"
|
||||
auth_type: "x-token" # or "basic"
|
||||
```
|
||||
|
||||
#### Logs Listener
|
||||
|
||||
```yaml
|
||||
logs:
|
||||
program_id: "${PROGRAM_ID}" # Program to monitor
|
||||
refresh_interval: 1 # Polling interval in seconds
|
||||
```
|
||||
|
||||
#### Blocks Listener
|
||||
|
||||
```yaml
|
||||
blocks:
|
||||
refresh_interval: 1 # Block polling interval in seconds
|
||||
```
|
||||
|
||||
#### PumpPortal Listener
|
||||
|
||||
```yaml
|
||||
pumpportal:
|
||||
endpoint: "${PP_ENDPOINT}" # PumpPortal API endpoint
|
||||
api_key: "${PP_API_KEY}" # API key for authentication
|
||||
```
|
||||
|
||||
### Filters
|
||||
|
||||
```yaml
|
||||
filters:
|
||||
listener_type: "geyser" # One of: "logs", "blocks", "geyser", "pumpportal"
|
||||
max_token_age: 10 # Maximum age of tokens to consider (in seconds)
|
||||
min_liquidity_sol: 0.1 # Minimum liquidity in SOL
|
||||
exclude_tokens: ["TOKEN1", "TOKEN2"] # Tokens to exclude
|
||||
```
|
||||
|
||||
### Priority Fees (Optional)
|
||||
|
||||
```yaml
|
||||
priority_fees:
|
||||
enabled: true # Enable priority fees
|
||||
fixed_amount: 10000 # Fixed fee amount in lamports
|
||||
extra_percentage: 0.1 # Extra percentage of transaction cost (0.1 = 10%)
|
||||
hard_cap: 100000 # Maximum fee cap in lamports
|
||||
```
|
||||
|
||||
### Error Handling and Retries (Optional)
|
||||
|
||||
```yaml
|
||||
retries:
|
||||
max_attempts: 3 # Maximum retry attempts
|
||||
backoff_factor: 1.5 # Backoff multiplier between retries
|
||||
initial_wait: 1 # Initial wait time in seconds
|
||||
```
|
||||
|
||||
### Cleanup Settings (Optional)
|
||||
|
||||
```yaml
|
||||
cleanup:
|
||||
mode: "after_sell" # Options: "disabled", "on_fail", "after_sell", "post_session"
|
||||
keep_min_balance: true # Keep minimum balance in accounts
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
- Numeric values must be within specified ranges (e.g., slippage between 0-1)
|
||||
- Required fields must be present and correctly formatted
|
||||
- Enum-like fields must use valid values from predefined options
|
||||
|
||||
## Examples
|
||||
|
||||
See sample configurations in the `bots/` directory:
|
||||
- @bot-sniper-1-geyser.yaml: Fast trading using Geyser stream
|
||||
- @bot-sniper-2-logs.yaml: Trading based on log monitoring
|
||||
- @bot-sniper-3-blocks.yaml: Trading based on block monitoring
|
||||
- @bot-sniper-4-pp.yaml: Trading using PumpPortal integration
|
||||
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
description: Comprehensive guide for account cleanup operations and resource management. Apply when working with token account cleanup operations.
|
||||
globs: src/cleanup/*.py
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Account Cleanup System Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The cleanup module handles the safe management and disposal of Solana token accounts after trading operations. This system ensures resources are properly released and minimizes unnecessary account maintenance fees.
|
||||
|
||||
## Core Components
|
||||
|
||||
### AccountCleanupManager
|
||||
|
||||
@src/cleanup/manager.py implements the `AccountCleanupManager` class which:
|
||||
- Handles safe cleanup of Associated Token Accounts (ATAs)
|
||||
- Manages token burning operations when needed
|
||||
- Implements proper account closure to recover rent
|
||||
- Integrates with priority fee systems for high-congestion scenarios
|
||||
|
||||
```python
|
||||
# Example usage
|
||||
cleanup_manager = AccountCleanupManager(client, wallet, priority_fee_manager, use_priority_fees)
|
||||
await cleanup_manager.cleanup_ata(token_mint)
|
||||
```
|
||||
|
||||
### Cleanup Modes
|
||||
|
||||
@src/cleanup/modes.py defines various cleanup strategies and their implementation:
|
||||
|
||||
1. **Disabled** - No automatic cleanup performed
|
||||
2. **On Failure** - Clean up accounts only after transaction failures
|
||||
3. **After Sell** - Clean up accounts after successful sell operations
|
||||
4. **Post-Session** - Clean up all empty accounts when a trading session ends
|
||||
|
||||
```python
|
||||
# Example implementation
|
||||
if should_cleanup_after_sell(cleanup_mode):
|
||||
await manager.cleanup_ata(mint)
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Account cleanup is configured in bot YAML files:
|
||||
|
||||
```yaml
|
||||
cleanup:
|
||||
mode: "post_session" # Options: "disabled", "on_fail", "after_sell", "post_session"
|
||||
force_close_with_burn: false # Force burn remaining tokens before closing
|
||||
with_priority_fee: false # Use priority fees for cleanup transactions
|
||||
```
|
||||
|
||||
## When to Use Each Mode
|
||||
|
||||
| Mode | Use Case |
|
||||
|------|----------|
|
||||
| `disabled` | Development/testing or when manual account management is preferred |
|
||||
| `on_fail` | Conservative approach to only clean up failed transaction remnants |
|
||||
| `after_sell` | Balance between efficiency and account reuse |
|
||||
| `post_session` | Maximum cleanup, recommended for production |
|
||||
|
||||
## Related Files
|
||||
|
||||
- @src/cleanup/manager.py: Core account cleanup implementation
|
||||
- @src/cleanup/modes.py: Cleanup mode strategies and handlers
|
||||
- @src/core/client.py: Solana client interface used by cleanup operations
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
description: Core blockchain interaction components and Solana protocol abstractions. Apply when working with blockchain operations, transactions, or protocol-specific logic.
|
||||
globs: src/core/*.py
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Core Blockchain Components Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The core module provides essential abstractions and utilities for interacting with the Solana blockchain, managing wallets, handling transactions, and working with protocol-specific logic such as bonding curves and token operations.
|
||||
|
||||
## Key Components
|
||||
|
||||
### Solana Client
|
||||
|
||||
@src/core/client.py implements the `SolanaClient` class which:
|
||||
- Handles RPC communication with Solana nodes
|
||||
- Manages transaction submission and confirmation
|
||||
- Provides methods for account data retrieval and subscription
|
||||
- Implements retry logic and error handling for blockchain operations
|
||||
|
||||
```python
|
||||
# Example usage
|
||||
client = SolanaClient(rpc_endpoint, wss_endpoint)
|
||||
await client.get_token_account_data(token_account)
|
||||
```
|
||||
|
||||
### Wallet Management
|
||||
|
||||
@src/core/wallet.py provides wallet functionality:
|
||||
- Secure private key handling
|
||||
- Transaction signing
|
||||
- Account derivation and management
|
||||
- Integration with hardware wallets (where applicable)
|
||||
|
||||
### Public Key Management
|
||||
|
||||
@src/core/pubkeys.py contains:
|
||||
- System address constants
|
||||
- Program ID references
|
||||
- Address derivation utilities
|
||||
- Token account resolution functions
|
||||
|
||||
### Bonding Curve Mathematics
|
||||
|
||||
@src/core/curve.py offers:
|
||||
- Mathematical models for bonding curve calculations
|
||||
- Price impact estimation
|
||||
- Liquidity modeling
|
||||
- Swap pricing utilities
|
||||
|
||||
### Priority Fee Management
|
||||
|
||||
@src/core/priority_fee/manager.py implements:
|
||||
- Dynamic priority fee calculation
|
||||
- Fee cap enforcement
|
||||
- Network congestion detection
|
||||
- Transaction prioritization strategies
|
||||
|
||||
## Common Operations
|
||||
|
||||
| Operation | Key Functions |
|
||||
|-----------|--------------|
|
||||
| Send Transaction | `client.send_transaction(tx, opts)` |
|
||||
| Get Account Data | `client.get_account_info(pubkey)` |
|
||||
| Sign Message | `wallet.sign_message(message)` |
|
||||
| Calculate Price | `curve.calculate_price_impact(amount)` |
|
||||
|
||||
## Related Files
|
||||
|
||||
- @src/core/client.py: Solana RPC client implementation
|
||||
- @src/core/wallet.py: Wallet and signing functionality
|
||||
- @src/core/pubkeys.py: Address management and derivation
|
||||
- @src/core/curve.py: Bonding curve and pricing mathematics
|
||||
- @src/core/priority_fee/manager.py: Transaction fee optimization
|
||||
@@ -1,89 +0,0 @@
|
||||
---
|
||||
description: Program interface definitions for on-chain contract interactions. Apply when working with smart contract integration or program data structures.
|
||||
globs: idl/*.json
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Interface Definition Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The IDL (Interface Definition Language) files define the structure and interface of on-chain Solana programs. These definitions enable the bot to interact with smart contracts, serialize/deserialize data, and interpret on-chain events correctly.
|
||||
|
||||
## Core IDL Files
|
||||
|
||||
### Pump Fun IDL
|
||||
|
||||
@idl/pump_fun_idl.json contains the core protocol definitions:
|
||||
- Main pump.fun protocol instruction schemas
|
||||
- Account structures and data layouts
|
||||
- Token creation and management instructions
|
||||
- Event definitions and discriminators
|
||||
|
||||
### Pump Swap IDL
|
||||
|
||||
@idl/pump_swap_idl.json defines the swap interface:
|
||||
- Token swap instruction formats
|
||||
- Liquidity management operations
|
||||
- Price calculation functions
|
||||
- Fee structure definitions
|
||||
|
||||
### Raydium AMM IDL
|
||||
|
||||
@idl/raydium_amm_idl.json provides integration with Raydium:
|
||||
- AMM pool interface definitions
|
||||
- Liquidity provider instructions
|
||||
- Market making operations
|
||||
- Price discovery mechanisms
|
||||
|
||||
## Working with IDLs
|
||||
|
||||
IDL files are used throughout the codebase for:
|
||||
|
||||
```python
|
||||
# Example: Using IDLs for instruction building
|
||||
with open("idl/pump_fun_idl.json", "r") as f:
|
||||
pump_idl = json.load(f)
|
||||
|
||||
# Extract instruction discriminator
|
||||
discriminator = bytes(pump_idl["instructions"][0]["discriminator"])
|
||||
```
|
||||
|
||||
## IDL Structure
|
||||
|
||||
Each IDL file follows this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"address": "Program address on chain",
|
||||
"metadata": {
|
||||
"name": "Program name",
|
||||
"version": "Version number"
|
||||
},
|
||||
"instructions": [
|
||||
{
|
||||
"name": "instructionName",
|
||||
"discriminator": [byte array],
|
||||
"accounts": [...],
|
||||
"args": [...]
|
||||
}
|
||||
],
|
||||
"accounts": [...],
|
||||
"events": [...]
|
||||
}
|
||||
```
|
||||
|
||||
## IDL Usage
|
||||
|
||||
| Component | Usage |
|
||||
|-----------|-------|
|
||||
| Instructions | Building transaction instructions |
|
||||
| Discriminators | Identifying program events in logs |
|
||||
| Accounts | Parsing account data |
|
||||
| Events | Interpreting program-emitted events |
|
||||
|
||||
## Related Files
|
||||
|
||||
- @idl/pump_fun_idl.json: Main pump.fun protocol definition
|
||||
- @idl/pump_swap_idl.json: Swap functionality interface
|
||||
- @idl/raydium_amm_idl.json: Raydium AMM integration
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
description: Event monitoring and data collection systems for tracking blockchain activity. Apply when implementing token detection, event processing, or subscription logic.
|
||||
globs: src/monitoring/*.py
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Monitoring System Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The monitoring module provides various mechanisms to detect and process events from the Solana blockchain. It offers multiple strategies for token discovery, event filtering, and real-time notifications through different data sources.
|
||||
|
||||
## Listener Architecture
|
||||
|
||||
### Base Listener
|
||||
|
||||
@src/monitoring/base_listener.py defines the abstract base class `BaseTokenListener` which:
|
||||
- Provides a common interface for all token listeners
|
||||
- Declares required methods for event subscription
|
||||
- Standardizes token event processing
|
||||
|
||||
```python
|
||||
# Common listener interface
|
||||
async def listen_for_tokens(
|
||||
self,
|
||||
token_callback: Callable[[TokenInfo], Awaitable[None]],
|
||||
match_string: str | None = None,
|
||||
creator_address: str | None = None,
|
||||
) -> None:
|
||||
pass
|
||||
```
|
||||
|
||||
### Listener Implementations
|
||||
|
||||
#### Geyser Listener (Fastest)
|
||||
|
||||
@src/monitoring/geyser_listener.py implements the Geyser-based listener:
|
||||
- Direct connection to Geyser WebSocket endpoint
|
||||
- Lowest latency for token detection
|
||||
- Advanced filtering capabilities
|
||||
|
||||
#### Logs Listener
|
||||
|
||||
@src/monitoring/logs_listener.py provides log-based monitoring:
|
||||
- Subscription to program logs
|
||||
- Pattern matching for token creation events
|
||||
- Program-specific event detection
|
||||
|
||||
#### Block Listener
|
||||
|
||||
@src/monitoring/block_listener.py implements block-based scanning:
|
||||
- Processes entire blocks
|
||||
- Extracts transaction data
|
||||
- Identifies token creation events
|
||||
|
||||
#### PumpPortal Listener
|
||||
|
||||
@src/monitoring/pumpportal_listener.py offers integration with external service:
|
||||
- Connects to PumpPortal API
|
||||
- Receives preprocessed token events
|
||||
- Simplifies integration with third-party data providers
|
||||
|
||||
## Event Processing
|
||||
|
||||
Each listener has a corresponding event processor that:
|
||||
- Validates incoming events
|
||||
- Extracts relevant token information
|
||||
- Applies filtering rules
|
||||
- Dispatches events to trading components
|
||||
|
||||
## Configuration
|
||||
|
||||
In bot configuration files, specify the listener type:
|
||||
|
||||
```yaml
|
||||
filters:
|
||||
listener_type: "geyser" # Options: "logs", "blocks", "geyser", "pumpportal"
|
||||
max_token_age: 0.001 # Maximum token age in seconds
|
||||
```
|
||||
|
||||
## Comparison of Approaches
|
||||
|
||||
| Listener Type | Latency | CPU Usage | Reliability | Use Case |
|
||||
|---------------|---------|-----------|-------------|----------|
|
||||
| Geyser | Lowest | Medium | High | Production sniper bots |
|
||||
| Logs | Low | Low | High | General purpose |
|
||||
| Blocks | Medium | High | Very High | Deep scanning |
|
||||
| PumpPortal | Varies | Very Low | Depends | Easy integration |
|
||||
|
||||
## Related Files
|
||||
|
||||
- @src/monitoring/base_listener.py: Abstract listener interface
|
||||
- @src/monitoring/geyser_listener.py: Geyser-based implementation
|
||||
- @src/monitoring/logs_listener.py: Program log monitoring
|
||||
- @src/monitoring/block_listener.py: Block processing implementation
|
||||
- @src/monitoring/pumpportal_listener.py: External API integration
|
||||
@@ -1,89 +0,0 @@
|
||||
---
|
||||
description: Package management and command execution guidelines using uv. Apply when installing dependencies, running scripts, or managing the Python environment.
|
||||
globs: "**/*"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Package Management with UV
|
||||
|
||||
## Overview
|
||||
|
||||
This project exclusively uses `uv` as the package manager for all Python operations. UV is a fast Python package installer and resolver, written in Rust, that serves as a drop-in replacement for pip and other Python package managers.
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Use `uv` for all package operations** - Never use pip, pipenv, poetry, or conda
|
||||
2. **Use `uv run` for script execution** - Ensures proper virtual environment activation
|
||||
3. **Maintain consistency** - All documentation and examples should reference uv commands
|
||||
|
||||
## Package Installation
|
||||
|
||||
### Installing Dependencies
|
||||
|
||||
```bash
|
||||
# Install all project dependencies
|
||||
uv sync --extra dev
|
||||
|
||||
# Install additional packages
|
||||
uv add package-name
|
||||
|
||||
# Install from requirements file
|
||||
uv add -r requirements.txt
|
||||
```
|
||||
|
||||
### Managing Virtual Environments
|
||||
|
||||
```bash
|
||||
# Create virtual environment
|
||||
uv venv
|
||||
|
||||
# Activate virtual environment (if needed manually)
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
## Script Execution
|
||||
|
||||
### Running Bot Scripts
|
||||
|
||||
```bash
|
||||
# Primary method: Use the installed command
|
||||
pump_bot
|
||||
|
||||
# Alternative: Run bot_runner.py directly
|
||||
uv run src/bot_runner.py
|
||||
```
|
||||
|
||||
### Running Test Scripts
|
||||
|
||||
```bash
|
||||
# Run listener performance tests
|
||||
uv run tests/test_geyser_listener.py
|
||||
uv run tests/test_logs_listener.py
|
||||
uv run tests/test_block_listener.py
|
||||
|
||||
# Run comparative analysis
|
||||
uv run tests/compare_listeners.py
|
||||
uv run tests/compare_listeners.py 60
|
||||
```
|
||||
|
||||
### Development and Testing
|
||||
|
||||
```bash
|
||||
# Run linting
|
||||
uv run ruff check src/
|
||||
|
||||
# Run formatting
|
||||
uv run ruff format src/
|
||||
```
|
||||
|
||||
## Project Structure Integration
|
||||
|
||||
The project is configured to work seamlessly with uv:
|
||||
|
||||
- `pyproject.toml` - Defines project dependencies and the `pump_bot` command
|
||||
- `uv.lock` - Locks dependency versions for reproducible builds
|
||||
- `.venv/` - Virtual environment managed by uv
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
UV automatically detects and uses the virtual environment when running commands.
|
||||
@@ -1,115 +0,0 @@
|
||||
---
|
||||
description: Comprehensive overview of the project architecture and organization. Apply when working with the codebase structure or integrating new components.
|
||||
globs: *.md
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Project Structure Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The pump-bot system is organized into modular components with clear separation of concerns. This architecture facilitates maintainability, testing, and extension of functionality.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
### Source Code
|
||||
|
||||
The main codebase is organized as follows:
|
||||
|
||||
- @src/: Root source directory
|
||||
- @src/bot_runner.py: Entry point for bot execution
|
||||
- @src/config_loader.py: Configuration loading and validation
|
||||
|
||||
### Package Command
|
||||
|
||||
The project provides a convenient command-line interface:
|
||||
- `pump_bot`: Installed command that runs all enabled bots (defined in @pyproject.toml)
|
||||
- Alternative: `uv run src/bot_runner.py` for direct script execution
|
||||
|
||||
#### Core Components
|
||||
|
||||
- @src/core/: Blockchain interaction and protocol abstractions
|
||||
- @src/core/client.py: Solana client implementation
|
||||
- @src/core/wallet.py: Wallet management and transaction signing
|
||||
- @src/core/pubkeys.py: System and program addresses
|
||||
- @src/core/curve.py: Bonding curve mathematics
|
||||
- @src/core/priority_fee/: Priority fee optimization system
|
||||
|
||||
#### Trading System
|
||||
|
||||
- @src/trading/: Trading execution and strategy
|
||||
- @src/trading/trader.py: Main trading coordination
|
||||
- @src/trading/buyer.py: Token purchase implementation
|
||||
- @src/trading/seller.py: Token sale implementation
|
||||
- @src/trading/position.py: Position tracking and management
|
||||
- @src/trading/base.py: Shared abstractions
|
||||
|
||||
#### Monitoring System
|
||||
|
||||
- @src/monitoring/: Event detection and processing
|
||||
- @src/monitoring/geyser_listener.py: Geyser-based monitoring
|
||||
- @src/monitoring/logs_listener.py: Log-based monitoring
|
||||
- @src/monitoring/block_listener.py: Block-based monitoring
|
||||
- @src/monitoring/pumpportal_listener.py: PumpPortal integration
|
||||
- @src/monitoring/base_listener.py: Shared listener abstractions
|
||||
|
||||
#### Resource Management
|
||||
|
||||
- @src/cleanup/: Token account management
|
||||
- @src/cleanup/manager.py: Account cleanup operations
|
||||
- @src/cleanup/modes.py: Cleanup strategy implementation
|
||||
|
||||
#### Utilities
|
||||
|
||||
- @src/utils/: Shared utilities
|
||||
- @src/utils/logger.py: Logging framework
|
||||
- @src/utils/env.py: Environment configuration
|
||||
|
||||
### Configuration
|
||||
|
||||
- @bots/: Bot configuration files
|
||||
- @bots/bot-sniper-1-geyser.yaml: Geyser-based sniper configuration
|
||||
- @bots/bot-sniper-2-logs.yaml: Log-based sniper configuration
|
||||
- @bots/bot-sniper-3-blocks.yaml: Block-based sniper configuration
|
||||
- @bots/bot-sniper-4-pp.yaml: PumpPortal sniper configuration
|
||||
|
||||
### Program Interfaces
|
||||
|
||||
- @idl/: Interface definitions for on-chain programs
|
||||
- @idl/pump_fun_idl.json: Pump.fun protocol interface
|
||||
- @idl/pump_swap_idl.json: Swap interface definition
|
||||
- @idl/raydium_amm_idl.json: Raydium AMM interface
|
||||
|
||||
### Testing
|
||||
|
||||
- @tests/: Test cases and validation
|
||||
- @tests/compare_listeners.py: Listener comparison framework
|
||||
- @tests/test_geyser_listener.py: Geyser listener tests
|
||||
- @tests/test_logs_listener.py: Logs listener tests
|
||||
- @tests/test_block_listener.py: Block listener tests
|
||||
|
||||
### Operational Data
|
||||
|
||||
- @logs/: Application logs
|
||||
- @trades/: Trading activity records
|
||||
|
||||
## Development Flow
|
||||
|
||||
1. Configure bot parameters in @bots/*.yaml
|
||||
2. Launch bot using `uv run pump_bot` or `uv run src/bot_runner.py`
|
||||
3. Monitor execution in @logs/
|
||||
4. Review trade outcomes in @trades/trades.log
|
||||
|
||||
## Architecture Principles
|
||||
|
||||
1. **Modular Design**: Components have clear responsibilities and interfaces
|
||||
2. **Configurability**: External configuration for adjustable behavior
|
||||
3. **Extensibility**: Easy to add new listeners or trading strategies
|
||||
4. **Reliability**: Error handling and recovery throughout the system
|
||||
5. **Observability**: Comprehensive logging and monitoring
|
||||
|
||||
## Related Documents
|
||||
|
||||
- @README.md: Project overview and setup instructions
|
||||
- @MAINTAINERS.md: Maintenance guidelines and procedures
|
||||
- @CLAUDE.md: Development rules for Claude Code
|
||||
@@ -1,153 +0,0 @@
|
||||
---
|
||||
description: Performance testing and listener comparison scripts for token detection systems. Apply when benchmarking listener performance or validating detection accuracy.
|
||||
globs: tests/*.py
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Listener Performance Testing Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The test scripts provide performance comparison and validation tools for different listener implementations. These are standalone scripts designed to measure which listener is fastest at discovering new tokens, helping optimize the bot's detection capabilities.
|
||||
|
||||
## Individual Listener Tests
|
||||
|
||||
Each listener has a dedicated test script for standalone performance analysis:
|
||||
|
||||
### Geyser Listener Test
|
||||
|
||||
@tests/test_geyser_listener.py tests the fastest detection method:
|
||||
- Direct gRPC connection to Geyser endpoint
|
||||
- Real-time token creation monitoring
|
||||
- Performance measurement and token logging
|
||||
|
||||
```bash
|
||||
# Run Geyser listener test for 30 seconds
|
||||
uv run tests/test_geyser_listener.py
|
||||
```
|
||||
|
||||
### Logs Listener Test
|
||||
|
||||
@tests/test_logs_listener.py validates log-based monitoring:
|
||||
- WebSocket subscription to program logs
|
||||
- Pattern matching for token creation events
|
||||
- Detection accuracy verification
|
||||
|
||||
```bash
|
||||
# Run logs listener test
|
||||
uv run tests/test_logs_listener.py
|
||||
```
|
||||
|
||||
### Block Listener Test
|
||||
|
||||
@tests/test_block_listener.py tests block-based scanning:
|
||||
- Full block processing for token discovery
|
||||
- Transaction analysis and extraction
|
||||
- Comprehensive but potentially slower detection
|
||||
|
||||
```bash
|
||||
# Run block listener test
|
||||
uv run tests/test_block_listener.py
|
||||
```
|
||||
|
||||
## Comparative Performance Analysis
|
||||
|
||||
### Listener Comparison Tool
|
||||
|
||||
@tests/compare_listeners.py runs all listeners simultaneously:
|
||||
- Side-by-side performance measurement
|
||||
- Detection speed comparison with timing data
|
||||
- Accuracy analysis (tokens detected by each method)
|
||||
- Statistical reporting on detection overlap
|
||||
|
||||
```bash
|
||||
# Compare all listeners for 60 seconds
|
||||
uv run tests/compare_listeners.py 60
|
||||
|
||||
# Default 60-second comparison
|
||||
uv run tests/compare_listeners.py
|
||||
```
|
||||
|
||||
### Performance Metrics
|
||||
|
||||
The comparison tool provides:
|
||||
|
||||
| Metric | Description |
|
||||
|--------|-------------|
|
||||
| Detection Speed | Time to detect each token (microsecond precision) |
|
||||
| Detection Count | Total tokens found by each listener |
|
||||
| Overlap Analysis | Tokens detected by multiple listeners |
|
||||
| Unique Detections | Tokens found only by specific listeners |
|
||||
|
||||
## Test Output Analysis
|
||||
|
||||
### Individual Test Results
|
||||
|
||||
Each listener test displays:
|
||||
```
|
||||
==================================================
|
||||
NEW TOKEN: TokenName
|
||||
Symbol: SYMBOL
|
||||
Mint: TokenMintAddress
|
||||
URI: MetadataURI
|
||||
Creator: CreatorAddress
|
||||
==================================================
|
||||
```
|
||||
|
||||
### Comparison Results
|
||||
|
||||
The comparison tool generates:
|
||||
```
|
||||
Geyser detected: 15 tokens
|
||||
Logs detected: 12 tokens
|
||||
Block detected: 18 tokens
|
||||
|
||||
Token | Geyser | Logs | Block | Fastest
|
||||
------|--------|------|-------|--------
|
||||
ABC123... | 1.234567 | N/A | 2.345678 | Geyser
|
||||
DEF456... | 0.987654 | 1.123456 | 1.567890 | Geyser
|
||||
```
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
Tests require these environment variables:
|
||||
```bash
|
||||
export SOLANA_NODE_RPC_ENDPOINT="https://api.mainnet-beta.solana.com"
|
||||
export SOLANA_NODE_WSS_ENDPOINT="wss://api.mainnet-beta.solana.com"
|
||||
export GEYSER_ENDPOINT="wss://your-geyser-endpoint"
|
||||
export GEYSER_API_TOKEN="your-api-token"
|
||||
```
|
||||
|
||||
## Common Usage Patterns
|
||||
|
||||
### Quick Performance Check
|
||||
```bash
|
||||
# 30-second comparison of all listeners
|
||||
uv run tests/compare_listeners.py 30
|
||||
```
|
||||
|
||||
### Extended Performance Analysis
|
||||
```bash
|
||||
# 10-minute deep analysis
|
||||
uv run tests/compare_listeners.py 600
|
||||
```
|
||||
|
||||
### Individual Listener Validation
|
||||
```bash
|
||||
# Test specific listener implementation
|
||||
uv run tests/test_geyser_listener.py
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
1. **Performance Optimization**: Determine fastest listener for production
|
||||
2. **Reliability Testing**: Verify consistent token detection
|
||||
3. **Configuration Tuning**: Optimize listener parameters
|
||||
4. **Debugging**: Isolate listener-specific issues
|
||||
|
||||
## Related Files
|
||||
|
||||
- @tests/test_geyser_listener.py: Geyser performance testing
|
||||
- @tests/test_logs_listener.py: Logs listener validation
|
||||
- @tests/test_block_listener.py: Block listener analysis
|
||||
- @tests/compare_listeners.py: Multi-listener performance comparison
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
description: Core trading functionality including buy/sell operations, position management, and execution strategies. Apply when working with trading logic or transaction execution.
|
||||
globs: src/trading/*.py
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Trading System Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The trading module forms the core of the pump-bot's execution capabilities, handling token purchases, sales, position management, and trading strategy implementation. This system translates token detection events into actual on-chain transactions.
|
||||
|
||||
## Core Components
|
||||
|
||||
### Trading Coordinator
|
||||
|
||||
@src/trading/trader.py implements the `PumpTrader` class which:
|
||||
- Orchestrates the entire trading lifecycle
|
||||
- Manages token detection to execution flow
|
||||
- Implements risk management controls
|
||||
- Coordinates buy and sell operations
|
||||
- Handles position tracking and reporting
|
||||
|
||||
```python
|
||||
# Example usage
|
||||
trader = PumpTrader(config, client, wallet)
|
||||
await trader.process_token(token_info)
|
||||
```
|
||||
|
||||
### Buy Operations
|
||||
|
||||
@src/trading/buyer.py provides the `TokenBuyer` class:
|
||||
- Implements token purchase logic
|
||||
- Handles slippage calculation and management
|
||||
- Creates and submits buy transactions
|
||||
- Validates transaction success
|
||||
|
||||
### Sell Operations
|
||||
|
||||
@src/trading/seller.py implements the `TokenSeller` class:
|
||||
- Manages token selling operations
|
||||
- Implements various exit strategies
|
||||
- Handles profit calculation and optimization
|
||||
- Ensures proper transaction construction
|
||||
|
||||
### Position Management
|
||||
|
||||
@src/trading/position.py offers position tracking:
|
||||
- Records entry and exit prices
|
||||
- Calculates profit/loss metrics
|
||||
- Manages position state throughout lifecycle
|
||||
- Implements risk management boundaries
|
||||
|
||||
### Base Abstractions
|
||||
|
||||
@src/trading/base.py defines core abstractions:
|
||||
- Common interfaces for trading components
|
||||
- Shared data structures
|
||||
- Type definitions and constants
|
||||
- Interface contracts for strategy implementations
|
||||
|
||||
## Trading Strategies
|
||||
|
||||
The system supports multiple exit strategies:
|
||||
|
||||
1. **Time-Based**: Automatically sells after a configurable holding period
|
||||
2. **TP/SL**: Uses Take Profit / Stop Loss targets to manage exits
|
||||
3. **Manual**: Requires explicit sell commands
|
||||
|
||||
```yaml
|
||||
# Configuration example
|
||||
trade:
|
||||
exit_strategy: "tp_sl"
|
||||
take_profit_percentage: 0.2
|
||||
stop_loss_percentage: 0.2
|
||||
```
|
||||
|
||||
## Common Trading Flows
|
||||
|
||||
| Operation | Flow |
|
||||
|-----------|------|
|
||||
| Token Purchase | Detection → Validation → Buy Transaction → Position Creation |
|
||||
| Token Sale | Strategy Trigger → Position Update → Sell Transaction → Cleanup |
|
||||
| Error Handling | Error Detection → Transaction Retry → Position Closure → Cleanup |
|
||||
|
||||
## Related Files
|
||||
|
||||
- @src/trading/trader.py: Main trading coordination
|
||||
- @src/trading/buyer.py: Buy transaction implementation
|
||||
- @src/trading/seller.py: Sell transaction implementation
|
||||
- @src/trading/position.py: Position tracking and management
|
||||
- @src/trading/base.py: Core abstractions and interfaces
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
description: Shared utilities and helper functions for common operations. Apply when working with project-wide utilities.
|
||||
globs: src/utils/*.py
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Utility Functions Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The utils module provides shared functionality and helper methods used throughout the pump-bot system. These utilities handle common concerns like logging.
|
||||
|
||||
## Core Utilities
|
||||
|
||||
### Logging
|
||||
|
||||
@src/utils/logger.py implements a centralized logging system:
|
||||
- Consistent log formatting across the application
|
||||
- Log level management
|
||||
- File and console output handling
|
||||
- Context-aware logging with component identification
|
||||
|
||||
```python
|
||||
# Example usage
|
||||
logger = get_logger(__name__)
|
||||
logger.info("Processing token %s", token_mint)
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
| Operation | Utility |
|
||||
|-----------|---------|
|
||||
| Logging | `get_logger(__name__)` |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Reuse existing utilities** rather than implementing similar functionality
|
||||
2. **Keep utilities focused** on a single responsibility
|
||||
3. **Document usage examples** for each utility
|
||||
4. **Maintain backward compatibility** when enhancing utilities
|
||||
|
||||
## Related Files
|
||||
|
||||
- @src/utils/logger.py: Centralized logging system
|
||||
Reference in New Issue
Block a user