SatRank — Lightning trust + audit oracle

SatRank

适用于 L402 上 AI Agent 的闪电网络信任预言机。纯 Bitcoin。

功能

• 爬取 L402 生态（l402.directory + RSS + DNS），建立付费端点目录。
• 探测每个端点，并按 5 个阶段对结果进行分类：质询 / 发票 / 支付 / 交付 / 质量。
• 将每个（端点，阶段）配对表示为流式 Beta(α, β) 后验分布并进行评分。端到端成功概率为各阶段均值的乘积。
• 在 POST /api/intent 上排名候选项（通过 L402 付费 2 sats）：Agent 提交类别 + 预算 + SLA，获取排名前 K 的端点及完整的贝叶斯分析结果。
• 发布已签名的 Nostr 信任断言（kind 30782），让任何 Agent 都能离线缓存 / 验证 SatRank 的输出。

公共端点

文档页面：

GET  /                                 landing page (static HTML)
GET  /methodology                      technical reference (static HTML)
GET  /api                              API reference (static HTML)
GET  /openapi.json                     OpenAPI 3.0 spec (machine-readable)

功能 API（共九个路由——只有 POST /api/intent 受 L402 门控）：

POST /api/intent                       paid, 2 sats via L402
POST /api/deposit                      free, mint a multi-use deposit macaroon (10–10000 sats, 30-day TTL)
GET  /api/deposit/:macaroon_id         free, read remaining balance
GET  /api/services/:url_hash           free, per-endpoint score snapshot
GET  /api/services/categories          free, list of catalogue categories
GET  /api/services/best                free, top-3 per category (5-min cache)
GET  /api/oracle/budget                free, last 24h revenue + paid-probe spend
GET  /health                           free, liveness
GET  /.well-known/satrank-key          free, oracle pubkey for offline verify

存款 macaroon 可让 Agent 一次预付 N sats，并在多次 /api/intent 调用中使用 bearer 原像，无需每次调用都进行 Lightning 往返。 Authorization: L402 deposit_<id>:<preimage_hex>。

MCP

适用于任何兼容 MCP 的 AI 运行时（Claude Code、Cursor、Codex、n8n）的三个工具：

intent              forwards POST /api/intent (paid)
get_endpoint_score  forwards GET /api/services/:url_hash (free)
verify_assertion    offline Schnorr verification of kind 30782 (no network)

在 Claude Code 中安装：

claude mcp add satrank -- npx -y satrank-mcp

可自托管的用户将 SATRANK_API_BASE 指向自己的部署。

架构

14 个源文件 + 4 个文档页面（3 个 HTML 页面 + OpenAPI 规范）。30 分钟内即可从头读完。

src/
├── types.ts             Stage, Posterior, Endpoint, Observation
├── config.ts            zod env schema, parsed once at boot
├── logger.ts            JSON-line stdout
├── db.ts                pg Pool + idempotent schema bootstrap
├── schema.sql           9 tables in ONE file (no migrations folder)
├── lnd.ts               minimal LND REST client (addInvoice + payInvoice)
├── ssrf.ts              RFC1918 + link-local + IPv6 ULA URL guard
├── nostr.ts             kind 30782 sign + publish + offline verify
├── scoring.ts           Beta(α,β) per stage, Wilson CI95, ranker
├── probe.ts             HTTP probe with optional L402 pay
├── crawler.ts           l402.directory + RSS + DNS + cron
├── api.ts               Express; 9 functional routes + 4 doc surfaces, native L402 paid gate, deposit credits
├── mcp.ts               MCP server, 3 tools, ships verbatim to npm
├── landing.html         static landing served at GET /
├── methodology.html     technical reference served at GET /methodology
├── api-reference.html   API reference served at GET /api
├── openapi.json         OpenAPI 3.0 spec served at GET /openapi.json
└── index.ts             boot + shutdown

运行

cp .env.example .env
# minimum: set DATABASE_URL

npm install
npm run build
npm start

如需启用付费探测 + 付费 /api/intent 门控，请设置 LND_REST_URL + LND_MACAROON_HEX + L402_MACAROON_SECRET。如需启用 Nostr 信任断言，请设置 NOSTR_PRIVATE_KEY。

评分数学

对每个（端点，阶段），使用 α₀ = β₀ = 1（均匀先验）维护 Beta(α, β) 后验分布。每次观测时：

• 成功 → α += 1
• 失败 → β += 1

阶段均值：α / (α+β)。95% 可信区间通过 Wilson 方法计算（闭式解）。假设各阶段相互独立，端到端成功概率为 5 个阶段均值的乘积。

当且仅当 challenge 阶段至少有 MEANINGFUL_N_OBS_MIN 次观测时，is_meaningful 才为 true。每次探测（免费或付费）都会观测 challenge 阶段，因此该阶段的 n_obs 收敛最快。p_e2e 仍单独保留，作为诚实的端到端乘积。

许可证

AGPL-3.0