Code Snippets
This page collects short, complete contracts for patterns that come up in almost every GenLayer project. Each snippet is followed by a line-by-line explanation of what it does and why.
| Snippet | What it shows |
|---|---|
| Factory Pattern | Deploying child contracts from a parent contract with gl.deploy_contract() |
| Pass Web Content to an LLM | Fetching a page with gl.nondet.web.get() and asking an LLM about it |
| Read from Another Contract | Calling another contract's view methods with .view() |
| Write to Another Contract | Sending a write call to another contract with .emit() |
For the reference behind these snippets, see Interacting with Intelligent Contracts, Web Access, Calling LLMs and the Equivalence Principle.
Factory Pattern
A factory is a contract that deploys other contracts. Use it when you need many instances of the same contract, for example one escrow per deal or one market per question, and want a single on-chain registry of every instance.
# { "Depends": "py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" }
from genlayer import *
CHILD_CODE = """
# { "Depends": "py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" }
from genlayer import *
class Market(gl.Contract):
question: str
owner: Address
def __init__(self, question: str, owner: str):
self.question = question
self.owner = Address(owner)
@gl.public.view
def get_question(self) -> str:
return self.question
"""
class MarketFactory(gl.Contract):
markets: DynArray[Address]
def __init__(self):
pass
@gl.public.write
def create_market(self, question: str) -> None:
child_address = gl.deploy_contract(
code=CHILD_CODE.encode("utf-8"),
args=[question, gl.message.sender_address.as_hex],
salt_nonce=u256(len(self.markets) + 1),
on="accepted",
)
self.markets.append(child_address)
@gl.public.view
def get_markets(self) -> list[str]:
return [address.as_hex for address in self.markets]How it works
CHILD_CODE: the source of the contract the factory deploys. It is a regular contract, including its ownDependsheader, stored as a string. You can also read it from a file bundled with the factory, or accept it as a constructor argument and keep it in storage.markets: DynArray[Address]: the factory's registry. Every deployed child address is appended here so clients can discover all instances by callingget_markets().gl.deploy_contract(...)deploys a new contract:codeis the child source asbytes, hence.encode("utf-8").argsare passed to the child's__init__. Here the caller ofcreate_marketbecomes the market owner.gl.message.sender_addressis the account that called the factory, not the factory itself.salt_noncemakes the deployment deterministic: the child address is derived from the factory address and the salt, andgl.deploy_contractreturns it immediately. Each salt can be used only once per factory, so the snippet derives it from the number of markets already created. The value must not be0; with0the address is assigned by consensus andgl.deploy_contractreturnsNone.on="accepted"deploys the child as soon as the factory transaction is accepted. Useon="finalized"(the default) if the child must not exist until the factory transaction can no longer be appealed.
- Deployment is asynchronous: the child is created in a separate transaction after
create_marketcompletes, so you cannot call the child in the same transaction that deploys it.
Deployed children are immutable. To change their logic, deploy new children with updated code from the factory. See Upgradability if a single instance must be upgradable.
Pass Web Content to an LLM
The most common Intelligent Contract pattern: fetch a web page, give its content to an LLM, and store the LLM's decision on-chain. Validators must agree on the result, so the decision is wrapped in a non-deterministic block with a validator function.
# { "Depends": "py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" }
from genlayer import *
LABELS = ("finance", "sports", "technology", "other")
class PageClassifier(gl.Contract):
labels: TreeMap[str, str]
def __init__(self):
pass
@gl.public.write
def classify(self, url: str) -> None:
def leader_fn() -> str:
page = gl.nondet.web.get(url).body.decode("utf-8")
prompt = f"""
Read the web page below and classify its main topic.
Answer with exactly one of: {", ".join(LABELS)}.
Page content:
{page[:5000]}
Respond only with JSON: {{"label": "<one of the labels>"}}
"""
result = gl.nondet.exec_prompt(prompt, response_format="json")
label = result.get("label") if isinstance(result, dict) else None
if label not in LABELS:
raise gl.vm.UserError(f"LLM returned an invalid label: {label!r}")
return label
def validator_fn(leader_result) -> bool:
if not isinstance(leader_result, gl.vm.Return):
return False
if leader_result.calldata not in LABELS:
return False
try:
return leader_result.calldata == leader_fn()
except gl.vm.UserError:
return False
self.labels[url] = gl.vm.run_nondet_unsafe(leader_fn, validator_fn)
@gl.public.view
def get_label(self, url: str) -> str:
return self.labels.get(url, "")How it works
gl.nondet.web.get(url)fetches the page. The responsebodyisbytes, so it is decoded to text before it goes into the prompt. Usegl.nondet.web.render(url, mode="text")instead for pages that need a browser to run JavaScript.page[:5000]truncates the content. Web pages can be large, and a shorter prompt is cheaper and keeps the LLM focused. Pick a limit that fits your use case.gl.nondet.exec_prompt(prompt, response_format="json")runs the prompt and returns the parsed JSON as adict, so there is no manualjson.loads()on the LLM output.- The label is checked against
LABELS: asking for one of four labels in the prompt does not guarantee the LLM complies. The leader raisesgl.vm.UserErrorif the response is not adictor itslabelis not in the allowed set, so an off-list answer such as"hacked"is never returned. - The leader returns only the label, not the whole page or the LLM's wording. Returning a small, well-defined value is what makes consensus possible: two validators can easily agree on
"sports", but never on two paragraphs of free text. validator_fnruns on every validator. It rejects the leader's result if the leader failed (leader_resultis not agl.vm.Return) or returned a label outsideLABELS. Otherwise it fetches the page, asks the LLM itself and agrees only if it gets the same valid label. Checking the leader's value too means that a faulty or malicious leader cannot get an off-list label accepted, even if a validator's LLM happens to give the same answer.gl.vm.run_nondet_unsafe(leader_fn, validator_fn)ties the two together and returns the agreed label, which is then written to storage. Storage writes happen outside the non-deterministic functions.
Web content is untrusted input. A page can contain text that tries to override your instructions. Constrain the output to a fixed set of values, as above, and read Prompt Injection before using this pattern with user-supplied URLs.
If the LLM output is free text and two validators cannot be expected to produce the same value, see non-comparative validation and the GitHub Profile Summary example.
Read from Another Contract
A contract can call the view methods of any other Intelligent Contract and use the returned value in the same transaction.
# { "Depends": "py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" }
from genlayer import *
@gl.contract_interface
class Token:
class View:
def get_balance_of(self, owner: str) -> int: ...
class Write:
pass
class BalanceReader(gl.Contract):
token: Address
last_balance: u256
def __init__(self, token: str):
self.token = Address(token)
self.last_balance = u256(0)
@gl.public.write
def record_balance(self, owner: str) -> None:
balance = Token(self.token).view().get_balance_of(owner)
self.last_balance = u256(balance)
@gl.public.view
def get_balance(self, owner: str) -> int:
return gl.get_contract_at(self.token).view().get_balance_of(owner)How it works
@gl.contract_interfacedescribes the methods of the other contract. Methods underViewcan be called with.view(), methods underWritewith.emit(). The interface only gives you type checking and IDE autocompletion; the method bodies are....Token(self.token)creates a typed reference to the contract at that address.gl.get_contract_at(self.token), used inget_balance, is the untyped alternative. It needs no interface and lets you call any method by name, but without type checking. Both produce the same calls at runtime..view().get_balance_of(owner)calls the view method synchronously and returns its result immediately. The call cannot modify the other contract's state.- Reads work from both write and view methods:
record_balancestores the value it read, whileget_balancesimply passes it through. - Arguments and return values must be types that can be encoded as calldata, such as
int,str,bool,bytes,Address, lists and dicts.
Write to Another Contract
A contract cannot change another contract's state directly. Instead, it emits a message: a write call that is executed as a separate transaction after the current one.
# { "Depends": "py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" }
from genlayer import *
@gl.contract_interface
class Counter:
class View:
def get_count(self) -> int: ...
class Write:
def increment(self, amount: int) -> None: ...
class CounterCaller(gl.Contract):
counter: Address
def __init__(self, counter: str):
self.counter = Address(counter)
@gl.public.write
def bump(self, amount: int) -> None:
Counter(self.counter).emit(on="finalized").increment(amount)
@gl.public.write
def bump_untyped(self, amount: int) -> None:
gl.get_contract_at(self.counter).emit(on="accepted").increment(amount)How it works
.emit(...)returns a proxy for the target's write methods. Callingincrement(amount)on it does not runincrementnow: it queues a message that runsincrementon theCountercontract in a new transaction once the current transaction is accepted or finalized.- Nothing is returned: because the call runs later, you cannot use its result in
bump. If you need a value back, read it later with.view(), or have the target contract emit a message back to the caller. on="finalized"(the default) sends the message only after the current transaction can no longer be appealed. This is the safe choice.on="accepted"sends the message as soon as the transaction is accepted, which is faster. If the transaction is then appealed and re-executed, the message can be sent again, so the receiving method must tolerate duplicate calls. See Accepted vs Finalized.- Sending value:
emit(value=u256(100))also transfers GEN with the call. The receiving method must be marked@gl.public.write.payable. See Value Transfers. - Sender: inside
increment,gl.message.sender_addressis the address ofCounterCaller, not the account that calledbump.
To call a contract on the EVM chain instead of another Intelligent Contract, use @gl.evm.contract_interface. See Interacting with EVM Contracts.