示例 GenLayer 项目

关于

本项目包含 GenLayer 用例实现的样板代码，具体为一个足球投注游戏。

包含内容

• 一个智能合约示例（Football Bets），具备网络访问和 LLM 集成功能
• 直接模式测试——快速、内存中的单元测试，包含网络/LLM 模拟（每个测试约毫秒级）
• 集成测试——针对 GenLayer Studio 的完整端到端测试
• 合约 linting——静态分析，可在部署前发现常见的合约问题
• CI 流水线——用于 linting 和直接测试的 GitHub Actions 工作流
• 生产就绪的 Next.js 15 前端，包含 TypeScript、TanStack Query 和 Radix UI
• 配置文件模板和部署脚本

环境要求

• Python >= 3.12
• 全局安装 GenLayer CLI：npm install -g genlayer
• GenLayer Studio（用于集成测试和部署）：从 文档 安装，或使用托管版 GenLayer Studio

项目结构

contracts/              # Python intelligent contracts
tests/
  direct/               # Fast in-memory tests (no Studio required)
    test_create_bet.py   # Bet creation logic
    test_resolve_bet.py  # Bet resolution with web/LLM mocks
    test_views.py        # Read-only view methods
  integration/           # Full tests against GenLayer Studio
    test_football_bets.py
    fixtures.py          # Expected state fixtures
frontend/               # Next.js 15 app (TypeScript, TanStack Query, Radix UI)
deploy/                 # TypeScript deployment scripts
gltest.config.yaml      # Test runner network configuration
pyproject.toml          # Python/pytest configuration
.github/workflows/      # CI pipeline

快速开始

1. 设置 Python 环境

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

2. 对合约进行代码检查

运行 GenVM 代码检查工具，在部署前发现问题：

genvm-lint check contracts/football_bets.py

代码检查器能够捕获以下问题：

• 禁止的导入和非确定性调用
• 无效的存储类型（必须使用 TreeMap、DynArray、u256 等）
• 缺失的装饰器和返回类型注解
• 等价原理块之外的非确定性操作
• 以及20 多种其他规则

3. 运行直接模式测试

直接模式测试无需 GenLayer Studio，可在内存中运行合约。它们使用模拟进行网络请求和 LLM 调用，为你提供快速反馈（每个测试约几毫秒）：

pytest tests/direct/ -v

这些测试中使用的直接模式功能：

• direct_deploy("contracts/file.py") — 在内存中部署合约
• direct_vm.sender = address — 设置交易发送者
• direct_vm.mock_web(pattern, response) — 模拟 HTTP/render 调用
• direct_vm.mock_llm(pattern, response) — 模拟 LLM 响应
• direct_vm.expect_revert("message") — 断言预期的失败
• direct_vm.clear_mocks() — 在调用之间重置模拟

4. 部署合约

1. 选择网络：genlayer network
2. 部署：genlayer deploy（运行 /deploy/deployScript.ts 中的脚本）

5. 运行集成测试

集成测试将合约部署到 GenLayer Studio，并使用真实共识进行测试：

gltest tests/integration/ -v -s

这些需要 GenLayer Studio 运行（本地或托管）。

6. 设置前端

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 提取比分，并通过等效性原则进行验证。
3. 积分：正确的预测会获得积分。用户可以查询自己的积分或排行榜。

测试策略

测试类型	命令	速度	是否需要 Studio
代码检查	genvm-lint check contracts/*.py	~250ms	否
直接测试	pytest tests/direct/ -v	~毫秒/测试	否
集成测试	gltest tests/integration/ -v -s	~分钟/测试	是

推荐工作流程：

1. 每次合约变更后进行代码检查
2. 开发过程中频繁运行直接测试
3. 部署前运行集成测试以验证共识行为

对于 AI 编码代理（Claude Code、Cursor 等），代码检查器和直接测试提供了迭代开发所需的快速反馈循环，无需运行 Studio 实例。

社区

• Discord：讨论、支持和公告
• Telegram：非正式聊天和快速更新

文档

有关详细信息，请参阅我们的 文档。

许可证

本项目采用 MIT 许可证 - 详情请参见 LICENSE 文件。