feat(core): add stats and tradeHistory state variables with NatSpec documentation to TestArbitrage.sol

[malgus01]

Summary

This PR introduces new state variables and a dedicated NatSpec section header into the TestArbitrage contract. These additions improve the transparency and accessibility of contract performance data while enabling detailed tracking of individual trades.

Changes

• Added Section Header

  • Introduced a STATE VARIABLES section for improved readability and code organization.

• Added State Variables

  • ContractStats public stats:
    • Tracks aggregated contract statistics (total trades, total profit, volume, gas efficiency, last trade timestamp).
    • Exposed as public for direct external access.
  • mapping(uint256 => TradeResult) public tradeHistory:
    • Stores historical trade execution results keyed by trade ID.
    • Enables granular retrieval of arbitrage outcomes for analysis and debugging.

• Added NatSpec Documentation

  • Clear field-level documentation for stats and tradeHistory.
  • Maintains consistency with prior struct NatSpec style.

• Formatting

  • Ran forge fmt to ensure style consistency.

• Codebase Metrics

  • 12 additions
  • 0 deletions

Why This Change

• Establishes a foundation for on-chain analytics and reporting.
• Provides direct visibility into contract health (stats) and detailed trade outcomes (tradeHistory).
• Improves maintainability by grouping variables into a clearly documented section.
• Sets the stage for future query functions and events tied to trade performance.

Impact

• No breaking changes.
• Adds externally accessible state for monitoring.
• Increases contract observability and auditability.

Testing

• Verified compilation with new state variables.
• Confirmed stats and tradeHistory are accessible as public.
• Upcoming unit tests to validate tradeHistory storage and stats updates after trades.

Next Steps

• Implement helper functions to paginate and query trade history.
• Add events to synchronize trade history updates off-chain.
• Write Foundry tests to ensure stats and tradeHistory update correctly after executions.