genlayer-project-boilerplate

18.8K stars
MIT
Active recently
Last commit 43 days ago

Last verified Oct 17, 2026

Build and test GenLayer intelligent contracts with this MIT-licensed boilerplate: LLM integration, web access, contract linting, and a Next.js 15 frontend.

Visit website GitHub18.8K

Read the full breakdownWho it is for, how it works, trade-offs, the quick start and the FAQ

who it's for

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

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 genlayer-project-boilerplate solves it

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 · trade-offs

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.

versus alternatives

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 · quick start

Quick start#

bash

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
```

tech stack · detected from GitHub

What it's built on#

Languages: PythonTypeScript
Frameworks: Next.jsReact

frequently asked

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.

also worth a look

Similar open-source tools#

CodeBoarding

Alternative toCodeDashboard

Review code changes as architecture maps, not line diffs

2,601 GitHub stars
Licence MIT

Dyad

Alternative toLovable

Local, open-source AI app builder with your own API keys

22,031 GitHub stars
Licence Apache-2.0 with separate pro-directory license

Cloudflare Os

Alternative toDust

Open source AI workspace with sandboxed apps and Gatekeeper security

11,537 GitHub stars
Licence Apache-2.0

Effect

InWeb Development

Typed errors, DI, and concurrency for TypeScript

17,341 GitHub stars
Licence MIT

Firebase Ios Sdk

Alternative toAWS Amplify

Open source Apple SDK for Firebase auth, data, push and crashes

6,974 GitHub stars
Licence Apache-2.0

servers

Alternative toComposio

Open reference servers for connecting AI to external tools and data

91,470 GitHub stars
Licence Apache-2.0 and MIT (dual, transitioning)

by category

Open source tools in these categories#

196

2,957 GitHub stars
Licence Apache-2.0
#AI Agents

rakazo

Alternative toGrok Bot

AI teammates you own: your keys, your model, your machine.

4,904 GitHub stars
Licence Apache-2.0
#AI Agents

Inbox Zero

Alternative toSuperhuman

AI email assistant that drafts replies and clears your inbox

12,712 GitHub stars
Licence AGPL-3.0
#Email

Feature your project

The projects we add and every new guide. Free, unsubscribe any time.

Find open source alternatives to paid software

GenLayer Boilerplate vs Venly

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 vs Unity

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

Who genlayer-project-boilerplate is for#

Web3 developers starting a GenLayer project

Skip if:

Developers building prediction markets or betting apps

Skip if:

AI engineers exploring on-chain LLM integration

Skip if:

The problem it solves#

How it solves it#

Direct mode in-memory tests

Three-tier testing strategy

GenVM contract linter

Next.js 15 frontend with TypeScript

GitHub Actions CI pipeline

LLM and web access in intelligent contracts

Strengths and trade-offs#

Strengths

Trade-offs

genlayer-project-boilerplate vs alternatives#

GenLayer Boilerplate vs Venly

GenLayer Boilerplate vs Unity

Quick start#

What it's built on#

FAQ#

Similar open-source tools#

Open source tools in these categories#

Web Development

AI & Machine Learning

Developer Tools

Find open source alternatives to paid software

Who genlayer-project-boilerplate is for#

Web3 developers starting a GenLayer project

Skip if:

Developers building prediction markets or betting apps

Skip if:

AI engineers exploring on-chain LLM integration

Skip if:

The problem it solves#

How it solves it#

Direct mode in-memory tests

Three-tier testing strategy

GenVM contract linter

Next.js 15 frontend with TypeScript

GitHub Actions CI pipeline

LLM and web access in intelligent contracts

Strengths and trade-offs#

Strengths

Trade-offs

genlayer-project-boilerplate vs alternatives#

GenLayer Boilerplate vs Venly

GenLayer Boilerplate vs Unity

Quick start#

What it's built on#

FAQ#

Similar open-source tools#

Open source tools in these categories#

Web Development

AI & Machine Learning

Developer Tools

Find open source alternatives to paid software