SkateSpots/RELATR_INTEGRATION.md

Relatr Integration Guide

Overview

Relatr (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

✅ 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:

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

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

# 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:

// 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:

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

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):

{
  "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

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.