assetx/webapp-back/holders/README-CN.md

Holder Scanner 使用说明

问题诊断

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

当前状态：

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

解决步骤

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

你数据库中的合约地址是：

• YT-A: 0x7f9eEA491eE53045594ee4669327f0355aCd0e58
• YT-B: 0x20B94C5E5b7361552E0548161a58696aA6FeDBd4
• YT-C: 0x0EF308D70cf35460E26a3Eb42F3442Ff28cbE07C

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

方法 1：通过 Arbiscan 查询

1. 访问 Arbiscan Sepolia
2. 搜索合约地址（例如：0x7f9eEA491eE53045594ee4669327f0355aCd0e58）
3. 查看 "Contract Creation" 或 "Contract Creator" 信息
4. 找到 "Block" 号码

方法 2：使用 Web3 工具查询

# 使用 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 文件，更新部署区块号：

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

第三步：启动 Scanner

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

# Linux/Mac
./run-scanner.sh

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

方法 2：手动编译并运行

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

# 运行
./bin/holder-scanner

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

./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：

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. 错误信息