SatRank

Route reliability for Lightning payments. Built for the agentic economy.

SatRank scores the reliability of Lightning endpoints. Before each payment, an agent queries SatRank for a GO/NO-GO decision — one request, one answer, 1 sat.

Getting Started

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

Architecture

routes → controllers → services → repositories → SQLite

Layers:

• Routes — Express endpoint definitions
• Controllers — Input validation (zod), response formatting
• Services — Business logic and orchestration
• Repositories — SQLite data access (better-sqlite3)

Manual dependency injection in src/app.ts for testability.

Scoring Algorithm

Composite score 0-100 computed from 5 weighted factors:

Anti-gaming:

• Mutual attestation loop detection (A↔B) with 95% penalty
• Circular cluster detection (A→B→C→A) with 90% penalty
• Extended cycle detection via BFS (A→B→C→D→A, up to 4 hops) with 90% penalty
• Minimum 7-day seniority required to attest
• Attester score weighting (PageRank-like recursion)
• Attestation source concentration penalty

API

Decision API (primary interface for agents)

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

# Real-time reachability check (free)
curl http://localhost:3000/api/ping/<ln-pubkey>
curl "http://localhost:3000/api/ping/<ln-pubkey>?from=<your-ln-pubkey>"

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 (free — no 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 exposes an MCP (Model Context Protocol) server for agent-native access via stdio. 12 tools covering trust decisions, scoring, search, and reporting.

Install in Claude Code

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

Or with environment variables:

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

Install in Cursor / VS Code

Add to .cursor/mcp.json or .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"
      }
    }
  }
}

Available tools (12)

Run manually

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 publishes trust scores for Lightning nodes as NIP-85 Trusted Assertions (kind 30382).

What's published: composite score (0-100), verdict (SAFE/RISKY/UNKNOWN), reachability, survival prediction, and 5 scoring components for ~3,900 nodes with score >= 30.

Frequency: every 6 hours.

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

Query assertions from any Nostr client:

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

Why free? Global scores are the trailer. The personalized /api/decide (pathfinding from YOUR position, survival, P_empirical) is the film — 1 sat via L402.

DVM — Data Vending Machine (NIP-90)

SatRank runs a DVM that responds to trust-check job requests on Nostr. Any agent can publish a kind 5900 event with ["j", "trust-check"] and ["i", "<ln_pubkey>", "text"], and SatRank responds with the score, verdict, and reachability. Free, no payment required.

Tech Stack

• TypeScript strict mode
• Express — REST API
• better-sqlite3 — Embedded database, WAL mode
• zod — Input validation
• pino — Structured logging
• helmet — Security headers
• express-rate-limit — Abuse protection

Scripts

Roadmap

• Decision API — GO/NO-GO with success probability, outcome reports, agent profiles
• Personalized pathfinding — real-time route from caller to target via LND QueryRoutes
• Aperture integration (L402 reverse proxy) — monetize queries in sats
• Observer Protocol crawler — automatic on-chain data ingestion
• Lightning graph crawler — channel topology and capacity via LND node
• Route probe crawler — reachability testing for indexed nodes
• TypeScript SDK for agents (@satrank/sdk)
• Verdict API — SAFE/RISKY/UNKNOWN binary decision
• MCP server — agent-native access via stdio
• Auto-indexation — unknown pubkeys indexed on demand
• 4tress connector — verified attestations
• Trust network visualization dashboard

Vision

SatRank is the reliability check before every Lightning payment. 66% of the network is phantom nodes — we tell you which endpoints are alive.