Guide · Open source

How to use genlayer-project-boilerplate: setup, tests and frontend

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

genlayer-project-boilerplate is a sample project for GenLayer, a platform for smart contracts written in Python that can fetch web data and call an LLM. It includes an example Football Bets contract, tests, a contract linter and a Next.js frontend. This guide shows you how to set it up, lint and test the contract, deploy it and run the frontend, so you can copy the structure and adapt it.

GenLayergenlayerlabs/genlayer-project-boilerplate · ★ 19.3k · MIT Install options & downloads

Quick start

1Create a Python environment. Run python3 -m venv .venv, activate it, and install requirements.txt with pip.
2Install the GenLayer CLI. Install it globally with npm install -g genlayer.
3Lint the contract. Run genvm-lint check contracts/football_bets.py to catch issues before deployment.
4Run direct tests. Run pytest tests/direct/ -v for fast in-memory tests that need no Studio.
5Deploy. Choose a network with genlayer network, then run genlayer deploy.
6Run integration tests. With GenLayer Studio running, run gltest tests/integration/ -v -s.
7Start the frontend. Copy frontend/.env.example to frontend/.env, set the contract address, then run npm install and npm run dev in frontend.

What you need before you start

The project needs Python 3.12 or newer and the GenLayer CLI, which you install globally with npm. Node.js is required for the frontend and the CLI.

You also need GenLayer Studio for integration tests and deployment. You can install it locally following the GenLayer docs, or use the hosted GenLayer Studio.

Python >= 3.12
GenLayer CLI installed globally
Node.js for the frontend and the CLI
GenLayer Studio (local or hosted) for integration tests and deployment

npm install -g genlayer

Set up the Python environment

Clone the repository, then create and activate a virtual environment and install the Python dependencies from requirements.txt.

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

Lint the contracts

Run the GenVM linter on the example contract before deploying. It checks for forbidden imports, non-deterministic calls, invalid storage types, missing decorators and return type annotations, and non-deterministic operations outside equivalence principle blocks. The README says there are 20+ rules in total.

Use TreeMap, DynArray, u256 and similar types for storage, as the linter expects.
Lint after every contract change.

genvm-lint check contracts/football_bets.py

Run the direct mode tests

Direct mode tests run contracts in memory without GenLayer Studio. They use mocks for web requests and LLM calls, so each test takes about a millisecond. The test files cover bet creation, bet resolution with web and LLM mocks, and read-only views.

The README lists these helpers used in direct tests: direct_deploy, direct_vm.sender, direct_vm.mock_web, direct_vm.mock_llm, direct_vm.expect_revert and direct_vm.clear_mocks.

tests/direct/test_create_bet.py: bet creation logic
tests/direct/test_resolve_bet.py: bet resolution with web/LLM mocks
tests/direct/test_views.py: read-only view methods

pytest tests/direct/ -v

Deploy the contract

Choose your network, then deploy. According to the README, the deploy command runs the script in /deploy/deployScript.ts.

Select the network with genlayer network.
Deploy with genlayer deploy.
Save the deployed contract address for the frontend.

genlayer network
genlayer deploy

Run the integration tests

Integration tests deploy the contract to GenLayer Studio and test it with real consensus. They are the slowest tier, and they need Studio running, either local or hosted. Run them before deployment to verify consensus behavior.

gltest tests/integration/ -v -s

Start the frontend

Copy the example environment file, add your deployed contract address as NEXT_PUBLIC_CONTRACT_ADDRESS, then install dependencies and start the Next.js dev server. The app is served at http://localhost:3000/.

Copy frontend/.env.example to frontend/.env.
Set NEXT_PUBLIC_CONTRACT_ADDRESS to your deployed contract address.

cd frontend
npm install
npm run dev

What people use it for

Learning how a GenLayer intelligent contract is structured, using the Football Bets example.
Starting a GenLayer app with a working test setup and a Next.js frontend.
Getting fast local feedback on contract logic with direct mode tests and mocks.
Setting up a CI pipeline that runs contract linting and direct tests, as the included GitHub Actions workflow does.

Frequently asked questions

Is genlayer-project-boilerplate free to use?

The project is released under the MIT License, as stated in the README. The license file in the repository has the full terms.

What do I need to install to use it?

You need Python 3.12 or newer, the GenLayer CLI installed with npm install -g genlayer, and Node.js for the frontend and CLI. Integration tests and deployment also need GenLayer Studio, local or hosted.

Do I need GenLayer Studio to run the tests?

No, the direct mode tests in tests/direct/ run in memory without Studio. Integration tests in tests/integration/ do need a running GenLayer Studio.

What is the difference between direct and integration tests?

Direct tests are fast in-memory unit tests with web and LLM mocks, taking about a millisecond each. Integration tests deploy to GenLayer Studio and check real consensus, taking minutes per test according to the README.

Is this boilerplate ready for a production football betting app?

No. The README describes it as boilerplate for a football bets use case, meant as a starting point to copy and adapt. Plan your own production hardening.

What language do I need to know?

You need Python for the intelligent contracts and tests, and TypeScript for the deployment scripts and the Next.js frontend.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This boilerplate suits developers who want to learn how GenLayer intelligent contracts are structured, or who want a working test, lint and frontend setup to copy into their own app. Skip it if you do not want to write Python and TypeScript, or if you need a production football betting product. Without GenLayer Studio you can only run the lint and direct tests, not the full consensus tests.

Install options & downloads