# What Is the GenLayer Project Boilerplate? A Complete Starter Kit for AI-Native Blockchain Apps

> Explore the GenLayer Project Boilerplate, a starter kit for AI-native blockchain apps. Build intelligent contracts in Python with automated testing and a Next.js frontend.

- Repository: [GenLayer Labs/genlayer-project-boilerplate](https://github.com/genlayerlabs/genlayer-project-boilerplate)
- Tags: getting-started
- Published: 2026-08-20

---

**The GenLayer Project Boilerplate is a ready-to-run starter kit that demonstrates how to build AI-native blockchain applications using intelligent contracts written in Python, featuring automated testing pipelines, static analysis, and a production-grade Next.js frontend.**

The GenLayer Project Boilerplate serves as the canonical reference implementation for developers entering the GenLayer ecosystem. It provides a complete end-to-end stack centered on a **football-bets use case**, showing exactly how to write intelligent contracts that fetch real-time web data, invoke large language models (LLMs), and enforce deterministic results through equivalence principles. This repository eliminates setup overhead by packaging contract templates, testing utilities, deployment scripts, and a modern React frontend into a single cohesive workflow.

## Core Capabilities of the GenLayer Project Boilerplate

### Intelligent Contracts in Python

At the heart of the boilerplate lies the ability to write **intelligent contracts** using familiar Python syntax rather than traditional smart contract languages. In [`contracts/football_bets.py`](https://github.com/genlayerlabs/genlayer-project-boilerplate/blob/main/contracts/football_bets.py), the contract leverages nondeterministic operations through the `gl` module to access external resources:

- **`gl.nondet.web`** for fetching external web pages
- **`gl.nondet.exec_prompt`** for querying LLMs

These operations execute within **equivalence blocks** that ensure consensus among validators, allowing blockchain contracts to reason about real-world data. The boilerplate enforces proper usage patterns, ensuring nondeterministic calls never occur outside protected contexts.

### Fast Direct-Mode Testing

The repository includes a **direct-mode testing framework** that runs contracts in-memory with mocked dependencies. Located in `tests/direct/`, these unit tests provide rapid feedback during development without requiring a running GenLayer Studio instance.

Test files utilize `direct_vm` fixtures to inject deterministic responses for web and LLM calls:

```python
def test_resolve_bet(direct_vm, direct_deploy, direct_alice):
    contract = direct_deploy("contracts/football_bets.py")
    direct_vm.sender = direct_alice
    # Mock the BBC page content

    direct_vm.mock_web(r".*bbc.com.*", {"status": 200, "body": "Team A 1-2 Team B"})
    # Mock the LLM extraction

    direct_vm.mock_llm(r".*Extract the match result.*", {"score": "1:2", "winner": 2})
    contract.create_bet("2024-11-10", "Team A", "Team B", "2")
    contract.resolve_bet("2024-11-10_team a_team b")
    assert contract.get_player_points(direct_alice.as_hex) == 1

```

### Integration Testing Against GenLayer Studio

For consensus-level validation, the boilerplate provides **full integration tests** in `tests/integration/` that execute against a live GenLayer Studio instance. These tests verify that intelligent contracts behave correctly under actual network conditions, including proper handling of equivalence principles and validator consensus mechanisms.

### Static Analysis with GenVM Linter

The project incorporates **static contract linting** via the GenVM linter, configurable through [`gltest.config.yaml`](https://github.com/genlayerlabs/genlayer-project-boilerplate/blob/main/gltest.config.yaml). This tool catches critical violations before deployment:

- Forbidden import statements
- Nondeterministic function calls outside equivalence blocks
- Storage type mismatches and violations

Run the linter locally using:

```bash
genvm-lint check contracts/football_bets.py

```

### Continuous Integration Pipeline

The `.github/workflows/` directory contains a **CI pipeline** that automatically executes on every push. This workflow lints all contracts and runs the direct-mode test suite, ensuring code quality gates pass before integration. The pipeline validates that contracts remain compliant with GenLayer's deterministic execution requirements.

### Production-Ready Frontend Stack

The `frontend/` directory delivers a **modern React application** built with Next.js 15, TypeScript, TanStack Query, and Radix UI. This stack enables seamless interaction with deployed contracts through type-safe hooks. For example, creating a bet uses a mutation hook that interfaces with the GenLayer client:

```tsx
// frontend/lib/hooks/useFootballBets.ts
export const useCreateBet = (contractAddress: string) => {
  const client = useGenlayerClient();
  return useMutation(
    ({ gameDate, team1, team2, predictedWinner }) =>
      client.contract(contractAddress).write("create_bet", [
        gameDate,
        team1,
        team2,
        predictedWinner,
      ]),
    { onSuccess: () => client.invalidateQueries(['bets']) }
  );
};

```

## Repository Architecture and Key Files

Understanding the file structure accelerates onboarding:

- **[`contracts/football_bets.py`](https://github.com/genlayerlabs/genlayer-project-boilerplate/blob/main/contracts/football_bets.py)** – Core intelligent contract demonstrating web access, LLM integration, and state management patterns
- **`tests/direct/`** – Fast in-memory unit tests with mocked external dependencies
- **`tests/integration/`** – End-to-end tests requiring a running GenLayer Studio instance
- **`frontend/`** – Next.js 15 application with TypeScript and modern data-fetching patterns
- **[`deploy/deployScript.ts`](https://github.com/genlayerlabs/genlayer-project-boilerplate/blob/main/deploy/deployScript.ts)** – TypeScript deployment script for pushing contracts to selected networks
- **[`gltest.config.yaml`](https://github.com/genlayerlabs/genlayer-project-boilerplate/blob/main/gltest.config.yaml)** – Configuration for the GenLayer test runner and linter settings
- **[`.github/workflows/ci.yml`](https://github.com/genlayerlabs/genlayer-project-boilerplate/blob/main/.github/workflows/ci.yml)** – Automated linting and testing pipeline

## How the Football Bets Example Works

The boilerplate demonstrates practical AI-blockchain interaction through a betting application that resolves wagers based on real match outcomes.

### Creating a Bet

The `create_bet` method in [`contracts/football_bets.py`](https://github.com/genlayerlabs/genlayer-project-boilerplate/blob/main/contracts/football_bets.py) initializes a wager by storing prediction data and constructing a resolution URL for later validation:

```python

# In contracts/football_bets.py

@gl.public.write
def create_bet(self, game_date: str, team1: str, team2: str, predicted_winner: str) -> None:
    match_resolution_url = (
        "https://www.bbc.com/sport/football/scores-fixtures/" + game_date
    )
    sender_address = gl.message.sender_address
    bet_id = f"{game_date}_{team1}_{team2}".lower()
    if sender_address in self.bets and bet_id in self.bets[sender_address]:
        raise Exception("Bet already created")
    bet = Bet(
        id=bet_id,
        has_resolved=False,
        game_date=game_date,
        resolution_url=match_resolution_url,
        team1=team1,
        team2=team2,
        predicted_winner=predicted_winner,
        real_winner="",
        real_score="",
    )
    self.bets.get_or_insert_default(sender_address)[bet_id] = bet

```

### Resolving Bets with Web Data and LLMs

The `resolve_bet` method demonstrates the boilerplate's core innovation: **fetching external data and processing it through LLMs within a consensus-enforced environment**. The contract retrieves match results from the BBC Sport website, uses a language model to extract structured data from the HTML, and updates on-chain state based on the outcome:

```python
@gl.public.write
def resolve_bet(self, bet_id: str) -> None:
    bet = self.bets[gl.message.sender_address][bet_id]
    bet_status = self._check_match(bet.resolution_url, bet.team1, bet.team2)
    if int(bet_status["winner"]) < 0:
        raise Exception("Game not finished")
    bet.has_resolved = True
    bet.real_winner = str(bet_status["winner"])
    bet.real_score = bet_status["score"]
    if bet.real_winner == bet.predicted_winner:
        self.points[gl.message.sender_address] = self.points.get(
            gl.message.sender_address, 0
        ) + 1

```

The `_check_match` internal method utilizes `gl.nondet.web` to fetch the page content and `gl.nondet.exec_prompt` to parse the unstructured HTML into deterministic JSON, demonstrating how the GenLayer Project Boilerplate bridges traditional web data with blockchain state.

## Testing and Deployment Workflow

### Unit Testing Strategy

Developers should leverage the **direct-mode test suite** for rapid iteration. The `direct_vm` fixture provides methods like `mock_web()` and `mock_llm()` to simulate external dependencies, allowing 100% test coverage of contract logic without network latency or API rate limits.

### Deployment Process

The [`deploy/deployScript.ts`](https://github.com/genlayerlabs/genlayer-project-boilerplate/blob/main/deploy/deployScript.ts) file contains the deployment logic for migrating contracts to GenLayer networks. This TypeScript script handles contract compilation, bytecode generation, and network registration, providing a seamless path from local development to live deployment.

## Summary

- The **GenLayer Project Boilerplate** provides a complete development environment for AI-native blockchain applications using Python-based intelligent contracts.
- **Key files** include [`contracts/football_bets.py`](https://github.com/genlayerlabs/genlayer-project-boilerplate/blob/main/contracts/football_bets.py) for contract logic, `tests/direct/` for fast unit testing, and `frontend/` for the Next.js 15 user interface.
- **Direct-mode testing** enables rapid iteration through in-memory mocks of web and LLM calls, while **integration tests** validate consensus behavior against live Studio instances.
- The repository includes **static linting** via GenVM, **CI automation** through GitHub Actions, and **deployment scripts** for network migration.
- The football-bets example demonstrates real-world usage patterns including web scraping, natural language processing, and on-chain state management within equivalence blocks.

## Frequently Asked Questions

### What programming language are GenLayer contracts written in?

GenLayer contracts are written in **Python**, allowing developers to use standard libraries and data structures while accessing blockchain-specific functionality through the `gl` module. The GenLayer Project Boilerplate demonstrates idiomatic Python patterns for smart contract development, including type hints and class-based state management.

### How does direct-mode testing differ from integration testing?

**Direct-mode testing** runs contracts locally with mocked external services (web pages and LLM responses), providing sub-second feedback during development. **Integration testing** requires a running GenLayer Studio instance and validates actual consensus behavior across multiple validators. The boilerplate includes both approaches in `tests/direct/` and `tests/integration/` respectively.

### Can I deploy the boilerplate contracts to a live network?

Yes. The [`deploy/deployScript.ts`](https://github.com/genlayerlabs/genlayer-project-boilerplate/blob/main/deploy/deployScript.ts) file provides a TypeScript-based deployment mechanism for pushing contracts to any GenLayer network. The script handles contract compilation and network registration, though you must configure appropriate RPC endpoints and credentials for your target environment.

### What frontend technologies does the boilerplate use?

The frontend employs **Next.js 15** with the App Router, **TypeScript** for type safety, **TanStack Query** for server-state management, and **Radix UI** for accessible component primitives. This stack ensures type-safe interaction with GenLayer contracts while providing a modern user experience for creating and resolving bets.