eth-id 0.1.0

# ETH.id Quick Start Guide

Get started with ETH.id in 5 minutes.

---

## Installation

### Option 1: Build from Source (Recommended)

```bash
# Clone repository
git clone https://github.com/your-org/eth-id.git
cd eth-id

# Build and install
make install

# Verify installation
eth --version
```

### Option 2: Cargo Install

```bash
cargo install --path .
```

### Option 3: Docker

```bash
docker build -t eth-id:latest .
docker run -it --rm eth-id:latest
```

---

## Configuration

### Set API Key

Choose one provider:

**OpenAI (Recommended for beginners)**:
```bash
export OPENAI_API_KEY=sk-your-key-here
```

**Claude (Best quality)**:
```bash
export ANTHROPIC_API_KEY=sk-ant-your-key-here
```

**Ollama (Offline/Privacy)**:
```bash
# Install Ollama first: https://ollama.ai
ollama pull llama3.2
export OLLAMA_URL=http://localhost:11434
```

### Configure Default Provider

```bash
eth config --provider openai
# or
eth config --provider claude
# or
eth config --provider ollama
```

---

## First Verification

### 1. Prepare a Document

Use one of the example documents:
```bash
ls examples/sample_documents/
# brazilian_id.txt
# passport.txt
# drivers_license.txt
# income_proof.txt
```

Or use your own PDF/text document.

### 2. Run Verification

**Age Verification**:
```bash
eth verify \
  --doc examples/sample_documents/brazilian_id.txt \
  --claim "maior de 18 anos"
```

**Expected Output**:
```
✅ Verification Result
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Answer: true
Confidence: 100.0%
Reasoning: Age calculation confirms person is over 18 years old
Proof Type: Virtualization (local computation)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### 3. Understand What Happened

1. **Document parsed locally** - Birth date extracted
2. **Age calculated locally** - No birth date sent anywhere
3. **Only result sent to LLM** - "Age calculation result: true"
4. **LLM confirms** - Returns boolean answer
5. **Audit log created** - Hash-only record saved

---

## Common Use Cases

### CPF Verification

```bash
eth verify \
  --doc examples/sample_documents/brazilian_id.txt \
  --claim "CPF bate com 123.456.789-09"
```

**Privacy**: Only masked CPF sent (123.***.***-09)

### Income Verification

```bash
eth verify \
  --doc examples/sample_documents/income_proof.txt \
  --claim "renda acima de 5000"
```

**Privacy**: Only amount field sent, no name/CPF

### Document Expiry

```bash
eth verify \
  --doc examples/sample_documents/passport.txt \
  --claim "passaporte está expirado"
```

### With Attestation

```bash
eth verify \
  --doc examples/sample_documents/brazilian_id.txt \
  --claim "maior de 21 anos" \
  --attest
```

Generates cryptographic proof bundle.

---

## Debug Mode

See exactly what data is sent to the LLM:

```bash
eth verify \
  --doc examples/sample_documents/brazilian_id.txt \
  --claim "maior de 18 anos" \
  --debug
```

**Output includes**:
- Filtered data content
- Privacy filter mode used
- Fields included/masked
- Original and filtered hashes

---

## Offline Mode

Complete privacy with local LLM:

```bash
# Start Ollama
ollama serve

# Run verification
eth verify \
  --doc examples/sample_documents/brazilian_id.txt \
  --claim "maior de 18 anos" \
  --offline \
  --provider ollama
```

**Zero network calls** - Everything local.

---

## View Audit Log

```bash
# List all verifications
eth audit --list

# Show specific session
eth audit --show <session-id>

# Export to JSON
eth audit --export <session-id>
```

---

## Interactive Demo

Run the full demo:

```bash
./examples/demo.sh
```

Demonstrates:
- Age verification
- CPF verification
- Income verification
- Passport expiry
- Attestation generation
- Audit log review

---

## Troubleshooting

### "API key not set"

```bash
# Check environment
env | grep API_KEY

# Set key
export OPENAI_API_KEY=sk-your-key
```

### "Document parsing failed"

- Check file exists
- Verify file format (PDF, txt, JSON, image)
- Check file size (< 10MB)

### "Claim parsing failed"

Supported claim formats:
- "maior de 18 anos" / "over 18 years old"
- "renda acima de 5000" / "income above 5000"
- "CPF bate com 123.456.789-00"
- "documento assinado" / "document signed"

### "Ollama not running"

```bash
# Start Ollama
ollama serve

# Pull model
ollama pull llama3.2
```

---

## Next Steps

1. **Read Privacy Docs**: `PRIVACY.md` - Understand data handling
2. **Read Threat Model**: `THREAT_MODEL.md` - Security guarantees
3. **Try ZK Proofs**: `eth zk` - Zero-knowledge circuits
4. **Generate Attestations**: `--attest` flag
5. **Review Audit Log**: `eth audit --list`

---

## Help & Support

```bash
# General help
eth --help

# Command help
eth verify --help
eth audit --help
eth config --help
```

**Documentation**:
- README.md - Full documentation
- ARCHITECTURE.md - System design
- CONTRIBUTING.md - Development guide

**Issues**: https://github.com/your-org/eth-id/issues

---

## Example Workflow

```bash
# 1. Configure
export OPENAI_API_KEY=sk-your-key
eth config --provider openai

# 2. Verify
eth verify --doc passport.pdf --claim "over 18 years old" --attest

# 3. Review
eth audit --list

# 4. View attestation
eth attest --session <session-id>
```

---

**You're ready to use ETH.id! 🚀**

For advanced usage, see the full README.md.