feat: Enhance IdentityManagerV2 with Stats Tracking for Verifications

[2PykeETH]

Summary

This PR introduces two new internal functions to IdentityManagerV2 that update system-level statistics whenever a verification is added or revoked. This enhancement ensures accurate, real-time tracking of verification activity and lays the foundation for future analytics, auditing, and monitoring features.

---

Changes

src/IdentityManagerV2.sol

• New Internal Functions

  • _updateStatsOnAdd(VerificationLevel level)
    • Increments totalVerifications (global counter).
    • Increments activeVerifications (currently valid verifications).
    • Increments specific counters based on verification level:
      • deviceVerifications
      • orbVerifications
  • _updateStatsOnRevoke(VerificationLevel level)
    • Decrements activeVerifications safely (only if > 0).
    • Prevents underflow conditions by using guard checks.

• NatSpec Documentation

  • Added detailed NatSpec comments for both functions to improve maintainability and clarity.

• Formatting

  • Applied forge fmt for consistent Solidity code style.

---

Motivation

• Data Integrity: Previous implementation tracked users and types but lacked direct updates to system statistics when verification states changed.
• Analytics Support: Provides real-time counters for auditing verification growth and churn.
• Future Compatibility: Prepares the contract for external dashboards, monitoring tools, or reward systems that depend on verification activity metrics.

---

Impact

• Developers: Easier tracking of verification flows without requiring manual recalculations.
• System Monitoring: Enables transparent reporting of active vs. revoked verifications.
• Scalability: Foundation for advanced features like tiered access, rewards, or network health indicators.

---

Next Steps

• Integrate _updateStatsOnAdd and _updateStatsOnRevoke into public verification management functions (e.g., verifyUser, revokeVerification).
• Expand stats struct to cover more granular insights (e.g., timestamp tracking, user retention).
• Expose read-only stats functions for external dApps and analytics platforms.