nullxnothing/ricomaps
GitHub: nullxnothing/ricomaps
Solana 链上取证情报工具，通过可视化资金链追踪和协同交易检测来识别代币发行中的狙击者、利益集团与打包集群。
Stars: 1 | Forks: 0
# RicoMaps
Solana 取证情报工具。追踪钱包资金链，检测垄断资金方、狙击者以及代币发行过程中的协调打包集群。
## 功能
- **Token 扫描** — 粘贴任意 Solana token mint。分析头部持有者，追踪各自的资金来源，并检测协同操作者。
- **钱包扫描** — 从任意钱包反向追踪资金链，找出为其提供资金的来源。
- **利益集团检测** — 识别为多个代币持有者提供资金的钱包（共同资金方）。
- **狙击者检测** — 标记在代币发行后前 10 个区块 / 60 秒内买入的钱包。
- **打包检测** — 检测在同一个 Jito bundle 中买入的钱包（相同 slot 的交易）。跨多次代币扫描追踪连续打包者。
- **黑名单** — 跨扫描累积的打包集群。可导出为 CSV。
- **实时流** — 通过 WebSocket 提供所监控钱包的实时交易流。
- **2D 力导向图** — 交互式 canvas 可视化，支持集群检测、节点类型和可疑链接高亮。
## 技术栈
- Next.js 16 (App Router)
- React 19
- TypeScript 5
- Tailwind CSS v4
- D3 力导向模拟 (canvas 渲染)
- Helius API (Solana RPC, Wallet API, DAS, Enhanced Transactions)
- PostgreSQL (可选，用于持久化缓存)
## 设置
```
git clone https://github.com/Nullxnothing/ricomaps.git
cd ricomaps
npm install
```
创建 `.env.local`：
```
HELIUS_API_KEY=your_helius_api_key
```
可选（用于更高吞吐量的额外 API key）：
```
HELIUS_API_KEY_2=
HELIUS_API_KEY_3=
HELIUS_API_KEY_4=
HELIUS_DEDICATED_RPC=
DATABASE_URL=postgresql://...
```
可选（Venum — 实时多 DEX 价格 + 实时 SSE 价格流）：
```
VENUM_API_KEY=your_venum_api_key
VENUM_BASE_URL=https://api.venum.dev # override only if needed
```
设置后，代币扫描将覆盖 Venum 的实时多 DEX 价格（该价格能在 GeckoTerminal/DexScreener 尚无数据的新发行代币上生效），并且 `/api/prices/stream` SSE 代理 + `useVenumPriceStream` hook 可提供实时价格，无需轮询。如果未设置，将回退到现有的价格源。
在 [dashboard.helius.dev](https://dashboard.helius.dev) 获取 Helius API key。
在 [app.venum.dev](https://app.venum.dev) 获取 Venum API key。
可选（Telegram 机器人 — 通过 `/scan
` 获取取证代币卡片）：
```
TELEGRAM_BOT_TOKEN=your_bot_token # from @BotFather
TELEGRAM_WEBHOOK_SECRET=long_random_string
NEXT_PUBLIC_APP_URL=https://ricomaps.fun # used for "Live Bubble Map" deep links
```
设置后，机器人会使用取证卡片响应 `/scan `（或在私信中的纯合约地址）— 包括 rug 分数、内部人士/利益集团/打包/狙击者的代币供应量，以及部署者情报 — 并附带指向实时气泡图的深度链接。注册 webhook：
```
TELEGRAM_BOT_TOKEN=... TELEGRAM_WEBHOOK_SECRET=... \
node scripts/telegram-set-webhook.mjs https://ricomaps.fun/api/telegram/webhook
```
可选（公共 API — 针对 `/api/v1/analyze` 的分级 key）：
```
RICO_API_KEYS=key1,key2 # legacy flat list, served at the default tier
RICO_API_DEFAULT_TIER=free # tier for RICO_API_KEYS (free | pro | enterprise)
RICO_API_KEYS_PRO= # comma-list of statically-provisioned pro keys
RICO_API_KEYS_ENTERPRISE= # comma-list of statically-provisioned enterprise keys
```
分级仅控制**访问权限**（速率限制 + 月度配额），绝不影响扫描或评分输出 — 参见 [`NEUTRALITY.md`](./NEUTRALITY.md)。限制：免费版 10 次请求/分钟 & 1k 次/月，专业版 60 次请求/分钟 & 50k 次/月，企业版 300 次请求/分钟 & 无限。
可选（Helio 订阅 — 基于链上支付自动配置 API key）：
```
HELIO_WEBHOOK_TOKEN=shared_secret # bearer token Helio signs each webhook with
HELIO_PAYLINK_PRO=paylink_id # Helio paylink mapped to the pro tier
HELIO_PAYLINK_ENTERPRISE=paylink_id
```
将 Helio 订阅 webhook (https://docs.hel.io) 指向 `/api/webhooks/helio`。在 `started`/`renewed` 状态下，它会配置一个分级 key（仅返回一次）；在 `ended` 状态下，它会撤销该订阅的 key。已配置的 key 会在 Postgres 中哈希存储，因此此路径需要 `DATABASE_URL`。
可选（代币推广 — 在 Telegram 机器人上显示“已赞助，依然客观评分”）：
```
PROMO_TIERS=[{"hours":6,"priceUsd":50},{"hours":24,"priceUsd":150},{"hours":72,"priceUsd":350}]
HELIO_PROMO_PAYLINK_URL=https://hel.io/pay/
```
`/promote `（或任意扫描卡片上的“📣 Promote”按钮）会运行扫描，拒绝明显的 rug 项目（活跃的 mint authority / 严重违规），并根据所选时长返回一个 Helio 结账链接。当支付完成时，同一个 `/api/webhooks/helio` 路由会激活推广（metadata 中包含 mint + 时长）。已激活的推广信息会显示在每张扫描卡片的底部，展示该代币**真实、未经修改的 rug 分数** — 参见 [`NEUTRALITY.md`](./NEUTRALITY.md)。需要 `DATABASE_URL` 以在不同实例间持久化。
可选（白标嵌入式卡片 — 将带有特定主题的取证卡片嵌入到合作伙伴网站或发射平台）：
```
```
通过 `RICO_PARTNER_BRANDS` 配置合作伙伴品牌（以 brand id 为键的 JSON）；未知 ID 会回退到 RicoMaps 默认设置，因此错误的 `?brand=` 绝不会破坏卡片：
```
RICO_PARTNER_BRANDS={"acme":{"name":"Acme Intel","appUrl":"https://acme.xyz","accentHex":"#ff00aa"}}
```
品牌主题**仅用于展示** — 无论使用哪个品牌，判定结果和徽章都是一致的（参见 [`NEUTRALITY.md`](./NEUTRALITY.md)）。
机器人扫描入口（`/api/internal/discord-scan`, `/api/internal/x-scan`）在其 POST body 中接受相同的可选 `brand` id，因此由合作伙伴运营的 Discord/X 机器人可以通过传入其 brand id 自动应用其卡片主题。
由合作伙伴运营的 **Telegram** 机器人通过其 webhook secret 应用主题。使用 `TELEGRAM_PARTNER_BRANDS` 将每个合作伙伴机器人的 secret 映射到 brand id；主机器人（`TELEGRAM_WEBHOOK_SECRET`）保持使用 RicoMaps 默认设置：
```
TELEGRAM_PARTNER_BRANDS={"":"acme"}
```
## 开发
```
npm run dev # Dev server on port 3600
npm run build # Production build
npm run lint # ESLint
npm run typecheck # tsc --noEmit
npm test # Vitest unit tests (scoring engine + API tiers)
```
## 架构
```
src/
├── app/
│ ├── page.tsx # Landing + graph view
│ ├── blacklist/page.tsx # Blacklist page
│ └── api/
│ ├── scan/route.ts # Auto-detect wallet vs token
│ ├── trace/route.ts # Wallet funding chain
│ ├── token/route.ts # Token holder analysis
│ ├── expand/route.ts # On-demand node expansion
│ ├── stream/route.ts # WebSocket transaction stream
│ ├── blacklist/route.ts # Bundle cluster queries
│ └── trending/route.ts # Trending tokens feed
├── components/
│ ├── BubbleMap.tsx # 2D force graph (canvas)
│ ├── StatsPanel.tsx # Risk + stats sidebar
│ ├── BlacklistView.tsx # Blacklist page UI
│ ├── ClusterCard.tsx # Bundle cluster card
│ └── ...
├── hooks/
│ ├── useGraphData.ts # Central graph state
│ ├── useBlacklist.ts # Blacklist data fetching
│ └── useTransactionStream.ts # WebSocket stream
└── lib/
├── helius.ts # Helius API wrapper (rate limiting, caching, retries)
├── holder-mapper.ts # Token holder analysis + cabal/sniper/bundle detection
├── graph-builder.ts # Wallet funding chain tracer (BFS)
├── bundle-detector.ts # Same-slot bundle cluster detection
├── graph-analysis.ts # Cluster detection (union-find) + centrality
├── db-cache.ts # PostgreSQL scan cache
├── db-blacklist.ts # Bundle cluster persistence (PG + in-memory fallback)
└── types.ts # All TypeScript interfaces
```
## Bundle 检测的工作原理
1. 在代币扫描期间，会获取所有已分析持有者的早期交易
2. 交易按 Solana slot 编号进行分组
3. 如果有 2 个及以上的持有者钱包在同一个 slot 内进行交易，它们很可能处于同一个 Jito bundle 中
4. 重叠的集群会被合并（并查集）
5. 集群持久化存储在 PostgreSQL（或内存）中，并跨扫描进行累积
6. 在多个代币的 bundle 中出现的钱包会被标记为连续打包者
## 许可证
MIT标签：Solana, Web3, 区块链, 测试用例, 自动化攻击, 链上取证