Документація Ноди DSRCH

Повна технічна документація з запуску, налаштування та керування нодою децентралізованого пошуку DSRCH.

Огляд

DSRCH (Decentralized Search Ranking Consensus Hypernetwork) — це спеціалізований блокчейн Layer 1 для децентралізованого веб-пошуку. Кожна нода сканує веб, будує локальний пошуковий індекс, обслуговує запити та отримує токени DSRCH через консенсус Proof-of-Index.

Архітектура

Швидкий старт

Варіант 1: З бінарного файлу

# Збірка з вихідного коду
cd dsrch && go build -o dsrchd ./cmd/dsrchd

# Ініціалізація ноди
./dsrchd init --mode full --port 9090

# Запуск ноди
./dsrchd start --api-port 8080 --epoch-duration 30s

Варіант 2: Docker

# Збірка та запуск
docker build -t dsrch-node .
docker run -d --name dsrch \
  -p 8080:8080 -p 9090:9090 \
  -v dsrch-data:/home/dsrch/.dsrch \
  --restart unless-stopped \
  dsrch-node start --api-port 8080 --epoch-duration 30s

Варіант 3: Docker Compose (тестнет з 3 нод)

docker compose up -d

CLI Довідка

dsrch init

Ініціалізація нової ноди DSRCH. Генерує ключову пару Ed25519 та конфігурацію за замовчуванням.

Згенеровані файли:

~/.dsrch/
├── config.yaml    # Конфігурація ноди
└── node.key       # Приватний ключ Ed25519 (зберігайте надійно!)

dsrch start

Запуск повної ноди DSRCH з усіма підсистемами.

dsrch status

Відображення поточного статусу ноди та кількості документів.

Конфігурація

Конфігурація зберігається в ~/.dsrch/config.yaml:

node:
  mode: "full"           # light | full | validator
  dataDir: "/home/user/.dsrch"
  apiPort: 8080

p2p:
  listenPort: 9090
  bootstrapPeers: []
  enableMDNS: true
  enableDHT: true
  externalIP: ""         # Public IP for NAT/Docker

Режими ноди

Директорія даних

~/.dsrch/
├── config.yaml      # Конфігурація
├── node.key         # Приватний ключ Ed25519
├── index/           # Повнотекстовий індекс Bluge
├── state.json       # Стан блокчейну
└── query.log        # Журнал пошукових запитів

API Довідка

Base URL: https://api.dsrch.net · Повна інтерактивна документація: api.dsrch.net

Пошук

curl "https://api.dsrch.net/api/search?q=ukraine&limit=5"

Статус ноди

{
  "nodeId": "12D3KooW...",
  "status": "running",
  "documents": 2921,
  "version": "329.11.81",
  "chainId": "dsrch-mainnet-1"
}

Мережа

Епоха та консенсус

Стейкінг

Управління

Краулер

curl -X POST "https://api.dsrch.net/api/crawl/add?url=https://example.com&depth=3&maxPages=200"

Інструменти вебмайстра

Інші ендпоінти

P2P Мережа

DSRCH uses libp2p для всього пірингового зв'язку.

Протоколи

Виявлення пірів

• DHT — Розподілена хеш-таблиця Kademlia для глобального виявлення
• mDNS — Виявлення в локальній мережі (розробка/LAN)
• Bootstrap peers — Захардкоджені seed-ноди для початкового підключення
• Periodic discovery — Виконується кожні 30 секунд

Рушій краулера

Компоненти

Авто-сідер

Забезпечує безперервну індексацію, надаючи нові URL коли черга порожня:

• 56+ курованих джерел: Wikipedia (UK, EN, DE, FR, ES, PL, JA), BBC, DW, Reuters, Українські ЗМІ, техсайти, наукові журнали, блокчейн-ресурси
• Виявлення посилань: Зовнішні посилання зі сканованих сторінок автоматично стають новими seed-ами
• Дедуплікація доменів: Кожен домен сканується лише раз
• Інтеграція блоклісту: Державні ЗМІ РФ, Китаю, КНДР, Ірану та Білорусі заблоковані

Параметри сканування

Пошук та індексація

• Bluge — Високопродуктивний повнотекстовий пошуковий рушій на Go
• Scatter-Gather — Розподілений пошук між шард-нодами з консистентним хеш-маршрутизуванням
• Index Replication — Синхронізація на основі маніфесту кожні 2 хвилини + синхронізація за подіями
• Autocomplete — На основі заголовків проіндексованих сторінок

Консенсус: Proof-of-Index

DSRCH використовує власний механізм консенсусу Proof-of-Index.

Епохи

Default duration: 1 hour (configurable, 30s для тестнету). At epoch end, each node generates a Work Report:

{
  "nodeId": "12D3KooW...",
  "epoch": 42,
  "pageCount": 150,
  "queriesServed": 89,
  "avgLatency": "15ms",
  "shardsStored": 3,
  "crawlMerkle": "a1b2c3d4..."
}

Процес валідації

1. Нода сканує сторінки та обслуговує запити впродовж епохи
2. Активність відстежується через ActivityTracker
3. В кінці епохи звіт генерується та транслюється через GossipSub
4. DSRCHApp.ProcessEpochWithValidation валідує всі звіти
5. Валідні ноди отримують винагороди в токенах DSRCH
6. Стан зберігається на диск

Модулі блокчейну

Управління

DSRCH має ончейн-управління для оновлення протоколу та зміни параметрів.

• Голосувати можуть лише ноди зі стейком
• Варіанти голосування: yes, no, abstain, veto
• Сила голосу пропорційна стейку
• Життєвий цикл: подано → кворум → голосування → підрахунок → виконано

Стейкінг та винагороди

Винагороди розподіляються на основі:

• Проіндексовано сторінок — робота краулера
• Оброблено запитів — корисність
• Час роботи — надійність
• Зберігання шардів — доступність даних

Docker розгортання

# Одна нода
docker build -t dsrch-node .
docker run -d --name dsrch \
  -p 8080:8080 -p 9090:9090 \
  -v dsrch-data:/home/dsrch/.dsrch \
  --restart unless-stopped \
  dsrch-node start --api-port 8080 --external-ip YOUR_PUBLIC_IP

# Тестнет з 3 нод
docker compose up -d

Продакшн налаштування

Рекомендації

• Реверс-проксі: Caddy або Nginx для TLS
• Файрвол: Відкрити порти 8080 (HTTP) та 9090 (P2P, TCP+UDP)
• Ресурси: 2+ vCPU, 4+ ГБ RAM, 50+ ГБ SSD

Конфігурація Caddy

explorer.dsrch.net {
    reverse_proxy localhost:8080
}
api.dsrch.net {
    reverse_proxy localhost:8080
}
docs.dsrch.net {
    reverse_proxy localhost:8080
}

Моніторинг

• Метрики Prometheus at /metrics: кількість запитів, гістограми затримки, розмір індексу
• Панель управління на /dashboard: статус ноди, піри, епохи, винагороди
• Оглядач на /explorer: огляд мережі, всі ноди, пошук

Безпека

• Приватний ключ: ~/.dsrch/node.key (дозволи: 0600) — ніколи не поширюйте
• Обмеження частоти: Вбудоване обмеження за IP на всіх ендпоінтах
• CORS: Налаштовуваний список дозволених джерел
• CSP заголовки: Content Security Policy на всіх сторінках
• TLS: --tls-cert та --tls-key прапорці
• robots.txt: Краулер дотримується Robots Exclusion Protocol

Усунення проблем

Нода не запускається

Run dsrch init спочатку для генерації конфігурації та ключів.

Немає підключених пірів

• Перевірте файрвол: порт 9090 має бути відкритий (TCP + UDP)
• Якщо за NAT/Docker: використовуйте --external-ip YOUR_PUBLIC_IP
• Перевірте доступність бутстрап-пірів

Черга сканування порожня

Авто-сідер надає URL автоматично. Якщо все одно зупинено, додайте вручну:

curl -X POST "https://api.dsrch.net/api/crawl/add?url=https://example.com"

Пошук не повертає результатів

Перевірте кількість документів через curl https://api.dsrch.net/api/status. Якщо 0, зачекайте поки краулер проіндексує сторінки.