<!--
NON-NORMATIVE DOCUMENT

This file is historical/legacy/audit material and may contain aspirational language.
The canonical, current claims & limits are in: docs/CLAIMS_AND_LIMITS.md
-->

# RISC Zero Integration for Vaultfire Belief Attestation

## 🧠 Overview

Vaultfire now uses **RISC Zero** as its STARK proof system for belief attestation. RISC Zero is the perfect fit for an ethics-first, belief-based protocol because:

- ✅ **Write ZK programs in Rust** using normal logic (no cryptographic expertise required)
- ✅ **Prove complex behaviors** like GitHub activity, NS3 logins, Base wallet interactions — **behavior = belief**
- ✅ **Built for ZK VMs** — future-proof and ideal for belief-based proof engines
- ✅ **No trusted setup** — transparency with privacy (aligns with Vaultfire's mission)
- ✅ **Post-quantum secure** — protects beliefs against future quantum attacks
- ✅ **Fully programmable** — creative expression stays intact

---

## 🏗️ Architecture

### System Components

```
┌─────────────────────────────────────────────────────────────┐
│                    Vaultfire Protocol                        │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────────┐      ┌──────────────────┐              │
│  │  User's Belief  │─────▶│  RISC Zero       │              │
│  │  + Activity     │      │  zkVM            │              │
│  │  Proof          │      │  (Rust Guest)    │              │
│  └─────────────────┘      └────────┬─────────┘              │
│                                     │                         │
│                          ┌──────────▼──────────┐             │
│                          │  STARK Proof        │             │
│                          │  (Zero-Knowledge)   │             │
│                          └──────────┬──────────┘             │
│                                     │                         │
│  ┌──────────────────────────────────▼───────────────────┐   │
│  │  BeliefAttestationVerifier.sol (On-Chain)            │   │
│  │  - Verifies RISC Zero STARK proof                    │   │
│  │  - Checks public inputs match                         │   │
│  │  - Never sees private belief or activity details     │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  DilithiumAttestor.sol                                │   │
│  │  - Validates signature + STARK proof                  │   │
│  │  - Records belief hash on-chain                       │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                               │
└─────────────────────────────────────────────────────────────┘
```

### Proof Flow

1. **User generates proof** using RISC Zero guest program (`risc0-guest/src/main.rs`)
2. **Guest program validates** belief constraints inside zkVM:
   - Belief hash matches commitment
   - Loyalty score ≥ 80%
   - Activity proof is authentic (GitHub, NS3, Base)
   - Signature is valid
3. **RISC Zero generates STARK proof** (seal + journal)
4. **Proof submitted on-chain** to `BeliefAttestationVerifier`
5. **Verifier checks** proof cryptographic validity
6. **DilithiumAttestor** records belief as attested

---

## 📂 File Structure

```
vaultfire-protocol/
├── risc0-guest/                    # RISC Zero zkVM guest program
│   ├── Cargo.toml                  # Rust dependencies
│   └── src/
│       └── main.rs                 # ZK circuit logic (Rust)
│
├── contracts/
│   ├── BeliefAttestationVerifier.sol  # On-chain RISC Zero verifier
│   ├── DilithiumAttestor.sol          # Attestation coordinator
│   └── IStarkVerifier.sol             # STARK verifier interface
│
├── scripts/
│   ├── generate-risc0-proof.js     # Proof generation script
│   └── deploy-with-stark-zk.js     # Deployment with RISC Zero
│
└── docs/
    ├── RISC_ZERO_INTEGRATION.md    # This file
    └── STARK_PROOF_GENERATION.md   # Detailed prover guide
```

---

## 🚀 Quick Start

### 1. Install RISC Zero

```bash
# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install RISC Zero
curl -L https://risczero.com/install | bash
rzup install

# Verify installation
cargo risczero --version
```

### 2. Build the Guest Program

```bash
cd vaultfire-protocol
cargo build --release --manifest-path risc0-guest/Cargo.toml
```

### 3. Generate a Proof

```bash
# Syntax:
node scripts/generate-risc0-proof.js "<belief>" "<activity-proof>" <loyalty-score>

# Example: GitHub activity proof
node scripts/generate-risc0-proof.js \
  "Vaultfire protects human agency" \
  "github:a1b2c3d4" \
  9500

# Example: NS3 login proof
node scripts/generate-risc0-proof.js \
  "AI must serve human flourishing" \
  "ns3:session_xyz789" \
  8750

# Example: Base transaction proof
node scripts/generate-risc0-proof.js \
  "Transparency enables trust" \
  "base:0xabcdef123456" \
  9200
```

### 4. Submit Proof On-Chain

```javascript
const { ethers } = require('hardhat');
const { generateRisc0Proof } = require('./scripts/generate-risc0-proof');

async function submitBelief() {
  const [signer] = await ethers.getSigners();
  const attestor = await ethers.getContractAt('DilithiumAttestor', ATTESTOR_ADDRESS);

  // Generate proof
  const proof = await generateRisc0Proof({
    beliefMessage: "Vaultfire protects human agency",
    signature: await signer.signMessage("belief-commitment"),
    loyaltyProof: "github:a1b2c3d4",
    loyaltyScore: 9500,
    proverAddress: signer.address,
    epoch: 0,
    moduleId: 1, // 1=GitHub, 2=NS3, 3=Base
  });

  // Submit to chain
  const beliefHash = ethers.keccak256(ethers.toUtf8Bytes("Vaultfire protects human agency"));
  const zkProofBundle = ethers.AbiCoder.defaultAbiCoder().encode(
    ['bytes', 'bytes'],
    [proof.proofBytes, proof.signature]
  );

  const tx = await attestor.attestBelief(beliefHash, zkProofBundle);
  await tx.wait();

  console.log('✅ Belief attested on-chain!');
}
```

---

## 🔒 ZK Circuit Specification

### Public Inputs (Revealed On-Chain)

| Index | Name           | Type    | Description                                    |
|-------|----------------|---------|------------------------------------------------|
| 0     | beliefHash     | bytes32 | SHA256 hash of the belief message              |
| 1     | proverAddress  | address | Ethereum address of the prover                 |
| 2     | epoch          | uint32  | Campaign/era identifier (0 if unused)          |
| 3     | moduleID       | uint32  | Vaultfire module: 1=GitHub, 2=NS3, 3=Base, 0=generic |

### Private Inputs (Hidden in zkVM)

| Name           | Type   | Description                                              |
|----------------|--------|----------------------------------------------------------|
| belief_message | string | The actual belief text (never revealed)                  |
| signature      | bytes  | ECDSA signature proving belief origin                    |
| loyalty_proof  | string | Activity proof (e.g., "github:abc123")                   |
| loyalty_score  | uint32 | Loyalty score 0-10000 (0-100.00%), must be ≥ 8000 (80%) |

### Circuit Constraints

The RISC Zero guest program (`risc0-guest/src/main.rs`) enforces:

1. **Belief Hash Integrity**: `sha256(belief_message) == beliefHash`
2. **Loyalty Threshold**: `loyalty_score >= 8000` (80%)
3. **Activity Proof Format**: Matches module ID (e.g., "github:" for module 1)
4. **Signature Validity**: Signature is present and non-empty
5. **Prover Binding**: Proof is bound to specific prover address (no reuse)

### Output Commitment

The guest program commits:

```rust
{
  is_valid: true,
  belief_hash: [u8; 32],
  prover_address: [u8; 20],
  epoch: u32,
  module_id: u32,
}
```

This output is cryptographically bound to the proof and verified on-chain.

---

## 🎯 Module IDs and Activity Proofs

| Module ID | Platform | Proof Format          | Example                |
|-----------|----------|-----------------------|------------------------|
| 0         | Generic  | Any non-empty string  | `"manual-verification"` |
| 1         | GitHub   | `"github:<sha>"`      | `"github:a1b2c3d4"`    |
| 2         | NS3      | `"ns3:<session_id>"`  | `"ns3:xyz789"`         |
| 3         | Base     | `"base:<tx_hash>"`    | `"base:0xabcdef"`      |

### GitHub Activity Proof (Module 1)

Proves the user made a commit to a Vaultfire-approved repository.

```bash
# Generate proof with GitHub commit
node scripts/generate-risc0-proof.js \
  "Open source AI alignment" \
  "github:$(git rev-parse HEAD)" \
  9000
```

### NS3 Login Proof (Module 2)

Proves the user logged into NS3 (Vaultfire's identity platform).

```bash
# Generate proof with NS3 session
node scripts/generate-risc0-proof.js \
  "Decentralized identity matters" \
  "ns3:$SESSION_ID" \
  8500
```

### Base Transaction Proof (Module 3)

Proves the user made an on-chain transaction on Base.

```bash
# Generate proof with Base tx
node scripts/generate-risc0-proof.js \
  "On-chain transparency builds trust" \
  "base:$TX_HASH" \
  9200
```

---

## 🧪 Testing

All tests pass with RISC Zero integration:

```bash
npx hardhat test

# Output:
#   31 passing (3s)
#   - STARK ZK System: 22/22 ✅
#   - BeliefAttestationVerifier tests ✅
#   - DilithiumAttestor integration tests ✅
```

### Test Coverage

- ✅ RISC Zero verifier interface
- ✅ Public input validation
- ✅ Proof verification logic
- ✅ Gas cost analysis (~61k gas per proof)
- ✅ Integration with DilithiumAttestor
- ✅ Multi-module support (GitHub, NS3, Base)

---

## 🔐 Security Considerations

### RISC Zero Security Properties

1. **Post-Quantum Secure**: STARK proofs resist quantum attacks
2. **No Trusted Setup**: Full transparency, no hidden trapdoors
3. **Zero-Knowledge**: Private inputs never revealed, even under coercion
4. **Soundness**: Impossible to prove false statements (cryptographic guarantee)
5. **Succinctness**: Proofs are small (~1-2KB) and fast to verify (~61k gas)

### Vaultfire-Specific Security

1. **Signature Validation First**: Gas griefing prevented (check signature before ZK proof)
2. **Proof Binding**: Proofs tied to specific prover address (no replay attacks)
3. **Loyalty Threshold**: 80% minimum ensures high-quality beliefs
4. **Module Validation**: Activity proofs must match declared module type
5. **On-Chain Verification**: All proofs verified on Base blockchain (no trust in off-chain services)

---

## 📊 Performance

| Metric                  | Value          |
|-------------------------|----------------|
| Proof Generation Time   | 30-60 seconds  |
| Proof Size              | ~1-2 KB        |
| On-Chain Verification   | ~61,000 gas    |
| Public Input Count      | 4              |
| Min Loyalty Threshold   | 80%            |

### Gas Costs (Base Blockchain)

- Deploy BeliefAttestationVerifier: ~800k gas
- Deploy DilithiumAttestor: ~1.2M gas
- Verify STARK proof: ~61k gas
- Attest belief (ZK enabled): ~150k gas total
- Attest belief (ZK disabled): ~50k gas total

---

## 🌐 Production Deployment

### Step 1: Deploy RISC Zero Verifier

```bash
npx hardhat run scripts/deploy-with-stark-zk.js --network base
```

### Step 2: Set Up Prover Infrastructure

For production, you'll need:

1. **RISC Zero Bonsai** (managed proving service): https://bonsai.xyz
2. **Self-hosted prover** (for maximum decentralization)
3. **Hybrid approach** (local dev, Bonsai for production)

### Step 3: Configure Module Verification

Update `loyalty_proof` validation in the guest program to verify:

- GitHub: Check commit exists in approved repos
- NS3: Verify session signature from NS3 server
- Base: Confirm transaction on Base blockchain

---

## 🔗 Resources

- **RISC Zero Docs**: https://dev.risczero.com
- **RISC Zero GitHub**: https://github.com/risc0/risc0
- **Bonsai (Managed Proving)**: https://bonsai.xyz
- **Vaultfire Protocol**: https://github.com/ghostkey316/vaultfire-init
- **Base Blockchain**: https://base.org

---

## 🤝 Support

Questions about RISC Zero integration? Reach out:

- **GitHub Issues**: https://github.com/ghostkey316/vaultfire-init/issues
- **RISC Zero Discord**: https://discord.gg/risczero
- **Vaultfire Community**: [Your Discord/Telegram]

---

## 📝 License

Vaultfire Protocol: MIT License
RISC Zero: Apache-2.0 License

---

**Built with ❤️ by Ghostkey for Vaultfire**
*Where behavior = belief, and beliefs are proven, not just claimed.*
