Skip to content

Add support for flexible topics length matching using wildcard in getEvents#419

Merged
urvisavla merged 8 commits intostellar:protocol-23from
urvisavla:getevents-filter
May 20, 2025
Merged

Add support for flexible topics length matching using wildcard in getEvents#419
urvisavla merged 8 commits intostellar:protocol-23from
urvisavla:getevents-filter

Conversation

@urvisavla
Copy link
Contributor

@urvisavla urvisavla commented Apr 28, 2025

What

A new wildcard "**" is introduced in the getEvents RPC endpoint for flexible topic length matching of zero or more topics.

This eliminates the need for manual padding in filters. For eg, previously, to match events where the first topic is "X" followed by any number of subsequent topics, you'd need to specify multiple filters like ["X"], ["X", "*"], ["X", "*", "*"] and so on. The new "**" wildcard simplifies this to a single filter like ["X", "**"].

Rules for the new wildcard

  1. "**" wildcard can only appear as the last segment in a filter
    Invalid: ["X", "**", "*"]
    Valid: ["X", "*", "**"] ✅ - matches events with at least two topics, where the first topic is "X".

  2. The existing limit of max of 4 filter segments per filter is unchanged. The "" wildcard is exempt from this count.
    Invalid ["A","B","C","D","*"] ❌
    Valid: ["A","B","C","D","
    "] ✅

Why

Fixes #358

Known limitations

@urvisavla urvisavla changed the title Getevents filter Add support for flexible topics length matching using wildcard in getEvents Apr 29, 2025
@urvisavla urvisavla marked this pull request as ready for review May 1, 2025 17:08
@leighmcculloch
Copy link
Member

2. At least one segment is still required (existing behavior)
Filters must contain at least one non-** segment.
Invalid: ["**"]
Valid: ["*", "**"] ✅ - matches events with one or more topics.

This seems like an unnecessary restriction given that you can get ["**"] functionality by omitting the topic filter. Could we support this case so that the field works consistently for all positions it can be specified in?

@leighmcculloch
Copy link
Member

leighmcculloch commented May 1, 2025

3. The existing limit of max of 4 filter segments remains the same. The "**" wildcard does not count toward this 4 segment limit.

Does this mean that ["*", "*", "*", "**"] won't match an event that has 5 topics?

Or does ["*", "*", "*", "*"] already match events with 4+ topics? If so, that seems like a bug / inconsistency. 🤔

@urvisavla
Copy link
Contributor Author

Does this mean that ["*", "*", "*", "**"] won't match an event that has 5 topics?

No, it will match any event that >= 3 topics.

Or does ["*", "*", "*", "*"] already match events with 4+ topics?

No, it does not.

  1. The existing limit of max of 4 filter segments remains the same. The "**" wildcard does not count toward this 4 segment limit.

By this I meant that, the existing limit of max of 4 filter segments per filter is unchanged. The "**" wildcard is exempt from this count. so ["A","B","C","D","**"] is a valid filter where as ["A","B","C","D","*"] is not.

Also, per the docs the max limit for filter segments is 5 while the code currently enforces a limit of 4. So either the docs are wrong or it's been implemented incorrectly.

@urvisavla
Copy link
Contributor Author

  1. At least one segment is still required (existing behavior)
    Filters must contain at least one non-** segment.
    Invalid: ["**"]
    Valid: ["*", "**"] ✅ - matches events with one or more topics.

This seems like an unnecessary restriction given that you can get ["**"] functionality by omitting the topic filter. Could we support this case so that the field works consistently for all positions it can be specified in?

yes, we can do that for the sake of consistency but using [**] is effectively the same as no filter at all.

Copy link
Contributor

@Shaptic Shaptic left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something is wonky with the commit history here but otherwise this LGTM! I'm surprised there were no query changes necessary but I guess the fact that it's an OR clause for topic filters helps!

@urvisavla
Copy link
Contributor Author

Something is wonky with the commit history here but otherwise this LGTM!

Yikes! Fixed it.

@urvisavla urvisavla merged commit 8dc968b into stellar:protocol-23 May 20, 2025
21 of 27 checks passed
@urvisavla urvisavla deleted the getevents-filter branch May 20, 2025 03:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants