zkID

Overview

zkID is a privacy-preserving universal identity system that generates a did:zk decentralized identifier with on-chain verification on both Solana and Starknet.

DID Format

did:zk:[random alphanumeric string]

Example:

did:zk:a7bk9mx2pq4r8n5t

How It Works

Create Identity: Generate a new zkID with a username and password. The system creates an Ed25519 keypair, unique DID, and password hash using bcrypt.
Generate Proof: Client-side proof generation using Ed25519 signatures. The proof demonstrates ownership of the identity without revealing the private key.
On-Chain Verification: The proof is verified on-chain via Solana Mainnet transaction or Starknet Cairo contract (ZkIDProofRegistry).

Terminal Commands

Register New zkID

zk id register

Prompts for username and password, then generates your unique did:zk identity with an Ed25519 keypair.

zk id login

zk id login --blockchain solana
zk id login --blockchain starknet

Generate Proof

zk id prove

Generate a cryptographic ownership proof. Requires password to sign with your private key.

Verify On-Chain

zk id verify-onchain

Publish proof hash to Solana Mainnet. Server pays gas fees (free for users).

Check Status

zk id status

Shows your zkID and on-chain verification status on both Solana and Starknet.

View Proof History

zk id proof-history

Displays all generated and verified proofs.

Logout

zk id logout

Clears authentication data and ends current session.

Help

zk id help

Shows detailed help for all zkID commands.

API Reference

Register zkID

POST /api/auth/register
Content-Type: application/json

{
  "username": "alice",
  "password": "secure_password",
  "identityPublicKey": "base64...",
  "identityPrivateKeyEncrypted": "base64...",
  "identityPrivateKeyIv": "base64...",
  "kdfSalt": "base64...",
  "kdfIterations": 100000
}

Response:

{
  "message": "zkID created successfully",
  "user": {
    "id": "uuid",
    "zkId": "did:zk:a7bk9mx2pq4r8n5t",
    "username": "alice",
    "identityPublicKey": "base64..."
  }
}

POST /api/auth/login
Content-Type: application/json

{
  "username": "alice",
  "password": "secure_password"
}

Response:

{
  "message": "Login successful",
  "user": {
    "id": "uuid",
    "zkId": "did:zk:a7bk9mx2pq4r8n5t",
    "username": "alice"
  }
}

Check Session

GET /api/auth/me

Response:

{
  "user": {
    "id": "uuid",
    "zkId": "did:zk:a7bk9mx2pq4r8n5t",
    "username": "alice"
  }
}

Logout

POST /api/auth/logout

Response:

{
  "message": "Logged out successfully"
}

On-Chain Architecture

Solana Verification

zkID proofs are stored on Solana Mainnet using a Program Derived Address (PDA) structure. Only the signature hash goes on-chain for privacy.

Starknet Verification

The ZkIDProofRegistry Cairo contract stores zkID proofs on Starknet:

#[storage]
struct Storage {
    proofs: LegacyMap<felt252, ZkIDProof>,
    owner: ContractAddress,
}

struct ZkIDProof {
    did_hash: felt252,
    public_key: felt252,
    timestamp: u64,
    verified: bool,
}

Security Features

Ed25519 Cryptography: Elliptic curve cryptography for secure key generation and signatures.
bcrypt Password Hashing: 10 rounds of bcrypt for password protection.
Client-Side Proof Generation: Private key never leaves your device.
Dual-Chain Verification: Redundancy through verification on both Solana and Starknet.
Replay Protection: Nonce and timestamp prevent proof reuse.
Session-Based Auth: HTTP-only cookies for secure session management.

Example: Full Flow

# 1. Register your zkID
> zk id register
Username: alice
Password: ********
Confirm Password: ********

Creating zkID...
Generating Ed25519 keypair...
Your zkID: did:zk:a7bk9mx2pq4r8n5t

# 2. Login with on-chain verification
> zk id login --blockchain starknet
Username: alice
Password: ********

Authenticating...
Generating proof...
Submitting to Starknet...

Login successful!
  zkID: did:zk:a7bk9mx2pq4r8n5t
  Starknet: Verified (tx: 0x123...)

# 3. Check status
> zk id status
zkID: did:zk:a7bk9mx2pq4r8n5t
Status: Verified
Chains:
  - Solana Mainnet: Pending
  - Starknet: Verified

# 4. Logout
> zk id logout
Session cleared.

Introduction

Getting Started

ZK Ecosystem

Integrations

Resources

Overview

DID Format

How It Works

Terminal Commands

Register New zkID

Generate Proof

Verify On-Chain

Check Status

View Proof History

Logout

Help

API Reference

Register zkID

Check Session

Logout

On-Chain Architecture

Solana Verification

Starknet Verification

Security Features

Example: Full Flow

​Overview

​DID Format

​How It Works

​Terminal Commands

​Register New zkID

​Login

​Generate Proof

​Verify On-Chain

​Check Status

​View Proof History

​Logout

​Help

​API Reference

​Register zkID

​Login

​Check Session

​Logout

​On-Chain Architecture

​Solana Verification

​Starknet Verification

​Security Features

​Example: Full Flow

Overview

DID Format

How It Works

Terminal Commands

Register New zkID

Login

Generate Proof

Verify On-Chain

Check Status

View Proof History

Logout

Help

API Reference

Register zkID

Login

Check Session

Logout

On-Chain Architecture

Solana Verification

Starknet Verification

Security Features

Example: Full Flow