> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zkterm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# zkID

> Privacy-preserving universal zero-knowledge identity

## 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

```bash theme={null}
zk id register
```

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

### Login

```bash theme={null}
zk id login
```

Login with automatic on-chain verification. Supports blockchain selection:

```bash theme={null}
zk id login --blockchain solana
zk id login --blockchain starknet
```

### Generate Proof

```bash theme={null}
zk id prove
```

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

### Verify On-Chain

```bash theme={null}
zk id verify-onchain
```

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

### Check Status

```bash theme={null}
zk id status
```

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

### View Proof History

```bash theme={null}
zk id proof-history
```

Displays all generated and verified proofs.

### Logout

```bash theme={null}
zk id logout
```

Clears authentication data and ends current session.

### Help

```bash theme={null}
zk id help
```

Shows detailed help for all zkID commands.

## API Reference

### Register zkID

```bash theme={null}
POST /api/auth/register
Content-Type: application/json

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

**Response:**

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

### Login

```bash theme={null}
POST /api/auth/login
Content-Type: application/json

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

**Response:**

```json theme={null}
{
  "message": "Login successful",
  "user": {
    "id": "uuid",
    "zkId": "did:zk:a7bk9mx2pq4r8n5t",
    "username": "alice"
  }
}
```

### Check Session

```bash theme={null}
GET /api/auth/me
```

**Response:**

```json theme={null}
{
  "user": {
    "id": "uuid",
    "zkId": "did:zk:a7bk9mx2pq4r8n5t",
    "username": "alice"
  }
}
```

### Logout

```bash theme={null}
POST /api/auth/logout
```

**Response:**

```json theme={null}
{
  "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:

```cairo theme={null}
#[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

```bash theme={null}
# 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.
```