fix(query): fix off-by-one when iteration budget exhausts at offset (#4629)

Untrusted unfiltered offset queries were rejected with `InvalidArgument`
("scanned more than N entries before reaching offset") when
`max-iterations` equalled the requested offset, even though the offset
had been fully skipped at that point. The correct response is an empty
page whose `next_key` resumes at the first entry of the page. Defaults
cannot reach this (`max-iterations` 11000 > `max-offset` 10000), and
`ValidateQueryConfig` already warns about such configs, so it needs an
operator who ignores that warning. Follow-up to #3984 review; fixes
PLT-1485.

The cause is that `offsetScanCursor.phase()` meant different things at
its two call sites. The loop body calls it after `beginIteration`
increments `scanned`, where `scanned <= offset` correctly means "this
entry is skipped". The budget-exhaust check in `beginIteration` calls it
before the increment, where the same predicate is off by one. Rather
than overload `phase()` further, the exhaust check now uses a new
`offsetConsumed()` predicate, so `phase()` keeps a single meaning. The
filtered path is unaffected: `offsetConsumed()` reduces to the existing
`hits < offset` check there.

No consensus, state, or wire-format impact; this only changes the
response to a narrow class of ABCI queries from an error to a valid
page.
`TestUntrustedQueryUnfilteredBudgetExhaustAtOffsetReturnsResumeKey`
covers the boundary and its resume, and fails without the fix. The
existing
`TestUntrustedQueryRejectsBudgetExhaustBeforeOffset{Filtered,Unfiltered}`
tests pass unchanged.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: amir-deris

sei-cosmos/server/config/config.go

@@ -418,6 +418,8 @@ func GetConfig(v *viper.Viper) (Config, error) {
 			StreamImport:      v.GetBool("genesis.stream-import"),
 			GenesisStreamFile: v.GetString("genesis.genesis-stream-file"),
 		},
+		// The query.* keys are read at runtime by baseapp.readQueryConfig; nothing consumes
+		// this field, so parsing them here would add a second reader that could drift.
 		Query: DefaultQueryConfig(),
 	}
 

sei-cosmos/server/config/toml.go

@@ -119,9 +119,13 @@ max-limit = {{ .Query.MaxLimit }}
 max-offset = {{ .Query.MaxOffset }}
 
 # MaxIterations is the maximum store entries a single untrusted query may scan. 0 uses
-# the default. When the budget is exhausted the response is a partial page with next_key;
-# total stays 0 even when the client set count_total, so next_key != nil with total == 0
-# means the total is unknown rather than zero results.
+# the default. When the budget is exhausted after the offset is reached, the response is
+# a partial page with next_key; total stays 0 even when the client set count_total, so
+# next_key != nil with total == 0 means the total is unknown rather than zero results.
+# When the budget is exhausted before the offset is reached, the query fails with
+# InvalidArgument. Filtered queries (for example gov proposals with a status filter)
+# can hit this on defaults, because entries the filter rejects still count against
+# the budget but not toward the offset.
 max-iterations = {{ .Query.MaxIterations }}
 `
 

sei-cosmos/types/query/filtered_pagination.go

@@ -211,50 +211,6 @@ func GenericFilteredPaginate[T codec.ProtoMarshaler, F codec.ProtoMarshaler](
 	onResult func(key []byte, value T) (F, error),
 	constructor func() T,
 ) ([]F, *PageResponse, error) {
-	return genericFilteredPaginate(ctx, cdc, prefixStore, pageRequest, onResult, constructor, false)
-}
-
-// GenericFilteredPaginateForContext applies GenericFilteredPaginate on the ABCI query path
-// and GenericFilteredPaginateV66 during consensus execution.
-func GenericFilteredPaginateForContext[T codec.ProtoMarshaler, F codec.ProtoMarshaler](
-	ctx sdk.Context,
-	cdc codec.BinaryCodec,
-	prefixStore types.KVStore,
-	pageRequest *PageRequest,
-	onResult func(key []byte, value T) (F, error),
-	constructor func() T,
-) ([]F, *PageResponse, error) {
-	if ctx.IsABCIQuery() {
-		return GenericFilteredPaginate(ctx, cdc, prefixStore, pageRequest, onResult, constructor)
-	}
-	return GenericFilteredPaginateV66(cdc, prefixStore, pageRequest, onResult, constructor)
-}
-
-// GenericFilteredPaginateV66 preserves release/v6.6 behavior for EVM
-// precompiles. Node-local LCD/gRPC queries must use GenericFilteredPaginate.
-func GenericFilteredPaginateV66[T codec.ProtoMarshaler, F codec.ProtoMarshaler](
-	cdc codec.BinaryCodec,
-	prefixStore types.KVStore,
-	pageRequest *PageRequest,
-	onResult func(key []byte, value T) (F, error),
-	constructor func() T,
-) ([]F, *PageResponse, error) {
-	return genericFilteredPaginate(sdk.Context{}, cdc, prefixStore, pageRequest, onResult, constructor, true)
-}
-
-func genericFilteredPaginate[T codec.ProtoMarshaler, F codec.ProtoMarshaler](
-	ctx sdk.Context,
-	cdc codec.BinaryCodec,
-	prefixStore types.KVStore,
-	pageRequest *PageRequest,
-	onResult func(key []byte, value T) (F, error),
-	constructor func() T,
-	useV66 bool,
-) ([]F, *PageResponse, error) {
-	if useV66 {
-		return genericFilteredPaginateV66(cdc, prefixStore, pageRequest, onResult, constructor)
-	}
-
 	var results []F
 	pageRes, err := FilteredPaginate(ctx, prefixStore, pageRequest, func(key []byte, value []byte, accumulate bool) (bool, error) {
 		protoMsg := constructor()
@@ -284,6 +240,34 @@ func genericFilteredPaginate[T codec.ProtoMarshaler, F codec.ProtoMarshaler](
 	return results, pageRes, nil
 }
 
+// GenericFilteredPaginateForContext applies GenericFilteredPaginate on the ABCI query path
+// and GenericFilteredPaginateV66 during consensus execution.
+func GenericFilteredPaginateForContext[T codec.ProtoMarshaler, F codec.ProtoMarshaler](
+	ctx sdk.Context,
+	cdc codec.BinaryCodec,
+	prefixStore types.KVStore,
+	pageRequest *PageRequest,
+	onResult func(key []byte, value T) (F, error),
+	constructor func() T,
+) ([]F, *PageResponse, error) {
+	if ctx.IsABCIQuery() {
+		return GenericFilteredPaginate(ctx, cdc, prefixStore, pageRequest, onResult, constructor)
+	}
+	return GenericFilteredPaginateV66(cdc, prefixStore, pageRequest, onResult, constructor)
+}
+
+// GenericFilteredPaginateV66 preserves release/v6.6 behavior for EVM
+// precompiles. Node-local LCD/gRPC queries must use GenericFilteredPaginate.
+func GenericFilteredPaginateV66[T codec.ProtoMarshaler, F codec.ProtoMarshaler](
+	cdc codec.BinaryCodec,
+	prefixStore types.KVStore,
+	pageRequest *PageRequest,
+	onResult func(key []byte, value T) (F, error),
+	constructor func() T,
+) ([]F, *PageResponse, error) {
+	return genericFilteredPaginateV66(cdc, prefixStore, pageRequest, onResult, constructor)
+}
+
 func genericFilteredPaginateV66[T codec.ProtoMarshaler, F codec.ProtoMarshaler](
 	cdc codec.BinaryCodec,
 	prefixStore types.KVStore,

sei-cosmos/types/query/paginate_driver.go

@@ -159,9 +159,17 @@ func (c *offsetScanCursor) phase() scanPhase {
 	}
 }
 
+// offsetConsumed reports whether the requested offset has been fully skipped.
+func (c *offsetScanCursor) offsetConsumed() bool {
+	if c.filtered {
+		return c.hits >= c.req.offset
+	}
+	return c.scanned >= c.req.offset
+}
+
 func (c *offsetScanCursor) beginIteration(key []byte) (stop bool, err error) {
 	if resumeKey, exhausted := c.budget.begin(key); exhausted {
-		if c.phase() == scanPhaseSkip {
+		if !c.offsetConsumed() {
 			return true, c.budget.offsetNotReachedError()
 		}
 		if c.nextKey == nil {

sei-cosmos/types/query/scan_limit_test.go

@@ -82,6 +82,33 @@ func TestUntrustedQueryRejectsBudgetExhaustBeforeOffsetUnfiltered(t *testing.T)
 	require.Contains(t, err.Error(), "scanned more than 50 entries before reaching offset")
 }
 
+func TestUntrustedQueryUnfilteredBudgetExhaustAtOffsetReturnsResumeKey(t *testing.T) {
+	const maxIterations = 50
+	ctx := sdk.Context{}.WithIsABCIQuery(true).WithPaginationLimits(sdk.UntrustedPaginationLimits(1000, 10_000, maxIterations))
+	store := newTestKVStore(t)
+
+	for i := 0; i < 200; i++ {
+		store.Set([]byte(fmt.Sprintf("%03d", i)), []byte("v"))
+	}
+
+	var keys [][]byte
+	collect := func(key, _ []byte) error {
+		keys = append(keys, key)
+		return nil
+	}
+
+	res, err := query.Paginate(ctx, store, &query.PageRequest{Offset: maxIterations, Limit: 10}, collect)
+	require.NoError(t, err)
+	require.Empty(t, keys)
+	require.Equal(t, "050", string(res.NextKey))
+
+	_, err = query.Paginate(ctx, store, &query.PageRequest{Key: res.NextKey, Limit: 10}, collect)
+	require.NoError(t, err)
+	require.Len(t, keys, 10)
+	require.Equal(t, []byte("050"), keys[0])
+	require.Equal(t, []byte("059"), keys[9])
+}
+
 func TestUntrustedQueryPartialPageWhenBudgetExhaustDuringCollect(t *testing.T) {
 	ctx := sdk.Context{}.WithIsABCIQuery(true).WithPaginationLimits(sdk.UntrustedPaginationLimits(1000, 10_000, 25))
 	store := newTestKVStore(t)