Skip to content
This repository was archived by the owner on Jul 22, 2026. It is now read-only.
This repository was archived by the owner on Jul 22, 2026. It is now read-only.

docs: chain.py Event docstring shows gl.Event, which does not resolve at runtime #327

Open

Description

@dohernandez

Problem

The docstring/examples on runners/genlayer-py-std/src/genlayer/chain.py (Event class, ~lines 103/107) show contracts subclassing gl.Event:

class TransferOccurredEvent(gl.Event):

But Event is exported only under genlayer.chain:

  • top-level genlayer/__init__.py does from .types import *, and genlayer/types __all__ has no Event;
  • the top-level __all__ lists submodules/aliases, not Event;
  • the module-level __getattr__ is a lazy module loader only — __getattr__('Event') raises.

So a contract following the docstring crashes at module load:

File "/contract.py", line 8, in <module>
    class EmitterDeployed(gl.Event):
File "/py/libs/genlayer/__init__.py", line 186, in __getattr__
    raise AttributeError(f"module 'genlayer' has no attribute '{name}'")
AttributeError: module 'genlayer' has no attribute 'Event'

Verified against the py-lib-genlayer-std runner shipped in genvm-manager v0.6.0-rc1 (executor v0.3.0-rc7, runner map default py-genlayer:9b8kjyda…) by executing the same contract in both forms: gl.Event → VmError + empty emissions; gl.chain.Event → Return + the expected emission.

Why it bit hard downstream

The crashed deploy is still accepted by consensus (accepted-with-VmError), so an e2e that waits on transaction status sees a "successful" deploy that emitted nothing — the symptom ("zero events, everything green") implicated the executor/runner/manager/node pipeline before the docstring. Cost us a full cross-repo debugging cycle on the node side.

Fix options

  1. Minimal: correct the docstring/examples to gl.chain.Event (and audit other docs for gl.Event, e.g. the website spec examples).
  2. Nicer: additionally export Event at top level (add to the lazy map or re-export), making the current docstring true — the name is short and event definitions are common enough to warrant it.

Happy to PR option 1 if you prefer it.

Activity

  1. dohernandez commented on Jul 21, 2026

    @dohernandez
    MemberAuthor

    Adopted (genvm session). Decision on the two options:

    Option 1 (docstring fix, #328) is the right fix. Option 2 (restore a top-level gl.Event alias) is rejected.

    Rationale: the v0.2.x → v0.3 rename was deliberate and systematic — the whole flat namespace moved into submodules (gl.Contract → gl.contract.Contract, gl.deploy_contract → gl.contract.deploy, gl.Event → gl.chain.Event, …; see the migration table in doc/website/src/python-sdk/changelog-notes/v0.3.rst). Restoring a back-alias for exactly one of those names would erode that consistency (why Event top-level but not Contract?), reintroduce two spellings of the same API for docs/examples/goldens to drift between, and create a third state across the v0.3 rc line (rc0–rc7 already shipped the strict namespace). The compatibility story for v0.2.x contracts is the migration table, not selective aliases.

    Audit result for "other docs showing gl.Event": a full-repo grep finds only three sites — chain.py (fixed by #328), the v0.3 changelog rows (labeled v0.2.x "before" examples, correctly left untouched), and the tests/cases/stable/py/events/post_event.py fixture (already gl.chain.Event). Nothing else to fix; #328 is complete as-is.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions