SatRank

Fiabilidad de rutas para pagos Lightning. Creado para la economía de agentes.

SatRank puntúa la fiabilidad de los endpoints de Lightning. Antes de cada pago, un agente consulta a SatRank para obtener una decisión de GO/NO-GO: una solicitud, una respuesta, 1 sat.

Primeros pasos

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

Arquitectura

routes → controllers → services → repositories → SQLite

Capas:

• Routes — Definiciones de endpoints de Express

• Controllers — Validación de entrada (zod), formato de respuesta

• Services — Lógica de negocio y orquestación

• Repositories — Acceso a datos SQLite (better-sqlite3)

Inyección de dependencias manual en src/app.ts para facilitar las pruebas.

Algoritmo de puntuación

Puntuación compuesta de 0 a 100 calculada a partir de 5 factores ponderados:

Anti-juego:

• Detección de bucles de atestación mutua (A↔B) con penalización del 95%

• Detección de clústeres circulares (A→B→C→A) con penalización del 90%

• Detección de ciclos extendidos mediante BFS (A→B→C→D→A, hasta 4 saltos) con penalización del 90%

• Se requiere una antigüedad mínima de 7 días para atestar

• Ponderación de la puntuación del atestador (recursión tipo PageRank)

• Penalización por concentración de fuentes de atestación

API

API de decisión (interfaz principal para agentes)

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

API de puntuación y veredicto

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

Veredictos por lotes

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

Puntuación del agente

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

Historial de puntuaciones

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

Atestaciones recibidas

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

Tabla de clasificación

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

Los que más suben

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

Búsqueda por alias

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

Enviar atestación (gratis — sin 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"}'

Salud y estadísticas

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

Servidor MCP

SatRank expone un servidor MCP (Model Context Protocol) para acceso nativo de agentes a través de stdio. 11 herramientas que cubren decisiones de confianza, puntuación, búsqueda e informes.

Instalar en Claude Code

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

O con variables de entorno:

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

Instalar en Cursor / VS Code

Añadir a .cursor/mcp.json o .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"
      }
    }
  }
}

Herramientas disponibles (11)

Ejecutar manualmente

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>');

Integración con Nostr

SatRank publica puntuaciones de confianza para nodos Lightning como NIP-85 Trusted Assertions (tipo 30382).

Qué se publica: puntuación compuesta (0-100), veredicto (SAFE/RISKY/UNKNOWN), accesibilidad, predicción de supervivencia y 5 componentes de puntuación para ~3.900 nodos con puntuación >= 30.

Frecuencia: cada 6 horas.

Formato del evento:

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

Consultar aserciones desde cualquier cliente Nostr:

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

¿Por qué es gratis? Las puntuaciones globales son el tráiler. El /api/decide personalizado (búsqueda de rutas desde TU posición, supervivencia, P_empírica) es la película: 1 sat vía L402.

Stack tecnológico

• TypeScript modo estricto

• Express — API REST

• better-sqlite3 — Base de datos embebida, modo WAL

• zod — Validación de entrada

• pino — Registro estructurado

• helmet — Cabeceras de seguridad

• express-rate-limit — Protección contra abusos

Scripts

Hoja de ruta

• [x] API de decisión: GO/NO-GO con probabilidad de éxito, informes de resultados, perfiles de agentes

• [x] Búsqueda de rutas personalizada: ruta en tiempo real desde el llamador al objetivo vía LND QueryRoutes

• [x] Integración con Aperture (proxy inverso L402): monetizar consultas en sats

• [x] Rastreador del Protocolo Observer: ingesta automática de datos on-chain

• [x] Rastreador de grafos Lightning: topología de canales y capacidad vía nodo LND

• [x] Rastreador de sondeo de rutas: pruebas de accesibilidad para nodos indexados

• [x] SDK de TypeScript para agentes (@satrank/sdk)

• [x] API de veredicto: decisión binaria SAFE/RISKY/UNKNOWN

• [x] Servidor MCP: acceso nativo de agentes vía stdio

• [x] Auto-indexación: claves públicas desconocidas indexadas bajo demanda

• [ ] Conector 4tress: atestaciones verificadas

• [ ] Panel de visualización de la red de confianza

Visión

SatRank es la comprobación de fiabilidad antes de cada pago Lightning. El 66% de la red son nodos fantasma: nosotros te decimos qué endpoints están vivos.