feat(core): add structured trade parameters, results, and contract statistics to TestArbitrage.sol

[malgus01]

Summary

This PR introduces new structs and corresponding NatSpec documentation into the TestArbitrage contract to improve clarity, maintainability, and analytical capabilities of the arbitrage testing framework. These additions allow for more structured trade execution, result tracking, and performance monitoring.

Changes

• Added Structs

  • TradeParams: encapsulates all configurable parameters for executing arbitrage (router paths, token paths, fee, slippage, deadlines, etc.).
  • TradeResult: captures detailed outcome metrics (success, flash loan amount, profit, gas used, timestamp, tokens).
  • ContractStats: tracks overall performance metrics (total trades, cumulative profit, total volume, average gas usage, last trade timestamp).

• Added NatSpec Documentation

  • Provided detailed field-level annotations for all new structs.
  • Introduced a STRUCTS section with clear separation for readability and maintainability.

• Constructor Update

  • Ensures initial stats are seeded with block.timestamp.
  • Improved clarity around configuration initialization and authorized trader setup.

• Codebase Metrics

  • 58 additions
  • 3 deletions

Why This Change

• Provides a clear and extensible data model for trade configuration and analysis.
• Enhances auditability by documenting purpose and parameters of each struct.
• Prepares groundwork for advanced reporting, analytics, and automated testing.
• Improves readability and future maintainability.

Impact

• No breaking changes introduced.
• Existing arbitrage logic remains intact.
• Developers can now leverage structured inputs/outputs for testing and analysis.

Testing

• Verified contract compilation passes with new structs.
• Confirmed constructor initializes stats.lastTradeTimestamp.
• Validated NatSpec comments render correctly for documentation.
• To be followed up with new test cases utilizing TradeParams and TradeResult.

Next Steps

• Expand unit tests to validate trade execution against TradeParams.
• Add event emissions tied to TradeResult for easier on-chain monitoring.
• Implement performance tracking updates for ContractStats during live simulations.