genlayer-project-boilerplate

GenLayer 示例项目

关于

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

包含内容

• 一个示例智能合约（Football Bets），支持 Web 访问和 LLM（大语言模型）集成
• 直接模式测试 — 快速的进程内单元测试，带有 Web/LLM 模拟（每个测试约毫秒级）
• 集成测试 — 针对 GenLayer Studio 的完整端到端测试
• 合约 Lint — 在部署前通过静态分析捕获常见合约问题
• CI 流水线 — 用于 Lint 和直接测试的 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. Lint 你的合约

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

genvm-lint check contracts/football_bets.py

linter 可以捕获：

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

3. 运行直接模式测试

直接模式测试在内存中运行合约，无需 GenLayer Studio。它们使用 mock 模拟 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() — 在调用之间重置 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/ 可用。

Football Bets 合约如何工作

1. 创建投注：用户通过提供比赛日期、球队和预测胜者来对足球比赛进行投注。
2. 结算投注：比赛结束后，合约从 BBC Sport 获取结果，使用 LLM 提取比分，并通过等价原则（equivalence principle）进行验证。
3. 积分：预测正确可获得积分。用户可以查询自己的积分或排行榜。

测试策略

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

推荐工作流程：

1. 每次修改合约后运行 Lint
2. 开发期间频繁运行直接模式测试
3. 部署前运行集成测试，以验证共识行为

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

社区

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

文档

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

许可证

本项目采用 MIT 许可证授权 — 有关详细信息，请参阅 LICENSE 文件。