Consensus client reward APIs

This project aims to develop APIs that provide detailed reward data for Ethereum validators. The APIs will allow clients to access information regarding the amount of rewards earned for their duties and will enhance transparency in the consensus process. Prior to the development of this project, there was a lack of publicly available APIs that could accurately calculate the rewards paid to validators, hindering the development of essential tools such as block explorers and graphical user interfaces. By developing reliable and comprehensive APIs, this project aims to promote further research on the economic incentives of consensus networks and facilitate the design and operation of blockchain systems.

For more information, see the project document.

Overview

The Ethereum beacon-APIs are a collection of generic RESTful APIs designed to enhance interoperability across beacon node implementations. The new APIs for this project, attestation, block, and sync_committee, can be found here.

As part of this project, these three APIs were designed to provide information on rewards earned by validators for their respective duties. These APIs enable clients to obtain detailed information on the rewards earned by each validator, enhancing transparency in the consensus process.

Now that the new APIs have been proposed and accepted, they were implemented in Lighthouse. This integration allows the APIs to be used by clients running Lighthouse and enables easy access to reward data for each validator.

In the following, we will showcase the three new APIs.

Attestation (PR #3822)

Query:

$ curl --data "[\"8663\", \"0xb0bd225a6202effca9986e8c3ed50b4f29f8b3154ef21337843d945877aadd6c9bf40ff39393f329cfb243e1dfde23ee\"]" -H "Content-Type:application/json" "http://localhost:5052/eth/v1/beacon/rewards/attestations/179550" | jq

Output:

{
  "execution_optimistic": false,
  "data": {
    "ideal_rewards": [
      {
        "effective_balance": "0",
        "head": "0",
        "target": "0",
        "source": "0"
      },
        // omitted
      {
        "effective_balance": "32",
        "head": "3360",
        "target": "6314",
        "source": "3478"
      }
    ],
    "total_rewards": [
      {
        "validator_index": "8663",
        "head": "3360",
        "target": 6314,
        "source": 3478
      },
      {
        "validator_index": "27563",
        "head": "3360",
        "target": 6314,
        "source": 3478
      }
    ]
  }
}

Block (PR #3907)

Query:

$ curl -H "Content-Type:application/json" "http://localhost:5052/eth/v1/beacon/rewards/blocks/5745617" | jq

Output:

{
  "execution_optimistic": false,
  "data": {
    "proposer_index": "32632",
    "total": "31843976",
    "attestations": "30723010",
    "sync_aggregate": "1120966",
    "proposer_slashings": "0",
    "attester_slashings": "0"
  }
}

Sync committee (PR #3903)

Query:

$ curl --data "[\"8663\", \"0xb0bd225a6202effca9986e8c3ed50b4f29f8b3154ef21337843d945877aadd6c9bf40ff39393f329cfb243e1dfde23ee\"]" -H "Content-Type:application/json" "http://localhost:5052/eth/v1/beacon/rewards/sync_committee/5745617" | jq

Output:

{
  "execution_optimistic": false,
  "data": [
    {
      "validator_index": "8663",
      "reward": 15637
    },
    {
      "validator_index": "27563",
      "reward": 15637
    }
  ]
}

Future of the project

While this project has provided a set of APIs for obtaining reward data, there are still opportunities for further development and improvement. One potential next step would be to write tests for the new APIs to ensure their functionality and reliability. While the lack of tests was due to time constraints, implementing them in the future would enhance the overall quality and usability of the APIs.

Additionally, the new APIs will be implemented in other consensus clients beyond Lighthouse, further expanding their potential use cases.

The new APIs also have the potential to be used in blockchain explorers with beaconcha.in expressing interest in their implementation. This would allow platform users to obtain detailed information on the rewards earned by validators and other crucial data, providing greater insight into the consensus process.

In conclusion, the new APIs developed in this project have the potential to enhance transparency, accountability, and research capabilities.

Self-evaluation

NC:

Joining EPF is one of the best decisions I have made in my life. I discovered this program by accident while browsing Reddit when I was slacking off on my day-to-day job. As a person who is new to Ethereum space, I was blown away by how inclusive the community is with so much positive vibe. Everyone is humble and supportive. 

As a person who is new to not only Ethereum, but open source project in general, plus the unfamiliarity of Rust, I threw myself in at the triple deep end of a pool. Big shoutout to my mentor Michael Sproul to help clueless self getting started on the project. Intro to Ethereum, intro to codebases, clear instructions, prompt answers when asked, pulled me back on track when I was totally off, this is way more than what I could ask for from a mentor. It was also a great pleasure working with Kevin. The project is less intimidating when there is another fellow working alongside with you.

Another shoutout to Mario and Josh who did amazing jobs to ensure the whole fellowship program running smoothly and created a sense of belonging within the fellowship circle. I can imagine it was tough particularly when everyone were strangers coming from different background at the start. 

Moving forward, I will continue contributing to the Etheruem eco-system and improving my skills so I can give more back to community just like the mentors, fellows and organizers in EPF. 

Kevin:

Working on this project as part of the EPF has been an amazing experience. I've had the opportunity to learn and collaborate with brilliant people in a supportive and encouraging environment. I'm grateful for the chance to work on a project that has the potential to contribute to the broader Ethereum ecosystem and enhance transparency.

I want to express my deepest appreciation to my mentor Sproul for their guidance, support, and patience throughout the project. Their expertise and mentorship were invaluable, and I couldn't have asked for a better mentor. Sproul went above and beyond to provide feedback and ensure we had everything we needed to succeed. I'm incredibly grateful for their mentorship and look forward to staying in touch.

Finally, I'd like to thank the EPF team, particularly Josh and Mario, for their outstanding organization and support. The calls on Monday and Tuesday were a standout experience for me, and I particularly enjoyed the AMAs on Tuesdays. The EPF team did an excellent job connecting us with other Fellows and mentors, removing obstacles, and providing resources to make our experience as smooth as possible. Overall, I'm incredibly grateful for the opportunity to be a part of the EPF and look forward to continuing to contribute to the community.

<3.