Skip to content

Commit 9272d31

Browse files
seidroid[bot]kollegianclaude
authored
Backport release/v6.8: EvmRpc: add admission checks for eth_getFilterLogs and eth_getFilterChanges (#4705)
Backport of #4701 to `release/v6.8`. Co-authored-by: Yasin <64729564+kollegian@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 2c9eeff commit 9272d31

8 files changed

Lines changed: 533 additions & 55 deletions

File tree

‎evmrpc/AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ EVM RPCs prefixed by `eth_` and `debug_` on Sei generally follows [Ethereum's sp
4242
- `eth_newPendingTransactionFilter`
4343
- `eth_syncing`
4444
- `eth_getProof` — deprecated rather than permanently incompatible; the message directs callers who need proofs to the Sei team.
45-
- **Log filters poll from a cursor.** `eth_newFilter` fixes where its polls start, once: a numeric `fromBlock` (or `earliest`, which is block 0) as given, otherwise the block after the head at creation; a numeric `toBlock` below that start is rejected. Each `eth_getFilterChanges` scans from that cursor to the head, or to a numeric `toBlock` below it; a tag `toBlock` such as `latest` follows the head and never ends the filter. A numeric `fromBlock` above 0 that is below the earliest available block is rejected, while a `fromBlock` of 0 polls from that block. When pruning passes the cursor of a filter, its next poll fails with an error naming the pruned blocks, and the filter continues from the earliest block. A poll covers at most `max_blocks_for_log` blocks, and fewer when its logs exceed the log caps; later polls return the rest. A block whose logs alone exceed the caps fails the poll that reaches it with an error naming the block, and the filter or subscription continues after it. Unlike geth, a numeric `fromBlock` in the past makes the first poll return that history. `eth_getFilterLogs` resolves tags when called and never moves the cursor. `eth_subscribe("logs")` polls through the same cursor logic, and treats a `fromBlock` of 0 with a tag `toBlock`, which ethclient sends for an open-ended query, as an omitted `fromBlock`. A failed subscription poll notifies `{"error": message}` in place of logs, adding the skipped block's `blockNumber` when the subscription continues past an oversized block; any other failure, pruned blocks included, ends the subscription.
45+
- **Log filters poll from a cursor.** `eth_newFilter` fixes where its polls start, once: a numeric `fromBlock` (or `earliest`, which is block 0) as given, otherwise the block after the head at creation; a numeric `toBlock` below that start is rejected. Each `eth_getFilterChanges` scans from that cursor to the head, or to a numeric `toBlock` below it; a tag `toBlock` such as `latest` follows the head and never ends the filter. A numeric `fromBlock` above 0 that is below the earliest available block is rejected, while a `fromBlock` of 0 polls from that block. When pruning passes the cursor of a filter, its next poll fails with an error naming the pruned blocks, and the filter continues from the earliest block. A poll covers at most `max_blocks_for_log` blocks, and fewer when its logs exceed the log caps; later polls return the rest. A block whose logs alone exceed the caps fails the poll that reaches it with an error naming the block, and the filter or subscription continues after it. Unlike geth, a numeric `fromBlock` in the past makes the first poll return that history. `eth_getFilterLogs` resolves tags when called and never moves the cursor. `eth_getLogs`, `eth_getFilterLogs` and each `eth_getFilterChanges` poll pass the same admission before reading anything: `eth_getLogs` and `eth_getFilterLogs` are refused for a range over `max_blocks_for_log`, which a poll never covers; a range over 100 blocks takes a token from one large-query rate limit shared by all three, and without one `eth_getLogs` and `eth_getFilterLogs` are refused while a poll scans only the next 100 blocks, so a filter that has fallen behind keeps advancing and catches up as long as it is polled more often than every 100 blocks of chain time (a slower poller falls further behind, and a cut poll looks like any other on the wire); and any read is refused while the worker queue or the DB read semaphore is 80% used, as seen when it arrives, so a burst of concurrent reads can pass together and only the worker queue's capacity bounds it. The rate and load refusals carry code `-32005` (limit exceeded, retry later). A refused poll leaves the cursor where it was, so the next poll retries the same blocks. Subscription polls are not admitted. `eth_subscribe("logs")` polls through the same cursor logic, and treats a `fromBlock` of 0 with a tag `toBlock`, which ethclient sends for an open-ended query, as an omitted `fromBlock`. A failed subscription poll notifies `{"error": message}` in place of logs, adding the skipped block's `blockNumber` when the subscription continues past an oversized block; any other failure, pruned blocks included, ends the subscription.
4646
- **Block filters.** Under Autobahn, `eth_newBlockFilter` collects hashes from the `BlockHeaderNotifier`, and a filter holding `max_block_filter_hashes` unpolled hashes is removed. Otherwise there is no notifier, and the filter polls the CometBFT block store from a cursor that starts at the block after the head at creation, so no poll returns a block from before the filter existed. Each `eth_getFilterChanges` covers at most `max_block_filter_hashes` heights from the cursor up to the head and returns their hashes oldest first; later polls cover the rest. A block store read failure leaves the cursor where it was, so the next poll retries the same heights. When pruning passes the cursor, before or during a poll, that poll fails with a `-32000` error naming the pruned blocks, and the filter continues from the earliest block. Concurrent polls of one filter may return the same hashes. `eth_getFilterLogs` rejects a block filter as not existing, as geth does.
4747

4848
## `sei_` prefixed endpoints

‎evmrpc/export_test.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ func (f *LogFetcher) PollLogsForTest(
127127
crit filters.FilterCriteria,
128128
cursor int64,
129129
) ([]*ethtypes.Log, int64, error) {
130-
return f.pollLogs(ctx, crit, cursor)
130+
return f.pollLogs(ctx, crit, cursor, nil)
131131
}
132132

133133
// NewLogsSubscriptionAPIForTest returns a SubscriptionAPI that serves eth_subscribe("logs") from

‎evmrpc/filter.go‎

Lines changed: 153 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -295,6 +295,7 @@ type FilterAPI struct {
295295
shutdownCtx context.Context
296296
shutdownCancel context.CancelFunc
297297
globalRPSLimiter *rate.Limiter
298+
poolMetrics *WorkerPoolMetrics // load admission sheds against
298299
blockHeaderNotifier *BlockHeaderNotifier
299300
}
300301

@@ -369,6 +370,7 @@ func NewFilterAPI(
369370
shutdownCtx: shutdownCtx,
370371
shutdownCancel: shutdownCancel,
371372
globalRPSLimiter: rate.NewLimiter(rate.Limit(GlobalRPSLimit), GlobalRPSLimit),
373+
poolMetrics: GetGlobalMetrics(),
372374
blockHeaderNotifier: blockHeaderNotifier,
373375
}
374376
if blockHeaderNotifier != nil {
@@ -637,7 +639,7 @@ func (a *FilterAPI) GetFilterChanges(
637639
}
638640
return hashes, nil
639641
case LogsSubscription:
640-
logs, cursor, err := a.logFetcher.pollLogs(ctx, filter.fc, filter.logCursor)
642+
logs, cursor, err := a.logFetcher.pollLogs(ctx, filter.fc, filter.logCursor, a.admitPoll)
641643
a.advanceFilterCursor(filterID, cursor)
642644
if err != nil {
643645
return nil, err
@@ -674,8 +676,17 @@ func (a *FilterAPI) GetFilterLogs(
674676
// Update access time
675677
a.updateFilterAccess(filterID)
676678

679+
// Each call re-reads the filter's whole range, so it is admitted like an eth_getLogs query.
680+
begin, end, err := a.logFetcher.queryBounds(ctx, filter.fc)
681+
if err != nil {
682+
return nil, err
683+
}
684+
if err := a.admitLogQuery(end - begin + 1); err != nil {
685+
return nil, err
686+
}
687+
677688
// Read-only history query: the eth_getFilterChanges cursor is left untouched.
678-
logs, _, err := a.logFetcher.GetLogsByFilters(ctx, filter.fc)
689+
logs, _, err := a.logFetcher.logsInRange(ctx, filter.fc, begin, end)
679690
if err != nil {
680691
return nil, err
681692
}
@@ -691,16 +702,7 @@ func (a *FilterAPI) GetLogs(ctx context.Context, crit filters.FilterCriteria) (r
691702
recordMetricsWithError(ctx, fmt.Sprintf("%s_getLogs", a.namespace), a.connectionType, startTime, err, recover())
692703
}()
693704

694-
latest, err := a.logFetcher.latestHeight(ctx)
695-
if err != nil {
696-
return nil, err
697-
}
698-
earliest, err := a.logFetcher.earliestHeight(ctx)
699-
if err != nil {
700-
earliest = 0
701-
}
702-
703-
begin, end, err := ComputeBlockBounds(latest, earliest, crit)
705+
begin, end, err := a.logFetcher.queryBounds(ctx, crit)
704706
if err != nil {
705707
return nil, err
706708
}
@@ -712,49 +714,107 @@ func (a *FilterAPI) GetLogs(ctx context.Context, crit filters.FilterCriteria) (r
712714
GetGlobalMetrics().RecordGetLogsRequest(blockRange, time.Since(startTime), startTime, err)
713715
}()
714716

715-
// Use config value instead of hardcoded constant
716-
if blockRange > a.filterConfig.maxBlock {
717-
return nil, fmt.Errorf("block range too large (%d), maximum allowed is %d blocks", blockRange, a.filterConfig.maxBlock)
717+
if err := a.admitLogQuery(blockRange); err != nil {
718+
return nil, err
719+
}
720+
721+
logs, _, err := a.logFetcher.logsInRange(ctx, crit, begin, end)
722+
if err != nil {
723+
return nil, err
718724
}
719725

720-
// Early rejection for pruned blocks - avoid wasting resources on blocks that don't exist
721-
if earliest > 0 && begin < earliest {
722-
return nil, fmt.Errorf("requested block range [%d, %d] includes pruned blocks, earliest available block is %d", begin, end, earliest)
726+
// Ensure we never return nil, always return an array (even if empty)
727+
if logs == nil {
728+
logs = []*ethtypes.Log{}
723729
}
724730

725-
// Only apply rate limiting for large queries (> RPSLimitThreshold blocks)
726-
if blockRange > RPSLimitThreshold && !a.globalRPSLimiter.Allow() {
727-
return nil, fmt.Errorf("log query rate limit exceeded for large queries, please try again later")
731+
return logs, nil
732+
}
733+
734+
// admitLogQuery reports whether a client log query over blockRange blocks may run now.
735+
func (a *FilterAPI) admitLogQuery(blockRange int64) error {
736+
return checkLogQueryAdmission(blockRange, a.filterConfig.maxBlock, a.globalRPSLimiter, a.poolMetrics)
737+
}
738+
739+
// admitPoll returns how many of the blockRange blocks a log filter's poll may scan now.
740+
func (a *FilterAPI) admitPoll(blockRange int64) (allowed int64, err error) {
741+
return checkPollAdmission(blockRange, a.filterConfig.maxBlock, a.globalRPSLimiter, a.poolMetrics)
742+
}
743+
744+
// checkLogQueryAdmission reports whether a log query over blockRange blocks may run, against the
745+
// range cap, the large-query rate limiter, and the worker-queue and DB-semaphore load in m.
746+
func checkLogQueryAdmission(blockRange, maxBlock int64, limiter *rate.Limiter, m *WorkerPoolMetrics) error {
747+
// First, so an over-range query cannot spend a token the valid queries need.
748+
if err := checkBlockRange(blockRange, maxBlock); err != nil {
749+
return err
728750
}
751+
if blockRange > RPSLimitThreshold && !limiter.Allow() {
752+
return &errLogQueryRefused{msg: "log query rate limit exceeded for large queries, please try again later"}
753+
}
754+
return checkLoad(m)
755+
}
729756

730-
// Backpressure: early rejection based on system load
731-
m := GetGlobalMetrics()
757+
// checkPollAdmission returns how many of blockRange blocks a filter poll may scan: all of them
758+
// with a large-query token, RPSLimitThreshold without one. It refuses the poll only under load, as
759+
// checkLogQueryAdmission does.
760+
func checkPollAdmission(blockRange, maxBlock int64, limiter *rate.Limiter, m *WorkerPoolMetrics) (allowed int64, err error) {
761+
// A safeguard only: pollWindow already caps a poll at maxBlock.
762+
if err := checkBlockRange(blockRange, maxBlock); err != nil {
763+
return 0, err
764+
}
765+
if blockRange > RPSLimitThreshold && !limiter.Allow() {
766+
// Cut rather than refused, so a filter that has fallen behind keeps moving instead of
767+
// waiting on tokens.
768+
blockRange = RPSLimitThreshold
769+
}
770+
if err := checkLoad(m); err != nil {
771+
return 0, err
772+
}
773+
return blockRange, nil
774+
}
732775

733-
// Check 1: Too many pending tasks (queue backlog)
776+
// checkLoad refuses any log query while the worker queue or the DB read semaphore in m is 80% used.
777+
// It reads m without reserving capacity, so concurrent queries arriving together can all pass it;
778+
// the worker queue's capacity is the hard bound.
779+
func checkLoad(m *WorkerPoolMetrics) error {
734780
pending := m.TasksSubmitted.Load() - m.TasksCompleted.Load()
735781
maxPending := int64(float64(m.QueueCapacity.Load()) * 0.8) // 80% threshold
736782
if pending > maxPending {
737-
return nil, fmt.Errorf("server too busy, rejecting new request (pending: %d, threshold: %d)", pending, maxPending)
783+
return &errLogQueryRefused{msg: "server too busy, rejecting new request, please try again later"}
738784
}
739785

740-
// Check 2: I/O saturated (semaphore exhausted)
741786
semInUse := m.DBSemaphoreAcquired.Load()
742787
semCapacity := m.DBSemaphoreCapacity.Load()
743788
if semCapacity > 0 && float64(semInUse)/float64(semCapacity) >= 0.8 {
744-
return nil, fmt.Errorf("server I/O saturated, rejecting new request (semaphore: %d/%d in use)", semInUse, semCapacity)
789+
return &errLogQueryRefused{msg: "server I/O saturated, rejecting new request, please try again later"}
745790
}
791+
return nil
792+
}
746793

747-
logs, _, err := a.logFetcher.GetLogsByFilters(ctx, crit)
748-
if err != nil {
749-
return nil, err
750-
}
794+
// errCodeLogQueryRefused is the JSON-RPC error code (-32005, limit exceeded) for a valid log query
795+
// the node declines to run now; it may succeed when retried.
796+
const errCodeLogQueryRefused = -32005
751797

752-
// Ensure we never return nil, always return an array (even if empty)
753-
if logs == nil {
754-
logs = []*ethtypes.Log{}
755-
}
798+
// errLogQueryRefused is a log query shed by admission; the JSON-RPC layer maps it to
799+
// errCodeLogQueryRefused.
800+
type errLogQueryRefused struct {
801+
msg string
802+
}
756803

757-
return logs, nil
804+
func (e *errLogQueryRefused) Error() string {
805+
return e.msg
806+
}
807+
808+
func (e *errLogQueryRefused) ErrorCode() int {
809+
return errCodeLogQueryRefused
810+
}
811+
812+
// checkBlockRange rejects a query over more than maxBlock blocks.
813+
func checkBlockRange(blockRange, maxBlock int64) error {
814+
if blockRange > maxBlock {
815+
return fmt.Errorf("block range too large (%d), maximum allowed is %d blocks", blockRange, maxBlock)
816+
}
817+
return nil
758818
}
759819

760820
// blockHashesFrom returns the hashes of the blocks from cursor on, oldest first, and the cursor the
@@ -933,28 +993,53 @@ func (f *LogFetcher) storeCandidateBudget() *receipt.LogBudget {
933993
return receipt.NewLogBudgetBytesOnly(maxLogBytes)
934994
}
935995

936-
func (f *LogFetcher) GetLogsByFilters(ctx context.Context, crit filters.FilterCriteria) (res []*ethtypes.Log, end int64, err error) {
937-
if err := requireReceiptStore(f.k); err != nil {
938-
return nil, 0, err
996+
// withBounds returns crit fixed to the numeric range [begin, end]. A blockHash crit is returned
997+
// unchanged.
998+
func withBounds(crit filters.FilterCriteria, begin, end int64) filters.FilterCriteria {
999+
if crit.BlockHash != nil {
1000+
return crit
9391001
}
1002+
crit.FromBlock = big.NewInt(begin)
1003+
crit.ToBlock = big.NewInt(end)
1004+
return crit
1005+
}
1006+
1007+
// queryBounds resolves crit's block range against the current head and earliest available block
1008+
// (see ComputeBlockBounds). An unreadable earliest block counts as 0.
1009+
func (f *LogFetcher) queryBounds(ctx context.Context, crit filters.FilterCriteria) (begin, end int64, err error) {
9401010
latest, err := f.latestHeight(ctx)
9411011
if err != nil {
942-
return nil, 0, err
1012+
return 0, 0, err
9431013
}
9441014
earliest, err := f.earliestHeight(ctx)
9451015
if err != nil {
9461016
earliest = 0
9471017
}
948-
begin, end, err := ComputeBlockBounds(latest, earliest, crit)
1018+
return ComputeBlockBounds(latest, earliest, crit)
1019+
}
1020+
1021+
func (f *LogFetcher) GetLogsByFilters(ctx context.Context, crit filters.FilterCriteria) (res []*ethtypes.Log, end int64, err error) {
1022+
// Before the bounds, so a node without a receipt store says so rather than failing on heights.
1023+
if err := requireReceiptStore(f.k); err != nil {
1024+
return nil, 0, err
1025+
}
1026+
begin, end, err := f.queryBounds(ctx, crit)
9491027
if err != nil {
9501028
return nil, 0, err
9511029
}
1030+
return f.logsInRange(ctx, crit, begin, end)
1031+
}
9521032

953-
blockRange := end - begin + 1
954-
955-
// Use config value instead of hardcoded constant
956-
if blockRange > f.filterConfig.maxBlock {
957-
return nil, 0, fmt.Errorf("block range too large (%d), maximum allowed is %d blocks", blockRange, f.filterConfig.maxBlock)
1033+
// logsInRange returns the logs crit matches in [begin, end], a range the caller resolved with
1034+
// queryBounds, and the last block read.
1035+
func (f *LogFetcher) logsInRange(ctx context.Context, crit filters.FilterCriteria, begin, end int64) (res []*ethtypes.Log, last int64, err error) {
1036+
if err := requireReceiptStore(f.k); err != nil {
1037+
return nil, 0, err
1038+
}
1039+
// Fixed to the resolved range, so the block-by-block fallback reads it even if the head moves.
1040+
crit = withBounds(crit, begin, end)
1041+
if err := checkBlockRange(end-begin+1, f.filterConfig.maxBlock); err != nil {
1042+
return nil, 0, err
9581043
}
9591044

9601045
// maxLog caps the number of matching logs a single query may return, for
@@ -1140,12 +1225,19 @@ func (f *LogFetcher) ensureStartRetained(ctx context.Context, start int64) error
11401225
// is below that block fails the poll with an error naming the pruned blocks, and the returned
11411226
// cursor is the earliest block. A block whose logs alone exceed the log caps fails the poll that
11421227
// reaches it, and the returned cursor is past it. A blockHash crit's block is returned by the
1143-
// poll at cursor 0.
1144-
func (f *LogFetcher) pollLogs(ctx context.Context, crit filters.FilterCriteria, cursor int64) ([]*ethtypes.Log, int64, error) {
1228+
// poll at cursor 0. A non-nil admit is asked once per poll, before any block is read, how many of
1229+
// the blocks due it may scan, between 1 and that number; the poll scans that many, and when admit
1230+
// refuses, the poll fails without moving the cursor.
1231+
func (f *LogFetcher) pollLogs(ctx context.Context, crit filters.FilterCriteria, cursor int64, admit func(blockRange int64) (allowed int64, err error)) ([]*ethtypes.Log, int64, error) {
11451232
if logsExhausted(crit, cursor) {
11461233
return []*ethtypes.Log{}, cursor, nil
11471234
}
11481235
if crit.BlockHash != nil {
1236+
if admit != nil {
1237+
if _, err := admit(1); err != nil {
1238+
return nil, cursor, err
1239+
}
1240+
}
11491241
logs, _, err := f.GetLogsByFilters(ctx, crit)
11501242
if exceedsLogCaps(err) {
11511243
// Every later poll would fail on the block again, so the filter ends with the error.
@@ -1160,18 +1252,28 @@ func (f *LogFetcher) pollLogs(ctx context.Context, crit filters.FilterCriteria,
11601252
if err != nil {
11611253
return nil, cursor, err
11621254
}
1255+
// A failed poll returns cursor rather than start, so a filter from block 0 keeps following the
1256+
// earliest block instead of being pinned to the one this poll saw.
1257+
start := cursor
11631258
if earliest, err := f.earliestHeight(ctx); err == nil && cursor < earliest {
11641259
// Pruned blocks cannot be served on any later poll either, so the filter moves on to the
11651260
// earliest block. A filter from block 0 asked for whatever the node has, so only a filter
11661261
// that lost blocks it was due is told.
11671262
if cursor > 0 {
11681263
return nil, earliest, prunedLogsError(crit, cursor, earliest)
11691264
}
1170-
cursor = earliest
1265+
start = earliest
11711266
}
1172-
from, to, ok := pollWindow(crit.ToBlock, cursor, head, f.filterConfig.maxBlock)
1267+
from, to, ok := pollWindow(crit.ToBlock, start, head, f.filterConfig.maxBlock)
11731268
if !ok {
1174-
return []*ethtypes.Log{}, cursor, nil
1269+
return []*ethtypes.Log{}, start, nil
1270+
}
1271+
if admit != nil {
1272+
allowed, err := admit(to - from + 1)
1273+
if err != nil {
1274+
return nil, cursor, err
1275+
}
1276+
to = min(to, from+max(allowed, 1)-1)
11751277
}
11761278
logs, end, err := f.getLogsByFiltersWithBackoff(ctx, crit, from, to)
11771279
var oversized *oversizedBlockError

0 commit comments

Comments
 (0)