WoT Oracle
High-performance indexer for the Nostr follow graph. Sub-millisecond queries answering "how many hops separate these two users?"
What It Does
WoT Oracle continuously syncs follow lists (Kind 3 events) from Nostr relays, building an in-memory graph of the entire social network. It then provides a REST API to query social distance between any two pubkeys.
Example: If Alice follows Bob, and Bob follows Carol, then the distance from Alice to Carol is 2 hops.
Performance
API Endpoints
GET /distance
Query the social distance between two pubkeys.
GET /distance?from=PUBKEY1&to=PUBKEY2{
"from": "PUBKEY1",
"to": "PUBKEY2",
"distance": 2,
"paths": 5,
"mutual": false,
"bridging_nodes": ["PUBKEY3", "PUBKEY4"]
}POST /distance/batch
Query distances from one pubkey to multiple targets.
POST /distance/batch
Content-Type: application/json
{
"from": "PUBKEY1",
"targets": ["PUBKEY2", "PUBKEY3", "PUBKEY4"]
}{
"from": "PUBKEY1",
"results": [
{ "to": "PUBKEY2", "distance": 1 },
{ "to": "PUBKEY3", "distance": 2 },
{ "to": "PUBKEY4", "distance": null }
]
}GET /stats
Get statistics about the indexed graph.
{
"total_pubkeys": 1250000,
"total_follows": 8500000,
"last_sync": "2024-01-15T10:30:00Z",
"cache_hit_rate": 0.85
}GET /health
Health check endpoint for monitoring.
{ "status": "healthy", "uptime": 864000 }Self-Hosting
Run your own WoT Oracle instance. Full control over your trust infrastructure.
Docker (Recommended)
Docker Compose
From Source (Rust 1.75+)
Configuration
Configure via environment variables:
| Variable | Default | Description |
|---|---|---|
RELAYS | damus, nos.lol, nostr.band | Comma-separated relay URLs |
HTTP_PORT | 8080 | Server port |
DB_PATH | wot.db | SQLite database location |
RATE_LIMIT_PER_MINUTE | 100 | Query throttle per IP |
CACHE_SIZE | 10000 | LRU cache entries |
CACHE_TTL_SECS | 300 | Cache expiration (5 min) |
Architecture
Graph Storage
In-memory graph for fast traversal, backed by SQLite for persistence. Syncs continuously from configured Nostr relays.
Pathfinding
Bidirectional breadth-first search (BFS) from both endpoints simultaneously, meeting in the middle for O(b^(d/2)) complexity.
Caching
LRU cache with configurable size and TTL. Most queries hit cache for sub-millisecond response times.
Rate Limiting
Per-IP rate limiting protects the service from abuse. Configurable limits for different deployment scenarios.
Public Instance
A public instance is available for development and testing:
https://wot-oracle.mappingbitcoin.comRate limited to 100 requests/minute per IP. For production use, consider self-hosting.
Open Source
Written in Rust. MIT licensed. Self-host for your community or contribute improvements.