IVerificationOracle

Verification Oracle interface: query user credentials on-chain, verify claims, and integrate proof-of-humanity into smart contract logic.ge describes the Verification Oracle Interface

Contract address

Testnet

0x67c0A5cA2Fb19E8E0Ff008d727aff5f128b00E09

Mainnet

0x8D71D8bD47860bd0381b272AE42162c3692c4F3a

Overview

IHumanityVerificationOracle provides the core verification functionality for Humanity Protocol. It enables DApps to request human verification for users, validates signatures, manages verification requests via EAS attestations, coordinates fee payments through FeeEscrow, and notifies DApps of results via callbacks.

Core Concepts

Concept

Description

Request Lifecycle

Each verification request transitions through states: Pending → Done or Cancelled

EAS Integration

Requests and results are recorded as EAS attestations for auditability and on-chain proof

User Consent

Users must sign a permission message off-chain before verification can be requested

DApp Callback

Upon completion, the Oracle notifies the DApp via onVerificationComplete()

Request Status

enum RequestStatus {
    Pending,    // Verification in progress
    Done,       // Verification completed
    Cancelled   // Request cancelled or revoked
}

Verification Request Structure

struct VerificationRequest {
    bytes32 attestationUID;      // EAS attestation UID for this request
    address requester;           // DApp that requested verification
    address user;                // User being verified
    address attester;            // Address that created the attestation
    uint256 expirationTime;      // When the verification expires
    uint256 revocationTime;      // When revoked (0 if not revoked)
    string[] requiredClaims;     // Claims required for verification
    uint256 maxAge;              // Maximum age of verification data
    uint256 fee;                 // Fee paid for verification
    address callbackContract;    // Contract to notify on completion
    RequestStatus status;        // Current status
    uint256 timestamp;           // When request was created
}

Verification Flow

1. PREPARE

DApp determines the requiredClaims[] array and maxAge parameter for the verification request.

2. GET PERMISSION HASH

DApp calls getPermissionMessageHash(user, dapp, claims, maxAge, callbackContract) to generate the message hash that the user must sign.

3. USER SIGNS

User signs the messageHash off-chain using their wallet, producing userSignature.

4. REQUEST VERIFICATION

DApp calls requestVerification(dapp, user, claims, maxAge, callbackContract, signature). The Oracle validates the signature, reserves the fee via FeeEscrow.reserveForRequest(), and returns a requestId (bytes32).

5. ORACLE PROCESSES

The Oracle performs off-chain verification of the user's humanity credentials and creates an EAS attestation for the result.

6. SUBMIT RESULT

Oracle calls submitVerificationResult(requestUID, verified, ...). This settles fees via FeeEscrow.settleRequest() and emits a VerificationCompleted event.

7. CALLBACK

Oracle calls the DApp's onVerificationComplete(requestId, user, verified, attestationUID) callback. The DApp grants or denies access based on the verified boolean.

Interface

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

interface IHumanityVerificationOracle is IHumanityVerificationOracleErrors {
    // Request Management
    function requestVerification(
        address dapp,
        address user,
        string[] memory requiredClaims,
        uint256 maxAge,
        address callbackContract,
        bytes memory userSignature
    ) external returns (bytes32 requestId);

    function submitVerificationResult(
        bytes32 requestUID,
        bool verified,
        uint256 expiresAt,
        string[] memory usedIssuers,
        string[] memory usedCategories
    ) external;

    function revokeVerificationRequest(bytes32 attestationUID) external;

    // Verification Queries
    function isUserVerified(
        address user,
        string[] memory requiredClaims,
        uint256 maxAge
    ) external view returns (bool verified, bytes32 attestationUID, uint256 expiresAt);

    function getRequest(bytes32 requestUID) external view returns (VerificationRequest memory);
    function getResult(bytes32 resultUID) external view returns (...);
    function getUserRequests(address user) external view returns (bytes32[] memory);
    function resultToRequest(bytes32 resultUID) external view returns (bytes32 requestUID);

    // Signature Helpers
    function getPermissionMessageHash(
        address user,
        address dapp,
        string[] memory requiredClaims,
        uint256 maxAge,
        address callbackContract
    ) external view returns (bytes32);

    function getUserNonce(address user) external view returns (uint256);

    // Attestation Decoders
    function decodeRequestAttestation(bytes memory attestationData) external pure returns (...);
    function decodeResultAttestation(bytes memory attestationData) external pure returns (...);

    // Admin Functions
    function updateVerificationFee(uint256 _newFee) external;
    function updateTreasuryAddress(address _newTreasury) external;
    function updateEAS(address _newEAS) external;
    function updateSchemas(bytes32 _newRequestSchemaUID, bytes32 _newResultSchemaUID) external;
    function pause() external;
    function unpause() external;
}

Functions

Request Management

`requestVerification(...)`

Request verification for a user. Requires a valid user signature.

function requestVerification(
    address dapp,
    address user,
    string[] memory requiredClaims,
    uint256 maxAge,
    address callbackContract,
    bytes memory userSignature
) external returns (bytes32 requestId);

Parameter

Type

Description

dapp

address

Address of the DApp requesting verification

user

address

Address of the user to verify

requiredClaims

string[]

Array of claim types required (e.g., ["humanity_identity"])

maxAge

uint256

Maximum age of verification data in seconds

callbackContract

address

Contract to receive verification callback

userSignature

bytes

User’s signature authorizing the verification

Returns: requestId - The unique identifier (bytes32) for this verification request

Reverts:

UnauthorizedRequest if signature is invalid
NoClaimsSpecified if requiredClaims is empty
InsufficientAvailableBalance (from FeeEscrow) if DApp hasn’t pre-funded

Emits: VerificationRequested(bytes32 indexed attestationUID, address indexed requester, address indexed user, string[] requiredClaims, uint256 fee)

`submitVerificationResult(...)`

Submit the result of a verification request. Called by the Oracle after processing.

function submitVerificationResult(
    bytes32 requestUID,
    bool verified,
    uint256 expiresAt,
    string[] memory usedIssuers,
    string[] memory usedCategories
) external;

Parameter

Type

Description

requestUID

bytes32

The request to submit results for

verified

bool

Whether verification succeeded

expiresAt

uint256

Timestamp when this verification expires

usedIssuers

string[]

DIDs of issuers whose credentials were used

usedCategories

string[]

Categories of claims that were verified

Emits: VerificationCompleted(bytes32 indexed requestUID, bool verified, bytes32 resultUID)

`revokeVerificationRequest(bytes32 attestationUID)`

Revoke a verification request or result.

function revokeVerificationRequest(bytes32 attestationUID) external;

Reverts:

RequestNotFound if request doesn’t exist
RequestAlreadyRevoked if already revoked
NotAuthorizedToRevoke if caller lacks permission

Emits: VerificationRequestRevoked(address indexed revoker, bytes32 indexed requestUID, uint256 revokedAt)

Verification Queries

`isUserVerified(...)`

Check if a user has a valid verification matching the specified criteria.

function isUserVerified(
    address user,
    string[] memory requiredClaims,
    uint256 maxAge
) external view returns (
    bool verified,
    bytes32 attestationUID,
    uint256 expiresAt
);

Parameter

Type

Description

user

address

Address of the user to check

requiredClaims

string[]

Claims that must be verified

maxAge

uint256

Maximum age of verification in seconds

Returns:

verified - Whether user has valid verification
attestationUID - UID of the verification attestation (if verified)
expiresAt - When the verification expires

`getRequest(bytes32 requestUID)`

Get full details of a verification request.

function getRequest(bytes32 requestUID) external view returns (VerificationRequest memory request);

`getResult(bytes32 resultUID)`

Get details of a verification result.

function getResult(bytes32 resultUID) external view returns (
    address user,
    address requester,
    bytes32 requestUID,
    bool verified,
    uint256 expiresAt,
    uint256 revocationTime,
    string[] memory usedIssuers,
    string[] memory usedCategories
);

`getUserRequests(address user)`

Get all verification request UIDs for a user.

function getUserRequests(address user) external view returns (bytes32[] memory);

`resultToRequest(bytes32 resultUID)`

Map a result UID back to its original request UID.

function resultToRequest(bytes32 resultUID) external view returns (bytes32 requestUID);

Signature Helpers

`getPermissionMessageHash(...)`

Get the message hash that a user must sign to authorize verification.

function getPermissionMessageHash(
    address user,
    address dapp,
    string[] memory requiredClaims,
    uint256 maxAge,
    address callbackContract
) external view returns (bytes32);

Important: The signature must be computed over the exact tuple (user, dapp, requiredClaims[], maxAge, callbackContract, currentUserNonce). Any mismatch causes UnauthorizedRequest.

`getUserNonce(address user)`

Get the current nonce for a user. The nonce is incremented after each verification request.

function getUserNonce(address user) external view returns (uint256);

Attestation Decoders

`decodeRequestAttestation(bytes memory attestationData)`

Decode EAS-encoded request attestation data.

function decodeRequestAttestation(bytes memory attestationData) external pure returns (
    address requester,
    address user,
    string[] memory requiredClaims,
    uint256 maxAge,
    uint256 fee,
    address callbackContract
);

`decodeResultAttestation(bytes memory attestationData)`

Decode EAS-encoded result attestation data.

function decodeResultAttestation(bytes memory attestationData) external pure returns (
    bytes32 requestUID,
    bool verified,
    uint256 expiresAt,
    string[] memory usedIssuers,
    string[] memory usedCategories
);

Admin Functions

`updateVerificationFee(uint256 _newFee)`

Update the fee required for verification requests.

function updateVerificationFee(uint256 _newFee) external;

Emits: VerificationFeeUpdated(uint256 newFee)

`updateTreasuryAddress(address _newTreasury)`

Update the treasury address for fee collection.

function updateTreasuryAddress(address _newTreasury) external;

Emits: TreasuryAddressUpdated(address newTreasury)

`updateEAS(address _newEAS)`

Update the EAS contract address.

function updateEAS(address _newEAS) external;

Emits: EASAddressUpdated(address newEAS)

`updateSchemas(bytes32 _newRequestSchemaUID, bytes32 _newResultSchemaUID)`

Update the EAS schema UIDs for requests and results.

function updateSchemas(bytes32 _newRequestSchemaUID, bytes32 _newResultSchemaUID) external;

Emits: SchemasUpdated(bytes32 oldRequestSchemaUID, bytes32 newRequestSchemaUID, bytes32 oldResultSchemaUID, bytes32 newResultSchemaUID)

`pause()` / `unpause()`

Pause or unpause contract operations.

function pause() external;
function unpause() external;

DApp Callback Interface

DApps must implement IHumanityVerificationCallback to receive verification results.

interface IHumanityVerificationCallback {
    function onVerificationComplete(
        bytes32 requestId,
        address user,
        bool verified,
        bytes32 attestationUID
    ) external;
}

Parameter

Type

Description

requestId

bytes32

The verification request ID

user

address

The user who was verified

verified

bool

Whether verification succeeded

attestationUID

bytes32

EAS attestation UID for the result

Events

Lifecycle Events

Event

Description

VerificationRequested(bytes32 indexed attestationUID, address indexed requester, address indexed user, string[] requiredClaims, uint256 fee)

New verification request created

VerificationCompleted(bytes32 indexed requestUID, bool verified, bytes32 resultUID)

Verification completed

VerificationRequestRevoked(address indexed revoker, bytes32 indexed requestUID, uint256 revokedAt)

Request revoked

VerificationResultRevoked(address indexed revoker, bytes32 indexed resultUID, uint256 revokedAt)

Result revoked

Callback Events

Event

Description

CallbackErrorString(bytes32 indexed requestUID, address callbackContract, string reason)

Callback failed with revert string

CallbackErrorPanic(bytes32 indexed requestUID, address callbackContract, uint256 errorCode)

Callback failed with panic

CallbackErrorLowLevel(bytes32 indexed requestUID, address callbackContract, bytes lowLevelData)

Callback failed with low-level error

Fee Events

Event

Description

FeeCollected(address indexed dapp, uint256 feePaid, uint256 debtPaid)

Fee collected from DApp

FeesDistributed(address dapp, bytes32 verificationUID, address[] issuerAddresses, uint256[] issuersFee, uint256 stakingFee, uint256 proofFee, uint256 totalFee)

Fees distributed to stakeholders

FeeVerifierPaid(address indexed dapp, uint256 fee, uint256 debt)

Verifier paid

FeesWithdrawn(address indexed recipient, uint256 amount)

Fees withdrawn

DebtUpdated(address indexed dapp, uint256 oldDebt, uint256 newDebt)

DApp debt updated

Configuration Events

Event

Description

VerificationFeeUpdated(uint256 newFee)

Fee amount changed

TreasuryAddressUpdated(address newTreasury)

Treasury address changed

EASAddressUpdated(address newEAS)

EAS contract address changed

FeeEscrowUpdated(address indexed oldEscrow, address indexed newEscrow)

FeeEscrow address changed

SchemasUpdated(...)

EAS schemas changed

Errors

Configuration Errors

Error

Description

AlreadyProcessing()

Request is already being processed

InvalidAddress(string param)

Provided address is invalid

SchemasAlreadyInitialized()

Schemas already set

SchemasNotInitialized()

Schemas not yet configured

InvalidSchema(string schemaType)

Invalid schema provided

Request Errors

Error

Description

InvalidUser()

User address is invalid

InvalidRequest()

Request data is invalid

InvalidValue(string param)

Parameter value is invalid

NoClaimsSpecified()

Required claims array is empty

InsufficientVerificationFee(uint256 required, uint256 provided)

Fee provided is insufficient

RequestNotFound(bytes32 requestUID)

Request doesn’t exist

RequestExpired(bytes32 requestUID)

Request has expired

RequestAlreadyRevoked(bytes32 requestUID)

Request was already revoked

BatchSizeExceedsLimit(uint256 size, uint256 maxSize)

Batch too large

MismatchedArrayLengths()

Array parameters have different lengths

DebtLimitExceeded(uint256 newDebt, uint256 maxDebtAllowance)

DApp debt would exceed limit

Authorization Errors

Error

Description

NotAuthorizedToRevoke(address caller)

Caller cannot revoke this request

UnauthorizedUpgrade(address caller)

Caller cannot upgrade contract

UnauthorizedRequest(address expectedSigner, address actualSigner)

Signature doesn’t match expected signer

Transfer Errors

Error

Description

NoFeesToWithdraw()

No fees available for withdrawal

RefundFailed(address recipient, uint256 amount)

Refund transfer failed

TreasuryTransferFailed(address treasury, uint256 amount)

Treasury transfer failed

LockFeeFailed(address issuer)

Failed to lock fee for issuer

Integration Example

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

import "./interfaces/verificationOracle/IVerificationOracle.sol";
import "./interfaces/feeEscrow/IFeeEscrow.sol";

contract MyVerifiedDApp is IHumanityVerificationCallback {
    IHumanityVerificationOracle public oracle;
    IFeeEscrow public feeEscrow;

    mapping(address => bool) public verifiedUsers;
    mapping(bytes32 => address) public pendingRequests;

    string[] public requiredClaims = ["humanity_identity"];
    uint256 public constant MAX_VERIFICATION_AGE = 30 days;

    constructor(address _oracle, address _feeEscrow) {
        oracle = IHumanityVerificationOracle(_oracle);
        feeEscrow = IFeeEscrow(_feeEscrow);
    }

    // Step 1: Get the message hash for user to sign
    function getPermissionHash(address user) external view returns (bytes32) {
        return oracle.getPermissionMessageHash(
            user,
            address(this),
            requiredClaims,
            MAX_VERIFICATION_AGE,
            address(this)
        );
    }

    // Step 2: Request verification with user's signature
    function requestVerification(
        address user,
        bytes memory userSignature
    ) external returns (bytes32 requestId) {
        // Ensure we have funds in escrow
        require(
            feeEscrow.getAvailable(address(this)) > 0,
            "Insufficient escrow balance"
        );

        requestId = oracle.requestVerification(
            address(this),
            user,
            requiredClaims,
            MAX_VERIFICATION_AGE,
            address(this),
            userSignature
        );

        pendingRequests[requestId] = user;
    }

    // Step 3: Receive callback from Oracle
    function onVerificationComplete(
        bytes32 requestId,
        address user,
        bool verified,
        bytes32 attestationUID
    ) external override {
        require(msg.sender == address(oracle), "Only oracle can callback");

        if (verified) {
            verifiedUsers[user] = true;
            // Grant access, mint tokens, etc.
        }

        delete pendingRequests[requestId];
    }

    // Check if user is already verified
    function checkVerification(address user) external view returns (bool) {
        (bool verified, , ) = oracle.isUserVerified(
            user,
            requiredClaims,
            MAX_VERIFICATION_AGE
        );
        return verified;
    }

    // Fund the escrow
    function fundEscrow() external payable {
        feeEscrow.deposit{value: msg.value}();
    }
}

Integration Tips

Signature Validation: The userSignature must be computed over the exact tuple (user, dapp, requiredClaims[], maxAge, callbackContract, currentUserNonce). Any mismatch causes UnauthorizedRequest and reverts.
FeeEscrow Configuration: Ensure FeeEscrow.verificationOracle is configured to this Oracle instance. Otherwise, reserveForRequest/settleRequest will revert with UnauthorizedCaller.
Insufficient Balance Error: If you see a revert with data starting 0x6701c6f6, it decodes to InsufficientAvailableBalance(dapp, required, available) from IFeeEscrow. Pre-fund FeeEscrow via deposit or lower the verificationFee (admin).
Callback Handling: Treat callback execution as untrusted. Handle errors gracefully and consider timeouts/compensation logic if callbacks revert.
Upgrades (UUPS): Always append new state variables at the end when upgrading. Do not increase __gap; reduce it by the number of slots you add.
Nonce Management: Each verification request increments the user’s nonce. If a signature fails, check that you’re using the current nonce from getUserNonce(user).

PreviousIFeeEscrow NextDeveloper Guides & Tutorials

Last updated 9 hours ago

Good night

hashtagContract address

hashtagOverview

hashtagCore Concepts

hashtagRequest Status

hashtagVerification Request Structure

hashtagVerification Flow

hashtag1. PREPARE

hashtag2. GET PERMISSION HASH

hashtag3. USER SIGNS

hashtag4. REQUEST VERIFICATION

hashtag5. ORACLE PROCESSES

hashtag6. SUBMIT RESULT

hashtag7. CALLBACK

hashtagInterface

hashtagFunctions

hashtagRequest Management

hashtagrequestVerification(...)

hashtagsubmitVerificationResult(...)

hashtagrevokeVerificationRequest(bytes32 attestationUID)

hashtagVerification Queries

hashtagisUserVerified(...)

hashtaggetRequest(bytes32 requestUID)

hashtaggetResult(bytes32 resultUID)

hashtaggetUserRequests(address user)

hashtagresultToRequest(bytes32 resultUID)

hashtagSignature Helpers

hashtaggetPermissionMessageHash(...)

hashtaggetUserNonce(address user)

hashtagAttestation Decoders

hashtagdecodeRequestAttestation(bytes memory attestationData)

hashtagdecodeResultAttestation(bytes memory attestationData)

hashtagAdmin Functions

hashtagupdateVerificationFee(uint256 _newFee)

hashtagupdateTreasuryAddress(address _newTreasury)

hashtagupdateEAS(address _newEAS)

hashtagupdateSchemas(bytes32 _newRequestSchemaUID, bytes32 _newResultSchemaUID)

hashtagpause() / unpause()

hashtagDApp Callback Interface

hashtagEvents

hashtagLifecycle Events

hashtagCallback Events

hashtagFee Events

hashtagConfiguration Events

hashtagErrors

hashtagConfiguration Errors

hashtagRequest Errors

hashtagAuthorization Errors

hashtagTransfer Errors

hashtagIntegration Example

hashtagIntegration Tips

Contract address

Overview

Core Concepts

Request Status

Verification Request Structure

Verification Flow

1. PREPARE

2. GET PERMISSION HASH

3. USER SIGNS

4. REQUEST VERIFICATION

5. ORACLE PROCESSES

6. SUBMIT RESULT

7. CALLBACK

Interface

Functions

Request Management

`requestVerification(...)`

`submitVerificationResult(...)`

`revokeVerificationRequest(bytes32 attestationUID)`

Verification Queries

`isUserVerified(...)`

`getRequest(bytes32 requestUID)`

`getResult(bytes32 resultUID)`

`getUserRequests(address user)`

`resultToRequest(bytes32 resultUID)`

Signature Helpers

`getPermissionMessageHash(...)`

`getUserNonce(address user)`

Attestation Decoders

`decodeRequestAttestation(bytes memory attestationData)`

`decodeResultAttestation(bytes memory attestationData)`

Admin Functions

`updateVerificationFee(uint256 _newFee)`

`updateTreasuryAddress(address _newTreasury)`

`updateEAS(address _newEAS)`

`updateSchemas(bytes32 _newRequestSchemaUID, bytes32 _newResultSchemaUID)`

`pause()` / `unpause()`

DApp Callback Interface

Events

Lifecycle Events

Callback Events

Fee Events

Configuration Events

Errors

Configuration Errors

Request Errors

Authorization Errors

Transfer Errors

Integration Example

Integration Tips