DEV Community: onyi

From Zero to GenLayer: Connecting Your dApp with Next.js and genlayer-js (Part 3/3)

onyi — Fri, 20 Mar 2026 20:25:37 +0000

Your contract is deployed. It lives on the GenLayer network, it can create bets, accept them, and use AI to resolve subjective outcomes. You tested it in Studio, watched validators argue about whether a movie was "critically acclaimed," and saw the right answer win. That was satisfying.

But nobody is going to interact with your contract through a developer console. They need a frontend. So let us build one.

Project Setup

GenLayer provides an official boilerplate that gives you a full-stack project out of the box. Clone it:

git clone https://github.com/genlayerlabs/genlayer-project-boilerplate.git GenBets
cd GenBets

Take a look at what you get:

GenBets/
  contracts/          # Python intelligent contracts
  frontend/           # Next.js 15 app (TypeScript, Tailwind, TanStack Query)
  deploy/             # TypeScript deployment scripts
  test/               # Python integration tests

The boilerplate ships with a sample contract called football_bets.py. We do not need it. Replace it with the genbets.py contract you wrote in Part 2:

cp your-genbets-contract/genbets.py contracts/genbets.py

Now set up the frontend:

cd frontend
npm install

Copy the environment template and configure it:

cp .env.example .env

Open .env and set the contract address you got from Studio when you deployed in Part 2:

NEXT_PUBLIC_GENLAYER_RPC_URL=https://studio.genlayer.com/api
NEXT_PUBLIC_GENLAYER_CHAIN_ID=61999
NEXT_PUBLIC_GENLAYER_CHAIN_NAME=GenLayer Studio
NEXT_PUBLIC_GENLAYER_SYMBOL=GEN
NEXT_PUBLIC_CONTRACT_ADDRESS=0xYourContractAddressFromStudio

That last line is the important one. Without it, the frontend has no idea which contract to talk to.

The frontend stack is modern but not exotic: Next.js 15 with the App Router, React 19, TypeScript, Tailwind CSS for styling, TanStack Query for data management, and MetaMask wallet integration through genlayer-js. If you have built a React app before, nothing here will surprise you. The only new piece is genlayer-js -- GenLayer's JavaScript SDK for reading from and writing to intelligent contracts.

Understanding the Architecture

Before diving into code, it helps to understand how the pieces connect. The boilerplate separates concerns into four layers:

Contract class (lib/contracts/GenBets.ts) -- A TypeScript wrapper around raw genlayer-js calls. This is where readContract() and writeContract() live.
React hooks (lib/hooks/useGenBets.ts) -- Custom hooks that wrap the contract class with TanStack Query for caching, loading states, and automatic refetching.
UI components (components/) -- The visible interface. Tables, modals, buttons, status badges.
Wallet management (lib/genlayer/client.ts and WalletProvider.tsx) -- MetaMask connection, network switching, and account management.

The data flow for every user action follows the same path:

User clicks button
  -> React hook fires
    -> Contract class method called
      -> genlayer-js sends request to GenLayer RPC
        -> GenLayer network processes transaction

The GenLayer client connects to the Studio RPC endpoint (or a local node) and delegates transaction signing to MetaMask. When you call writeContract(), MetaMask pops up asking the user to confirm. When you call readContract(), it is a free read -- no signature needed, no popup.

TanStack Query sits in the middle and handles the tedious parts: caching responses so you do not re-fetch data on every render, automatically refetching when the browser window regains focus, and invalidating stale data after a mutation succeeds.

The Contract Class

The GenBets.ts contract class is the bridge between your TypeScript frontend and your Python contract on GenLayer. Here is how it works.

The constructor creates a genlayer-js client configured with the chain, the user's wallet address, and the RPC endpoint:

import { createClient } from "genlayer-js";
import { studionet } from "genlayer-js/chains";

class GenBets {
  private contractAddress: `0x${string}`;
  private client: ReturnType<typeof createClient>;

  constructor(contractAddress: string, address?: string | null, studioUrl?: string) {
    this.contractAddress = contractAddress as `0x${string}`;

    const config: any = { chain: studionet };
    if (address) config.account = address as `0x${string}`;
    if (studioUrl) config.endpoint = studioUrl;

    this.client = createClient(config);
  }
}

Two fundamental operations drive everything:

Reading state uses readContract(). This calls @gl.public.view methods on the contract. No gas, no wallet signature. The getBets() method demonstrates a common pattern -- calling get_bet_count first, then looping through get_bet(i) to build an array:

async getBets(): Promise<Bet[]> {
  const betCount: any = await this.client.readContract({
    address: this.contractAddress,
    functionName: "get_bet_count",
    args: [],
  });

  const count = Number(betCount);
  const bets: Bet[] = [];

  for (let i = 0; i < count; i++) {
    const betData: any = await this.client.readContract({
      address: this.contractAddress,
      functionName: "get_bet",
      args: [i],
    });
    bets.push({ id: i, ...betData } as Bet);
  }
  return bets;
}

Writing state uses writeContract(). This calls @gl.public.write methods, which modify the blockchain. These require a wallet signature and cost gas. After sending the transaction, you wait for it to be accepted:

async createBet(description: string, resolutionUrl: string,
                resolutionPrompt: string, opponent: string): Promise<TransactionReceipt> {
  const txHash = await this.client.writeContract({
    address: this.contractAddress,
    functionName: "create_bet",
    args: [description, resolutionUrl, resolutionPrompt, opponent],
  });

  const receipt = await this.client.waitForTransactionReceipt({
    hash: txHash,
    status: "ACCEPTED",
    retries: 24,
    interval: 5000,
  });
  return receipt;
}

That waitForTransactionReceipt() call is worth understanding. GenLayer transactions do not go from "pending" to "confirmed" like Ethereum. They move through a multi-stage consensus pipeline: PENDING, PROPOSING, COMMITTING, REVEALING, ACCEPTED, and finally FINALIZED. Each stage corresponds to a phase of the Optimistic Democracy protocol, where validators independently execute the contract, propose results, and vote on whether they agree. The status: "ACCEPTED" parameter tells the SDK to wait until validators have reached consensus and the transaction is accepted -- though not yet finalized.

Notice there is no value parameter in the writeContract() call. The GenBets contract does not handle token transfers -- it tracks who wins but does not move money. This keeps the contract simple and focused on the AI resolution logic.

The resolveBet() method follows the same pattern but returns the winner string from the transaction receipt, so the UI can display who won.

React Hooks

The hooks layer wraps each contract method with TanStack Query, turning raw async calls into reactive data that components can consume without thinking about loading states or cache invalidation.

The useBets() hook fetches all bets and keeps them fresh:

export function useBets() {
  const contract = useGenBetsContract();

  return useQuery<Bet[], Error>({
    queryKey: ["bets"],
    queryFn: () => contract ? contract.getBets() : Promise.resolve([]),
    refetchOnWindowFocus: true,
    staleTime: 2000,
    enabled: !!contract,
  });
}

Any component that calls useBets() gets { data, isLoading, isError } -- the standard TanStack Query return shape. Multiple components can call the same hook and they will share the cached result rather than making duplicate network requests.

Mutations follow a different pattern. useCreateBet() wraps the contract's write method and handles cache invalidation on success:

export function useCreateBet() {
  const contract = useGenBetsContract();
  const queryClient = useQueryClient();
  const [isCreating, setIsCreating] = useState(false);

  const mutation = useMutation({
    mutationFn: async ({ description, resolutionUrl, resolutionPrompt,
                         opponent }) => {
      setIsCreating(true);
      return contract.createBet(description, resolutionUrl,
                                resolutionPrompt, opponent);
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["bets"] });
      setIsCreating(false);
    },
  });

  return { ...mutation, isCreating, createBet: mutation.mutate };
}

When a bet is created successfully, invalidateQueries({ queryKey: ["bets"] }) tells TanStack Query that the cached bets list is stale. Every component using useBets() automatically refetches.

The useResolveBet() hook adds one extra piece: it tracks which bet is currently being resolved and stores the winner string returned from the receipt. This lets the UI show a spinner on the correct row and display the winner when it arrives.

The pattern across all hooks is consistent: create a contract instance from the current wallet context, call the contract method, update local state for loading indicators, invalidate relevant caches on success, and show toast notifications for success or failure.

The UI Components

With the hooks in place, the components are straightforward React.

Bets Table

The GenBetsTable component renders every bet as a row in a table with columns for description, status, creator, opponent, winner, and actions:

export function GenBetsTable() {
  const { data: bets, isLoading, isError } = useBets();
  const { address, isConnected } = useWallet();
  const { acceptBet, isAccepting, acceptingBetId } = useAcceptBet();
  const { cancelBet, isCancelling, cancellingBetId } = useCancelBet();
  const { resolveBet, isResolving, resolvingBetId } = useResolveBet();

  // ... loading and error states ...

  return (
    <table>
      {bets.map((bet) => (
        <BetRow
          key={bet.id}
          bet={bet}
          currentAddress={address}
          onAccept={handleAccept}
          onCancel={handleCancel}
          onResolve={handleResolve}
          isAccepting={isAccepting && acceptingBetId === bet.id}
        />
      ))}
    </table>
  );
}

Each row conditionally renders action buttons based on the bet's status and the connected wallet. If you are the invited opponent and the bet is open, you see an "Accept" button. If you are the creator, you see "Cancel." If the bet has been accepted by both parties, anyone can click "Resolve" to trigger AI resolution. Status badges use color coding -- yellow for open, blue for accepted, green for resolved, red for cancelled. Resolved bets display the winner ("creator" or "opponent") in the winner column.

Create Bet Modal

The CreateGenBetModal component is a dialog form with four fields: bet description, resolution URL, resolution prompt, and opponent address. It validates inputs client-side (valid URL format, valid address, cannot bet against yourself) before submitting:

const handleSubmit = async (e: React.FormEvent) => {
  e.preventDefault();
  if (!validateForm()) return;

  createBet({ description, resolutionUrl, resolutionPrompt,
              opponentAddress });
};

The form is straightforward — no stake or amount fields since the contract does not handle token transfers. The modal auto-closes on success and resets its form fields, thanks to a useEffect that watches the mutation's isSuccess state.

Navbar

The Navbar ties everything together with GenBets branding, live statistics (total bets, resolved count), a "Create Bet" button that opens the modal, and the wallet connection panel. The stats update automatically because they derive from the same useBets() query that the table uses -- no extra network calls.

End-to-End Demo

Time to see it all work together.

Step 1: Start the dev server.

npm run dev

Open http://localhost:3000 in your browser. You should see the GenBets interface with an empty bets table.

Step 2: Connect your wallet.

Click the wallet button in the navbar. MetaMask will ask you to connect and may prompt you to add the GenLayer Studio network (chain ID 61999). Accept both prompts. Your address appears in the navbar.

If you are using GenLayer Studio, it provides pre-funded test accounts. Import one of those private keys into MetaMask so you have GEN tokens to work with.

Step 3: Create a bet.

Click "Create Bet." Fill in something like:

Description: "The Shawshank Redemption has above 90% on Rotten Tomatoes"
Resolution URL: https://www.rottentomatoes.com/m/shawshank_redemption
Resolution Prompt: "Check the Tomatometer score on this page. If it is above 90%, the creator wins. If it is 90% or below, the opponent wins."
Opponent: paste the address of a second test account

Click "Create Bet." MetaMask asks you to sign. Confirm. The button shows a spinner while the transaction moves through consensus. After a few seconds, the bet appears in the table with status "Open."

Step 4: Accept the bet.

Switch MetaMask to the opponent account (the address you entered as the opponent). Refresh the page. You will see the bet with an "Accept" button. Click it, confirm the MetaMask transaction, and the status changes to "Accepted."

Step 5: Resolve with AI.

Click "Resolve." This is where GenLayer does something no other blockchain can do. The transaction triggers your contract's resolve_bet method, which tells validators to fetch the Rotten Tomatoes page, read the score, and determine the winner using your prompt. Multiple validators do this independently and compare their answers through the Equivalence Principle.

Resolution takes longer than a simple transfer -- expect 15 to 30 seconds. The validators are independently browsing the web, running LLM reasoning, and reaching consensus. When they finish, the bet status flips to "Resolved" and the winner ("creator" or "opponent") is displayed.

Step 6: Verify.

Check the winner field on the resolved bet. It will show either "creator" or "opponent" based on what the AI validators determined from the web data.

What You Have Learned

Over three posts, we built a complete dApp on GenLayer from scratch. Here is everything we covered:

Intelligent Contracts. GenLayer's smart contracts are written in Python and can natively access the internet and large language models. No oracles, no off-chain workers -- the contract itself browses the web and reasons about what it finds.

Optimistic Democracy. GenLayer's consensus mechanism where multiple validators independently execute non-deterministic operations (web fetches, LLM calls) and vote on whether their results agree. This is not proof-of-work or proof-of-stake. It is a consensus protocol designed specifically for AI-powered execution.

The Equivalence Principle. The mechanism validators use to compare non-deterministic outputs. Strict equality for exact matches (like our single-word winner output), comparative prompts for "close enough" reasoning, and non-comparative prompts for independent assessment. This is how a blockchain can reach agreement on subjective questions.

GenLayer Studio. The development sandbox where you write, deploy, and test intelligent contracts. It simulates the full validator network locally so you can iterate quickly before deploying to a live network.

genlayer-js. The frontend SDK that connects your JavaScript or TypeScript application to GenLayer. readContract() for views, writeContract() for mutations, waitForTransactionReceipt() to track consensus progress.

The full stack. A Python intelligent contract deployed on GenLayer, connected through genlayer-js to a Next.js frontend, with MetaMask handling wallet management and TanStack Query managing data flow.

Next Steps

GenBets is a working dApp, but it is a starting point, not a finish line.

Deploy to testnet. GenLayer's public testnet, Asimov, lets you test with real (test) validators and real network conditions. Run genlayer network and select testnet, then redeploy your contract.

Extend GenBets. The current design tracks who wins but does not handle token transfers. Consider adding staking functionality where both parties lock tokens and the winner receives the pot. Add bet categories, a reputation system for reliable bettors, or time-limited bets that auto-resolve after a deadline.

Explore the ecosystem. The GenLayer documentation at docs.genlayer.com covers advanced contract patterns, testing strategies, and deployment workflows. Join the GenLayer Discord to connect with other builders. Browse the contract examples on GitHub for inspiration.

You started this series not knowing what an intelligent contract was. Now you have written one, tested it, deployed it, and built a frontend around it. You understand how AI-native consensus works, why the Equivalence Principle matters, and how genlayer-js connects a web app to a blockchain that can think.

Welcome to GenLayer. Now go build something intelligent.

From Zero to GenLayer: Writing Your First Intelligent Contract in Python (Part 2/3)

onyi — Fri, 20 Mar 2026 20:19:56 +0000

Recap

Welcome back. In Part 1 of this series, we covered what GenLayer is — an AI-native blockchain where "Intelligent Contracts" can call LLMs and fetch live web data right from on-chain code. We also got GenLayer Studio up and running so we have a local playground ready to go. If you missed it, go back and read Part 1 first. Now it is time to actually write some code.

What We're Building

We are building GenBets — a peer-to-peer betting contract where users can wager on subjective, real-world outcomes. Here is the flow: a creator posts a bet with a description (like "Inception will have above 80% on Rotten Tomatoes") and names an opponent. The opponent accepts the bet. Then anyone can trigger resolution, at which point the AI validators fetch a web page, read the actual data, reason about who won, and record the winner on-chain. No oracles. No manual judging. The AI handles it.

Contract Architecture

Before we dive into the code line by line, let us look at the big picture. The GenBets contract has six public methods:

Method	Decorator	What It Does
`create_bet()`	`@gl.public.write`	Creates a new bet with a named opponent
`accept_bet()`	`@gl.public.write`	Opponent accepts the bet
`cancel_bet()`	`@gl.public.write`	Creator cancels an open bet
`resolve_bet()`	`@gl.public.write`	AI fetches web data, evaluates the outcome, records the winner
`get_bet()`	`@gl.public.view`	Returns all details of a specific bet
`get_bet_count()`	`@gl.public.view`	Returns how many bets have been created

Let us talk about those decorators. They tell GenLayer how a method behaves:

@gl.public.write — This method modifies the contract's state. When a user calls a write method, the transaction goes through the validator consensus process.
@gl.public.view — Read-only. It looks at the contract's data but changes nothing. These calls are free and fast.

The contract stores its data using two state variables:

bets: TreeMap[u256, Bet] — A key-value map where the key is a bet ID (an unsigned 256-bit integer) and the value is a Bet object. TreeMap is GenLayer's on-chain storage type, similar to a dictionary that persists between transactions.
bet_counter: u256 — A simple counter that increments every time a bet is created, giving each bet a unique ID.

Each bet is represented by the Bet dataclass, which holds the creator's address (as a string), the opponent's address (as a string), a human-readable description, the URL to check for resolution, the prompt that tells the AI how to judge, the current status ("open", "accepted", "cancelled", or "resolved"), and the winner (a string — either "creator", "opponent", or empty).

One important runtime value you will see throughout the code:

gl.message.sender_address — The wallet address of whoever is calling the method. This is how the contract knows who is making a request. The contract converts it to a string with str() for comparison and storage.

Building Step by Step

Step 1: The Foundation

Let us start with the skeleton — imports, the data model, and the contract class.

# { "Depends": "py-genlayer:test" }

import json
from dataclasses import dataclass
from genlayer import *


@allow_storage
@dataclass
class Bet:
    creator: str
    opponent: str
    description: str
    resolution_url: str
    resolution_prompt: str
    status: str
    winner: str


class GenBets(gl.Contract):
    bet_counter: u256
    bets: TreeMap[u256, Bet]

    def __init__(self):
        self.bet_counter = u256(0)

Walking through this:

The comment on line 1 is a metadata hint for GenLayer's build system — it tells it which dependencies this contract needs.
We import json (standard Python) for potential use in data handling.
from genlayer import * gives us everything GenLayer-specific: gl, u256, TreeMap, and the decorators.
The @allow_storage decorator on the Bet dataclass tells GenLayer that this class can be stored on-chain. Without it, you cannot put a custom object into a TreeMap.
Notice that creator, opponent, and winner are all str fields, not Address. We store addresses as plain strings, which simplifies comparisons and storage.
GenBets extends gl.Contract, which is the base class for all intelligent contracts. The two class-level type annotations (bet_counter and bets) declare the contract's persistent storage.
The __init__ method runs once when the contract is first deployed. We initialize the counter to zero. The TreeMap does not need explicit initialization — it starts empty.

Step 2: Creating a Bet

Now let us add the ability for someone to create a bet.

@gl.public.write
def create_bet(self, description: str, resolution_url: str, resolution_prompt: str, opponent: str) -> u256:
    bet_id = self.bet_counter
    self.bets[bet_id] = Bet(creator=str(gl.message.sender_address), opponent=opponent, description=description, resolution_url=resolution_url, resolution_prompt=resolution_prompt, status="open", winner="")
    self.bet_counter = bet_id + u256(1)
    return bet_id

This method is @gl.public.write — it modifies the contract's state but does not handle any token transfers.

We grab the current counter value as the new bet's ID, create a Bet object with all the details, and store it in the TreeMap. The creator field is set by converting gl.message.sender_address to a string. The opponent is passed in as a string (the opponent's address). The winner field starts as an empty string meaning "no winner yet." Finally, we bump the counter for the next bet and return the new bet's ID so the caller knows which bet they just created.

Notice that the caller provides four arguments (description, resolution_url, resolution_prompt, opponent), but we also capture one implicit value: gl.message.sender_address becomes the creator. The caller does not pass this explicitly — it comes from the transaction itself.

Step 3: Accepting a Bet

The opponent needs to accept the bet.

@gl.public.write
def accept_bet(self, bet_id: u256) -> None:
    bet = self.bets[bet_id]
    if bet.status != "open":
        raise Exception("Bet is not open")
    if str(gl.message.sender_address) == bet.creator:
        raise Exception("Cannot accept your own bet")
    if str(gl.message.sender_address) != bet.opponent:
        raise Exception("Only the invited opponent can accept")
    bet.status = "accepted"
    self.bets[bet_id] = bet

Three validations protect against misuse. The bet must be open (not already accepted, cancelled, or resolved). You cannot accept your own bet. Only the specific opponent the creator named can accept — the contract compares str(gl.message.sender_address) against the stored opponent string.

If all checks pass, we update the status to "accepted" and write the updated bet back to storage.

Step 4: Cancelling a Bet

What if no one accepts your bet and you want to withdraw it?

@gl.public.write
def cancel_bet(self, bet_id: u256) -> None:
    bet = self.bets[bet_id]
    if bet.status != "open":
        raise Exception("Can only cancel open bets")
    if str(gl.message.sender_address) != bet.creator:
        raise Exception("Only creator can cancel")
    bet.status = "cancelled"
    self.bets[bet_id] = bet

Only open bets can be cancelled (you cannot cancel a bet someone already accepted — that would be unfair). Only the creator can cancel. If those checks pass, we mark it as cancelled and save the updated bet.

Step 5: The Magic — Resolving a Bet

This is the heart of the contract and the part that makes GenLayer different from every other blockchain. Let us look at the full method first, then break it down.

@gl.public.write
def resolve_bet(self, bet_id: u256) -> str:
    bet = self.bets[bet_id]
    if bet.status != "accepted":
        raise Exception("Bet must be in accepted status")

    def nondet() -> str:
        web_data = gl.nondet.web.render(bet.resolution_url, mode="text")

        task = f"""You are an impartial judge evaluating a bet.

Bet description: {bet.description}

Resolution criteria: {bet.resolution_prompt}

Web page content:
{web_data[:3000]}
End of web page data.

Based on the data above, determine who wins this bet.
You must respond with exactly one word: either "creator" or "opponent".
Nothing else. Just one word.
"""
        result = gl.nondet.exec_prompt(task).strip().lower()
        if "creator" in result:
            return "creator"
        return "opponent"

    winner = gl.eq_principle.strict_eq(nondet)

    bet.winner = winner
    bet.status = "resolved"
    self.bets[bet_id] = bet
    return winner

There is a lot happening here, so let us go piece by piece.

The closure pattern. The inner function nondet() is the non-deterministic part — the code that each validator will run independently. Everything inside this function can vary between validators (because web pages can return slightly different content and LLMs can give slightly different answers). Everything outside it is deterministic and runs the same way on every validator.

Fetching web data. gl.nondet.web.render(bet.resolution_url, mode="text") tells the validator's GenVM to actually visit the URL and render the page, then return the text content as a string. The mode="text" parameter means we want the readable text, not raw HTML. This is the "internet-native" part of GenLayer — your contract can read any web page. Note that render() returns a string directly — there is no need to call .body.decode() on the result.

Building the LLM prompt. We construct a prompt that gives the AI everything it needs: the bet description, the resolution criteria the creator specified, and the actual web page content. We truncate the page content to 3000 characters with web_data[:3000] to keep the prompt a reasonable size — web pages can be huge, and we only need the relevant data. Crucially, the prompt instructs the LLM to respond with exactly one word: either "creator" or "opponent." Nothing else.

Calling the LLM. gl.nondet.exec_prompt(task) sends the prompt to the LLM and returns a plain string. There is no response_format="json" here — we want a simple, single-word answer. The result is normalized with .strip().lower() to remove whitespace and ensure consistent casing. Then we check if "creator" appears in the result; if so, we return "creator", otherwise "opponent". This normalization step is critical for consensus.

Ensuring validator consensus with strict_eq. Here is where it gets interesting. Each validator runs nondet() independently — they each fetch the web page and query the LLM separately. But for the transaction to be finalized, the validators need to agree on the result. That is what gl.eq_principle.strict_eq(nondet) does.

The strict_eq function requires that every validator produces exactly the same string output. This is why we designed the prompt to return a single word and then normalize the response to one of exactly two possible values: "creator" or "opponent". No matter which LLM a validator uses, no matter how it phrases its reasoning internally, the final output of nondet() will always be one of these two strings. Since strict_eq compares the outputs character-by-character, this design guarantees that validators who reach the same conclusion will produce identical output. No JSON serialization tricks needed — just a clean, deterministic single-word result.

Recording the winner. The winner variable is a string — either "creator" or "opponent". We store it directly in bet.winner, update the status to "resolved", save the bet, and return the winner string.

Step 6: View Methods

Finally, two read-only methods to inspect the contract's state.

@gl.public.view
def get_bet(self, bet_id: u256) -> dict:
    bet = self.bets[bet_id]
    return {"id": int(bet_id), "creator": bet.creator, "opponent": bet.opponent, "description": bet.description, "resolution_url": bet.resolution_url, "resolution_prompt": bet.resolution_prompt, "status": bet.status, "winner": bet.winner}

@gl.public.view
def get_bet_count(self) -> u256:
    return self.bet_counter

get_bet() takes a bet ID and returns a dictionary with all the bet's details. Since creator, opponent, and winner are already strings, no conversion is needed — we return them directly. get_bet_count() simply returns how many bets have been created — useful for iterating through all bets on the frontend.

These are @gl.public.view methods, meaning they do not modify any state. They are free to call and return instantly.

The Complete Contract

Here is the complete contract in one block — copy and paste this into Studio.

# { "Depends": "py-genlayer:test" }

import json
from dataclasses import dataclass
from genlayer import *


@allow_storage
@dataclass
class Bet:
    creator: str
    opponent: str
    description: str
    resolution_url: str
    resolution_prompt: str
    status: str
    winner: str


class GenBets(gl.Contract):
    bet_counter: u256
    bets: TreeMap[u256, Bet]

    def __init__(self):
        self.bet_counter = u256(0)

    @gl.public.write
    def create_bet(self, description: str, resolution_url: str, resolution_prompt: str, opponent: str) -> u256:
        bet_id = self.bet_counter
        self.bets[bet_id] = Bet(creator=str(gl.message.sender_address), opponent=opponent, description=description, resolution_url=resolution_url, resolution_prompt=resolution_prompt, status="open", winner="")
        self.bet_counter = bet_id + u256(1)
        return bet_id

    @gl.public.write
    def accept_bet(self, bet_id: u256) -> None:
        bet = self.bets[bet_id]
        if bet.status != "open":
            raise Exception("Bet is not open")
        if str(gl.message.sender_address) == bet.creator:
            raise Exception("Cannot accept your own bet")
        if str(gl.message.sender_address) != bet.opponent:
            raise Exception("Only the invited opponent can accept")
        bet.status = "accepted"
        self.bets[bet_id] = bet

    @gl.public.write
    def cancel_bet(self, bet_id: u256) -> None:
        bet = self.bets[bet_id]
        if bet.status != "open":
            raise Exception("Can only cancel open bets")
        if str(gl.message.sender_address) != bet.creator:
            raise Exception("Only creator can cancel")
        bet.status = "cancelled"
        self.bets[bet_id] = bet

    @gl.public.write
    def resolve_bet(self, bet_id: u256) -> str:
        bet = self.bets[bet_id]
        if bet.status != "accepted":
            raise Exception("Bet must be in accepted status")

        def nondet() -> str:
            web_data = gl.nondet.web.render(bet.resolution_url, mode="text")

            task = f"""You are an impartial judge evaluating a bet.

Bet description: {bet.description}

Resolution criteria: {bet.resolution_prompt}

Web page content:
{web_data[:3000]}
End of web page data.

Based on the data above, determine who wins this bet.
You must respond with exactly one word: either "creator" or "opponent".
Nothing else. Just one word.
"""
            result = gl.nondet.exec_prompt(task).strip().lower()
            if "creator" in result:
                return "creator"
            return "opponent"

        winner = gl.eq_principle.strict_eq(nondet)

        bet.winner = winner
        bet.status = "resolved"
        self.bets[bet_id] = bet
        return winner

    @gl.public.view
    def get_bet(self, bet_id: u256) -> dict:
        bet = self.bets[bet_id]
        return {"id": int(bet_id), "creator": bet.creator, "opponent": bet.opponent, "description": bet.description, "resolution_url": bet.resolution_url, "resolution_prompt": bet.resolution_prompt, "status": bet.status, "winner": bet.winner}

    @gl.public.view
    def get_bet_count(self) -> u256:
        return self.bet_counter

Deploy and Test in Studio

Let us take this contract for a spin.

Deploy the contract. Open GenLayer Studio (either the local version at localhost:8080 or the hosted version at studio.genlayer.com). Paste the complete contract code into the editor and click Deploy. Once it deploys successfully, note the contract address — you will need it later.

Create a bet. With your first account selected, call create_bet with these parameters:

description: "Inception will have above 80% on Rotten Tomatoes"
resolution_url: "https://www.rottentomatoes.com/m/inception"
resolution_prompt: "Check if the Tomatometer score is above 80%. If yes, creator wins. If no, opponent wins."
opponent: the address of your second Studio account (copy it from the account dropdown)

The transaction should succeed and return 0 (the first bet's ID).

Accept the bet. Switch to your second account in Studio. Call accept_bet with bet_id set to 0. You should see the transaction succeed.

Resolve the bet. Now call resolve_bet with bet_id set to 0. This is where it gets interesting — watch the transaction logs. You will see each validator independently fetch the Rotten Tomatoes page, extract the score, and reason about whether it is above 80%. The validators compare their results, reach consensus, and the winner is recorded. The method returns the winner as a string — either "creator" or "opponent."

Inspect the result. Call get_bet with bet_id set to 0. You will see the full bet details including the status (now "resolved") and the winner (either "creator" or "opponent").

Try the error cases. These are worth testing to make sure the validations work:

Try calling cancel_bet on the resolved bet — you should get "Can only cancel open bets."
Switch back to the first account and try calling accept_bet on your own bet — you should get "Cannot accept your own bet."
Create a new bet and try accepting it from an account that is not the named opponent — you should get "Only the invited opponent can accept."

These guardrails ensure the contract behaves correctly in every scenario.

What's Next

In Part 3, we will build a Next.js frontend that connects to our contract using genlayer-js, letting users create, accept, and resolve bets through a polished web interface. We will cover wallet connection with MetaMask, reading contract state with TanStack Query, and sending transactions — everything you need to turn this contract into a real application users can interact with.

From Zero to GenLayer: Why Smart Contracts Need AI (Part 1/3)

onyi — Fri, 20 Mar 2026 20:18:06 +0000

This is Part 1 of a 3-part tutorial series where we build GenBets -- a peer-to-peer betting dApp on GenLayer where friends bet on subjective outcomes and AI validators settle the result.

The Bet You Can't Settle on a Blockchain

Picture this: you and a friend are arguing about whether the latest Marvel movie is actually good. Not just box-office numbers -- you're debating whether it was well-received. Critics loved it, audiences were split, and Reddit is a warzone of hot takes. Your friend says it flopped creatively. You say it landed. So you make a bet.

Now here's the question nobody thinks to ask: who decides who wins? You could ask a mutual friend, but they might be biased. You could check Rotten Tomatoes, but what score counts as "well-received"? 85%? 70%? And what about audience scores versus critic scores? The whole thing is... subjective.

What if, instead of trusting a single person's judgment, the blockchain itself could read reviews, analyze sentiment, and reason about whether the movie was genuinely well-received -- and what if multiple independent AI models had to agree before anyone won? That is not science fiction. That is what GenLayer does, and by the end of this three-part series, you will have built exactly that.

The Problem: Smart Contracts Hit a Wall

If you have never touched blockchain before, here is the thirty-second version. A blockchain is a shared ledger that nobody owns but everyone can verify. A smart contract is a program that lives on that ledger -- it runs automatically, it cannot be tampered with, and it does exactly what its code says. Think of it as a vending machine: you put in the right inputs, you get the guaranteed output. No middleman needed.

That vending machine analogy, though, reveals the limitation. Traditional smart contracts are deterministic -- given the same input, they always produce the same output. They can add numbers, move tokens between accounts, and enforce rules like "only release payment after both parties sign." What they absolutely cannot do is think. They cannot read a news article and form an opinion. They cannot browse the web. They cannot interpret nuance.

So what happens when a smart contract needs real-world information? The blockchain world solved this with oracles -- services like Chainlink that feed external data into contracts. Need the current price of ETH? An oracle can provide that. Need last night's football scores? An oracle can deliver those too. Oracles are excellent at providing objective, verifiable facts: numbers, timestamps, binary outcomes.

But go back to our movie bet. No oracle can tell you whether a movie was "well-received." That requires reading multiple sources, weighing different perspectives, and making a judgment call. The same gap appears everywhere in real life: Did a startup's product launch "succeed"? Was a political debate performance "strong"? Did a restaurant "deserve" its Michelin star? These are the kinds of questions humans bet on, argue about, and make agreements around every single day -- and traditional smart contracts simply cannot handle them. There is a gap between what smart contracts can do and what real-world agreements actually need.

Enter GenLayer: The First AI-Native Blockchain

GenLayer closes that gap. It is a blockchain built from the ground up to integrate large language models (LLMs) into the contract execution layer itself. Contracts on GenLayer are not just deterministic code -- they are programs that can reason, browse the internet, and make nuanced judgments, all while maintaining the trustless guarantees that make blockchain valuable in the first place.

Let's break down the three pillars that make this work.

Intelligent Contracts: Smart Contracts That Think

On GenLayer, smart contracts are called Intelligent Contracts, and they are written in Python. If you are wondering why Python and not Solidity (the language most blockchains use), the answer is straightforward: Python is the lingua franca of AI and machine learning. When your contracts need to compose prompts, parse LLM outputs, and process web data, Python is the natural choice.

An Intelligent Contract looks like a regular Python class, but it has access to special functions that no traditional blockchain offers:

gl.nondet.exec_prompt() -- Sends a prompt to a large language model and gets back a response. Your contract can literally ask an AI a question and use the answer in its logic.
gl.nondet.web.render() -- Fetches and renders a live web page, returning its content. Your contract can read news articles, check review aggregators, or pull data from any public URL.

These are called non-deterministic operations because, unlike adding two numbers, they might return slightly different results each time. Different LLMs might phrase the same answer differently. A web page might update between requests. GenLayer has a specific mechanism for handling this, which brings us to the next pillar.

Optimistic Democracy: How Validators Agree

If a contract calls an LLM, and different validators are connected to different LLMs (GPT-4, Claude, Gemini, etc.), how do they agree on a result? GenLayer uses a consensus mechanism called Optimistic Democracy. Here is how it works:

               Transaction Submitted
                       |
                       v
            +---------------------+
            |   Leader Validator  |  <-- Randomly selected
            |  (runs the contract |
            |   and proposes an   |
            |      output)        |
            +---------------------+
                       |
                       v
       +-------------------------------+
       |       Validator Set           |
       |  [V1]   [V2]   [V3]   [V4]   |  <-- Each connected to
       |   |       |       |       |   |      a different LLM
       |   v       v       v       v   |
       | verify  verify  verify  verify|
       |   |       |       |       |   |
       |   v       v       v       v   |
       | vote    vote    vote    vote   |
       +-------------------------------+
                       |
                       v
              Majority Agrees?
              /              \
           Yes                No
            |                  |
            v                  v
     Transaction           Transaction
      Accepted              Rejected
            |
            v
     +--- Appeal Window ---+
     | Anyone can challenge |
     | by posting a bond.   |
     | Validator set doubles|
     | and re-votes.        |
     +----------------------+

A randomly selected subset of validators processes each transaction. One validator is chosen as the leader -- it runs the contract and proposes an output. The remaining validators then independently run the same contract and vote on whether the leader's output is acceptable. If a majority agrees, the transaction goes through.

But there is an important safety net: the appeal window. After a transaction is accepted, anyone who disagrees with the result can challenge it by posting a bond (putting tokens at stake). When a challenge is filed, the validator set doubles in size and the transaction is re-processed. This means bad results can be overturned, but frivolous challenges are discouraged because the challenger loses their bond if the original result holds. It is democracy with skin in the game.

The Equivalence Principle: Agreeing on "Close Enough"

Here is the subtle problem: if you ask GPT-4 and Claude the same question, they will give you correct but differently worded answers. "The movie was well-received" and "Critics and audiences responded positively to the film" mean the same thing, but they are different strings. A naive equality check would reject the transaction every time.

GenLayer solves this with the Equivalence Principle -- a mechanism that defines what "agreement" means for non-deterministic outputs. There are three variants, and choosing the right one is a key design decision when writing Intelligent Contracts:

1. Strict Equality -- gl.eq_principle.strict_eq()

The simplest form. The leader's output must exactly match what each validator produces. This works when you design the non-deterministic function to produce a single, deterministic output -- for example, returning a single word like "creator" or "opponent" rather than free-form text. If the LLM's answer is normalized to one of a small set of possible values, every validator will produce the same string, and strict equality passes cleanly.

# Example: strict equality for normalized single-word output
winner = gl.eq_principle.strict_eq(nondet)
# Every validator must return exactly the same string

2. Comparative -- gl.eq_principle.prompt_comparative()

Both the leader and each validator perform the same task independently. Then an LLM compares their outputs to see if they are substantively equivalent. This works well for quantitative or structured outputs where you expect the same conclusion but possibly different wording.

# Example: comparative equivalence
with gl.eq_principle.prompt_comparative(
    "Are these two summaries making the same factual claims?"
):
    result = gl.nondet.exec_prompt("Summarize this data...")
    # Validators do the same work, then compare

3. Non-Comparative -- gl.eq_principle.prompt_non_comparative()

Validators do not replicate the leader's work. Instead, they assess the leader's output against a set of criteria. Think of it like a teacher grading an essay: the teacher does not write their own essay first -- they just evaluate whether the submitted one meets the requirements. This is ideal for subjective, qualitative assessments.

# Example: non-comparative equivalence
result = gl.eq_principle.prompt_non_comparative(
    my_function,
    task="Summarize the sentiment of these reviews",
    criteria="The summary should accurately reflect the overall tone"
)

Which does GenBets use? GenBets uses strict_eq with a clever design: instead of asking the LLM to return complex JSON or free-form text, we ask it to return exactly one word -- either "creator" or "opponent." The code then normalizes the response with .strip().lower() and checks whether "creator" appears in the result. This means every validator, regardless of which LLM it runs, will produce the same single-word output: either "creator" or "opponent". Since the output is a simple, deterministic string, strict_eq passes reliably. We will see this pattern in detail in Part 2.

Meet GenBets: What We Are Building

Across this three-part series, we are building GenBets -- a peer-to-peer betting platform for subjective outcomes. No bookmakers, no centralized judges, no oracles feeding in predetermined data points. Just two people, a bet, and AI-powered validators that settle it.

Here is how it works:

+------------------+       +-------------------+       +--------------------+
|   1. CREATE BET  |       |  2. ACCEPT BET    |       |  3. RESOLVE BET    |
|                  |       |                   |       |                    |
| Creator defines: | ----> | Opponent accepts  | ----> | Anyone triggers    |
| - Description    |       |   the bet         |       |   resolution       |
| - Resolution URL |       |                   |       |                    |
| - Criteria       |       | Bet status moves  |       | Contract fetches   |
| - Opponent addr  |       |   to "accepted"   |       |   data from URL,   |
|                  |       |                   |       |   LLM evaluates    |
| Names opponent   |       |                   |       |   against criteria |
+------------------+       +-------------------+       +--------------------+
                                                               |
                                                               v
                                                  +-------------------------+
                                                  |  4. VALIDATORS VERIFY   |
                                                  |                         |
                                                  | Multiple validators     |
                                                  |   (different LLMs)      |
                                                  |   independently check   |
                                                  |   the result via        |
                                                  |   Optimistic Democracy  |
                                                  +-------------------------+
                                                               |
                                                               v
                                                  +-------------------------+
                                                  |  5. RESULT RECORDED     |
                                                  |                         |
                                                  | Winner ("creator" or    |
                                                  |   "opponent") is stored |
                                                  |   on-chain.             |
                                                  |                         |
                                                  +-------------------------+

For example, you might create a bet: "The new Dune movie will be well-received by critics", set the resolution URL to Rotten Tomatoes, define your criteria as "well-received means a critic score above 75% and generally positive consensus", and name your friend as the opponent. Your friend accepts the bet. After the movie releases, anyone triggers resolution. The contract fetches the Rotten Tomatoes page, an LLM evaluates the reviews against your criteria, validators verify the judgment, and the winner is recorded on-chain. All transparent, all trustless.

Setting Up Your Environment

Let's get your local development environment ready so you can hit the ground running in Part 2.

Prerequisites

You need two things installed on your machine:

Node.js 18+ -- Download from nodejs.org if you do not have it. Verify with:

node --version
# Should output v18.x.x or higher

A modern browser -- Chrome, Firefox, or Edge. You will use it to access GenLayer Studio.

Install the GenLayer CLI

The GenLayer CLI is a command-line tool that sets up and manages your local GenLayer development environment. Install it globally with npm:

npm install -g genlayer

Initialize Your Local Environment

Once installed, spin up a local GenLayer network with three validators:

genlayer init --numValidators 3 --reset-db

This command pulls the necessary Docker containers, configures three validator nodes (each connected to a different LLM), and sets up a local blockchain instance. It may take a few minutes on the first run.

Open GenLayer Studio

Once initialization completes, open your browser and navigate to:

http://localhost:8080/

Welcome to GenLayer Studio -- your development playground. Take a moment to familiarize yourself with the interface:

Contract Editor (center panel) -- This is where you write your Intelligent Contracts in Python. It has syntax highlighting and is where we will spend most of our time in Part 2.
Accounts Panel (sidebar) -- You will see several pre-funded test accounts. These come loaded with test tokens so you can deploy contracts and send transactions without any real money.
Transaction History (bottom panel) -- Every transaction you submit shows up here, including its status, the validator votes, and the final result. This is invaluable for debugging.

We will use Studio's built-in web editor for Parts 1 and 2 of this series. In Part 3, when we build the frontend, we will switch to a local project repository with a proper development setup.

What's Next

In Part 2, we will write the GenBets Intelligent Contract in Python from scratch -- including the AI-powered resolution logic that reads live web data, prompts an LLM to evaluate subjective criteria, and lets validators reach consensus through the Equivalence Principle. That is where the real magic happens. See you there.