Backend API

WoT Oracle

High-performance indexer for the Nostr follow graph. Sub-millisecond queries answering "how many hops separate these two users?"

View on GitHub API Documentation

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

<1msCached query latency

<50msUncached query latency

10,000+Queries per second

O(b^d/2)Bidirectional BFS

API Endpoints

`GET /distance`

Query the social distance between two pubkeys.

Request

GET /distance?from=PUBKEY1&to=PUBKEY2

Response

{
  "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.

Request

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

{
  "from": "PUBKEY1",
  "targets": ["PUBKEY2", "PUBKEY3", "PUBKEY4"]
}

Response

{
  "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)

# Pull and run the image
docker pull ghcr.io/nostr-wot/nostr-wot-oracle:v1.0.0

docker run -d \
  -p 8080:8080 \
  -v wot-data:/app/data \
  ghcr.io/nostr-wot/nostr-wot-oracle:v1.0.0

Docker Compose

git clone https://github.com/nostr-wot/nostr-wot-oracle.git
cd wot-oracle
docker-compose up -d

From Source (Rust 1.75+)

git clone https://github.com/nostr-wot/nostr-wot-oracle.git
cd wot-oracle
cargo build --release
./target/release/nostr-wot-oracle

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.com

Rate 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.

View Source on GitHub Learn about WoT Extension →