gavindiaz/sol-trade-sdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: Refactor SDK core architecture and trading parameter system

Browse Source 
- Refactor SolanaTrade main class structure with improved modular design
- Refactor trading parameter system: BuyParams/SellParams -> InternalBuyParams/InternalSellParams
- Remove deprecated PriorityFee and related utility functions
- Add SwqosSettings to replace legacy SwqosConfig
- Add comprehensive technical documentation:
  • Address Lookup Table usage guide (EN/CN)
  • Nonce Cache mechanism documentation (EN/CN)
  • Trading Parameters documentation (EN/CN)
- Refactor all example code to adapt to new API interfaces
- Optimize public API design and code comments
- Clean up redundant utility functions and type definitions

Impact: 43 files changed, 2013 insertions(+), 1735 deletions(-)
This commit is contained in:
ysq
2025-09-17 00:10:33 +08:00
parent 943c2627f3
commit c5ff7c1cbb
43 changed files with 2010 additions and 1732 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+88 -152
View File
@@ -44,15 +44,14 @@
- [✨ Features](#-features)
- [📦 Installation](#-installation)
- [🛠️ Usage Examples](#️-usage-examples)
- [📋 Important Parameter Description](#-important-parameter-description)
- [📋 Example Usage](#-example-usage)
- [⚡ Trading Parameters](#-trading-parameters)
- [📊 Usage Examples Summary Table](#-usage-examples-summary-table)
- [⚙️ SWQOS Service Configuration](#️-swqos-service-configuration)
- [🔧 Middleware System](#-middleware-system)
- [⚡ Custom Priority Fee Configuration](#-custom-priority-fee-configuration)
- [🏪 Supported Trading Platforms](#-supported-trading-platforms)
- [🔍 Address Lookup Tables](#-address-lookup-tables)
- [🔍 Nonce Cache](#-nonce-cache)
- [🛡️ MEV Protection Services](#️-mev-protection-services)
- [💰 Price Calculation Utilities](#-price-calculation-utilities)
- [🧮 Amount Calculation Utilities](#-amount-calculation-utilities)
- [📁 Project Structure](#-project-structure)
- [📄 License](#-license)
- [💬 Contact](#-contact)
@@ -67,13 +66,11 @@
3. **Bonk Trading**: Support for Bonk trading operations
4. **Raydium CPMM Trading**: Support for Raydium CPMM (Concentrated Pool Market Maker) trading operations
5. **Raydium AMM V4 Trading**: Support for Raydium AMM V4 (Automated Market Maker) trading operations
6. **Event Subscription**: Subscribe to PumpFun, PumpSwap, Bonk, Raydium CPMM, and Raydium AMM V4 program trading events
7. **Yellowstone gRPC**: Subscribe to program events using Yellowstone gRPC
8. **ShredStream Support**: Subscribe to program events using ShredStream
9. **Multiple MEV Protection**: Support for Jito, Nextblock, ZeroSlot, Temporal, Bloxroute, FlashBlock, BlockRazor, Node1, Astralane and other services
10. **Concurrent Trading**: Send transactions using multiple MEV services simultaneously; the fastest succeeds while others fail
11. **Unified Trading Interface**: Use unified trading protocol enums for trading operations
12. **Middleware System**: Support for custom instruction middleware to modify, add, or remove instructions before transaction execution
6. **Event Subscription**: SDK integrates solana-streamer SDK, supports subscribing to PumpFun, PumpSwap, Bonk, Raydium CPMM, and Raydium AMM V4 program trading events, the description of this SDK can be found in [solana-streamer SDK](https://github.com/0xfnzero/solana-streamer).
7. **Multiple MEV Protection**: Support for Jito, Nextblock, ZeroSlot, Temporal, Bloxroute, FlashBlock, BlockRazor, Node1, Astralane and other services
8. **Concurrent Trading**: Send transactions using multiple MEV services simultaneously; the fastest succeeds while others fail
9. **Unified Trading Interface**: Use unified trading protocol enums for trading operations
10. **Middleware System**: Support for custom instruction middleware to modify, add, or remove instructions before transaction execution
## 📦 Installation
@@ -90,74 +87,78 @@ Add the dependency to your `Cargo.toml`:
```toml
# Add to your Cargo.toml
sol-trade-sdk = { path = "./sol-trade-sdk", version = "0.6.15" }
sol-trade-sdk = { path = "./sol-trade-sdk", version = "1.0.0" }
```
### Use crates.io
```toml
# Add to your Cargo.toml
sol-trade-sdk = "0.6.15"
sol-trade-sdk = "1.0.0"
```
## 🛠️ Usage Examples
### 📋 Important Parameter Description
### 📋 Example Usage
#### 🌱 open_seed_optimize Parameter
#### 1. Create SolanaTrade Instance
`open_seed_optimize` is used to specify whether to use seed optimization to reduce transaction CU consumption.
You can refer to [Example: Create SolanaTrade Instance](examples/trading_client/src/main.rs).
- **Purpose**: When `open_seed_optimize: true`, the SDK uses createAccountWithSeed optimization to create token ata accounts during transactions.
- **Note**: Transactions created with `open_seed_optimize` enabled must be sold through this SDK. Using official methods to sell may fail.
- **Note**: After enabling `open_seed_optimize`, you need to use the `get_associated_token_address_with_program_id_fast_use_seed` method to get the token ata address.
```rust
// Wallet
let payer = Keypair::from_base58_string("use_your_payer_keypair_here");
// RPC URL
let rpc_url = "https://mainnet.helius-rpc.com/?api-key=xxxxxx".to_string();
let commitment = CommitmentConfig::processed();
// Transaction CU and fee settings
let cu_limit = DEFAULT_CU_LIMIT;
let cu_price = DEFAULT_CU_PRICE;
let buy_tip_fee = DEFAULT_BUY_TIP_FEE;
let sell_tip_fee = DEFAULT_SELL_TIP_FEE;
// SWQOS service configuration
let swqos_settings: Vec<SwqosSettings> = vec![
SwqosSettings::new(SwqosConfig::Default(rpc_url.clone()), cu_limit, cu_price, 0.0, 0.0),
// First parameter is UUID, pass empty string if no UUID
SwqosSettings::new(SwqosConfig::Jito("your uuid".to_string(), SwqosRegion::Frankfurt, None), cu_limit, cu_price, buy_tip_fee, sell_tip_fee),
// ....other service configurations...
];
// Create SolanaTrade instance
let client =
SolanaTrade::new(Arc::new(payer), rpc_url, commitment, swqos_settings).await;
```
#### 💰 create_wsol_ata and close_wsol_ata、 create_mint_ata Parameters
#### 2. Build Trading Parameters
In PumpSwap, Bonk, and Raydium trading, the `create_wsol_ata` and `close_wsol_ata`、 `create_mint_ata` parameters provide fine-grained control over wSOL (Wrapped SOL) account management:
For detailed information about all trading parameters, see the [Trading Parameters Reference](docs/TRADING_PARAMETERS.md).
- **create_wsol_ata**:
- When `create_wsol_ata: true`, the SDK automatically creates and wraps SOL to wSOL before trading
- When buying: automatically wraps SOL to wSOL for trading
```rust
let buy_params = sol_trade_sdk::TradeBuyParams {
dex_type: DexType::PumpSwap,
mint: mint_pubkey,
sol_amount: buy_sol_amount,
slippage_basis_points: slippage_basis_points,
recent_blockhash: recent_blockhash,
extension_params: Box::new(params.clone()),
custom_cu_limit: None,
lookup_table_key: None,
wait_transaction_confirmed: true,
create_wsol_ata: true,
close_wsol_ata: true,
create_mint_ata: true,
open_seed_optimize: false,
};
```
- **close_wsol_ata**:
- When `close_wsol_ata: true`, the SDK automatically closes the wSOL account and unwraps to SOL after trading
- When selling: automatically unwraps the received wSOL to SOL and reclaims rent
#### 3. Execute Trading
- **create_mint_ata**:
- When `create_mint_ata: true`, the SDK automatically creates the token ata account before trading
```rust
client.buy(buy_params).await?;
```
- **Benefits of Separate Parameters**:
- Allows independent control of wSOL account creation and closure
- Useful for batch operations where you want to create once and close after multiple transactions
- Provides flexibility for advanced trading strategies
### ⚡ Trading Parameters
#### 🔍 lookup_table_key Parameter
The `lookup_table_key` parameter is an optional `Pubkey` that specifies an address lookup table for transaction optimization. You need to use `AddressLookupTableCache` to manage the cached address lookup table before using it.
- **Purpose**: Address lookup tables can reduce transaction size and improve execution speed by storing frequently used addresses
- **Usage**:
- Can be overridden per transaction in `buy()` and `sell()` methods
- If not provided, defaults to `None`
- **Benefits**:
- Reduces transaction size by referencing addresses from lookup tables
- Improves transaction success rate and speed
- Particularly useful for complex transactions with many account references
#### ⚡ priority_fee Parameter
The `priority_fee` parameter is an optional `PriorityFee` that allows you to override the default priority fee settings for individual transactions:
- **Purpose**: Provides fine-grained control over transaction priority fees on a per-transaction basis
- **Usage**:
- Can be passed to `buy()` and `sell()` methods to override the global priority fee settings
- If not provided, defaults to `None` and uses the priority fee settings from `TradeConfig`
- When provided, the `buy_tip_fees` array will be automatically padded to match the number of SWQOS clients
- **Benefits**:
- Allows dynamic adjustment of priority fees based on market conditions
- Enables different fee strategies for different types of transactions
- Provides flexibility for high-frequency trading scenarios
For comprehensive information about all trading parameters including `TradeBuyParams` and `TradeSellParams`, see the dedicated [Trading Parameters Reference](docs/TRADING_PARAMETERS.md).
#### About ShredStream
@@ -166,22 +167,22 @@ Please ensure that the parameters your trading logic depends on are available in
### 📊 Usage Examples Summary Table
| Feature Type | Package Name | Description | Run Command | Source Code |
|-------------|--------------|-------------|-------------|-------------|
| Event Subscription | `event_subscription` | Monitor token trading events | `cargo run --package event_subscription` | [examples/event_subscription](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/event_subscription/src/main.rs) |
| Trading Client | `trading_client` | Create and configure SolanaTrade instance | `cargo run --package trading_client` | [examples/trading_client](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/trading_client/src/main.rs) |
| PumpFun Sniping | `pumpfun_sniper_trading` | PumpFun token sniping trading | `cargo run --package pumpfun_sniper_trading` | [examples/pumpfun_sniper_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/pumpfun_sniper_trading/src/main.rs) |
| PumpFun Copy Trading | `pumpfun_copy_trading` | PumpFun token copy trading | `cargo run --package pumpfun_copy_trading` | [examples/pumpfun_copy_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/pumpfun_copy_trading/src/main.rs) |
| PumpSwap | `pumpswap_trading` | PumpSwap trading operations | `cargo run --package pumpswap_trading` | [examples/pumpswap_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/pumpswap_trading/src/main.rs) |
| Raydium CPMM | `raydium_cpmm_trading` | Raydium CPMM trading operations | `cargo run --package raydium_cpmm_trading` | [examples/raydium_cpmm_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/raydium_cpmm_trading/src/main.rs) |
| Raydium AMM V4 | `raydium_amm_v4_trading` | Raydium AMM V4 trading operations | `cargo run --package raydium_amm_v4_trading` | [examples/raydium_amm_v4_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/raydium_amm_v4_trading/src/main.rs) |
| Bonk Sniping | `bonk_sniper_trading` | Bonk token sniping trading | `cargo run --package bonk_sniper_trading` | [examples/bonk_sniper_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/bonk_sniper_trading/src/main.rs) |
| Bonk Copy Trading | `bonk_copy_trading` | Bonk token copy trading | `cargo run --package bonk_copy_trading` | [examples/bonk_copy_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/bonk_copy_trading/src/main.rs) |
| Middleware System | `middleware_system` | Custom instruction middleware example | `cargo run --package middleware_system` | [examples/middleware_system](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/middleware_system/src/main.rs) |
| Address Lookup | `address_lookup` | Address lookup table example | `cargo run --package address_lookup` | [examples/address_lookup](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/address_lookup/src/main.rs) |
| Nonce | `nonce_cache` | Nonce example | `cargo run --package nonce_cache` | [examples/nonce_cache](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/nonce_cache/src/main.rs) |
| WSOL Wrapper | `wsol_wrapper` | Wrap/unwrap SOL to/from WSOL example | `cargo run --package wsol_wrapper` | [examples/wsol_wrapper](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/wsol_wrapper/src/main.rs) |
| Seed Trading | `seed_trading` | Seed trading example | `cargo run --package seed_trading` | [examples/seed_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/seed_trading/src/main.rs) |
| Description | Run Command | Source Code |
|-------------|-------------|-------------|
| Monitor token trading events | `cargo run --package event_subscription` | [examples/event_subscription](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/event_subscription/src/main.rs) |
| Create and configure SolanaTrade instance | `cargo run --package trading_client` | [examples/trading_client](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/trading_client/src/main.rs) |
| PumpFun token sniping trading | `cargo run --package pumpfun_sniper_trading` | [examples/pumpfun_sniper_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/pumpfun_sniper_trading/src/main.rs) |
| PumpFun token copy trading | `cargo run --package pumpfun_copy_trading` | [examples/pumpfun_copy_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/pumpfun_copy_trading/src/main.rs) |
| PumpSwap trading operations | `cargo run --package pumpswap_trading` | [examples/pumpswap_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/pumpswap_trading/src/main.rs) |
| Raydium CPMM trading operations | `cargo run --package raydium_cpmm_trading` | [examples/raydium_cpmm_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/raydium_cpmm_trading/src/main.rs) |
| Raydium AMM V4 trading operations | `cargo run --package raydium_amm_v4_trading` | [examples/raydium_amm_v4_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/raydium_amm_v4_trading/src/main.rs) |
| Bonk token sniping trading | `cargo run --package bonk_sniper_trading` | [examples/bonk_sniper_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/bonk_sniper_trading/src/main.rs) |
| Bonk token copy trading | `cargo run --package bonk_copy_trading` | [examples/bonk_copy_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/bonk_copy_trading/src/main.rs) |
| Custom instruction middleware example | `cargo run --package middleware_system` | [examples/middleware_system](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/middleware_system/src/main.rs) |
| Address lookup table example | `cargo run --package address_lookup` | [examples/address_lookup](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/address_lookup/src/main.rs) |
| Nonce example | `cargo run --package nonce_cache` | [examples/nonce_cache](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/nonce_cache/src/main.rs) |
| Wrap/unwrap SOL to/from WSOL example | `cargo run --package wsol_wrapper` | [examples/wsol_wrapper](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/wsol_wrapper/src/main.rs) |
| Seed trading example | `cargo run --package seed_trading` | [examples/seed_trading](https://github.com/0xfnzero/sol-trade-sdk/tree/main/examples/seed_trading/src/main.rs) |
### ⚙️ SWQOS Service Configuration
@@ -230,41 +231,18 @@ let middleware_manager = MiddlewareManager::new()
.add_middleware(Box::new(ThirdMiddleware)); // Executes last
```
### ⚡ Custom Priority Fee Configuration
### 🔍 Address Lookup Tables
```rust
use sol_trade_sdk::common::PriorityFee;
Address Lookup Tables (ALT) allow you to optimize transaction size and reduce fees by storing frequently used addresses in a compact table format. For detailed information, see the [Address Lookup Tables Guide](docs/ADDRESS_LOOKUP_TABLE.md).
// Custom priority fee configuration
let priority_fee = PriorityFee {
tip_unit_limit: 190000,
tip_unit_price: 1000000,
rpc_unit_limit: 500000,
rpc_unit_price: 500000,
buy_tip_fee: 0.001,
buy_tip_fees: vec![0.001, 0.002],
sell_tip_fee: 0.0001,
};
### 🔍 Nonce Cache
// Use custom priority fee in TradeConfig
let trade_config = TradeConfig {
rpc_url: rpc_url.clone(),
commitment: CommitmentConfig::confirmed(),
priority_fee, // Use custom priority fee
swqos_configs,
};
```
## 🏪 Supported Trading Platforms
- **PumpFun**: Primary meme coin trading platform
- **PumpSwap**: PumpFun's swap protocol
- **Bonk**: Token launch platform (letsbonk.fun)
- **Raydium CPMM**: Raydium's Concentrated Pool Market Maker protocol
- **Raydium AMM V4**: Raydium's Automated Market Maker V4 protocol
Use Nonce Cache to implement transaction replay protection and optimize transaction processing. For detailed information, see the [Nonce Cache Guide](docs/NONCE_CACHE.md).
## 🛡️ MEV Protection Services
You can apply for a key through the official website: [Community Website](https://fnzero.dev/swqos)
- **Jito**: High-performance block space
- **NextBlock**: Fast transaction execution
- **ZeroSlot**: Zero-latency transactions
@@ -275,28 +253,6 @@ let trade_config = TradeConfig {
- **Node1**: High-speed transaction execution with API key authentication - [Official Documentation](https://node1.me/docs.html)
- **Astralane**: Blockchain network acceleration
## 💰 Price Calculation Utilities
The SDK includes price calculation utilities for all supported protocols in `src/utils/price/`.
## 🧮 Amount Calculation Utilities
The SDK provides trading amount calculation functionality for various protocols, located in `src/utils/calc/`:
- **Common Calculation Functions**: Provides general fee calculation and division utilities
- **Protocol-Specific Calculations**: Specialized calculation logic for each protocol
- **PumpFun**: Token buy/sell amount calculations based on bonding curves
- **PumpSwap**: Amount calculations for multiple trading pairs
- **Raydium AMM V4**: Amount and fee calculations for automated market maker pools
- **Raydium CPMM**: Amount calculations for constant product market makers
- **Bonk**: Specialized calculation logic for Bonk tokens
Key features include:
- Calculate output amounts based on input amounts
- Fee calculation and distribution
- Slippage protection calculations
- Liquidity pool state calculations
## 📁 Project Structure
```
@@ -304,38 +260,18 @@ src/
├── common/ # Common functionality and tools
├── constants/ # Constant definitions
├── instruction/ # Instruction building
│ └── utils/ # Instruction utilities
├── protos/ # gRPC protocol definitions
├── swqos/ # MEV service clients
├── trading/ # Unified trading engine
│ ├── common/ # Common trading tools
│ ├── core/ # Core trading engine
│ ├── middleware/ # Middleware system
│ │ ├── builtin.rs # Built-in middleware implementations
│ │ ├── traits.rs # Middleware trait definitions
│ │ └── mod.rs # Middleware module
│ ├── bonk/ # Bonk trading implementation
│ ├── pumpfun/ # PumpFun trading implementation
│ ├── pumpswap/ # PumpSwap trading implementation
│ ├── raydium_cpmm/ # Raydium CPMM trading implementation
│ ├── raydium_amm_v4/ # Raydium AMM V4 trading implementation
│ └── factory.rs # Trading factory
├── utils/ # Utility functions
│ ├── price/ # Price calculation utilities
│ │ ├── common.rs # Common price functions
│ │ ├── bonk.rs # Bonk price calculations
│ │ ├── pumpfun.rs # PumpFun price calculations
│ │ ├── pumpswap.rs # PumpSwap price calculations
│ │ ├── raydium_cpmm.rs # Raydium CPMM price calculations
│ │ ├── raydium_clmm.rs # Raydium CLMM price calculations
│ │ └── raydium_amm_v4.rs # Raydium AMM V4 price calculations
│ └── calc/ # Amount calculation utilities
│ ├── common.rs # Common calculation functions
│ ├── bonk.rs # Bonk amount calculations
│ ├── pumpfun.rs # PumpFun amount calculations
│ ├── pumpswap.rs # PumpSwap amount calculations
│ ├── raydium_cpmm.rs # Raydium CPMM amount calculations
│ └── raydium_amm_v4.rs # Raydium AMM V4 amount calculations
├── lib.rs # Main library file
└── main.rs # Example program
│ ├── calc/ # Amount calculation utilities
│ └── price/ # Price calculation utilities
└── lib.rs # Main library file
```
## 📄 License