feat: Add IIdentityManagerV2 Interface with Core Enums, Structs, and Events

[2PykeETH]

PR Description

Summary

This PR introduces the new IIdentityManagerV2 interface, providing a clear, structured contract for identity verification management in the IdentityManagerV2 system.
It establishes the foundational enums, structs, and events required for consistent external interaction, ensuring type safety and standardization across the protocol.

---

🔄 Changes Made

1. Interface Creation

• Added IIdentityManagerV2.sol under src/interfaces/.
• Includes contract-level NatSpec comments (@title, @notice, @dev).

2. Enums

• VerificationLevel

  • NONE → no verification.
  • DEVICE → device-based verification.
  • ORB → orb-based biometric verification.

• UserType

  • STUDENT
  • INSTITUTION
  • VERIFIER
  • ADMIN

Defines system roles and verification categories in a standardized format.

3. Structs

• UserVerification: encapsulates full verification details, including:

  • isVerified flag
  • VerificationLevel + UserType
  • Timestamps (verification + expiration)
  • nullifierHash for uniqueness
  • Optional metadata for extensibility

• VerificationStats: tracks global statistics:

  • totalVerifications
  • deviceVerifications
  • orbVerifications
  • activeVerifications
  • expiredVerifications

4. Events

• UserVerified

  • Fires when a user is successfully verified.
  • Includes user, nullifierHash, level, userType, and expirationTimestamp.

• UserVerificationRevoked

  • Fires when a user’s verification is revoked.
  • Includes user, revoker, and reason.

---

📂 Files Added

• src/interfaces/IIdentityManagerV2.sol → new interface definition

---

🎯 Motivation

• Provides a clean, modular interface for IdentityManagerV2.
• Establishes common data structures and events that ensure interoperability across contracts and external integrations.
• Enables developers and integrators to build against a stable API, decoupling interface from implementation.

---

✅ Next Steps

• Implement the interface in IdentityManagerV2.sol.
• Add external functions (verifyUser, revokeVerification, etc.) that adhere to this standard.
• Expand testing to validate event emission and struct population.

---

This PR is the foundation for the IdentityManagerV2 verification system, setting the stage for future functionality and contract integrations.