path: root/INHERITANCE.md

# 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!**