SatRank

Надежность маршрутов для платежей Lightning. Создано для экономики агентов.

SatRank оценивает надежность конечных точек Lightning. Перед каждым платежом агент запрашивает у SatRank решение GO/NO-GO — один запрос, один ответ, 1 сат.

Начало работы

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

Архитектура

routes → controllers → services → repositories → SQLite

Слои:

• Routes — определения конечных точек Express

• Controllers — валидация входных данных (zod), форматирование ответов

• Services — бизнес-логика и оркестрация

• Repositories — доступ к данным SQLite (better-sqlite3)

Ручное внедрение зависимостей в src/app.ts для обеспечения тестируемости.

Алгоритм оценки

Составная оценка от 0 до 100, вычисляемая на основе 5 взвешенных факторов:

Защита от манипуляций:

• Обнаружение циклов взаимной аттестации (A↔B) со штрафом 95%

• Обнаружение циклических кластеров (A→B→C→A) со штрафом 90%

• Обнаружение расширенных циклов через BFS (A→B→C→D→A, до 4 переходов) со штрафом 90%

• Требуется минимальный стаж 7 дней для аттестации

• Взвешивание оценок аттестаторов (рекурсия типа PageRank)

• Штраф за концентрацию источников аттестации

API

Decision API (основной интерфейс для агентов)

# 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 (бесплатно — без 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 предоставляет сервер MCP (Model Context Protocol) для доступа агентов через stdio. 11 инструментов, охватывающих принятие решений о доверии, оценку, поиск и отчетность.

Установка в Claude Code

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

Или с переменными окружения:

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

Установка в Cursor / VS Code

Добавьте в .cursor/mcp.json или .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"
      }
    }
  }
}

Доступные инструменты (11)

Запуск вручную

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

SatRank публикует оценки доверия для узлов Lightning как NIP-85 Trusted Assertions (тип 30382).

Что публикуется: составная оценка (0-100), вердикт (SAFE/RISKY/UNKNOWN), доступность, прогноз выживаемости и 5 компонентов оценки для ~3900 узлов с оценкой >= 30.

Частота: каждые 6 часов.

Формат события:

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

Запрос утверждений из любого клиента Nostr:

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

Почему бесплатно? Глобальные оценки — это трейлер. Персонализированный /api/decide (поиск пути из ВАШЕЙ позиции, выживаемость, P_empirical) — это фильм — 1 сат через L402.

Технологический стек

• TypeScript в строгом режиме

• Express — REST API

• better-sqlite3 — встроенная база данных, режим WAL

• zod — валидация входных данных

• pino — структурированное логирование

• helmet — заголовки безопасности

• express-rate-limit — защита от злоупотреблений

Скрипты

Дорожная карта

• [x] Decision API — GO/NO-GO с вероятностью успеха, отчетами о результатах, профилями агентов

• [x] Персонализированный поиск пути — маршрут в реальном времени от вызывающего к цели через LND QueryRoutes

• [x] Интеграция Aperture (обратный прокси L402) — монетизация запросов в сатах

• [x] Краулер Observer Protocol — автоматическое получение данных из блокчейна

• [x] Краулер графа Lightning — топология каналов и емкость через узел LND

• [x] Краулер зондирования маршрутов — проверка доступности для индексированных узлов

• [x] TypeScript SDK для агентов (@satrank/sdk)

• [x] Verdict API — бинарное решение SAFE/RISKY/UNKNOWN

• [x] Сервер MCP — доступ для агентов через stdio

• [x] Автоиндексация — неизвестные pubkey индексируются по запросу

• [ ] Коннектор 4tress — верифицированные аттестации

• [ ] Панель визуализации сети доверия

Видение

SatRank — это проверка надежности перед каждым платежом Lightning. 66% сети — это фантомные узлы, мы подскажем вам, какие конечные точки активны.