Initial commit: OnionCoin prototype with Proof-of-Relay consensusHEADv0.1.0main

OnionCoin is a privacy cryptocurrency that rewards Tor relay operators
through a unique Proof-of-Contribution consensus mechanism.

Core Features:
- Proof-of-Relay: 30% of block rewards go to Tor operators
- Native .onion node identity (no IP exposure)
- Temporal obfuscation protocols
- Dandelion++ over Tor propagation
- Native inheritance system with dead man's switch

Technical Stack:
- Rust workspace with 8 crates
- Ed25519/X25519 cryptography
- arti (Rust Tor client) integration planned
- 10 minute block time, 5-10 TPS design

Status: Prototype
- Consensus logic complete with passing tests (30/33)
- Network layer conceptual design complete
- Tor integration pending
- Testnet launch planned Q3 2026

License: MIT
Author: Gabriele Salati (virebent)
Contact: g48rix@gmail.com
Website: https://www.gabrielesalati.eu
Repository: https://git.virebent.art/virebent/onioncoin

1 files changed, 489 insertions, 0 deletions

diff --git a/INHERITANCE.md b/INHERITANCE.md
new file mode 100644
index 0000000..e8ef009
--- /dev/null
+++ b/INHERITANCE.md
@@ -0,0 +1,489 @@
+# OnionCoin Inheritance System
+
+## World's First Native Blockchain Inheritance Protocol
+
+> **$140+ billion in Bitcoin is lost forever** because owners died without access plans.
+>
+> OnionCoin solves this with inheritance **built into the blockchain**, not a third-party service.
+
+---
+
+## The Problem
+
+### Current Solutions Are Broken
+
+❌ **Write down seed phrase**: Family finds it, steals funds before you die
+❌ **Give to lawyer**: They can access anytime, or company goes bankrupt
+❌ **Third-party services**: Centralized, hackable, require trust
+❌ **Dead man's switch**: Too fragile, false triggers common
+❌ **Do nothing**: **$140B+ lost forever**
+
+### Why OnionCoin Is Different
+
+✅ **Native blockchain protocol** (not external service)
+✅ **Progressive unlock** (gradual release, time to dispute)
+✅ **Privacy-preserving** (via Tor + encryption)
+✅ **Anti-scam protections** (dispute system)
+✅ **Shamir secret sharing** (distribute trust)
+✅ **No lawyers required** (fully automated)
+
+---
+
+## How It Works
+
+### 1. Create Inheritance Contract
+
+```rust
+let beneficiaries = vec![
+    Beneficiary::new(wife_pubkey, 70),     // 70% to wife
+    Beneficiary::new(child_pubkey, 30),    // 30% to child
+];
+
+let contract = InheritanceContract::new(
+    owner_pubkey,
+    beneficiaries,
+    InheritanceConfig::default(),  // 90 days + 30 days grace
+    locked_amount,
+);
+```
+
+**Contract is stored on-chain**, immutable and transparent.
+
+### 2. Send Regular Heartbeats
+
+Owner must "check in" periodically to prove they're alive:
+
+```rust
+// Every 90 days (configurable)
+heartbeat_manager.process_heartbeat(&mut contract, current_time);
+```
+
+**Heartbeat = Send 0.00000001 ONC to yourself**
+- Privacy-preserving (looks like normal transaction)
+- Can be done via Tor for extra anonymity
+- Simple: Just use your wallet!
+
+### 3. Grace Period (Safety Net)
+
+If heartbeat is missed:
+
+```
+Day 0-90:   Normal period (heartbeat expected)
+Day 90-120: GRACE PERIOD (30 days warning)
+            ↓
+            - Owner gets critical warning notifications
+            - Beneficiaries get info notification
+            - Still time to send heartbeat!
+Day 120+:   Progressive unlock begins
+```
+
+### 4. Progressive Unlock (REVOLUTIONARY!)
+
+Unlike traditional dead man's switches that release everything at once, OnionCoin uses **gradual unlock**:
+
+#### Standard 4-Tier Schedule
+
+| Tier | Days After Grace | Unlock % | Cumulative | Amount (100K ONC) |
+|------|------------------|----------|------------|-------------------|
+| 1    | 30 days         | 10%      | 10%        | 10,000 ONC        |
+| 2    | 60 days         | 25%      | 35%        | 25,000 ONC        |
+| 3    | 90 days         | 35%      | 70%        | 35,000 ONC        |
+| 4    | 120 days        | 30%      | 100%       | 30,000 ONC        |
+
+**Why Progressive?**
+
+Imagine you're in a coma for 2 months:
+- ❌ **Traditional**: ALL funds gone when you wake up
+- ✅ **OnionCoin**: Only 35% unlocked, you can **dispute and recover 65%**!
+
+### 5. Dispute System (If You're Still Alive!)
+
+If owner recovers (hospital, lost keys, etc.):
+
+```rust
+recovery_manager.file_dispute(
+    &mut contract,
+    owner_pubkey,
+    DisputeReason::TemporaryIncapacitation,
+);
+
+// Add evidence
+recovery_manager.add_evidence(
+    &contract_id,
+    Evidence {
+        evidence_type: EvidenceType::MedicalCertificate,
+        data: encrypted_cert,
+    }
+);
+```
+
+**Protections**:
+- Maximum 3 disputes (prevent abuse)
+- 7-day cooldown between disputes
+- Evidence required (proof of life)
+- Can freeze contract pending investigation
+
+**Resolution Options**:
+- Reset heartbeat (owner proven alive)
+- Extend grace period (temporary incapacitation)
+- Cancel unlock (false alarm)
+- Proceed with unlock (dispute invalid)
+
+---
+
+## Advanced Features
+
+### Shamir Secret Sharing (3-of-5)
+
+Distribute seed phrase recovery among trusted guardians:
+
+```rust
+// Split seed among 5 people
+// Any 3 can recover, but 2 or fewer cannot
+
+let distribution = ShareDistribution::standard_3_of_5(guardians);
+let shares = distribution.generate_shares(seed_phrase)?;
+
+// Give each guardian their encrypted share
+```
+
+**Use Case**: Family doesn't know crypto but trusted friends do
+- Give 5 shares to: lawyer, colleague, friend, sibling, advisor
+- When you die, family contacts any 3 to recover
+
+**Security**:
+- No single person can steal funds
+- Requires collusion of 3+ people
+- Redundancy: Can lose 2 shares and still recover
+
+### Multi-Signature Requirements
+
+For high-value contracts:
+
+```rust
+let config = InheritanceConfig {
+    multi_sig_required: true,
+    required_signatures: 2,  // Need 2 of 3 beneficiaries
+    ..Default::default()
+};
+```
+
+Prevents single beneficiary from claiming everything.
+
+### Encrypted Beneficiary List
+
+Privacy mode: Beneficiaries are encrypted on-chain
+
+```rust
+let config = InheritanceConfig {
+    encrypted_beneficiaries: true,
+    ..Default::default()
+};
+```
+
+Only owner and (eventually) beneficiaries can see who inherits.
+
+### Tor-Only Heartbeat
+
+Maximum privacy:
+
+```rust
+let config = InheritanceConfig {
+    tor_only: true,  // Heartbeat must come via Tor
+    ..Default::default()
+};
+```
+
+Prevents IP-based tracking of owner.
+
+---
+
+## Configuration Presets
+
+### Quick Config (Urgent)
+```rust
+InheritanceConfig::quick()
+// - 30 day heartbeat interval
+// - 7 day grace period
+// - Progressive unlock enabled
+```
+
+### Standard Config (Recommended)
+```rust
+InheritanceConfig::default()
+// - 90 day heartbeat interval
+// - 30 day grace period
+// - Progressive unlock enabled
+// - Tor-only heartbeat
+```
+
+### Secure Config (Maximum Protection)
+```rust
+InheritanceConfig::secure()
+// - 180 day heartbeat interval
+// - 60 day grace period
+// - Progressive unlock enabled
+// - Multi-sig required
+// - Shamir 3-of-5 enabled
+```
+
+---
+
+## Security Features
+
+### Anti-Scam Protections
+
+1. **Maximum Disputes**: Owner can only file 3 disputes total
+2. **Dispute Cooldown**: 7 days between disputes
+3. **Evidence Required**: Must provide proof of life
+4. **Suspicious Activity Detection**:
+   - Multiple failed recovery attempts
+   - Many different parties trying to access
+   - Rapid succession of attempts
+
+5. **Recovery Attempt Logging**: All attempts are recorded
+
+### Privacy Protections
+
+1. **Tor Integration**: All heartbeats can be via Tor
+2. **Encrypted Beneficiaries**: On-chain list is encrypted
+3. **Fuzzy Timestamps**: Timing metadata obfuscated
+4. **No Metadata Leakage**: Can't tell it's inheritance contract
+
+---
+
+## Real-World Scenarios
+
+### Scenario 1: Natural Death
+
+1. Owner stops sending heartbeats
+2. 90 days pass → Grace period starts
+3. 30 more days → Grace period expires
+4. Progressive unlock begins:
+   - Day 150: 10% to beneficiaries
+   - Day 180: 25% more (35% total)
+   - Day 210: 35% more (70% total)
+   - Day 240: 30% more (100% total)
+5. Inheritance complete
+
+**Total time**: ~8 months from last heartbeat to full distribution
+
+### Scenario 2: Medical Emergency
+
+1. Owner hospitalized, can't send heartbeat
+2. Grace period expires
+3. Unlock begins, 10% released
+4. Owner recovers after 2 months
+5. **Files dispute** with medical certificate
+6. Only 35% was unlocked, **65% recovered!**
+7. Heartbeat reset, contract continues
+
+**Owner saved**: 65% of funds that would be lost with traditional systems
+
+### Scenario 3: Lost Keys
+
+1. Owner loses hardware wallet
+2. Can't send heartbeat
+3. Uses **Shamir recovery**:
+   - Contacts 3 of 5 guardians
+   - Recovers seed phrase
+   - Regains access
+   - Sends heartbeat
+4. Contract continues normally
+
+**Redundancy saved the day**
+
+### Scenario 4: Attempted Theft
+
+1. Malicious beneficiary tries to access funds early
+2. Makes multiple recovery attempts
+3. **Suspicious activity detected**
+4. Owner receives alerts
+5. Owner sends heartbeat + **files dispute**
+6. Contract frozen pending investigation
+7. Malicious beneficiary identified
+8. Owner removes them and adds new beneficiary
+
+**Anti-scam protections worked**
+
+---
+
+## Comparison
+
+| Feature | Bitcoin (nothing) | Centralized Service | OnionCoin Inheritance |
+|---------|-------------------|---------------------|----------------------|
+| **Trustless** | ✅ (but lost) | ❌ Requires trust | ✅ On-chain protocol |
+| **Privacy** | ✅ | ❌ KYC required | ✅ Tor + encryption |
+| **Progressive Unlock** | ❌ | ❌ | ✅ **Unique!** |
+| **Dispute System** | ❌ | ⚠️ Manual process | ✅ **Built-in** |
+| **No Third Party** | ✅ | ❌ | ✅ |
+| **Cost** | Free | $$$ subscription | Gas fees only |
+| **Shamir Sharing** | ❌ DIY | ⚠️ Some services | ✅ **Native** |
+| **Tor Compatible** | ⚠️ Optional | ❌ | ✅ **Required** |
+
+---
+
+## Economic Model
+
+### Contract Creation
+
+- **Minimum Lock**: 10 ONC
+- **Gas Fee**: ~0.001 ONC for contract creation
+- **Heartbeat Fee**: ~0.00000001 ONC per heartbeat
+
+### Example Costs (500,000 ONC inheritance)
+
+```
+Contract Creation:     0.001 ONC     ($0.10 assuming $100/ONC)
+10 Years of Heartbeats: 0.0004 ONC   ($0.04)
+Total Cost:            ~0.0014 ONC   ($0.14)
+```
+
+Compare to:
+- Lawyer: $3,000 - $10,000
+- Centralized service: $120/year = $1,200 over 10 years
+- Lost funds: **$50,000,000** (value of 500K ONC)
+
+**OnionCoin inheritance costs 99.999% less than alternatives!**
+
+---
+
+## Technical Implementation
+
+See `/inheritance` module for full implementation:
+
+- `contract.rs` - Time-locked inheritance contracts
+- `unlock.rs` - Progressive unlock mechanism
+- `heartbeat.rs` - Heartbeat monitoring system
+- `secret_sharing.rs` - Shamir secret sharing
+- `recovery.rs` - Dispute resolution & anti-scam
+
+---
+
+## Roadmap
+
+### Phase 1 ✅ (Current)
+- ✅ Time-locked contracts
+- ✅ Progressive unlock
+- ✅ Heartbeat system
+- ✅ Shamir secret sharing
+- ✅ Dispute resolution
+
+### Phase 2 (Next)
+- Multi-sig beneficiary claims
+- Oracle integration (death certificates)
+- Mobile app for heartbeats
+- Email/SMS notifications
+
+### Phase 3 (Future)
+- Conditional inheritance (age-gating)
+- Recurring payments to beneficiaries
+- NFT/asset inheritance
+- Cross-chain inheritance
+
+---
+
+## Usage Examples
+
+### Create Simple Contract
+
+```rust
+use onioncoin_inheritance::*;
+
+// Create beneficiaries
+let beneficiaries = vec![
+    Beneficiary::new(spouse_key, 100).unwrap(),
+];
+
+// Create contract
+let mut contract = InheritanceContract::new(
+    owner_key,
+    beneficiaries,
+    InheritanceConfig::default(),
+    100_000, // Lock 100,000 ONC
+    current_time,
+).unwrap();
+```
+
+### Send Heartbeat
+
+```rust
+// Simple heartbeat transaction
+let tx = HeartbeatManager::create_heartbeat_tx(owner_key);
+
+// Or use heartbeat manager
+heartbeat_manager.process_heartbeat(&mut contract, current_time)?;
+```
+
+### Setup Shamir Shares
+
+```rust
+let guardians = vec![key1, key2, key3, key4, key5];
+let distribution = ShareDistribution::standard_3_of_5(guardians)?;
+let shares = distribution.generate_shares(seed_phrase)?;
+
+// Distribute shares to guardians
+for (guardian, share) in shares {
+    send_encrypted_share(guardian, share);
+}
+```
+
+### File Dispute
+
+```rust
+recovery_manager.file_dispute(
+    &mut contract,
+    owner_key,
+    DisputeReason::TemporaryIncapacitation,
+    current_time,
+)?;
+
+// Add proof of life
+let evidence = Evidence {
+    evidence_type: EvidenceType::ProofOfLife,
+    data: signed_message,
+    submitted_at: current_time,
+};
+
+recovery_manager.add_evidence(&contract.contract_id, evidence)?;
+```
+
+---
+
+## Demo
+
+Run the full inheritance demo:
+
+```bash
+cargo run --example inheritance_demo
+```
+
+This shows:
+- Contract creation
+- Progressive unlock
+- Heartbeat system
+- Shamir secret sharing
+- Dispute resolution
+- Complete inheritance scenario
+
+---
+
+## Conclusion
+
+OnionCoin's inheritance system is **revolutionary** because:
+
+1. ✅ **First cryptocurrency** with native blockchain inheritance
+2. ✅ **Progressive unlock** prevents total loss if owner recovers
+3. ✅ **Privacy-first** (Tor, encryption, obfuscation)
+4. ✅ **Anti-scam protections** (disputes, activity monitoring)
+5. ✅ **Shamir sharing** for distributed trust
+6. ✅ **Fully automated** (no lawyers, no courts)
+7. ✅ **Costs $0.14** for 10 years (vs $10,000 for lawyers)
+
+**This solves the $140 billion problem that Bitcoin created.**
+
+No other cryptocurrency has this. OnionCoin does.
+
+---
+
+**🎉 The Future of Crypto Inheritance Is Here!**