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:

Factor	Weight	Description
Volume	25%	Verified transactions, log-normalized
Reputation	30%	Graph centrality + peer trust (BTC/channel). LN+ ratings as bonus (+8 max)
Seniority	15%	Days since first seen, diminishing returns
Regularity	15%	Inverse coefficient of variation of transaction intervals
Diversity	15%	Unique counterparties, log-normalized

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)

Tool	Description
decide	GO/NO-GO with success probability — the primary pre-transaction tool
ping	Real-time reachability check via QueryRoutes (free)
report	Report outcome (success/failure/timeout) — requires API key
get_profile	Full agent profile with reports, uptime, rank, evidence
get_agent_score	Detailed trust score with components and evidence
get_verdict	SAFE/RISKY/UNKNOWN with risk profile and pathfinding
get_batch_verdicts	Batch verdict for up to 100 agents
get_top_agents	Leaderboard ranked by score
search_agents	Search by alias (partial match)
get_network_stats	Global network statistics
get_top_movers	Agents with biggest 7-day score changes
submit_attestation	Submit a trust attestation — requires API key

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

Script	Description
npm run dev	Development with hot reload (tsx watch)
npm run build	TypeScript compilation
npm start	Production
npm test	Tests (vitest)
npm run lint	TypeScript check
npm run crawl	Observer Protocol crawler
npm run crawl:cron	Crawler en mode cron
npm run mcp	MCP server (dev)
npm run mcp:prod	MCP server (production)
npm run purge	Purge stale data
npm run backup	Database backup
npm run rollback	Database rollback
npm run calibrate	Scoring calibration report
npm run demo	Attestation demo script
npm run sdk:build	Build TypeScript SDK

Roadmap

• [x] Decision API — GO/NO-GO with success probability, outcome reports, agent profiles
• [x] Personalized pathfinding — real-time route from caller to target via LND QueryRoutes
• [x] Aperture integration (L402 reverse proxy) — monetize queries in sats
• [x] Observer Protocol crawler — automatic on-chain data ingestion
• [x] Lightning graph crawler — channel topology and capacity via LND node
• [x] Route probe crawler — reachability testing for indexed nodes
• [x] TypeScript SDK for agents (@satrank/sdk)
• [x] Verdict API — SAFE/RISKY/UNKNOWN binary decision
• [x] MCP server — agent-native access via stdio
• [x] 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.