Backend-API

WoT Oracle

Frage gerichtete Follow-Distanzen und öffentliche Stummschaltungsdaten per HTTP ab. Version 0.3.0, ohne Erweiterung.

Was es macht

Das Oracle indexiert Kind-3-Follows und öffentliche Schlüssel aus Kind-10000-Stummschaltungslisten der konfigurierten Relays. Die Abdeckung beschränkt sich auf diese Ereignisse. Distanz und Stummschaltungen bleiben getrennte Signale; die API kombiniert sie nicht zu einem Vertrauenswert.

Beispiel: Wenn Alice Bob folgt und Bob Carol folgt, dann beträgt die Distanz von Alice zu Carol 2 Hops.

Funktionen der Version

0.3.0Version

1–5Maximale Suchtiefe (Hops)

100Ziele pro Stapel

3 / 10000Indexierte Ereignistypen

API-Endpunkte

Beispielantworten mit synthetischen öffentlichen Schlüsseln aus 64 Hexadezimalzeichen. Ergebnisse hängen von den indexierten Ereignissen ab. Alle Endpunkte, einschließlich /mutes, /trust und /ready, stehen in der API-Referenz.

`GET /distance`

Abfrage der sozialen Distanz zwischen zwei pubkeys.

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`

Abfrage der Distanzen von einem pubkey zu mehreren Zielen.

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`

Statistiken über den indizierten Graphen abrufen.

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`

Prozessstatus und Version. Prüfe die Aufnahmebereitschaft mit /ready.

http

GET /health

json

{
  "status": "healthy",
  "version": "0.3.0"
}

Selbst hosten

Die Beispiele nutzen v0.3.0. Docker und Compose veröffentlichen auf localhost:8080. Öffentliche Installationen benötigen einen Reverse-Proxy, der Client-IP-Header ersetzt. Native Builds benötigen Rust 1.93, pkg-config und OpenSSL-Entwicklungsbibliotheken.

Docker (Empfohlen)

Terminal

$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

Terminal

$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

Aus dem Quellcode (Rust 1.93)

Terminal

$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

Konfiguration

Die Werte unten sind Standardwerte des nativen Programms. Das Docker-Image nutzt /app/data/wot.db; Compose veröffentlicht standardmäßig nur lokal. Der Cache erlaubt 100–100000 Einträge, die TTL 10–3600 Sekunden und das Limit 1–1000 Anfragen/Minute.

Variable	Standard	Beschreibung
`RELAYS`	wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net/,wss://relay.mostr.pub/	Kommagetrennte Relay-URLs
`HTTP_PORT`	8080	Server-Port
`DB_PATH`	wot.db	SQLite-Datenbank-Speicherort
`RATE_LIMIT_PER_MINUTE`	100	Abfragedrosselung pro IP
`CACHE_SIZE`	10000	Maximale Einträge im Moka-Abfragecache
`CACHE_TTL_SECS`	300	Cache-Ablaufzeit (5 Min.)

Architektur

Graph-Speicher

In-Memory-Graph für schnelle Traversierung, gesichert durch SQLite für Persistenz. Synchronisiert kontinuierlich von konfigurierten Nostr-Relays.

Pfadfindung

Die bidirektionale Breitensuche berechnet kürzeste gerichtete Follow-Pfade. Die Laufzeit hängt von Graphgröße, Verzweigung und Suchtiefe ab.

Zwischenspeicherung

Moka-Abfragecache mit konfigurierbarer Kapazität und TTL. Einträge werden bei einer neuen Graphrevision ungültig. Die Latenz hängt von Installation und Last ab.

Anfragebegrenzung

Pro-IP-Rate-Limiting schützt den Dienst vor Missbrauch. Konfigurierbare Limits für verschiedene Einsatzszenarien.

Öffentliche Instanz

Eine öffentliche Instanz ist für Entwicklung und Tests verfügbar:

https://wot-oracle.mappingbitcoin.com

Limits hängen von der Installation ab. Wiederhole HTTP-429-Anfragen mit zunehmender Wartezeit. Ausgelastete Graphabfragen liefern 503; /health und /ready liegen außerhalb des Datenendpunkt-Limiters.

Quelloffen

Geschrieben in Rust. MIT-lizenziert. Hosten Sie es selbst für Ihre Community oder tragen Sie Verbesserungen bei.

Quellcode auf GitHub ansehen Mehr über die WoT Extension erfahren →