Skip to main content

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

Contract auditNot yet
No independent review of the contracts yet.
Penetration testNot yet
Not carried out yet.
Direct messagesAvailable
XMTP with MLS, encrypted in the browser.
Fallback relayPartly available
Stores readable messages when XMTP delivery fails. Labelled in the interface.
Community contentPartly available
Stored readable on the server.
Mobile appsIn development
Not submitted to the stores. The web client is the supported one.
Private wallet on Aztec AlphaPartly available
Send, shield and unshield with a cap per payment. Each account pays its own fee.
PasskeysPartly available
In code and unit tests. Not yet tested on a real authenticator.
Ethereum portalIn development
Contracts and wallet code tested in CI. Not deployed on any network.

Integrations added on 17 November 2026

IntegrationCodeTestsState
Passkey unlock (WebAuthn PRF)lib/aztec/wallet/passkey.ts, passkey-store.ts, app/api/aztec/passkeystest/unit/aztec/passkey.test.tsIn the wallet. Real devices not tested.
G7 binding scheme v2 (network bound)lib/aztec/peer-binding.tstest/unit/aztec/peer-binding-network.test.tsIssued by every wallet. Required on Alpha.
Ethereum portal (HLPortal)contracts/portal/HLPortal.sol, AztecMessaging.soltest/portal/HLPortal.test.ts (Hardhat)Not deployed.
Receiver addressescontracts/portal/HLReceiver.sol, lib/portal/receivers.tsHardhat and test/unit/portal/Not deployed.
PortalToken (aztec-nr)contracts/aztec/portal_token11 TXE tests (aztec test in that folder)Not deployed.
Portal configurationlib/portal/config.tstest/unit/portal/config.test.tsOff unless every value is set and every Ethereum token is canonical.
Security viewcomponents/zk/wallet/SecurityCenter.tsxRendered from live wallet stateIn the wallet.
One signature sign inlib/xmtp/device-key-vault.tstest/unit/chat/calls-ring-anywhere-and-expressions.test.tsIn 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

LayerTechnologyNotes
ApplicationNext.js 15, React 19, TypeScriptApp Router. The middleware runs on the Edge runtime and holds the identity perimeter.
MessagingXMTP browser SDK, MLSDirect messages are encrypted in the browser. A server fallback exists and is labelled.
IdentitySign in with Ethereum, JWTSessions are cookies scripts cannot read. Identity is never taken from a header or a query parameter.
Paymentswagmi, viem; Aztec 6.0.0 and aztec-nr; Solidity for the portalPublic 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.
DataPostgreSQL with Prisma, RedisRedis is optional in development. Rate limiting and nonce storage degrade gracefully without it.
RealtimeServer sent events, WebRTCSome views still poll, which is the current scaling limit.
TestingVitest, PlaywrightUnit tests in test/, end to end tests in e2e/.

Run it locally

1. Clone and install

Terminal
git clone https://github.com/humanityledger/Humanity-Ledger.git
cd Humanity-Ledger
npm install

Some 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

.env.local
# 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

Terminal
npx prisma generate
npx prisma db push

DATABASE_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

Terminal
npm run dev

Open 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.