Add validator score penalty details to epochs API

Rather than do all the below, I will just state my wish list of what we would like to be able to show in the front end and let Zohar tell me the correct way to get it because otherwise we're likely to get into a mess with the whole reward vs ranking score and which epoch they're relevant for.

For all the below we are using the /api/v2/epoch API to pull the data into the UI. The more we can put in the API so the calc is the FE is minimised the better.

This is what we currently show, with a popup to show the penalty breakdown on hover.

What we want to be able to show is for the epoch that just ended, how has the rewards earned by the validators been impacted by penalties. And this should include:

The overall penalty for each validator
- Assumption was we should use 1 - validatorScore / stakeScore here but we run into the epoch issue, so maybe this is where we need that "theoretical stake score" to be added to the rewardScore?
The penalty broken down into its components
- Overstaking component, where I was using 1 - rawValidatorScore / stakeScore but same issue
- Would be good to have PenaltyFlatAmt & PenaltyDownAmt here in case we ever want to show an actual "overstaked amount" rather than just a percentage
- Alternatively if we had the optStake on this API somewhere we could use that

Performance Component, which is basically 1- performanceScore so we already have it (though question mark over whether to use performanceScore from rewardScore or rankingScore...we seemed to conclude rankingScore in current epoch here.
Multisig Component, which we can already get from the rewardScore.multisigScore

Total stake; currently the front ends have to sum across all nodes to get this the whole time, would be useful to just have it, or maybe to have the stake on consensus, standby and candidate nodes broken down since they are relevant to the scores
We also want to be able to show the "Stake Needed for Promotion" for each of the Standby / Candidate validators. This gets difficult because there are many variables and Barney didnt want to introduce rankingScore as it doesnt mean anything to users, but what we agreed with Barney was that we'd do the below - you are probably going to say this is completely wrong!

Take the rankingScore of the lowest consensus validator, and we know rankingScore = Stake x Performance x (1 + incumbent bonus)
Multiply that by total stake and you would get the Stake x Performance that a standby validator woudl need to hit to be promoted
Then if you assume constant performance with prior epoch you can calculate the stake each standby validator woudl need for promotion

I dont know if that works or not ....open to other ideas. The requirement is to be able to give some indication of how far away standby validators are from promotion without introducing the user to lots of complicated new scores.

I dont know if ANY of this works for Candidate / Pending validators because those dont have a rewardScore section at all. Ideally we'd again be able to show the stake needed for promotion into the standby set here, but I dont know whether the various things we need for that calculation (if it even works) are available for Candidate / Pending validators.

IGNORE whats below the line as it is now replaced with the above....but left it in for context / background

In the POS rewards spec there is a section on generating the "linearScore" which is exposed on the epochs API as rawValidatorScore.

Effectively this part of the code is generating the "anti-whaled" score, and then we take this score and scale it by performance to get to the validatorScore.

function validatorScore(valStake) {
  a = Math.max(s_minVal, s_numVal/s_compLevel)
  optStake = s_total / a

  penaltyFlatAmt = Math.max(0.0, valStake - optStake)
  penaltyDownAmt = Math.max(0.0, valStake - optimalStakeMultiplier*optStake)
  linearScore = (valStake - penaltyFlatAmt - penaltyDownAmt)/s_total

  // make sure we're between 0 and 1.
  linearScore = Math.min(1.0, Math.max(0.0,linearScore))
  return linearScore
}

We have been reworking the validator page on the Governance App to make all this stuff clearer and simpler, and we have also revamped the validator details page to try to expose some of the underlying detail held on that reward epochs API, but have hit a bit of a snag.

Rather than request anything new - given the focus on trading - I attempted to infer the overstaking penalty based on comparing the rawValidatorScore to the stake share. So you basically say

Overstaking Penalty = 1 - (rawValidatorScore / Stake Share)

Which sort of works, but .. ideally we wanted to be able to show an "Overstaked Amount" (ie. how far above the optimal stake a validator is) and we cant get to this, because the penalty is a combination of the PenaltyFlatAmt (which is I think equivalent to this overstaked amount I'm talking about) AND this PenaltyDownAmt (which appears to be an extra penalty to really nail heavily overstaked validators).

All of which is to say ... would it be possible to start exposing the PenaltyFlatAmt and PenaltyDownAmt for each validator on the epochs API? Otherwise we need to look at recreating the full logic above in the TFE, which doesnt seem sensible.

Not urgent, but would be good to agree if its something that can go on the backlog, and then I'll ticket it and the accompanying TFE change so we can track it.

It might also be useful to have Total Stake and OptStake exposed on that API, obviously once at the top since this is common across all validators. (edited)

Will need attention of @ze97286 as he is the expert in this area.

vegaprotocol / vega

Add validator score penalty details to epochs API #7351