genlayerlabs/genlayer-project-boilerplate

来源：https://github.com/genlayerlabs/genlayer-project-boilerplate

GenLayer 项目示例

许可证：MIT (https://opensource.org/license/mit/) Discord (https://discord.gg/8Jm4v89VAu) Telegram (https://t.me/genlayer) Twitter (https://x.com/GenLayer) GitHub 星标历史 (https://star-history.com/#yeagerai/genlayer-js)

关于

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

包含内容

• 一个集成了网络访问和LLM功能的智能合约示例（足球博彩）
• 直接模式测试 —— 快速的、内存中的单元测试，通过模拟Web/LLM交互（每个测试约需毫秒级时间）
• 集成测试 —— 针对 GenLayer Studio 的完整端到端测试
• 合约代码检查 —— 在部署前进行静态分析，以捕获常见的合约问题
• CI 流水线 —— 用于代码检查和直接测试的 GitHub Actions 工作流
• 一个生产就绪的 Next.js 15 前端，使用 TypeScript、TanStack Query 和 Radix UI 构建
• 配置文件模板和部署脚本

要求

• Python >= 3.12
• 全局安装的 GenLayer CLI (https://github.com/genlayerlabs/genlayer-cli)：npm install -g genlayer
• GenLayer Studio（用于集成测试和部署）：从文档安装 (https://docs.genlayer.com/developers/intelligent-contracts/tooling-setup#using-the-genlayer-studio) 或使用托管的 GenLayer Studio (https://studio.genlayer.com/)

项目结构

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          # 预期状态的测试夹具
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. 检查你的合约

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

genvm-lint check contracts/football_bets.py

代码检查器可捕获：

• 禁止的导入和非确定性调用
• 无效的存储类型（必须使用 TreeMap, DynArray, u256 等）
• 缺少的装饰器和返回类型注解
• 在等效原则块之外的非确定性操作
• 以及超过 20 条其他规则 (https://github.com/genlayerlabs/genvm-linter)

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/渲染调用
• 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. 积分：预测正确可获得积分。用户可以查询自己的积分或排行榜。

测试策略

推荐工作流：

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

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

社区

• Discord (https://discord.gg/8Jm4v89VAu)：讨论、支持与公告
• Telegram (https://t.me/genlayer)：非正式聊天与快速更新

文档

详细信息，请参阅我们的文档 (https://docs.genlayer.com/)。

许可证

本项目根据 MIT 许可证授权 - 详情请参阅 LICENSE 文件。