Documentation

Everything about Matchplay.

How a round works, how matches are judged, where the money goes, every contract method, and the Studionet details worth knowing.

Overview

Matchplay is an Intelligent Contract on GenLayer. A host opens a round with a prize and a mission. Between 3 and 8 entrants pay a bond and pitch. Every pair of entries meets exactly once. For each match the contract asks an AI judge to read both entries twice, once in each order, and the network's validators must agree on the result before it is stored. Points decide the payout.

This web app is a thin client. It reads the contract through GenLayer's JavaScript SDK, checks your input against the same rules the contract uses, and sends your signed calls through your own wallet. It holds no keys and no funds.

Where it runs

GenLayer Studionet, chain id 61999, currency GEN. Contract:

Quick start

Take part in a round

  1. Press Connect wallet, pick your wallet, and approve. If the wallet is on another network the app asks it to switch to Studionet (and to add the network first when needed).
  2. Open the Arena and choose a round that is Open.
  3. Fill the entry form: a name, a pitch of 40 to 600 characters and, if the round asks for it, one public evidence link. The form shows what is wrong before you can send.
  4. Confirm. Your wallet attaches exactly the entry bond. Wait for the validators (usually under a minute).
  5. When the round is done, open My account and press Claim.

Host a round

  1. Open Host a round. Write a title and a mission. The mission is the only text the judge measures entries against, so be concrete.
  2. Set the prize (the GEN you attach), the entry bond, how many entries you need, the two time windows and the bar.
  3. The preview shows what one point will be worth. Press Open the round and confirm in your wallet.
  4. Entrants join until the entry window closes, or until you start early once the minimum is reached.

Run the matches

Anyone can press Run the next match on a playing round. Each press judges one match. When all are played (or the playing time ends) anyone can press Finish the round.

No wallet? Try demo mode

Demo mode runs the whole app against a simulated network and a pretend wallet. Nothing real is sent. Use Exit demo in the orange bar to leave.

Wallet & network

How the wallet connection works

Matchplay finds wallets with EIP-6963 (multi injected provider discovery). Every installed wallet announces itself with a name and an icon, and the connect window lists them. You pick one, and from then on every request goes to that wallet only, through the standard EIP-1193 interface. With several wallets installed there is no tug of war over window.ethereum. A wallet that does not announce itself is offered as Browser wallet.

Switching to Studionet

If your wallet is on another chain, an orange bar appears under the header and the network pill says Wrong network. Press Switch network: the app calls wallet_switchEthereumChain and, when the wallet does not know Studionet, wallet_addEthereumChain with these values:

FieldValue
Network nameGenLayer Studio Network
Chain id61999 (0xf22f)
RPC URLhttps://studio.genlayer.com/api
CurrencyGEN (18 decimals)

Any action that sends a transaction checks the network again first and asks for the switch if needed, so a wrong network never reaches the contract.

Disconnecting

The wallet menu (your address in the header) has Disconnect. EIP-1193 has no standard disconnect call, so the app does everything that is possible: it asks the wallet to revoke this site's account permission (wallet_revokePermissions, supported by MetaMask and several others), clears its own session and remembers your choice so the page does not reconnect silently on the next visit. Wallets that ignore the revoke request still end the session here; you can remove the site from the wallet's connected sites list too.

The app also follows the wallet: changing account or network in the wallet updates the page at once.

Key ideas

TermMeaning
RoundOne competition: a mission, a prize, a bond, a bar and two clocks.
HostThe address that opened the round and attached the prize.
EntryA name, a pitch and an optional evidence link, backed by the entry bond. One per address.
BondA deposit paid with the entry. Refunded after the round, unless the entry is struck.
MatchOne pair of entries. Every pair meets once, in a fixed order, so n entries give n×(n−1)÷2 matches.
PointsA match is worth 2: 2 to the winner, 1 each for a tie, 0 when nobody clears the bar.
BarThe fit score (0 to 90) an entry has to reach on its own to earn from a match.
StrikeThe judge found an evidence page that tries to steer it. Final: no more points, bond forfeited.
CreditMoney the contract owes an address. It stays bookkeeping until that address calls claim.

Round lifecycle

StateWhat can happenWho
OpenEntries join or withdraw. The host tops up the prize or removes an entry (bond refunded).entrants, host
start_round: closes entries and fixes the schedule. Needs the minimum number of entries. Allowed when the entry time is over, when the round is full, or by the host at any time.anyone / host
cancel_round: everything goes back. The host any time; anyone once the entry time is over without enough entries.host / anyone
Playingplay_next judges the next match in the fixed order, until all are played or the playing time ends.anyone
finalize_round: after the last match, or once the playing time is over. Matches nobody ran earn nothing.anyone
DoneEvery entry and the host are credited. Winners and the host claim.each address
CancelledThe prize is credited to the host and each bond to its owner.each address

The match order is fixed: (0,1) (0,2) … (1,2) (1,3) … so nobody can pick an easy opponent. schedule_of(n) returns the full order for n entries.

How matches are judged

Two readings, swapped

For each match the judge is asked twice. Reading 1 shows entry A first, then B. Reading 2 shows B first, then A. In each reading the judge rates each entry against the mission with one level from 0 to 4 (stored as a fit of 0, 25, 50, 75 or 100) and names a winner or a tie. An entry's fit is the lower of its two readings.

Deciding the result

SituationResult
Neither entry reaches the barNobody earns (0 points each)
Only one reaches the barThat entry wins, whatever the winner was in the readings. The bar always wins.
Both reach it, same winner in both ordersThat entry wins (2 points)
Both reach it, the order changes the winnerTie (1 point each)

Evidence pages and strikes

If an entry has an evidence link, the contract fetches the page and gives the judge the first 1,500 characters of its visible text. A page shorter than 20 characters counts as unreadable. If the page text tries to steer the judge (for example telling it to ignore the instructions or to rate the entry as perfect), the entry gets a strike: its page is withheld from the judge and a fingerprint of the page is stored. A strike is final. The entry can no longer score, matches it already played are re-scored without it, and its bond goes to the host. If both pages in a match steer the judge, nobody earns and the model is not asked at all. Names and pitches are checked for the same thing when an entry is made, and are refused outright.

Unreadable pages

When a page cannot be read, the match stays pending and can be run again after two minutes. After 3 tries the match is voided: neither entry earns and the round moves on.

Consensus

The leader's result is checked by the other validators, who judge the match again. They compare exactly: the strike flags, unreadable pages, both fits, the winner of each order, the result and the page fingerprints. Only the judge's one-line reasons may differ. A single difference means the validators refuse the result, and the transaction ends as UNDETERMINED with no change to the contract. You can simply run it again (see Studionet quirks).

Money & payouts

matches        = n × (n − 1) ÷ 2
points         = 2 × matches
price of point = pool ÷ points           (integer division, in wei)
payout(entry)  = points(entry) × price + bond          (not struck)
host gets back = pool − Σ points × price + bonds of struck entries

Example. A 1 GEN prize with 5 entries and a 0.05 GEN bond: 10 matches, 20 points, 0.05 GEN per point. An entry that wins all 4 of its matches takes 8 points = 0.4 GEN plus its 0.05 GEN bond. If some matches earn nothing, that GEN returns to the host.

While a round is open the price of a point is an estimate for the entries so far (at least the minimum number). It becomes final when the round starts. top_up raises the prize only while the round is open, so nobody can change the stakes after the matches begin.

Ranking is by points, then decisive wins, then the earlier entry. Struck entries have no rank. All credits are bookkeeping until claim sends them out; the Ledger page proves that paid in = sent out + owed + locked.

Limits & rules

WhatRule
Title3 to 60 characters
Mission30 to 1000 characters
Entry name2 to 40 characters
Pitch40 to 600 characters, at least 20 letters or digits, and no two entries with the same pitch
Evidence linkOne public http(s) link, up to 300 characters, ASCII only. No logins in the link, no private or local hosts, no IP-style hosts, only ports 80/443. The same page cannot back two entries.
Entries3 to 8; the minimum cannot be above the maximum
Entry bondAt least 0.001 GEN; entrants pay exactly the bond
PrizeAt least 0.002 GEN, and enough that one point is worth more than 0 for a full round
WindowsEntry and playing windows: 1 minute to 30 days each
Bar0 to 90
Removal reason3 to 160 characters
Listing pagesAt most 50 rows per call

Text is cleaned the same way everywhere: invisible characters are removed, spacing is collapsed, and angle brackets become parentheses. The app mirrors these rules so that you see an error before any GEN is attached.

Contract API

All amounts are wei (18 decimals) and travel as text in the JSON the views return. The app passes integers as numbers, the entry bond and prize as bigint.

Write methods

payablecreate_round(title, mission, entry_bond, min_entries, max_entries, entry_window, play_window, min_fit, need_evidence) → int

Opens a round. The attached value is the prize. The caller is the host. Returns the new round id (the app finds it with rounds_of).

Refused when: any limit above is broken (messages in Messages). A refused call keeps the attached GEN in the contract.

payabletop_up(round_id)

Host only, while the round is open. Adds the attached value to the prize.

payableenter(round_id, name, pitch, evidence_url) → int

Enter an open round before its entry time ends. The attached value must equal the entry bond exactly. One entry per address; the host cannot enter. Returns the entry index.

writewithdraw_entry(round_id)

The entrant leaves an open round. The bond is credited back.

writeremove_entry(round_id, entrant, reason)

Host only, while open. Turns an entry away; the bond is credited back. reason is 3 to 160 characters.

writestart_round(round_id)

Closes entries and fixes the schedule. Needs the minimum entries. Anyone once the entry time is over or the round is full; the host at any time.

writecancel_round(round_id)

Open rounds only. The host any time; anyone once the entry time is over without enough entries. Credits the prize to the host and each bond to its owner.

writeplay_next(round_id)

Judges the next match of a playing round. Anyone can call it. May end UNDETERMINED (no change, retry at once). After an unreadable evidence page there is a two minute pause for that match.

writefinalize_round(round_id)

Ends a playing round once every match is played or the playing time is over. Credits every entry and the host.

writeclaim()

Sends everything credited to the caller. Refused with "There is nothing to claim." when the credit is zero.

View methods (free to call)

MethodReturns
get_round(round_id)One round with its entries and matches (JSON)
list_rounds(offset, limit)Rounds, newest first, without entries and matches
rounds_of(who, offset, limit)Rounds an address hosts or has entered
get_match(round_id, index)One match with the judge's stored review
credit_of(who)What the address can claim now (wei, text)
schedule_of(entries)Fixed match order for 2 to 8 entries as [a, b] pairs
would_steer(text)true if the text trips the steering check
stats()Counters and money totals
solvency()paid in, sent out, owed, locked, balanced, native balance, in_sync
audit_books()Recomputes the books from every round and credit

Reading from JavaScript

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

const client = createClient({ chain: studionet });
const text = await client.readContract({
  address: "0xdd842644E5fEaba5c4FDB28d97236b5B58C5C69c",
  functionName: "get_round",
  args: [0],
});
const round = JSON.parse(text);

Writing through an EIP-6963 wallet

const writer = createClient({
  chain: studionet,
  account: connectedAddress,
  provider: selectedWallet.provider,   // from the EIP-6963 announcement
});
const hash = await writer.writeContract({
  address, functionName: "enter",
  args: [roundId, name, pitch, url],
  value: entryBond,                    // bigint, exactly the bond
});

Messages & errors

The contract refuses with plain sentences. The app shows the sentence when the receipt carries it.

MessageMeaning
The title needs 3 to 60 characters. / The mission needs 30 to 1000 characters.Text length after cleaning.
The entry bond has to be at least 0.001 GEN.Bond too small or too large.
The round needs 3 to 8 entries, and the minimum cannot be above the maximum.Entry counts.
The entry / playing window has to be between 1 minute and 30 days.Window out of range.
The bar has to be between 0 and 90.Bar out of range.
Attach at least 0.002 GEN as the prize.Prize too small.
The prize is too small for this many matches.One point would be worth nothing.
The round is not open for entries. / The entry time is over. / The round is full.Entering is not possible now.
The host cannot enter their own round. / This address already has an entry in the round.One entry per address; not the host.
Attach exactly the entry bond.Wrong value on enter.
The name or the pitch tries to steer the judge.The steering check matched.
The evidence must be a single public http(s) link. / This round needs a link to evidence.Link missing or not acceptable.
That evidence page already backs another entry. / That pitch is already used by another entry.Duplicates, even spelled differently.
The round does not have enough entries yet. / The entry time is not over and the round is not full.start_round not allowed yet.
Only the host can do that. / Only the host can cancel, unless…Host-only calls.
Matches are still being played. / The round is not being played.finalize_round or play_next in the wrong state.
Wait two minutes before asking again.Pause after an unreadable page.
There is nothing to claim.No credit for the caller.

Studionet quirks

A refused payable call traps the GEN

If create_round, enter or top_up is refused, the GEN you attached stays in the contract's balance, outside its books, and claim cannot return it. The app therefore checks every field against the contract's rules, and runs would_steer on the name and pitch, before it ever asks your wallet to attach value. If you call the contract from your own scripts, do the same.

UNDETERMINED is harmless

If play_next ends as UNDETERMINED, the validators could not agree under the strict comparison. No state changes and you can retry immediately. Only a match whose evidence page was unreadable (tries above 0) has the 120 second pause.

About 500 requests an hour

Studionet rate limits the RPC. The app caches reads, refreshes slowly (and more slowly as the hour fills up), pauses when the tab is hidden, waits out a rate limit and retries reads once. The footer shows how many requests this browser has used in the last hour. Writes are never retried automatically.

The contract's native balance can briefly be below its books after a claim, until the network finalises the transfer. The Ledger page explains which difference is normal and which one means trapped GEN.

This web app

A static site: Vite builds nine plain HTML pages. There is no server and no framework. The only runtime dependencies are genlayer-js (pinned to 1.1.8), viem and three font packages.

frontend/
  index.html rounds.html round.html create.html
  account.html ledger.html docs.html demo.html 404.html
  public/            images, logos, Mochi, demo video
  src/config.js      contract address, chain, links, rule limits
  src/lib/wallet.js  EIP-6963 discovery, connect, disconnect, switch
  src/lib/chain.js   reads, writes, request budget, transaction polling
  src/lib/validate.js  browser port of the contract's checks
  src/lib/mock.js    demo mode: simulated contract + pretend wallet
  src/lib/ui.js      header, banners, dialogs, spinners, 3D helpers
  src/pages/*.js     one script per page

Configuration

The contract address lives in src/config.js. It defaults to 0xdd842644E5fEaba5c4FDB28d97236b5B58C5C69c and can be overridden at build time with VITE_MATCHPLAY_ADDRESS. Explorer link formats are in the same file.

Run it locally

cd frontend
npm install
npm run dev        # http://localhost:5173
npm run build      # static files in dist/

Demo mode

Open any page with ?demo=1. The app swaps its network layer for an in-browser copy of the rules and announces a pretend EIP-6963 wallet that starts on the wrong network, so you can try connecting, switching, entering, hosting, judging and claiming without risk. State lives in your browser's local storage and the orange bar has Reset and Exit buttons.

Deploy

Any static host works. For Cloudflare Pages: connect the repository, set the root directory to frontend, the build command to npm run build and the output directory to dist. All nine pages are listed in vite.config.js under build.rollupOptions.input, so each one is built and none returns 404. The built 404.html is used by Pages as the custom not-found page. Cloudflare serves /rounds.html as /rounds; links inside the app work either way and a round link such as round.html?id=3 keeps its query.

Because the site is fully static, GitHub Pages, Netlify and Vercel work the same way.

Security notes

  • The app never asks for a private key or a seed phrase. Signing happens in your wallet.
  • Everything shown from the contract (titles, pitches, links) is escaped before display, and evidence links open with noopener nofollow.
  • Before a transaction the wallet shows the address and the value. Check that the value is the prize or the bond you expect.
  • Studionet is a test network. GEN there has no market value, and Studionet can be reset by GenLayer.
  • The judge is a language model. The two-order reading, the bar and the strict consensus make results more consistent, not infallible.

FAQ

Why are matches judged twice?

Models can lean toward the first thing they read. Swapping the order and requiring the same winner removes much of that bias.

Can the host pick winners?

No. The host can turn an entry away only while the round is open. After the start the schedule, the judge and the payout rules are fixed.

What if nobody runs the matches?

When the playing time ends anyone can finish the round. Matches nobody ran earn nothing and the prize that was not earned goes back to the host. Bonds are returned.

Why did my wallet not ask me anything?

Check that the wallet is unlocked and look for a pending prompt in its own window. The app waits for your answer.

Why do I see "Wrong network"?

Your wallet is on another chain. Press Switch network in the bar or the pill.

The page says the Studionet rate limit was hit.

Wait a minute. The app pauses by itself and retries.

Glossary

TermMeaning
EIP-6963Standard for pages to discover every installed wallet.
EIP-1193The standard request interface of a wallet provider.
Intelligent ContractA GenLayer contract that can call a language model and read the web, with validators agreeing on the result.
ValidatorA GenLayer node that re-runs the leader's work and votes.
UNDETERMINEDA transaction status: validators did not agree, nothing changed.
WeiThe smallest unit: 1 GEN = 1018 wei.
MochiGenLayer's cat mascot.