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
What is this?This is a boilerplate project for building a GenLayer intelligent contract application, demonstrated through a sample football betting game where the contract fetches real match results and uses an LLM to resolve bets.
Is this a smart contract framework, or a ready-made app?It is a full-stack starter template: Python-based GenLayer intelligent contracts paired with a Next.js 15 TypeScript frontend, plus testing and deployment tooling.
How do I get it running?Set up a Python environment, lint the contracts with the GenVM linter, run direct mode tests, deploy the contract with 'genlayer deploy', then run integration tests and set up the frontend by copying frontend/.env.example and running npm commands.
What do I need installed before starting?You need Python 3.12+, the GenLayer CLI installed globally via npm, and GenLayer Studio (local or hosted) for integration tests and deployment.
Do integration tests work without GenLayer Studio?No, integration tests require GenLayer Studio to be running, either locally or the hosted version; only direct mode tests and linting work without it.
Who is this template meant for?Developers building GenLayer intelligent contracts, especially those using AI coding agents like Claude Code or Cursor who need fast feedback loops from linting and direct tests.
How does the sample Football Bets contract actually work?Users place bets predicting a match winner, then after the game the contract fetches results from BBC Sport, uses an LLM to extract the score, validates it via GenLayer's equivalence principle, and awards points for correct predictions.
What does the contract linter check for?It catches forbidden imports, non-deterministic calls outside equivalence principle blocks, invalid storage types (must use TreeMap, DynArray, u256, etc.), missing decorators and return type annotations, plus over 20 other rules.
What's the difference between direct mode and integration tests?Direct mode tests run contracts in-memory with mocked web/LLM calls for millisecond-fast feedback with no Studio needed, while integration tests deploy to GenLayer Studio and verify real consensus behavior, taking minutes per test.
Is there a CI pipeline included?Yes, a GitHub Actions workflow runs linting and direct tests automatically as part of the CI pipeline.
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