# Nostr Web of Trust - Complete Documentation

> Filter spam and find trusted content on Nostr using your trust network. A decentralized reputation system that helps you see better content without relying on central moderators.

## Overview

Nostr has no central moderators to filter spam or verify identity. Web of Trust solves this by using your social network—measuring how many hops separate you from someone in the follow graph.

### How It Works

1. Your pubkey is the center of your Web of Trust
2. People you follow = 1 hop (highest trust)
3. People they follow = 2 hops (medium trust)
4. People those follow = 3 hops (lower trust)
5. Beyond 3 hops = likely noise (minimal trust)

### Trust Score Calculation

The trust score is calculated using this formula:

```
score = base × distance_weight × (1 + path_bonus)
```

**Distance Weights:**
- 1 hop: 100% (0.95 base score)
- 2 hops: 60% (0.57 base score)
- 3 hops: 30% (0.285 base score)
- 4+ hops: 10% (0.095 base score)

**Path Bonus:** Multiple independent paths to a user increase their trust score, as it indicates stronger social connection.

---

## Browser Extension

The WoT Extension adds Web of Trust capabilities directly to your browser, exposing the `window.nostr.wot` API for any Nostr client to use.

### Installation

Available for Chrome, Brave, Edge, Opera, and Firefox.

Download from: https://nostr-wot.com/download

### API Reference

The extension exposes these methods on `window.nostr.wot`:

```javascript
// Get the distance (number of hops) to a target pubkey
// Returns: number (1, 2, 3, etc.) or -1 if not found
await window.nostr.wot.getDistance(targetPubkey: string): Promise<number>

// Get the trust score for a target pubkey
// Returns: number between 0 and 1
await window.nostr.wot.getTrustScore(targetPubkey: string): Promise<number>

// Check if a pubkey is within your Web of Trust
// Returns: boolean
await window.nostr.wot.isInWoT(targetPubkey: string): Promise<boolean>

// Get multiple distances in batch
// Returns: Map<string, number>
await window.nostr.wot.getDistances(pubkeys: string[]): Promise<Map<string, number>>

// Get your current pubkey (root of WoT)
await window.nostr.wot.getPubkey(): Promise<string>
```

### Features

- Real-time trust scoring as you browse
- Visual indicators showing trust level
- Client-side filtering capabilities
- Works with any NIP-07 compatible Nostr client
- Privacy-preserving (calculations done locally)

---

## JavaScript SDK

The nostr-wot-sdk provides a lightweight JavaScript/TypeScript library for integrating Web of Trust directly into your applications.

### Installation

```bash
npm install nostr-wot-sdk
# or
yarn add nostr-wot-sdk
# or
pnpm add nostr-wot-sdk
```

### Basic Usage

```typescript
import { NostrWoT } from 'nostr-wot-sdk'

// Initialize with your pubkey
const wot = new NostrWoT({
  userPubkey: 'your-hex-pubkey',
  relays: ['wss://relay.damus.io', 'wss://nos.lol'], // optional
  maxDistance: 3, // optional, default 3
})

// Get trust score (0-1)
const score = await wot.getTrustScore('target-pubkey')

// Get distance in hops
const distance = await wot.getDistance('target-pubkey')

// Check if in WoT
const isInWot = await wot.isInWoT('target-pubkey')

// Batch queries
const scores = await wot.getTrustScores(['pubkey1', 'pubkey2', 'pubkey3'])
```

### React Hooks

```typescript
import { useWoT, useDistance, useTrustScore } from 'nostr-wot-sdk/react'

function Component() {
  // Initialize WoT context
  const { wot, isLoading } = useWoT({ userPubkey: 'your-pubkey' })

  // Get distance for a specific pubkey
  const { distance, loading } = useDistance('target-pubkey')

  // Get trust score
  const { score, loading } = useTrustScore('target-pubkey')

  return <div>Trust: {Math.round(score * 100)}%</div>
}
```

### Configuration Options

```typescript
interface WoTConfig {
  userPubkey: string          // Required: Your hex pubkey
  relays?: string[]           // Optional: Relay URLs to use
  maxDistance?: number        // Optional: Max hops to consider (default: 3)
  cacheTimeout?: number       // Optional: Cache duration in ms (default: 300000)
  oracleUrl?: string         // Optional: WoT Oracle URL for server-side queries
}
```

---

## WoT Oracle

A high-performance Rust backend that maintains a real-time graph of the Nostr follow network and provides instant distance/trust queries via REST API.

### Public Instance

URL: `https://wot-oracle.mappingbitcoin.com`

### API Endpoints

#### Get Distance

```
GET /distance?from={pubkey}&to={pubkey}
```

Response:
```json
{
  "from": "pubkey1",
  "to": "pubkey2",
  "distance": 2,
  "paths": 3,
  "trustScore": 0.68
}
```

#### Batch Distance Query

```
POST /distance/batch
Content-Type: application/json

{
  "from": "your-pubkey",
  "targets": ["pubkey1", "pubkey2", "pubkey3"]
}
```

Response:
```json
{
  "results": [
    { "pubkey": "pubkey1", "distance": 1, "trustScore": 0.95 },
    { "pubkey": "pubkey2", "distance": 2, "trustScore": 0.57 },
    { "pubkey": "pubkey3", "distance": -1, "trustScore": 0 }
  ]
}
```

#### Get Stats

```
GET /stats
```

Response:
```json
{
  "totalUsers": 1250000,
  "totalFollows": 45000000,
  "lastUpdated": "2026-02-04T12:00:00Z",
  "cacheHitRate": 0.94
}
```

### Self-Hosting

The Oracle is fully open source and can be self-hosted:

```bash
git clone https://github.com/nostr-wot/nostr-wot-oracle
cd nostr-wot-oracle
cargo build --release
./target/release/nostr-wot-oracle --config config.toml
```

### Performance

- Bidirectional BFS algorithm for optimal path finding
- LRU caching with <1ms cached query responses
- Real-time graph updates via relay subscriptions
- Horizontal scaling support

---

## Playground

The interactive playground at https://nostr-wot.com/playground allows you to:

1. **Visualize your Web of Trust** - 3D graph showing your social connections
2. **Explore trust paths** - See how you're connected to any user
3. **Test the API** - Try queries in real-time
4. **View profiles** - Full profile pages with notes and following lists

### Features

- Login with NIP-07 extension, nsec/npub keys, or NIP-46 bunker
- Interactive 3D force-directed graph
- Filter by trust threshold, distance, and connection type
- Search users by name or pubkey
- Export graph data as PNG, JSON, or CSV

---

## Use Cases

### Spam Filtering

```javascript
const score = await wot.getTrustScore(eventPubkey)
if (score < 0.3) {
  // Hide or deprioritize this content
}
```

### Marketplace Trust

Display trust indicators on user profiles:
- Green badge: Trust > 70%
- Yellow badge: Trust 30-70%
- Red badge: Trust < 30%

### Tiered Notifications

```javascript
const distance = await wot.getDistance(pubkey)
if (distance === 1) {
  // Push notification for direct follows
} else if (distance === 2) {
  // In-app notification only
} else {
  // Silent/no notification
}
```

### Content Filtering

```javascript
const posts = await fetchPosts()
const filteredPosts = await Promise.all(
  posts.map(async (post) => ({
    ...post,
    trustScore: await wot.getTrustScore(post.pubkey)
  }))
).then(posts => posts.filter(p => p.trustScore > threshold))
```

---

## Repositories

- **Browser Extension**: https://github.com/nostr-wot/nostr-wot-extension
- **JavaScript SDK**: https://github.com/nostr-wot/nostr-wot-sdk
- **WoT Oracle**: https://github.com/nostr-wot/nostr-wot-oracle
- **Website**: https://github.com/nostr-wot/nostr-wot (this repository)

## NPM Package

- **Package**: https://www.npmjs.com/package/nostr-wot-sdk

## License

All Nostr Web of Trust projects are released under the MIT License.

## Support

- GitHub Issues: https://github.com/nostr-wot/nostr-wot/issues
- Contact: https://nostr-wot.com/contact

## Supporters

- Dandelion Labs: https://dandelionlabs.io
- We Are Bitcoin: https://wearebitcoin.org