API Backend

WoT Oracle

Consulte distâncias de seguimentos direcionados e evidências públicas de silenciamento via HTTP. Versão 0.3.0, sem extensão.

Ver no GitHub Documentação da API

O Que Faz

O Oracle indexa seguimentos kind-3 e chaves públicas das listas de silenciamento kind-10000 recebidos dos relays configurados. A cobertura se limita a esses eventos. Distância e silenciamentos são sinais separados; a API não os combina em uma pontuação de confiança.

Exemplo: Se Alice segue Bob, e Bob segue Carol, então a distância de Alice para Carol é 2 saltos.

Recursos da versão

0.3.0Versão

1–5Profundidade máxima (saltos)

100Destinos por lote

3 / 10000Tipos de eventos indexados

Endpoints da API

Respostas ilustrativas com chaves públicas hexadecimais sintéticas de 64 caracteres. Os resultados dependem dos eventos indexados. Consulte a referência da API para todos os endpoints, incluindo /mutes, /trust e /ready.

`GET /distance`

Consulte a distância social entre duas 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`

Consulte distâncias de uma pubkey para múltiplos alvos.

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`

Obtenha estatísticas sobre o 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 do processo e versão. Use /ready para verificar a disponibilidade da ingestão.

http

GET /health

json

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

Auto-Hospedagem

Os exemplos usam v0.3.0. Docker e Compose publicam em localhost:8080. Instalações públicas precisam de um proxy reverso que substitua os cabeçalhos de IP do cliente. A compilação nativa exige Rust 1.93, pkg-config e bibliotecas de desenvolvimento 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

A partir do código-fonte (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

Configuração

Os valores abaixo são os padrões do binário nativo. A imagem Docker usa /app/data/wot.db; o Compose publica apenas na interface local por padrão. O cache aceita 100–100000 entradas, o TTL 10–3600 segundos e o limite 1–1000 solicitações/minuto.

Variável	Padrão	Descrição
`RELAYS`	wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net/,wss://relay.mostr.pub/	URLs de relays separadas por vírgula
`HTTP_PORT`	8080	Porta do servidor
`DB_PATH`	wot.db	Localização do banco de dados SQLite
`RATE_LIMIT_PER_MINUTE`	100	Limite de consultas por IP
`CACHE_SIZE`	10000	Número máximo de entradas no cache de consultas Moka
`CACHE_TTL_SECS`	300	Expiração do cache (5 min)

Arquitetura

Armazenamento de Grafo

Grafo em memória para traversal rápido, apoiado por SQLite para persistência. Sincroniza continuamente dos relays Nostr configurados.

Busca de Caminhos

A busca em largura bidirecional calcula os caminhos direcionados mais curtos. O tempo depende do tamanho do grafo, da ramificação e da profundidade.

Cache

Cache Moka com capacidade e TTL configuráveis. As entradas são invalidadas quando a revisão do grafo muda. A latência depende da instalação e da carga.

Limitação de Taxa

Limitação de taxa por IP protege o serviço de abuso. Limites configuráveis para diferentes cenários de implantação.

Instância Pública

Uma instância pública está disponível para desenvolvimento e testes:

https://wot-oracle.mappingbitcoin.com

Os limites dependem da instalação. Trate HTTP 429 com espera progressiva. A saturação das consultas retorna 503; /health e /ready ficam fora do limitador dos endpoints de dados.

Código Aberto

Escrito em Rust. Licença MIT. Auto-hospede para sua comunidade ou contribua melhorias.

Ver Código Fonte no GitHub Conheça a Extensão WoT →