added filestrings to most places

Author: Bengt Lofgren

solana/modules/matching-engine-testing/tests/testing_engine/setup.rs

@@ -581,13 +581,19 @@ pub struct TestingActors {
 }
 
 impl TestingActors {
+    /// Create a new TestingActors struct
+    ///
+    /// # Arguments
+    ///
+    /// * `owner_keypair_path` - The path to the owner keypair
+    ///
+    /// # Returns
     pub fn new(owner_keypair_path: &str) -> Self {
         let owner_kp = Rc::new(read_keypair_from_file(owner_keypair_path));
         let owner = TestingActor::new(owner_kp.clone(), None);
         let owner_assistant = TestingActor::new(owner_kp.clone(), None);
         let fee_recipient = TestingActor::new(Rc::new(Keypair::new()), None);
         let relayer = TestingActor::new(Rc::new(Keypair::new()), None);
-        // TODO: Change player 1 solver to use the keyfile
         let mut solvers = vec![];
         solvers.extend(vec![
             Solver::new(Rc::new(Keypair::new()), None),
@@ -605,6 +611,7 @@ impl TestingActors {
         }
     }
 
+    /// Get the actors that should have token accounts
     pub fn token_account_actors(&mut self) -> Vec<&mut TestingActor> {
         let mut actors = Vec::new();
         actors.push(&mut self.fee_recipient);
@@ -644,7 +651,7 @@ impl TestingActors {
 
     /// Add solvers to the testing actors
     #[allow(dead_code)]
-    async fn add_solvers(
+    pub async fn add_solvers(
         &mut self,
         test_context: &mut ProgramTestContext,
         num_solvers: usize,
@@ -675,6 +682,13 @@ pub enum ShimMode {
     VerifyAndPostSignature,
 }
 
+/// The direction of the transfer
+///
+/// # Enums
+///
+/// * `FromArbitrumToEthereum` - The direction of the transfer from Arbitrum to Ethereum
+/// * `FromEthereumToArbitrum` - The direction of the transfer from Ethereum to Arbitrum
+/// * `Other` - The direction of the transfer is not supported
 #[allow(dead_code)]
 #[derive(Copy, Clone, PartialEq, Eq)]
 pub enum TransferDirection {

solana/modules/matching-engine-testing/tests/utils/account_fixtures.rs

@@ -1,3 +1,9 @@
+//! # Account Fixtures
+//!
+//! This module provides fixtures for creating accounts in the test environment.
+//! It includes methods for creating accounts and for reading a keypair from a JSON fixture file.
+//! These accounts are located in the `tests/fixtures/accounts` directory.
+
 use anchor_lang::prelude::{pubkey, Pubkey};
 use anyhow::Result as AnyhowResult;
 use serde_json::Value;

solana/modules/matching-engine-testing/tests/utils/airdrop.rs

@@ -9,10 +9,9 @@ use super::constants;
 ///
 /// # Arguments
 ///
-/// * `test_context` - The test context
+/// * `test_context` - The program test context
 /// * `recipient` - The recipient of the airdrop        
 /// * `amount` - The amount of SOL to airdrop
-
 pub async fn airdrop(test_context: &mut ProgramTestContext, recipient: &Pubkey, amount: u64) {
     // Create the transfer instruction with values from the context
     let transfer_ix = system_instruction::transfer(&test_context.payer.pubkey(), recipient, amount);
@@ -32,6 +31,13 @@ pub async fn airdrop(test_context: &mut ProgramTestContext, recipient: &Pubkey,
         .unwrap();
 }
 
+/// Airdrops USDC to a given recipient
+///
+/// # Arguments
+///
+/// * `test_context` - The program test context
+/// * `recipient_ata` - The recipient's ATA
+/// * `amount` - The amount of USDC to airdrop
 pub async fn airdrop_usdc(
     test_context: &mut ProgramTestContext,
     recipient_ata: &Pubkey,

solana/modules/matching-engine-testing/tests/utils/auction.rs

@@ -6,6 +6,19 @@ use super::Chain;
 use crate::testing_engine::setup::{TestingActor, TestingContext, TransferDirection};
 use anyhow::{anyhow, Result as AnyhowResult};
 use matching_engine::state::{Auction, AuctionInfo};
+
+/// A struct representing the accounts for an auction
+///
+/// # Fields
+///
+/// * `posted_fast_vaa` - The address of the posted fast VAA
+/// * `offer_token` - The address of the offer token
+/// * `actor` - The actor of the auction (who places the initial offer, improves it, executes it, or settles it)
+/// * `auction_config` - The address of the auction config
+/// * `from_router_endpoint` - The address of the router endpoint for the source chain
+/// * `to_router_endpoint` - The address of the router endpoint for the destination chain
+/// * `custodian` - The address of the custodian
+/// * `usdc_mint` - The usdc mint address
 #[derive(Clone)]
 pub struct AuctionAccounts {
     pub posted_fast_vaa: Option<Pubkey>,
@@ -178,6 +191,12 @@ impl ActiveAuctionState {
     }
 }
 
+/// Compares two auctions to assert they are equal
+///
+/// # Arguments
+///
+/// * `auction_1` - The first auction
+/// * `auction_2` - The second auction
 pub async fn compare_auctions(auction_1: &Auction, auction_2: &Auction) {
     let auction_1_info = auction_1.info.unwrap();
     let auction_2_info = auction_2.info.unwrap();

solana/modules/matching-engine-testing/tests/utils/cctp_message.rs

@@ -131,7 +131,7 @@ pub enum TokenMessengerError {
     InvalidTokenMint,
 }
 
-//https://github.com/circlefin/solana-cctp-contracts/blob/4477f889732209dfc9a08b3aeaeb9203a324055c/programs/token-messenger-minter/src/token_messenger/state.rs#L35-L38
+// Imported from https://github.com/circlefin/solana-cctp-contracts/blob/4477f889732209dfc9a08b3aeaeb9203a324055c/programs/token-messenger-minter/src/token_messenger/state.rs#L35-L38
 #[derive(Debug, InitSpace)]
 pub struct CctpRemoteTokenMessenger {
     pub domain: u32, // Big endian
@@ -147,7 +147,7 @@ impl From<&RemoteTokenMessenger> for CctpRemoteTokenMessenger {
     }
 }
 
-// https://github.com/circlefin/solana-cctp-contracts/blob/4477f889732209dfc9a08b3aeaeb9203a324055c/programs/message-transmitter/src/message.rs#L30
+// Imported from https://github.com/circlefin/solana-cctp-contracts/blob/4477f889732209dfc9a08b3aeaeb9203a324055c/programs/message-transmitter/src/message.rs#L30
 #[derive(Clone, Debug)]
 pub struct Message<'a> {
     data: &'a [u8],
@@ -296,7 +296,7 @@ impl<'a> Message<'a> {
     }
 }
 
-// https://github.com/circlefin/solana-cctp-contracts/blob/4477f889732209dfc9a08b3aeaeb9203a324055c/programs/token-messenger-minter/src/token_messenger/burn_message.rs#L26
+// Imported from https://github.com/circlefin/solana-cctp-contracts/blob/4477f889732209dfc9a08b3aeaeb9203a324055c/programs/token-messenger-minter/src/token_messenger/burn_message.rs#L26
 #[derive(Clone, Debug)]
 pub struct BurnMessage<'a> {
     data: &'a [u8],
@@ -393,6 +393,15 @@ pub struct CircleAttester {
 }
 
 impl CircleAttester {
+    /// Creates an attestation for a given message
+    ///
+    /// # Arguments
+    ///
+    /// * `message` - The message to attest to
+    ///
+    /// # Returns
+    ///
+    /// A 65 byte array containing the attestation and the recovery id in the last byte
     pub fn create_attestation(&self, message: &[u8]) -> [u8; 65] {
         // Sign the message hash with the guardian key
         let secp = secp256k1::SECP256K1;
@@ -425,6 +434,14 @@ impl Default for CircleAttester {
     }
 }
 
+/// A struct representing a CCTP token burn message
+///
+/// # Fields
+///
+/// * `destination_cctp_domain` - The destination CCTP domain
+/// * `cctp_message` - The CCTP message
+/// * `encoded_cctp_burn_message` - The encoded CCTP burn message
+/// * `cctp_attestation` - The CCTP attestation
 pub struct CctpTokenBurnMessage {
     pub destination_cctp_domain: u32,
     pub cctp_message: CctpMessage,
@@ -440,6 +457,17 @@ impl CctpTokenBurnMessage {
     }
 }
 
+/// A struct representing a CCTP message header
+///
+/// # Fields
+///
+/// * `version` - The version of the CCTP message
+/// * `source_domain` - The source CCTP domain
+/// * `destination_domain` - The destination CCTP domain
+/// * `nonce` - The nonce of the CCTP message
+/// * `sender` - The sender of the CCTP message
+/// * `recipient` - The recipient of the CCTP message
+/// * `destination_caller` - The destination caller of the CCTP message
 pub struct CctpMessageHeader {
     pub version: u32,
     pub source_domain: u32,
@@ -470,6 +498,15 @@ impl CctpMessageHeader {
     }
 }
 
+/// A struct representing a CCTP message body
+///
+/// # Fields
+///
+/// * `version` - The version of the CCTP message
+/// * `burn_token_address` - The address of the token to burn
+/// * `mint_recipient` - The address of the recipient of the token
+/// * `amount` - The amount of the token to burn
+/// * `message_sender` - The address of the sender of the message
 pub struct CctpMessageBody {
     pub version: u32,
     pub burn_token_address: [u8; 32],
@@ -520,6 +557,12 @@ impl From<&BurnMessage<'_>> for CctpMessageBody {
     }
 }
 
+/// A struct representing a CCTP message
+///
+/// # Fields
+///
+/// * `header` - The header of the CCTP message
+/// * `body` - The body of the CCTP message
 pub struct CctpMessage {
     pub header: CctpMessageHeader,
     pub body: CctpMessageBody,
@@ -535,6 +578,18 @@ impl CctpMessage {
     }
 }
 
+/// Crafts a CCTP token burn message
+///
+/// # Arguments
+///
+/// * `test_context` - The test context
+/// * `source_cctp_domain` - The source CCTP domain
+/// * `cctp_nonce` - The nonce of the CCTP message
+/// * `amount` - The amount of the token to burn
+/// * `message_transmitter_config_pubkey` - The pubkey of the message transmitter config
+/// * `remote_token_messenger` - The remote token messenger
+/// * `cctp_mint_recipient` - The address of the recipient of the token
+/// * `custodian_address` - The address of the custodian
 #[allow(clippy::too_many_arguments)]
 pub async fn craft_cctp_token_burn_message(
     test_context: &mut ProgramTestContext,
@@ -612,6 +667,15 @@ pub async fn craft_cctp_token_burn_message(
     })
 }
 
+/// Converts an Ethereum address to a wormhole universal address
+///
+/// # Arguments
+///
+/// * `eth_address` - The Ethereum address to convert
+///
+/// # Returns
+///
+/// A 32-byte array containing the universal address
 pub fn ethereum_address_to_universal(eth_address: &str) -> [u8; 32] {
     // Remove '0x' prefix if present
     let address_str = eth_address
@@ -629,6 +693,15 @@ pub fn ethereum_address_to_universal(eth_address: &str) -> [u8; 32] {
     universal_address
 }
 
+/// Gets the base fee for a deposit
+///
+/// # Arguments
+///
+/// * `deposit` - The deposit to get the base fee for
+///
+/// # Returns
+///
+/// The base fee for the deposit
 pub fn get_deposit_base_fee(deposit: &Deposit) -> u64 {
     let payload = deposit.payload.clone();
     let liquidity_layer_message = LiquidityLayerDepositMessage::parse(&payload).unwrap();
@@ -664,6 +737,12 @@ impl UsedNonces {
     }
 }
 
+/// A struct representing a decoded CCTP message
+///
+/// # Fields
+///
+/// * `nonce` - The nonce of the CCTP message
+/// * `source_domain` - The source CCTP domain
 #[derive(Debug)]
 pub struct CctpMessageDecoded {
     pub nonce: u64,

solana/modules/matching-engine-testing/tests/utils/constants.rs

@@ -1,5 +1,39 @@
 #![allow(dead_code)]
 
+//! # Constants
+//!
+//! This module contains constants for the matching engine testing module.
+//!
+//! ## Exposed constants
+//!
+//! - `CORE_BRIDGE_PID` - The program ID of the core bridge
+//! - `CORE_BRIDGE_FEE_COLLECTOR` - The fee collector of the core bridge
+//! - `CORE_BRIDGE_CONFIG` - The config of the core bridge
+//! - `TOKEN_BRIDGE_PID` - The program ID of the token bridge
+//! - `TOKEN_BRIDGE_EMITTER_AUTHORITY` - The emitter authority of the token bridge
+//! - `TOKEN_BRIDGE_CUSTODY_AUTHORITY` - The custody authority of the token bridge
+//! - `TOKEN_BRIDGE_MINT_AUTHORITY` - The mint authority of the token bridge
+//! - `TOKEN_BRIDGE_TRANSFER_AUTHORITY` - The transfer authority of the token bridge
+//! - `USDC_MINT` - The mint address of USDC
+//! - `GUARDIAN_SECRET_KEY` - The guardian secret key
+//! - `TOKEN_ROUTER_PID` - The program ID of the token router
+//! - `CCTP_TOKEN_MESSENGER_MINTER_PID` - The program ID of the CCTP token messenger minter
+//! - `CCTP_MESSAGE_TRANSMITTER_PID` - The program ID of the CCTP message transmitter
+//! - `WORMHOLE_POST_MESSAGE_SHIM_PID` - The program ID of the Wormhole post message shim
+//! - `WORMHOLE_VERIFY_VAA_SHIM_PID` - The program ID of the Wormhole verify VAA shim
+//! - `WORMHOLE_POST_MESSAGE_SHIM_EVENT_AUTHORITY` - The event authority of the Wormhole post message shim
+//!
+//! ## Enums
+//!
+//! - `Chain` - An enum representing the different chains. Chain implements `as_cctp_domain` to get the CCTP domain for the chain.
+//!
+//! ## Examples
+//!
+//! ```rust
+//! use crate::constants::*;
+//! let eth_cctp_domain = Chain::Ethereum.as_cctp_domain();
+//! ```
+
 use solana_program::pubkey;
 use solana_sdk::pubkey::Pubkey;
 use solana_sdk::signature::Keypair;
@@ -79,36 +113,28 @@ pub const WORMHOLE_POST_MESSAGE_SHIM_EVENT_AUTHORITY_BUMP: u8 = 255;
 // pub const PLAYER_ONE_KEYPAIR_B64: &str = "4STrqllKVVva0Fphqyf++6uGTVReATBe2cI26oIuVBft77CQP9qQrMTU1nM9ql0EnCpSgmCmm20m8khMo9WdPQ==";
 
 /// Keypairs as base58 strings (taken from consts.ts in ts tests using a converter)
-#[allow(dead_code)]
 pub const PAYER_KEYPAIR_B58: &str =
     "4NMwxzmYj2uvHuq8xoqhY8RXg0Pd5zkvmfWAL6YvbYFuViXVCBDK5Pru9GgqEVEZo6UXcPVH6rdR8JKgKxHGkXDp";
-#[allow(dead_code)]
 pub const OWNER_ASSISTANT_KEYPAIR_B58: &str =
     "2UbUgoidcNHxVEDG6ADNKGaGDqBTXTVw6B9pWvJtLNhbxcQDkdeEyBYBYYYxxDy92ckXUEaU9chWEGi5jc8Uc9e3";
-#[allow(dead_code)]
 pub const OWNER_KEYPAIR_B58: &str =
     "3M5rkG5DQVEGQFRtA1qruxPqJvYBbkGCdkCdB9ZjcnQnYL9ec8W78pLcQHVtjJzHP8phUXQ8V1SXbgZK9ZaFaS6U";
-#[allow(dead_code)]
 pub const PLAYER_ONE_KEYPAIR_B58: &str =
     "yqJrKqGqzuW6nEmfj62AgvZWqgGv9TqxfvPXiGvf8DxGDWz3UNkQdDfKDnBYpHQxPRVrYMupDKqbGVYHhfZApGb";
 
 // Helper functions to get keypairs
-#[allow(dead_code)]
 pub fn get_payer_keypair() -> Keypair {
     Keypair::from_base58_string(PAYER_KEYPAIR_B58)
 }
 
-#[allow(dead_code)]
 pub fn get_owner_assistant_keypair() -> Keypair {
     Keypair::from_base58_string(OWNER_ASSISTANT_KEYPAIR_B58)
 }
 
-#[allow(dead_code)]
 pub fn get_owner_keypair() -> Keypair {
     Keypair::from_base58_string(OWNER_KEYPAIR_B58)
 }
 
-#[allow(dead_code)]
 pub fn get_player_one_keypair() -> Keypair {
     Keypair::from_base58_string(PLAYER_ONE_KEYPAIR_B58)
 }

solana/modules/matching-engine-testing/tests/utils/mint.rs

@@ -1,3 +1,7 @@
+//! # Mint fixture
+//!
+//! This module provides a fixture for creating a mint account (like a USDC mint).
+
 use anchor_spl::token::spl_token;
 use solana_cli_output::CliAccount;
 use solana_program_test::ProgramTestContext;

solana/modules/matching-engine-testing/tests/utils/program_fixtures.rs

@@ -1,3 +1,9 @@
+//! # Program Fixtures
+//!
+//! This module provides fixtures for initializing programs on the Solana blockchain.
+//! It includes functions to initialize the upgrade manager, CCTP token messenger minter,
+//! wormhole core bridge, CCTP message transmitter, local token router, and verify shims.
+
 use solana_program::bpf_loader_upgradeable;
 use solana_program_test::ProgramTest;
 use solana_sdk::pubkey::Pubkey;

solana/modules/matching-engine-testing/tests/utils/public_keys.rs

@@ -1,3 +1,8 @@
+//! # Public Keys
+//!
+//! This module provides a struct for representing public keys in the test environment.
+//! It includes methods for converting between different key types and for creating unique keys.
+
 use solana_sdk::{keccak, pubkey::Pubkey};
 
 use super::Chain;