VC contract

The Verifiable Credentials (VC) contract is the backbone of the Humanity Protocol's verification system. It enables user registration, verification management, and tracks referral relationships.

Contract Address

Testnet: 0x6B325482141A010d79114eb9c8B9C51975DC0a43

Mainnet: 0x836C8C88d368d95Cc245b6EC73d15183303a81f5

Overview

The VC contract provides essential functionality to establish and verify human identities on the blockchain. It maintains a registry of users, tracks verification status, and manages referral relationships.

Key Features

• User registry maintaining address, referrer, and verification status
• Social Media verification that supports multiple platforms
• Referral tree tracking up to 10 levels deep
• Batch processing for efficient registration and verification operations

Architecture

Core Data Structures

Copy
struct User {
    address userAddr;      // User's wallet address
    address referrerAddr;  // Address of the user who referred this user
    bool verified;         // Whether the user has completed verification
}

struct SocialVCParams {
    address userAddr;      // User address for social verification
    string social;         // Social network identifier (e.g., "twitter", "facebook")
    string vc;             // Verification credential (empty string for revocation)
}

Access Control Roles

• DEFAULT_ADMIN_ROLE: Full administrative access, can grant other roles
• REGISTRATION_ADMIN_ROLE: Can register new users to the system
• VERIFICATION_ADMIN_ROLE: Can verify users and manage social verifications

Key Functions

Viewing Functions

Copy
// Returns total number of registered users
function totalUsers() external view returns (uint256)

// Returns total number of verified users
function totalVerifiedUsers() external view returns (uint256)

// Returns complete user data for a specific address
function getUser(address user) external view returns (User memory)

// Checks if a user is verified
function isVerified(address user) external view returns (bool)

// Checks if a user is registered
function isRegistered(address user) external view returns (bool)

// Returns an array of referrer addresses (up to 10 levels)
function getReferrersTree(address user) external view returns (address[] memory)

// Checks if a specific social network is verified for a user
function isSocialVerified(address user, string memory social) external view returns (bool)

// Returns the number of verified social networks for a user
function getSocialVerifiedCount(address user) external view returns (uint256)

// Returns the total users count when a user was registered
function getUsersCountOnRegistration(address user) external view returns (uint256)

Administrative Functions

Copy
// Initializes the contract (for proxy pattern)
function init() external initializer

// Registers a new user (requires REGISTRATION_ADMIN_ROLE)
function register(address userAddress, address referrerAddress) external

// Verifies a user (requires VERIFICATION_ADMIN_ROLE)
function verifyUser(address user) external

// Processes social verifications in batch (requires VERIFICATION_ADMIN_ROLE)
function batchSocialVC(SocialVCParams[] calldata params) external

// Registers and optionally verifies multiple users at once (requires REGISTRATION_ADMIN_ROLE)
function processBatch(User[] calldata users) external

Events

Copy
// Emitted when a user is registered
event UserRegistered(address userAddress, address referrerAddress)

// Emitted when a user is verified
event UserVerified(address user)

// Emitted when a social network is verified
event SocialVCVerified(address userAddr, string social, string vc)

// Emitted when a social verification is revoked
event SocialVCRevoked(address userAddr, string social)

Sequence Flows

User Registration Flow

1. A contract with REGISTRATION_ADMIN_ROLE calls register(userAddress, referrerAddress)
2. The contract checks if the user already exists (reverts if true)
3. The contract checks if the referrer exists (reverts if referrer is specified but doesn't exist)
4. The user is added to the registry and total user count is incremented
5. A UserRegistered event is emitted

User Verification Flow

1. A contract with VERIFICATION_ADMIN_ROLE calls verifyUser(user)
2. The contract checks if the user exists and is not already verified
3. The user's verification status is updated to true
4. The total verified user count is incremented
5. A UserVerified event is emitted

Social Verification Flow

1. A contract with VERIFICATION_ADMIN_ROLE calls batchSocialVC() with a list of params
2. For each social verification, the contract:
   • Updates the verification status for the specific social network
   • Updates the count of verified social networks for the user
   • Emits either SocialVCVerified or SocialVCRevoked based on operation