Skip to main content

Technical Overview

v2.0

This document describes the HumanPass protocol from a technical perspective. It presents the underlying cryptographic components and specifies the building blocks used to construct the HumanPass cross-chain human identity and reputation framework.

The HumanPass protocol is meticulously designed to serve as a cross-chain identity verification system, leveraging World Chain's Proof of Personhood as its foundation. The protocol extends this verification across multiple blockchain environments through a sophisticated system of Soulbound Tokens (SBTs) and cryptographic proofs, ensuring that a user's verified human status is both portable and tamper-resistant.

HumanPass operates through a multi-layered architecture that combines on-chain verification with off-chain identity management, allowing the protocol to provide robust identity verification while maintaining privacy and scalability. This design ensures flexibility in identity verification scenarios across different blockchain networks without compromising security or user experience.

Overviewโ€‹

While traditional identity verification systems often operate within closed ecosystems, they don't allow users to prove their human identity across different blockchain environments. Existing solutions either require unwanted trust assumptions or platform-specific implementations, effectively siloing users' identity verification to specific networks. The HumanPass protocol addresses this issue by extending World Chain's Proof of Personhood into a cross-chain verification system, enabling secure identity sharing without compromising privacy or requiring redundant verification processes.

The HumanPass protocol involves three key components: the World ID verification system, the Soulbound Token (SBT) infrastructure, and the Human Identity Score (HIS) framework. Departing from conventional methods, HumanPass utilizes a user's World ID verification to establish their human uniqueness, then issues non-transferable SBTs to their connected wallets across different chains. These SBTs serve as on-chain attestations of the user's verified status, which can be queried by decentralized applications (dApps) to confirm the user's humanity.

To actualize this architecture, we integrate World ID verification, EVM-compatible smart contracts, and cross-chain identity binding technologies.

We have designed and implemented the HumanPass protocol with two verification levels:

  1. Device Verification: The base level of verification using World ID's device verification.
  2. Orb Verification: The highest level of verification using World ID's Orb verification.

These two levels form a hierarchical verification system, providing HumanPass with the flexibility to support different security requirements across various applications. The protocol operates efficiently across both verification levels, with applications able to specify their minimum required verification level.

Smart Contract Architectureโ€‹

The HumanPass protocol is built on a robust smart contract architecture that ensures the integrity and security of the identity verification system. The core contracts include:

HumanBoundToken Contractsโ€‹

The HumanPass protocol implements two separate Soulbound Token (SBT) contracts for different verification levels:

  1. HumanBoundTokenDeviceUpgradeable: Issues SBTs for users with World ID device verification
  2. HumanBoundTokenOrbUpgradeable: Issues SBTs for users with World ID Orb verification

Both contracts extend the ERC721 standard but implement transfer restrictions to make the tokens non-transferable (soulbound). The contracts include:

  • Soul Binding Mechanism: Overrides the _update function to prevent transfers between addresses
  • Server-Signed Minting: Requires cryptographic signatures from an authorized server to mint tokens
  • EIP-712 Compliant Signatures: Uses typed structured data signing for secure minting and burning operations
  • Nonce Protection: Implements one-time-use nonces to prevent replay attacks
  • UUPS Upgradeability: Allows for contract upgrades while preserving state and token ownership

The minting process is secured through a server-side signature mechanism:

function mint(MintData calldata data) external whenNotPaused {
    require(block.timestamp <= data.deadline, "Signature expired");
    require(!usedServerNonces[data.nonce], "Nonce already used");
    require(data.to != address(0), "Invalid recipient");
    require(data.tokenId > 0, "Invalid token ID");
    require(_userTokenIds[data.to] == 0, "User already has a token");

    // Verify server signature
    bytes32 structHash = keccak256(
        abi.encode(
            MINT_TYPEHASH,
            data.to,
            data.tokenId,
            keccak256(bytes(data.tokenURI)),
            data.deadline,
            data.nonce
        )
    );
    bytes32 digest = _hashTypedDataV4(structHash);
    address signer = ECDSA.recover(digest, data.serverSignature);
    require(signer == serverSigner, "Invalid server signature");

    // Mark nonce as used
    usedServerNonces[data.nonce] = true;

    // Mint token
    _safeMint(data.to, data.tokenId);
    _tokenURIs[data.tokenId] = data.tokenURI;
    _tokenOwners[data.tokenId] = data.to;
    _userTokenIds[data.to] = data.tokenId; // Track user's token ID
    _totalSupply++;

    emit TokenMinted(data.to, data.tokenId, data.tokenURI);
    emit TokenMintedWithDetails(
        data.to,
        data.tokenId,
        data.tokenURI,
        block.timestamp,
        _totalSupply
    );
}

HumanVerifier Contractโ€‹

The HumanVerifierUpgradeable contract serves as a central verification hub that interfaces with both HumanBoundToken contracts. It provides a unified API for dApps to verify a user's human status across different verification levels:

  • Hierarchical Verification: Implements a verification hierarchy where Orb verification satisfies both "orb" and "device" requirements, while device verification only satisfies "device" requirements
  • Unified Query Interface: Provides a single isHuman function that accepts a verification level parameter
  • Verification Status Queries: Offers functions to check verification status and determine the highest verification level a user has achieved
function isHuman(address user, string calldata minVerification) external view returns (bool) {
    // Check orb verification first (highest level)
    bool hasOrb = address(orbToken) != address(0) && orbToken.isHuman(user);

    // Check device verification
    bool hasDevice = address(deviceToken) != address(0) && deviceToken.isHuman(user);

    // Determine verification level based on minVerification parameter
    if (keccak256(bytes(minVerification)) == keccak256(bytes("orb"))) {
        // For orb verification, only orb token qualifies
        return hasOrb;
    } else if (keccak256(bytes(minVerification)) == keccak256(bytes("device"))) {
        // For device verification, either device or orb token qualifies
        return hasDevice || hasOrb;
    }

    // Invalid verification level
    return false;
}

Backend Infrastructureโ€‹

The HumanPass backend infrastructure is built with a microservices architecture that handles user verification, wallet connections, social account linking, and point management. The system is designed for scalability, security, and cross-chain compatibility.

API Servicesโ€‹

The API services are implemented as serverless functions that handle various aspects of the HumanPass ecosystem:

  1. Authentication Service: Manages World ID verification and session management
  2. Wallet Connection Service: Handles wallet linking, proof generation, and SBT minting
  3. Social Connection Service: Manages social account verification (Twitter, Telegram, etc.)
  4. Points Service: Tracks and updates Human Points based on user activity

The API services implement robust security measures:

  • JWT Authentication: Secures API endpoints with JSON Web Tokens
  • Cryptographic Proofs: Generates and verifies cryptographic proofs for wallet connections
  • OAuth Integration: Securely connects with social platforms via OAuth flows
  • Rate Limiting: Prevents abuse through request rate limiting

Database Schemaโ€‹

The HumanPass database uses a relational schema to track user identity, connections, and points:

  1. Users Table: Stores basic user information and verification level
  2. Wallet Connections: Tracks wallet addresses linked to users
  3. Social Connections: Records verified social accounts
  4. Points: Maintains a ledger of point transactions and balances

The database schema implements several key features:

  • Referential Integrity: Ensures data consistency across related tables
  • Timestamp Tracking: Records creation and modification times for audit purposes
  • Soft Deletion: Supports revocation without destroying historical data
  • JSON Metadata: Stores flexible metadata for extensibility

Cross-Chain Identity Bindingโ€‹

One of HumanPass's key innovations is its cross-chain identity binding mechanism, which allows a user's verified human status to be recognized across multiple blockchain networks.

Wallet Linking Processโ€‹

The wallet linking process involves several cryptographic steps:

  1. User Authentication: The user authenticates with World ID
  2. Wallet Connection: The user connects their wallet and signs a message to prove ownership
  3. Server Verification: The server verifies the signature and World ID proof
  4. SBT Minting: The server generates a signature for minting an SBT on the target chain
  5. On-Chain Verification: The SBT is minted to the user's wallet, creating an on-chain attestation of their verified status

Multi-Chain Supportโ€‹

HumanPass is designed to support multiple blockchain networks:

  1. EVM Compatibility: The initial implementation supports all EVM-compatible chains
  2. Chain-Specific Deployment: SBT contracts are deployed to each supported chain
  3. Unified Verification: The backend tracks verification across all chains
  4. Chain Addition: New chains can be added through a standardized deployment process

Human Identity Score (HIS)โ€‹

The Human Identity Score (HIS) is a reputation framework that quantifies a user's verified identity and ecosystem engagement. It is calculated through a sophisticated algorithm that considers various factors:

Score Calculationโ€‹

The HIS is calculated using a weighted model:

(1) \quad R_{raw} = \sum_{i \in A} W_i S_i
(2) \quad C = \frac{\sum_{i \in A} W_i}{\sum_i W_i}
(3) \quad HIS_t = (R_{raw} \times C^{\alpha}) + \beta_t

Where:

  • Sแตข is the score of source i
  • Wแตข is its weight
  • A is the verified set
  • ฮฑ controls the incentive for completeness
  • ฮฒ_t represents the weekly bonus multiplier for early or active users

Point Systemโ€‹

The point system translates the HIS into Human Points that accumulate over time:

  1. Weekly Updates: Points are calculated and distributed weekly
  2. Verification Levels: Higher verification levels earn more points
  3. Social Connections: Linked social accounts contribute to point totals
  4. Activity Bonuses: Regular engagement with the ecosystem earns additional points
  5. Early Adopter Rewards: Early users receive multipliers to their point earnings

Developer Integrationโ€‹

HumanPass provides a comprehensive JavaScript SDK for developers to integrate human verification into their applications.

JS-SDK Architectureโ€‹

The SDK is organized into several modules:

  1. Core Module: Handles initialization, configuration, and communication
  2. Verification Module: Manages World ID verification and status checks
  3. Wallet Module: Handles wallet connections and SBT verification
  4. Social Module: Manages social account verification
  5. HIS Module: Provides access to Human Identity Score data

Integration Flowโ€‹

Developers can integrate HumanPass through a straightforward process:

  1. SDK Initialization: Configure the SDK with application credentials
  2. Verification Request: Prompt users to verify their human status
  3. Status Checking: Query verification status for access control
  4. On-Chain Verification: Optionally verify SBTs directly on-chain
// Example SDK initialization
const humanpass = new HumanPassSDK({
  appId: "your-app-id",
  environment: "production",
});

// Check if user is verified as human
const isHuman = await humanpass.verification.isHuman("device");

// Access Human Identity Score
const hisData = await humanpass.his.getUserScore();

HPFP NFT Systemโ€‹

The Human Profile Picture (HPFP) NFT system extends the HumanPass ecosystem by providing verified users with customizable profile pictures that represent their verified human status.

Technical Implementationโ€‹

The HPFP system is built on several technical components:

  1. Trait-Based Composition: Dynamic generation of profile images based on user-selected traits
  2. On-Chain Verification: Each HPFP is linked to a verified HumanPass identity
  3. Metadata Standards: Following established NFT metadata standards for compatibility
  4. Points Integration: Users spend accumulated Human Points to unlock traits
  5. Composable Metadata: Efficient on-chain representation of trait combinations

Architectureโ€‹

The HPFP system architecture includes:

  1. Trait Registry: Smart contract that manages available traits and their costs
  2. HPFP Token: ERC-721 contract that represents the user's profile picture
  3. Metadata Service: Off-chain service that generates and serves NFT metadata
  4. Rendering Engine: Client-side component that visualizes the NFT based on traits

Security Considerationsโ€‹

The HumanPass protocol implements multiple security measures to protect user identity and prevent fraud:

  1. Soulbound Tokens: Non-transferable tokens prevent identity trading or theft
  2. Server-Signed Transactions: Cryptographic signatures ensure only authorized operations
  3. Nonce Protection: One-time-use nonces prevent replay attacks
  4. Upgradeability: UUPS upgradeability pattern allows security patches without disruption
  5. Timelock Mechanisms: Signature expiration prevents delayed execution attacks

Privacy Modelโ€‹

HumanPass follows a privacy-first approach to identity verification:

  1. Minimal Data Collection: Only cryptographic proofs are stored, not personal data
  2. Zero-Knowledge Proofs: World ID's zero-knowledge proofs verify uniqueness without revealing identity
  3. Hashed Identifiers: Social identifiers are stored as hashed values
  4. Selective Disclosure: Users control which aspects of their identity to share
  5. Revocation Rights: Users can revoke connections and delete their data

Summaryโ€‹

The HumanPass protocol distinguishes itself by combining advanced cryptographic techniques to achieve secure, efficient, and privacy-preserving identity verification across multiple blockchain environments. By extending World ID's Proof of Personhood through Soulbound Tokens and a robust backend infrastructure, HumanPass effectively addresses both security and usability challenges.

Its hierarchical verification system, which includes both Device and Orb verification levels, allows the protocol to adapt to various security requirements without compromising efficiency or user experience. The use of non-transferable SBTs ensures that identity verification remains tied to the original user, preventing identity transfer or theft.

The Human Identity Score (HIS) framework adds a reputation layer to the identity system, rewarding users for verification completeness and ecosystem engagement. This creates positive incentives for users to maintain and enhance their verified status, contributing to the overall security and value of the ecosystem.

Optimized smart contracts, efficient backend services, and a comprehensive SDK make HumanPass highly scalable, ensuring that the protocol remains practical for real-world applications without sacrificing security or speed. As the protocol continues to evolve, additional chains and verification methods will be supported, further enhancing its utility as a cross-chain human identity layer.