zk-id

Privacy-preserving identity verification using zero-knowledge proofs.

zk-id lets users prove claims (for example, "age >= 18" or "nationality is in the EU") without revealing raw identity data (for example, exact birth date, name, or ID number). It includes SDKs for issuers/verifiers, OpenID4VP support, nationality/residency set-membership proofs, and runnable demos.

Quick Start

Prerequisites

• Node.js 20 (repo .nvmrc)
• npm

Install and prepare circuits

npm install
npm run compile:circuits
npm run --workspace=@zk-id/circuits setup

Run the main web demo

npm start --workspace=@zk-id/example-web-app

Open http://localhost:5050.

Optional: run the interactive portal

npm run portal:dev

Open http://localhost:4321.

For an end-to-end walkthrough, see GETTING-STARTED.md.

What You Can Run

Examples

Example	What it shows	Run	Default URL	Docs
examples/web-app	Full issuance + verification flow (age, nationality, scenarios, revocation)	npm start --workspace=@zk-id/example-web-app	http://localhost:5050	examples/web-app/README.md
examples/openid4vp-demo	QR-based OpenID4VP verifier + wallet flow	npm start --workspace=zk-id-openid4vp-demo	http://localhost:5173	examples/openid4vp-demo/README.md
examples/age-gate-widget	Embeddable age-gate widget integration	npm run dev --workspace=zk-id-age-gate-widget	http://localhost:5174 (or next Vite port)	examples/age-gate-widget/README.md

Workspace-level examples index: examples/README.md

Mobile Clarification

There are two mobile code paths in this repo:

• @zk-id/mobile (packages/mobile): TypeScript SDK for React Native/Expo/Node-style environments.
• @zk-id/wallet-app (packages/wallet-app): native iOS SwiftUI wallet app (workspace app/reference implementation, private package).

They are related but different. The iOS app is not the same package as the TypeScript mobile SDK.

Package Overview

zk-id is a monorepo with 11 package workspaces:

Workspace	Purpose
@zk-id/core	Core credential, proof, verification, revocation, and BBS+ primitives
@zk-id/circuits	Circom circuits and proving artifacts
@zk-id/sdk	Web client/server SDK and OpenID4VP components
@zk-id/issuer	Credential issuance and key-management helpers
@zk-id/issuer-server	Reference Express issuer service
@zk-id/redis	Redis-backed stores for production deployments
@zk-id/contracts	Solidity verifier contracts for EVM chains
@zk-id/mobile	Mobile TypeScript SDK (React Native/Expo)
@zk-id/portal	Developer portal and playground app
@zk-id/wallet-app	Native iOS wallet app (SwiftUI, private workspace app)
@zk-id/wallet-app-rn	React Native / Expo wallet app

Minimal SDK Usage

import { ZkIdClient } from '@zk-id/sdk';

const client = new ZkIdClient({
  verificationEndpoint: '/api/verify-age',
});

const verified = await client.verifyAge(18);
if (verified) {
  // grant access
}

import { ZkIdServer } from '@zk-id/sdk';

const server = new ZkIdServer({
  verificationKeyPath: './verification_key.json',
});

app.post('/api/verify-age', async (req, res) => {
  const result = await server.verifyProof(req.body, req.ip);
  res.json({ verified: result.verified });
});

See package docs for complete APIs:

• packages/core/README.md
• packages/sdk/README.md
• packages/issuer/README.md
• packages/issuer-server/README.md
• packages/mobile/README.md
• packages/wallet-app/README.md

Security and Operational Notes

• Threat model: docs/THREAT-MODEL.md
• Known limitations: docs/KNOWN-LIMITATIONS.md
• Signed-circuit option: docs/SIGNED-CIRCUITS.md
• Security policy: SECURITY.md

Additional Docs

• Protocol: docs/PROTOCOL.md
• OpenID4VP: docs/OPENID4VP.md
• Schema extensibility: docs/SCHEMA-EXTENSIBILITY.md
• Architecture: docs/ARCHITECTURE.md
• Roadmap: docs/ROADMAP.md
• OpenAPI spec: docs/openapi.yaml

Contributing

• Contributing guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md

License

Apache-2.0. See LICENSE and NOTICE.