Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: add filtering capability to event stream endpoints #186

Open
seanmcgary opened this issue Jan 14, 2025 · 0 comments · May be fixed by #212
Open

feat: add filtering capability to event stream endpoints #186

seanmcgary opened this issue Jan 14, 2025 · 0 comments · May be fixed by #212
Assignees
@seanmcgary
Labels
api enhancement New feature or request
Milestone
v2.2.0

Comments

@seanmcgary
Copy link
Member

Overview

Add support for flexible filtering of event streams using a JSON-based query syntax. This will allow clients to filter events based on field values and complex logical conditions.

Motivation

Currently, clients must consume and filter all events on their side. Adding server-side filtering will:

  • Reduce bandwidth usage by only sending relevant events
  • Simplify client implementations
  • Enable more efficient data access patterns
  • Support complex query scenarios without requiring client-side implementation

Proposed Solution

Add an optional filter field to the stream request messages that accepts a JSON object representing filter conditions. The filter syntax will support:

  • Field-level filtering on any filterable struct fields
  • Logical operators (AND/OR)
  • Comparison operators (=, !=, >, <, >=, <=, contains)
  • Nested conditions

Filter Syntax Specification

Grammar (EBNF)

Filter ::= Condition | AndFilter | OrFilter

AndFilter ::= {
    "type": "and",
    "filters": [ Filter {"," Filter} ]
}

OrFilter ::= {
    "type": "or",
    "filters": [ Filter {"," Filter} ]
}

Condition ::= {
    "type": "condition",
    "field": string,
    "operator": Operator,
    "value": Value,
    "entityType": EntityType
}

Operator ::= "eq" | "ne" | "gt" | "lt" | "gte" | "lte" | "contains" | "notContains"

Value ::= string | uint64

EntityType ::= "block" | "transaction" | "transactionLog"

Examples

Simple condition

{
    "type": "condition",
    "field": "BlockNumber",
    "operator": "gt",
    "value": 1000,
    "entityType": "block"
}

AND condition

{
    "type": "and",
    "filters": [
        {
            "type": "condition",
            "field": "BlockNumber",
            "operator": "gt",
            "value": 1000,
            "entityType": "block"
        },
        {
            "type": "condition",
            "field": "Hash",
            "operator": "eq",
            "value": "0x123",
            "entityType": "block"
        }
    ]
}

Complex nested condition

{
  "type": "and",
  "filters": [
    {
      "type": "condition",
      "field": "BlockNumber",
      "operator": "gt",
      "value": 1000,
      "entityType": "block"
    },
    {
      "type": "or",
      "filters": [
        {
          "type": "condition",
          "field": "FromAddress",
          "operator": "eq",
          "value": "0x123",
          "entityType": "transaction"
        },
        {
          "type": "condition",
          "field": "ToAddress",
          "operator": "eq",
          "value": "0x456",
          "entityType": "transaction"
        }
      ]
    }
  ]
}

Protobuf changes

This feature adds a filter field to the existing protobuf spec:

syntax = "proto3";

import "google/protobuf/struct.proto";

message StreamEigenStateChangesRequest {
  google.protobuf.Value filter = 1;  // new JSON filter object
}

message StreamIndexedBlocksRequest {
  bool include_state_changes = 1;
  google.protobuf.Value filter = 2;  // new JSON filter object
}
@seanmcgary seanmcgary added enhancement New feature or request api labels Jan 14, 2025
@seanmcgary seanmcgary self-assigned this Jan 14, 2025
@seanmcgary seanmcgary added this to the v1.1.0 milestone Jan 14, 2025
@seanmcgary seanmcgary changed the title Add filtering capability to event stream endpoints feat: add filtering capability to event stream endpoints Jan 14, 2025
@seanmcgary seanmcgary modified the milestones: v1.1.0, v1.2.0 Jan 15, 2025
@seanmcgary seanmcgary modified the milestones: v1.2.0, v2.1.0, v2.2.0 Jan 27, 2025
@seanmcgary seanmcgary linked a pull request Jan 30, 2025 that will close this issue
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@seanmcgary seanmcgary

Labels
api enhancement New feature or request
Projects
None yet
Milestone
v2.2.0
Development

Successfully merging a pull request may close this issue.

feat: filterable event streaming Layr-Labs/sidecar
1 participant
@seanmcgary