Humanity Protocol VCs Contract

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

Contract Address

Testnet: 0x6B325482141A010d79114eb9c8B9C51975DC0a43

Overview

The VCs contract provides essential functionality to establish and manage decentralized identities on the blockchain. It maintains a registry of users, a registry of verifiable credentials, and supports a simple, one-level referral system.

Key Features

• User Registry: Maintains a record of user addresses and their referrers.
• Verifiable Credentials (VC) Registry: Stores VCs by hash, including status, issuer, expiration, category, and source.
• Credential Categorization: Supports dynamic categories for organizing VCs.
• Role-Based Access Control: Distinguishes between contract owner, authorizedRegistrars, and authorizedIssuers.
• Batch Processing: Allows for efficient bulk registration of users and issuance of credentials.

Architecture

The system consists of a main contract, HumanityProtocolVCs_Phase1, and an optional helper contract, VCBatchProcessor, for off-chain batching operations.

Core Data Structures

Copy
// Main VC Contract: HumanityProtocolVCs_Phase1

struct User {
    address userAddr;      // User's wallet address
    address referrerAddr;  // Address of the user who referred this user
}

struct VC {
    string issuerDID; // DID of the issuer (validator)
    VCStatus status; // Status of the credential (ACTIVE, REVOKED)
    uint256 expiresAt; // Timestamp when expires (0 for no expiry)
    string category; // Category as string
    string source; // Source identifier
}

// Used for batch credential issuance
struct CredentialData {
    bytes32 vcHash;
    string vcCategory;
    string vcSource;
    string issuerDID;
    uint256 expiresAt;
}

Access Control Roles

• owner: Full administrative access, equivalent to DEFAULT_ADMIN_ROLE. Manages registrars and issuers.
• authorizedRegistrars: Permitted to register new users.
• authorizedIssuers: Permitted to issue and revoke verifiable credentials.

Key Functions

Viewing Functions

Copy
// --- Counters & Totals ---
function totalUsers() external view returns (uint256);
function totalPalmVerifiedUsers() external view returns (uint256);

// --- User & VC Lookups ---
function users(address userAddress) external view returns (User memory);
function isRegistered(address userAddress) external view returns (bool);
function getVcData(bytes32 vcHash) external view returns (VC memory);
function isCredentialValid(bytes32 vcHash) external view returns (bool);

// --- Category Management ---
function getCategories() external view returns (string[] memory);
function isCategoryValid(string calldata category) external view returns (bool);

// --- Access Control ---
function authorizedIssuers(address issuer) external view returns (bool);
function authorizedRegistrars(address registrar) external view returns (bool);

Administrative & Core Functions

Copy
// --- Initialization (for proxy) ---
function initialize() external initializer;

// --- User Registration (Registrar Role) ---
function register(address userAddress, address referrerAddress) external;
function batchRegister(User[] calldata usersToRegister) external;

// --- Credential Management (Issuer Role) ---
function issueCredential(...) external;
function batchIssueCredentials(CredentialData[] calldata credentials) external;
function revokeCredential(bytes32 vcHash) external;

// --- Role Management (Owner Role) ---
function authorizeRegistrar(address registrar) external;
function deauthorizeRegistrar(address registrar) external;
function authorizeIssuer(address issuer) external;
function deauthorizeIssuer(address issuer) external;
function transferAdmin(address newAdmin) external;

// --- Category Management (Owner Role) ---
function addCategory(string calldata category) external;
function removeCategory(string calldata category) external;
function addCategories(string[] calldata categories) external;
function removeCategories(string[] calldata categories) external;

Events

Copy
// Emitted on user registration
event UserRegistered(address userAddress, address referrerAddress);

// Emitted on credential state changes
event CredentialIssued(bytes32 vcHash);
event CredentialRevoked(bytes32 vcHash);

// Emitted on role changes
event RegistrarAuthorized(address registrar);
event RegistrarDeauthorized(address registrar);
event IssuerAuthorized(address issuer);
event IssuerDeauthorized(address issuer);

// Emitted on category changes
event CategoryAdded(string category);
event CategoryRemoved(string category);

Sequence Flows

User Registration Flow

1. A contract with authorizedRegistrars role (or the owner) calls register(userAddress, referrerAddress).
2. The contract checks if userAddress is not address(0) and not already registered.
3. The contract checks that the user is not referring themselves.
4. The new user is stored in the _users mapping.
5. totalUsers counter is incremented.
6. A UserRegistered event is emitted.

Credential Issuance Flow

1. A contract with authorizedIssuers role (or the owner) calls issueCredential(...).
2. The contract checks that the credential does not already exist and the issuer DID is not empty.
3. If a category is provided, it must be a valid, registered category.
4. The new VC is stored in the vcRegistry mapping.
5. A CredentialIssued event is emitted.

VCBatchProcessor Contract

The VCBatchProcessor is a separate, optional helper contract that can be used to batch-issue credentials. It is controlled by its own admin and authorizedOperators. It calls the batchIssueCredentials function on the main VC contract. This can be useful for off-chain services that need to process large volumes of credentials efficiently.