# Staking Info PR - claimed field - Guide
The following is a helper document to make this [PR](https://github.com/paritytech/substrate-api-sidecar/pull/1445)'s review in Sidecar easier.

## Purpose of this PR
This PR fixes the `claimed` field that is returned from Sidecar's `staking-info` endpoint.

## Context
In Sidecar we have the `/accounts/{accountId}/staking-info` endpoint ([docs](https://paritytech.github.io/substrate-api-sidecar/dist/)) that takes an account and a block as params and returns the staking information related to this account and at the specified block height.

An example response from the endpoint is the following:

{
  "at": {
    "hash": "0x9d64767ea3daba970b8b1ac7cce96e31329d7c8c048203e6f44c87f16ec7d4f6",
    "height": "21298962"
  },
  "controller": "1zugcapKRuHy2C1PceJxTvXWiq6FHEDm2xa5XSU7KYP3rJE",
  "rewardDestination": {
    "account": "12nT9mWLcxbqyXMLXCwaXswb762v5hBDBK2CWDNLdJcyxaTa"
  },
  "numSlashingSpans": "3",
  "nominations": null,
  "staking": {
    "stash": "1zugcapKRuHy2C1PceJxTvXWiq6FHEDm2xa5XSU7KYP3rJE",
    "total": "10000000000000",
    "active": "10000000000000",
    "unlocking": [],
    "claimedRewards": [....]

As you can see the last field is called `claimed` and that is exactly what we will be talking about here since it broke and it needs fixing. 🧑‍🔧

## How did `claimed` break
Let's see what changed/broke in the `claimed` field to understand why it needs fixing in the first place.

### Before
Until era 6514 (in Kusama) and era 1420 (in Polkadot) (related [comment](https://github.com/paritytech/substrate-api-sidecar/issues/1433#issuecomment-2075914389)), the endpoint's response was :


The above output in the `claimedRewards` field was the result of a very simple and straightforward logic implemented in the backend. We were just using the call `historicApi.query.staking.ledger(controller)` ([link](https://github.com/paritytech/substrate-api-sidecar/blob/a6eb6aa6687982d31474f305f1044db3c2b8faf8/src/services/accounts/AccountsStakingInfoService.ts#L53) to code) which returned:

{
  stash: 13foHgXdzr1agokV6Ed9CBHGQG1NpBqvqhmUL7rojcBUBzvq
  total: 100,000,000,000,000
  active: 100,000,000,000,000
  unlocking: []
  claimedRewards: [
    1,328
    1,329
    1,330
    1,331
    1,332
    1,379
    1,380
  ]
}

and we would directly return that in the endpoint's result under the `staking` field ([link](https://github.com/paritytech/substrate-api-sidecar/blob/a6eb6aa6687982d31474f305f1044db3c2b8faf8/src/services/accounts/AccountsStakingInfoService.ts#L83) to code) including all the eras found in the `claimedRewards` array.

### After with no fix
Then after this [PR](https://github.com/paritytech/polkadot-sdk/pull/1189) was merged and applied (*so after era 6514 (in Kusama) and era 1420 (in Polkadot)*), two important changes happened :
- the array `claimedRewards` was renamed to `legacyClaimedRewards` and
- the array `legacyClaimedRewards` was deprecated so not used anymore.

So for all the subsequent eras what we have now is one of the following cases :

#### Case 1
The renamed field `legacyClaimedRewards` showing the claimed eras from the last time this array was updated before deprecation.


#### Case 2


*Response from endpoint `http://127.0.0.1:8080/accounts/13foHgXdzr1agokV6Ed9CBHGQG1NpBqvqhmUL7rojcBUBzvq/staking-info?at=21802111`*

The renamed field `legacyClaimedRewards` with no data since it was deprecated and another array is updated instead (`claimedRewards`).

## Problems
The issues that we have in Sidecar after this change are the following:
- The returned field was renamed from `claimedRewards` to `legacyClaimedRewards` so this immediately broke the logic of anyone retrieving the info from the `claimedRewards` field
- The field `legacyClaimedRewards` stopped being updated so even if you retrieve the renamed field you do not get the desired info anymore.

## Suggested Solution
With the suggested fix in the current PR, we propose the following solutions:
- Restore the original name of the field to `claimedRewards`.
- Change the structure of the `claimedRewards` field in the response to returns the status for each era individually.
- Added `IStakingLedger` interface in the [AccountStakingInfo.ts](https://github.com/paritytech/substrate-api-sidecar/blob/master/src/types/responses/AccountStakingInfo.ts) file.
- Return claimed rewards for both the validator and the nominator's account.
- Introduce different set of era statuses for the validator and the nominator.
- Refactor the entire logic for retrieving the desired information based on the new logic.

### After with the proposed fix
With the suggested solution / implementation, we will get the following data from the endpoint's response regarding the claimed rewards:


### What would this mean for the users of the endpoint?
- Is the suggested solution a breaking change for the users?
- Yes, this solution is a breaking change. However, without doing anything, the endpoint has already a breaking change introduced by the runtime upgrade (the field was renamed - [link](https://github.com/paritytech/substrate-api-sidecar/issues/1433#issue-2261548632) to comment). So, the users are already affected.
- Why do we need this PR?
- This change is necessary to restore the endpoint's functionality, which is currently not displaying claimed information for eras after the relevant runtime upgrades.
- What information does the endpoint show right now?
- Claimed information appears correctly for eras before the runtime upgrade and briefly afterward. Then the field was renamed and deprecated so no data are displayed in the relevant response field.
- With this solution, does the endpoint's response changes only for eras after the runtime upgrade or also before?
- This solution will affect how claimed information is displayed for all queried blocks, both before and after the runtime upgrade.
- This means that users used to retrieve claimed information before runtime upgrade in the usual format:

        {
          stash: 13foHgXdzr1agokV6Ed9CBHGQG1NpBqvqhmUL7rojcBUBzvq
          ...
          claimedRewards: [
            1,328
            1,329
          ]
        }

- With this PR, the response for all eras will change to the new format:

        {
          stash: 13foHgXdzr1agokV6Ed9CBHGQG1NpBqvqhmUL7rojcBUBzvq
          ...
          claimedRewards: [
            {
                era: 1328,
                status: "claimed"
            },
            {
                era: 1329,
                status: "claimed"
            },
          ]
        }

## Implementation Details of this Solution
All the implementation details were added in the STAKING_IMPLEMENTATION_DETAILS.md in the same [PR](https://github.com/paritytech/substrate-api-sidecar/pull/1445/files).

## Note for the Reviewer
Take into consideration that the endpoint is already "broken", meaning it does not provide any claimed information right now. Hence, even if this solution is found not perfect, it can also be considered as a first step towards regaining the lost functionality (claimed) of the endpoint.

To review this PR it is recommended to:
- First check the PR's description which includes some general info like :
- What is this PR fixing -> claimed field in the `staking-info` endpoint
- with what issue is related
- Check the guide IMPLEMENTATION DETAILS which was added in the PR.

## How to test the change
You can test by :
- Running the 3 tests that were added in the PR `yarn test AccountsStakingInfoService`
- Manual testing to check the different cases mentioned earlier