Under the Hood of ethstaker.tax
![Under the Hood of ethstaker.tax - article thumbnail](/assets/blog/2024/ethstaker_tax_under_the_hood/thumbnail.png)
This post documents the evolution of the ethstaker.tax website over the years in conjunction with Ethereum upgrades. We will delve into the inner workings to give you a better idea of what needs to happen behind the scenes for us to be able to provide your Ethereum staking income data as easily as you are used to!
Early Days – December 1, 2020
In the early days of the beacon chain, staking income consisted of consensus rewards only. Every epoch (6.4 minutes) a validator was assigned duties for which they were rewarded (or penalized) on the consensus layer.
![](/assets/blog/2024/ethstaker_tax_under_the_hood/figure_1.png)
Determining income during this period was relatively straightforward, consisting of the comparison of so-called end-of-day balances. We implemented a system where snapshots of all validators' balances were taken at the end of each day and compared to their balances from the previous day. These snapshots occurr every 24 hours at midnight UTC.
![](/assets/blog/2024/ethstaker_tax_under_the_hood/figure_2.png)
Bellatrix / Paris (The Merge) – September 2022
The Paris upgrade, commonly known as The Merge, marked the transition of Ethereum from a proof-of-work based network to a proof-of-stake based network. Following this transition, validators on the Ethereum network assumed the responsibility of including an execution payload in their block proposals, introducing a new source of staking income – execution layer rewards.
Validators chosen at random to propose a block now receive rewards for:
proposing a valid block containing consensus layer data – consensus layer rewards (which existed since the beacon chain's genesis)
including an execution payload – execution layer rewards
Execution layer rewards consist of (1) the priority fees users pay for transactions on the Ethereum network and (2) a portion of the extracted value if the validator is using software to extract MEV (maximal extractable value).
Despite the challenge of extracting the value of execution layer rewards, we successfully developed a system that automatically and accurately processes and verifies over 99.9% of blocks for execution layer rewards.
Capella / Shanghai – April 12, 2023
The highly anticipated upgrade that granted validators the ability to withdraw their staked ETH from the consensus layer to the execution layer. This significant change introduced a withdrawal mechanism that regularly skims rewards exceeding 32 ETH from the validator balance and distributes them to the validator's withdrawal address. The distribution occurs in a round-robin fashion, and for a more detailed understanding of the mechanism, we recommend reading Upgrading Ethereum.
In essence, if a validator has set up a withdrawal address, the excess balance is sent to it every few days. The time between withdrawals is not fixed and varies based on the total number of active validators. The beacon chain cycles through all validators, processing 16 withdrawals every block.
![](/assets/blog/2024/ethstaker_tax_under_the_hood/figure_3.png)
Frequently asked questions
- Where does the price data come from?
- When should staking income be recognized?
Pre-withdrawals
Post-withdrawals
- Are there other sources of this kind of data?
- beaconcha.in
The output shows consensus layer rewards only
Output contains income based on end-of-day balances only
For withdrawal operations, you will need to query the API
- etherscan.io
- EvilJordan's script
- You guessed it - your own node!
ethstaker.tax uses price data provided by CoinGecko, relying on the close price (= price at midnight UTC) returned by their `/api/v3/coins/{id}/history` API endpoint. This aligns with the balance snapshots which also occur at midnight UTC.
Let us preface this with the usual disclaimer: this is not tax advice, as rules vary across the world. We recommend consulting with your accountant regarding your approach.
Before withdrawals were enabled, the validator balance was effectively locked on the beacon chain, making it impossible to access. It could be argued that stakers did not have dominion over the earned Ethereum, and no income occurred before the Capella/Shanghai network upgrade.
Once withdrawals were enabled, stakers gained the ability to access and withdraw the earned rewards. At this point, the Ethereum rewards are no longer locked, and stakers can be considered to have dominion over their earned Ethereum.
We believe the most reasonable approach of reporting income is to recognize the income once it is available to you at the execution layer, every time a withdrawal operation occurs that sweeps rewards to your withdrawal address. This is the approach ethstaker.tax defaults to at the time of writing.
Even though ethstaker.tax has been around for a while and there are no plans to discontinue it, it is always good to have alternatives sources of data.
Apart from ethstaker.tax, there are some other ways of getting the data needed for your tax returns.
The beaconcha.in website has a handy Income History tool that provides some of the same data ethstaker.tax does. However, there are some things to be aware of:
Etherscan provides a CSV export of withdrawal operations as well as produced blocks. These exports don’t include price data so you’ll need to augment the exported data yourself.
This is a script that uses a combination of Etherscan, Infura and CoinGecko APIs to calculate staking income data. The tool (link) makes a few assumptions which may not necessarily be true for you, like "this script assumes all incoming transactions are Execution Layer proposal rewards.". But if you want more control over how the data is calculated, you may want to try it out and adjust it based on your needs.
ethstaker.tax is fully open-source and can be run locally! Keep in mind it does need to process a lot of data, going over the entire history of the beacon chain. At the time of writing (January 2024) the database contains over 530 million rows of balance snapshots, 3.6 million indexed block rewards and more than 33 million withdrawal operations.
Serenita is a leading blockchain infrastructure operator specializing in secure and reliable solutions for managing and growing digital assets, with a primary focus on Ethereum staking. Our seasoned team combines years of experience, technical expertise, and industry knowledge to ensure optimal performance and best-in-class digital asset security. Serenita is committed to contribute to the broader ecosystem by continuing to support home stakers, running minority clients and taking any future measures that benefit the network at large.
We guide our customers through the technical complexities of Ethereum staking, providing non-custodial solutions with the flexibility to stop staking at any time. Reach out to discover how Serenita can help you manage and grow your digital assets, providing expert-driven solutions tailored to your needs.