GenLayer 项目模板

项目概述

本项目是 GenLayer 智能合约（Intelligent Contract）的样板代码，以"足球竞猜"游戏为示例，演示如何构建一个具备 Web 访问与 LLM 集成能力的链上应用，并配套前端、测试与部署工具。

核心特性

• 足球竞猜合约示例：包含创建竞猜、结算竞猜、排行榜查询等完整业务逻辑。
• 直接模式测试（Direct Mode）：在内存中运行合约，通过 mock 模拟 HTTP/Render 与 LLM 调用，单测耗时毫秒级。
• 集成测试（Integration Tests）：在 GenLayer Studio 中端到端运行，覆盖真实共识流程。
• 合约静态检查：基于 genvm-lint，可捕获非确定性调用、非法存储类型（如应使用 TreeMap、DynArray、u256）、缺失装饰器与返回类型注解等 20+ 类问题。
• CI 流水线：GitHub Actions 自动执行 lint 与直接模式测试。
• 前端：基于 Next.js 15 + TypeScript + TanStack Query + Radix UI。
• 部署脚本与配置模板，便于切换网络并完成发布。

环境要求

• Python ≥ 3.12
• 全局安装 GenLayer CLI：npm install -g genlayer
• 运行集成测试或部署时，需要本地或托管版 GenLayer Studio

项目结构

contracts/              # Python 智能合约源码
tests/
  direct/               # 直接模式测试（无需 Studio）
    test_create_bet.py   # 创建竞猜逻辑
    test_resolve_bet.py  # 结算竞猜，含 Web/LLM mock
    test_views.py        # 只读视图方法
  integration/           # 集成测试（依赖 Studio）
    test_football_bets.py
    fixtures.py          # 期望状态快照
frontend/               # Next.js 15 前端应用
deploy/                 # TypeScript 部署脚本
gltest.config.yaml      # 测试运行器网络配置
pyproject.toml          # Python/pytest 配置
.github/workflows/      # CI 配置

快速上手

创建虚拟环境

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

合约静态检查

genvm-lint check contracts/football_bets.py

运行直接模式测试

pytest tests/direct/ -v

常用直接模式 API：

• direct_deploy("contracts/file.py")：在内存中部署合约
• direct_vm.sender = address：设置交易发送者
• direct_vm.mock_web(pattern, response)：mock HTTP/Render 调用
• direct_vm.mock_llm(pattern, response)：mock LLM 响应
• direct_vm.expect_revert("message")：断言预期回退
• direct_vm.clear_mocks()：用例间重置 mock

部署合约

genlayer network        # 选择目标网络
genlayer deploy         # 执行 deploy/deployScript.ts

运行集成测试

gltest tests/integration/ -v -s

需先启动 GenLayer Studio。

启动前端

1. 复制 frontend/.env.example 为 frontend/.env
2. 将已部署合约地址写入 NEXT_PUBLIC_CONTRACT_ADDRESS
3. 执行：

cd frontend
npm install
npm run dev

应用默认监听 http://localhost:3000/ 。

合约业务逻辑

1. 创建竞猜：用户提交比赛日期、参赛队伍与预测胜方。
2. 结算竞猜：赛后从 BBC Sport 抓取比赛结果，借助 LLM 抽取比分，再通过等价原则（Equivalence Principle）进行链上验证。
3. 积分：预测正确的用户获得积分，支持查询个人积分与全局排行榜。

测试策略

类型	命令	速度	是否需要 Studio
Lint	genvm-lint check contracts/*.py	~250ms	否
Direct	pytest tests/direct/ -v	毫秒/测试	否
Integration	gltest tests/integration/ -v -s	分钟/测试	是

推荐流程：每次合约修改后先 lint；开发阶段高频运行直接模式测试；发布前再跑集成测试验证共识行为。对于 AI 编码助手而言，lint 与直接模式测试可在不启动 Studio 的前提下提供快速反馈，适合迭代开发。

许可证

本项目基于 MIT 协议开源。