Dev Update #6

Hey

,
We finally made it. We merged our endpoints (#260 and #262) to the beacon-APIs. In this development update, I want to give a more detailed showcase of the three APIs:

• get block rewards;
• get attestation rewards; and
• get sync committee rewards.

In the following four sections, I will explain what general design decisions we took and what endpoints-specific choices we made.

General design decisions

POST - We decided on a POST request (on attestation and sync committees) because GET requests have length limitations in their URLs which has caused some trouble in the past. When users have tried to fetch data on multiple validators.

---

TAGS - Our endpoints have the TAGS, Beacon, Rewards, and Experimental. Beacon already exists and is meant for a set of endpoints to query beacon chain. We added Rewards, designed for endpoints to query rewards and penalties for validators, and Experimental, for endpoints that are not stable or fully implemented by each client.

---

execution_optimistic - True if the response references an unverified execution payload. Optimistic information may be invalidated at a later time. If the field is not present, assume the False value.

---

finalized - True if the response references the finalized history of the chain, as determined by fork choice. If the field is not present, additional calls are necessary to compare the epoch of the requested information with the finalized checkpoint.

---

In the following, we will look into what kind of data the three endpoints are providing.

Block rewards

/eth/v1/beacon/rewards/blocks/{block_id}

GET block rewards

{
  "execution_optimistic": false,
  "finalized": false,
  "data": {
    "proposer_index": "123",
    "total": "123",
    "attestations": "123",
    "sync_aggregate": "123",
    "proposer_slashings": "123",
    "attester_slashings": "123"
  }
}

• proposer_index - Proposer of the block, the proposer_index, receives these rewards.
• total - Total block reward in gwei equals attestations + sync_aggregate + proposer_slashings + attester_slashings.
• attestations - Block reward component due to included attestations in gwei.
• sync_aggregate - Block reward component due to included sync_aggregate in gwei.
• proposer_slashings - Block reward component due to included proposer_slashings in gwei.
• attester_slashings - Block reward component due to included attester_slashings in gwei.

Attestation rewards

/eth/v1/beacon/rewards/attestations/{epoch}

POST attestation rewards

{
  "execution_optimistic": false,
  "finalized": false,
  "ideal_rewards": [
    {
      "effective_balance": "1000000000",
      "head": "2500",
      "target": "5000",
      "source": "5000"
    }
  ],
  "total_rewards": [
    {
      "validator_index": "0",
      "head": "2000",
      "target": "2000",
      "source": "4000",
      "inclusion_delay": "2000"
    }
  ]
}

• ideal_rewards
  • effective_balance - Validator's effective_balance in gwei.
  • head - Ideal attester's reward for head vote in gwei.
  • target - Ideal attester's reward for target vote in gwei.
  • source - Ideal attester's reward for source vote in gwei.
• total_rewards
  • validator_index - One entry for every validator based on their attestations in the epoch.
  • head - Attester's reward for head vote in gwei.
  • target - Attester's reward for target vote in gwei.
  • source - Attester's reward for source vote in gwei.
  • inclusion_delay - Attester's inclusion_delay reward in gwei (phase0 only).

Sync committee rewards

/eth/v1/beacon/rewards/sync_committee/{block_id}

POST sync committee rewards

{
  "execution_optimistic": false,
  "finalized": false,
  "data": [
    {
      "validator_index": "0",
      "reward": "2000"
    }
  ]
}

• validator_index - One entry for every validator participating in the sync committee.
• reward - Sync committee reward in gwei for the validator.

Next steps

In the last update, I mentioned that this project consists of two significant milestones. The implementation of the beacon-APIs endpoints, which we successfully managed to do, and the implementation into consensus clients.

So in my next development update, I will report how my first steps in implementing the endpoints into Lighthouse went. Bye