Skip to main content

​
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

  1. Create Identity: Generate a new zkID with a username and password. The system creates an Ed25519 keypair, unique DID, and password hash using bcrypt.
  2. Generate Proof: Client-side proof generation using Ed25519 signatures. The proof demonstrates ownership of the identity without revealing the private key.
  3. 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.

​
Login

zk id login
Login with automatic on-chain verification. Supports blockchain selection: 
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..."
  }
}

​
Login

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

  1. Ed25519 Cryptography: Elliptic curve cryptography for secure key generation and signatures.
  2. bcrypt Password Hashing: 10 rounds of bcrypt for password protection.
  3. Client-Side Proof Generation: Private key never leaves your device.
  4. Dual-Chain Verification: Redundancy through verification on both Solana and Starknet.
  5. Replay Protection: Nonce and timestamp prevent proof reuse.
  6. 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.