Nostr WoT
Серверный API

WoT Oracle

Запрашивайте расстояния в направленном графе подписок и публичные сведения о скрытии по HTTP. Версия 0.3.0, без расширения.

Смотреть на GitHubДокументация API

Что он делает

Oracle индексирует подписки kind-3 и открытые ключи из списков скрытия kind-10000, полученных от настроенных реле. Охват ограничен этими событиями. Расстояния и скрытия остаются отдельными сигналами; API не объединяет их в оценку доверия.

Пример: Если Алиса подписана на Боба, а Боб подписан на Кэрол, то расстояние от Алисы до Кэрол составляет 2 перехода.

Возможности версии

0.3.0Версия
1–5Максимальная глубина (переходы)
100Целей в пакете
3 / 10000Типы индексируемых событий

API-эндпоинты

Примеры ответов с синтетическими открытыми ключами из 64 шестнадцатеричных символов. Результаты зависят от индексированных событий. Полный справочник API включает /mutes, /trust и /ready.

GET /distance

Запрос социальной дистанции между двумя pubkey.

http
GET /distance?from=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&to=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb&max_hops=3
json
{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "hops": 2,
  "path_count": 1,
  "mutual_follow": false
}

POST /distance/batch

Запрос дистанций от одного pubkey до нескольких целей.

http
POST /distance/batch
Content-Type: application/json

{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "targets": [
    "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  ],
  "max_hops": 3
}
json
{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "results": [
    {
      "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "hops": 2,
      "path_count": 1,
      "mutual_follow": false
    }
  ]
}

GET /stats

Получение статистики об индексированном графе.

http
GET /stats
json
{
  "node_count": 3,
  "edge_count": 2,
  "nodes_with_follows": 2,
  "mute_edge_count": 0,
  "nodes_with_mute_lists": 1,
  "sync": {
    "running": true,
    "ready": false,
    "last_event_received_at": 0,
    "last_persisted_at": 0,
    "persisted_events": 0,
    "lagged_notifications": 0,
    "persistence_errors": 0,
    "coverage": "configured_relays_only"
  },
  "cache": {
    "size": 0,
    "capacity": 10000,
    "ttl_secs": 300
  },
  "locks": {
    "write_lock_count": 0,
    "write_lock_avg_us": 0,
    "write_lock_max_us": 0,
    "read_lock_count": 0,
    "read_lock_avg_us": 0,
    "read_lock_max_us": 0
  }
}

GET /health

Состояние процесса и версия. Используйте /ready для проверки готовности приёма событий.

http
GET /health
json
{
  "status": "healthy",
  "version": "0.3.0"
}

Самостоятельный хостинг

Примеры используют v0.3.0. Docker и Compose публикуют порт на localhost:8080. Для публичного развёртывания нужен обратный прокси, заменяющий заголовки IP клиента. Нативная сборка требует Rust 1.93, pkg-config и библиотеки разработки OpenSSL.

Docker (рекомендуется)

терминал
$docker pull ghcr.io/nostr-wot/nostr-wot-oracle:0.3.0
$
$docker run -d --name nostr-wot-oracle \
$ -p 127.0.0.1:8080:8080 \
$ -v wot-data:/app/data \
$ ghcr.io/nostr-wot/nostr-wot-oracle:0.3.0

Docker Compose

терминал
$git clone --branch v0.3.0 --depth 1 https://github.com/nostr-wot/nostr-wot-oracle.git
$cd nostr-wot-oracle
$docker compose up -d

Из исходного кода (Rust 1.93)

терминал
$git clone --branch v0.3.0 --depth 1 https://github.com/nostr-wot/nostr-wot-oracle.git
$cd nostr-wot-oracle
$rustup toolchain install 1.93.0
$cargo +1.93.0 build --locked --release
$./target/release/wot-oracle

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

Ниже указаны стандартные значения нативной программы. Образ Docker использует /app/data/wot.db; Compose по умолчанию публикует порт только локально. Кеш допускает 100–100000 записей, TTL 10–3600 секунд, лимит 1–1000 запросов в минуту.

ПеременнаяПо умолчаниюОписание
RELAYSwss://relay.damus.io,wss://nos.lol,wss://relay.primal.net/,wss://relay.mostr.pub/URL реле через запятую
HTTP_PORT8080Порт сервера
DB_PATHwot.dbРасположение базы данных SQLite
RATE_LIMIT_PER_MINUTE100Ограничение запросов на IP
CACHE_SIZE10000Максимальное число записей в кеше запросов Moka
CACHE_TTL_SECS300Время жизни кэша (5 мин)

Архитектура

Хранение графа

Граф в оперативной памяти для быстрого обхода, с резервным хранением в SQLite. Непрерывная синхронизация с настроенных реле Nostr.

Поиск пути

Двунаправленный поиск в ширину вычисляет кратчайшие направленные пути подписок. Время зависит от размера графа, ветвления и глубины поиска.

Кэширование

Кеш Moka с настраиваемой ёмкостью и TTL. Записи становятся недействительными при изменении ревизии графа. Задержка зависит от развёртывания и нагрузки.

Ограничение частоты запросов

Ограничение частоты запросов по IP защищает сервис от злоупотреблений. Настраиваемые лимиты для различных сценариев развёртывания.

Публичный экземпляр

Публичный экземпляр доступен для разработки и тестирования:

https://wot-oracle.mappingbitcoin.com

Лимиты зависят от настроек развёртывания. При HTTP 429 увеличивайте задержку перед повтором. Перегрузка запросов возвращает 503; /health и /ready не ограничиваются лимитером данных.

Открытый исходный код

Написан на Rust. Лицензия MIT. Разверните для своего сообщества или внесите улучшения.

Исходный код на GitHubУзнать о расширении WoT →