Skip to content

AI_IMPLEMENTATION.md

Latest commit

 

History

History
471 lines (338 loc) · 10.4 KB

AI_IMPLEMENTATION.md

File metadata and controls

471 lines (338 loc) · 10.4 KB
Raw

🤖 AI Destekli Ölüm Tespiti ve Vasiyet İcrası - Implementation Guide

📋 Genel Bakış

Bu proje, blockchain tabanlı dijital vasiyet sistemine AI destekli ölüm tespiti ve otomatik mirasçı belirleme özellikleri ekler.

Temel Özellikler

  1. Risk Skorlama Sistemi (0-100%)

    • Blockchain aktivite analizi (Etherscan API)
    • Uygulama aktivite takibi
    • Doğrulama bildirimleri

  2. Heir Discovery (Mirasçı Tespiti)

    • Blockchain işlem geçmişi analizi
    • En sık ve en son transfer yapılan adresleri bulma
    • Skorlama algoritması ile en uygun mirasçıyı belirleme

  3. Smart Contract Entegrasyonu

    • AI tarafından belirlenen mirasçıyı otomatik ekleme
    • Deceased status ayarlama
    • Will execution

🏗️ Mimari

1. Smart Contract (Solidity)

Dosya: contracts/contracts/DigitalWill.sol

Yeni Fonksiyon: setDefaultBeneficiaryByAI

function setDefaultBeneficiaryByAI(uint256 willId, address determinedHeir)
    external
    onlyOwner
    willExists(willId)
{
    require(beneficiaries[willId].length == 0, "Beneficiaries already exist");
    require(determinedHeir != address(0), "Invalid heir address");
    require(wills[willId].isDeceased, "Owner must be deceased first");
    require(!wills[willId].isExecuted, "Will already executed");

    beneficiaries[willId].push(Beneficiary({
        beneficiaryAddress: determinedHeir,
        sharePercentage: 10000, // 100%
        hasClaimed: false,
        hasClaimedETH: false
    }));

    emit AIBeneficiarySet(willId, wills[willId].owner, determinedHeir, block.timestamp);
}

Önemli:

  • Bu fonksiyon sadece contract owner (backend/AI servisi) tarafından çağrılabilir
  • Mirasçı listesi boş olmalı
  • Kullanıcı önce deceased olarak işaretlenmiş olmalı

2. Death Detection Service (Dart)

Dosya: lib/data/services/death_detection_service.dart

Ana Sınıf: DeathDetectionService

Risk Skorlama Algoritması
Future<RiskAnalysisResult> analyzeUserActivityStatus({
  required String userAddress,
  required int willId,
  DateTime? lastAppActivity,
  bool? hasRespondedToVerification,
})

Risk Skorları:

  • 0% → Kullanıcı aktif (Blockchain aktivitesi var)
  • 20% → Düşük şüphe (Sadece uygulama aktivitesi var)
  • 80% → Yüksek şüphe (6+ ay inaktif, doğrulama bekleniyor)
  • 100% → Deceased (Tüm kriterler karşılandı)

Veri Kaynakları:

  1. Blockchain Aktivitesi (Etherscan API)

    • Son 1 ay içinde outgoing transaction var mı?
    • En son işlem tarihi

  2. Uygulama Aktivitesi

    • Son giriş zamanı
    • 180 gün eşiği

  3. Doğrulama Yanıtı

    • 7 gün içinde yanıt verildi mi?
Heir Discovery (Mirasçı Tespiti)
Future<String?> discoverHeirFromBlockchainHistory(String userAddress)

Algoritma:

  1. Etherscan API'den son 1000 işlemi çek

  2. Outgoing transactions filtrele (from == userAddress)

  3. Her adres için istatistik topla:

    • İşlem sayısı
    • Toplam transfer miktarı
    • En son işlem zamanı

  4. Skorlama:

    Score = (txCount * 0.3) + (totalValue * 0.4) + (recency * 0.3)

  5. En yüksek skoru olan adres = Mirasçı

Örnek:

// Kullanım
final deathService = Provider.of<DeathDetectionService>(context, listen: false);

// Risk analizi
final riskResult = await deathService.analyzeUserActivityStatus(
  userAddress: '0x123...',
  willId: 1,
  lastAppActivity: DateTime(2024, 1, 1),
  hasRespondedToVerification: false,
);

print('Risk Score: ${riskResult.riskScore}%');
print('Recommendation: ${riskResult.recommendation}');

// Mirasçı tespiti
if (riskResult.riskScore == 100) {
  final heir = await deathService.discoverHeirFromBlockchainHistory('0x123...');
  print('Determined Heir: $heir');
}

3. Web3 Service Integration (Dart)

Dosya: lib/data/services/web3_service.dart

Yeni Fonksiyonlar

1. setDefaultBeneficiaryByAI
Future<String> setDefaultBeneficiaryByAI({
  required int willId,
  required String determinedHeirAddress,
  required Credentials ownerCredentials, // Backend private key
})

⚠️ Önemli: Bu fonksiyon backend servisi tarafından çağrılmalı!

2. getBeneficiaryCount
Future<int> getBeneficiaryCount(int willId)

Bir will'in kaç mirasçısı olduğunu kontrol eder.

3. executeAIWorkflow

Tam AI iş akışını çalıştırır:

Future<Map<String, String>> executeAIWorkflow({
  required int willId,
  required String determinedHeirAddress,
  required Credentials ownerCredentials,
})

Adımlar:

  1. setDefaultBeneficiaryByAI() → Mirasçı ekle
  2. setDeceasedStatus() → Deceased olarak işaretle
  3. executeWill() → Vasiyeti gerçekleştir

🚀 Kullanım Senaryosu

Backend/AI Servisi İş Akışı

// 1. Risk Analizi Yap
final deathService = DeathDetectionService(web3Service: web3);

final riskResult = await deathService.analyzeUserActivityStatus(
  userAddress: userWalletAddress,
  willId: willId,
  lastAppActivity: lastAppActivity,
  hasRespondedToVerification: false,
);

// 2. Risk %100 ise ve mirasçı yoksa
if (riskResult.riskScore == 100) {
  final beneficiaryCount = await web3.getBeneficiaryCount(willId);

  if (beneficiaryCount == 0) {
    // 3. Mirasçı Bul
    final heir = await deathService.discoverHeirFromBlockchainHistory(
      userWalletAddress,
    );

    if (heir != null) {
      // 4. Backend Credentials ile AI Workflow Çalıştır
      final backendCredentials = EthPrivateKey.fromHex(backendPrivateKey);

      final txHashes = await web3.executeAIWorkflow(
        willId: willId,
        determinedHeirAddress: heir,
        ownerCredentials: backendCredentials,
      );

      print('✅ AI Workflow Completed!');
      print('TX Hashes: $txHashes');
    }
  }
}

🔧 Kurulum ve Konfigürasyon

1. Environment Variables

.env dosyasına ekle:

# Etherscan API (Ücretsiz: https://etherscan.io/myapikey)
ETHERSCAN_API_KEY=YOUR_ETHERSCAN_API_KEY

2. Smart Contract Deploy

cd contracts
npx hardhat compile
npx hardhat run scripts/deploy.js --network sepolia

Contract address'i .env dosyasına ekle:

CONTRACT_ADDRESS=0x...

3. Flutter Dependencies

Zaten yüklü:

  • ✅ dio (HTTP requests)
  • ✅ web3dart (Blockchain)
  • ✅ flutter_dotenv (Environment variables)

📊 Veri Modelleri

RiskAnalysisResult

class RiskAnalysisResult {
  final int riskScore; // 0-100
  final BlockchainActivityInfo? blockchainActivity;
  final int appInactiveDays;
  final String recommendation; // USER_ACTIVE, REQUEST_VERIFICATION, etc.
  final DateTime analysisTime;
  final String? error;
}

BlockchainActivityInfo

class BlockchainActivityInfo {
  final bool hasRecentActivity;
  final DateTime? lastTransactionDate;
  final int transactionCount;
  final int? daysSinceLastTransaction;
}

AIProcessResult

class AIProcessResult {
  final bool success;
  final RiskAnalysisResult? riskAnalysis;
  final String? determinedHeir;
  final String message;
}

⚙️ Konfigürasyon Parametreleri

Risk Eşikleri

// death_detection_service.dart
static const Duration APP_ACTIVITY_THRESHOLD = Duration(days: 180); // 6 ay
static const Duration BLOCKCHAIN_ACTIVITY_THRESHOLD = Duration(days: 30); // 1 ay
static const Duration VERIFICATION_RESPONSE_TIMEOUT = Duration(days: 7);

Bu değerleri projeye göre özelleştirebilirsiniz.

🔐 Güvenlik Notları

1. Backend Private Key

ÇOK ÖNEMLİ: setDefaultBeneficiaryByAI fonksiyonu contract owner tarafından çağrılmalı.

  • Backend servisinizin private key'ini asla Flutter uygulamasına koymayın
  • Backend servisi ayrı bir Node.js/Python backend olmalı
  • Private key environment variable olarak saklanmalı

2. API Key Güvenliği

# .gitignore'da olduğundan emin olun
.env
.env.local
.env.*.local

3. Rate Limiting

Etherscan API ücretsiz planda:

  • 5 calls/second
  • 100,000 calls/day

Çok fazla çağrı yapmayın, cache kullanın.

🧪 Test Senaryoları

Test 1: Risk Analizi

test('Risk score %100 when inactive 6+ months and no verification', () async {
  final service = DeathDetectionService(web3Service: mockWeb3);

  final result = await service.analyzeUserActivityStatus(
    userAddress: testAddress,
    willId: 1,
    lastAppActivity: DateTime.now().subtract(Duration(days: 200)),
    hasRespondedToVerification: false,
  );

  expect(result.riskScore, equals(100));
  expect(result.recommendation, contains('DECEASED'));
});

Test 2: Heir Discovery

test('Discovers most frequent transaction recipient', () async {
  final service = DeathDetectionService(web3Service: mockWeb3);

  final heir = await service.discoverHeirFromBlockchainHistory(testAddress);

  expect(heir, isNotNull);
  expect(heir, startsWith('0x'));
});

📚 API Referansı

Etherscan API

Base URL (Sepolia):

https://api-sepolia.etherscan.io/api

Get Transactions:

GET /api?module=account&action=txlist&address=0x...&apikey=...

Response:

{
  "status": "1",
  "result": [
    {
      "from": "0x...",
      "to": "0x...",
      "value": "1000000000000000000",
      "timeStamp": "1234567890"
    }
  ]
}

🐛 Troubleshooting

Hata: "Etherscan API key not configured"

Çözüm: .env dosyasına ETHERSCAN_API_KEY ekleyin.

Hata: "Beneficiaries already exist"

Çözüm: Bu will için zaten mirasçı tanımlı. AI sadece mirasçısız will'ler için çalışır.

Hata: "Owner must be deceased first"

Çözüm: setDeceasedStatus fonksiyonunu önce çağırın.

🎯 Gelecek Geliştirmeler

  • Bildirim Sistemi (Firebase Cloud Messaging)

    • "Hayatta mısınız?" push notification
    • Email/SMS entegrasyonu

  • ML Model Entegrasyonu

    • TensorFlow Lite ile anomali tespiti
    • Kullanıcı davranış pattern'lerini öğrenme

  • Multi-chain Support

    • Polygon, BSC, Avalanche desteği
    • Cross-chain mirasçı tespiti

  • Legal Compliance

    • Dijital imza entegrasyonu
    • Notary verification

📞 Destek

Sorularınız için:

📄 Lisans

MIT License - Detaylar için LICENSE dosyasına bakın.

Son Güncelleme: 2025-11-25 Versiyon: 2.0.0 (AI Integration)