feat: implement getEvents#38
Open
RaoulSchaffranek wants to merge 3 commits into
Open
Conversation
Cover the getEvents surface from the official OpenRPC spec: request validation (startLedger/cursor rules, filter and topic limits, xdrFormat), the result shape (events array, latestLedger as a JSON number, cursor string), event objects for a contract event published via the contract_event host function (TOID-style id, base64 SCVal topics/value, ISO-8601 close time), filtering by contract id, type and topics, and cursor-based pagination. The emitting contract (data/wasm/events.wat) builds its topics vector with vec_new/vec_push_back and runs successfully through the semantics today; the tests fail only because getEvents is not implemented yet.
The upstream soroban semantics implement the contract_event host function as a no-op, so node.md now shadows it: the interception rule resolves the topics vector and data value from the host objects and stages one JSON record per event in events_staged.jsonl, alongside how the tracer appends trace records. After a successful sendTransaction the server converts the staged records into one finished events/events_<ledger>.json per ledger (base64 SCVal XDR, strkey contract ids, and TOID-style event ids are XDR work K cannot do). getEvents itself is dispatched in K: it validates the requested window against the chain tip, scans the per-ledger event files, applies the spec's filters (type, contractIds, topics with * and ** wildcards), and paginates with TOID-style cursors. Structural parameter validation (filter and segment counts, cursor format, xdrFormat - 'json' is rejected as unsupported) lives in the server next to the existing param checks. System events are never emitted, and events whose values have no staging representation (maps, errors, 256-bit ints) are dropped with a warning instead of fabricating XDR. Covered by the getEvents integration tests; the full test_server.py suite still passes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the
getEventsRPC method per the official stellar-rpc OpenRPC spec.What changed
src/komet_node/kdist/node.md): the upstream soroban semantics implement thecontract_eventhost function ("x"/"1") as a no-op that drops topics and data. A priority(40) rule now shadows it: it resolves the topics vector and data value from the host objects and stages one JSON record per event inevents_staged.jsonl, mirroring how the tracer appends trace records. After a successfulsendTransactionthe server converts the staged records into oneevents/events_<ledger>.jsonper ledger in the spec's Event shape (_finalize_events— base64 SCVal XDR, strkey contract ids, and TOID-style event ids are XDR work K cannot do).node.md): validates the requested window against the chain tip (startLedgerbeyond the tip is-32600with the same message real stellar-rpc uses), scans the per-ledger event files over the[startLedger, endLedger)window, applies the spec's filters (type,contractIds,topicswith*and trailing**matchers), and paginates with TOID-style cursors. Adds#respondErroras the error-shaped counterpart of#respond.server.py): structural checks live next to the existing param validation — filter/topic-segment counts, cursor format,limit1–10000,xdrFormat(jsonrejected as unsupported, consistent with the repo's policy), cursor exclusive withstartLedger/endLedger.scval_from_json(scval.py): inverse ofscval_to_jsonfor turning the staged K-side ScVal JSON intostellar_sdkXDR values.server.md,architecture.md,node-semantics.md,notes.md(including documented limitations: nosystemevents — the semantics have no source of them; events with values that have no staging representation are dropped with a warning; a topic filter of just["**"]is rejected; a degenerate window returns an empty result).Why
getEventsis part of the required stellar-rpc surface and was missing entirely; dapp tooling uses it to ingest contract events.latestLedgerandledgerare JSON numbers,topic/valueare base64 SCVal XDR, and event ids follow the SEP-35 TOID format, matching real stellar-rpc serialization.Testing
src/tests/integration/test_get_events.py(9 tests) with a dedicatedevents.watcontract that publishes an event viacontract_event: request validation, empty-window shape, the exact Event shape (independently computed XDR, TOID id, strkey contract id, ISO-8601 close time),endLedgerexclusivity, filtering by contract id / type / topics, and cursor pagination.test_server.pysuite passes (26 tests, no regressions);make checkis clean apart from the two mypy findings already present onmain.**topic matchers, cursor+endLedgerrejection, limit bounds, degenerate windows, and resuming a persisted io-dir.