WoT Oracle
Interrogez la distance des abonnements dirigés et les observations publiques de masquage par HTTP. Version 0.3.0, sans extension.
Ce qu'il fait
L’Oracle indexe les abonnements kind-3 et les clés publiques des listes de masquage kind-10000 reçus des relais configurés. La couverture se limite à ces événements. Distance et masquages restent des signaux séparés ; l’API ne les combine pas en score de confiance.
Exemple : Si Alice suit Bob, et Bob suit Carol, alors la distance entre Alice et Carol est de 2 sauts.
Fonctions de la version
Points d'accès API
Réponses illustratives avec des clés publiques hexadécimales fictives de 64 caractères. Les résultats dépendent des événements indexés. Consultez la référence pour tous les endpoints, dont /mutes, /trust et /ready.
GET /distance
Interroger la distance sociale entre deux pubkeys.
GET /distance?from=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&to=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb&max_hops=3{
"from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"hops": 2,
"path_count": 1,
"mutual_follow": false
}POST /distance/batch
Interroger les distances d'une pubkey vers plusieurs cibles.
POST /distance/batch
Content-Type: application/json
{
"from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"targets": [
"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
],
"max_hops": 3
}{
"from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"results": [
{
"from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"hops": 2,
"path_count": 1,
"mutual_follow": false
}
]
}GET /stats
Obtenir les statistiques du graphe indexé.
GET /stats{
"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
État du processus et version. Utilisez /ready pour vérifier la disponibilité de l’ingestion.
GET /health{
"status": "healthy",
"version": "0.3.0"
}Auto-hébergement
Les exemples utilisent v0.3.0. Docker et Compose exposent localhost:8080. Un déploiement public nécessite un proxy inverse qui remplace les en-têtes d’IP client. La compilation native nécessite Rust 1.93, pkg-config et les bibliothèques de développement OpenSSL.
Docker (recommandé)
Docker Compose
Depuis les sources (Rust 1.93)
Configuration
Les valeurs ci-dessous sont celles du binaire natif. L’image Docker utilise /app/data/wot.db ; Compose expose l’interface locale par défaut. Le cache accepte 100–100000 entrées, le TTL 10–3600 secondes et la limite 1–1000 requêtes/minute.
| Variable | Par défaut | Description |
|---|---|---|
RELAYS | wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net/,wss://relay.mostr.pub/ | URLs des relais séparées par des virgules |
HTTP_PORT | 8080 | Port du serveur |
DB_PATH | wot.db | Emplacement de la base de données SQLite |
RATE_LIMIT_PER_MINUTE | 100 | Limitation des requêtes par IP |
CACHE_SIZE | 10000 | Nombre maximal d’entrées du cache de requêtes Moka |
CACHE_TTL_SECS | 300 | Expiration du cache (5 min) |
Architecture
Stockage du graphe
Graphe en mémoire pour un parcours rapide, sauvegardé par SQLite pour la persistance. Synchronisation continue depuis les relais Nostr configurés.
Recherche de chemin
La recherche en largeur bidirectionnelle calcule les plus courts chemins dirigés. La durée dépend de la taille du graphe, des ramifications et de la profondeur.
Mise en cache
Cache Moka avec capacité et TTL configurables. Les entrées sont invalidées quand la révision du graphe change. La latence dépend du déploiement et de la charge.
Limitation du débit
La limitation du débit par IP protège le service contre les abus. Limites configurables pour différents scénarios de déploiement.
Instance publique
Une instance publique est disponible pour le développement et les tests :
https://wot-oracle.mappingbitcoin.comLes limites dépendent du déploiement. Gérez HTTP 429 avec une attente progressive. La saturation renvoie 503 ; /health et /ready restent hors du limiteur des endpoints de données.
Code source ouvert
Écrit en Rust. Sous licence MIT. Auto-hébergez pour votre communauté ou contribuez des améliorations.