Nostr WoT
API Backend

WoT Oracle

Interroga distanze dei follow diretti e osservazioni pubbliche di silenziamento via HTTP. Versione 0.3.0, senza estensione.

Vedi su GitHubDocumentazione API

Cosa Fa

L’Oracle indicizza follow kind-3 e chiavi pubbliche delle liste di silenziamento kind-10000 ricevuti dai relay configurati. La copertura si limita a questi eventi. Distanza e silenziamenti restano segnali separati; l’API non li combina in un punteggio di fiducia.

Esempio: Se Alice segue Bob e Bob segue Carol, la distanza da Alice a Carol è di 2 salti.

Funzioni della versione

0.3.0Versione
1–5Profondità massima (salti)
100Destinatari per lotto
3 / 10000Tipi di eventi indicizzati

Endpoint API

Risposte illustrative con chiavi pubbliche esadecimali sintetiche di 64 caratteri. I risultati dipendono dagli eventi indicizzati. Consulta il riferimento API per tutti gli endpoint, inclusi /mutes, /trust e /ready.

GET /distance

Interroga la distanza sociale tra due 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

Interroga le distanze da una pubkey a più destinazioni.

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

Ottieni statistiche sul grafo indicizzato.

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

Stato del processo e versione. Usa /ready per verificare la disponibilità dell’acquisizione.

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

Hosting autonomo

Gli esempi usano v0.3.0. Docker e Compose espongono localhost:8080. Le installazioni pubbliche richiedono un reverse proxy che sostituisca le intestazioni IP del client. La compilazione nativa richiede Rust 1.93, pkg-config e le librerie di sviluppo OpenSSL.

Docker (Consigliato)

terminale
$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

terminale
$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

Dal codice sorgente (Rust 1.93)

terminale
$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

Configurazione

I valori seguenti sono quelli predefiniti del binario nativo. L’immagine Docker usa /app/data/wot.db; Compose espone solo l’interfaccia locale per impostazione predefinita. La cache ammette 100–100000 voci, il TTL 10–3600 secondi e il limite 1–1000 richieste/minuto.

VariabilePredefinitoDescrizione
RELAYSwss://relay.damus.io,wss://nos.lol,wss://relay.primal.net/,wss://relay.mostr.pub/URL dei relay separati da virgola
HTTP_PORT8080Porta del server
DB_PATHwot.dbPosizione del database SQLite
RATE_LIMIT_PER_MINUTE100Limite query per IP
CACHE_SIZE10000Numero massimo di voci nella cache Moka
CACHE_TTL_SECS300Scadenza della cache (5 min)

Architettura

Archiviazione del Grafo

Grafo in memoria per attraversamento veloce, supportato da SQLite per la persistenza. Si sincronizza continuamente dai relay Nostr configurati.

Ricerca del Percorso

La ricerca in ampiezza bidirezionale calcola i percorsi diretti più brevi. Il tempo dipende da dimensioni del grafo, ramificazioni e profondità.

Cache

Cache Moka con capacità e TTL configurabili. Le voci vengono invalidate quando cambia la revisione del grafo. La latenza dipende dall’installazione e dal carico.

Limitazione delle Richieste

Limitazione per IP per proteggere il servizio da abusi. Limiti configurabili per diversi scenari di distribuzione.

Istanza Pubblica

Un'istanza pubblica è disponibile per sviluppo e test:

https://wot-oracle.mappingbitcoin.com

I limiti dipendono dall’installazione. Gestisci HTTP 429 con attese crescenti. La saturazione delle query restituisce 503; /health e /ready non sono soggetti al limite degli endpoint dati.

Codice aperto

Scritto in Rust. Licenza MIT. Ospita per la tua comunità o contribuisci con miglioramenti.

Vedi il Sorgente su GitHubScopri l'estensione WoT →