Who genlayer-project-boilerplate is for#
Web3 developers starting a GenLayer project
Provides the full development scaffold: contract, tests, linter, CI, and frontend in one repository. Developers can clone, set the contract address, and have a working development environment in under an hour instead of building tooling from scratch.
Skip if:
Skip if you are building on a different blockchain. The intelligent contract API, GenVM linter rules, and direct mode test helpers are GenLayer-specific and do not transfer to Ethereum, Solana, or other chains.
Developers building prediction markets or betting apps
The Football Bets contract demonstrates the exact pattern needed: accepting user predictions, fetching real-world outcomes from the web, using LLM inference to parse results, and distributing points to correct predictors. Prediction market developers get a working reference implementation.
Skip if:
Skip if your prediction market does not require web data fetching or LLM-based result parsing. A simpler oracle pattern may be sufficient for contracts with structured external data sources.
AI engineers exploring on-chain LLM integration
GenLayer intelligent contracts run LLM inference as part of consensus, validated by multiple nodes via the equivalence principle. This boilerplate demonstrates mocking LLM calls in tests and verifying consensus in integration tests, giving AI engineers a concrete on-chain LLM integration pattern.
Skip if:
Skip if your use case requires low-latency LLM inference. On-chain LLM calls go through a consensus process across validator nodes, which is slower than calling a model API directly from a backend service.
The problem it solves#
Building on a new blockchain platform like GenLayer means starting with no scaffolding: configuring a Python contract environment, learning the equivalence principle, choosing a test strategy, and connecting a frontend to a deployed contract. Most developers spend their first days fighting tooling rather than writing application logic.
The GenLayer model adds a second layer of complexity: intelligent contracts fetch web data and call LLMs on-chain, but testing those behaviors without a running Studio instance is slow. Without fast in-memory tests that mock HTTP requests and LLM calls, every contract change requires a full Studio round-trip. A CI pipeline that automates linting and direct tests before any Studio deployment is not something most teams build from scratch on day one.
How it solves it#
Direct mode in-memory tests
Unit tests for intelligent contracts run in-memory without GenLayer Studio, using mocks for web requests (direct_vm.mock_web()) and LLM calls (direct_vm.mock_llm()). Each test completes in milliseconds, giving the fast feedback loop needed for iterative contract development or AI coding agents like Claude Code.
Three-tier testing strategy
Lint checks catch common contract issues in ~250ms with no Studio required. Direct tests run in milliseconds for in-memory logic verification. Integration tests deploy to GenLayer Studio for full consensus verification before production. Each tier maps to a specific command, speed, and Studio dependency as documented in the README testing table.
GenVM contract linter
The genvm-lint check command runs static analysis over Python contract files, catching forbidden imports, non-deterministic calls outside equivalence principle blocks, invalid storage types (TreeMap, DynArray, u256), missing decorators, and 20+ other rules. Runs in ~250ms with no Studio dependency, making it suitable for CI.
Next.js 15 frontend with TypeScript
A production-ready Next.js 15 app is included in the frontend/ directory, built with TypeScript, TanStack Query for data fetching, and Radix UI for components. It reads the deployed contract address from NEXT_PUBLIC_CONTRACT_ADDRESS, so it connects to any GenLayer deployment without code changes.
GitHub Actions CI pipeline
A pre-built .github/workflows/ CI pipeline runs genvm-lint and direct mode tests on every push. Integration tests are excluded from CI because they require a running Studio instance, but lint and unit-level feedback run automatically, catching contract issues before any manual testing step.
LLM and web access in intelligent contracts
The included Football Bets contract fetches match results from BBC Sport and uses an LLM to extract the score, then validates the result via the equivalence principle across multiple validator nodes. This pattern of on-chain web fetch plus LLM inference is the core GenLayer primitive the boilerplate demonstrates end-to-end.
Strengths and trade-offs#
Strengths
- Millisecond feedback without StudioDirect mode tests run contract logic in-memory using mocked web and LLM responses, so developers can iterate on contract behavior without a running GenLayer Studio instance. The README specifically notes this matches the fast feedback loop that AI coding agents (Claude Code, Cursor) need for iterative development.
- End-to-end stack in one repositoryMost blockchain boilerplates cover the contract layer only. This one ships a sample intelligent contract, three test tiers, a linting step, a CI pipeline, and a Next.js 15 frontend that connects to the deployed contract. The full stack is wired together and ready to clone.
- MIT license with no runtime feesThe MIT license places no restrictions on commercial use, modification, or distribution. Unlike managed Web3 API platforms that charge per API call or per wallet operation, running on GenLayer means no per-call billing from a middleware vendor.
- Equivalence principle testing patternThe integration tests demonstrate how to verify GenLayer's equivalence principle in practice: deploying the contract to Studio and confirming that multiple validator nodes reach consensus on LLM-based resolution. This is a non-trivial behavior to test, and the boilerplate provides a working reference pattern.
Trade-offs
- -Single example contract: football betting gameThe boilerplate ships one intelligent contract (Football Bets). Developers building contracts outside betting or prediction markets must adapt the examples to their domain. The testing infrastructure and CI pipeline transfer directly, but the contract logic and frontend are sports-specific and need rewriting for other use cases.
- -Requires Python 3.12 and the GenLayer CLIThe contract environment requires Python 3.12 or later and the GenLayer CLI (npm install -g genlayer). Teams that do not already run a Python environment alongside their Node.js toolchain add a second language runtime to their stack. Integration tests additionally require GenLayer Studio, which is not a lightweight dependency.
- -GenLayer-specific: no portability to other chainsIntelligent contracts are a GenLayer concept. The Python contract code, the GenVM linter rules, and the direct mode test API (direct_deploy, direct_vm) only work on GenLayer. This boilerplate does not port to Ethereum, Solana, or other chains.
genlayer-project-boilerplate vs alternatives#
GenLayer Boilerplate vs Venly
Venly is a commercial Web3 infrastructure service that provides managed APIs for blockchain integration. GenLayer Project Boilerplate is an open source starter kit for the GenLayer network, which runs intelligent contracts with on-chain LLM inference and web access.
| Feature | GenLayer Boilerplate | Venly |
|---|---|---|
| License | MIT | Proprietary |
| Self-hosting | Yes (GenLayer node + Studio) | No |
| Pricing | Free to deploy | Pay-per-use or subscription |
| Contract logic | Python intelligent contracts on-chain | Off-chain app logic via managed APIs |
| LLM integration | Native on-chain via GenLayer consensus | Not available |
GenLayer boilerplate is the better choice when you need on-chain LLM inference and web data access as part of contract execution, and when data sovereignty or cost predictability make a managed API service impractical. Venly is worth considering when you need managed wallet infrastructure and multi-chain blockchain integration through an API without deploying or maintaining your own node infrastructure.
GenLayer Boilerplate vs Unity
Unity is a commercial game engine with a proprietary license used for building 2D and 3D games, including blockchain games via third-party Web3 plugins. GenLayer Project Boilerplate targets a narrower scope: the smart contract and backend layer of a blockchain-based game or prediction market, not the graphics or rendering layer.
| Feature | GenLayer Boilerplate | Unity |
|---|---|---|
| License | MIT | Proprietary (free tier available) |
| Primary use | Intelligent smart contracts | Game engine (2D/3D rendering, physics) |
| Blockchain support | GenLayer network | Via third-party plugins |
| LLM integration | Native on-chain | Not built-in |
The comparison is more complementary than competitive: a blockchain game could use Unity for the rendering layer and GenLayer for on-chain contract logic. GenLayer boilerplate replaces Unity only in the specific scenario where a team wants to build a lightweight web-based game frontend using the included Next.js 15 app rather than a native game client. For any project requiring 3D graphics, physics, or platform-native deployment, Unity remains the appropriate choice regardless of the contract layer.
Install and self-host#
Install Python dependencies and the GenLayer CLI before running tests or deploying contracts.
```bash
git clone https://github.com/genlayerlabs/genlayer-project-boilerplate
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
npm install -g genlayer
```What it's built on#
- Languages
- PythonTypeScript
- Frameworks
- Next.jsReact
FAQ#
What is GenLayer and how does this boilerplate fit in?
GenLayer is a blockchain where contracts can access the web and run LLM inference as part of their execution. This boilerplate is a starter project for building on GenLayer: it includes a sample intelligent contract (Football Bets), a three-tier test suite, a contract linter, a CI pipeline, and a Next.js 15 frontend. It removes the setup work developers would otherwise do manually when starting a GenLayer project.
Can I run the tests without GenLayer Studio?
Yes. The lint step and direct mode tests both run without Studio and complete in milliseconds. Only the integration tests require a running Studio instance (local or the hosted studio.genlayer.com). The README testing table maps each tier to its command, speed, and Studio dependency clearly.
Is this boilerplate licensed for commercial use?
Yes. The project is MIT licensed, which allows commercial use, modification, and redistribution without restriction. The MIT license terms are in the LICENSE file in the repository.
What Python version does this project require?
Python 3.12 or later is required for the contract environment. The GenLayer CLI is installed separately via npm (npm install -g genlayer). Contract files live in the contracts/ directory as Python source. The frontend is a standard Node.js application and has no Python dependency.
Does this project work with any blockchain or only GenLayer?
Only GenLayer. The intelligent contract model, the GenVM linter, the direct mode test API (direct_deploy, direct_vm), and the deployment scripts all target the GenLayer network specifically. The boilerplate does not support Ethereum, Solana, or other chains, and the contract code is not portable across blockchain runtimes.
Similar open-source tools#
r3
Minimalist Forth language for games and systems programming
Godot Engine
Free open source game engine for 2D and 3D development
Flare
Graph-first IDE for agentic coding and real-time oversight
dograh
Open source voice agent builder with telephony and BYOK AI support
whishper
Local speech-to-text transcription and subtitling with a web UI
ego-lite
AI agent browser with shared Chrome state, zero cost