# Relatr Integration Guide

## Overview

**Relatr** ([https://www.relatr.xyz/](https://www.relatr.xyz/)) is a decentralized Web of Trust service for Nostr that provides global trust scores based on social graph analysis and profile validation.

**GitHub**: [https://github.com/ContextVM/relatr](https://github.com/ContextVM/relatr)

## ✅ Integration Method: NIP-85 (Trusted Assertions)

Relatr publishes trust scores as **Nostr events** using **NIP-85** (kind 30382). This is the Nostr-native approach - no external API needed!

## Current Status

### ✅ What's Implemented

SkateSpots currently uses a **local Web of Trust (WoT)** implementation:

- **Algorithm**: Client-side social graph analysis
- **Data source**: User's follow list (kind 3) + friends' follows
- **Scoring**: 
  - 100 = Self
  - 90 = Direct follow
  - 60 = Friend-of-friend (2 hops)
  - 30 = NIP-05 verified
  - 0 = Unknown
- **Performance**: Fast, works offline, privacy-preserving
- **Limitation**: Only knows about your social graph (not global)

### 🔮 Relatr Integration (Planned)

Relatr provides **global trust scores** computed server-side using:
- Social graph distances (multiple hops)
- NIP-05 validation
- Lightning address verification  
- Reciprocity checking
- Configurable weighting schemes

## Integration Architecture

### Hybrid Approach (Recommended)

Combine local WoT with Relatr for best results:

```typescript
async function getTrustScore(source: string, target: string): Promise<number> {
  // 1. Try local WoT first (instant, offline-capable)
  const localScore = await calculateLocalWoT(source, target);
  
  // 2. Fetch Relatr score in background (global perspective)
  const relatrScore = await relatrClient.getScore(source, target);
  
  // 3. Blend scores or use Relatr as fallback
  if (localScore >= 90) {
    return localScore; // Trust your direct follows
  }
  
  if (relatrScore && relatrScore.score > localScore) {
    return relatrScore.score; // Relatr found stronger trust signal
  }
  
  return localScore; // Use local score
}
```

### Integration Options

#### Option 1: Fallback Only
- Use local WoT by default
- Query Relatr only when local score is 0
- **Pros**: Fast, minimal API calls
- **Cons**: Misses global trust signals

#### Option 2: Blended Scoring  
- Calculate both local and Relatr scores
- Take the maximum or weighted average
- **Pros**: Best of both worlds
- **Cons**: Requires API calls for every pubkey

#### Option 3: Relatr Primary
- Query Relatr first
- Fall back to local WoT if unavailable
- **Pros**: Global perspective
- **Cons**: Slower, requires internet

## Implementation Steps

### 1. Determine Relatr API Structure

Relatr is documented as an **MCP Server** (Model Context Protocol), not a traditional REST API. This requires:

**Option A: MCP Client Integration**
```bash
npm install @modelcontextprotocol/sdk
```

**Option B: REST API (if available)**
- Endpoint discovery needed
- Authentication requirements
- Rate limits

**Option C: Nostr Events**
- Relatr may publish trust scores as Nostr events
- Query via existing Nostr infrastructure

### 2. Test Relatr Service

```bash
# Test if REST API exists
curl https://api.relatr.xyz/v1/health

# Test MCP server
# (requires MCP client setup)

# Check for Nostr event-based scores
# (query kind 10050 or similar Trusted Assertion events)
```

### 3. Update Code

**Files to modify:**

1. **`src/lib/relatr.ts`** - Implement actual API client
2. **`src/hooks/useTrustScore.ts`** - Add Relatr fallback
3. **`src/hooks/useBatchTrustScores.ts`** - Add Relatr batch support
4. **`src/pages/CommunityStatsPage.tsx`** - Show Relatr vs local comparison

### 4. Configuration

Add settings for Relatr integration:

```typescript
// src/lib/config.ts
export const RELATR_CONFIG = {
  enabled: false, // Toggle in settings
  apiUrl: 'https://api.relatr.xyz',
  mcpServerUrl: 'https://www.relatr.xyz',
  fallbackToLocal: true, // Use local WoT if Relatr fails
  blendScores: true, // Combine local + Relatr scores
  timeout: 10000, // API timeout (ms)
};
```

## Relatr Features to Leverage

Based on [Relatr's README](https://github.com/ContextVM/relatr):

### Key Capabilities

1. **Social Graph Analysis** - Uses `nostr-social-duck` for graph distances
2. **Profile Validation** - Validates NIP-05, Lightning addresses
3. **Reciprocity Checking** - Mutual follow relationships
4. **Configurable Scoring** - Weighted trust factors
5. **Trusted Assertions (TA)** - NIP-85 trust rank publishing

### Integration Benefits

- 🌍 **Global perspective** - Not limited to your social graph
- 📊 **Deeper analysis** - Multi-hop traversal beyond 2 hops
- ✅ **Profile validation** - NIP-05 + Lightning address checks
- 🔄 **Reciprocity** - Identifies mutual trust relationships
- 📈 **Better spam detection** - More sophisticated scoring

## Example Integration

### Modified `useTrustScore` Hook

```typescript
import { RELATR_ENABLED, relatrClient, normalizeRelatrScore } from '@/lib/relatr';

export function useTrustScore(targetPubkey: string | undefined) {
  const { nostr } = useNostr();
  const { user } = useCurrentUser();

  return useQuery({
    queryKey: ['trust-score', targetPubkey, user?.pubkey, RELATR_ENABLED],
    queryFn: async (c) => {
      if (!targetPubkey) return undefined;
      
      const signal = AbortSignal.any([c.signal, AbortSignal.timeout(5000)]);
      const sourcePubkey = user?.pubkey || '20e7c953...';

      // Try Relatr first if enabled
      if (RELATR_ENABLED) {
        try {
          const relatrScore = await relatrClient.getScore(sourcePubkey, targetPubkey);
          if (relatrScore) {
            const normalized = normalizeRelatrScore(relatrScore.score);
            console.log(`[Relatr] Score for ${targetPubkey.slice(0,8)}: ${normalized}`);
            return normalized;
          }
        } catch (error) {
          console.warn('[Relatr] API failed, falling back to local WoT:', error);
        }
      }

      // Fallback: Local WoT calculation
      return await calculateLocalWoT(nostr, sourcePubkey, targetPubkey, signal);
    },
    // ... rest of config
  });
}
```

## Testing Plan

### Phase 1: API Discovery
- [ ] Determine actual Relatr API structure (REST vs MCP vs Nostr events)
- [ ] Test API endpoints with sample requests
- [ ] Document authentication requirements
- [ ] Measure response times and rate limits

### Phase 2: Integration
- [ ] Implement Relatr client in `src/lib/relatr.ts`
- [ ] Add feature flag in settings
- [ ] Update `useTrustScore` with fallback logic
- [ ] Update `useBatchTrustScores` for batch requests

### Phase 3: Testing
- [ ] Test with various pubkeys (followed, friends-of-friends, unknown)
- [ ] Verify score normalization
- [ ] Test offline behavior (should fall back gracefully)
- [ ] Performance testing (ensure < 1s response times)

### Phase 4: Analytics
- [ ] Add "Powered by Relatr" badge to stats page
- [ ] Show comparison: Local WoT vs Relatr scores
- [ ] Display Relatr metadata (distance, NIP-05, LUD16 status)

## How It Works (NIP-85)

### Event Format

Relatr publishes kind 30382 events (User Trust Assertions):

```json
{
  "kind": 30382,
  "pubkey": "<relatr-service-pubkey>",
  "tags": [
    ["d", "<target-user-pubkey>"],
    ["rank", "85"],              // Trust score 0-100
    ["followers", "1234"],       // Follower count
    ["post_cnt", "567"],         // Number of posts
    ["zap_amt_recd", "50000"],   // Sats received
    // ... other metrics
  ],
  "content": ""
}
```

### Integration Steps

**Step 1**: Find Relatr's Service Pubkey
- Visit https://www.relatr.xyz/about
- Look for their npub or hex pubkey
- OR query Nostr: `kinds: [0], search: "relatr"`

**Step 2**: Enable in Settings
- Go to Settings → Advanced → Relatr Integration
- Enter service pubkey (or click Auto-Discover)
- Click "Enable Relatr"

**Step 3**: Query Trust Scores
```typescript
import { useRelatrScore } from '@/hooks/useRelatrScore';

// Query Relatr's NIP-85 assertion for a user
const { data: relatrScore } = useRelatrScore(targetPubkey);

if (relatrScore) {
  console.log('Global trust rank:', relatrScore.rank); // 0-100
  console.log('Followers:', relatrScore.followers);
  console.log('Posts:', relatrScore.postCount);
}
```

**No API keys, no authentication needed** - just query Nostr events!

## Resources

- **Relatr Website**: https://www.relatr.xyz/
- **GitHub Repo**: https://github.com/ContextVM/relatr
- **ContextVM Org**: https://github.com/ContextVM
- **Contact**: Check Relatr GitHub issues or ContextVM Nostr account

## Next Steps

1. **Contact Relatr Team** - Get API documentation or examples
2. **Test API** - Verify endpoints work and understand response format
3. **Implement Client** - Complete `src/lib/relatr.ts` with actual API
4. **Add Feature Flag** - Toggle Relatr integration in settings
5. **Update UI** - Show "Powered by Relatr" when enabled
6. **Monitor Performance** - Ensure < 1s response times for good UX

---

**Status**: Waiting for Relatr API documentation to complete integration.

**ETA**: Can be completed in 2-3 hours once API structure is confirmed.