path: root/CONSENSUS.md

# Proof-of-Contribution Consensus

## OnionCoin's Revolutionary Consensus Mechanism

Unlike traditional Proof-of-Work (wasteful) or Proof-of-Stake (plutocratic), OnionCoin introduces **Proof-of-Contribution**: a hybrid system that rewards **actual network contribution**, not just capital or electricity.

## Core Philosophy

> "OnionCoin rewards WORK, not just WEALTH"

A validator with 10 ONC who actively relays traffic can be more competitive than a whale with 10,000 ONC doing nothing.

## Contribution Components

### 1. Stake (40% weight)

**Purpose**: Economic security, skin in the game

**Calculation**: Logarithmic scale to prevent whale dominance

```
stake_score = log10(stake_amount) / log10(max_stake)
              × tier_multiplier
```

**Why logarithmic?**
- 10 ONC → 100 ONC = 0.1 score increase
- 100 ONC → 1,000 ONC = 0.1 score increase
- 1,000 ONC → 10,000 ONC = 0.1 score increase

**Result**: Diminishing returns on large stakes

**Tiers**:
- Micro (10 ONC): 1.0x multiplier
- Light (100 ONC): 1.1x multiplier
- Standard (1,000 ONC): 1.2x multiplier
- Power (10,000 ONC): 1.3x multiplier

### 2. Tor Relay Work (30% weight) ⭐ UNIQUE!

**Purpose**: Reward validators who relay OnionCoin traffic through Tor

**This is OnionCoin's killer feature!** No other cryptocurrency rewards Tor relay work.

**Calculation**:
```
base_score = GB_relayed / 100 (capped at 0.8)
quality_multiplier = (1 - failure_rate) × latency_factor
diversity_bonus =
  - 0.0 for < 50 circuits
  - 0.1 for 50-100 circuits
  - 0.2 for 100+ circuits

relay_score = (base_score × quality_multiplier) + diversity_bonus
```

**Proof-of-Relay**:
Validators submit hourly proofs containing:
- Bytes relayed
- Packets relayed
- Unique circuits served
- Average latency
- Cryptographic proof (hash chain)

**Rewards**:
- 1 ONC per GB relayed (base)
- Up to 1.2x bonus for high circuit diversity
- Quality penalty for high latency/failures

**Example**:
```
Validator relays 50 GB with:
- 150 unique circuits (high diversity)
- 500ms avg latency (good)
- 99% success rate (excellent)

Reward: 50 GB × 1 ONC/GB × 1.2 = 60 ONC
```

### 3. Bandwidth (15% weight)

**Purpose**: Encourage high-bandwidth nodes

**Calculation**:
```
bandwidth_score = avg_bandwidth / max_bandwidth
                  (10 Mbps = 1.0 score)
```

**Measurement**:
- Total bytes sent/received per measurement period
- Rolling average over 24 hours
- Peak bandwidth tracking

### 4. Uptime (10% weight)

**Purpose**: Reward reliability

**Calculation**:
```
uptime_score = (uptime_percentage / 100)
               × disconnection_penalty
               × streak_bonus
```

**Bonuses/Penalties**:
- 99%+ uptime: 1.2x bonus
- 95-99% uptime: 1.1x bonus
- \>5 disconnects/day: 0.5x penalty
- 7+ day streak: 1.2x bonus
- 24+ hour streak: 1.1x bonus

### 5. Storage (5% weight)

**Purpose**: Encourage full nodes with blockchain storage

**Calculation**:
```
storage_score = GB_provided / 100
                (100 GB = 1.0 score)
```

## Total Score Calculation

```rust
total_score =
  stake_score      × 0.40 +
  relay_score      × 0.30 +
  bandwidth_score  × 0.15 +
  uptime_score     × 0.10 +
  storage_score    × 0.05
```

Result: Score between 0.0 and 1.0

## Validator Selection

### Algorithm: Verifiable Random Function (VRF)

Selection is **weighted random** based on contribution score:

```
1. Calculate each validator's contribution score
2. Generate deterministic random seed from:
   - Previous block hash
   - Current block height
3. Weighted random selection using VRF
4. Higher score = higher probability
```

**Example**:
```
Validator A: 0.8 score → 40% selection probability
Validator B: 0.6 score → 30% selection probability
Validator C: 0.4 score → 20% selection probability
Validator D: 0.2 score → 10% selection probability
```

### Fairness Properties

✅ **Deterministic**: Same inputs → same validator selected
✅ **Unpredictable**: Cannot predict future selections
✅ **Fair**: Probability proportional to contribution
✅ **Verifiable**: Anyone can verify selection was correct

## Genesis Mining (Fair Launch)

### Phase 1: 6 Months Genesis Period

**Goal**: Fair initial distribution with NO pre-mine

**How it works**:
1. Anyone runs a Tor relay for OnionCoin
2. Record relay activity (bytes, uptime)
3. After 6 months, distribute 1,000,000 ONC proportionally

**Rewards**:
```
base_reward = (your_relay_bytes / total_relay_bytes) × 1,000,000 ONC
early_bonus = 2x for month 1, linear decay to 1x
uptime_bonus = up to 20% extra for 99%+ uptime

total_reward = base_reward × early_bonus × (1 + uptime_bonus)
```

**Requirements**:
- Minimum 1 GB relayed to qualify
- Must maintain uptime during measurement

**Why this is fair**:
- ❌ NO pre-mine (unlike Bitcoin)
- ❌ NO ICO (unlike Ethereum)
- ❌ NO founder allocation (unlike most alts)
- ✅ 100% earned through work
- ✅ Anyone can participate (just run Tor relay)
- ✅ Low barrier to entry (1 GB relay minimum)

### Phase 2: Regular PoC

After genesis period, transition to regular Proof-of-Contribution:
- Block rewards: 5 ONC/block
- Halving: Every 4 years
- Validators earn based on contribution score

## Economic Incentives

### For Small Validators (Micro/Light)

**Can compete by**:
- Running excellent Tor relay (30% weight!)
- High uptime (10% weight)
- Good bandwidth (15% weight)

**Example**:
```
Micro validator (10 ONC):
- Stake score: 0.1 (low)
- Relay score: 0.9 (high - relays 100 GB/day)
- Bandwidth: 0.8 (good connection)
- Uptime: 0.95 (rarely offline)
- Storage: 0.2 (20 GB)

Total: 0.1×0.4 + 0.9×0.3 + 0.8×0.15 + 0.95×0.1 + 0.2×0.05
     = 0.04 + 0.27 + 0.12 + 0.095 + 0.01
     = 0.535

This Micro validator is MORE competitive than a Power validator
(10,000 ONC) who does no relay work (score ~0.3)!
```

### For Large Validators (Power)

**Can maximize by**:
- Large stake (but diminishing returns)
- Running high-capacity relay
- Multiple geographically distributed nodes
- Professional infrastructure (99.99% uptime)

**Best strategy**: Combine capital with actual work

## Attack Resistance

### Sybil Attack

**Attack**: Create many low-stake validators

**Defense**:
- Minimum 10 ONC stake required
- Relay work must be genuine (verified through proofs)
- Bandwidth/uptime must be real (measured independently)
- Cost of running fake relays > rewards

### Whale Attack (51% stake)

**Attack**: Acquire 51% of all ONC to dominate

**Defense**:
- Stake is only 40% of score
- Logarithmic scaling reduces whale advantage
- Must also provide relay work (expensive!)
- Slashing for misbehavior

**Example**:
Whale with 50% of total stake gets:
- Stake score: ~0.85 (due to log scaling)
- Total score without work: 0.85 × 0.4 = 0.34
- Still needs relay/bandwidth/uptime to be competitive

### Lazy Validator Attack

**Attack**: Stake coins but provide no service

**Defense**:
- Low contribution score → rarely selected
- No block rewards → no ROI
- Other validators with lower stake but higher work out-compete
- Economic pressure to either work or unstake

## Comparison with Other Consensus Mechanisms

| Feature | Bitcoin PoW | Ethereum PoS | OnionCoin PoC |
|---------|-------------|--------------|----------------|
| Energy consumption | ❌ Very high | ✅ Low | ✅ Very low |
| Minimum requirement | $$$ ASIC | 32 ETH (~$50k) | 10 ONC (~$1?) |
| Hardware | Industrial | Standard PC | Raspberry Pi |
| Centralization risk | Mining pools | Whale validators | ✅ Distributed (work matters) |
| Environmental impact | ❌ Terrible | ✅ Good | ✅ Excellent |
| Fair launch | ✅ Yes | ❌ Pre-mine | ✅ Genesis mining |
| **Rewards network work** | ❌ No | ❌ No | ✅ **YES!** |

## Technical Implementation

See `/consensus` module for implementation:

- `validator.rs`: Validator tiers and registry
- `proof_of_contribution.rs`: Score calculation
- `relay_proof.rs`: Proof-of-Relay system ⭐
- `metrics.rs`: Bandwidth, uptime, storage tracking
- `selection.rs`: VRF-based validator selection
- `genesis.rs`: Fair launch genesis mining

## Future Research

Potential improvements:
- ZK-SNARKs for relay proofs (privacy + efficiency)
- Adaptive weight adjustment based on network needs
- Dynamic tier thresholds
- Cross-shard relay rewards (if sharding implemented)

## Conclusion

OnionCoin's Proof-of-Contribution is **the first consensus mechanism** to:

1. ✅ Reward Tor relay work
2. ✅ Make small validators competitive
3. ✅ Combine security with network utility
4. ✅ Be truly accessible (Raspberry Pi can validate!)
5. ✅ Prevent plutocracy through logarithmic stake scaling

**This is not just another PoS fork. This is genuinely novel.**

---

Run the demo:
```bash
cargo run --example consensus_demo
```