feat: Add emergency controls and expired verification cleanup to IdentityManagerV2

[2PykeETH]

PR Description

Summary

This PR introduces emergency functions and an administrative cleanup mechanism to the IdentityManagerV2 contract. These updates improve system resilience, security, and long-term state management.

Changes

🚨 Emergency Controls

• Added pause() function:
  • Callable only by EMERGENCY_ROLE.
  • Temporarily halts contract operations using OpenZeppelin’s Pausable.
• Added unpause() function:
  • Callable only by EMERGENCY_ROLE.
  • Resumes contract operations.

🧹 Cleanup Function

• Implemented cleanupExpiredVerifications(address[] calldata users):
  • Callable by anyone to reduce state bloat and maintain contract health.
  • Iterates through a batch of user addresses (capped by MAX_BATCH_SIZE).
  • For each expired verification:
    • Removes the user from the verified users list.
    • Removes the user from their corresponding user-type list.
    • Updates system statistics:
      • activeVerifications decremented.
      • expiredVerifications incremented.
    • Deletes expired UserVerification storage entry.
    • Emits a VerificationExpire event.

📖 Documentation

• Added NatSpec section header for emergency functions.
• Detailed comments for:
  • pause()
  • unpause()
  • cleanupExpiredVerifications()

Motivation

• Provide admins with the ability to halt and resume operations in emergencies (security incidents, exploits, or protocol-wide issues).
• Introduce a public cleanup function to safely remove expired verifications, preventing:
  • Unnecessary state growth.
  • Outdated verifications from being exploited.

Files Changed

• src/IdentityManagerV2.sol
  • +42 additions
  • Emergency functions (pause, unpause).
  • Public cleanup function (cleanupExpiredVerifications).
  • NatSpec documentation.

Next Steps

• Add test coverage for:
  • Pausing/unpausing functionality.
  • Batch cleanup of expired verifications.
• Consider gas-optimizations for large-scale cleanup (e.g., events-only approach or pagination).

---

✅ This PR strengthens contract security with emergency controls and improves state integrity via public expired verification cleanup.