Developers
Developers
Everything you need to read, run and contribute to the Humanity Ledger code.
The Humanity Ledger source code is public. If you want to know what the product does, the repository is a better answer than any page we write, including this one. It is open source under MIT OR Apache-2.0, at your option, so you may also modify and redistribute it. Security reports are welcome under Report a vulnerability.
State of the project
Integrations added on 17 November 2026
| Integration | Code | Tests | State |
|---|---|---|---|
| Passkey unlock (WebAuthn PRF) | lib/aztec/wallet/passkey.ts, passkey-store.ts, app/api/aztec/passkeys | test/unit/aztec/passkey.test.ts | In the wallet. Real devices not tested. |
| G7 binding scheme v2 (network bound) | lib/aztec/peer-binding.ts | test/unit/aztec/peer-binding-network.test.ts | Issued by every wallet. Required on Alpha. |
Ethereum portal (HLPortal) | contracts/portal/HLPortal.sol, AztecMessaging.sol | test/portal/HLPortal.test.ts (Hardhat) | Not deployed. |
| Receiver addresses | contracts/portal/HLReceiver.sol, lib/portal/receivers.ts | Hardhat and test/unit/portal/ | Not deployed. |
| PortalToken (aztec-nr) | contracts/aztec/portal_token | 11 TXE tests (aztec test in that folder) | Not deployed. |
| Portal configuration | lib/portal/config.ts | test/unit/portal/config.test.ts | Off unless every value is set and every Ethereum token is canonical. |
| Security view | components/zk/wallet/SecurityCenter.tsx | Rendered from live wallet state | In the wallet. |
| One signature sign in | lib/xmtp/device-key-vault.ts | test/unit/chat/calls-ring-anywhere-and-expressions.test.ts | In main. Falls back to the signature where IndexedDB is unavailable. |
Design notes: docs/ACCOUNT_MODEL.md, docs/PORTAL.md and docs/RECEIVER_ADDRESSES.md in the repository. The portal's build variables (NEXT_PUBLIC_HL_PORTAL, NEXT_PUBLIC_HL_RECEIVER_FACTORY, NEXT_PUBLIC_HL_RECEIVER_IMPLEMENTATION, NEXT_PUBLIC_HL_PORTAL_L1_CHAIN_ID, NEXT_PUBLIC_HL_PORTAL_ASSETS, NEXT_PUBLIC_HL_PORTAL_TOKEN_ARTIFACT, NEXT_PUBLIC_HL_PORTAL_DEPLOY_BLOCK) are listed in .env.example and are empty by default.
The stack
| Layer | Technology | Notes |
|---|---|---|
| Application | Next.js 15, React 19, TypeScript | App Router. The middleware runs on the Edge runtime and holds the identity perimeter. |
| Messaging | XMTP browser SDK, MLS | Direct messages are encrypted in the browser. A server fallback exists and is labelled. |
| Identity | Sign in with Ethereum, JWT | Sessions are cookies scripts cannot read. Identity is never taken from a header or a query parameter. |
| Payments | wagmi, viem; Aztec 6.0.0 and aztec-nr; Solidity for the portal | Public payments are signed in the user's wallet. Private payments run on Aztec Alpha with a cap per payment; proofs are made in the browser. |
| Data | PostgreSQL with Prisma, Redis | Redis is optional in development. Rate limiting and nonce storage degrade gracefully without it. |
| Realtime | Server sent events, WebRTC | Some views still poll, which is the current scaling limit. |
| Testing | Vitest, Playwright | Unit tests in test/, end to end tests in e2e/. |
Run it locally
1. Clone and install
git clone https://github.com/humanityledger/Humanity-Ledger.git
cd Humanity-Ledger
npm installSome dependencies still declare React 18 as a peer while the project uses React 19. The overrides in package.json handle most cases. If npm still refuses, add legacy-peer-deps=true to your .npmrc.
2. Configure the environment
# Required, or the app will not start
DATABASE_URL=
DATABASE_URL_UNPOOLED=
JWT_SECRET=
NEXTAUTH_SECRET=
NEXTAUTH_URL=http://localhost:3000
ENCLAVE_PIN_PEPPER=
ENCLAVE_PIN_SECRET=Never regenerate the PIN pepper in production
ENCLAVE_PIN_PEPPER is part of every stored PIN hash. Changing it makes every existing PIN invalid.
3. Set up the database
npx prisma generate
npx prisma db pushDATABASE_URL is the pooled connection and DATABASE_URL_UNPOOLED the direct one. Prisma needs both, because migrations use session level features that a transaction pooler cannot carry. A free Neon project works well.
4. Start it
npm run devOpen http://localhost:3000. The messenger is at /chat.
Common questions
Why does signing in fail locally?
Usually one of these. The message must be a real EIP-4361 message, built with prepareMessage(), with the checksummed address. Its domain must match the server's, which ignores the port: sign for localhost, not localhost:3000. In production the domain comes from NEXT_PUBLIC_DOMAIN or NEXT_PUBLIC_APP_URL (the www. variant is accepted too, and SIWE_ALLOWED_DOMAINS adds others); if neither is set, every sign in is refused. The nonce route, /api/siwe/nonce, must be reachable without a session, and the request to /api/siwe/verify must carry the siwe-nonce cookie it set. test/auth/siwe-routes.test.ts runs the whole flow with a real signature.
Where is the identity check?
In middleware.ts. It removes every identity header the client sent, on every request including public ones, then attaches the address from the verified session. Routes read it with requireWallet(req) or getSession(). Never send an identity header from a client: it is discarded.
Can I run it without Docker?
Yes. PostgreSQL can come from any provider and Redis is optional in development. docs/RUN-LOCAL.md in the repository covers both.
How do I report a vulnerability?
Privately, through the process on Report a vulnerability. Please do not open a public issue.
