Architecture

How HumanGate works under the hood.

System Overview

HumanGate is a provider-agnostic human verification middleware for Starknet dApps. Users verify their humanity once on the HumanGate Portal, the attestation is stored on Starknet, and any dApp can read it from the contract for free.

How It Works

system-architecture

┌──────────────────┐                              ┌─────────────────┐
│                  │  1. User verifies via          │                 │
│  HumanGate       │     World ID                   │    Starknet     │
│  Portal          │                                │  (on-chain      │
│  (humangate.xyz) │  2. Submits attestation ──────▶│   registry)     │
│                  │     to chain (pays ~$0.01 gas) │                 │
└──────────────────┘                                └────────▲────────┘
                                                             │
┌──────────────────┐          free reads                     │
│                  │  isHuman(), isEligible()                 │
│  Your dApp       │─────────────────────────────────────────┘
│  (uses SDK)      │
└──────────────────┘

What You Use

Component	What It Does
@humangate/sdk	TypeScript SDK. Read attestation data from Starknet — `isHuman()`, `isEligible()`, `hasConsumed()`. Free, no API keys.
HumanGateRegistry	Cairo smart contract on Starknet Mainnet. Stores attestations, verifies signatures, manages scoped actions. Your contract can call it directly.
Portal	Where users verify. Link your users here — once verified, your dApp can check their status on-chain.

Verification Flow

User connects wallet — On the HumanGate Portal, the user connects their Starknet wallet (ArgentX or Braavos).
World ID verification — User scans a QR code with their Worldcoin app. World ID generates a zero-knowledge proof.
Attestation signed & submitted — The proof is validated, attestation data is signed, and the user submits it to the on-chain registry with their wallet (~$0.01 gas).
Contract verifies and stores — The contract verifies the ECDSA signature, checks the nullifier hasn't been used, and stores the attestation.
Any dApp reads for free — Any Starknet contract or frontend calls isHuman(), isEligible(), or getAttestation() to check verification status. Free, no gas for reads.

Security Model

Nullifier Hashes

Each World ID verification produces a unique nullifier hash derived from the user's identity and the action. This hash is stored on-chain. If the same person tries to register again (even with a different wallet), the duplicate nullifier will be rejected. One human = one attestation.

Scoped Actions

Actions are scoped using Poseidon hashes. Each scope is independent: consuming an attestation for "airdrop-claim" does not affect eligibility for "governance-vote". One verification, many actions.

User-Paid Gas Model

The user pays gas for their own on-chain registration (~$0.01 on Starknet). This makes the protocol free to operate at any scale — zero infrastructure costs for attestation storage.

For integration details, see the Getting Started guide.