Skip to content

Copy Stake Info (with epoch stake syscall) - #152

Open
mrmizz wants to merge 3 commits into
masterfrom
ab/epoch-stake-syscall-v3
Open

Copy Stake Info (with epoch stake syscall)#152
mrmizz wants to merge 3 commits into
masterfrom
ab/epoch-stake-syscall-v3

Conversation

@mrmizz

@mrmizz mrmizz commented Aug 7, 2025

Copy link
Copy Markdown
Contributor

Introduces four new instructions:

  • UpdateStakeBuffer
  • CopyStakeInfo
  • InitializeStakeBuffer
  • ReallocStakeBuffer

ValidatorStakeBuffer is a new singleton account that allocates a (rather large) buffer, where we can insert active epoch stake amounts for vote accounts.

The intent is to provide a permission-less variant of the UpdateStakeHistory instruction. For this -- we need to observe the active stake amounts of all vote accounts and compute a sorted rank, onchain.

We use the get_epoch_stake_for_vote_account sysvar to observe the stake amounts onchain, one by one for each vote account, and insert them into this fat buffer with sorted descending order.

Once all vote accounts (that have validator history accounts) have been observed and inserted, the buffer is finalized. With the finalized buffer we can then use the CopyStakeInfo instruction to read from the buffer and insert a new entry into the CircBuf of the validator history account.

It is important to note that the buffer can only be written to, finalized, and read from, in the current epoch. That is because the syscall used to populate the buffer only reports current epoch data -- there is no historic data available onchain for active stake values per single vote accounts. This means that if the keeper clients were to miss an epoch, we would not be able to backfill without an oracle signer.

Another important note, is that because this new CopyStakeBuffer does not require an oracle authority to sign, anyone can actually use this instruction to overwrite a keeper that is still using the UpdateStakeHistory instruction. We could mitigate this by adding an oracle signer to this new instruction, for the time being. Although, this is a not a huge issue because an oracle signer can always backfill with final-say so long as we keep that instruction around.

The size of the buffer is also interesting to comment on. At 50,000 elements, the worst case insert into the buffer consumes roughly 700,000 CUs (half the maximum). The best case insert (tail push) consumes roughly 17,000 CUs, irrespective of buffer size. This was extensively tested with integration tests, included in this PR.

Lastly, the buffer size does not inherently limit the number of validator history accounts the program can initialize. Rather, there is as race to fill the buffer. And that race is finalized when either all validator history accounts have been inserted, or the end of the buffer is reached.

-- NOTE --
This is a single cherry-picked commit from an original PR that fell behind master by hundreds of commits. An extensive review was conducted there, which can still be seen. #133

@mrmizz mrmizz mentioned this pull request Aug 7, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant