feat: Add Pool Reserves Query Function to Test_AMMContract

[Neros0]

Summary

This PR adds a new view function getPoolReserves() to the Test_AMMContract, enabling external callers to query the current token reserves for any pool by its market ID. This enhances the contract's observability and enables better integration with off-chain systems and frontends.

Changes

New Function

getPoolReserves(bytes32 marketId)

• Type: External view function
• Parameters:
  • marketId: Unique identifier for the prediction market/pool
• Returns:
  • reserve0: Current reserve amount of tokenA in the pool
  • reserve1: Current reserve amount of tokenB in the pool
• Gas: Read-only operation, minimal gas cost for queries

Use Cases

This function enables several important capabilities:

1. Price Discovery: Calculate current token ratios and implied prices

   (uint256 reserveA, uint256 reserveB) = amm.getPoolReserves(marketId);
   uint256 price = (reserveA * 1e18) / reserveB;

2. Liquidity Analysis: Determine available liquidity before executing swaps

3. Frontend Integration: Display real-time pool state in user interfaces

4. Analytics & Monitoring: Track reserve changes over time for market insights

5. Smart Contract Composition: Other contracts can query reserves for decision-making

Technical Details

• +20 lines added to src/onchain/TestAMMContract.sol
• Pure view function with no state modifications
• Returns tuple of two uint256 values
• Reads from marketIdToPool mapping to retrieve pool data
• Non-existent pools return (0, 0) gracefully

Behavior

Scenario	Return Value	Notes
Valid pool with liquidity	(reserveA, reserveB)	Actual current reserves
Valid pool, no liquidity	(0, 0)	Pool exists but empty
Non-existent pool	(0, 0)	Default struct values

Documentation

The function includes comprehensive NatSpec documentation:

• @notice: Clear description of functionality
• @dev: Implementation details
• @param: Parameter explanation
• @return: Description of both return values
• Requirements: Notes on pool existence handling
• @Custom:reserves: Clarification that these are actual contract balances
• @Custom:analytics: Highlights use cases for the data

Integration Examples

Frontend (using Wagmi)

const { data: reserves } = useReadContract({
  address: ammAddress,
  abi: ammABI,
  functionName: 'getPoolReserves',
  args: [marketId],
});

const [reserveA, reserveB] = reserves || [0n, 0n];

Smart Contract

(uint256 reserveA, uint256 reserveB) = ammContract.getPoolReserves(marketId);
require(reserveA > minLiquidity && reserveB > minLiquidity, "Insufficient liquidity");

Testing Recommendations

Ensure the following test cases are covered:

1. Valid Pool: Returns correct reserves for an existing pool with liquidity
2. Empty Pool: Returns (0, 0) for pool with no liquidity
3. Non-Existent Pool: Returns (0, 0) without reverting
4. Multiple Pools: Correctly differentiates reserves between different market IDs
5. After Swap: Reserves update correctly after token swaps
6. After Liquidity Add/Remove: Reserves reflect liquidity changes

Suggested Test Structure (Foundry)

function test_GetPoolReserves_ValidPool() public {
    // Setup pool with known reserves
    (uint256 reserve0, uint256 reserve1) = amm.getPoolReserves(marketId);
    assertEq(reserve0, expectedReserveA);
    assertEq(reserve1, expectedReserveB);
}

function test_GetPoolReserves_NonExistentPool() public {
    bytes32 fakeMarketId = keccak256("fake");
    (uint256 reserve0, uint256 reserve1) = amm.getPoolReserves(fakeMarketId);
    assertEq(reserve0, 0);
    assertEq(reserve1, 0);
}

Security Considerations

• Read-only function poses no security risks
• No access control needed for public pool data
• Does not expose sensitive internal state
• Cannot be exploited for state manipulation

Related Functions

This function complements the existing getAllPools() function by providing:

• More granular, targeted queries
• Lower gas costs for single pool lookups
• Simpler return type for specific use cases