GenLayer Project Boilerplate

This is a starter project for building on GenLayer, a platform for writing intelligent contracts that can access the web and call LLMs. It ships a complete example (a football bets game) that shows how to structure contracts, test them, and connect a frontend. It's aimed at developers new to GenLayer who want a working reference instead of starting from an empty repo.

The example contract lets users bet on football match outcomes, fetches results from BBC Sport after the match, and uses an LLM to extract the score, validating the result through GenLayer's equivalence principle. Points accumulate per correct prediction and a leaderboard can be queried.

Key features

• Example intelligent contract: a football bets contract demonstrating web access and LLM integration inside a GenLayer contract.
• Direct mode tests: fast, in-memory unit tests with mocked web and LLM calls, running in milliseconds without needing GenLayer Studio.
• Integration tests: end-to-end tests that deploy to GenLayer Studio and check real consensus behavior.
• Contract linting: static analysis (genvm-lint) that catches forbidden imports, invalid storage types, missing decorators, and non-deterministic operations before deployment.
• CI pipeline: a GitHub Actions workflow that runs linting and direct tests automatically.
• Next.js 15 frontend: a TypeScript app using TanStack Query and Radix UI, wired to read from and write to a deployed contract.
• Deployment scripts: TypeScript scripts and a config template for deploying contracts to a chosen network.

Ideal use cases

• You're learning GenLayer and want a runnable example instead of documentation alone.
• You're starting a new intelligent contract project and want a project layout (contracts, tests, deploy scripts, frontend) already wired together.
• You're building an AI coding agent workflow (Claude Code, Cursor, etc.) and need a fast lint + direct-test feedback loop without spinning up GenLayer Studio each time.
• You want to see how web access and LLM calls fit into a contract's deterministic execution model via the equivalence principle.

It's not a fit if you need a production-ready betting application as-is (it's a demo contract, not audited for real-money use), or if your use case has nothing to do with intelligent contracts or GenLayer's specific execution model. It also assumes familiarity with Python for contract code and TypeScript/Next.js for the frontend; it isn't a general-purpose smart contract framework for other chains.

Installation

Requirements: Python >= 3.12, the GenLayer CLI installed globally, and GenLayer Studio (local or hosted) for integration tests and deployment.

npm install -g genlayer

Set up the Python environment:

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

Lint the contract before testing:

genvm-lint check contracts/football_bets.py

Run direct mode tests (no Studio required):

pytest tests/direct/ -v

Deploy the contract once you've picked a network:

genlayer network
genlayer deploy

Run integration tests against a running GenLayer Studio instance:

gltest tests/integration/ -v -s

Set up the frontend by copying frontend/.env.example to frontend/.env, adding your deployed contract address as NEXT_PUBLIC_CONTRACT_ADDRESS, then:

cd frontend
npm install
npm run dev

The app runs at http://localhost:3000/.