Copyright	© 2022 IOHK
License	Apache-2.0
Safe Haskell	None
Language	Haskell2010

Cardano.Pool.Rank

Contents

Pool information
Ranking formulas
Redelegation warning
Legacy metrics

Description

This module provides tools to estimate pool rewards for the purpose of ranking pools.

Synopsis

data RewardInfoPool = RewardInfoPool {
- stakeRelative :: Percentage
- ownerPledge :: Coin
- ownerStake :: Coin
- ownerStakeRelative :: Percentage
- cost :: Coin
- margin :: Percentage
- performanceEstimate :: Double
}
data RewardParams = RewardParams {
- nOpt :: Int
- a0 :: Rational
- r :: Coin
- totalStake :: Coin
}
data StakePoolsSummary = StakePoolsSummary {
- rewardParams :: RewardParams
- pools :: Map PoolId RewardInfoPool
}
poolSaturation :: RewardParams -> RewardInfoPool -> Double
optimalRewards :: RewardParams -> Percentage -> Rational -> Coin
currentROS :: RewardParams -> RewardInfoPool -> Coin -> Percentage
saturationROS :: RewardParams -> RewardInfoPool -> Percentage
data RedelegationWarning
- = AllGood
- | TooFewBlocks
- | OtherPoolsBetter
redelegationWarning :: EpochNo -> ( RewardInfoPool , Coin ) -> StakePoolsSummary -> EpochNo -> RedelegationWarning
nonMyopicMemberReward :: RewardParams -> RewardInfoPool -> Bool -> Coin -> Coin
desirability :: RewardParams -> RewardInfoPool -> Coin
data PoolScore = PoolScore {
- _desirability :: Coin
- _nonMyopicMemberReward :: Coin
}
scorePools :: Ord poolId => RewardParams -> Map poolId ( RewardInfoPool , a) -> Coin -> Map poolId ( PoolScore , RewardInfoPool , a)

Pool information

NOTE [RewardEpochs]

We need to be careful to show the right information at the right time in order prevent manipulation of the proof-of-stake (PoS) protocol.

In particular, we need to show those pool costs, margins, and owner stakes that will affect the rewards for a delegation choice made at the present moment.

The reward cycle is illustrated in Section 11.2 of SL-D1, here a brief sketch.

                    mark   set     go
                  +------.------.------
                  |
    |e0----|e1----|e2----|e3----|e4----|e5----|
              ^
          we are here

We imagine that we are in epoch e1 , and choose to delegate to a pool. At the end of epoch e1 , a snapshot of the stake distribution will be taken. This snapshot will be labeled "mark" during epoch e2 , "set" during epoch e3 , and "go" during epoch e4 . Blocks will be produced randomly according to this stake distribution when it is labeled "set", i.e. in epoch e3 . Rewards for this block production will be computed when this stake distribution is labeled "go", i.e. during epoch e4 , and these rewards will paid out at the beginning of epoch e5 .

The owner stake is part of the snapshot taken at the end of epoch e1 . If the pool is newly registered, its cost, margin and pledge are also immediately available in epoch e1 . However, if a pool re-registers, the changes to its cost, margin and pledge will not be visible until the next epoch; put differently, the rewards for the stake snapshot taken at the end of epoch e1 will only depend on changes to cost, margin, and pledge that the pool owner initiated in epoch e0 . This prevents pool owners from duping delegators by changing pool costs during an epoch. However, the pool owner could still choose to undelegate his stake, and fail to meet his pledge at the end of epoch e1 , which results in zero rewards paid out at the beginning of e5 .

To summarize, in order to make an informed delegation choice during epoch e1 , the delegator needs to know RewardInfoPool where

stakeRelative , ownerStake , and ownerStakeRelative are taken at the time of decision (in epoch e1 ).
ownerPledge , margin , cost are the values of the last pool registration certificate from epoch e0 in case of an update, or from epoch e1 in case of a newly created pool.

For the performanceEstimate , it's best to estimate it from recent pool block production using functions provided here.

data RewardInfoPool Source #

Information need for the computation of rewards, such as the stake currently delegated to a pool, or the pool cost and margin.

Constructors

RewardInfoPool
Fields stakeRelative :: Percentage sigma = pool stake / total stake ownerPledge :: Coin pledge of pool owner(s) ownerStake :: Coin absolute stake delegated by pool owner(s) ownerStakeRelative :: Percentage s = owner stake / total stake cost :: Coin margin :: Percentage performanceEstimate :: Double

Instances

Instances details

Eq RewardInfoPool Source #
Instance details Defined in Cardano.Pool.Rank Methods (==) :: RewardInfoPool -> RewardInfoPool -> Bool Source # (/=) :: RewardInfoPool -> RewardInfoPool -> Bool Source #
Show RewardInfoPool Source #
Instance details Defined in Cardano.Pool.Rank Methods showsPrec :: Int -> RewardInfoPool -> ShowS Source # show :: RewardInfoPool -> String Source # showList :: [ RewardInfoPool ] -> ShowS Source #
Buildable RewardInfoPool Source #
Instance details Defined in Cardano.Pool.Rank Methods build :: RewardInfoPool -> Builder Source #

data RewardParams Source #

Global parameters used for computing rewards

Constructors

RewardParams
Fields nOpt :: Int desired number of stake pools a0 :: Rational influence of the pool owner's pledge on rewards r :: Coin Total rewards available for the given epoch totalStake :: Coin Maximum lovelace supply minus treasury

Instances

Instances details

Eq RewardParams Source #
Instance details Defined in Cardano.Pool.Rank Methods (==) :: RewardParams -> RewardParams -> Bool Source # (/=) :: RewardParams -> RewardParams -> Bool Source #
Show RewardParams Source #
Instance details Defined in Cardano.Pool.Rank Methods showsPrec :: Int -> RewardParams -> ShowS Source # show :: RewardParams -> String Source # showList :: [ RewardParams ] -> ShowS Source #
Buildable RewardParams Source #
Instance details Defined in Cardano.Pool.Rank Methods build :: RewardParams -> Builder Source #

data StakePoolsSummary Source #

Summary of stake distribution and stake pools obtained from network.

Constructors

StakePoolsSummary
Fields rewardParams :: RewardParams pools :: Map PoolId RewardInfoPool

Instances

Instances details

Eq StakePoolsSummary Source #
Instance details Defined in Cardano.Pool.Rank Methods (==) :: StakePoolsSummary -> StakePoolsSummary -> Bool Source # (/=) :: StakePoolsSummary -> StakePoolsSummary -> Bool Source #
Show StakePoolsSummary Source #
Instance details Defined in Cardano.Pool.Rank Methods showsPrec :: Int -> StakePoolsSummary -> ShowS Source # show :: StakePoolsSummary -> String Source # showList :: [ StakePoolsSummary ] -> ShowS Source #
Buildable StakePoolsSummary Source #
Instance details Defined in Cardano.Pool.Rank Methods build :: StakePoolsSummary -> Builder Source #

Ranking formulas

poolSaturation :: RewardParams -> RewardInfoPool -> Double Source #

The saturation of a pool is the ratio of the current pool stake to the fully saturated stake.

optimalRewards :: RewardParams -> Percentage -> Rational -> Coin Source #

Optimal rewards for a stake pool according to Eq.(2) of Section 5.5.3 in SL-D1.

optimalRewards s sigma

NOTE: This computation uses Double internally and is only suitable for the purpose of ranking, not for computing actual monetary rewards.

currentROS :: RewardParams -> RewardInfoPool -> Coin -> Percentage Source #

The yearly rate of return per unit of stake, assuming that the pool's stake remains at the same level. Rewards compound every epoch.

saturationROS :: RewardParams -> RewardInfoPool -> Percentage Source #

The (yearly) return per unit of stake for a pool that has reached saturation.

Redelegation warning

data RedelegationWarning Source #

Constructors

AllGood
TooFewBlocks
OtherPoolsBetter

Instances

Instances details

Eq RedelegationWarning Source #
Instance details Defined in Cardano.Pool.Rank Methods (==) :: RedelegationWarning -> RedelegationWarning -> Bool Source # (/=) :: RedelegationWarning -> RedelegationWarning -> Bool Source #
Show RedelegationWarning Source #
Instance details Defined in Cardano.Pool.Rank Methods showsPrec :: Int -> RedelegationWarning -> ShowS Source # show :: RedelegationWarning -> String Source # showList :: [ RedelegationWarning ] -> ShowS Source #
Buildable RedelegationWarning Source #
Instance details Defined in Cardano.Pool.Rank Methods build :: RedelegationWarning -> Builder Source #

redelegationWarning Source #

Arguments

:: EpochNo	Epoch when delegation was made
-> ( RewardInfoPool , Coin )	( Info about the pool that we delegate to , absolute stake that we delegate )
-> StakePoolsSummary	Current summary of all stake pools (for comparison)
-> EpochNo	Current epoch
-> RedelegationWarning

Compute redelegation warning from current pool performance.

Note: This function uses the performanceEstimate for the pool that we delegate to, but ignores this fields for the argument StakePoolsSummary .

Legacy metrics

nonMyopicMemberReward Source #

Arguments

:: RewardParams
-> RewardInfoPool
-> Bool	The pool ranks in the top `nOpt` pools
-> Coin	stake that the member wants to delegate
-> Coin

Non-Myopic Pool Member Rewards according to Eq.(3) of Section 5.6.4 in SL-D1.

desirability :: RewardParams -> RewardInfoPool -> Coin Source #

The desirabilty of a pool is equal to the total member rewards at saturation IF the owner meets their pledge.

data PoolScore Source #

Constructors

PoolScore
Fields _desirability :: Coin _nonMyopicMemberReward :: Coin

scorePools Source #

Arguments

:: Ord poolId
=> RewardParams
-> Map poolId ( RewardInfoPool , a)
-> Coin	Stake that the user wants to delegate
-> Map poolId ( PoolScore , RewardInfoPool , a)

Compute the desirability and non-myopic rewards for all pools.

To compute the non-myopic rewards, we need to know all pools in order to rank them by desirability, and we need to know the stake that the user wants to delegate.