GenLayer样板项目：LLM集成智能合约开发脚手架

本项目包含 GenLayer 用例实现的开箱即用代码模板，具体实现了一个足球投注游戏。

一个集成了 Web 访问和 LLM 的示例智能合约（Football Bets）

直接模式测试 — 快速的内存单元测试，使用 Web/LLM 模拟（每个测试约毫秒级）

集成测试 — 针对 GenLayer Studio 的完整端到端测试

合约 linting — 部署前的静态分析，捕获常见合约问题

CI 流水线 — 用于 linting 和直接测试的 GitHub Actions 工作流

生产就绪的 Next.js 15 前端，使用 TypeScript、TanStack Query 和 Radix UI

配置文件模板和部署脚本

前置依赖

全局安装 GenLayer CLI：npm install -g genlayer

GenLayer Studio（用于集成测试和部署）：从文档安装或使用托管版 GenLayer Studio

项目结构

contracts/              # Python 智能合约
tests/
  direct/               # 快速内存测试（无需 Studio）
    test_create_bet.py   # 投注创建逻辑
    test_resolve_bet.py  # 使用 Web/LLM 模拟的投注结算
    test_views.py        # 只读视图方法
  integration/           # 针对 GenLayer Studio 的完整测试
    test_football_bets.py
    fixtures.py          # 预期状态 fixture
frontend/               # Next.js 15 应用（TypeScript, TanStack Query, Radix UI）
deploy/                 # TypeScript 部署脚本
gltest.config.yaml      # 测试运行器网络配置
pyproject.toml          # Python/pytest 配置
.github/workflows/      # CI 流水线

1. 设置 Python 环境

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

2. Lint 合约

运行 GenVM linter，在部署前捕获问题：

genvm-lint check contracts/football_bets.py

检查项包括：

禁止的导入和非确定性调用

无效的存储类型（必须使用 TreeMap、DynArray、u256 等）

缺失的装饰器和返回类型注解

等价原则块外的非确定性操作

3. 运行直接模式测试

直接模式测试无需 GenLayer Studio 即可在内存中运行合约。它使用 Web 请求和 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. 部署合约

选择网络：genlayer network

部署：genlayer deploy（运行 /deploy/deployScript.ts 中的脚本）

5. 运行集成测试

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

gltest tests/integration/ -v -s

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

6. 设置前端

将 frontend/.env.example 复制到 frontend/.env

将已部署的合约地址添加为 NEXT_PUBLIC_CONTRACT_ADDRESS

cd frontend
npm install
npm run dev

应用将在 http://localhost:3000/ 可用。

足球投注合约的工作原理

创建投注：用户通过提供比赛日期、参赛队伍和预测赢家来对足球比赛进行投注。

结算投注：比赛结束后，合约从 BBC Sport 获取结果，使用 LLM 提取比分，并通过等价原则进行验证。

积分：正确的预测获得积分。用户可以查询自己的积分或排行榜。

推荐工作流：

每次合约更改后执行 lint

开发过程中频繁运行直接测试

部署前运行集成测试以验证共识行为

对于 AI 编程助手（Claude Code、Cursor 等），linter 和直接测试提供了快速反馈循环，使迭代开发无需运行中的 Studio 实例即可进行。

Discord：讨论、支持和服务公告

Telegram：非正式聊天和快速更新

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

本项目采用 MIT 许可证授权 — 详见 LICENSE 文件。