Add endpoints for block and attestation rewards

apis/beacon/rewards/attestations.yaml

@@ -0,0 +1,67 @@
+post:
+  operationId: getAttestationsRewards
+  summary: Get attestations rewards
+  description: Retrieve attestation reward info for validators specified by array of public keys or validator index. If no array is provided, return reward info for every validator.
+  tags:
+    - Beacon
+    - Rewards
+    - Experimental
+  parameters:
+    - name: epoch
+      in: path
+      required: true
+      description: "The epoch to get rewards info from"
+      schema:
+        $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Uint64"
+  requestBody:
+    description: "An array of either hex encoded public key (any bytes48 with 0x prefix) or validator index"
+    required: false
+    content:
+      application/json:
+        schema:
+          type: array
+          uniqueItems: true
+          items:
+            description: "Either hex encoded public key (any bytes48 with 0x prefix) or validator index"
+            type: string
+  responses:
+    "200":
+      description: "Success"
+      content:
+        application/json:
+          schema:
+            title: GetAttestationsRewardsResponse
+            type: object
+            properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
+              finalized:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized"
+              data:
+                type: array
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/AttestationsRewards"
+
+    "400":
+      description: "Invalid get attestations rewards request"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            InvalidRequest:
+              value:
+                code: 400
+                message: "Invalid request to retrieve attestations rewards info"
+    "404":
+      description: "Epoch not known or required data not available"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            InvalidRequest:
+              value:
+                code: 404
+                message: "Epoch not known or required data not available"
+    "500":
+      $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError"

apis/beacon/rewards/blocks.yaml

@@ -0,0 +1,52 @@
+get:
+  operationId: getBlockRewards
+  summary: Get block rewards
+  description: Retrieve block reward info for a single block
+  tags:
+    - Beacon
+    - Rewards
+    - Experimental
+  parameters:
+    - name: block_id
+      in: path
+      required: true
+      $ref: '../../../beacon-node-oapi.yaml#/components/parameters/BlockId'
+  responses:
+    "200":
+      description: "Success"
+      content:
+        application/json:
+          schema:
+            title: GetBlockRewardsResponse
+            type: object
+            properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
+              finalized:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized"
+              data:
+                $ref: '../../../beacon-node-oapi.yaml#/components/schemas/BlockRewards'              
+    "400":
+      description: "Invalid get block rewards request"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            InvalidRequest:
+              value:
+                code: 400
+                message: "Invalid request to retrieve block rewards info"
+    "404":
+      description: "Block or required state not found"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            InvalidRequest:
+              value:
+                code: 404
+                message: "Block or required state not found"
+    "500":
+      $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError"

beacon-node-oapi.yaml

@@ -54,6 +54,10 @@ tags:
       Minimal set of endpoints to enable a working validator implementation.
 
       [Checkout validator flow](./validator-flow.md) to learn how to use this api.
+  - name: Rewards
+    description: Endpoints to query rewards and penalties for validators.
+  - name: Experimental
+    description: Endpoints that are not stable or fully implemented by each client.
 paths:
 
   /eth/v1/beacon/genesis:
@@ -90,6 +94,10 @@ paths:
     $ref: "./apis/beacon/blocks/root.yaml"
   /eth/v1/beacon/blocks/{block_id}/attestations:
     $ref: "./apis/beacon/blocks/attestations.yaml"
+  /eth/v1/beacon/rewards/blocks/{block_id}:
+    $ref: "./apis/beacon/rewards/blocks.yaml"
+  /eth/v1/beacon/rewards/attestations/{epoch}:
+    $ref: "./apis/beacon/rewards/attestations.yaml"
   /eth/v1/beacon/blinded_blocks/{block_id}:
     $ref: "./apis/beacon/blocks/blinded_block.yaml"
   /eth/v1/beacon/light_client/bootstrap/{block_root}:
@@ -314,6 +322,10 @@ components:
       $ref: './types/fork_choice.yaml#/Node'
     ExtraData:
       $ref: './types/fork_choice.yaml#/ExtraData'
+    BlockRewards:
+      $ref: './types/rewards.yaml#/BlockRewards'
+    AttestationsRewards:
+      $ref: './types/rewards.yaml#/AttestationsRewards'
 
   parameters:
     StateId:

types/primitive.yaml

@@ -34,6 +34,10 @@ Uint256:
   type: string
   example: "1"
 
+Int64:
+  type: string
+  example: "1"
+
 DependentRoot:
   allOf:
     - $ref: "./primitive.yaml#/Root"

types/rewards.yaml

@@ -0,0 +1,105 @@
+AttestationsRewards:
+  description: "Rewards info for attestations"
+  type: array
+  items:
+    properties:
+      ideal_rewards:
+        type: array
+        items:
+          $ref: ./rewards.yaml#/IdealAttestationRewards
+      total_rewards:
+        type: array
+        items:
+          $ref: ./rewards.yaml#/AttestationRewards
+
+AttestationRewards:
+  type: object
+  description: "Rewards info for a single attestation"
+  required: ["validator_index", "head", "target", "source"]
+  properties:
+      validator_index:
+        allOf:
+          - $ref: "./primitive.yaml#/Uint64"
+          - example: 0
+          - description: "one entry for every validator based on their attestations in the epoch"
+      head:
+        allOf:
+          - $ref: "./primitive.yaml#/Int64"
+          - example: 2000
+          - description: "attester's reward for head vote in gwei"
+      target:
+        allOf:
+          - $ref: "./primitive.yaml#/Int64"
+          - example: 2000
+          - description: "attester's reward for target vote in gwei"
+      source:
+        allOf:
+          - $ref: "./primitive.yaml#/Int64"
+          - example: 4000
+          - description: "attester's reward for source vote in gwei"
+      inclusion_delay:
+        allOf:
+          - $ref: "./primitive.yaml#/Uint64"
+          - example: 2000
+          - description: "attester's inclusion_delay reward in gwei (phase0 only)"
+
+IdealAttestationRewards:
+  type: object
+  description: "Ideal rewards info for a single attestation"
+  required: ["effective_balance", "head", "target", "source"]
+  properties:
+    effective_balance:
+      allOf:
+        - $ref: "./primitive.yaml#/Uint64"
+        - example: 1000000000
+        - description: "validator's effective balance in gwei"
+    head:
+      allOf:
+        - $ref: "./primitive.yaml#/Int64"
+        - example: 2500
+        - description: "Ideal attester's reward for head vote in gwei"
+    target:
+      allOf:
+        - $ref: "./primitive.yaml#/Int64"
+        - example: 5000
+        - description: "Ideal attester's reward for target vote in gwei"
+    source:
+      allOf:
+        - $ref: "./primitive.yaml#/Int64"
+        - example: 5000
+        - description: "Ideal attester's reward for source vote in gwei"
+
+BlockRewards:
+  type: object
+  description: "Rewards info for a single block"
+  properties:
+    proposer_index:
+      allOf:
+        - $ref: "./primitive.yaml#/Uint64"
+        - example: 123
+        - description: "proposer of the block, the proposer index who receives these rewards"
+    total:
+      allOf:
+        - $ref: "./primitive.yaml#/Uint64"
+        - example: 123
+        - description: "total block reward in gwei, equal to attestations + sync_aggregate + proposer_slashings + attester_slashings"
+    attestations:
+      allOf:
+        - $ref: "./primitive.yaml#/Uint64"
+        - example: 123
+        - description: "block reward component due to included attestations in gwei"
+    sync_aggregate:
+      allOf:
+        - $ref: "./primitive.yaml#/Uint64"
+        - example: 123
+        - description: "block reward component due to included sync_aggregate in gwei"
+    proposer_slashings:
+      allOf:
+        - $ref: "./primitive.yaml#/Uint64"
+        - example: 123
+        - description: "block reward component due to included proposer_slashings in gwei"
+    attester_slashings:
+      allOf:
+        - $ref: "./primitive.yaml#/Uint64"
+        - example: 123
+        - description: "block reward component due to included attester_slashings in gwei"