add docstrings and fix format

src/amm_core/oracles/agg.cairo

@@ -36,6 +36,9 @@ mod OracleAgg {
     }
 
     // @notice Returns terminal spot price for given ticker (quote and base token)
+    // @dev This function first checks if a price has been cached in the current block.
+    //      If so, it returns the cached price to avoid unnecessary oracle calls within
+    //      the same block. This optimization reduces external calls and gas costs.
     // @param quote_token_addr: Address of quote token in given ticker
     // @param base_token_addr: Address of base token in given ticker
     // @return terminal_price: Terminal spot price

src/amm_core/state.cairo

@@ -529,13 +529,22 @@ mod State {
         let pool = state.pool_definition_from_lptoken_address.write(lptoken_address, pool);
     }
 
+    // @notice Reads the latest oracle price for a given token pair
+    // @param base_token_address: Address of the base token
+    // @param quote_token_address: Address of the quote token
+    // @returns (price, block): Tuple containing the latest price as Fixed and the block number when it was updated
     fn read_latest_oracle_price(
         base_token_address: ContractAddress, quote_token_address: ContractAddress
     ) -> (Fixed, u64) {
         let state = AMM::unsafe_new_contract_state();
         state.latest_oracle_price.read((base_token_address, quote_token_address))
     }
 
+    // @notice Writes the latest oracle price for a given token pair
+    // @param base_token_address: Address of the base token
+    // @param quote_token_address: Address of the quote token
+    // @param price: The latest price as Fixed
+    // @param current_block: The current block number
     fn write_latest_oracle_price(
         base_token_address: ContractAddress,
         quote_token_address: ContractAddress,

tests/liquidity_pools/test_get_value_of_pool_position.cairo

@@ -2,18 +2,10 @@ use carmine_protocol::testing::setup::deploy_setup;
 use traits::{Into, TryInto};
 use debug::PrintTrait;
 use option::OptionTrait;
-use carmine_protocol::testing::test_utils::{Stats, StatsTrait};
 use carmine_protocol::amm_core::oracles::pragma::Pragma::PRAGMA_ORACLE_ADDRESS;
-use carmine_protocol::amm_core::oracles::pragma::PragmaUtils::{
-    PragmaPricesResponse, Checkpoint, AggregationMode
-};
+use carmine_protocol::amm_core::oracles::pragma::PragmaUtils::PragmaPricesResponse;
 use cubit::f128::types::fixed::{Fixed, FixedTrait};
-use snforge_std::{
-    declare, ContractClassTrait, start_prank, stop_prank, start_warp, stop_warp, ContractClass,
-    start_mock_call, stop_mock_call, start_roll
-};
-use carmine_protocol::amm_core::helpers::{FixedHelpersTrait, toU256_balance};
-use carmine_protocol::amm_core::amm::AMM;
+use snforge_std::{start_prank, stop_prank, start_warp, stop_warp, start_mock_call, stop_mock_call};
 use carmine_protocol::amm_interface::{IAMMDispatcher, IAMMDispatcherTrait};
 use carmine_protocol::testing::setup::{Ctx, Dispatchers};
 
@@ -22,9 +14,8 @@ fn test_get_value_of_pool_position() {
     let (ctx, dsps) = deploy_setup();
 
     // Set up initial state
+    start_warp(ctx.amm_address, 1000000000);
     start_prank(ctx.amm_address, ctx.admin_address);
-
-    // Mock the Pragma oracle call
     start_mock_call(
         PRAGMA_ORACLE_ADDRESS.try_into().unwrap(),
         'get_data',
@@ -38,24 +29,27 @@ fn test_get_value_of_pool_position() {
     );
 
     // Add some liquidity to the pool
-    let initial_deposit: u256 = 5000000000000000000; // 5 ETH
-    initial_deposit.print();
-    dsps.amm.deposit_liquidity(
-        ctx.eth_address,
-        ctx.usdc_address,
-        ctx.eth_address,
-        0, // Call option
-        initial_deposit
-    );
+    let one_int = 1000000000000000000; // 1*10**18
+    // Longs
+    let long_call_premia = dsps
+        .amm
+        .trade_open(
+            0, // Call
+            ctx.strike_price,
+            ctx.expiry,
+            0, // Long
+            one_int,
+            ctx.usdc_address,
+            ctx.eth_address,
+            FixedTrait::from_unscaled_felt(100_000),
+            99999999999
+        );
 
     // Get the initial pool value (this should use the mocked oracle price)
     let initial_pool_value = dsps.amm.get_value_of_pool_position(ctx.call_lpt_address);
-    initial_pool_value.print();
-    // Stop the mock call to the oracle
-    stop_mock_call(PRAGMA_ORACLE_ADDRESS.try_into().unwrap(), 'get_data');
 
-    // Warp time forward to ensure we're past any potential cache expiration
-    // start_warp(ctx.amm_address, 1000000000 + 60 * 60); // 1 hour later
+    // Stop the mock call to the oracle with price $1400
+    stop_mock_call(PRAGMA_ORACLE_ADDRESS.try_into().unwrap(), 'get_data');
 
     // Start pragma mock with new price
     // Expected behavior: price is gonna be obtained from state as block stays the same and new price in pragma would not
@@ -76,15 +70,5 @@ fn test_get_value_of_pool_position() {
     let new_pool_value = dsps.amm.get_value_of_pool_position(ctx.call_lpt_address);
 
     // Assert that the values are the same, indicating the use of cached oracle data
-    assert(
-        initial_pool_value == new_pool_value,
-        'Prices differ.'
-    );
-
-    // Calculate the expected pool value (5 ETH * $1400)
-    // let expected_value = FixedTrait::from_felt(7000000000000000000000); // 7000 USDC
-
-    // Assert that both values match the expected value
-    // assert(initial_pool_value == expected_value, 'Initial pool value incorrect');
-    // assert(new_pool_value == expected_value, 'Cached pool value incorrect');
+    assert(initial_pool_value == new_pool_value, 'Prices differ.');
 }