feat: Add getUserPositionInPool and getAllPools external view functions with full Natspec documentation

[2PykeETH]

Summary

This PR introduces two new external view functions — getUserPositionInPool and getAllPools — to the Test_AMMContract for improved transparency, analytics, and compatibility with frontends and off-chain monitoring tools.
Both functions include comprehensive Natspec comments to ensure clarity, maintainability, and adherence to Solidity documentation standards.

---

Changes Overview

🧩 New External View Functions

1. getUserPositionInPool(address _user, bytes32 _marketId)

Returns detailed information about a user’s liquidity position within a given market pool.
This function mirrors the structure of Uniswap V3–style position data, while simplifying some parameters for test and analytics environments.

Returns:

• operator: Contract address managing the position
• token0, token1: Token pair addresses for the pool
• fee: Fixed at 3000 (representing 0.3%) for compatibility
• liquidity: User’s current liquidity contribution
• tickLower, tickUpper: Fixed at 0 for simplified implementation
• tokensOwed0, tokensOwed1: Fixed to 0 (no fee tracking)
• amount0, amount1: Simplified token amount estimates (half of user liquidity each)

Purpose:

• Provides external visibility into user positions for UIs and analytics tools.
• Simplifies debugging and testing of pool state in development environments.
• Ensures compatibility with mainnet AMM interfaces while remaining lightweight.

---

2. getAllPools()

Returns a full array of all pools managed by this contract.

Returns:

• PoolData[]: Array containing every pool’s configuration and reserve state.

Purpose:

• Enables iteration over all pools without knowing their identifiers.
• Provides raw pool data for external dashboards, testing suites, and data pipelines.
• Facilitates analytics such as total liquidity, market depth, and pool enumeration.

---

Motivation

These enhancements significantly improve observability and testability of the AMM simulation contract (Test_AMMContract).
By exposing well-documented view functions, developers and analytics systems can now:

• 🧠 Query user and pool state directly from the blockchain.
• 📊 Aggregate and display on-chain AMM data in dashboards.
• 🔍 Debug and validate pool interactions more easily during integration testing.
• 🧩 Maintain compatibility with frontends designed for Uniswap-style contracts.

---

Implementation Notes

• Both functions are purely view-based, ensuring no gas cost for off-chain reads.
• Adheres to Forge formatting standards (forge fmt).
• Implements consistent Natspec headers following Arenium documentation structure.
• Designed to scale as new pool properties and analytics metrics are introduced.

---

Next Steps

• Add automated test coverage for getUserPositionInPool and getAllPools.
• Integrate with off-chain indexers for real-time pool tracking.
• Extend PoolData struct to include volume and fee metrics for richer analytics.

---

Result:
These additions strengthen the observability layer of the Arenium test AMM contract, improving both developer ergonomics and data accessibility.