genlayer-project-boilerplate README

The project's README from github.com/genlayerlabs/genlayer-project-boilerplate. As one markdown file: README.md.

Sample GenLayer project

License: MIT Discord Telegram Twitter GitHub star chart

About

This project includes the boilerplate code for a GenLayer use case implementation, specifically a football bets game.

What's included

Requirements

Project Structure

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

Quick Start

1. Set up Python environment

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

2. Lint your contracts

Run the GenVM linter to catch issues before deployment:

genvm-lint check contracts/football_bets.py

The linter catches:

3. Run direct mode tests

Direct mode tests run contracts in-memory without needing GenLayer Studio. They use mocks for web requests and LLM calls, giving you fast feedback (~milliseconds per test):

pytest tests/direct/ -v

Direct mode features used in these tests:

4. Deploy the contract

  1. Choose your network: genlayer network
  2. Deploy: genlayer deploy (runs the script in /deploy/deployScript.ts)

5. Run integration tests

Integration tests deploy the contract to GenLayer Studio and test with real consensus:

gltest tests/integration/ -v -s

These require GenLayer Studio running (local or hosted).

6. Set up the frontend

  1. Copy frontend/.env.example to frontend/.env
  2. Add your deployed contract address as NEXT_PUBLIC_CONTRACT_ADDRESS
  3. Run:
cd frontend
npm install
npm run dev

The app will be available at http://localhost:3000/.

How the Football Bets Contract Works

  1. Creating Bets: Users bet on a football match by providing the game date, teams, and predicted winner.
  2. Resolving Bets: After the match, the contract fetches results from BBC Sport, uses an LLM to extract the score, and validates via the equivalence principle.
  3. Points: Correct predictions earn points. Users can query their points or the leaderboard.

Testing Strategy

Test Type Command Speed Requires Studio
Lint genvm-lint check contracts/*.py ~250ms No
Direct pytest tests/direct/ -v ~ms/test No
Integration gltest tests/integration/ -v -s ~min/test Yes

Recommended workflow:

  1. Lint after every contract change
  2. Run direct tests frequently during development
  3. Run integration tests before deployment to verify consensus behavior

For AI coding agents (Claude Code, Cursor, etc.), the linter and direct tests provide the fast feedback loop needed for iterative development without requiring a running Studio instance.

Community

Documentation

For detailed information, see our documentation.

License

This project is licensed under the MIT License - see the LICENSE file for details.

genlayer-project-boilerplate (genlayerlabs/genlayer-project-boilerplate)

Searching Database…

18.8K ·GitHub
Genlayer-project-boilerplate
Что это такое?Это шаблон проекта для создания приложения на основе интеллектуального контракта GenLayer. В качестве примера показана простая игра в ставки на футбол: контракт получает реальные результаты матчей и с помощью LLM определяет исход ставок.
Это фреймворк для контрактов или готовое приложение?Это полноценный стартовый шаблон: интеллектуальные контракты GenLayer на Python вместе с фронтендом на Next.js 15 и TypeScript, а также инструменты для тестирования и развёртывания.
Как мне всё запустить?Настройте окружение Python, проверьте контракты линтером GenVM, запустите тесты в прямом режиме, разверните контракт командой 'genlayer deploy', затем запустите интеграционные тесты и настройте фронтенд: скопируйте frontend/.env.example и выполните команды npm.
Что нужно установить перед началом?Нужны Python 3.12+, GenLayer CLI, установленный глобально через npm, и GenLayer Studio (локальная или облачная версия) для интеграционных тестов и развёртывания.
Работают ли интеграционные тесты без GenLayer Studio?Нет, для интеграционных тестов нужно, чтобы GenLayer Studio была запущена, локально или в облачной версии. Без неё работают только тесты в прямом режиме и линтинг.
Для кого предназначен этот шаблон?Для разработчиков интеллектуальных контрактов GenLayer, особенно для тех, кто использует ИИ-агентов для написания кода, например Claude Code или Cursor, и нуждается в быстрой обратной связи от линтера и тестов в прямом режиме.
Как на самом деле работает пример контракта Football Bets?Пользователи делают ставки на победителя матча. После игры контракт получает результаты с BBC Sport, с помощью LLM извлекает счёт, проверяет его по принципу эквивалентности GenLayer и начисляет очки за правильные прогнозы.
Что проверяет линтер контрактов?Он находит запрещённые импорты, недетерминированные вызовы вне блоков принципа эквивалентности, некорректные типы хранилища (нужно использовать TreeMap, DynArray, u256 и т. д.), отсутствующие декораторы и аннотации типов возвращаемых значений, а также более 20 других правил.
В чём разница между режимом прямых тестов и интеграционными тестами?Тесты в прямом режиме запускают контракты в памяти, с заглушками вместо реальных запросов в интернет и к LLM. Они дают обратную связь за миллисекунды и не требуют Studio. Интеграционные тесты развёртываются в GenLayer Studio и проверяют реальное поведение консенсуса, и каждый из них занимает несколько минут.
Есть ли в комплекте CI-пайплайн?Да, рабочий процесс GitHub Actions автоматически запускает линтинг и тесты в прямом режиме как часть CI-пайплайна.
What are similar projects?agentic-playwright, kolo-frontend, SolidityCoreLegend, SolcQueue, truffle, ai-website-cloner-template, clearledger, robinhood-meme-token-stock-launchpad
Which topics is it in?testing-tools, smart-contracts, boilerplate, web3, blockchain, github-actions, ci, nextjs, cursor, testing, agents, ai-agent
Creator
genlayerlabs
Size
1.1 MB
Stars
18.8K
Updated
CommitJun 10Releasev0.2.0Dec 09
Age
2y
Commits · 90 Days