Skip to main content

System Overview

This document describes how Hadinet Africa works under the hood. It is intended for technically-minded users who want to understand the system design.

High-Level Data Flow​

User (Browser)
    |
    v
Frontend (Next.js + Privy Wallet Auth)
    |
    v
Attestor Service (TEE)
    |
    |---> KYC Provider (Smile ID / Plaid)
    |         via zkFetch TLS tunnel
    |         generates 14 ZK proofs per request
    |
    |---> IPFS (Pinata) -- encrypted document storage
    |
    +---> Cartesi Rollup (RISC-V Linux VM)
              |
              +---> SQLite deterministic database
                        |
                        +---> Arbitrum L2 (settlement layer)

Components​

Frontend​

The user-facing application is a Next.js progressive web app (PWA). It handles:

  • Wallet connection via Privy — supports MetaMask, WalletConnect, email, and social login
  • DID generation — derives a did:key identifier from the user's wallet using secp256k1 cryptography
  • Identity dashboard — displays verification status, history, and document vault
  • KYC flow — guides users through provider selection, authorization, and result display
  • Document management — upload, view, and download encrypted documents

The frontend never handles raw personal data. It communicates with the attestor service over authenticated API calls.

Attestor Service​

The attestor runs in a Trusted Execution Environment (TEE) and acts as the bridge between the user and the blockchain. It:

  1. Orchestrates KYC verification — manages sessions with providers (Smile ID, Plaid)
  2. Creates ZK proofs — uses Reclaim Protocol's zkFetch to establish a TLS tunnel with the KYC provider, generating cryptographic proofs that the provider returned specific data without revealing what that data was
  3. Encrypts documents — applies AES-256-GCM encryption before uploading to IPFS
  4. Submits to Cartesi — sends only non-PII metadata (provider, country, verification level) along with the ZK proof to the rollup

The attestor is the only component that briefly sees personal data during KYC verification. It does not persist this data — it processes it in-memory within the TEE, creates the proof, and discards the original data.

Cartesi Rollup​

Cartesi provides a full Linux virtual machine running on RISC-V architecture inside the blockchain. This is where Hadinet's verified state lives. The rollup:

  • Runs SQLite for deterministic data storage
  • Stores identity attestations — verification records containing only non-PII metadata
  • Stores document vault metadata — file names, types, and IPFS references (not the documents themselves)
  • Manages access control — who can read which attestations
  • Supports discovery queries — allowing services to verify a user's status

All data in the Cartesi rollup is deterministic, meaning every validator node arrives at exactly the same state. This makes it fraud-provable via Arbitrum.

Settlement Layer (Arbitrum)​

Arbitrum Sepolia (an Ethereum L2) provides:

  • Finality — rollup state is anchored to Ethereum
  • Fraud proofs — if a validator publishes incorrect state, anyone can challenge it
  • Input ordering — the InputBox contract ensures all inputs are processed in the same order

Users do not interact with Arbitrum directly. The Cartesi node handles settlement automatically.

Identity Model​

Users are identified by a DID (Decentralized Identifier) derived from their wallet:

Wallet (secp256k1 private key)
    -> Public key (33 bytes, compressed)
    -> Multicodec prefix (0xe7 0x01)
    -> Base58btc encoding
    -> did:key:zQ3sh...

This DID is deterministic — the same wallet always produces the same DID. It serves as the user's pseudonymous identity across the entire system. No registration is required; connecting a wallet is sufficient.

Next Steps​