You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit b625eff
Browse filesBrowse the repository at this point in the historyBrowse files
authored
PLT-980: Index delegations by validator at the v6.8 upgrade (#4518)
The staking precompile's `validatorDelegations` reverts for most
validators on atlantic-2, including bonded ones with thousands of
delegators ([PLT-1447](https://linear.app/seilabs/issue/PLT-1447)).
Delegations are stored by delegator, so listing one validator's
delegations scans the whole delegation store. The precompile path keeps
the v6.6 paginator for consensus safety, and that paginator fails once
it has scanned 10,000 entries without collecting a full page of 100. Any
validator whose delegations are sparse in that keyspace can never return
a page, and the caller gets a bare revert with no cursor.
This adds a delegation-by-validator index under prefix `0x37`
(`validator | delegator`, empty value), a ready marker at `0x38`, and a
backfill cursor at `0x39`. Once the marker is present,
`Querier.ValidatorDelegations` pages over a single validator's prefix,
so each page costs about one read per result; before that it keeps the
full scan. The marker is versioned state, so replaying or tracing
heights before the index is ready still takes the old path and
reproduces the old result, and the frozen v6.6/v6.7 precompiles behave
as before. The query serves the staking precompile and REST/gRPC alike,
so REST/gRPC callers also get the index once it is ready.
**Populating the index.** The v6.8 upgrade handler does not build the
index; it only writes the cursor, which starts a backfill. From then on
`SetDelegation` and `RemoveDelegation` maintain the index (their marker
reads are gasless, so pre-upgrade delegation gas is unchanged), and the
staking `EndBlocker` indexes the next 1,000 delegations after the cursor
each block. When the cursor reaches the end it is deleted and the ready
marker is set. Building it in one pass inside the handler would make the
upgrade block's work and memory grow with the delegation count, which
anyone can inflate ahead of a known upgrade height. Pending writes also
slow every staking iterator created in that block, since the cache store
rescans them per iterator. The batch runs in EndBlock rather than
BeginBlock so that no transaction iterates the staking store while a
batch is pending. `InitGenesis` still builds the index in one pass with
`MigrateDelegationByValIndex`, so fresh chains start with it ready.
**Pagination across the switch.** The index path returns `next_key` as a
length-prefixed delegator rather than a full delegation key. A forward
cursor obtained from the scan before the index was ready resumes at the
delegation it names, so a client paging across that height neither skips
nor repeats a delegator. A reverse page cannot resume from such a cursor
and is rejected with `InvalidArgument`.
This changes consensus at v6.8: from the upgrade height, delegation
writes also write index entries, each block runs a backfill batch until
the index is ready, and precompile results change once it is. Coverage:
staking keeper and genesis tests for the index, the batched backfill
(including delegations written and removed on either side of the cursor)
and scan-cursor resumption; `upgrade_v68` in-process tests that the
handler only starts the backfill and the EndBlocker completes it; and
`make upgrade-test-offline FROM_REF=release/v6.7 TO_REF=<this branch>`,
whose v6.7 source phase now seeds delegations and whose target phase
requires exactly one index entry per delegation after the upgrade block.
The existing size of the index seems to be around 80k, which the
backfill covers in about 80 blocks:
<img width="2130" height="972" alt="image"
src="https://github.com/user-attachments/assets/15b0d51e-d678-4db0-bf4d-2e5bb5f875e9"
/>
**Mainnet shadow test (pacific-1).** A stock v6.7.1 node state-synced
pacific-1 and halted at H-1. A `mock_chain_validation` build of this
branch then ran the real v6.8 handler at H = 237,808,668, on an
r7i.8xlarge, the same type as the mainnet RPC nodes. The build had two
test-only commits on `amir/plt-980-mainnet-shadow`: one forces v6.8 from
`upgrade-info.json`, the other adds batch logging and a full index
audit.
- **Backfill:** 80,832 delegations in 81 blocks (80 × 1,000 + 832), at
about 4.5 ms per batch. Before the upgrade, the staking EndBlocker
averaged 0.48 ms. The node caught up after the switch and then stayed at
the tip.
- **Index audit at the ready height (237,808,748):** 80,832 delegations
and 80,832 index entries, with 0 missing and 0 orphaned.
- **Correctness:** at height 237,811,970, `ValidatorDelegations` for all
40 bonded validators matched a stock mainnet node exactly (delegator,
shares and balance). Offset paging matched too.
- **Latency** (local REST, `limit=1000`):
- Walking every bonded validator through `next_key` took 86 pages and 23
s, against 327 pages and 52 s on the scan path.
- A validator with 2 delegations now takes 1 page (44 ms) instead of 8
(0.86 s).
- A full page of 1,000 results costs about the same as before: p50
around 285 ms, against 174–278 ms. The p99 dropped from up to 424 ms to
at most 315 ms.
- `count_total` now returns the real total (6,961 for one validator).
The scan path returns 0 once a query hits its iteration limit.
- **Not exercised on mainnet data:** the backfill ran while the node was
catching up after the switch, so it finished in about 2 seconds of wall
time. A restart in the middle of the backfill, and diffs while the
cursor moves, were not tested here. The unit tests cover both.
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
0 commit comments