## Sidecar - Staking Payouts Endpoint

Sidecar provides the endpoint `/accounts/{accountId}/staking-payouts`, allowing you to retrieve the payout information for a Stash account.

### Claimed field
One of the available fields within the response is the `claimed` field. The value of this field is defined in this [part](https://github.com/paritytech/substrate-api-sidecar/blob/master/src/services/accounts/AccountsStakingPayoutsService.ts#L404L431) of the code which is under this `for` loop (line [385](https://github.com/paritytech/substrate-api-sidecar/blob/8de3f34d093e69a14d73b0ee332a8ba15bc2fa1c/src/services/accounts/AccountsStakingPayoutsService.ts#L385)).

#### `for` loop
I am mentioning this `for` loop because in the [part](https://github.com/paritytech/substrate-api-sidecar/blob/master/src/services/accounts/AccountsStakingPayoutsService.ts#L404L431) where `claimed` is defined there are specific checks with `continue` statements. This means that if the check is `true`, we will skip the rest of the code and continue to the next iteration. In our case, this means that basically for the queried account we do not print the payouts (more precisely the payouts fields in the response will be an empty array) in the response since we skip this [part](https://github.com/paritytech/substrate-api-sidecar/blob/master/src/services/accounts/AccountsStakingPayoutsService.ts#L433L449) of the code.

#### `claimed` checks
Returning to the code related to `claimed`, we see seven distinct checks:
1. Line [412](https://github.com/paritytech/substrate-api-sidecar/blob/8de3f34d093e69a14d73b0ee332a8ba15bc2fa1c/src/services/accounts/AccountsStakingPayoutsService.ts#L412) : checking the value of `legacyClaimedRewards`
1. Line [414](https://github.com/paritytech/substrate-api-sidecar/blob/8de3f34d093e69a14d73b0ee332a8ba15bc2fa1c/src/services/accounts/AccountsStakingPayoutsService.ts#L414) : checking the value of `claimedRewards`
1. Line [416](https://github.com/paritytech/substrate-api-sidecar/blob/8de3f34d093e69a14d73b0ee332a8ba15bc2fa1c/src/services/accounts/AccountsStakingPayoutsService.ts#L416C66-L416C76) : checking the value of `lastReward`
1. Line [418](https://github.com/paritytech/substrate-api-sidecar/blob/8de3f34d093e69a14d73b0ee332a8ba15bc2fa1c/src/services/accounts/AccountsStakingPayoutsService.ts#L418) : subcheck on the value of `lastReward`
1. Line [420](https://github.com/paritytech/substrate-api-sidecar/blob/8de3f34d093e69a14d73b0ee332a8ba15bc2fa1c/src/services/accounts/AccountsStakingPayoutsService.ts#L420) : subcheck on the value of `lastReward`
1. Line [423](https://github.com/paritytech/substrate-api-sidecar/blob/8de3f34d093e69a14d73b0ee332a8ba15bc2fa1c/src/services/accounts/AccountsStakingPayoutsService.ts#L423) : specific check if the chain isKusama and the era < 518
1. Line [425](https://github.com/paritytech/substrate-api-sidecar/blob/8de3f34d093e69a14d73b0ee332a8ba15bc2fa1c/src/services/accounts/AccountsStakingPayoutsService.ts#L425) : if none of the above works

#### `indexOfEra` variable
In each of the above checks, we either set a value to the variable `indexOfEra` or we `continue`. In Line [428](https://github.com/paritytech/substrate-api-sidecar/blob/8de3f34d093e69a14d73b0ee332a8ba15bc2fa1c/src/services/accounts/AccountsStakingPayoutsService.ts#L428), the value of `claimed` is set to either `true` or `false` based on the value of `indexOfEra`.

#### Checking the query param
In Line [429](https://github.com/paritytech/substrate-api-sidecar/blob/8de3f34d093e69a14d73b0ee332a8ba15bc2fa1c/src/services/accounts/AccountsStakingPayoutsService.ts#L429) checks :
1. the value of the query parameter `unclaimedOnly` that the user chose in the request. Example:

    staking-payouts?unclaimedOnly=false&at=20496105&depth=1&era=1418

1. and the value of `claimed` variable

This condition will evaluate to `true` only if `unclaimedOnly` is `true` and `claimed` is also `true`, which then means that the payouts in the response will be an empty array.

Examples:
- if the user chose `unclaimedOnly` = `false` and the variable `claimed` from the above checks resulted to `true`, then the payouts in the response will be returned.
- if the user chose `unclaimedOnly` = `false` and `claimed` resulted `false`, the payouts in the response will be returned.

### Changes in the code related to `claimed` field

#### 20240424
There was a recent fix in the calculation of the `claimed` field which is reflected in the [PR #1429](https://github.com/paritytech/substrate-api-sidecar/pull/1429). In this PR we fixed the cases where for the same `account` and `era` :
- for early block heights we were not printing the payouts (returning an empty array) even though there were payouts
- for later block heights of same era, we were printing the payouts

Now we print the payouts but with `claimed` variable being `false` or `true` depending on the queried block height.

#### Upcoming Changes
Further changes will be made to `claimed` due to the latest runtime upgrade. It will affect the eras (Polkadot and Kusama) mentioned in this [comment](https://github.com/paritytech/substrate-api-sidecar/issues/1433#issuecomment-2075914389).