{"id":36627913,"url":"https://github.com/cardano-foundation/cf-java-rewards-calculation","last_synced_at":"2026-01-12T09:34:09.567Z","repository":{"id":204503265,"uuid":"684216356","full_name":"cardano-foundation/cf-java-rewards-calculation","owner":"cardano-foundation","description":"This java project is used to calculate the rewards of the Cardano blockchain. It aims to be both an edge case documentation and formula implementation.","archived":false,"fork":false,"pushed_at":"2025-03-21T11:19:28.000Z","size":5073,"stargazers_count":20,"open_issues_count":3,"forks_count":1,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-03-21T11:23:50.416Z","etag":null,"topics":["calculation","cardano","java","pool","reserve","rewards","treasury"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cardano-foundation.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-28T17:29:19.000Z","updated_at":"2025-03-21T10:58:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"5fb69ba8-2696-445c-92f8-b08906d0f9ae","html_url":"https://github.com/cardano-foundation/cf-java-rewards-calculation","commit_stats":null,"previous_names":["cardano-foundation/cf-java-rewards-calculation"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/cardano-foundation/cf-java-rewards-calculation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardano-foundation%2Fcf-java-rewards-calculation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardano-foundation%2Fcf-java-rewards-calculation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardano-foundation%2Fcf-java-rewards-calculation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardano-foundation%2Fcf-java-rewards-calculation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cardano-foundation","download_url":"https://codeload.github.com/cardano-foundation/cf-java-rewards-calculation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardano-foundation%2Fcf-java-rewards-calculation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calculation","cardano","java","pool","reserve","rewards","treasury"],"created_at":"2026-01-12T09:34:09.512Z","updated_at":"2026-01-12T09:34:09.562Z","avatar_url":"https://github.com/cardano-foundation.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cardano Rewards Calculation 🧮\n\n\u003cp align=\"left\"\u003e\n\u003ca href=\"https://cardano-foundation.github.io/cf-java-rewards-calculation/coverage-report/\"\u003e\u003cimg alt=\"Tests\" src=\"https://github.com/cardano-foundation/cf-java-rewards-calculation/actions/workflows/tests.yaml/badge.svg?branch=main\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://cardano-foundation.github.io/cf-java-rewards-calculation/coverage-report/\"\u003e\u003cimg alt=\"Coverage\" src=\"https://cardano-foundation.github.io/cf-java-rewards-calculation/badges/jacoco.svg\" /\u003e\u003c/a\u003e\n\u003cimg alt=\"Release\" src=\"https://github.com/cardano-foundation/cf-java-rewards-calculation/actions/workflows/release.yaml/badge.svg?branch=main\" /\u003e\n\u003ca href=\"https://central.sonatype.com/artifact/org.cardanofoundation/cf-rewards-calculation\"\u003e\u003cimg alt=\"Publish\" src=\"https://github.com/cardano-foundation/cf-java-rewards-calculation/actions/workflows/publish.yaml/badge.svg?branch=main\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://cardano-foundation.github.io/cf-java-rewards-calculation/report-latest/treasury_calculation.html\"\u003e\u003cimg alt=\"Report\" src=\"https://github.com/cardano-foundation/cf-java-rewards-calculation/actions/workflows/report.yaml/badge.svg?branch=main\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://conventionalcommits.org\"\u003e\u003cimg alt=\"conventionalcommits\" src=\"https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/License-MIT-green.svg\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://discord.gg/4WVNHgQ7bP\"\u003e\u003cimg alt=\"Discord\" src=\"https://img.shields.io/discord/1022471509173882950?label=Discord\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nThis project is aims to target *multiple goals*. First of all, it tries to *re-implement the cardano ledger rules* for calculating \nthe [ADA pots](https://cexplorer.io/pot) (Treasury, Reserves, Rewards, Deposits, Utxo, Fees), as well as the rewards for stake pool operators and delegators. \nThe second goal is to use this implementation to *[validate the rewards calculation](https://cardano-foundation.github.io/cf-java-rewards-calculation/report-latest/treasury_calculation.html)* of the Cardano blockchain by providing a *different implementation of the [ledger specification](https://github.com/IntersectMBO/cardano-ledger?tab=readme-ov-file#cardano-ledger)*.\nThe third goal is to *provide a library* that can be used in other project (such as [yaci-store](https://github.com/bloxbean/yaci-store)) to serve the rewards data *independently of [DB Sync](https://github.com/IntersectMBO/cardano-db-sync)*. \nLast but not least, this project could also be used to *understand the influence of protocol parameters* and the flow of ADA through an interactive report.\n\n## 🧪 Test Reports\n\nTo ensure the stability and reliability of this project, unit tests have been implemented. By clicking on the link below, you can access the detailed test report.\nWe also generate for each version of this project calculation reports. These reports are generated by the unit tests and contain the calculation results compared to the actual values.\n\n📈 [Treasury Calculation Report](https://cardano-foundation.github.io/cf-java-rewards-calculation/report-latest/treasury_calculation.html)\n📊 [Coverage Report](https://cardano-foundation.github.io/cf-java-rewards-calculation/coverage-report/)\n\n```mermaid\nflowchart\n    A[Total Transaction Fees \u003cbr /\u003eat Epoch n] --\u003e B[Total Reward Pot \u003cbr /\u003eat Epoch n]\n    B --\u003e | treasuryGrowthRate | C[Treasury]\n    B --\u003e | 1 - treasuryGrowthRate | D[Stake Pool Rewards Pot \u003cbr /\u003eat Epoch n]\n        subgraph ADA_POTS[\" \"]\n        D --\u003e | Unclaimed Rewards | E[\"ADA Reserves\u003cbr /\u003e (monetary expansion) \u003cbr /\u003e Started at ~14B ADA\"]\n        E --\u003e | monetaryExpandRate * Performance of all Stake Pools | B\n        C --\u003e F[Payouts e.g. for \u003cbr /\u003eProject Catalyst]\n        D --\u003e | Rewards Equation\u003cbr /\u003e for Pool 1 | G[Stake Pool 1]\n        D --\u003e | ewards Equation\u003cbr /\u003e for Pool 2 | H[Stake Pool 2]\n        D --\u003e I[...]\n        D --\u003e | Rewards Equation\u003cbr /\u003e for Pool n | J[Stake Pool n]\n        J --\u003e | margin \u0026 minPoolCost | K[Operators]\n        J --\u003e | rewards | L[Delegators]\n        D --\u003e | Rewards going to\u003cbr /\u003e de-registered\u003cbr /\u003e stake addresses | C\n        L \u003c--\u003e | Stake Key Registrations + \u003cbr /\u003e Deregistrations | M[Deposits]\n        K \u003c--\u003e | Stake Pool Registrations + \u003cbr /\u003e Deregistrations | M\n        M --\u003e | Unclaimed Refunds for Retired Pools | C\n        end\n\n    style A fill:#5C8DFF,stroke:#5C8DFF\n    style B fill:#5C8DFF,stroke:#5C8DFF\n    style C fill:#1EC198,stroke:#1EC198\n    style D fill:#5C8DFF,stroke:#5C8DFF\n    style E fill:#1EC198,stroke:#1EC198\n\n    style F fill:#F6C667,stroke:#F6C667\n    style G fill:#F6C667,stroke:#F6C667\n    style H fill:#F6C667,stroke:#F6C667\n    style I fill:#F6C667,stroke:#F6C667\n    style J fill:#F6C667,stroke:#F6C667\n\n    style ADA_POTS fill:#f6f9ff,stroke:#f6f9ff\n```\n\n## 🤓 Interesting Facts\n\nWhile the flowchart above shows the calculation of the Ada pots in general, there are some more aspects that need to be considered:\n\n- The point in time 🕑. The reward calculation starts at slot `(4 * 2160) / 0.05) = 172800` (48h) each epoch. Before the Babbage era, \n  accounts that were de-registered **before** this point in time were not considered for the rewards calculation.  \n  This means that the rewards for the de-registered stake addresses are not considered in the rewards calculation. \n  Those rewards were not distributed and went therefore back to the **reserves**. Accounts that deregistered **after** \n  this point in time, but before the end of the epoch, were considered for the rewards calculation. But as it is not \n  possible to send rewards to a de-registered stake address, the rewards went back to the **treasury**.\n- At the Allegra hard fork, the (pre-Shelley) bootstrap addresses were removed from the UTxO and the Ada contained in them was returned to the reserves.\n- There was a different behavior (pre-Allegra): If a pool reward address had been used for multiple pools,\n  the stake account only received the reward for one of those pools and did also not get any member rewards.\n  This **behavior has changed in mainnet epoch 236** with the Allegra hard fork. Now, the stake account receives the rewards for all pools (including member rewards).\n- Transaction fees and a part of the reserve is used to build the total reward pot. It is often mentioned that\n  the monetary expansion rate (protocol parameter) is used to calculate the part coming from the reserves.\n  While this is true, the actual calculation is a multiplication of the monetary expansion rate and the performance of all stake pools `eta`.\n  `Eta` is the ratio of the blocks produced **by pools** in an epoch and the expected blocks `(432000 slots per epoch / 20 sec per block = 21600)`.\n  With beginning of Shelly the blocks were produced by OBFT nodes and not by pools. Therefore, the performance of all stake pools would be 0.\n  The decentralization parameter `d` has been introduced to slightly increase the amount of **expected blocks produced by pools**.\n  In the time when `d` was above 0.8 `eta` was set to 1.0. `d` decreased over time from 1.0 to 0.0 and disappeared completely with the Vasil hard fork.\n- The pool deposit is currently 500 Ada. This deposit will be returned (on the next epoch boundary) to the pool reward address when the pool is retired.\n  However, if the deposit could not be returned (e.g. because the pool reward address is de-registered), the **deposit will be added to the treasury** instead.\n- Pool updates override pool deregistrations. This means that if a pool is updated before the end of the epoch, the pool will not be retired and the deposit will not be returned.\n\n## 🚀 Getting Started\n\nYou can use this project as a library in your own project. The library is available through maven central,\nor you can clone the repository and run the tests or build the library yourself.\n\n#### Maven\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.cardanofoundation\u003c/groupId\u003e\n    \u003cartifactId\u003ecf-rewards-calculation\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nMake sure to have Java 17 installed and run the following commands:\n\n```\ngit clone https://github.com/cardano-foundation/cf-java-rewards-calculation.git\ncd cf-java-rewards-calculation\n./mvnw clean test\n```\n\n## 📦 Usage\n\nIn the near future you can use the calculation part of this repository as a library in your own project as it will be accessible \nthrough maven central.\n\nFor now the structure of the repository is divided in two parts:\n \n- calculation package\n  - [EpochCalculation](calculation/src/main/java/org/cardanofoundation/rewards/calculation/EpochCalculation.java)\n  - [DepositsCalculation](calculation/src/main/java/org/cardanofoundation/rewards/calculation/DepositsCalculation.java)\n  - [PoolRewardsCalculation](calculation/src/main/java/org/cardanofoundation/rewards/calculation/PoolRewardsCalculation.java)\n  - [TreasuryCalculation](calculation/src/main/java/org/cardanofoundation/rewards/calculation/TreasuryCalculation.java)\n\n- validation package\n  - [EpochValidation](validation/src/main/java/org/cardanofoundation/rewards/validation/EpochValidation.java)\n  - [DepositsValidation](validation/src/main/java/org/cardanofoundation/rewards/validation/DepositsValidation.java)\n  - [PoolRewardValidation](validation/src/main/java/org/cardanofoundation/rewards/validation/PoolRewardValidation.java)\n  - [TreasuryValidation](validation/src/main/java/org/cardanofoundation/rewards/validation/TreasuryValidation.java)\n  - ...\n\nWhile the calculation package is used as a pure re-implementation of the ledger specification,\nthe validation package is used to get the needed data (e.g. registration/deregistration certificates, epoch stakes, etc.) \nfrom the data provider and execute the calculation. Furthermore, the validation package is used to compare the calculated\nvalues with the actual values using DB Sync as ground truth.\n\n#### Data Provider\n\nThe pool rewards calculation and also the treasury calculation requires a data provider to perform the calculation.\nThis repository offers different data providers and also an interface if you want to add your own provider. The following data providers are available:\n\n - [Koios Data Provider](validation/src/main/java/org/cardanofoundation/rewards/validation/data/provider/KoiosDataProvider.java)\n - [JSON Data Provider](validation/src/main/java/org/cardanofoundation/rewards/validation/data/provider/JsonDataProvider.java)\n - [DbSync Data Provider](validation/src/main/java/org/cardanofoundation/rewards/validation/data/provider/DbSyncDataProvider.java)\n\n#### Data Fetcher\n\nThe data fetcher is used to fetch the data from the data provider and put it into local json files.\nThese files can be used to perform the calculation using the JSON Data Provider. The following data fetchers are available:\n\n - [Koios Data Fetcher](validation/src/main/java/org/cardanofoundation/rewards/validation/data/fetcher/KoiosDataFetcher.java)\n - [DbSync Data Fetcher](validation/src/main/java/org/cardanofoundation/rewards/validation/data/fetcher/DbSyncDataFetcher.java)\n\nTo make the application fetching the data, create an `.env` file with the following content in the [validation resources folder](validation/src/main/resources/.env):\n\n```\nSPRING_PROFILES_ACTIVE=db-sync\n\nRUN_MODE=fetch\nOVERWRITE_EXISTING_DATA=false\nDATA_FETCHER_START_EPOCH=\u003cstart-epoch\u003e\nDATA_FETCHER_END_EPOCH=\u003cend-epoch\u003e\nDATA_FETCHER_SKIP_VALIDATION_DATA=\u003ctrue|false\u003e\n\nPOSTGRES_USER=\u003cusername\u003e\nPOSTGRES_PASSWORD=\u003cpassword\u003e\nPOSTGRES_DB=cexplorer\n\nJSON_DATA_SOURCE_FOLDER=/path/to/your/rewards-calculation-test-data\n```\n\u003e [!NOTE]\n\u003e️ The actual rewards data will also be fetched when setting DATA_FETCHER_SKIP_VALIDATION_DATA=false, but it is only used from the validator and not within the calculation itself.`\n  \n#### Data Plotter\n\nThe data plotter is used to generate the report. The following data plotters are available:\n\n - [Koios Data Plotter](./validation/src/main/java/org/cardanofoundation/rewards/validation/data/plotter/JsonDataPlotter.java)\n\nTo use the application to make the report, create an `.env` file with the following content in the [validation resources folder](validation/src/main/resources/.env):\n\n```\nSPRING_PROFILES_ACTIVE=json\nRUN_MODE=plot\nJSON_DATA_SOURCE_FOLDER=/path/to/your/rewards-calculation-test-data\n```\n\n## 🫡 Roadmap\n - [ ] Enhance reporting and add values for the other pots as well. Display the flow of Ada within an epoch\n - [ ] Add a `/docs` folder containing parsable Markdown files to explain MIR certificates and edge cases\n - [X] Provide a library through maven central to use the calculation in other projects\n - [X] Find out the root cause of the difference between the actual rewards and the calculated rewards beginning with epoch 350\n - [X] Include MIR certificates\n - [X] Calculate member and operator rewards\n - [X] Add deposits and utxo pot\n - [X] Calculate unclaimed rewards that need to go back to the reserves\n - [X] Put rewards to unregistered stake addresses into the treasury\n\n## 📖 Sources\n - [Shelley Cardano Delegation Specification](https://github.com/input-output-hk/cardano-ledger/releases/download/cardano-ledger-spec-2023-04-03/shelley-ledger.pdf)\n - [Shelley Cardano Ledger Specification](https://github.com/input-output-hk/cardano-ledger/releases/download/cardano-ledger-spec-2023-04-03/shelley-ledger.pdf)\n - [Protocol Parameters - CIP-0009](https://cips.cardano.org/cips/cip9/#updatableprotocolparameters)\n - Beavr Cardano Stake Pool: [How is the Rewards Pot (R) Calculated](https://archive.ph/HQfoV/fb8166e31d2bf61d3d6ca769e7785f2a96530f8e.webp)\n - [History of Protocol Parameters](https://beta.explorer.cardano.org/en/protocol-parameters/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcardano-foundation%2Fcf-java-rewards-calculation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcardano-foundation%2Fcf-java-rewards-calculation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcardano-foundation%2Fcf-java-rewards-calculation/lists"}