refactor: optimize instruction builders structure and improve code documentation

- Add structured comment sections with clear code organization - Improve variable naming and account address calculation logic - Update comments for better readability across all trading protocols - Enhance code structure for PumpFun, PumpSwap, and Raydium protocols
2025-09-09 00:50:24 +08:00
parent ccf6330260
commit b9fa2f2f0f
16 changed files with 333 additions and 307 deletions
@@ -16,10 +16,10 @@ const MAX_INSTRUCTION_CACHE_SIZE: usize = 10000;

 // --------------------- Instruction Cache ---------------------

-/// 指令缓存键，用于唯一标识指令类型和参数
+/// Instruction cache key for uniquely identifying instruction types and parameters
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum InstructionCacheKey {
-    /// Associated Token Account 创建指令
+    /// Associated Token Account creation instruction
    CreateAssociatedTokenAccount {
        payer: Pubkey,
        owner: Pubkey,
@@ -30,18 +30,18 @@ pub enum InstructionCacheKey {
    CloseWsolAccount { payer: Pubkey, wsol_token_account: Pubkey },
 }

-/// 全局指令缓存，用于存储常用指令
+/// Global instruction cache for storing common instructions
 static INSTRUCTION_CACHE: Lazy<RwLock<CLruCache<InstructionCacheKey, Instruction>>> =
    Lazy::new(|| {
        RwLock::new(CLruCache::new(NonZeroUsize::new(MAX_INSTRUCTION_CACHE_SIZE).unwrap()))
    });

-/// 获取缓存的指令，如果不存在则计算并缓存
+/// Get cached instruction, compute and cache if not exists
 pub fn get_cached_instruction<F>(cache_key: InstructionCacheKey, compute_fn: F) -> Instruction
 where
    F: FnOnce() -> Instruction,
 {
-    // 尝试从缓存中获取（使用读锁）
+    // Try to get from cache (using read lock)
    {
        let cache = INSTRUCTION_CACHE.read();
        if let Some(cached_instruction) = cache.peek(&cache_key) {
@@ -49,10 +49,10 @@ where
        }
    }

-    // 缓存未命中，计算新的指令
+    // Cache miss, compute new instruction
    let instruction = compute_fn();

-    // 将计算结果存入缓存（使用写锁）
+    // Store computation result in cache (using write lock)
    {
        let mut cache = INSTRUCTION_CACHE.write();
        cache.put(cache_key, instruction.clone());
@@ -69,7 +69,7 @@ pub fn create_associated_token_account_idempotent_fast(
    mint: &Pubkey,
    token_program: &Pubkey,
 ) -> Instruction {
-    // 创建缓存键
+    // Create cache key
    let cache_key = InstructionCacheKey::CreateAssociatedTokenAccount {
        payer: *payer,
        owner: *owner,
@@ -77,23 +77,23 @@ pub fn create_associated_token_account_idempotent_fast(
        token_program: *token_program,
    };

-    // 使用缓存获取指令
+    // Use cache to get instruction
    get_cached_instruction(cache_key, || {
-        // 使用缓存的方式获取 Associated Token Address
+        // Get Associated Token Address using cache
        let associated_token_address =
            get_associated_token_address_with_program_id_fast(owner, mint, token_program);

-        // 创建 Associated Token Account 指令
-        // 参考 spl_associated_token_account::instruction::create_associated_token_account 的实现
+        // Create Associated Token Account instruction
+        // Reference implementation of spl_associated_token_account::instruction::create_associated_token_account
        Instruction {
            program_id: ASSOCIATED_TOKEN_PROGRAM_ID,
            accounts: vec![
-                AccountMeta::new(*payer, true), // 支付者（签名者，可写）
-                AccountMeta::new(associated_token_address, false), // ATA地址（可写，非签名者）
-                AccountMeta::new_readonly(*owner, false), // Token账户拥有者（只读，非签名者）
-                AccountMeta::new_readonly(*mint, false), // Token mint地址（只读，非签名者）
+                AccountMeta::new(*payer, true), // Payer (signer, writable)
+                AccountMeta::new(associated_token_address, false), // ATA address (writable, non-signer)
+                AccountMeta::new_readonly(*owner, false), // Token account owner (readonly, non-signer)
+                AccountMeta::new_readonly(*mint, false), // Token mint address (readonly, non-signer)
                crate::constants::SYSTEM_PROGRAM_META,
-                AccountMeta::new_readonly(*token_program, false), // Token程序（只读，非签名者）
+                AccountMeta::new_readonly(*token_program, false), // Token program (readonly, non-signer)
            ],
            data: vec![1],
        }
@@ -102,7 +102,7 @@ pub fn create_associated_token_account_idempotent_fast(

 // --------------------- PDA ---------------------

-/// PDA 缓存键，用于唯一标识 PDA 计算的输入参数
+/// PDA cache key for uniquely identifying PDA computation input parameters
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum PdaCacheKey {
    PumpFunUserVolume(Pubkey),
@@ -113,16 +113,16 @@ pub enum PdaCacheKey {
    PumpSwapUserVolume(Pubkey),
 }

-/// 全局 PDA 缓存，用于存储计算结果
+/// Global PDA cache for storing computation results
 static PDA_CACHE: Lazy<RwLock<CLruCache<PdaCacheKey, Pubkey>>> =
    Lazy::new(|| RwLock::new(CLruCache::new(NonZeroUsize::new(MAX_PDA_CACHE_SIZE).unwrap())));

-/// 获取缓存的 PDA，如果不存在则计算并缓存
+/// Get cached PDA, compute and cache if not exists
 pub fn get_cached_pda<F>(cache_key: PdaCacheKey, compute_fn: F) -> Option<Pubkey>
 where
    F: FnOnce() -> Option<Pubkey>,
 {
-    // 尝试从缓存中获取（使用读锁）
+    // Try to get from cache (using read lock)
    {
        let cache = PDA_CACHE.read();
        if let Some(cached_pda) = cache.peek(&cache_key) {
@@ -130,10 +130,10 @@ where
        }
    }

-    // 缓存未命中，计算新的 PDA
+    // Cache miss, compute new PDA
    let pda_result = compute_fn();

-    // 如果计算成功，将结果存入缓存（使用写锁）
+    // If computation succeeds, store result in cache (using write lock)
    if let Some(pda) = pda_result {
        let mut cache = PDA_CACHE.write();
        cache.put(cache_key, pda);
@@ -144,7 +144,7 @@ where

 // --------------------- ATA ---------------------

-/// ATA 缓存键，用于 Associated Token Address 缓存
+/// ATA cache key for Associated Token Address caching
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 struct AtaCacheKey {
    wallet_address: Pubkey,
@@ -152,11 +152,11 @@ struct AtaCacheKey {
    token_program_id: Pubkey,
 }

-/// 全局 ATA 缓存，用于存储 Associated Token Address 计算结果
+/// Global ATA cache for storing Associated Token Address computation results
 static ATA_CACHE: Lazy<RwLock<CLruCache<AtaCacheKey, Pubkey>>> =
    Lazy::new(|| RwLock::new(CLruCache::new(NonZeroUsize::new(MAX_ATA_CACHE_SIZE).unwrap())));

-/// 获取缓存的 Associated Token Address，如果不存在则计算并缓存
+/// Get cached Associated Token Address, compute and cache if not exists
 pub fn get_associated_token_address_with_program_id_fast(
    wallet_address: &Pubkey,
    token_mint_address: &Pubkey,
@@ -168,7 +168,7 @@ pub fn get_associated_token_address_with_program_id_fast(
        token_program_id: *token_program_id,
    };

-    // 尝试从缓存中获取（使用读锁）
+    // Try to get from cache (using read lock)
    {
        let cache = ATA_CACHE.read();
        if let Some(cached_ata) = cache.peek(&cache_key) {
@@ -176,14 +176,14 @@ pub fn get_associated_token_address_with_program_id_fast(
        }
    }

-    // 缓存未命中，计算新的 ATA
+    // Cache miss, compute new ATA
    let ata = get_associated_token_address_with_program_id(
        wallet_address,
        token_mint_address,
        token_program_id,
    );

-    // 将计算结果存入缓存（使用写锁）
+    // Store computation result in cache (using write lock)
    {
        let mut cache = ATA_CACHE.write();
        cache.put(cache_key, ata);
@@ -192,20 +192,20 @@ pub fn get_associated_token_address_with_program_id_fast(
    ata
 }

-// --------------------- 初始化账号 ---------------------
+// --------------------- Initialize Accounts ---------------------

 pub fn fast_init(payer: &Pubkey) {
-    // 获取 PumpFun 用户量累加器 PDA
+    // Get PumpFun user volume accumulator PDA
    crate::instruction::utils::pumpfun::get_user_volume_accumulator_pda(payer);
-    // 获取 PumpSwap 用户量累加器 PDA
+    // Get PumpSwap user volume accumulator PDA
    crate::instruction::utils::pumpswap::get_user_volume_accumulator_pda(payer);
-    // 获取 wSOL ATA 地址
+    // Get wSOL ATA address
    let wsol_token_account = get_associated_token_address_with_program_id_fast(
        payer,
        &crate::constants::WSOL_TOKEN_ACCOUNT,
        &crate::constants::TOKEN_PROGRAM,
    );
-    // 获取 Close wSOL Account 指令
+    // Get Close wSOL Account instruction
    get_cached_instruction(
        crate::common::fast_fn::InstructionCacheKey::CloseWsolAccount {
            payer: *payer,
@@ -38,9 +38,9 @@ pub struct PriorityFee {
    pub tip_unit_price: u64,
    pub rpc_unit_limit: u32,
    pub rpc_unit_price: u64,
-    // 与 swqos 顺序一致 (Matches the order of swqos)
+    // Matches the order of swqos
    pub buy_tip_fees: Vec<f64>,
-    // 与 swqos 顺序一致 (Matches the order of swqos)
+    // Matches the order of swqos
    pub sell_tip_fees: Vec<f64>,
 }

@@ -51,9 +51,9 @@ impl Default for PriorityFee {
            tip_unit_price: DEFAULT_TIP_UNIT_PRICE,
            rpc_unit_limit: DEFAULT_RPC_UNIT_LIMIT,
            rpc_unit_price: DEFAULT_RPC_UNIT_PRICE,
-            // 与 swqos 顺序一致 (Matches the order of swqos)
+            // Matches the order of swqos
            buy_tip_fees: vec![DEFAULT_BUY_TIP_FEE],
-            // 与 swqos 顺序一致 (Matches the order of swqos)
+            // Matches the order of swqos
            sell_tip_fees: vec![DEFAULT_SELL_TIP_FEE],
        }
    }