feat: Add batchVerifyUsers external function to IIdentityManagerV2

[2PykeETH]

Summary

This PR extends the IIdentityManagerV2 interface with the new batchVerifyUsers external function. The feature enables administrators to efficiently verify multiple users in a single transaction, improving scalability and reducing gas overhead compared to individual verification calls.

---

Changes

• New Function: batchVerifyUsers

  • Parameters:

    • users[] — array of user addresses to verify.
    • userTypes[] — array mapping each user to a UserType (e.g., basic, advanced, institution).
    • levels[] — array of verification levels applied to each user.
    • expirationTimestamps[] — array of verification expiration timestamps for each user.
    • metadataHashes[] — array of off-chain metadata/IPFS or hash references for auditability.

  • Expected Behavior:

    • Processes arrays in a single call, ensuring one-to-one mapping between users and verification attributes.
    • Emits events per user or a batch event for transparency (implementation detail to be handled in contract logic).
    • Provides significant gas savings and improves UX for onboarding multiple users at once.

---

Motivation

• Efficiency: Replaces multiple single verifyAndExecute calls with one batched call.
• Scalability: Supports high-volume user onboarding for dApps, DAOs, and identity systems.
• Flexibility: Allows attaching metadata hashes for off-chain compliance, audit logs, or KYC integration.

---

Next Steps

• Implement the function logic in the IdentityManagerV2 contract.
• Add validation checks:
  • Arrays must be of equal length.
  • Each user address must be unique within the batch.
  • Expiration timestamps must be valid (greater than current block timestamp).
• Add NatSpec comments for function documentation.
• Create test coverage for:
  • Successful batch verification.
  • Failure when array lengths mismatch.
  • Failure when one of the verifications is invalid.