news 2026/8/21 17:03:06

新手必读：GenLayer Project Boilerplate项目结构逐目录解析（contracts/tests/frontend/deploy）

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
新手必读：GenLayer Project Boilerplate项目结构逐目录解析（contracts/tests/frontend/deploy）

新手必读：GenLayer Project Boilerplate项目结构逐目录解析（contracts/tests/frontend/deploy）

【免费下载链接】genlayer-project-boilerplate项目地址: https://gitcode.com/GitHub_Trending/gen/genlayer-project-boilerplate

GenLayer Project Boilerplate 是 AI 原生区块链 GenLayer 官方提供的示例项目脚手架，内置了一个支持联网与 LLM 大模型裁决的"足球竞猜"智能合约（Football Bets），并配齐了 Python 合约、双轨测试体系、Next.js 前端与部署脚本。这篇文章将带新手逐目录拆解 GenLayer 项目结构，搞懂contracts、tests、frontend、deploy每个目录的职责，让你 30 分钟就能看懂整套 GenLayer 智能合约项目。

一、GenLayer 项目结构总览：一张图看懂全貌

GenLayer 是一个"AI 原生区块链"，它的智能合约用 Python 编写、运行在 GenVM 虚拟机中，并且能直接访问互联网、调用 LLM 来做决策。这个 Boilerplate 项目就是教你如何把这样的"智能合约 + DApp 前端 + 测试 + 部署"串成一套完整工程。

克隆仓库后，你会看到如下顶层结构：

genlayer-project-boilerplate/ ├── contracts/ # Python 智能合约源码 ├── tests/ # 测试（direct 快速模式 + integration 集成模式） ├── frontend/ # Next.js 15 前端应用 ├── deploy/ # TypeScript 部署脚本 ├── config/ # 环境配置读取 ├── support/ # CI 辅助文件 ├── gltest.config.yaml ├── pyproject.toml └── requirements.txt
目录一句话职责关键语言/框架
contracts/链上智能合约（业务核心）Python / GenLayer SDK
tests/单元测试 + 端到端测试pytest / gltest
frontend/用户交互界面Next.js 15 / TypeScript / Wagmi
deploy/合约部署脚本TypeScript / genlayer-js
config/RPC 配置读取Python / dotenv

二、contracts/ 目录：GenLayer 智能合约核心代码

contracts/目录存放的是真正跑在链上的"智能合约"，这是整个 GenLayer 项目结构中最核心的部分。包含两个文件：

  • contracts/football_bets.py：足球竞猜主合约，包含全部业务逻辑
  • contracts/PatternTest.py：合约编程模式验证文件（配合测试使用）

以足球竞猜合约为例，它展示了 GenLayer 智能合约的三大典型能力：

1️⃣ 链上存储：使用TreeMap、u256等 GenLayer 专用类型（不能用普通dict/list），例如bets: TreeMap[Address, TreeMap[str, Bet]]存储每位玩家的投注。

2️⃣ 方法装饰器：@gl.public.write标记会修改状态的方法（如create_bet、resolve_bet），@gl.public.view标记只读查询方法（如get_bets、get_points）。

3️⃣ AI 联网裁决：合约通过gl.nondet.web.render()抓取 BBC Sport 的比赛页面，再用gl.nondet.exec_prompt()让 LLM 从网页中提取比分，最后用gl.eq_principle.strict_eq()等价原则校验非确定性结果——这是 GenLayer 区别于传统区块链的最大亮点。

三、tests/ 目录：双轨测试体系是新手最佳学习材料

对于新手来说，tests/目录是理解合约行为最好的"说明书"。它分为两套互补的测试：

3.1 tests/direct/ —— 毫秒级快速测试（无需区块链环境）

tests/direct/使用 GenLayer 的 direct mode，在内存中直接运行合约，通过 mock 模拟网络请求和 LLM 调用，每个测试只需几毫秒：

  • tests/direct/test_create_bet.py：验证创建投注的确定性逻辑（无需 mock）
  • tests/direct/test_resolve_bet.py：验证结算逻辑，用direct_vm.mock_web()和direct_vm.mock_llm()模拟比赛结果
  • tests/direct/test_views.py：验证只读查询方法
  • tests/direct/test_patterns.py：验证 7 种合约编程模式
  • tests/direct/conftest.py：共享工具函数（地址格式化等）

运行方式非常简单：

pytest tests/direct/ -v

3.2 tests/integration/ —— 真实链上端到端测试

tests/integration/则要求启动 GenLayer Studio，用真实共识网络跑完整流程：

gltest tests/integration/ -v -s
  • tests/integration/test_football_bets.py：覆盖下注 → 结算 → 积分全流程
  • tests/integration/test_new_features.py：新功能验证
  • tests/integration/fixtures.py：期望状态的测试夹具
测试类型命令速度是否需要 Studio
静态检查genvm-lint check contracts/football_bets.py~250ms否
快速测试pytest tests/direct/ -v~毫秒/个否
集成测试gltest tests/integration/ -v -s~分钟/个是

新手推荐工作流：改合约 → 先 lint → 再跑 direct 测试 → 最后跑 integration 测试，前两步几秒钟就能完成反馈，非常适合学习迭代。

四、frontend/ 目录：生产级 Next.js 15 前端

frontend/是一个开箱即用的 Next.js 15 前端，技术栈为 TypeScript + TanStack Query + Radix UI + Wagmi/Viem，并且内置了 MetaMask 钱包集成。核心文件分布在几个子目录：

  • frontend/lib/contracts/FootballBets.ts：封装合约交互类，提供createBet、resolveBet、getBets、getLeaderboard等方法
  • frontend/lib/hooks/useFootballBets.ts：React Hook 层，用 TanStack Query 管理状态
  • frontend/lib/genlayer/WalletProvider.tsx：钱包连接上下文
  • frontend/lib/genlayer/client.ts+fees.ts：GenLayer 客户端与交易费估算
  • frontend/components/：UI 组件（BetsTable、CreateBetModal、Leaderboard、Navbar 等）
  • frontend/app/：Next.js 页面与全局布局

启动前端只需三步：

cd frontend npm install npm run dev

然后将部署好的合约地址填入NEXT_PUBLIC_CONTRACT_ADDRESS环境变量，访问 http://localhost:3000/ 即可在网页上完成下注、查看排行榜等操作。

五、deploy/ 目录：一键部署智能合约

deploy/deployScript.ts是官方推荐的合约部署脚本，使用genlayer-jsSDK 完成完整部署流程：读取contracts/football_bets.py源码 → 初始化共识合约 → 提交部署交易 → 轮询等待ACCEPTED/FINALIZED状态 → 打印合约地址。

实际部署时只需两条命令：

genlayer network # 选择网络（localnet / studionet） genlayer deploy # 执行 deployScript.ts

六、config/ 与根目录配置：新手易忽略的拼图

  • config/genlayer_config.py：读取.env中的RPCPROTOCOL、RPCHOST、RPCPORT配置
  • gltest.config.yaml：测试网络配置，默认连接本地http://127.0.0.1:4000/api
  • pyproject.toml：pytest 配置，定义了 integration 标记
  • requirements.txt：Python 依赖清单
  • support/ci/：CI 辅助文件（如ACTIVE_DEV_BRANCH）

七、新手 30 分钟上手路线图

如果你完全没接触过 GenLayer，建议按这个顺序探索：

  1. 先跑测试：执行pytest tests/direct/ -v，通过测试输出反推合约行为
  2. 再读合约：打开contracts/football_bets.py，对照测试里的断言逐行理解
  3. 后看前端：从frontend/lib/contracts/FootballBets.ts入手，理解前端如何调用链上方法
  4. 最后部署：配置好环境后运行genlayer deploy，拿到合约地址接入前端

总结

GenLayer Project Boilerplate 把"AI 智能合约开发"的全套最佳实践浓缩在四个目录中：contracts/写链上逻辑、tests/双轨验证、frontend/落地交互、deploy/打通上线。对新手而言，它既是学习 GenLayer 智能合约与 AI 裁决机制的最佳教材，也是一个可以直接复用的生产级脚手架。照着本文的目录地图，顺着"测试 → 合约 → 前端 → 部署"的顺序读源码，你会惊讶于 AI 原生区块链的开发竟然如此顺畅。

【免费下载链接】genlayer-project-boilerplate项目地址: https://gitcode.com/GitHub_Trending/gen/genlayer-project-boilerplate

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/8/21 16:59:46

IDM下载加速完全指南：从安装配置到高级优化的12个实用技巧

IDM下载加速完全指南：从安装配置到高级优化的12个实用技巧 【免费下载链接】IDM-Activation-Script IDM Activation & Trail Reset Script 项目地址: https://gitcode.com/gh_mirrors/id/IDM-Activation-Script 先说明本文要讲什么：这是一篇围…

作者头像 李华
网站建设 2026/8/21 16:59:14

罗技PUBG压枪宏：4步跑通 + 核心参数调优与避坑清单

罗技PUBG压枪宏：4步跑通 核心参数调优与避坑清单 【免费下载链接】logitech-pubg PUBG no recoil script for Logitech gaming mouse / 绝地求生 罗技 鼠标宏 项目地址: https://gitcode.com/gh_mirrors/lo/logitech-pubg 全自动M416弹道上跳，手…

作者头像 李华