Releasing an open source rewards calculation

On Cardano’s proof-of-stake (PoS) protocol—Ouroboros—delegators and stake pool operators (SPOs) receive rewards as they contribute to securing the network. The Cardano ledger specifications outline formulas to calculate these rewards. Bearing this in mind and as part of the Cardano Foundation’s efforts towards the operational resilience of the network, we have open sourced a node-independent reward calculation. The project intends to achieve a means of performing and validating the rewards calculation that is independent of a single implementation. It likewise looks to provide comprehensive documentation related to Cardano’s treasury, reserves, and pool rewards.

As an open source repository under the MIT license, the initiative also deepens the Foundation’s commitment towards open source maturity and aims to garner contributions from the ecosystem at large. Finally, the calculation can equally serve as an educational tool, for example in relation to how protocol parameter changes could impact the flow of funds. It ultimately enhances transparency and improves operational resilience.

Reinforcing operational resilience with open source

The Cardano blockchain offers several unique, carefully considered features. A key one is that staked ada remains in user wallets, enabling transfers to other wallets at any time. While this functionality has benefits, it also presents challenges in implementing rewards calculations. This necessitates the use of snapshots for rewards calculation, as outlined in the ledger specification.

The process begins with the calculation of new reserves, fees, the total rewards pot, and the treasury. Subsequently, pool rewards are determined based on this total rewards pot. The pool rewards are used to calculate the stake pool delegators’ and stake pool operators’ rewards. Due to the requirement for snapshot-based calculations, it can happen that a stake account might become unregistered after taking a snapshot. The stake account therefore cannot receive rewards after the calculation is completed and needs custom rules to handle those special situations.

These rules are naturally spread across the code base, as the calculation process itself is distributed over time. The cardano-ledger repository aggregates most of the business logic, alongside relevant documentation. Some additional components required for this process can be found in the cardano-node itself or in the ouroboros-network repository.

The code gets executed using a slot-based scheduler, which can prove challenging to read and follow for those unfamiliar with the codebase. While certain optimizations have been introduced to enhance the calculation's performance, these optimizations can make the code less straightforward to understand. The open source rewards calculation aims to address these challenges while maintaining the robust features native to the Cardano network.

The Cardano rewards mechanism

Cardano ledger specification includes multiple equations that collectively define the flow of ada at the end of each epoch. Each node will independently calculate the rewards per epoch in a distributed manner with any potential rewards then distributed based on the consensus mechanism. Notably, no one entity completes this calculation nor can anyone withhold rewards. These ada rewards are calculated every epoch and derive from the interaction of two sources: transaction fees and monetary expansion.

• Transaction fees: At the end of each epoch the value from the fee pot (the sum of all transaction fees in that epoch) goes into the total rewards pot.
• Monetary expansion: In addition to transaction fees, a fixed percentage of the reserve is put into the same rewards pot.

The total rewards pot is then divided into two segments. The first part goes into the treasury, while the second forms the stake pool rewards pot. Notably, the mentioned reserves originally started with approximately 14 billion ada and have decreased gradually.

Simultaneously, another calculation computes the pool reward, utilizing the stake pool parameters that, in conjunction with the apparent pool performance, determine the individual stake pool rewards. The resulting value forms the foundation for calculating both delegator and operator rewards. Importantly, all these calculations depend on protocol parameters. The rewards calculation forms an integral part of the Cardano blockchain ecosystem, making it crucial to educate people on how it works. This knowledge empowers people to choose a stake pool that fits with their vision and values.

How the rewards calculation improves transparency

The treasury, reserves, rewards, deposits, and fees—oftentimes referred to as ada-pots—sum up to the max supply of 45 billion ada. While anyone can review ada-pot numbers on Cardano blockchain explorers and on Cardano DB Sync, these platforms are only able to supply the final output of the calculations, without any underlying data available to confirm how those were calculated. Although these calculations exist in the Haskell code of the node and the ledger repositories, they employ a complex, highly distributed formula implementation.

For this reason, the Foundation started pursuing a node-independent reward calculation that implements the formulas outlined in the Cardano ledger specifications and serves as a documentation resource for handling edge cases where the specified formula does not align with the actual implementation. For example, in one instance, a bug in the node implementation resulted in a pool owner running two different pools but with the same reward address receiving rewards for only one stake pool. In this case, fixing the bug led to additional rewards from the treasury being issued to pool owners.

While those manual interventions are completely in line with the protocol specification and recorded in a transparent manner via so called move instantaneous rewards (MIR) certificates, the ada-pots calculated for this epoch would be incorrect. Specifically, if one would calculate the treasury value with the plain formula for this epoch, it would become apparent that it does not match the actual amount of ada held. In short, without knowledge of such extraordinary events, the discrepancy between the formula and the treasury value would prove challenging to trace and there would be less funds in the treasury than indicated by the formula.

Advantages of open sourcing the formula implementation

The rewards calculation was originally integrated into LedgerSync, the Java-based data pipeline developed to supply the Cardano Foundation’s new Cardano explorer with data from the Cardano blockchain. However, the Foundation’s Engineering Team soon realized that untangling the multiple components involved in different aspects of the calculation would prove quite complex. The diversity of input data, which includes specifications, blog posts, forum threads, and self-hosted community documentation, means that gathering the necessary information from various sources to comprehensively understand the flow of ada becomes particularly time-consuming.

Open sourcing the rewards calculation, on the other hand, can empower public inspection, review, and verification of the algorithm as well as the code used to determine how rewards are distributed. This approach  similarly helps build trust in the Cardano infrastructure by serving as a repository that includes an interactive chart explaining the ada flow at the end of an epoch, plus reports that highlight the differences between the formula and actual value.

It also acts as a useful way to educate people about Cardano’s decentralized treasury system and contributes to providing insights into the use of transaction fees. As an open source repository, the rewards calculation further engages the community, propelling everyone to contribute as much documentation as possible. Moreover, it provides a tool for technical enablement as it exposes an API allowing users to compute values currently only available with Cardano DB Sync, a Haskell tool from IOG for crawling node data and making it accessible in a PostgreSQL database.

Working towards rewards calculation transparency

As discussed in the earlier edge case example, using the formula for the next epoch to calculate, for example, the treasury value, will sometimes not yield accurate results. This dynamic can arise when transferring funds to pay a Project Catalyst proposal or, for instance, when using a MIR certificate to compensate for pool rewards missed due to a bug. While transparently recorded on the Cardano blockchain via the MIR certificate mechanism, such edge cases are not always documented in detail publicly, leading to a lack of historical background and therefore significantly compromising transparency, which in turn results in uncertainty and decreased trust. Establishing suitable documentation can prevent this, enabling future reviews and audits as well as improvements to the documentation, thus strengthening the credibility and operational resilience of Cardano.

The Foundation’s work started with the formula implementation and edge case documentation, but some remaining unknowns still need to be addressed. For instance, it is necessary to account for the early Catalyst funds or MIR certificates before epoch 271, as they have no metadata attached to them. Through open sourcing this formula, the Foundation hopes to collaborate with community members to establish a data source-independent solution. Currently, we have a Koios data provider and a data provider for static JSON files, which serve aggregated data. Additionally, a scoped indexer—potentially based on Yaci-Store, a Java-based Cardano datastore implementation—would prove helpful in ensuring maximum transparency in the reward calculation.

This initiative also ultimately concerns the treasury value, which Cardano uses to fund the decentralized development of the ecosystem, pool rewards, and transaction fees. Consequently, it directly impacts aspects that every Cardano user should care about, including the rewards deployment in the ecosystem they are a part of. At the same time, all contributors, whether sharing code or information, play an important role in bringing more trust and transparency to the ecosystem, therefore improving conditions for increased blockchain adoption.

Cracking the calculation

The Foundation generates a report alongside every new version of the repository. We added the average absolute difference between the calculation and the actual treasury value as a metric, and together with the community we hope to achieve a reduction in this value over time.

Contributions to this repository are not limited to code alone; people can add data, links, documentation, and insights regarding the substantial differences observed in some epochs. The repository itself follows a test-driven approach, so it makes sense to begin by creating tests, such as those related to specific pool rewards in specific epochs. The Foundation has created the report for the treasury only, but we see potential to introduce this type of report for the other constituents of the ada-pots as well as detailed reports about selected stake pools and member rewards in the future.

Most of the time, the treasury value averages around 3,500 ada higher than the formula predicts. The pool reap rule directs unclaimable pool deposits—such as when a pool retires and the associated stake address has already been deregistered—back to the treasury. Additionally, each pool can earn a maximum ada value for each epoch. The treasury also directs any difference between the value calculated by the formula and the maximum value. These adjustments to the current implementation should reduce the average absolute difference.

The Foundation has already experienced some success in tackling the fundamentals of the calculation and identifying explanations for some of these discrepancies. It would, however, be valuable to have comprehensive documentation for every outgoing transaction from the treasury.

Next steps also involve implementing the Pool Reap rule, as well as adding capped rewards to the treasury, incorporating MIR certificates, and directing unclaimed rewards to the reserves. In addition, while with each new epoch we currently reset to a known value to prevent forwarding errors from previous epochs, in the future it would prove beneficial to have a scoped consumer for fees, retired pools, deregistered stake accounts, pool updates, and more. This structure would enable dynamic calculations based on the previous calculation.

If, however, there is another unknown in the calculation, leading to a disparity between the calculation and the actual values, an in-depth examination of the Haskell implementation in the cardano-node and cardano-ledger repositories could be completed. This scenario would aim to identify changes that account for the discrepancies by exploring the commit history and issue discussions.

Moving forward, the Foundation intends to utilize the reports and interactive charts coming from this repository to explain ada tokenomics to regulators, businesses, and institutions. In September, we also met with teams from Koios CNTools to introduce them to the repository and gather initial feedback. They welcomed the initiative as well as the idea of implementing and documenting the reward calculation and noted that having other developers port this Java reference implementation to additional languages would provide supplementary value.

An open source approach always enriches the ecosystem, offering mutual benefits to all involved parties while simultaneously fostering transparency and improving the likelihood of widespread adoption of blockchain technology. The Cardano Foundation, therefore, plans to continue open sourcing repositories and solutions with a view to promoting Cardano’s open source maturity.

Fabian Bormann 
Team Lead Ecosystem Architecture and Engineering (EAE)