# Holder Scanner 使用说明

## 问题诊断

你遇到的问题是：**Scanner（扫描器）没有运行**，所以数据库中没有数据。

当前状态：
- ✅ API Server 正常运行
- ❌ Scanner 未启动（需要启动才能从区块链获取数据）
- ❌ 部署区块号可能不正确（需要更新）

## 解决步骤

### 第一步：获取正确的部署区块号

你数据库中的合约地址是：
- YT-A: `0x7f9eEA491eE53045594ee4669327f0355aCd0e58`
- YT-B: `0x20B94C5E5b7361552E0548161a58696aA6FeDBd4`
- YT-C: `0x0EF308D70cf35460E26a3Eb42F3442Ff28cbE07C`

**重要**：你需要找到这些合约的**实际部署区块号**。

#### 方法 1：通过 Arbiscan 查询

1. 访问 [Arbiscan Sepolia](https://sepolia.arbiscan.io/)
2. 搜索合约地址（例如：`0x7f9eEA491eE53045594ee4669327f0355aCd0e58`）
3. 查看 "Contract Creation" 或 "Contract Creator" 信息
4. 找到 "Block" 号码

#### 方法 2：使用 Web3 工具查询

```bash
# 使用 cast (foundry) 工具
cast block-number --rpc-url https://sepolia-rollup.arbitrum.io/rpc

# 或者使用 etherscan API
curl "https://api-sepolia.arbiscan.io/api?module=contract&action=getcontractcreation&contractaddresses=0x7f9eEA491eE53045594ee4669327f0355aCd0e58"
```

#### 方法 3：临时方案（不推荐）

如果暂时无法获取准确的部署区块号，可以使用一个较新的区块号（例如最新区块 - 10000），但这会导致：
- ⚠️ 可能遗漏早期的持有者数据
- ⚠️ 首次扫描时间更短，但数据不完整

### 第二步：更新 `.env` 配置

编辑 `.env` 文件，更新部署区块号：

```bash
# Deployment Block Numbers
YT_VAULTS_DEPLOY_BLOCK=123456789   # 替换为 YT-A/B/C 的实际部署区块
YTLP_DEPLOY_BLOCK=123456789        # 替换为 ytLP 的实际部署区块
LENDING_DEPLOY_BLOCK=123456789     # 替换为 Lending 的实际部署区块
```

### 第三步：启动 Scanner

#### 方法 1：使用快速启动脚本（推荐）

```bash
# Linux/Mac
./run-scanner.sh

# Windows (Git Bash)
bash run-scanner.sh
```

#### 方法 2：手动编译并运行

```bash
# 编译
go build -o bin/holder-scanner cmd/scanner/main.go

# 运行
./bin/holder-scanner
```

#### 方法 3：使用 start-holders.sh（交互式）

```bash
./start-holders.sh
# 选择: 2. Scanner only
```

### 第四步：验证数据

启动 Scanner 后，你应该看到类似的日志：

```
=== Holder Scanner Service ===
✓ Configuration loaded
✓ Database tables checked
🔗 Chain ID: 421614
📚 从数据库加载合约地址配置...
✅ [Scanner] 加载了 3 个 YT 资产
   ✓ YT-A: 0x7f9eEA491eE53045594ee4669327f0355aCd0e58
   ✓ YT-B: 0x20B94C5E5b7361552E0548161a58696aA6FeDBd4
   ✓ YT-C: 0x0EF308D70cf35460E26a3Eb42F3442Ff28cbE07C
...
📊 开始首次扫描...
1. Scanning YT Vaults...
   正在查询 YT-A (0x7f9eEA491eE53045594ee4669327f0355aCd0e58)...
   发现 X 个新地址
   余额>0: X 个持有者 ✅
```

等待首次扫描完成后，再次访问 API：

```bash
curl http://localhost:8080/api/holders/YT-A
```

应该能看到持有者数据。

## 常见问题

### Q1: Scanner 报错 "failed to query logs"
**原因**：部署区块号设置太早，或 RPC 节点限制

**解决**：
1. 检查部署区块号是否正确
2. 尝试使用更小的 `BatchSize`（在代码中默认 9999）
3. 更换 RPC 节点

### Q2: 扫描速度很慢
**原因**：区块范围太大

**解决**：
1. 确保使用准确的部署区块号（不要从太早的区块开始）
2. 检查网络连接
3. 考虑使用付费的 RPC 节点（更高的速率限制）

### Q3: 余额都是 0
**原因**：合约地址不正确，或合约不是 ERC20

**解决**：
1. 验证合约地址是否正确
2. 在区块浏览器上检查合约是否是 ERC20 代币
3. 确认合约在对应的链上（Arbitrum Sepolia）

## 配置参数说明

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `CHAIN_ID` | 链 ID（421614=Arbitrum Sepolia, 97=BSC Testnet） | 421614 |
| `YT_VAULTS_DEPLOY_BLOCK` | YT 代币合约部署区块号 | 227339300 |
| `YTLP_DEPLOY_BLOCK` | ytLP 合约部署区块号 | 227230270 |
| `LENDING_DEPLOY_BLOCK` | Lending 合约部署区块号 | 227746053 |

## 技术支持

如果遇到问题，请提供：
1. Scanner 完整日志
2. 合约地址
3. 部署区块号
4. 错误信息