genlayer-project-boilerplate Documentation

Technical Documentation: genlayerlabs/genlayer-project-boilerplate

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Sample GenLayer project

About Copy Chapter

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

What's included Copy Chapter

• An example intelligent contract (Football Bets) with web access and LLM integration
• Direct mode tests — fast, in-memory unit tests with web/LLM mocking (~ms per test)
• Integration tests — full end-to-end tests against GenLayer Studio
• Contract linting — static analysis to catch common contract issues before deployment
• CI pipeline — GitHub Actions workflow for linting and direct tests
• A production-ready Next.js 15 frontend with TypeScript, TanStack Query, and Radix UI
• Configuration file template and deployment scripts

Requirements Copy Chapter

• Python >= 3.12
• GenLayer CLI globally installed: npm install genlayer
• GenLayer Studio (for integration tests and deployment): Install from Docs or use the hosted GenLayer Studio

Project Structure Copy Chapter

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 Copy Chapter

1. Set up Python environment Copy Section

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

2. Lint your contracts Copy Section

Run the GenVM linter to catch issues before deployment:

genvm-lint check contracts/football_bets.py

The linter catches:

• Forbidden imports and non-deterministic calls
• Invalid storage types (must use TreeMap, DynArray, u256, etc.)
• Missing decorators and return type annotations
• Non-deterministic operations outside equivalence principle blocks
• And 20+ other rules

3. Run direct mode tests Copy Section

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:

• direct_deploy("contracts/file.py") — deploy contract in memory
• direct_vm.sender = address — set transaction sender
• direct_vm.mock_web(pattern, response) — mock HTTP/render calls
• direct_vm.mock_llm(pattern, response) — mock LLM responses
• direct_vm.expect_revert("message") — assert expected failures
• direct_vm.clear_mocks() — reset mocks between calls

4. Deploy the contract Copy Section

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

5. Run integration tests Copy Section

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 Copy Section

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

• Discord: Discussions, support, and announcements
• Telegram: Informal chats and quick updates

Documentation Copy Chapter

For detailed information, see our documentation.

License Copy Chapter

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

Overview (`frontend/README.md`) Copy Section

GenLayer Football Market

Next.js frontend for GenLayer Football Market - AI-powered football match predictions on GenLayer blockchain.

Setup Copy Chapter

1. Install dependencies:

Using bun:

bun install

Using npm:

npm install

2. Create .env file:

cp .env.example .env

3. Configure environment variables:
   • NEXT_PUBLIC_CONTRACT_ADDRESS - GenLayer Football Betting contract address
   • NEXT_PUBLIC_STUDIO_URL - GenLayer Studio URL (default: https://studio.genlayer.com/api)

Development Copy Chapter

Using bun:

bun dev

Using npm:

npm run dev

Open http://localhost:3000 in your browser.

Build Copy Chapter

Using bun:

bun run build
bun start

Using npm:

npm run build
npm start

Tech Stack Copy Chapter

• Next.js 15 - React framework with App Router
• TypeScript - Type safety
• Tailwind CSS v4 - Styling with custom glass-morphism theme
• genlayer-js - GenLayer blockchain SDK
• TanStack Query (React Query) - Data fetching and caching
• Radix UI - Accessible component primitives
• shadcn/ui - Pre-built UI components

Wallet Management Copy Chapter

The app uses GenLayer's account system:

• Create Account: Generate a new private key
• Import Account: Import existing private key
• Export Account: Export your private key (secured)
• Disconnect: Clear stored account data

Accounts are stored in browser's localStorage for development convenience.

Features Copy Chapter

• Create Bets: Create football match predictions with team names, game date, and predicted winner (Team 1, Team 2, or Draw)
• View Bets: Real-time bet table with match details, predictions, status, and owners
• Resolve Bets: Bet owners can resolve matches using GenLayer's AI to verify actual results
• Leaderboard: Track top players by points earned from correct predictions
• Player Stats: View your points and ranking in the community
• Glass-morphism UI: Premium dark theme with OKLCH colors, backdrop blur effects, and smooth animations
• Real-time Updates: Automatic data fetching with 3-second polling intervals via TanStack Query

--- METRICS ---

• Files Extracted: 2
• Estimated Token Budget: ~1919 tokens
• Canonical Reference: https://codewiki.google/github.com/genlayerlabs/genlayer-project-boilerplate