SatRank — Lightning trust + audit oracle

SatRank

L402 上的 AI エージェント向け高速トラストオラクル。ビットコイン純粋主義。

これは何をするものか

• L402 エコシステム（l402.directory + RSS + DNS）をクロールし、有料エンドポイントのカタログを作成します。
• 各エンドポイントをプローブし、チャレンジ／請求書／支払い／配信／品質の 5 段階で結果を分類します。
• すべての（エンドポイント、段階）の組み合わせを、ストリーミング Beta(α, β) 事後分布としてスコアリングします。エンドツーエンドの成功確率は各段階の平均値の積です。
• POST /api/intent（L402 経由で 2 sats の有料）で候補をランキングします。エージェントがカテゴリ + 予算 + SLA を渡すと、ベイズ分析の詳細を含む上位 K 件のエンドポイントが返されます。
• 署名済みの Nostr 信頼アサーション（kind 30782）を公開し、あらゆるエージェントが 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（9 つのルート — 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

デポジット・マカロンを使うと、エージェントは N sats を一度に前払いし、呼び出しごとに Lightning を往復することなく、複数の /api/intent 呼び出しでベアラープリイメージを使用できます。Authorization: L402 deposit_<id>:<preimage_hex>。

MCP

あらゆる MCP 互換 AI ランタイム（Claude Code、Cursor、Codex、n8n）で使える 3 つのツール：

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 つ（HTML ページ 3 つ + 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

段階の平均値：α / (α+β)。Wilson 法による 95% 信用区間（閉形式）。エンドツーエンドの成功確率：段階間の独立性を仮定した、5 段階の平均値の積 ∏ stage_means。

is_meaningful が true になるのは、challenge 段階の観測数が MEANINGFUL_N_OBS_MIN 以上の場合に限られます。challenge 段階はすべてのプローブ（無料または有料）で観測されるため、n_obs は最も速く収束します。p_e2e は、これとは別にエンドツーエンドの積を誠実に示します。

ライセンス

AGPL-3.0