SatRank

라이트닝 결제를 위한 경로 신뢰성. 에이전트 경제를 위해 구축되었습니다.

SatRank는 라이트닝 엔드포인트의 신뢰성을 점수화합니다. 각 결제 전, 에이전트는 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에서 수동 의존성 주입을 사용합니다.

점수 산정 알고리즘

5가지 가중치 요소를 기반으로 계산된 0-100점의 복합 점수:

요소	가중치	설명
거래량	25%	검증된 거래, 로그 정규화
평판	30%	그래프 중심성 + 피어 신뢰도(BTC/채널). LN+ 등급 보너스(최대 +8)
연차	15%	처음 발견된 후 경과 일수, 체감 수익
규칙성	15%	거래 간격의 변동 계수 역수
다양성	15%	고유 거래 상대방, 로그 정규화

어뷰징 방지:

상호 증명 루프 감지(A↔B), 95% 페널티
순환 클러스터 감지(A→B→C→A), 90% 페널티
BFS를 통한 확장된 사이클 감지(A→B→C→D→A, 최대 4홉), 90% 페널티
증명에 최소 7일 이상의 연차 필요
증명자 점수 가중치 적용(PageRank 방식의 재귀)
증명 소스 집중도 페널티

API

결정 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>

점수 및 판정 API

curl http://localhost:3000/api/agent/<hash>/verdict
# Returns: SAFE / RISKY / UNKNOWN with confidence, flags, risk profile

일괄 판정

curl -X POST http://localhost:3000/api/verdicts \
  -H "Content-Type: application/json" \
  -d '{"hashes": ["abc123...", "def456..."]}'

에이전트 점수

curl http://localhost:3000/api/agent/<hash>
# Returns: score, components, evidence, delta, alerts

점수 기록

curl http://localhost:3000/api/agent/<hash>/history?limit=10

수신된 증명

curl http://localhost:3000/api/agent/<hash>/attestations?limit=20

리더보드

curl http://localhost:3000/api/agents/top?limit=20&sort_by=score

급상승 에이전트

curl http://localhost:3000/api/agents/movers

별칭으로 검색

curl http://localhost:3000/api/agents/search?alias=atlas

증명 제출 (무료 — 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"}'

상태 및 통계

curl http://localhost:3000/api/health
curl http://localhost:3000/api/stats

MCP 서버

SatRank는 stdio를 통해 에이전트 네이티브 액세스를 위한 MCP(Model Context Protocol) 서버를 노출합니다. 신뢰 결정, 점수 산정, 검색 및 보고를 다루는 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개)

도구	설명
`decide`	성공 확률을 포함한 GO/NO-GO 결정 — 결제 전 기본 도구
`report`	결과 보고(성공/실패/시간 초과) — API 키 필요
`get_profile`	보고서, 가동 시간, 순위, 증거를 포함한 전체 에이전트 프로필
`get_agent_score`	구성 요소 및 증거를 포함한 상세 신뢰 점수
`get_verdict`	위험 프로필 및 경로 탐색을 포함한 SAFE/RISKY/UNKNOWN 판정
`get_batch_verdicts`	최대 100개 에이전트에 대한 일괄 판정
`get_top_agents`	점수 기준 리더보드
`search_agents`	별칭으로 검색 (부분 일치)
`get_network_stats`	글로벌 네트워크 통계
`get_top_movers`	7일간 점수 변화가 가장 큰 에이전트
`submit_attestation`	신뢰 증명 제출 — API 키 필요

수동 실행

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는 라이트닝 노드에 대한 신뢰 점수를 NIP-85 Trusted Assertions (kind 30382)로 게시합니다.

게시 내용: 복합 점수(0-100), 판정(SAFE/RISKY/UNKNOWN), 도달 가능성, 생존 예측, 그리고 점수가 30 이상인 약 3,900개 노드에 대한 5가지 점수 산정 구성 요소.

주기: 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)가 본편이며, L402를 통해 1사토시가 부과됩니다.

기술 스택

TypeScript 엄격 모드
Express — REST API
better-sqlite3 — 내장 데이터베이스, WAL 모드
zod — 입력 유효성 검사
pino — 구조화된 로깅
helmet — 보안 헤더
express-rate-limit — 남용 방지

스크립트

스크립트	설명
`npm run dev`	핫 리로드가 포함된 개발 모드 (tsx watch)
`npm run build`	TypeScript 컴파일
`npm start`	프로덕션 모드
`npm test`	테스트 (vitest)
`npm run lint`	TypeScript 체크
`npm run crawl`	Observer Protocol 크롤러
`npm run crawl:cron`	크론 모드 크롤러
`npm run mcp`	MCP 서버 (개발)
`npm run mcp:prod`	MCP 서버 (프로덕션)
`npm run purge`	오래된 데이터 삭제
`npm run backup`	데이터베이스 백업
`npm run rollback`	데이터베이스 롤백
`npm run calibrate`	점수 산정 보정 보고서
`npm run demo`	증명 데모 스크립트
`npm run sdk:build`	TypeScript SDK 빌드

로드맵

[x] 결정 API — 성공 확률을 포함한 GO/NO-GO, 결과 보고, 에이전트 프로필
[x] 개인화된 경로 탐색 — LND QueryRoutes를 통한 호출자에서 대상까지의 실시간 경로
[x] Aperture 통합 (L402 리버스 프록시) — 사토시 단위의 쿼리 수익화
[x] Observer Protocol 크롤러 — 자동 온체인 데이터 수집
[x] 라이트닝 그래프 크롤러 — LND 노드를 통한 채널 토폴로지 및 용량
[x] 경로 프로브 크롤러 — 인덱싱된 노드에 대한 도달 가능성 테스트
[x] 에이전트용 TypeScript SDK (@satrank/sdk)
[x] 판정 API — SAFE/RISKY/UNKNOWN 이진 결정
[x] MCP 서버 — stdio를 통한 에이전트 네이티브 액세스
[x] 자동 인덱싱 — 요청 시 알 수 없는 공개 키 인덱싱
[ ] 4tress 커넥터 — 검증된 증명
[ ] 신뢰 네트워크 시각화 대시보드

비전

SatRank는 모든 라이트닝 결제 전의 신뢰성 검사 도구입니다. 네트워크의 66%가 유령 노드인 상황에서, 어떤 엔드포인트가 활성 상태인지 알려드립니다.

SatRank

SatRank

시작하기

아키텍처

점수 산정 알고리즘

API

결정 API (에이전트를 위한 기본 인터페이스)

점수 및 판정 API

일괄 판정

에이전트 점수

점수 기록

수신된 증명

리더보드

급상승 에이전트

별칭으로 검색

증명 제출 (무료 — L402 없음)

상태 및 통계

MCP 서버

Claude Code에 설치

Cursor / VS Code에 설치

사용 가능한 도구 (11개)

수동 실행

SDK

Nostr 통합

기술 스택

스크립트

로드맵

비전

Resources

Latest Blog Posts

MCP directory API