Збирачі Даних (Data Harvesters)

Модуль Crypto використовує 3 збирачі даних для збору інформації в реальному часі із зовнішніх API.

🏗️ Архітектура

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  CoinGecko   │     │   GitHub     │     │  DefiLlama   │
│  Harvester   │     │  Harvester   │     │  Harvester   │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────┐
│                     Redis Cache                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │ coingecko:  │  │ github:     │  │ defillama:  │     │
│  │ SLUG        │  │ REPO        │  │ PROTOCOL    │     │
│  │ TTL: 24h    │  │ TTL: 24h    │  │ TTL: 6h     │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────┘

---

1. Збирач даних CoinGecko (CoinGecko Harvester)

File: coingecko.py

Призначення: Отримує ціну, ринкові дані та метадані.

Зібрані дані (Data Collected)

Поле	Опис	Приклад
price_usd	Поточна ціна в USD	245.50
market_cap	Загальна ринкова капіталізація	3,650,000,000
fdv	Повністю розбавлена оцінка (Fully Diluted Valuation)	4,100,000,000
price_change_24h	% зміни за 24 години	-2.5
github_url	URL основного репозиторію	github.com/aave
homepage	Веб-сайт проєкту	aave.com

Деталі API (API Details)

• Endpoint: https://api.coingecko.com/api/v3/coins/ID
• Rate Limit: 50 запитів/хвилину (безкоштовний рівень)
• Cache TTL: 24 години
• Cost: Безкоштовно

Використання (Usage)

from harvesters.coingecko import CoinGeckoHarvester

harvester = CoinGeckoHarvester()
data = await harvester.fetch("aave")

# Повертає:
{
    "price_usd": 245.50,
    "market_cap": 3650000000,
    "fdv": 4100000000,
    "github_url": "https://github.com/aave"
}

Відомі проблеми (Known Issues)

Застарілі URL-адреси GitHub: CoinGecko іноді повертає старі URL-адреси репозиторіїв. Ми підтримуємо мапування перевизначень:

GITHUB_OVERRIDES = {
    "aave": "https://github.com/aave/aave-v3-core",
    "compound": "https://github.com/compound-finance/compound-v2",
}

---

2. Збирач даних GitHub (GitHub Harvester)

File: github.py

Призначення: Отримує метрики активності розробників.

Зібрані дані (Data Collected)

Поле	Опис	Приклад
commits_30d	Комміти за останні 30 днів	45
active_devs	Унікальні дописувачі (30 днів)	12
last_commit_date	Остання дата комміту	2025-12-25
total_stars	Зірки репозиторію (Stars)	2,500
open_issues	Кількість відкритих задач (Issues)	48

Деталі API (API Details)

• Endpoint: https://api.github.com/repos/OWNER/REPO
• Stats Endpoint: https://api.github.com/repos/OWNER/REPO/stats/participation
• Rate Limit: 5 000 запитів/годину (з аутентифікацією)
• Cache TTL: 24 години
• Cost: Безкоштовно

Асинхронна обробка статистики (Async Stats Handling)

Великі репозиторії спочатку повертають 202 NO CONTENT – статистика обчислюється асинхронно:

async def fetch_stats(self, repo):
    response = await self.client.get(f"/repos/REPO/stats/participation")
    
    if response.status_code == 202:
        # GitHub обчислює статистику, повторіть спробу після затримки
        await asyncio.sleep(2)
        return await self.fetch_stats(repo)
    
    return response.json()

Запасний варіант для відсутніх репозиторіїв (Fallback for Missing Repos)

if not github_url or github_url == "":
    return {
        "commits_30d": 0,
        "active_devs": 0,
        "error": "No public repository found" # Публічний репозиторій не знайдено
    }

---

3. Збирач даних DefiLlama (DefiLlama Harvester)

File: defillama.py

Призначення: Отримує DeFi-специфічні метрики (TVL, казначейство).

Зібрані дані (Data Collected)

Поле	Опис	Приклад
tvl	Загальна заблокована вартість (Total Value Locked, USD)	32,400,000,000
chain_tvls	Розподіл TVL за блокчейном	ethereum: 25B, polygon: 5B
category	Категорія DeFi	"Lending"
mcap_to_tvl_ratio	Відношення ринкової капіталізації до TVL (Market Cap / TVL)	0.09

Деталі API (API Details)

• Endpoint: https://api.llama.fi/protocol/SLUG
• TVL History: https://api.llama.fi/protocol/SLUG/tvl
• Rate Limit: Безлімітно (не потрібен ключ)
• Cache TTL: 6 годин (TVL змінюється швидше)
• Cost: Безкоштовно ✅

Мапування Slug (Slug Mapping)

DefiLlama використовує інші slugs, ніж CoinGecko. Ми підтримуємо мапування:

DEFILLAMA_SLUGS = {
    "aave": "aave",
    "uniswap": "uniswap",
    "compound-governance-token": "compound",
}

Приклад відповіді (Example Response)

{
  "tvl": 32451269361,
  "chainTvls": {
    "Ethereum": 25000000000,
    "Polygon": 5000000000,
    "Avalanche": 2451269361
  },
  "category": "Lending",
  "mcap": 2900000000
}

---

🔄 Конвеєр збору даних (Harvesting Pipeline)

Коли запитується проєкт, CryptoService координує роботу всіх збирачів даних:

async def fetch_project(self, slug: str):
    # 1. Спочатку перевірити кеш
    cached = await self.cache.get(f"project:{slug}")
    if cached:
        return cached
    
    # 2. Отримати дані з усіх джерел паралельно
    coingecko_data, github_data, defillama_data = await asyncio.gather(
        self.coingecko.fetch(slug),
        self.github.fetch(slug),
        self.defillama.fetch(slug)
    )
    
    # 3. Об'єднати дані
    project = self.merge_data(coingecko_data, github_data, defillama_data)
    
    # 4. Розрахувати Trust Score
    project["trust_score"] = self.risk_engine.calculate(project)
    project["risk_level"] = self.risk_engine.get_risk_level(project["trust_score"])
    
    # 5. Зберегти в базу даних
    await self.db.upsert(project)
    
    # 6. Кешувати для наступного запиту
    await self.cache.set(f"project:{slug}", project, ttl=3600)
    
    return project

---

⚡ Продуктивність (Performance)

Метрика	Свіжий запит	Кешовано
Загальний час	2-3 секунди	менше 50 мс
CoinGecko	~800ms	-
GitHub	~1.2s	-
DefiLlama	~500ms	-

Коефіцієнт влучання в кеш (Cache Hit Rates)

• CoinGecko: ~90%
• GitHub: ~85%
• DefiLlama: ~75%

---

🚀 Майбутні збирачі даних (в планах)

Збирач даних CryptoRank (CryptoRank Harvester)

• Дані: Раунди залучення коштів, VC інвестори, розблокування токенів
• Метод: Веб-скрейпінг (безкоштовного API немає)
• Призначення: Основа токеноміки (Tokenomics pillar)

Збирач даних TwitterScore (TwitterScore Harvester)

• Дані: Якість підписників, виявлення ботів, залученість
• Призначення: Основа спільноти (Community pillar)

Збирач даних Discord/Telegram (Discord/Telegram Harvester)

• Дані: Кількість учасників, активність, настрої
• Призначення: Основа спільноти (Community pillar)

---

Всі збирачі даних розроблені для безкоштовної роботи з використанням безкоштовних рівнів API.