Contract Integration Guide (Phase 1)

This guide explains how to integrate your dApp or backend service with the Humanity Protocol Verifiable Credentials (VCs) Phase 1 contract.

1. Basic Integration Concepts

Interacting with Humanity Protocol currently involves one key on-chain component:

1. The VCs contract (HumanityProtocolVCs_Phase1) which handles:

• User registration & referrers
• Issuance / revocation of verifiable credentials
• Category & issuer management

2. Contract Address & ABI

Network	Address	Explorer
Testnet	0x6B325482141A010d79114eb9c8B9C51975DC0a43	Humanity Testnet Explorer

Grab the ABI from contracts/abis/humanityArbitrum/HumanityProtocolVCs_Phase1-abi.json or your preferred artifact source.

---

3. Solidity Integration Examples

3.1 Checking User Registration

Copy
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import { IHumanityProtocolVCs_Phase1 } from "./interfaces/IVC_Phase1.sol";

contract YourDApp {
    IHumanityProtocolVCs_Phase1 private immutable vc;

    constructor(address vcContractAddress) {
        vc = IHumanityProtocolVCs_Phase1(vcContractAddress);
    }

    modifier onlyRegisteredHuman() {
        require(vc.isRegistered(msg.sender), "User not registered on Humanity Protocol");
        _;
    }

    // Function that can only be executed by a registered user
    function gatedAction() external onlyRegisteredHuman {
        // Your business logic
    }

    // Fetch a user's referrer (address(0) if none)
    function getReferrer(address user) external view returns (address) {
        IHumanityProtocolVCs_Phase1.User memory u = vc.users(user);
        return u.referrerAddr;
    }
}

3.2 Validating a Credential

If your app stores a credential hash off-chain, you can verify its current status on-chain:

Copy
function isCredentialStillValid(bytes32 vcHash) external view returns (bool) {
    return vc.isCredentialValid(vcHash);
}

---

4. JavaScript / Ethers.js Integration

Copy
import { ethers } from "ethers";

// RPC for Humanity Protocol testnet
const provider = new ethers.providers.JsonRpcProvider(
  "https://humanity-testnet.g.alchemy.com/public",
);

// VC contract
const VC_ADDRESS = "0x6B325482141A010d79114eb9c8B9C51975DC0a43";
const vcAbi = require("./abis/HumanityProtocolVCs_Phase1-abi.json");
const vcContract = new ethers.Contract(VC_ADDRESS, vcAbi, provider);

// Check if a wallet is registered
export async function isWalletRegistered(walletAddress) {
  try {
    return await vcContract.isRegistered(walletAddress);
  } catch (err) {
    console.error("VC call failed", err);
    return false;
  }
}

// Lookup referrer
export async function getReferrer(userAddress) {
  const userStruct = await vcContract.users(userAddress);
  return userStruct.referrerAddr;
}

// Check if a credential is valid
export async function isCredentialValid(vcHash) {
  try {
    return await vcContract.isCredentialValid(vcHash);
  } catch (err) {
    console.error("Credential validation failed", err);
    return false;
  }
}

---

5. Best Practices

1. Verify contract addresses: Always double-check you are using the official Humanity Protocol addresses per network.
2. Cache results: isRegistered and credential checks are inexpensive, but caching frequent reads reduces RPC latency.
3. Batch where possible: Use batchRegister and batchIssueCredentials to cut gas costs when onboarding many users.
4. Graceful error handling: Treat failed calls as non-verified / non-registered and surface actionable messages to end-users.
5. Listen to events: Subscribe to UserRegistered, CredentialIssued, and CredentialRevoked for real-time UX updates.

Security Considerations

1. Always verify contract addresses: Ensure you're interacting with the official Humanity Protocol contracts
2. Check returned values: Always validate return values from contract calls
3. Handle error states gracefully: Implement proper error handling for failed transactions
4. Use event listeners cautiously: Consider the potential for missed events due to network issues

Performance Optimizations

1. Batch operations: Use the batch functions when possible for multiple registrations or verifications
2. Cache verification status: Consider caching verification results to reduce RPC calls
3. Monitor gas costs: Be mindful of gas costs, especially for batch operations

Frontend Integration Tips

1. Connect wallet first: Always ensure wallet connection before attempting contract interactions
2. Show pending transactions: Provide feedback for users during transaction processing
3. Handle network changes: Be prepared for users switching networks
4. Responsive error handling: Display user-friendly error messages

---

6. Referenced Interface (Subset)

Below is a minimal subset of the IHumanityProtocolVCs_Phase1 interface you'll typically use:

Copy
interface IHumanityProtocolVCs_Phase1 {
    struct User {
        address userAddr;
        address referrerAddr;
    }

    enum VCStatus {
        ACTIVE,
        REVOKED
    }

    struct VC {
        string issuerDID;
        VCStatus status;
        uint256 expiresAt;
        string category;
        string source;
    }

    // View functions
    function isRegistered(address user) external view returns (bool);
    function users(address user) external view returns (User memory);
    function isCredentialValid(bytes32 vcHash) external view returns (bool);
    function getVcData(bytes32 vcHash) external view returns (VC memory);
    function totalUsers() external view returns (uint256);
    function totalPalmVerifiedUsers() external view returns (uint256);

    // Events
    event UserRegistered(address indexed user, address indexed referrer);
    event CredentialIssued(bytes32 indexed vcHash);
    event CredentialRevoked(bytes32 indexed vcHash);
}

For complete definitions see the Solidity files in contracts/implementation/vc/.