mirror of
https://github.com/chainstacklabs/pumpfun-bonkfun-bot.git
synced 2026-08-17 09:18:05 +00:00
wip(cursor): craft cursor rules
This commit is contained in:
smypmsa
@@ -1,9 +1,68 @@
|
|||||||
# Cleanup Logic Guide
|
|
||||||
|
|
||||||
- [manager.py](mdc:src/cleanup/manager.py) manages cleanup operations and resource management.
|
|
||||||
- [modes.py](mdc:src/cleanup/modes.py) defines cleanup modes and strategies.
|
|
||||||
- This directory is responsible for resource cleanup and related logic.
|
|
||||||
description:
|
|
||||||
globs:
|
|
||||||
alwaysApply: false
|
|
||||||
---
|
---
|
||||||
|
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
|
||||||
|
|||||||
+75
-10
@@ -1,11 +1,76 @@
|
|||||||
# Core Logic Guide
|
|
||||||
|
|
||||||
- [client.py](mdc:src/core/client.py) handles blockchain client interactions.
|
|
||||||
- [wallet.py](mdc:src/core/wallet.py) manages wallet logic.
|
|
||||||
- [pubkeys.py](mdc:src/core/pubkeys.py) stores and manages public keys.
|
|
||||||
- [curve.py](mdc:src/core/curve.py) provides curve math and related utilities.
|
|
||||||
- This directory contains core abstractions and logic for blockchain and protocol interactions.
|
|
||||||
description:
|
|
||||||
globs:
|
|
||||||
alwaysApply: false
|
|
||||||
---
|
---
|
||||||
|
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
|
||||||
|
|||||||
+87
-6
@@ -1,8 +1,89 @@
|
|||||||
|
---
|
||||||
|
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
|
# Interface Definition Guide
|
||||||
|
|
||||||
- JSON files in this directory define program interfaces (IDLs) for interacting with on-chain programs.
|
## Overview
|
||||||
- These files are used for serialization, deserialization, and program interaction logic.
|
|
||||||
description:
|
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.
|
||||||
globs:
|
|
||||||
alwaysApply: false
|
## 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,9 +1,96 @@
|
|||||||
# Monitoring Logic Guide
|
|
||||||
|
|
||||||
- Listener files (e.g., [pumpportal_listener.py](mdc:src/monitoring/pumpportal_listener.py), [logs_listener.py](mdc:src/monitoring/logs_listener.py), [geyser_listener.py](mdc:src/monitoring/geyser_listener.py), [block_listener.py](mdc:src/monitoring/block_listener.py)) are responsible for subscribing to and receiving events from various sources.
|
|
||||||
- Event processor files (e.g., [pumpportal_event_processor.py](mdc:src/monitoring/pumpportal_event_processor.py), [logs_event_processor.py](mdc:src/monitoring/logs_event_processor.py), [geyser_event_processor.py](mdc:src/monitoring/geyser_event_processor.py), [block_event_processor.py](mdc:src/monitoring/block_event_processor.py)) handle the logic for processing and reacting to those events.
|
|
||||||
- [base_listener.py](mdc:src/monitoring/base_listener.py) provides shared abstractions for listeners.
|
|
||||||
description:
|
|
||||||
globs:
|
|
||||||
alwaysApply: false
|
|
||||||
---
|
---
|
||||||
|
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,17 +1,109 @@
|
|||||||
|
---
|
||||||
|
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
|
# Project Structure Guide
|
||||||
|
|
||||||
- The main source code is in the [src/](mdc:src/) directory.
|
## Overview
|
||||||
- Trading logic is in [src/trading/](mdc:src/trading/), including [trader.py](mdc:src/trading/trader.py), [buyer.py](mdc:src/trading/buyer.py), and [seller.py](mdc:src/trading/seller.py).
|
|
||||||
- Monitoring logic is in [src/monitoring/](mdc:src/monitoring/), with various listeners and event processors.
|
The pump-bot system is organized into modular components with clear separation of concerns. This architecture facilitates maintainability, testing, and extension of functionality.
|
||||||
- Utility functions are in [src/utils/](mdc:src/utils/).
|
|
||||||
- Core abstractions and blockchain logic are in [src/core/](mdc:src/core/).
|
## Directory Structure
|
||||||
- Cleanup logic is in [src/cleanup/](mdc:src/cleanup/).
|
|
||||||
- Geyser-related code is in [src/geyser/](mdc:src/geyser/).
|
### Source Code
|
||||||
- Bot configuration files are in [bots/](mdc:bots/).
|
|
||||||
- Trade logs are in [trades/](mdc:trades/).
|
The main codebase is organized as follows:
|
||||||
- Interface definitions are in [idl/](mdc:idl/).
|
|
||||||
- Tests are in [tests/](mdc:tests/).
|
- @src/: Root source directory
|
||||||
description:
|
- @src/bot_runner.py: Entry point for bot execution
|
||||||
globs:
|
- @src/config_loader.py: Configuration loading and validation
|
||||||
alwaysApply: false
|
|
||||||
---
|
#### 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 @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: Integration with Claude AI for strategy development
|
||||||
|
|||||||
+85
-7
@@ -1,9 +1,87 @@
|
|||||||
|
---
|
||||||
|
description: Testing framework and test cases for system validation. Apply when writing tests or performing system validation.
|
||||||
|
globs: tests/*.py
|
||||||
|
alwaysApply: true
|
||||||
|
---
|
||||||
|
|
||||||
# Testing Guide
|
# Testing Guide
|
||||||
|
|
||||||
- Python files in this directory contain tests for listeners and other core components.
|
## Overview
|
||||||
- Tests are organized by component type (e.g., geyser, logs, block listeners).
|
|
||||||
- [compare_listeners.py](mdc:tests/compare_listeners.py) is used for comparing listener outputs.
|
The testing framework provides validation for key components of the pump-bot system, focusing on listener accuracy, trading execution, and system integration. Tests ensure reliability and proper functioning of critical bot operations.
|
||||||
description:
|
|
||||||
globs:
|
## Test Organization
|
||||||
alwaysApply: false
|
|
||||||
---
|
### Listener Tests
|
||||||
|
|
||||||
|
Multiple implementations are tested for correctness and performance:
|
||||||
|
|
||||||
|
- @tests/test_geyser_listener.py: Tests the Geyser-based implementation
|
||||||
|
- @tests/test_logs_listener.py: Validates log-based token detection
|
||||||
|
- @tests/test_block_listener.py: Verifies block scanning functionality
|
||||||
|
|
||||||
|
### Comparison Testing
|
||||||
|
|
||||||
|
@tests/compare_listeners.py provides comparative analysis:
|
||||||
|
- Side-by-side execution of different listener implementations
|
||||||
|
- Latency measurement and comparison
|
||||||
|
- Detection reliability metrics
|
||||||
|
- False positive/negative analysis
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Example comparison usage
|
||||||
|
python -m tests.compare_listeners --duration 600 --output-file results.json
|
||||||
|
```
|
||||||
|
|
||||||
|
## Test Configuration
|
||||||
|
|
||||||
|
Tests use environment variables for configuration:
|
||||||
|
- Connection endpoints
|
||||||
|
- API keys
|
||||||
|
- Test durations
|
||||||
|
- Output verbosity
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Example test execution
|
||||||
|
SOLANA_NODE_RPC_ENDPOINT=https://api.mainnet-beta.solana.com \
|
||||||
|
GEYSER_ENDPOINT=wss://geyser.example.com/subscribe \
|
||||||
|
python -m tests.test_geyser_listener
|
||||||
|
```
|
||||||
|
|
||||||
|
## Test Data
|
||||||
|
|
||||||
|
The test suite includes:
|
||||||
|
- Mock token creation events
|
||||||
|
- Historical transaction data
|
||||||
|
- Performance benchmarks
|
||||||
|
- Edge case scenarios
|
||||||
|
|
||||||
|
## Running Tests
|
||||||
|
|
||||||
|
### Individual Component Tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run a specific listener test
|
||||||
|
python -m tests.test_logs_listener
|
||||||
|
|
||||||
|
# Run with custom parameters
|
||||||
|
python -m tests.test_block_listener --duration 60
|
||||||
|
```
|
||||||
|
|
||||||
|
### Full Test Suite
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run all tests
|
||||||
|
python -m pytest tests/
|
||||||
|
|
||||||
|
# Run with coverage report
|
||||||
|
python -m pytest --cov=src tests/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Related Files
|
||||||
|
|
||||||
|
- @tests/test_geyser_listener.py: Geyser listener validation
|
||||||
|
- @tests/test_logs_listener.py: Logs listener validation
|
||||||
|
- @tests/test_block_listener.py: Block listener validation
|
||||||
|
- @tests/compare_listeners.py: Comparative listener analysis
|
||||||
|
- @tests/test_trading.py: Trading execution validation
|
||||||
|
|||||||
+91
-10
@@ -1,11 +1,92 @@
|
|||||||
# Trading Logic Guide
|
|
||||||
|
|
||||||
- [trader.py](mdc:src/trading/trader.py) is the main entry point for trading operations, orchestrating buy and sell actions.
|
|
||||||
- [buyer.py](mdc:src/trading/buyer.py) implements logic for buying assets.
|
|
||||||
- [seller.py](mdc:src/trading/seller.py) implements logic for selling assets.
|
|
||||||
- [position.py](mdc:src/trading/position.py) manages trading positions.
|
|
||||||
- [base.py](mdc:src/trading/base.py) provides base classes and shared abstractions for trading components.
|
|
||||||
description:
|
|
||||||
globs:
|
|
||||||
alwaysApply: false
|
|
||||||
---
|
---
|
||||||
|
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
|
||||||
|
|||||||
+42
-6
@@ -1,8 +1,44 @@
|
|||||||
|
---
|
||||||
|
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
|
# Utility Functions Guide
|
||||||
|
|
||||||
- [logger.py](mdc:src/utils/logger.py) provides logging utilities for the project.
|
## Overview
|
||||||
- Utility modules in this directory are intended for shared, reusable helper functions and classes.
|
|
||||||
description:
|
The utils module provides shared functionality and helper methods used throughout the pump-bot system. These utilities handle common concerns like logging.
|
||||||
globs:
|
|
||||||
alwaysApply: false
|
## 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