Credentials Verification Service

Developer Integration Guide

What is This?

The Humanity Protocol Credentials Verification Service allows your DApp to verify if users meet specific conditions, such as:

• Has the user completed KYC identity verification?

• Has the user connected social accounts like Google or Twitter?

• Does the user's net worth reach a certain tier?

• Is the user a member of a specific airline or hotel loyalty program?

In simple terms: Your smart contract can ask Humanity Protocol questions like "Does this user have a Google account?" or "Has this user passed KYC?", then decide whether to allow user actions based on the answer.

---

How It Works

1. User clicks "Verify Identity" button

The user initiates the verification process from your DApp's frontend interface.

2. User signs authorization

The user signs a permission message using their wallet (e.g., MetaMask) to authorize the verification request.

3. Your DApp contract calls the Oracle

Your DApp contract submits the verification request to the Humanity Protocol Verification Oracle, including the user's signature.

4. Oracle backend checks user credentials

The Oracle's off-chain backend validates the user's humanity credentials against Humanity Protocol's verification system.

5. Oracle calls back your contract with the result

The Oracle creates an on-chain attestation and calls your contract's onVerificationComplete callback with the verification result.

6. Your contract executes business logic

Your contract processes the result (verified or not) and executes the appropriate action, such as granting access or distributing tokens.

---

Core Concepts

Concept	Description
Credential	A verifiable claim held by the user — may be a W3C Verifiable Credential (VC), a Zero-Knowledge proof, or a proof generated from another protocol
Issuer	The entity responsible for assessing user attributes/behavior and issuing credentials — this may be a KYC provider, the protocol itself, or an external partner
Holder	The user's wallet address that stores the credential/proof and presents it to the DApp when required
Verifier Contract	The smart contract provided by this service, responsible for verifying credentials
Claim	A specific verification condition (e.g., google_connected, mc_kyc)
Category	A grouping of related claims (e.g., IDENTITY, SOCIAL, FINANCE)

Supported Verification Claims

Social Account Verification

The simplest and most common verification - confirms users have connected social accounts:

Claim ID	Meaning
github_connected	User has connected GitHub
google_connected	User has connected Google
discord_connected	User has connected Discord
twitter_connected	User has connected Twitter/X
linkedin_connected	User has connected LinkedIn
telegram_connected	User has connected Telegram
email_verified	User has verified email ownership
humanity_identity	User has verified via Palm check

Use Cases: Community verification, sybil attack prevention, ensuring real users

Identity & Financial Verification (Mastercard)

Verify user identity and assets through bank account data:

Claim ID	Meaning	Category
mc_kyc	User has completed KYC verification	Identity
mc_residency	User residency verification	Identity
mc_net_worth	Net worth tier ($100 / $10K / $1M+)	Finance
mc_investments	Investment account verification	Finance
mc_retirement	Retirement savings verification (401K, IRA)	Finance
mc_mortgage	Mortgage verification	Finance

Use Cases: DeFi lending, accredited investor verification, credit assessment

---

Membership Verification

Verify user's airline/hotel loyalty program memberships:

Airlines:

Claim ID	Airline
delta_membership	Delta Airlines SkyMiles
emirates_membership	Emirates Skywards
singapore_airlines_membership	Singapore Airlines KrisFlyer
american_airlines_membership	American Airlines AAdvantage
cathay_pacific_membership	Cathay Pacific Asia Miles
korean_air_membership	Korean Air SKYPASS
jetblue_membership	JetBlue TrueBlue
thai_airways_membership	Thai Airways Royal Orchid Plus
virgin_australia_membership	Virgin Australia Velocity
frontier_airlines_membership	Frontier Airlines Frontier Miles
spirit_airlines_membership	Spirit Airlines Free Spirit
etihad_membership	Etihad Airways Guest
ryanair_membership	Ryanair Membership
sas_membership	Scandinavian Airlines EuroBonus

Hotels:

Claim ID	Hotel Brand
marriott_membership	Marriott Bonvoy
hilton_membership	Hilton Honors
accor_membership	Accor Live Limitless
wyndham_membership	Wyndham Rewards
radisson_membership	Radisson Rewards
shangri_la_membership	Shangri-La Circle
taj_hotels_membership	Taj Hotels InnerCircle

Entertainment/Casinos:

Claim ID	Brand
caesars_membership	Caesars Rewards
mgm_resorts_membership	MGM Rewards
wynn_resorts_membership	Wynn Rewards

Use Cases: VIP member-exclusive events, loyalty rewards, identity verification

---

Crypto Exchange Verification (CEX)

Claim ID	Exchange	Verification Content
binance_finance	Binance	Account and balances verification
okx_finance	OKX	Account and total valuation

Use Cases: Airdrop eligibility, trading volume proof

---

Contract Addresses

Mainnet (Humanity Chain)

Contract	Address	Chain ID
HumanityVerificationOracle	0x8D71D8bD47860bd0381b272AE42162c3692c4F3a	6985385
FeeEscrow	0xe433f01131eAbD8060a1E34149eF0e79b2b86fEc	6985385

Testnet (Humanity Testnet)

Contract	Address	Chain ID
HumanityVerificationOracle	0x67c0A5cA2Fb19E8E0Ff008d727aff5f128b00E09	7080969
FeeEscrow	0x1a247b7d7076e4c4D97D87c62947Ab5495C13423	7080969

Quick Start

Step 1: Set Up Your Contract

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.29;

import { IHumanityVerificationCallback, IHumanityVerificationOracle }
    from "./IVerificationOracle.sol";

contract MyDApp is IHumanityVerificationCallback {

    // Oracle contract address (Testnet / Mainnet)
    IHumanityVerificationOracle public oracle;

    // Claims you need to verify
    string[] public REQUIRED_CLAIMS = ["google_connected"];

    // Verification validity period (30 days)
    uint256 public constant MAX_AGE = 30 days;

    // Track which users are verified
    mapping(address => bool) public verifiedUsers;

    // Track pending verification requests
    mapping(bytes32 => address) public pendingRequests;
}

Step 2: Implement Verification Request

// Users call this function to verify their identity
function verifyMe(bytes memory signature) external {
    // First check if already verified
    (bool alreadyVerified, , ) = oracle.isUserVerified(
        msg.sender,
        REQUIRED_CLAIMS,
        MAX_AGE
    );

    if (alreadyVerified) {
        verifiedUsers[msg.sender] = true;
        return; // Already verified, return early
    }

    // Request new verification
    bytes32 requestId = oracle.requestVerification(
        address(this),     // Your DApp address
        msg.sender,        // User to verify
        REQUIRED_CLAIMS,   // Verification conditions
        MAX_AGE,           // Validity period
        address(this),     // Callback address (receives result)
        signature          // User's signature authorization
    );

    pendingRequests[requestId] = msg.sender;
}

Step 3: Receive Verification Result

// Oracle calls this function when verification is complete
function onVerificationComplete(
    bytes32 requestId,
    address user,
    bool verified,      // true = verification passed
    bytes32 attestationUID
) external {
    // Security check: only Oracle can call
    require(msg.sender == address(oracle), "Only Oracle");
    require(pendingRequests[requestId] == user, "Unknown request");

    delete pendingRequests[requestId];

    if (verified) {
        // ✅ Verification passed! User meets all conditions
        verifiedUsers[user] = true;
        // Execute your business logic...
    } else {
        // ❌ Verification failed
        // Handle failure case...
    }
}

Step 4: Get User Signature on Frontend

// Frontend code (TypeScript)
import { ethers } from 'ethers';

async function getVerificationSignature(
    userAddress: string,
    dappAddress: string,
    oracleContract: ethers.Contract,
    signer: ethers.Signer
) {
    // 1. Get the message to sign from Oracle
    const messageHash = await oracleContract.getPermissionMessageHash(
        userAddress,
        dappAddress,
        ["google_connected"],  // Your verification conditions
        30 * 24 * 60 * 60,     // 30 days (in seconds)
        dappAddress
    );

    // 2. Have user sign (MetaMask will pop up)
    const signature = await signer.signMessage(ethers.getBytes(messageHash));

    return signature;
}

// Usage example
const signature = await getVerificationSignature(
    userWallet.address,
    "0xYourDAppContractAddress",
    oracleContract,
    signer
);

// Call the contract
await myDappContract.verifyMe(signature);

Fee Management

Prepaid Model Overview

Humanity Protocol uses a prepaid model:

Your DApp deposits $tHP into FeeEscrow once. Verification fees are deducted automatically. Users never pay fees directly.

DApp deposits $tHP → Users request verification → Fees auto-deducted → Result delivered

---

Quick Start

Deposit Funds

IFeeEscrow feeEscrow = IFeeEscrow(0xe433f01131eAbD8060a1E34149eF0e79b2b86fEc);

// Deposit 10 $tHP for your DApp
feeEscrow.deposit{value: 10 ether}(address(yourDApp));

Check Balance

// Get available balance
uint256 available = feeEscrow.getAvailable(address(this));

// Get full balance info
(uint256 total, uint256 reserved, uint256 available) =
    feeEscrow.getBalanceInfo(address(this));

// Check if can afford verification
(bool canAfford, ) = feeEscrow.canAffordFee(address(this), feeAmount);

Withdraw Unused Funds

// Request withdrawal (requires admin approval)
uint256 requestId = feeEscrow.requestWithdrawal(recipientAddress, amount);

// Cancel if needed
feeEscrow.cancelWithdrawalRequest(requestId);

---

Balance Types

Type	Description	How to Get
Total	All deposited funds	getBalance(dapp)
Reserved	Locked for pending verifications	getReserved(dapp)
Available	Can use for new verifications	getAvailable(dapp)

Available = Total - Reserved

---

Fee Lifecycle

1. RESERVE   → Fee locked when verification requested
2. PROCESS   → Oracle verifies user credentials
3. SETTLE    → Success: fee deducted | Failure: fee released back

You only pay for successful verifications.

---

FAQ

Question	Answer
Who funds FeeEscrow?	DApp developer/operator
When to fund?	Before users start verifying
What if balance runs out?	Verification requests fail with InsufficientAvailableBalance
Can users steal my funds?	No. Only Oracle can deduct fees; withdrawals need admin approval
One escrow per DApp?	Yes, each DApp needs its own balance
Can I withdraw unused funds?	Yes, request withdrawal → admin approves → funds sent

---

Best Practice: Monitor Balance

function checkEscrowHealth() external view returns (bool needsRefill) {
    uint256 available = feeEscrow.getAvailable(address(this));
    uint256 minRequired = verificationFee * 50; // Keep 50 verifications worth
    return available < minRequired;
}

---

Fee Distribution (on successful verification)

25% → Credential Issuers
25% → Protocol Treasury
25% → Staking Pool
25% → Proof Generation

---

Best Practices

Check Before Requesting

// Good practice: check if already verified first
(bool verified, , ) = oracle.isUserVerified(user, claims, maxAge);
if (verified) {
    // Use directly, no new request needed
    return;
}
// Only then request new verification

Choose Appropriate Claims

// Lending scenario: needs KYC + asset proof
string[] memory LENDING_CLAIMS = ["mc_kyc", "mc_net_worth"];

// Community scenario: needs social accounts
string[] memory COMMUNITY_CLAIMS = ["google_connected"];

// VIP members: airline/hotel membership
string[] memory VIP_CLAIMS = ["emirates_membership"];

Choose Appropriate Validity Period

Scenario	Recommended MAX_AGE
High security (financial)	1-7 days
Medium security (access control)	30 days
Low security (preferences)	90+ days

Maintain Sufficient Balance

function checkBalance() public view returns (bool needsRefill) {
    uint256 available = feeEscrow.getAvailable(address(this));
    uint256 minRequired = verificationFee * 10; // At least enough for 10 verifications
    return available < minRequired;
}

---

Common Errors

Error	Cause	Solution
InvalidUser()	User address is zero	Check user address
NoClaimsSpecified()	No verification claims specified	Pass at least one claim
InsufficientVerificationFee	FeeEscrow balance too low	Deposit more ETH
UnauthorizedRequest	Invalid user signature	Have user sign again
RequestNotFound	Request ID doesn't exist	Check requestId

Complete Example Contract

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.29;

import { IHumanityVerificationCallback, IHumanityVerificationOracle }
    from "./interfaces/IVerificationOracle.sol";
import { IFeeEscrow } from "./interfaces/IFeeEscrow.sol";

/**
 * @title Example: Airdrop Contract Requiring Identity Verification
 * @notice Only users with verified Google accounts can claim the airdrop
 */
contract VerifiedAirdrop is IHumanityVerificationCallback {

    IHumanityVerificationOracle public immutable oracle;
    IFeeEscrow public immutable feeEscrow;

    string[] public REQUIRED_CLAIMS;
    uint256 public constant MAX_AGE = 30 days;
    uint256 public constant AIRDROP_AMOUNT = 100 ether; // 100 tokens

    mapping(bytes32 => address) public pendingClaims;
    mapping(address => bool) public hasClaimed;

    event ClaimRequested(address indexed user, bytes32 requestId);
    event AirdropClaimed(address indexed user, uint256 amount);
    event ClaimFailed(address indexed user, string reason);

    constructor(address _oracle, address _feeEscrow) {
        oracle = IHumanityVerificationOracle(_oracle);
        feeEscrow = IFeeEscrow(_feeEscrow);
        REQUIRED_CLAIMS = ["google_connected"];
    }

    /// @notice Get the message hash for user to sign
    function getClaimSignatureHash(address user) external view returns (bytes32) {
        return oracle.getPermissionMessageHash(
            user,
            address(this),
            REQUIRED_CLAIMS,
            MAX_AGE,
            address(this)
        );
    }

    /// @notice User claims airdrop
    function claimAirdrop(bytes memory signature) external {
        require(!hasClaimed[msg.sender], "Already claimed");

        // Check if already verified
        (bool verified, bytes32 attestationUID, ) = oracle.isUserVerified(
            msg.sender, REQUIRED_CLAIMS, MAX_AGE
        );

        if (verified) {
            // Already verified, distribute airdrop directly
            _sendAirdrop(msg.sender);
            return;
        }

        // Request verification
        bytes32 requestId = oracle.requestVerification(
            address(this),
            msg.sender,
            REQUIRED_CLAIMS,
            MAX_AGE,
            address(this),
            signature
        );

        pendingClaims[requestId] = msg.sender;
        emit ClaimRequested(msg.sender, requestId);
    }

    /// @notice Oracle callback
    function onVerificationComplete(
        bytes32 requestId,
        address user,
        bool verified,
        bytes32 attestationUID
    ) external override {
        require(msg.sender == address(oracle), "Only Oracle");
        require(pendingClaims[requestId] == user, "Unknown request");

        delete pendingClaims[requestId];

        if (verified && !hasClaimed[user]) {
            _sendAirdrop(user);
        } else if (!verified) {
            emit ClaimFailed(user, "Verification failed");
        }
    }

    function _sendAirdrop(address user) internal {
        hasClaimed[user] = true;
        // Send tokens here...
        // token.transfer(user, AIRDROP_AMOUNT);
        emit AirdropClaimed(user, AIRDROP_AMOUNT);
    }

    /// @notice Admin deposits verification fees
    function depositFees() external payable {
        feeEscrow.deposit{value: msg.value}();
    }

    receive() external payable {}
}

---

Quick Reference

// Request verification
oracle.requestVerification(dapp, user, claims, maxAge, callback, signature)
    → returns bytes32 requestId

// Check if already verified
oracle.isUserVerified(user, claims, maxAge)
    → returns (bool verified, bytes32 attestationUID, uint256 expiresAt)

// Get signature message hash
oracle.getPermissionMessageHash(user, dapp, claims, maxAge, callback)
    → returns bytes32 messageHash

// Get user nonce (for debugging)
oracle.getUserNonce(user)
    → returns uint256 nonce

// Callback interface (your contract must implement)
onVerificationComplete(requestId, user, verified, attestationUID)

---

Credential Categories

All credentials are organized into these categories:

Category	Description	Example Claims
IDENTITY	Identity verification	mc_kyc, mc_residency ,humanity_identity
SOCIAL	Social platform connections	google_connected, twitter_connected
FINANCE	Financial credentials	mc_net_worth, binance_finance
MEMBERSHIP	Loyalty program memberships	marriott_membership, delta_membership
EMPLOYMENT	Employment verification	(Coming soon)
EDUCATION	Educational credentials	(Coming soon)
HEALTH	Health-related credentials	(Coming soon)
REPUTATION	Reputation scores	(Coming soon)
LEGAL	Legal documents	(Coming soon)
OWNERSHIP	Asset ownership	(Coming soon)

---

Security Notes

1. Always verify the caller in your callback function:

   require(msg.sender == address(oracle), "Unauthorized");

2. User signatures are one-time use - the nonce prevents replay attacks

3. Signatures are chain-specific - prevents cross-chain attacks

4. Use ReentrancyGuard for functions that handle value transfers

5. Set appropriate MAX_AGE based on your security requirements