waterpump-solana-core 0.1.0

//! Transaction builder utilities for Solana

use anyhow::Result;
use solana_client::nonblocking::rpc_client::RpcClient;
use solana_sdk::{
    account::Account,
    hash::Hash,
    instruction::Instruction,
    message::{v0, AddressLookupTableAccount, Message, VersionedMessage},
    pubkey::Pubkey,
    signature::{Keypair, Signature, Signer},
    transaction::{Transaction, VersionedTransaction},
};

/// Builder for constructing Solana transactions from instructions and signers
///
/// This struct is similar to transaction result types from various Solana
/// program SDKs, containing the instructions and additional signers needed to
/// build and execute a transaction.
#[derive(Debug)]
pub struct TransactionBuilder {
    /// A vector of `Instruction` objects required to execute the transaction.
    pub instructions: Vec<Instruction>,

    /// A vector of `Keypair` objects representing additional signers required
    /// for the instructions.
    pub additional_signers: Vec<Keypair>,

    /// A vector of `AddressLookupTableAccount` objects for V0 transactions.
    /// Address lookup tables allow transactions to reference more accounts than
    /// the legacy format.
    pub address_lookup_tables: Vec<AddressLookupTableAccount>,
}

impl TransactionBuilder {
    /// Create a new empty `TransactionBuilder`
    pub fn new() -> Self {
        Self {
            instructions: Vec::new(),
            additional_signers: Vec::new(),
            address_lookup_tables: Vec::new(),
        }
    }

    /// Create a new `TransactionBuilder` with the given instructions and
    /// signers
    pub fn with_components(
        instructions: Vec<Instruction>,
        additional_signers: Vec<Keypair>,
    ) -> Self {
        Self { instructions, additional_signers, address_lookup_tables: Vec::new() }
    }

    /// Add an instruction to the builder
    pub fn add_instruction(&mut self, instruction: Instruction) -> &mut Self {
        self.instructions.push(instruction);
        self
    }

    /// Add multiple instructions to the builder
    pub fn add_instructions(&mut self, instructions: Vec<Instruction>) -> &mut Self {
        self.instructions.extend(instructions);
        self
    }

    /// Add an additional signer to the builder
    pub fn add_signer(&mut self, signer: Keypair) -> &mut Self {
        self.additional_signers.push(signer);
        self
    }

    /// Add multiple additional signers to the builder
    pub fn add_signers(&mut self, signers: Vec<Keypair>) -> &mut Self {
        self.additional_signers.extend(signers);
        self
    }

    /// Add an address lookup table to the builder
    ///
    /// Address lookup tables allow V0 transactions to reference more accounts
    /// than the legacy format by storing account addresses in on-chain lookup
    /// tables.
    ///
    /// # Arguments
    /// * `lookup_table` - The address lookup table account to add
    ///
    /// # Returns
    /// `&mut Self` for method chaining
    pub fn add_lookup_table(&mut self, lookup_table: AddressLookupTableAccount) -> &mut Self {
        self.address_lookup_tables.push(lookup_table);
        self
    }

    /// Add multiple address lookup tables to the builder
    ///
    /// # Arguments
    /// * `lookup_tables` - A vector of address lookup table accounts to add
    ///
    /// # Returns
    /// `&mut Self` for method chaining
    pub fn add_lookup_tables(
        &mut self,
        lookup_tables: Vec<AddressLookupTableAccount>,
    ) -> &mut Self {
        self.address_lookup_tables.extend(lookup_tables);
        self
    }

    /// Add an address lookup table by fetching it from RPC using its address
    ///
    /// This method fetches the lookup table from the RPC and adds it to the
    /// builder.
    ///
    /// # Arguments
    /// * `rpc_client` - The RPC client to fetch the lookup table from
    /// * `lookup_table_pubkey` - The public key of the lookup table to fetch
    ///   and add
    ///
    /// # Returns
    /// `&mut Self` for method chaining
    ///
    /// # Example
    /// ```ignore
    /// use waterpump_solana_core::transaction_builder::TransactionBuilder;
    /// use solana_client::nonblocking::rpc_client::RpcClient;
    /// use solana_sdk::pubkey::Pubkey;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let rpc_client = RpcClient::new("https://api.mainnet-beta.solana.com".to_string());
    /// let lookup_table_pubkey = Pubkey::from_str("...")?;
    ///
    /// let mut builder = TransactionBuilder::new();
    /// builder.add_lookup_table_by_address(&rpc_client, &lookup_table_pubkey).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn add_lookup_table_by_address(
        &mut self,
        rpc_client: &RpcClient,
        lookup_table_pubkey: &Pubkey,
    ) -> Result<&mut Self> {
        let lookup_table = Self::fetch_lookup_table(rpc_client, lookup_table_pubkey).await?;
        self.address_lookup_tables.push(lookup_table);
        Ok(self)
    }

    /// Add multiple address lookup tables by fetching them from RPC using their
    /// addresses
    ///
    /// This method fetches multiple lookup tables from the RPC in a single
    /// batch call and adds them to the builder.
    ///
    /// # Arguments
    /// * `rpc_client` - The RPC client to fetch the lookup tables from
    /// * `lookup_table_pubkeys` - A slice of public keys of the lookup tables
    ///   to fetch and add
    ///
    /// # Returns
    /// `&mut Self` for method chaining
    ///
    /// # Example
    /// ```ignore
    /// use waterpump_solana_core::transaction_builder::TransactionBuilder;
    /// use solana_client::nonblocking::rpc_client::RpcClient;
    /// use solana_sdk::pubkey::Pubkey;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let rpc_client = RpcClient::new("https://api.mainnet-beta.solana.com".to_string());
    /// let lookup_table_pubkeys = vec![/* lookup table pubkeys */];
    ///
    /// let mut builder = TransactionBuilder::new();
    /// builder.add_lookup_tables_by_addresses(&rpc_client, &lookup_table_pubkeys).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn add_lookup_tables_by_addresses(
        &mut self,
        rpc_client: &RpcClient,
        lookup_table_pubkeys: &[Pubkey],
    ) -> Result<&mut Self> {
        let lookup_tables = Self::fetch_lookup_tables(rpc_client, lookup_table_pubkeys).await?;
        self.address_lookup_tables.extend(lookup_tables);
        Ok(self)
    }

    /// Build a versioned transaction with the given fee payer
    ///
    /// # Arguments
    /// * `fee_payer` - The keypair that will pay for the transaction fees
    ///
    /// # Returns
    /// A signed `VersionedTransaction` ready to be sent
    ///
    /// # Note
    /// This method uses a default blockhash. For production use, prefer
    /// `build_transaction_with_blockhash` with a recent blockhash from RPC,
    /// or use `send`/`send_and_confirm` which fetch the latest blockhash
    /// automatically.
    pub fn build_transaction(&self, fee_payer: &Keypair) -> Result<VersionedTransaction> {
        self.build_transaction_with_blockhash(fee_payer, &Hash::default())
    }

    /// Build a versioned transaction with the given fee payer and blockhash
    ///
    /// # Arguments
    /// * `fee_payer` - The keypair that will pay for the transaction fees
    /// * `recent_blockhash` - The recent blockhash to use for the transaction
    ///
    /// # Returns
    /// A signed `VersionedTransaction` ready to be sent
    ///
    /// # Errors
    /// Returns an error if:
    /// - The V0 message fails to compile
    /// - The versioned transaction fails to create or sign
    pub fn build_transaction_with_blockhash(
        &self,
        fee_payer: &Keypair,
        recent_blockhash: &Hash,
    ) -> Result<VersionedTransaction> {
        // Collect all signers (fee payer + additional signers)
        let mut signers: Vec<&Keypair> = vec![fee_payer];
        signers.extend(self.additional_signers.iter());

        // Build a V0 message (supports address lookup tables)
        let message = v0::Message::try_compile(
            &fee_payer.pubkey(),
            &self.instructions,
            &self.address_lookup_tables,
            *recent_blockhash,
        )
        .map_err(|e| anyhow::anyhow!("Failed to compile V0 message: {}", e))?;

        // Create and sign the versioned transaction
        VersionedTransaction::try_new(VersionedMessage::V0(message), &signers)
            .map_err(|e| anyhow::anyhow!("Failed to create VersionedTransaction: {}", e))
    }

    /// Build a legacy transaction with the given fee payer
    ///
    /// Legacy transactions don't support address lookup tables and are limited
    /// to 64 accounts. Use versioned transactions if you need more accounts
    /// or address lookup tables.
    ///
    /// # Arguments
    /// * `fee_payer` - The keypair that will pay for the transaction fees
    ///
    /// # Returns
    /// A signed `Transaction` ready to be sent
    ///
    /// # Note
    /// This method uses a default blockhash. For production use, prefer
    /// `build_legacy_transaction_with_blockhash` with a recent blockhash from
    /// RPC, or use `send`/`send_and_confirm` which fetch the latest
    /// blockhash automatically.
    pub fn build_legacy_transaction(&self, fee_payer: &Keypair) -> Transaction {
        self.build_legacy_transaction_with_blockhash(fee_payer, &Hash::default())
    }

    /// Build a legacy transaction with the given fee payer and blockhash
    ///
    /// Legacy transactions don't support address lookup tables and are limited
    /// to 64 accounts. Use versioned transactions if you need more accounts
    /// or address lookup tables.
    ///
    /// # Arguments
    /// * `fee_payer` - The keypair that will pay for the transaction fees
    /// * `recent_blockhash` - The recent blockhash to use for the transaction
    ///
    /// # Returns
    /// A signed `Transaction` ready to be sent
    ///
    /// # Panics
    /// Panics if the transaction requires more than 64 accounts (legacy limit)
    pub fn build_legacy_transaction_with_blockhash(
        &self,
        fee_payer: &Keypair,
        recent_blockhash: &Hash,
    ) -> Transaction {
        // Collect all signers (fee payer + additional signers)
        let mut signers: Vec<&Keypair> = vec![fee_payer];
        signers.extend(self.additional_signers.iter());

        // Build a legacy message (no address lookup tables)
        let message = Message::new(&self.instructions, Some(&fee_payer.pubkey()));

        // Create and sign the legacy transaction
        let mut transaction = Transaction::new_unsigned(message);
        transaction.sign(&signers, *recent_blockhash);

        transaction
    }

    /// Build a versioned transaction with the given fee payer pubkey
    ///
    /// This method is useful when the fee payer keypair is not available,
    /// but you still want to construct the transaction structure.
    /// Additional signers will be used to sign the transaction, but the fee
    /// payer must sign it separately.
    ///
    /// # Arguments
    /// * `fee_payer_pubkey` - The public key of the fee payer
    ///
    /// # Returns
    /// A `VersionedTransaction` signed by additional signers (if any), but
    /// still needs to be signed by the fee payer
    ///
    /// # Errors
    /// Returns an error if:
    /// - The V0 message fails to compile
    /// - The versioned transaction fails to create
    /// - There are no additional signers (fee payer keypair is not available)
    pub fn build_partially_signed_transaction(
        &self,
        fee_payer_pubkey: &Pubkey,
    ) -> Result<VersionedTransaction> {
        // Build a V0 message (supports address lookup tables)
        // Note: Using default blockhash for partially signed transactions
        let message = v0::Message::try_compile(
            fee_payer_pubkey,
            &self.instructions,
            &self.address_lookup_tables,
            Hash::default(),
        )
        .map_err(|e| anyhow::anyhow!("Failed to compile V0 message: {}", e))?;
        let versioned_message = VersionedMessage::V0(message);

        // Sign with additional signers if any
        if !self.additional_signers.is_empty() {
            let signers: Vec<&Keypair> = self.additional_signers.iter().collect();
            let tx = VersionedTransaction::try_new(versioned_message, &signers)
                .map_err(|e| anyhow::anyhow!("Failed to create VersionedTransaction: {}", e))?;
            Ok(tx)
        } else {
            Err(anyhow::anyhow!(
                "build_partially_signed_transaction requires at least one additional signer when \
                 fee payer keypair is not available. Use build_transaction() if you have the fee \
                 payer keypair."
            ))
        }
    }

    /// Get the number of instructions
    pub fn instruction_count(&self) -> usize { self.instructions.len() }

    /// Get the number of additional signers
    pub fn signer_count(&self) -> usize { self.additional_signers.len() }

    /// Check if the builder is empty (no instructions)
    pub fn is_empty(&self) -> bool { self.instructions.is_empty() }

    /// Consume the builder and return its components
    pub fn into_components(
        self,
    ) -> (Vec<Instruction>, Vec<Keypair>, Vec<AddressLookupTableAccount>) {
        (self.instructions, self.additional_signers, self.address_lookup_tables)
    }

    /// Merge another `TransactionBuilder` into this one
    ///
    /// This method takes all instructions, signers, and lookup tables from the
    /// other builder and adds them to this builder. The other builder is
    /// consumed in the process.
    ///
    /// # Arguments
    /// * `other` - The `TransactionBuilder` to merge into this one
    ///
    /// # Returns
    /// `&mut Self` for method chaining
    ///
    /// # Example
    /// ```ignore
    /// use waterpump_solana_core::transaction_builder::TransactionBuilder;
    ///
    /// let mut builder1 = TransactionBuilder::new();
    /// builder1.add_instruction(instruction1);
    ///
    /// let mut builder2 = TransactionBuilder::new();
    /// builder2.add_instruction(instruction2);
    ///
    /// builder1.merge(builder2); // builder1 now contains both instructions
    /// ```
    pub fn merge(&mut self, other: TransactionBuilder) -> &mut Self {
        self.instructions.extend(other.instructions);
        self.additional_signers.extend(other.additional_signers);
        self.address_lookup_tables.extend(other.address_lookup_tables);
        self
    }

    /// Create a new `TransactionBuilder` by merging two builders
    ///
    /// This is a static method that takes two builders and creates a new one
    /// containing all instructions and signers from both. Both input builders
    /// are consumed.
    ///
    /// # Arguments
    /// * `first` - The first `TransactionBuilder` to merge
    /// * `second` - The second `TransactionBuilder` to merge
    ///
    /// # Returns
    /// A new `TransactionBuilder` containing all instructions and signers from
    /// both builders
    ///
    /// # Example
    /// ```ignore
    /// use waterpump_solana_core::transaction_builder::TransactionBuilder;
    ///
    /// let builder1 = TransactionBuilder::new();
    /// let builder2 = TransactionBuilder::new();
    ///
    /// let merged = TransactionBuilder::merge_builders(builder1, builder2);
    /// ```
    pub fn merge_builders(
        mut first: TransactionBuilder,
        second: TransactionBuilder,
    ) -> TransactionBuilder {
        first.merge(second);
        first
    }

    /// Build and send a transaction, then wait for confirmation
    ///
    /// This method:
    /// 1. Gets the latest blockhash from the RPC client
    /// 2. Builds a versioned transaction with the fee payer and recent
    ///    blockhash
    /// 3. Sends it to the network via the RPC client
    /// 4. Waits for confirmation
    /// 5. Returns the transaction signature
    ///
    /// # Arguments
    /// * `rpc_client` - The RPC client to use for sending the transaction
    /// * `fee_payer` - The keypair that will pay for the transaction fees
    ///
    /// # Returns
    /// The transaction signature if successful
    pub async fn send_and_confirm(
        &self,
        rpc_client: &RpcClient,
        fee_payer: &Keypair,
    ) -> Result<Signature> {
        // Get the latest blockhash
        let recent_blockhash = rpc_client
            .get_latest_blockhash()
            .await
            .map_err(|e| anyhow::anyhow!("Failed to get latest blockhash: {}", e))?;

        // Build transaction with the recent blockhash
        let transaction = self.build_transaction_with_blockhash(fee_payer, &recent_blockhash)?;

        let signature = rpc_client
            .send_and_confirm_transaction(&transaction)
            .await
            .map_err(|e| anyhow::anyhow!("Failed to send and confirm transaction: {}", e))?;

        Ok(signature)
    }

    /// Build and send a transaction
    ///
    /// This method:
    /// 1. Gets the latest blockhash from the RPC client
    /// 2. Builds a versioned transaction with the fee payer and recent
    ///    blockhash
    /// 3. Sends it to the network via the RPC client
    /// 4. Returns the transaction signature
    ///
    /// # Arguments
    /// * `rpc_client` - The RPC client to use for sending the transaction
    /// * `fee_payer` - The keypair that will pay for the transaction fees
    ///
    /// # Returns
    /// The transaction signature if successful
    pub async fn send(&self, rpc_client: &RpcClient, fee_payer: &Keypair) -> Result<Signature> {
        // Get the latest blockhash
        let recent_blockhash = rpc_client
            .get_latest_blockhash()
            .await
            .map_err(|e| anyhow::anyhow!("Failed to get latest blockhash: {}", e))?;

        // Build transaction with the recent blockhash
        let transaction = self.build_transaction_with_blockhash(fee_payer, &recent_blockhash)?;

        let signature = rpc_client
            .send_transaction(&transaction)
            .await
            .map_err(|e| anyhow::anyhow!("Failed to send transaction: {}", e))?;

        Ok(signature)
    }

    /// Simulate a transaction without sending it to the network
    ///
    /// This method:
    /// 1. Gets the latest blockhash from the RPC client
    /// 2. Builds a versioned transaction with the fee payer and recent
    ///    blockhash
    /// 3. Simulates the transaction execution via the RPC client
    /// 4. Returns the simulation result
    ///
    /// # Arguments
    /// * `rpc_client` - The RPC client to use for simulating the transaction
    /// * `fee_payer` - The keypair that will pay for the transaction fees
    ///
    /// # Returns
    /// The simulation result containing execution status, logs, and compute
    /// units used
    pub async fn simulate(
        &self,
        rpc_client: &RpcClient,
        fee_payer: &Keypair,
    ) -> Result<solana_client::rpc_response::RpcSimulateTransactionResult> {
        use solana_client::rpc_config::RpcSimulateTransactionConfig;

        // Get the latest blockhash
        let recent_blockhash = rpc_client
            .get_latest_blockhash()
            .await
            .map_err(|e| anyhow::anyhow!("Failed to get latest blockhash: {}", e))?;

        // Build transaction with the recent blockhash
        let transaction = self.build_transaction_with_blockhash(fee_payer, &recent_blockhash)?;

        // Simulate the transaction with default config
        let config = RpcSimulateTransactionConfig::default();

        let response = rpc_client
            .simulate_transaction_with_config(&transaction, config)
            .await
            .map_err(|e| anyhow::anyhow!("Failed to simulate transaction: {}", e))?;

        if let Some(err) = response.value.err {
            return Err(anyhow::anyhow!("Failed to simulate transaction: {}", err));
        }

        Ok(response.value)
    }
}

impl Default for TransactionBuilder {
    fn default() -> Self { Self::new() }
}

impl From<(Vec<Instruction>, Vec<Keypair>)> for TransactionBuilder {
    fn from((instructions, additional_signers): (Vec<Instruction>, Vec<Keypair>)) -> Self {
        Self::with_components(instructions, additional_signers)
    }
}

/// Helper functions for working with address lookup tables
impl TransactionBuilder {
    /// Fetch an address lookup table from RPC and create an
    /// AddressLookupTableAccount
    ///
    /// This function fetches the lookup table account data from the Solana
    /// network, deserializes it, and creates an `AddressLookupTableAccount`
    /// that can be used in V0 transactions.
    ///
    /// # Arguments
    /// * `rpc_client` - The RPC client to fetch the lookup table from
    /// * `lookup_table_pubkey` - The public key of the address lookup table
    ///
    /// # Returns
    /// An `AddressLookupTableAccount` containing the lookup table's key and
    /// addresses
    ///
    /// # Example
    /// ```ignore
    /// use waterpump_solana_core::transaction_builder::TransactionBuilder;
    /// use solana_client::nonblocking::rpc_client::RpcClient;
    /// use solana_sdk::pubkey::Pubkey;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let rpc_client = RpcClient::new("https://api.mainnet-beta.solana.com".to_string());
    /// let lookup_table_pubkey = Pubkey::from_str("...")?;
    ///
    /// let lookup_table_account = TransactionBuilder::fetch_lookup_table(
    ///     &rpc_client,
    ///     &lookup_table_pubkey,
    /// ).await?;
    ///
    /// let mut builder = TransactionBuilder::new();
    /// builder.add_lookup_table(lookup_table_account);
    /// # Ok(())
    /// # }
    /// ```
    /// Parse AddressLookupTable account data
    ///
    /// This is a helper function to parse raw account data into an
    /// AddressLookupTableAccount. Structure (based on
    /// solana-program/src/address_lookup_table/state.rs):
    /// - Discriminator: 1 byte (0x01 for AddressLookupTable)
    /// - Authority: 32 bytes (Pubkey)
    /// - Deactivation slot: 8 bytes (u64, little-endian)
    /// - Last extended slot: 8 bytes (u64, little-endian)
    /// - Last extended slot start index: 4 bytes (u32, little-endian)
    /// - Padding: 4 bytes
    /// - Addresses: variable length, each Pubkey is 32 bytes
    fn parse_lookup_table_account(
        pubkey: &Pubkey,
        account: &Account,
    ) -> Result<AddressLookupTableAccount> {
        let data = &account.data;
        if data.is_empty() {
            return Err(anyhow::anyhow!("Lookup table account {} data is empty", pubkey));
        }

        // Check discriminator (should be 0x01)
        if data[0] != 0x01 {
            return Err(anyhow::anyhow!(
                "Invalid lookup table discriminator for {}: expected 0x01, got 0x{:02x}",
                pubkey,
                data[0]
            ));
        }

        // Header size: 1 (discriminator) + 32 (authority) + 8 + 8 + 4 + 4 = 57 bytes
        const HEADER_SIZE: usize = 1 + 32 + 8 + 8 + 4 + 4;
        if data.len() < HEADER_SIZE {
            return Err(anyhow::anyhow!(
                "Lookup table account {} data too short: {} bytes, expected at least {}",
                pubkey,
                data.len(),
                HEADER_SIZE
            ));
        }

        // Extract addresses (each Pubkey is 32 bytes)
        // Account data may have padding at the end, so we parse only complete 32-byte
        // chunks
        let addresses_data = &data[HEADER_SIZE..];
        let num_complete_addresses = addresses_data.len() / 32;

        if num_complete_addresses == 0 {
            return Err(anyhow::anyhow!(
                "No complete addresses found in lookup table {}: {} bytes remaining after header",
                pubkey,
                addresses_data.len()
            ));
        }

        let mut addresses = Vec::with_capacity(num_complete_addresses);
        for chunk in addresses_data.chunks_exact(32).take(num_complete_addresses) {
            let address = Pubkey::try_from(chunk).map_err(|e| {
                anyhow::anyhow!("Failed to parse pubkey from lookup table {}: {}", pubkey, e)
            })?;
            addresses.push(address);
        }

        Ok(AddressLookupTableAccount { key: *pubkey, addresses })
    }

    /// Fetch a single address lookup table from RPC
    ///
    /// This is a convenience wrapper around `fetch_lookup_tables`.
    ///
    /// # Arguments
    /// * `rpc_client` - The RPC client to fetch the lookup table from
    /// * `lookup_table_pubkey` - The public key of the lookup table to fetch
    ///
    /// # Returns
    /// An `AddressLookupTableAccount` object
    ///
    /// # Example
    /// ```ignore
    /// use waterpump_solana_core::transaction_builder::TransactionBuilder;
    /// use solana_client::nonblocking::rpc_client::RpcClient;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let rpc_client = RpcClient::new("https://api.mainnet-beta.solana.com".to_string());
    /// let pubkey = /* lookup table pubkey */;
    ///
    /// let lookup_table = TransactionBuilder::fetch_lookup_table(
    ///     &rpc_client,
    ///     &pubkey,
    /// ).await?;
    ///
    /// let mut builder = TransactionBuilder::new();
    /// builder.add_lookup_table(lookup_table);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn fetch_lookup_table(
        rpc_client: &RpcClient,
        lookup_table_pubkey: &Pubkey,
    ) -> Result<AddressLookupTableAccount> {
        let mut tables = Self::fetch_lookup_tables(rpc_client, &[*lookup_table_pubkey]).await?;
        tables
            .pop()
            .ok_or_else(|| anyhow::anyhow!("Failed to fetch lookup table {}", lookup_table_pubkey))
    }

    /// Fetch multiple address lookup tables from RPC
    ///
    /// This function uses `get_multiple_accounts` for efficient batch fetching.
    ///
    /// # Arguments
    /// * `rpc_client` - The RPC client to fetch the lookup tables from
    /// * `lookup_table_pubkeys` - A slice of public keys for the lookup tables
    ///   to fetch
    ///
    /// # Returns
    /// A vector of `AddressLookupTableAccount` objects
    ///
    /// # Example
    /// ```ignore
    /// use waterpump_solana_core::transaction_builder::TransactionBuilder;
    /// use solana_client::nonblocking::rpc_client::RpcClient;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let rpc_client = RpcClient::new("https://api.mainnet-beta.solana.com".to_string());
    /// let pubkeys = vec![/* lookup table pubkeys */];
    ///
    /// let lookup_tables = TransactionBuilder::fetch_lookup_tables(
    ///     &rpc_client,
    ///     &pubkeys,
    /// ).await?;
    ///
    /// let mut builder = TransactionBuilder::new();
    /// builder.add_lookup_tables(lookup_tables);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn fetch_lookup_tables(
        rpc_client: &RpcClient,
        lookup_table_pubkeys: &[Pubkey],
    ) -> Result<Vec<AddressLookupTableAccount>> {
        if lookup_table_pubkeys.is_empty() {
            return Ok(Vec::new());
        }

        // Fetch all accounts in a single RPC call
        let accounts = rpc_client
            .get_multiple_accounts(lookup_table_pubkeys)
            .await
            .map_err(|e| anyhow::anyhow!("Failed to fetch lookup table accounts: {}", e))?;

        // Parse each account into AddressLookupTableAccount
        let mut lookup_tables = Vec::new();
        for (i, account_opt) in accounts.iter().enumerate() {
            let pubkey = &lookup_table_pubkeys[i];
            match account_opt {
                Some(account) => {
                    let lookup_table = Self::parse_lookup_table_account(pubkey, account)?;
                    lookup_tables.push(lookup_table);
                }
                None => {
                    return Err(anyhow::anyhow!("Lookup table account {} not found", pubkey));
                }
            }
        }

        Ok(lookup_tables)
    }
}