Package genlayer.std

gl

Blockchain specific functionality, that won’t work without GenVM and reexports form genlayer.py provided for convenience

genlayer.std.calldata

Proxy to module genlayer.py.calldata

genlayer.std.advanced

Proxy to module genlayer.std.advanced

genlayer.std.wasi

Proxy to module genlayer.std._wasi

genlayer.std.eth

Proxy to module genlayer.py.eth

class genlayer.std.Contract

Bases: object

property address: Address

Returns:

Address of this contract

property balance: u256

class genlayer.std.ContractAt

Bases: GenVMContractProxy

Provides a way to call view methods and send transactions to GenVM contracts

__init__(addr: Address)

address: Address

Address to which this proxy points

property balance: u256

emit(**data: Unpack[TransactionDataKwArgs])

Namespace with write message

Returns:

object supporting .name(*args, **kwargs) that emits a message and returns None

emit_transfer(**data: Unpack[TransactionDataKwArgs])

Method to emit a message that transfers native tokens

view()

Namespace with all view methods

Returns:

object supporting .name(*args, **kwargs) that calls a contract and returns its result (Any) or rises its Rollback

Note

supports name.lazy(*args, **kwargs) call version

class genlayer.std.Lazy

Bases: Generic

Base class to support lazy evaluation

__init__(_eval: Callable[[], T])

get() → T

Performs evaluation if necessary (only ones) and stores the result

Returns:

result of evaluating

Raises:

iff evaluation raised, this outcome is also cached, so subsequent calls will raise same exception

Return type:

T

class genlayer.std.MessageType

Bases: NamedTuple

MessageType(contract_address, sender_address, origin_address, value, is_init, chain_id)

static __new__(_cls, contract_address: Address, sender_address: Address, origin_address: Address, value: u256, is_init: bool, chain_id: u256)

Create new instance of MessageType(contract_address, sender_address, origin_address, value, is_init, chain_id)

chain_id: u256

Current chain ID

contract_address: Address

Address of current Intelligent Contract

is_init: bool

True iff it is a deployment

origin_address: Address

Entire transaction initiator

sender_address: Address

Address of this call initiator

value: u256

Alias for field number 3

genlayer.std.contract_interface(_contr: GenVMContractDeclaration) → Callable[[Address], GenVMContractProxy]

This decorator produces an “interface” for other GenVM contracts. It has no semantical value, but can be used for auto completion and type checks

@gl.contract_interface
class MyContract:
  class View:
    def view_meth(self, i: int) -> int: ...

  class Write:
    def write_meth(self, i: int) -> None: ...

Return type:

Callable[[Address], GenVMContractProxy]

genlayer.std.deploy_contract(*, code: bytes, args: Sequence[Any] = [], kwargs: Mapping[str, Any] = {}, **data: Unpack[DeploymentTransactionDataKwArgs]) → Address | None

Function for deploying new genvm contracts

Parameters:

• code (bytes) – code (i.e. contents of a python file) of the contract

• args (Sequence[Any]) – arguments to be encoded into calldata

• kwargs (Mapping[str, Any]) – keyword arguments to be encoded into calldata

Returns:

address of new contract iff non-zero salt_nonce was provided

Return type:

Address | None

Note

Refer to consensus documentation for exact specification of

• salt_nonce requirements and it’s effect on address

• order of transactions

genlayer.std.eq_principle_prompt_comparative(fn: Callable[[], T], principle: str) → T

Comparative equivalence principle that utilizes NLP for verifying that results are equivalent

Parameters:

• fn (Callable[[], T]) – function that does all the job

• principle (str) – principle with which equivalence will be evaluated in the validator (via performing NLP)

Return type:

T

See genlayer.std.advanced.run_nondet() for description of data transformations

Note

As leader results are encoded as calldata, format() is used for string representation. However, operating on strings by yourself is more safe in general

Note

supports .lazy() version, which will return Lazy

genlayer.std.eq_principle_prompt_non_comparative(fn: Callable[[], str], *, task: str, criteria: str) → str

Non-comparative equivalence principle that must cover most common use cases

Both leader and validator finish their execution via NLP, that is used to perform task on input. Leader just executes this task, but the validator checks if task was performed with integrity. This principle is useful when task is subjective

See run_nondet() for description of data transformations

Note

supports .lazy() version, which will return Lazy

Return type:

str

genlayer.std.eq_principle_strict_eq(fn: Callable[[], T]) → T

Comparative equivalence principle that checks for strict equality

Parameters:

fn (Callable[[], T]) – functions to perform an action

Return type:

T

See genlayer.std.advanced.run_nondet() for description of data transformations

Note

supports .lazy() version, which will return Lazy

genlayer.std.eth_contract(contr: ContractDeclaration) → Callable[[Address], ContractProxy]

Return type:

Callable[[Address], ContractProxy]

genlayer.std.exec_prompt(prompt: str, **config: Unpack[ExecPromptKwArgs]) → str

API to execute a prompt (perform NLP)

Parameters:

• prompt (str) – prompt itself

• **config (ExecPromptKwArgs) – configuration

Return type:

str

Note

supports .lazy() version, which will return Lazy

genlayer.std.get_webpage(url: str, **config: Unpack[GetWebpageKwArgs]) → str

API to get a webpage after rendering it

Parameters:

• url (str) – url of website

• **config (GetWebpageKwArgs) – configuration

Return type:

str

Note

supports .lazy() version, which will return Lazy

genlayer.std.message: MessageType = Ellipsis

Represents fields from a transaction message that was sent

genlayer.std.message_raw: dict = Ellipsis

Raw message as parsed json

genlayer.std.private(f)

Decorator that marks method as private. As all methods are private by default it does nothing.

class genlayer.std.public

Bases: object

static view(f)

Decorator that marks a contract method as a public view

write = <genlayer.std._write object>

Decorator that marks a contract method as a public write. Has .payable

@gl.public.write
def foo(self) -> None: ...

@gl.public.write.payable
def bar(self) -> None: ...

@gl.public.write.min_gas(100).payable
def bar(self) -> None: ...

Return type:

T

genlayer.std.rollback_immediate(reason: str) → NoReturn

Performs an immediate rollback, current VM won’t be able to handle it, stack unwind will not happen

Return type:

NoReturn

genlayer.std.storage_inmem_allocate(t: Type, *init_args, **init_kwargs) → T

Return type:

T

gl.calldata

This module is responsible for working with genvm calldata

Calldata natively supports following types:

1. Primitive types:

   1. python built-in: bool, None, int, str, bytes

   2. Address() type

2. Composite types:

   1. list (and any other collections.abc.Sequence)

   2. dict with str keys (and any other collections.abc.Mapping with str keys)

For full calldata specification see genvm repo

class genlayer.py.calldata.CalldataEncodable

Bases: object

Abstract class to support calldata encoding for custom types

Can be used to simplify code

abstract __to_calldata__() → Encodable

Override this method to return calldata-compatible type

Warning

returning self may lead to an infinite loop or an exception

Return type:

Encodable

genlayer.py.calldata.decode(mem0: ~collections.abc.Buffer, *, memview2bytes: ~typing.Callable[[memoryview], ~typing.Any] = <class 'bytes'>) → Decoded

Decodes calldata encoded bytes into python DSL

Out of composite types it will contain only dict and list

Return type:

Decoded

genlayer.py.calldata.encode(x: EncodableWithDefault, *, default: Callable[[EncodableWithDefault], Encodable] | None = None) → bytes

Encodes python object into calldata bytes

Parameters:

default (Callable[[EncodableWithDefault], Encodable] | None) – function to be applied to each object recursively, it must return object encodable to calldata

Return type:

bytes

Warning

All composite types in the end are coerced to dict and list, so custom type information is not be preserved. Such types include:

1. CalldataEncodable

2. dataclasses

genlayer.py.calldata.to_str(d: Encodable) → str

Transforms calldata DSL into human readable json-like format, should be used for debug purposes only

Return type:

str

gl.advanced

This module provides some “advanced” features that can be used for optimizations

Warning

If you are using something “advanced” you must know what you do

class genlayer.std.advanced.AlreadySerializedResult

Bases: bytes

If contract method returns instance of this class, calldata encoding won’t be performed. Instead stored bytes will be passed as is

static __new__(cls, *args, **kwargs)

Forwards all arguments to bytes

exception genlayer.std.advanced.ContractError

Bases: Exception

Represents “Contract error” result of a contract that is passed to validator function of genlayer.std.run_nondet()

Validating leader output and sandbox invocation are only places where contract can “handle” contract error

__init__(data: str) → None

data: str

class genlayer.std.advanced.ContractReturn

Bases: object

Represents a normal “Return” result of a contract that is passed to validator function of genlayer.std.run_nondet()

__init__(data: Decoded) → None

data: Decoded

genlayer.std.advanced.run_nondet(leader_fn: Callable[[], T], validator_fn: Callable[[ContractReturn | Rollback | ContractError], bool]) → Lazy

Most generic user-friendly api to execute a non-deterministic block

Parameters:

• leader_fn (Callable[[], T]) – function that is executed in the leader

• validator_fn (Callable[[ContractReturn | Rollback | ContractError], bool]) – function that is executed in the validator that also checks leader result

Return type:

Lazy

Uses cloudpickle to pass a “function” to sub VM

Note

If validator_fn produces an error and leader_fn produces an error, executor itself will set result of this block to “agree” and fail entire contract with leader’s error. This is done because not all errors can be caught in code itself (i.e. exit). If this behavior is not desired, just fast return False for leader error result.

Warning

All sub-vm returns go through genlayer.py.calldata encoding

genlayer.std.advanced.sandbox(fn: Callable[[], T]) → Lazy

Runs function in the sandbox

Return type:

Lazy

genlayer.std.advanced.validator_handle_rollbacks_and_errors_default(fn: Callable[[], Decoded], leaders_result: ContractReturn | Rollback | ContractError) → tuple[Decoded, Decoded]

Default function to handle rollbacks and contract errors

Errors and rollbacks are always checked for strict equality, which means that it’s user responsibility to dump least possible text in there

Returns:

ContractReturn data fields as (validator, leader)` iff both results are not errors/rollbacks

Return type:

tuple[Decoded, Decoded]

gl.eth

This module is responsible for interactions with ghost/external contracts

class genlayer.py.eth.ContractDeclaration

Bases: Protocol, Generic

Interface for declaring interfaces of external contracts

View: type[TView]

Write: type[TWrite]

__init__(*args, **kwargs)

class genlayer.py.eth.ContractProxy

Bases: Generic

__init__(address: Address, view_impl: Callable[[ContractProxy], TView], balance_impl: Callable[[ContractProxy], u256], send_impl: Callable[[ContractProxy, TransactionDataKwArgs], TWrite], transfer_impl: Callable[[ContractProxy, TransactionDataKwArgs], None])

address

property balance: u256

emit(**data: Unpack[TransactionDataKwArgs]) → TWrite

Return type:

TWrite

emit_transfer(**data: Unpack[TransactionDataKwArgs]) → None

view() → TView

Return type:

TView

class genlayer.py.eth.InplaceTuple

Bases: object

This class indicates that tuple should be encoded/decoded in-place. Which means that even if it is dynamically sized, it is ignored. It is useful for encoding/decoding arguments and returns

tuple[InplaceTuple, str, u256]

class genlayer.py.eth.MethodEncoder

Bases: object

__init__(name: str, params: tuple[Any, ...], ret: type)

decode_ret(data: Buffer) → Any

Return type:

Any

encode_call(args: tuple[Any, ...]) → bytes

Return type:

bytes

genlayer.py.eth.decode(expected: Type, encoded: Buffer) → T

Return type:

T

genlayer.py.eth.encode(params: Type, args: T) → bytes

Return type:

bytes

genlayer.py.eth.selector_of(name: str, params: Type[tuple[Unpack[T]]]) → bytes

Return type:

bytes

genlayer.py.eth.signature_of(name: str, params: Type[tuple[Unpack[T]]]) → str

calculates signature that is used for making method selector

Return type:

str

genlayer.py.eth.type_name_of(t: type) → str

Return type:

str

gl.wasi

genlayer.std._wasi.call_contract(address: bytes, calldata: bytes, data: str) → _Fd

Return type:

_Fd

genlayer.std._wasi.contract_return(s: bytes) → NoReturn

Return type:

NoReturn

genlayer.std._wasi.deploy_contract(calldata: bytes, code: bytes, data: str) → None

genlayer.std._wasi.eq_principle_prompt(id: int, vars: str) → bool

Return type:

bool

genlayer.std._wasi.eth_call(address: bytes, calldata: bytes) → _Fd

Return type:

_Fd

genlayer.std._wasi.eth_send(address: bytes, calldata: bytes, data: str) → None

genlayer.std._wasi.exec_prompt(config: str, prompt: str) → _FdErroring

Return type:

_FdErroring

genlayer.std._wasi.exec_prompt_id(id: int, vars: str) → _FdErroring

Return type:

_FdErroring

genlayer.std._wasi.get_balance(address: bytes) → int

Return type:

int

genlayer.std._wasi.get_entrypoint() → bytes

Return type:

bytes

genlayer.std._wasi.get_message_data() → str

Return type:

str

genlayer.std._wasi.get_self_balance() → int

Return type:

int

genlayer.std._wasi.get_webpage(config: str, url: str) → _FdErroring

Return type:

_FdErroring

genlayer.std._wasi.post_message(address: bytes, calldata: bytes, data: str) → None

genlayer.std._wasi.rollback(s: str) → NoReturn

Return type:

NoReturn

genlayer.std._wasi.run_nondet(leader_data: bytes, validator_data: bytes) → _Fd

Return type:

_Fd

genlayer.std._wasi.sandbox(data: bytes) → _Fd

Return type:

_Fd

genlayer.std._wasi.storage_read(slot: bytes, off: int, len: int) → bytes

Return type:

bytes

genlayer.std._wasi.storage_write(slot: bytes, off: int, what: Buffer) → bytes

Return type:

bytes