diff options
Diffstat (limited to 'INHERITANCE.md')
| -rw-r--r-- | INHERITANCE.md | 489 |
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!** |