Contract Listener Service

一个用Go语言编写的智能合约事件监听服务，提供REST API接口查询合约事件数据。

Portfolio Context

This repository is kept as a Go backend infrastructure project centered on blockchain event ingestion, persistence, and API exposure.

What it demonstrates

• Go service structuring with layered modules
• contract event listening and data ingestion
• REST API design for querying indexed event data
• Docker-friendly local deployment workflow

功能特性

• 🔗 监听以太坊智能合约事件
• 📊 存储事件数据到数据库
• 🌐 提供REST API接口查询事件
• ⚙️ 支持配置文件管理
• 📝 结构化日志记录
• 🐳 Docker容器化部署

项目结构

contract-listener/
├── cmd/                    # 应用程序入口
│   └── server/
│       └── main.go
├── internal/               # 内部包
│   ├── config/            # 配置管理
│   ├── handler/           # HTTP处理器
│   ├── listener/          # 合约监听器
│   ├── model/             # 数据模型
│   ├── repository/        # 数据访问层
│   └── service/           # 业务逻辑层
├── pkg/                   # 公共包
├── configs/               # 配置文件
├── docker/                # Docker相关文件
├── docs/                  # 文档
└── scripts/               # 脚本文件

快速开始

环境要求

• Go 1.21+
• PostgreSQL 13+
• 以太坊节点访问权限（如Infura、Alchemy等）

方式一：使用启动脚本（推荐）

# 本地运行
./scripts/start.sh start

# 使用Docker运行
./scripts/start.sh docker

# 查看帮助
./scripts/start.sh help

方式二：使用Makefile

# 设置环境
make setup

# 本地运行
make run

# Docker运行
make docker-up

# 查看所有命令
make help

方式三：手动运行

# 安装依赖
go mod tidy

# 复制配置文件
cp configs/config.example.yaml configs/config.yaml

# 构建并运行
go build -o bin/contract-listener cmd/server/main.go
./bin/contract-listener

配置说明

编辑 configs/config.yaml 文件：

1. 以太坊配置：设置RPC URL和WebSocket URL
2. 数据库配置：设置PostgreSQL连接信息
3. 合约配置：添加要监听的合约地址和ABI文件
4. 监听器配置：调整批处理大小和轮询间隔

API接口

服务启动后，API将在 http://localhost:8080 上可用。

健康检查

# 健康检查
GET /health

# 就绪检查
GET /ready

事件查询接口

# 获取事件列表
GET /api/v1/events?contract=0x...&limit=10&offset=0

# 获取特定事件详情
GET /api/v1/events/{id}

# 获取事件统计
GET /api/v1/events/stats?contract=0x...

查询参数

• contract: 合约地址
• contract_name: 合约名称
• event: 事件名称
• from_block: 起始区块号
• to_block: 结束区块号
• tx_hash: 交易哈希
• limit: 每页数量（默认50，最大1000）
• offset: 偏移量

示例请求

# 获取USDC合约的Transfer事件
curl "http://localhost:8080/api/v1/events?contract_name=USDC&event=Transfer&limit=5"

# 获取特定区块范围的事件
curl "http://localhost:8080/api/v1/events?from_block=18000000&to_block=18000100"

# 获取事件统计信息
curl "http://localhost:8080/api/v1/events/stats"

开发

运行测试

make test          # 完整测试
make test-short    # 快速测试

代码检查

make check         # 运行所有检查
make lint          # 代码检查
make fmt           # 格式化代码
make vet           # 静态分析

开发模式

# 安装air（热重载工具）
go install github.com/cosmtrek/air@latest

# 开发模式运行
make dev

部署

Docker部署

# 启动所有服务
make docker-up

# 查看服务状态
make docker-status

# 查看日志
make docker-logs

# 停止服务
make docker-down

生产环境部署

1. 配置环境变量
2. 设置数据库连接
3. 配置以太坊节点
4. 启动服务

# 构建生产版本
make build

# 安装到系统
make install

许可证

MIT License