# OnionCoin 🧅

**Privacy-first cryptocurrency natively built on the Tor network**

## Overview

OnionCoin is a cryptocurrency designed from the ground up to operate entirely within the Tor network, providing unprecedented privacy and censorship resistance. Unlike traditional cryptocurrencies that can optionally use Tor as a proxy, OnionCoin's entire architecture is built around Tor hidden services.

## Key Features

### 🕵️ Native Tor Integration
- Every node runs as a `.onion` hidden service
- P2P communication exclusively via Tor circuits
- Impossible to geolocate or censor nodes

### ⏰ Temporal Obfuscation (Unique!)
OnionCoin leverages Tor's inherent latency variability as a **privacy feature**:
- **Fuzzy timestamps**: Transactions use time ranges (2-6 hours) instead of precise timestamps
- **Zero-knowledge time proofs**: Prove transaction was created within a range without revealing exact time
- **Random delays**: Strategic delays at multiple propagation stages
- **Mixing pools**: Batch and shuffle transactions before broadcast
- Makes timing analysis and transaction correlation extremely difficult

### 🌸 Dandelion++ Propagation
- STEM phase: Forward through 1-4 random hops with delays
- FLUFF phase: Broadcast to network
- Hides transaction origin both temporally and topologically

### 🔒 Privacy by Default
- **Ring signatures**: Hide sender among decoys (Monero-style)
- **Stealth addresses**: Each transaction generates new recipient address
- **Confidential transactions**: Amounts hidden with Bulletproofs
- **No metadata leakage**: Timestamp, IP, location all obfuscated

### ⚡ Proof-of-Contribution Consensus (REVOLUTIONARY!)
OnionCoin's consensus is **unique**: it rewards WORK, not just wealth
- **Stake (40%)**: Still important, but uses logarithmic scale to reduce whale advantage
- **Tor Relay Work (30%)**: Earn by relaying OnionCoin traffic through Tor! 🌐
- **Bandwidth (15%)**: Network contribution matters
- **Uptime (10%)**: Reliability is rewarded
- **Storage (5%)**: Help store the blockchain

**Minimum stake: Only 10 ONC!** Even a Raspberry Pi Zero can validate!

### 💎 Native Blockchain Inheritance (WORLD'S FIRST!)
OnionCoin solves the **$140B+ lost Bitcoin problem** with inheritance built into the protocol
- **Progressive unlock**: Gradual release (10% → 35% → 70% → 100%) gives owner time to dispute if still alive!
- **Heartbeat system**: Send 0.00000001 ONC to yourself every 90 days to prove you're alive
- **Shamir secret sharing**: Split seed among 5 people, any 3 can recover
- **Anti-scam protections**: Dispute system, suspicious activity detection, max 3 disputes
- **Privacy-first**: Tor-only heartbeats, encrypted beneficiary lists
- **Costs $0.14** for 10 years vs $10,000 for lawyers

**NO OTHER CRYPTO HAS THIS!** Read [INHERITANCE.md](INHERITANCE.md) for details.

## Architecture

```
onioncoin/
├── core/        # Blockchain, transactions, blocks
├── crypto/      # Cryptographic primitives
├── timing/      # Temporal obfuscation (unique!)
├── network/     # Dandelion++, P2P over Tor
├── consensus/   # Proof-of-Contribution (UNIQUE!)
├── inheritance/ # Native inheritance system (WORLD'S FIRST!)
└── wallet/      # User wallet interface
```

## How It Works

### Transaction Flow

1. **Create**: Wallet creates transaction with fuzzy timestamp (T ± 2h)
2. **Delay**: Random delay (5-60 min) before broadcast
3. **STEM**: Forward through 1-4 Tor nodes with delays
4. **Mix**: Enter mixing pool, shuffle with other transactions
5. **FLUFF**: Broadcast to network after random batch delay
6. **Confirm**: Included in block by PoS validator

**Result**: Impossible to determine when/where transaction originated

### Timing Obfuscation Example

```rust
use onioncoin_timing::{TimeRange, TimingMetadata, DelayStrategy};

// Create transaction with fuzzy timestamp
let now = Utc::now();
let seed = [42u8; 32];
let timing = TimingMetadata::new(now, &seed)?;

// Timing range: now ± 2-6 hours (random)
// Actual time: provable via ZK proof, but not revealed

// Apply strategic delays
let strategy = DelayStrategy::wallet_broadcast(); // 5-60 min
strategy.sleep().await;
```

## Economic Model

### Genesis Mining (Fair Launch)
- **Phase 1 (6 months)**: 1,000,000 ONC distributed to Tor relay operators
- **NO pre-mine, NO ICO**: Completely fair distribution
- Early participants get 2x bonus (first month), then linear decay to 1x
- Anyone can join by running a Tor relay for OnionCoin traffic

### Regular Emission
- **Emission**: 5 ONC per block (~262,800/year)
- **Max supply**: ~21M ONC (halving every 4 years)
- **Block time**: 10 minutes
- **TPS**: 5-10 tx/s (realistic for Tor bandwidth)

### Validator Tiers

| Tier | Min Stake | Hardware | Monthly Return |
|------|-----------|----------|----------------|
| **Micro** | 10 ONC | Raspberry Pi Zero | ~0.1 ONC |
| **Light** | 100 ONC | Raspberry Pi 4 | ~1 ONC |
| **Standard** | 1000 ONC | Desktop/VPS | ~10 ONC |
| **Power** | 10000 ONC | Server 24/7 | ~100 ONC |

## Running a Node

```bash
# Install Tor
sudo apt install tor

# Run OnionCoin node (becomes a .onion hidden service)
cargo run --bin onioncoin-node

# Your node will have an address like:
# abc123def456.onion:9333
```

## Why OnionCoin?

**Existing cryptocurrencies:**
- Can use Tor as proxy (optional)
- Metadata leakage (timestamps, IP correlation)
- Vulnerable to timing analysis

**OnionCoin:**
- Tor is the **only** network layer
- Timing is deliberately obfuscated as a core feature
- Transaction origin is cryptographically untraceable
- **Rewards Tor relay work** - first crypto to do this!

## Use Cases

✅ **Privacy-preserving payments**
✅ **Censorship-resistant transactions**
✅ **Anonymous donations**
✅ **Darknet markets** (legitimate use)
✅ **Surveillance-free commerce**

## Development Status

🚧 **Prototype/Research Phase**

This is a proof-of-concept implementation demonstrating:
- ✅ Temporal obfuscation protocols
- ✅ Dandelion++ over Tor
- ✅ Privacy-preserving transaction structure
- ✅ **Proof-of-Contribution consensus** (UNIQUE!)
- ✅ **Proof-of-Relay system** (REVOLUTIONARY!)
- ✅ Fair genesis mining

**Not production-ready!** Missing:
- Full cryptographic implementations (ring sigs, bulletproofs)
- Actual Tor integration layer
- Consensus finalization
- Network security hardening

## Technical Specifications

| Parameter | Value |
|-----------|-------|
| Block time | 10 minutes |
| Block size | 2 MB |
| TPS | 5-10 tx/s |
| Consensus | Proof-of-Stake |
| Min stake | 1000 ONC |
| Timestamp range | 2-6 hours |
| STEM hops | 1-4 random |
| Mixing pool delay | 10-30 minutes |

## Building

```bash
cargo build --release
cargo test
```

## Contributing

This is a research/educational project. Contributions welcome:
- Cryptographic implementations
- Tor networking layer
- Performance optimizations
- Security analysis

## License

MIT

## Disclaimer

Educational/research project. Not financial advice. Use at your own risk.

---

**Built with privacy, for privacy. 🧅**