feat: add filtering capability to event stream endpoints #186
Description
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
}