SatRank

Routen-Zuverlässigkeit für Lightning-Zahlungen. Entwickelt für die Agenten-Ökonomie.

SatRank bewertet die Zuverlässigkeit von Lightning-Endpunkten. Vor jeder Zahlung fragt ein Agent SatRank nach einer GO/NO-GO-Entscheidung ab — eine Anfrage, eine Antwort, 1 Sat.

Erste Schritte

npm install
npm run dev     # Start development server on :3000

Architektur

routes → controllers → services → repositories → SQLite

Ebenen:

• Routes — Definitionen der Express-Endpunkte

• Controllers — Eingabevalidierung (zod), Antwortformatierung

• Services — Geschäftslogik und Orchestrierung

• Repositories — SQLite-Datenzugriff (better-sqlite3)

Manuelle Dependency Injection in src/app.ts für Testbarkeit.

Bewertungsalgorithmus

Ein zusammengesetzter Score von 0-100, berechnet aus 5 gewichteten Faktoren:

Anti-Gaming:

• Erkennung gegenseitiger Attestierungsschleifen (A↔B) mit 95% Strafe

• Erkennung zirkulärer Cluster (A→B→C→A) mit 90% Strafe

• Erweiterte Zykluserkennung via BFS (A→B→C→D→A, bis zu 4 Hops) mit 90% Strafe

• Mindestens 7 Tage Seniorität für Attestierungen erforderlich

• Gewichtung der Attestierer-Scores (PageRank-ähnliche Rekursion)

• Strafe für Konzentration der Attestierungsquellen

API

Decision API (primäre Schnittstelle für Agenten)

# GO / NO-GO decision with success probability
curl -X POST http://localhost:3000/api/decide \
  -H "Content-Type: application/json" \
  -d '{"target": "<hash>", "caller": "<your-hash>"}'

# Report transaction outcome (free — no L402)
curl -X POST http://localhost:3000/api/report \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <key>" \
  -d '{"target": "<hash>", "reporter": "<your-hash>", "outcome": "success"}'

# Agent profile with reports, uptime, rank
curl http://localhost:3000/api/profile/<hash>

Score & Verdict API

curl http://localhost:3000/api/agent/<hash>/verdict
# Returns: SAFE / RISKY / UNKNOWN with confidence, flags, risk profile

Batch Verdicts

curl -X POST http://localhost:3000/api/verdicts \
  -H "Content-Type: application/json" \
  -d '{"hashes": ["abc123...", "def456..."]}'

Agent Score

curl http://localhost:3000/api/agent/<hash>
# Returns: score, components, evidence, delta, alerts

Score History

curl http://localhost:3000/api/agent/<hash>/history?limit=10

Received Attestations

curl http://localhost:3000/api/agent/<hash>/attestations?limit=20

Leaderboard

curl http://localhost:3000/api/agents/top?limit=20&sort_by=score

Top Movers

curl http://localhost:3000/api/agents/movers

Search by Alias

curl http://localhost:3000/api/agents/search?alias=atlas

Submit Attestation (kostenlos — kein L402)

curl -X POST http://localhost:3000/api/attestations \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-key>" \
  -d '{"txId": "...", "attesterHash": "...", "subjectHash": "...", "score": 85, "category": "successful_transaction"}'

Health & Stats

curl http://localhost:3000/api/health
curl http://localhost:3000/api/stats

MCP Server

SatRank stellt einen MCP-Server (Model Context Protocol) für agenten-nativen Zugriff via stdio bereit. 11 Tools decken Vertrauensentscheidungen, Scoring, Suche und Berichterstattung ab.

Installation in Claude Code

claude mcp add satrank -- npx tsx src/mcp/server.ts

Oder mit Umgebungsvariablen:

claude mcp add satrank -e DB_PATH=./data/satrank.db -e SATRANK_API_KEY=<key> -- npx tsx src/mcp/server.ts

Installation in Cursor / VS Code

Hinzufügen zu .cursor/mcp.json oder .vscode/mcp.json:

{
  "mcpServers": {
    "satrank": {
      "command": "npx",
      "args": ["tsx", "src/mcp/server.ts"],
      "cwd": "/path/to/satrank",
      "env": {
        "DB_PATH": "./data/satrank.db",
        "SATRANK_API_KEY": "your-api-key"
      }
    }
  }
}

Verfügbare Tools (11)

Manuell ausführen

npm run mcp        # Development
npm run mcp:prod   # Production

SDK

npm install @satrank/sdk

import { SatRankClient } from '@satrank/sdk';

const client = new SatRankClient('http://localhost:3000');

// Full cycle in one line: decide → pay → report
const result = await client.transact('<target-hash>', '<your-hash>', async () => {
  const payment = await myWallet.pay(invoice);
  return { success: payment.ok, preimage: payment.preimage, paymentHash: payment.hash };
});
// result.paid, result.decision.go, result.report.weight

// Or step by step
const decision = await client.decide({ target: '<hash>', caller: '<your-hash>' });
const profile = await client.getProfile('<hash>');
const verdict = await client.getVerdict('<hash>');

Nostr-Integration

SatRank veröffentlicht Vertrauens-Scores für Lightning-Nodes als NIP-85 Trusted Assertions (Typ 30382).

Was wird veröffentlicht: Zusammengesetzter Score (0-100), Urteil (SAFE/RISKY/UNKNOWN), Erreichbarkeit, Überlebensprognose und 5 Scoring-Komponenten für ca. 3.900 Nodes mit einem Score >= 30.

Frequenz: alle 6 Stunden.

Event-Format:

{
  "kind": 30382,
  "tags": [
    ["d", "<lightning_pubkey>"],
    ["n", "lightning"],
    ["alias", "Kraken"],
    ["score", "94"],
    ["verdict", "SAFE"],
    ["reachable", "true"],
    ["survival", "stable"],
    ["volume", "100"],
    ["reputation", "79"],
    ["seniority", "87"],
    ["regularity", "100"],
    ["diversity", "100"]
  ],
  "content": ""
}

Assertions von jedem Nostr-Client abfragen:

["REQ", "satrank", {"kinds": [30382], "authors": ["<SATRANK_NOSTR_PUBKEY>"]}]

Warum kostenlos? Globale Scores sind der Trailer. Die personalisierte /api/decide (Routenfindung von IHRER Position, Überleben, P_empirical) ist der Film — 1 Sat via L402.

Tech Stack

• TypeScript Strict Mode

• Express — REST API

• better-sqlite3 — Eingebettete Datenbank, WAL-Modus

• zod — Eingabevalidierung

• pino — Strukturiertes Logging

• helmet — Sicherheits-Header

• express-rate-limit — Schutz vor Missbrauch

Skripte

Roadmap

• [x] Decision API — GO/NO-GO mit Erfolgswahrscheinlichkeit, Ergebnisberichten, Agentenprofilen

• [x] Personalisierte Routenfindung — Echtzeit-Route vom Anrufer zum Ziel via LND QueryRoutes

• [x] Aperture-Integration (L402 Reverse Proxy) — Monetarisierung von Anfragen in Sats

• [x] Observer Protocol Crawler — automatische On-Chain-Datenaufnahme

• [x] Lightning Graph Crawler — Kanaltopologie und Kapazität via LND-Node

• [x] Route Probe Crawler — Erreichbarkeitstests für indizierte Nodes

• [x] TypeScript SDK für Agenten (@satrank/sdk)

• [x] Verdict API — SAFE/RISKY/UNKNOWN binäre Entscheidung

• [x] MCP-Server — agenten-nativer Zugriff via stdio

• [x] Auto-Indizierung — unbekannte Pubkeys werden bei Bedarf indiziert

• [ ] 4tress-Connector — verifizierte Attestierungen

• [ ] Dashboard zur Visualisierung des Vertrauensnetzwerks

Vision

SatRank ist der Zuverlässigkeitscheck vor jeder Lightning-Zahlung. 66% des Netzwerks sind Phantom-Nodes — wir sagen Ihnen, welche Endpunkte aktiv sind.