HumanENS

Prove your humanity. Own your agent name. No gatekeepers.

📋 Table of Contents

• The Problem
• Quick Start
• How It Works
• Architecture
• Project Structure
• Development Guide
• Live Services
• Key Concepts

---

The Problem

1. No way to prove an ENS name belongs to a real human. Anyone can register a name — there's no on-chain signal distinguishing humans from bots. As AI agents proliferate, this distinction becomes critical.
2. AI agents have no human-readable identity. An agent might have a wallet, but no name, no discoverability, and no visible link to its human operator.
3. No trust anchor for agent namespaces. You can create ENS subnames, but nothing ties them back to a verified human — so there's no way to know who's behind an agent.

---

Quick Start

Prerequisites

• Node.js 18+ and pnpm
• A World ID (via Worldcoin)
• An existing ENS domain (yourname.eth)

Setup & Development

# Clone and install dependencies
git clone <repo-url>
cd ETHGlobal-Cannes2026
pnpm install

# Frontend (Next.js)
cd frontend
pnpm dev
# Open http://localhost:3000

# Backend (World ID verification service)
cd backend
pnpm dev
# Runs on http://localhost:3001

# Gateway (CCIP-Read service)
cd gateway
pnpm dev
# Runs on http://localhost:3002

Your First Registration

1. Go to http://localhost:3000
2. Connect your wallet (World App or browser wallet)
3. Enter your ENS name (e.g., alice)
4. Verify with World ID
5. Verify ownership on L1 via CCIP-Read
6. Mint your verified alice.humanens.eth on World Chain

Create an Agent

1. After registering your verified link
2. Click "Create Agent"
3. Enter an agent name (e.g., shopping-bot)
4. Verify with World ID again
5. Mint shopping-bot.alice.humanens.eth as an ERC-721

---

How It Works

🔐 Verified Link

The Problem: You own alice.eth on Ethereum L1, but how do we prove you also control it on World Chain without moving your NFT?

The Solution: Get a verified alice.humanens.eth subname linked via bidirectional proof — no transfer required. Uses CCIP-Read (EIP-3668) for trustless L1→L2 ownership verification without bridging.

What you get:

• Keep full control of your original alice.eth on L1
• Get a verified alice.humanens.eth on World Chain
• One-time World ID verification anchors the link
• 10-minute freshness window prevents replay attacks

🤖 Agent Subnames

The Problem: AI agents need human-readable names, but anyone can claim to represent you.

The Solution: Create shopping-bot.alice.humanens.eth — a World ID-gated agent namespace where every name traces back to a verified human. Resolvable everywhere ENS works.

Features:

• Compatible with ENSIP-25 (for ERC-8004 agents bidirectional attestation)
• Integrates with World's AgentBook for human-only privileges
• Each agent is an ERC-721 NFT (transferable, composable)
• Only you can create subagents under your verified link

---

Architecture

System Overview

Frontend (Next.js, IDKit, MiniKit, wagmi/viem)
    │
    ├── Backend (Express) ─── World ID v4 cloud verification + EIP-712 attestations
    │                         (temporary while v4 contracts are not on mainnet)
    │
    ├── Gateway (Express) ─── CCIP-Read L1 ENS ownership proofs
    │
    └── World Chain Mainnet
        ├── ENS L2Registry ──── handles subnames
        └── HumanENSLinker.sol ─── acts as a custom L2Registrar for verified links & agent subnames

Registration Flow

Step-by-step process for linking your ENS name:

1. User enters their ENS label (e.g. "alice")
   └─ Frontend validates the label format
   
2. Frontend checks L1 for existing text record
   └─ If missing: user must set humanens text record first
   └─ Value: arbitrary nullifier for the link
   
3. User verifies humanity with World ID v4
   └─ Obtains a World ID proof + nullifier
   
4. Frontend sends proof to backend for attestation
   └─ Backend verifies the proof cryptographically
   └─ Backend signs an EIP-712 attestation (nullifier + label + timestamp + expiry)
   
5. Frontend calls gateway for L1 ownership proof
   └─ Gateway reads alice.eth owner + text record from L1 via RPC
   └─ Gateway returns a signed CCIP-Read proof
   
6. Frontend submits registration transaction via MiniKit
   ✓ Contract verifies backend signature (humanity proof)
   ✓ Contract verifies gateway signature (L1 ownership proof)
   ✓ Contract checks freshness (10-min window)
   ✓ Contract enforces one-link-per-nullifier
   └─ L2 Registry mints alice.humanens.eth on World Chain

Agent Creation Flow

Step-by-step process for creating an agent under your verified link:

1. User enters an agent name (e.g. "shopping-bot") under alice.humanens.eth
   
2. User verifies with World ID v4 again
   └─ Proves they own the parent verified link
   
3. Frontend sends the proof to backend
   └─ Backend verifies and signs an EIP-712 attestation for agent creation
   
4. Frontend submits agent creation transaction via MiniKit
   ✓ Contract verifies signature
   ✓ Contract verifies nullifier matches parent link owner
   └─ L2 Registry mints shopping-bot.alice.humanens.eth as an ERC-721
   
5. (Optional) User sets ENSIP-25 text record
   └─ Link it to an existing ERC-8004 agent for bidirectional attestation

---

Project Structure

├── contracts/            Solidity smart contracts
│   ├── HumanENSLinker.sol    Main contract for link registration & agent creation
│   └── interfaces/           ENS L2Registry interfaces
│
├── backend/              Express.js server
│   ├── World ID v4 verification service
│   ├── EIP-712 attestation signing
│   └── REST API endpoints
│
├── gateway/              Express.js CCIP-Read gateway
│   ├── L1 ownership verification
│   ├── CCIP-Read proof generation
│   └── Signature verification
│
├── frontend/             Next.js 15 application
│   ├── World Mini App + browser UI
│   ├── ENS integration (viem/wagmi)
│   ├── MiniKit for transactions
│   └── World ID v4 IDKit
│
└── register-agent/       CLI utility for ERC-8004 agent registration

Service Breakdown

Component	Purpose	Tech Stack
Frontend	User interface for registration & agent creation	Next.js 15, TypeScript, viem/wagmi, IDKit, MiniKit
Backend	World ID verification & attestation signing	Express, TypeScript, EIP-712
Gateway	Trustless L1 ownership proofs via CCIP-Read	Express, TypeScript, EIP-3668
Contracts	On-chain registration logic & subname minting	Solidity, OpenZeppelin

---

Live Services

Service	URL
📦 L2Registry contract	0x37119ac61eb66d2b877e8c3fa65924a3b6c6970b
🔗 HumanENSLinker contract	0xE073cc7E0675a65BD9b03D528c1c227614119063

---

Development Guide

Working with Each Component

Frontend Development

cd frontend
pnpm dev

• Access at http://localhost:3000
• Uses hot reload (changes refresh automatically)
• Connect wallet via browser extension or World App
• Debugging: Open VS Code DevTools (F12)

Backend Development

cd backend
pnpm dev

• Runs on http://localhost:3001
• Endpoints:
  • POST /verify — Verify World ID proof
  • POST /attest — Get signed EIP-712 attestation

Gateway Development

cd gateway
pnpm dev

• Runs on http://localhost:3002
• Implements CCIP-Read standard
• Reads L1 ENS data via RPC
• Returns signed proofs for contract verification

Running All Services

# Terminal 1: Frontend
cd frontend && pnpm dev

# Terminal 2: Backend
cd backend && pnpm dev

# Terminal 3: Gateway
cd gateway && pnpm dev

Testing Contracts

cd contracts
# Run Foundry or Hardhat tests

Key Configuration Files

File	Purpose
pnpm-workspace.yaml	Monorepo configuration (root)
wagmi-config.ts (frontend)	Blockchain RPC & account config
.env.local (services)	API keys, RPC URLs, signing keys

---

Key Concepts

CCIP-Read (EIP-3668)

Allows smart contracts to verify off-chain data without storing it on-chain. Used to prove L1 ENS ownership without bridging the NFT.

EIP-712 Attestations

Standard for signing structured data. Used by backend to create verifiable proofs of World ID verification without storing nullifiers on-chain.

Nullifier

A World ID-provided identifier that prevents duplicate registrations (one per human, one per link).

World ID v4

Worldcoin's proof-of-personhood service. Provides cryptographic proof that you're a unique human.

ERC-721 Agent NFTs

Each agent name (shopping-bot.alice.humanens.eth) is minted as an NFT, making it transferable and composable with other protocols.

ENSIP-25

ENS Improvement Proposal for agent namespaces and bidirectional attestation between traditional ENS names and ERC-8004 agents.

---