Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update API docs on saturation, rewards, and relative stake #2162

Merged
merged 1 commit into from
Sep 22, 2020
Merged

Update API docs on saturation, rewards, and relative stake #2162

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 21 additions & 3 deletions specifications/api/swagger.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -723,12 +723,26 @@ x-stakePoolMargin: &stakePoolMargin

May be omitted if the wallet hasn't found the pool's registration cerificate yet.

x-jormungandrStakePoolSaturation: &jormungandrStakePoolSaturation
Anviking marked this conversation as resolved.
Show resolved Hide resolved
type: number
minimum: 0
description: |
Saturation-level of the pool based on the desired number of pools aimed by the network.
A value above `1` indicates that the pool is saturated.
example: 0.74

x-stakePoolSaturation: &stakePoolSaturation
type: number
minimum: 0
description: |
Saturation-level of the pool based on the desired number of pools aimed by the network.
A value above `1` indicates that the pool is saturated.

The `non_myopic_member_rewards` take oversaturation into account, as specified by the [specs](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec).
Anviking marked this conversation as resolved.
Show resolved Hide resolved

The saturation is based on the live `relative_stake`. The saturation at the end of epoch e,
will affect the rewards paid out at the end of epoch e+3.
Anviking marked this conversation as resolved.
Show resolved Hide resolved

example: 0.74

x-stakePoolDesirability: &stakePoolDesirability
Expand Down Expand Up @@ -760,11 +774,15 @@ x-stakePoolMetrics: &stakePoolMetrics
non_myopic_member_rewards: *nonMyopicMemberRewards
relative_stake:
<<: *percentage
description: The pools stake compared to the stake of all pools.
description: |
The live pool stake relative to the *total* stake.
Anviking marked this conversation as resolved.
Show resolved Hide resolved

For more details, see the section "Relative Stake: Active vs Total" in
[Design Specification for Delegation and Incentives in Cardano](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec).
saturation: *stakePoolSaturation
produced_blocks:
<<: *numberOfBlocks
description: Number of blocks produced by a given stake pool
description: Number of blocks produced by a given stake pool in its lifetime.
Anviking marked this conversation as resolved.
Show resolved Hide resolved

x-jormungandrStakePoolMetrics: &jormungandrStakePoolMetrics
type: object
Expand Down Expand Up @@ -968,7 +986,7 @@ components:
cost: *jormungandrStakePoolCost
margin: *jormungandrStakePoolMargin
metadata: *jormungandrStakePoolMetadata
saturation: *stakePoolSaturation
saturation: *jormungandrStakePoolSaturation
desirability: *stakePoolDesirability

ApiFee: &ApiFee
Expand Down