Merge pull request #5 from cardano-foundation/release-please--branches--main

chore(main): release 0.0.2-SNAPSHOT

Author: fabianbormann

README.md

@@ -10,21 +10,33 @@
 
 This java project is used to calculate the rewards of the Cardano network. It aims to be both an edge case documentation and formula implementation.
 
+## 🧪 Test Reports
+
+To 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.
+We 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.
+
 📈 [Treasury Calculation Report](https://cardano-foundation.github.io/cf-java-rewards-calculation/report-latest/treasury_calculation.html)
+📊 [Coverage Report](https://cardano-foundation.github.io/cf-java-rewards-calculation/coverage-report/)
 
 ```mermaid
 flowchart
     A[Total Transaction Fees <br />at Epoch n] --> B[<a href='https://github.com/cardano-foundation/cf-java-rewards-calculation/blob/a794130dc0e320426725a58b8b15f1fbe726b2de/src/main/java/org/cardanofoundation/rewards/calculation/TreasuryCalculation.java#L42'>Total Reward Pot <br />at Epoch n</a/>]
-    B --> | <a href='https://cips.cardano.org/cips/cip9/#updatableprotocolparameters'>treasuryGrowthRate</a> | C[<a href='https://github.com/cardano-foundation/cf-java-rewards-calculation/blob/a794130dc0e320426725a58b8b15f1fbe726b2de/src/main/java/org/cardanofoundation/rewards/calculation/TreasuryCalculation.java#L17'>Treasury</a/>]
-    B --> | 1 - <a href='https://cips.cardano.org/cips/cip9/#updatableprotocolparameters'>treasuryGrowthRate</a> | D[<a href='https://github.com/cardano-foundation/cf-java-rewards-calculation/blob/a794130dc0e320426725a58b8b15f1fbe726b2de/src/test/java/org/cardanofoundation/rewards/calculation/PoolRewardCalculationTest.java#L63'>Stake Pool Rewards Pot <br />at Epoch n</a/>]
+    B --> | <b><i><a href='https://cips.cardano.org/cips/cip9/#updatableprotocolparameters'>treasuryGrowthRate</a></b></i> | C[<a href='https://github.com/cardano-foundation/cf-java-rewards-calculation/blob/a794130dc0e320426725a58b8b15f1fbe726b2de/src/main/java/org/cardanofoundation/rewards/calculation/TreasuryCalculation.java#L17'>Treasury</a/>]
+    B --> | 1 - <b><i><a href='https://cips.cardano.org/cips/cip9/#updatableprotocolparameters'>treasuryGrowthRate</a></b></i> | D[<a href='https://github.com/cardano-foundation/cf-java-rewards-calculation/blob/a794130dc0e320426725a58b8b15f1fbe726b2de/src/test/java/org/cardanofoundation/rewards/calculation/PoolRewardCalculationTest.java#L63'>Stake Pool Rewards Pot <br />at Epoch n</a/>]
     subgraph ADA_POTS[" "]
     D --> | Unclaimed Rewards | E["ADA Reserves<br /> (monetary expansion) <br /> Started at ~14B ADA"]
-    E --> | <a href='https://cips.cardano.org/cips/cip9/#updatableprotocolparameters'>monetaryExpandRate</a> * <a href='https://github.com/cardano-foundation/cf-java-rewards-calculation/blob/main/src/main/java/org/cardanofoundation/rewards/calculation/PoolRewardCalculation.java#L19'>apparent performance of all stake pools</a> | B
+    E --> | <b><i><a href='https://cips.cardano.org/cips/cip9/#updatableprotocolparameters'>monetaryExpandRate</a></b></i> * <a href='https://github.com/cardano-foundation/cf-java-rewards-calculation/blob/main/src/main/java/org/cardanofoundation/rewards/calculation/PoolRewardCalculation.java#L19'>Performance of all Stake Pools</a> | B
     C --> F[Payouts e.g. for <br /><a href='https://projectcatalyst.io/'>Project Catalyst</a>]
     D --> | <a href='https://github.com/cardano-foundation/cf-java-rewards-calculation/blob/a794130dc0e320426725a58b8b15f1fbe726b2de/src/main/java/org/cardanofoundation/rewards/calculation/PoolRewardCalculation.java#L87'>Rewards Equation<br /> for Pool 1</a> | G[Stake Pool 1]
     D --> | <a href='https://github.com/cardano-foundation/cf-java-rewards-calculation/blob/a794130dc0e320426725a58b8b15f1fbe726b2de/src/main/java/org/cardanofoundation/rewards/calculation/PoolRewardCalculation.java#L87'>Rewards Equation<br /> for Pool 2</a> | H[Stake Pool 2]
     D --> I[...]
     D --> | <a href='https://github.com/cardano-foundation/cf-java-rewards-calculation/blob/a794130dc0e320426725a58b8b15f1fbe726b2de/src/main/java/org/cardanofoundation/rewards/calculation/PoolRewardCalculation.java#L87'>Rewards Equation<br /> for Pool n</a> | J[Stake Pool n]
+    J --> | <b><i>margin & minPoolCost</i></b> | K[Operators]
+    J --> | <b><i>rewards</b></i> | L[Delegators]
+    D --> | Capped Pool Rewards | C
+    L <--> | Stake Key Registration & <br /> Deregistration | M[Deposits]
+    K <--> | Stake Pool Registration & <br /> Deregistration | M
+    M --> | Unclaimed Refunds for Retired Pools | C
     end
 
     style A fill:#5C8DFF,stroke:#5C8DFF
@@ -56,13 +68,17 @@ cd cf-java-rewards-calculation
 ./mvnw clean test
 ```
 
-## 🧪 Test Reports
-
-To 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.
-
-📊 [Coverage Report](https://cardano-foundation.github.io/cf-java-rewards-calculation/coverage-report/)
+## 🫡 Todo
+ - [ ] Include MIR certificates
+ - [ ] Add a `/docs` folder containing parsable Markdown files to explain MIR certificates and edge cases
+ - [ ] Implement "The difference between the maximal amount and the actual amount received is added to the amount moved to the treasury" (shelley-ledger.pdf p.65)
+ - [ ] Enhance reporting and add values for the other pots as well. Include information from the `/docs` folder
+ - [ ] Add member and operator reward calculation as well as the deposits pot
+ - [ ] Calculate unclaimed rewards that need to go back to the reserves
 
 ## 📖 Sources
-
+ - [Shelley Cardano Delegation Specification](https://github.com/input-output-hk/cardano-ledger/releases/download/cardano-ledger-spec-2023-04-03/shelley-ledger.pdf)
+ - [Shelley Cardano Ledger Specification](https://github.com/input-output-hk/cardano-ledger/releases/download/cardano-ledger-spec-2023-04-03/shelley-ledger.pdf)
+ - [Protocol Parameters - CIP-0009](https://cips.cardano.org/cips/cip9/)
  - Beavr Cardano Stake Pool: [How is the Rewards Pot (R) Calculated](https://archive.ph/HQfoV/fb8166e31d2bf61d3d6ca769e7785f2a96530f8e.webp)
- - Protocol Parameters: https://beta.explorer.cardano.org/en/protocol-parameters/
+ - [History of Protocol Parameters](https://beta.explorer.cardano.org/en/protocol-parameters/)

src/main/java/org/cardanofoundation/rewards/calculation/PoolRewardCalculation.java

@@ -11,15 +11,17 @@ public class PoolRewardCalculation {
      *
      * hint: shelley-delegation.pdf 3.8.3
      *       As long as we have d >= 0.8, we set the apparent performance of any pool to 1
+     *
+     * See Haskell implementation: https://github.com/input-output-hk/cardano-ledger/blob/64459cc87094331c79d11880e0a4c81b9a721ab0/eras/shelley/impl/src/Cardano/Ledger/Shelley/Rewards.hs#L87C32-L87C44
      */
-    public static double calculateApparentPoolPerformance(final double activePoolStake, final double totalActiveEpochStake, final int blocksMintedByPool, final int totalBlocksInEpoch, final double decentralizationParam) {
+    public static double calculateApparentPoolPerformance(final double activePoolStake, final double totalActiveEpochStake, final int blocksMintedByPool, final int blocksMintedByStakePools, final double decentralizationParam) {
         if (decentralizationParam >= 0.8) {
             return 1.0;
         } else if (activePoolStake == 0.0 || totalActiveEpochStake == 0.0) {
             return 0.0;
         } else {
-            final double blocksMintedInNonOBFTSlots = (double) totalBlocksInEpoch * (1.0 - decentralizationParam);
-            final double relativeBlocksCreatedInEpoch = blocksMintedByPool / blocksMintedInNonOBFTSlots;
+
+            final double relativeBlocksCreatedInEpoch = (double) blocksMintedByPool / (double) blocksMintedByStakePools;
             final double relativeActiveStake = activePoolStake / totalActiveEpochStake;
             return relativeBlocksCreatedInEpoch / relativeActiveStake;
         }
@@ -44,6 +46,8 @@ public static double calculateApparentPoolPerformance(final double activePoolSta
      *          (( sizeOfASaturatedPool - cappedRelativeStake ) / sizeOfASaturatedPool))
      *          / sizeOfASaturatedPool)
      *      )
+     *
+     * See the Haskell implementation: https://github.com/input-output-hk/cardano-ledger/blob/e722881568155fc39550a8dfabda3efeb263a1e5/shelley/chain-and-ledger/executable-spec/src/Shelley/Spec/Ledger/EpochBoundary.hs#L111
      */
     public static double calculateOptimalPoolReward(double totalAvailableRewards, int optimalPoolCount, double influence, double relativeStakeOfPool, double relativeStakeOfPoolOwner) {
 
@@ -53,20 +57,17 @@ public static double calculateOptimalPoolReward(double totalAvailableRewards, in
 
         // R / (1 + a0)
         // "R are the total available rewards for the epoch (in ada)." (shelley-delegation.pdf 5.5.3)
-        double totalAvailableRewardsInAda = Math.round(totalAvailableRewards);
-        double rewardsDividedByOnePlusInfluence = totalAvailableRewardsInAda / (1 + influence);
-
-        // s' * a0
-        double influenceOfOwner = cappedRelativeStakeOfPoolOwner * influence;
+        double rewardsDividedByOnePlusInfluence = totalAvailableRewards / (1 + influence);
 
-        // s'((z0 - o')/ z0)
-        double relativeStakeOfSaturatedPool = cappedRelativeStakeOfPoolOwner * ((sizeOfASaturatedPool - cappedRelativeStake) / sizeOfASaturatedPool);
+        // (z0 - sigma') / z0
+        double relativeStakeOfSaturatedPool = (sizeOfASaturatedPool - cappedRelativeStake) / sizeOfASaturatedPool;
 
-        // o' - ((s' * (z0 - o')/ z0) / z0)
-        double saturatedPoolWeight = cappedRelativeStake - (relativeStakeOfSaturatedPool / sizeOfASaturatedPool);
+        // (sigma' - s' * relativeStakeOfSaturatedPool) / z0
+        double saturatedPoolWeight = (cappedRelativeStake - cappedRelativeStakeOfPoolOwner * relativeStakeOfSaturatedPool) / sizeOfASaturatedPool;
 
-        // R/(1+a0) (s'a0(o' - (s'(z0 - o') / z0)) / z0)
-        return rewardsDividedByOnePlusInfluence * (cappedRelativeStake + influenceOfOwner * saturatedPoolWeight);
+        // R / (1+a0) * (sigma' + s' * a0 * saturatedPoolWeight)
+        return Math.floor(rewardsDividedByOnePlusInfluence *
+                (cappedRelativeStake + cappedRelativeStakeOfPoolOwner * influence * saturatedPoolWeight));
     }
 
     /*
@@ -76,27 +77,4 @@ public static double calculateOptimalPoolReward(double totalAvailableRewards, in
     public static double calculatePoolReward(double optimalPoolReward, double poolPerformance) {
         return optimalPoolReward * poolPerformance;
     }
-
-    /*
-     *  Calculate the total reward pot (R) with transposing the equation from above:
-     */
-    public static double calculateRewardPotByOptimalPoolReward(double poolReward, int optimalPoolCount, double influence, double relativeStakeOfPool, double relativeStakeOfPoolOwner, double poolPerformance) {
-
-        double sizeOfASaturatedPool = 1.0 / optimalPoolCount;
-        double cappedRelativeStake = Math.min(sizeOfASaturatedPool, relativeStakeOfPool);
-        double cappedRelativeStakeOfPoolOwner = Math.min(sizeOfASaturatedPool, relativeStakeOfPoolOwner);
-
-        // s' * a0
-        double influenceOfOwner = cappedRelativeStakeOfPoolOwner * influence;
-
-        // s'((z0 - o')/ z0)
-        double relativeStakeOfSaturatedPool = cappedRelativeStakeOfPoolOwner * ((sizeOfASaturatedPool - cappedRelativeStake) / sizeOfASaturatedPool);
-
-        // o' - (s' * (z0 - o')/ z0) / z0)
-        double saturatedPoolWeight = (cappedRelativeStake - relativeStakeOfSaturatedPool) / sizeOfASaturatedPool;
-
-
-        double poolWeightsWithPerformance = poolPerformance * (cappedRelativeStake + influenceOfOwner * saturatedPoolWeight);
-        return ((1.0 + influence) * poolReward) / poolWeightsWithPerformance;
-    }
 }

src/main/java/org/cardanofoundation/rewards/calculation/TreasuryCalculation.java

@@ -1,12 +1,16 @@
 package org.cardanofoundation.rewards.calculation;
 
 import org.cardanofoundation.rewards.data.provider.DataProvider;
-import org.cardanofoundation.rewards.entity.AdaPots;
-import org.cardanofoundation.rewards.entity.Epoch;
-import org.cardanofoundation.rewards.entity.ProtocolParameters;
-import org.cardanofoundation.rewards.entity.TreasuryCalculationResult;
+import org.cardanofoundation.rewards.data.provider.JsonDataProvider;
+import org.cardanofoundation.rewards.data.provider.KoiosDataProvider;
+import org.cardanofoundation.rewards.entity.*;
+import org.cardanofoundation.rewards.enums.AccountUpdateAction;
 
-import static org.cardanofoundation.rewards.constants.RewardConstants.EXPECTED_SLOT_PER_EPOCH;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.List;
+
+import static org.cardanofoundation.rewards.constants.RewardConstants.*;
 import static org.cardanofoundation.rewards.util.CurrencyConverter.lovelaceToAda;
 
 public class TreasuryCalculation {
@@ -30,7 +34,7 @@ public static double calculateTreasury(double treasuryGrowRate, double rewardPot
   public static double calculateTotalRewardPotWithEta(double monetaryExpandRate, int totalBlocksInEpochByPools,
                                                          double decentralizationParameter, double reserve, double fee) {
     double eta = calculateEta(totalBlocksInEpochByPools, decentralizationParameter);
-    return Math.floor(reserve * monetaryExpandRate * eta + fee);
+    return Math.floor(reserve * monetaryExpandRate * eta) + fee;
   }
 
   /*
@@ -98,17 +102,9 @@ public static TreasuryCalculationResult calculateTreasuryForEpoch(int epoch, Dat
     double treasuryForCurrentEpoch = TreasuryCalculation.calculateTreasury(
             treasuryGrowthRate, rewardPot, treasuryInPreviousEpoch);
 
-    /*
-      TODO: "For each retiring pool, the refund for the pool registration deposit is added to the
-       pool's registered reward account, provided the reward account is still registered." -
-       https://github.com/input-output-hk/cardano-ledger/blob/9e2f8151e3b9a0dde9faeb29a7dd2456e854427c/eras/shelley/formal-spec/epoch.tex#L546C9-L547C87
-
-
-       int retiredPoolsWithDeregisteredRewardAddress = koiosDataProvider.countRetiredPoolsWithDeregisteredRewardAddress(epoch - 1);
-
-       BigDecimal deposit = new BigDecimal(DEPOSIT_POOL_REGISTRATION_IN_ADA);
-       treasuryForCurrentEpoch = treasuryForCurrentEpoch.add(deposit.multiply(new BigDecimal(retiredPoolsWithDeregisteredRewardAddress)));
-    */
+    // The sum of all the refunds attached to unregistered reward accounts are added to the
+    // treasury (see: Pool Reap Transition, p.53, figure 40, shely-ledger.pdf)
+    treasuryForCurrentEpoch += TreasuryCalculation.calculateUnclaimedRefundsForRetiredPools(epoch, dataProvider);
 
     return TreasuryCalculationResult.builder()
             .calculatedTreasury(treasuryForCurrentEpoch)
@@ -117,4 +113,44 @@ public static TreasuryCalculationResult calculateTreasuryForEpoch(int epoch, Dat
             .totalRewardPot(rewardPot)
             .build();
   }
+
+  /*
+    "For each retiring pool, the refund for the pool registration deposit is added to the
+    pool's registered reward account, provided the reward account is still registered." -
+    https://github.com/input-output-hk/cardano-ledger/blob/9e2f8151e3b9a0dde9faeb29a7dd2456e854427c/eras/shelley/formal-spec/epoch.tex#L546C9-L547C87
+   */
+  public static Double calculateUnclaimedRefundsForRetiredPools(int epoch, DataProvider dataProvider) {
+    List<PoolDeregistration> retiredPools = dataProvider.getRetiredPoolsInEpoch(epoch);
+
+    double refunds = 0.0;
+
+    if (retiredPools.size() > 0) {
+      // The deposit will pay back one epoch later
+      List<AccountUpdate> accountUpdates = dataProvider.getAccountUpdatesUntilEpoch(
+              retiredPools.stream().map(PoolDeregistration::getRewardAddress).toList(), epoch - 1);
+
+      // Order list by unix block time
+      accountUpdates = accountUpdates.stream().filter(update ->
+              update.getAction().equals(AccountUpdateAction.DEREGISTRATION)
+              || update.getAction().equals(AccountUpdateAction.REGISTRATION)).sorted(
+              Comparator.comparing(AccountUpdate::getUnixBlockTime).reversed()).toList();
+
+      // only hold the latest account update for each reward address
+      // preventing the case of an unregistered reward address becoming registered again
+      List<AccountUpdate> latestAccountUpdates = new ArrayList<>();
+      for (AccountUpdate accountUpdate : accountUpdates) {
+        if (latestAccountUpdates.stream().map(AccountUpdate::getStakeAddress).noneMatch(stakeAddress -> stakeAddress.equals(accountUpdate.getStakeAddress()))) {
+          latestAccountUpdates.add(accountUpdate);
+        }
+      }
+
+      for (AccountUpdate lastAccountUpdate : latestAccountUpdates) {
+        if (lastAccountUpdate.getAction() == AccountUpdateAction.DEREGISTRATION) {
+          refunds += DEPOSIT_POOL_REGISTRATION_IN_LOVELACE;
+        }
+      }
+    }
+
+    return refunds;
+  }
 }