Nostr WoT

Documentazione

Tutto ciò di cui hai bisogno per integrare Web of Trust nella tua applicazione.

Riferimento SDK

Crea applicazioni Nostr con funzioni per i dati, strumenti per i relay, interfaccia di accesso e query opzionali sulla distanza nel grafo dei follow.

Pacchetti pubblicati

Versioni verificate su npm il 20 settembre 2026. Il metapacchetto esporta WoT dalla radice e gli altri moduli tramite sottopercorsi. Puoi anche installare direttamente i pacchetti con ambito; @nostr-wot/pq è un pacchetto separato.

PacchettoVersione
nostr-wot-sdk1.0.1
@nostr-wot/data0.5.1
@nostr-wot/relay0.1.1
@nostr-wot/signers1.2.0
@nostr-wot/blossom0.1.7
@nostr-wot/dm0.6.2
@nostr-wot/wallet0.3.4
@nostr-wot/wot1.0.0
@nostr-wot/graph0.2.0
@nostr-wot/ui0.7.1
@nostr-wot/auth3.0.0
@nostr-wot/pq0.2.2

Installazione

terminale
$npm install [email protected]

Configurazione del provider

NostrSdkProvider combina configurazione dei dati, stato della sessione e contesto WoT opzionale. Specifica myPubkey per le query Oracle; l’accesso non imposta automaticamente la radice delle query WoT.

tsx
"use client";
import type { ReactNode } from "react";
import { NostrSdkProvider } from "nostr-wot-sdk/react";

export function Providers({ children }: { children: ReactNode }) {
  return (
    <NostrSdkProvider
      relays={["wss://relay.damus.io", "wss://nos.lol"]}
      profileAggregators={["wss://purplepag.es"]}
    >
      {children}
    </NostrSdkProvider>
  );
}

Compatibilità con Oracle

La versione pubblicata @nostr-wot/wot 1.0.0 usa il vecchio contratto /api/distance/FROM/TO?maxHops= e attende il campo distance. Oracle 0.3.0 usa /distance?from=&to=&max_hops= e restituisce hops. Cambiare solo l’URL di base non li rende compatibili. Usa fetch direttamente con Oracle 0.3.0 o la fonte del grafo locale mostrata sotto.

typescript
async function oracleDistance(from: string, to: string) {
  const query = new URLSearchParams({ from, to, max_hops: "2" });
  const response = await fetch(
    "https://wot-oracle.mappingbitcoin.com/distance?" + query,
  );
  if (!response.ok) throw new Error("Oracle HTTP " + response.status);
  const result = await response.json();
  return result.hops as number | null;
}

Riferimento API Oracle

Livello dati

Le funzioni autonome recuperano profili, note, discussioni, follow e interazioni. Gli hook React aggiungono una cache che restituisce i dati memorizzati mentre li aggiorna. Le funzioni dati condividono un proprio pool di connessioni.

terminale
$npm install @nostr-wot/[email protected]
typescript
import {
  fetchProfile, fetchNotesByAuthor, fetchEngagement, setDefaultRelays,
} from "@nostr-wot/data";

setDefaultRelays(["wss://relay.damus.io", "wss://nos.lol"]);

async function loadAuthor(pubkey: string) {
  const profile = await fetchProfile(pubkey);
  const notes = await fetchNotesByAuthor(pubkey, { limit: 50 });
  const engagement = await fetchEngagement(notes.map(note => note.id));
  return { profile, notes, engagement };
}
tsx
"use client";
import { useProfile } from "@nostr-wot/data/react";

function ProfileCard({ pubkey }: { pubkey: string }) {
  const profile = useProfile(pubkey);
  if (!profile) return null;
  return <h1>{profile.displayName ?? profile.name ?? pubkey}</h1>;
}

Gestione dei relay

RelayPool incapsula un trasporto PoolLike compatibile fornito dalla tua app. Configura urls, usa subscribe con onEvent/onEose e chiudi le sottoscrizioni al termine. Un wrapper relay creato separatamente non si collega automaticamente al provider dei dati.

terminale
$npm install @nostr-wot/[email protected]
typescript
import { RelayPool, type PoolLike, type NostrEvent } from "@nostr-wot/relay";

function watchNotes(transport: PoolLike, onEvent: (event: NostrEvent) => void) {
  const pool = new RelayPool({
    urls: ["wss://relay.damus.io", "wss://nos.lol"],
    pool: transport,
  });
  const sub = pool.subscribe({ kinds: [1], limit: 50 }, { onEvent });
  return () => {
    sub.close();
    pool.destroy();
  };
}

Interfaccia di accesso

LoginButton e useSession condividono la sessione di NostrSdkProvider. I metodi supportati includono NIP-07, NIP-46, generazione e importazione delle chiavi. Installa direttamente il pacchetto UI per importarne componenti e stili.

terminale
$npm install @nostr-wot/[email protected]
tsx
"use client";
import { LoginButton, useSession } from "@nostr-wot/ui";
import { NostrSdkProvider } from "nostr-wot-sdk/react";
import "@nostr-wot/ui/styles.css";

function Account() {
  const { pubkey } = useSession();
  return <><LoginButton /><output>{pubkey}</output></>;
}

function App() {
  return <NostrSdkProvider><Account /></NostrSdkProvider>;
}

Distanze della rete di fiducia

WoT interroga l’Oracle per impostazione predefinita. getDistance restituisce un numero o null; isInMyWoT restituisce un booleano. getDetails fornisce i salti, un numero di percorsi e informazioni opzionali sui collegamenti intermedi e sui follow reciproci. Usa chiavi pubbliche esadecimali valide di 64 caratteri.

Migrazione a @nostr-wot/wot 1.0.0

La versione 1.0.0 ha rimosso il rilevamento dell’estensione, i metodi di punteggio di fiducia e useTrustScore. Usa useWoT o useIsInWoT e leggi i loro oggetti risultato. Per query locali, passa una WoTLocalSource, come WotGraph.asWoTSource() di @nostr-wot/graph. Solo getDistance, isInMyWoT e filterByWoT usano questa fonte; gli altri metodi interrogano ancora l’Oracle.

Esempio di grafo locale

Carica ed esplora un grafo locale prima di passarne la fonte a WoT. L’esempio React riceve questo grafo preparato e usa useIsInWoT; useWoT richiede anche getDetails all’Oracle. @nostr-wot/graph ha una propria API getScore, distinta dall’API di punteggio rimossa da WoT.

terminale
$npm install @nostr-wot/[email protected] @nostr-wot/[email protected]
typescript
import { WotGraph } from "@nostr-wot/graph";
import { WoT } from "@nostr-wot/wot";

async function prepareGraph(myPubkey: string, targetPubkey: string) {
  const graph = new WotGraph({
    namespace: "my-app",
    relays: ["wss://relay.damus.io", "wss://nos.lol"],
  });
  await graph.load();
  await graph.crawl(myPubkey, { maxDepth: 2 });
  const wot = new WoT({ source: graph.asWoTSource(), maxHops: 2 });
  const distance = await wot.getDistance(targetPubkey);
  const inWoT = await wot.isInMyWoT(targetPubkey);
  return { graph, distance, inWoT };
}
tsx
"use client";
import type { WotGraph } from "@nostr-wot/graph";
import { NostrSdkProvider, useIsInWoT } from "nostr-wot-sdk/react";

function FollowBadge({ pubkey }: { pubkey: string }) {
  const { inWoT, loading, error } = useIsInWoT(pubkey, { maxHops: 2 });
  if (loading || error || !inWoT) return null;
  return <span>{pubkey}</span>;
}

function LocalTrust({ graph, pubkey }: { graph: WotGraph; pubkey: string }) {
  return (
    <NostrSdkProvider wot={{ enabled: true, options: { source: graph.asWoTSource() } }}>
      <FollowBadge pubkey={pubkey} />
    </NostrSdkProvider>
  );
}
API dell’estensioneAPI Oracle