API Backend

WoT Oracle

Consulta distancias de seguimiento dirigidas y evidencia pública de silencios por HTTP. Versión 0.3.0, sin extensión.

Qué Hace

El Oracle indexa seguimientos de tipo 3 y entradas de claves públicas de listas de silencios de tipo 10000 recibidas de los relés configurados. La cobertura se limita a esos eventos. La distancia y los silencios son señales separadas; la API no los combina en una puntuación de confianza.

Ejemplo: Si Alice sigue a Bob, y Bob sigue a Carol, entonces la distancia de Alice a Carol es 2 saltos.

Funciones de la versión

0.3.0Versión

1–5Profundidad máxima (saltos)

100Destinos por lote

3 / 10000Tipos de eventos indexados

Endpoints de API

Respuestas ilustrativas con claves públicas hexadecimales sintéticas de 64 caracteres. Los resultados dependen de los eventos indexados. Consulta todos los endpoints, incluidos /mutes, /trust y /ready, en la referencia de la API.

`GET /distance`

Consulta la distancia social entre dos 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`

Consulta distancias de una pubkey a múltiples objetivos.

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`

Obtén estadísticas sobre el grafo indexado.

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`

Estado del proceso y versión. Usa /ready para comprobar la disponibilidad de la ingesta.

http

GET /health

json

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

Auto-Hospedaje

Los ejemplos usan v0.3.0. Docker y Compose publican en localhost:8080. Los despliegues públicos necesitan un proxy inverso que sustituya las cabeceras de IP del cliente. La compilación nativa requiere Rust 1.93, pkg-config y las bibliotecas de desarrollo de OpenSSL.

Docker (Recomendado)

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

Desde el código fuente (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

Configuración

Los valores siguientes son los predeterminados del binario nativo. La imagen Docker usa /app/data/wot.db; Compose publica en la interfaz local por defecto. La caché admite 100–100000 entradas, el TTL 10–3600 segundos y el límite 1–1000 solicitudes/minuto.

Variable	Predeterminado	Descripción
`RELAYS`	wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net/,wss://relay.mostr.pub/	URLs de relays separados por coma
`HTTP_PORT`	8080	Puerto del servidor
`DB_PATH`	wot.db	Ubicación de base de datos SQLite
`RATE_LIMIT_PER_MINUTE`	100	Límite de consultas por IP
`CACHE_SIZE`	10000	Máximo de entradas en la caché de consultas Moka
`CACHE_TTL_SECS`	300	Expiración de caché (5 min)

Arquitectura

Almacenamiento de Grafo

Grafo en memoria para traversal rápido, respaldado por SQLite para persistencia. Sincroniza continuamente desde los relays Nostr configurados.

Búsqueda de Caminos

La búsqueda en anchura bidireccional calcula rutas de seguimiento dirigidas más cortas. El tiempo depende del tamaño del grafo, la ramificación y la profundidad.

Caché

Caché Moka con capacidad y TTL configurables. Las entradas se invalidan cuando cambia la revisión del grafo. La latencia depende del despliegue y de la carga.

Limitación de Tasa

Limitación de tasa por IP protege el servicio de abuso. Límites configurables para diferentes escenarios de despliegue.

Instancia Pública

Una instancia pública está disponible para desarrollo y pruebas:

https://wot-oracle.mappingbitcoin.com

Los límites dependen del despliegue. Gestiona HTTP 429 con espera progresiva. La saturación devuelve 503; /health y /ready quedan fuera del limitador de endpoints de datos.

Código Abierto

Escrito en Rust. Licencia MIT. Auto-hospeda para tu comunidad o contribuye mejoras.

Ver Código Fuente en GitHub Conoce la Extensión WoT →