Skip to content

Commit 4174dad

Browse files
KtorZKtorZ
committed
Re-implement and expose intermediate rewards calculation.
 This query used to exists, but was removed and replaced with rewardsProvenance', which does provide far less insightful results. I figured we could re-implement the old query by actually fetching the NewEpochState, and re-running the same calculations. The downside is obviously the time and resources it takes to fetch that state. So I ended up writing a partial CBOR decoder for it, that would skip the entire UTxO set (the largest part of the object) since it isn't actually required for calculations. However, this turned out not so useful because the results are unfortunately encoded and decoded as a strict bytestring at the moment instead of leverage lazy I/O. So we get no benefit from having a lazy decoder. I opened a PR to address the issue ouroboros-network: IntersectMBO/ouroboros-network#5138 So, hopefully, this wasn't all for nothing.
1 parent c3ec666 commit 4174dad

File tree

11 files changed

+571
-24
lines changed

11 files changed

+571
-24
lines changed

‎CHANGELOG.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,14 @@ math: true
1111

1212
#### Added
1313

14-
N/A
14+
- A new query `queryLedgerState/rewardsProvenance` which now re-implements and exposes the intermediate rewards calculation. The query name already exists, but the schema is now different. The previous behaviour can be recovered by using the new `queryLedgerState/stakePoolsPerformances` instead.
1515

1616
#### Changed
1717

1818
- **⚠️ BREAKING-CHANGE ⚠️**: `queryLedgerState/dump` no longer return a hex-encoded CBOR dump as part of the JSON response, but instead, serialise directly to a specified on-disk location.
1919

20+
- **⚠️ BREAKING-CHANGE ⚠️**: `queryLedgerState/rewardsProvenance` has been renamed to `queryLedgerState/stakePoolsPerformances`. The schema remains otherwise unchanged.
21+
2022
#### Removed
2123

2224
N/A

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ See our [Ogmios client starter kit](https://github.com/CardanoSolutions/ogmios-t
7171
`rewardAccountSummaries` | Current delegation settings and rewards of chosen reward accounts.
7272
`rewardsProvenance` | Get details about rewards calculation for the ongoing epoch.
7373
`stakePools` | The list of all pool identifiers currently registered and active, as well as their voting stake.
74+
`stakePoolsPerformances` | Details about pools performances indicators for the ongoing epoch.
7475
`tip` | The current tip the ledger is at. Said differently, the slot number and header hash of the last block that has been processed by the ledger.
7576
`treasuryAndReserves` | The Ada value of the treasury and reserves of the protocol.
7677
`utxo` | Current UTXO, possibly filtered by output reference.

‎docs/content/mini-protocols/local-state-query.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,7 @@ queryLedgerState | Information
116116
`rewardAccountSummaries` | Current delegation settings and rewards of chosen reward accounts.
117117
`rewardsProvenance` | Get details about rewards calculation for the ongoing epoch.
118118
`stakePools` | The list of all currently registered and active stake pools with their current parameters. This query can be made with or without specifying list of target `stakePools`. When no stake pools are provided as parameter, the query returns the list of all stake pools and their parameters from the node.
119+
`stakePoolsPerformances` | Details about pools performances indicators for the ongoing epoch.
119120
`tip` | The current tip the ledger is at. Said differently, the slot number and header hash of the last block that has been processed by the ledger.
120121
`treasuryAndReserves` | The Ada value of the treasury and reserves of the protocol.
121122
`utxo` | Current UTXO, possibly filtered by output reference.
@@ -671,6 +672,15 @@ Be aware that it is possible for an acquire request to fail even if (and in part
671672
}
672673
```
673674

675+
#### stakePoolsPerformances
676+
677+
```json
678+
{
679+
"jsonrpc": "2.0",
680+
"method": "queryLedgerState/stakePoolsPerformances"
681+
}
682+
```
683+
674684
#### treasuryAndReserves
675685

676686
```json

‎docs/static/api/specification.yaml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ info:
3434
- [ledgerState/rewardAccountSummaries](#operation-publish-/?QueryLedgerStateRewardAccountSummaries)
3535
- [ledgerState/rewardsProvenance](#operation-publish-/?QueryLedgerStateRewardsProvenance)
3636
- [ledgerState/stakePools](#operation-publish-/?QueryLedgerStateStakePools)
37+
- [ledgerState/stakePoolsPerformances](#operation-publish-/?QueryLedgerStateStakePoolsPerformances)
3738
- [ledgerState/tip](#operation-publish-/?QueryLedgerStateTip)
3839
- [ledgerState/treasuryAndReserves](#operation-publish-/?QueryLedgerStateTreasuryAndReserves)
3940
- [ledgerState/utxo](#operation-publish-/?QueryLedgerStateUtxo)
@@ -476,6 +477,20 @@ channels:
476477
oneOf:
477478
- $ref: "#/components/messages/QueryLedgerStateStakePoolsResponse"
478479

480+
/?QueryLedgerStateStakePoolsPerformances:
481+
description: |
482+
<p align="right"><a href="#asyncapi">Top ⬆️</a></p>
483+
publish:
484+
operationId: QueryLedgerStateStakePoolsPerformances
485+
message:
486+
oneOf:
487+
- $ref: "#/components/messages/QueryLedgerStateStakePoolsPerformances"
488+
subscribe:
489+
operationId: QueryLedgerStateStakePoolsPerformancesResponse
490+
message:
491+
oneOf:
492+
- $ref: "#/components/messages/QueryLedgerStateStakePoolsPerformancesResponse"
493+
479494
/?QueryLedgerStateTip:
480495
description: |
481496
<p align="right"><a href="#asyncapi">Top ⬆️</a></p>
@@ -842,6 +857,14 @@ components:
842857
payload:
843858
$ref: "/ogmios.json#/properties/QueryLedgerStateStakePools"
844859

860+
QueryLedgerStateStakePoolsPerformances:
861+
title: QueryLedgerStateStakePoolsPerformances
862+
name: "since v6.13.0"
863+
description: |
864+
Query details about pools performances indicators for the ongoing epoch.
865+
payload:
866+
$ref: "/ogmios.json#/properties/QueryLedgerStateStakePoolsPerformances"
867+
845868
QueryLedgerStateTip:
846869
title: QueryLedgerStateTip
847870
name: "since v6.0.0"
@@ -1006,6 +1029,12 @@ components:
10061029
payload:
10071030
$ref: "/ogmios.json#/properties/QueryLedgerStateStakePoolsResponse"
10081031

1032+
QueryLedgerStateStakePoolsPerformancesResponse:
1033+
title: QueryLedgerStateStakePoolsPerformancesResponse
1034+
name: "since v6.13.0"
1035+
payload:
1036+
$ref: "/ogmios.json#/properties/QueryLedgerStateStakePoolsPerformancesResponse"
1037+
10091038
QueryLedgerStateTipResponse:
10101039
title: QueryLedgerStateTipResponse
10111040
name: "since v6.0.0"

‎docs/static/ogmios.json‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
, "QueryLedgerStateRewardAccountSummaries", "QueryLedgerStateRewardAccountSummariesResponse"
2929
, "QueryLedgerStateRewardsProvenance", "QueryLedgerStateRewardsProvenanceResponse"
3030
, "QueryLedgerStateStakePools", "QueryLedgerStateStakePoolsResponse"
31+
, "QueryLedgerStateStakePoolsPerformances", "QueryLedgerStateStakePoolsPerformancesResponse"
3132
, "QueryLedgerStateTip", "QueryLedgerStateTipResponse"
3233
, "QueryLedgerStateTreasuryAndReserves", "QueryLedgerStateTreasuryAndReservesResponse"
3334
, "QueryLedgerStateUtxo", "QueryLedgerStateUtxoResponse"
@@ -689,6 +690,7 @@
689690
, "queryLedgerState/rewardAccountSummaries"
690691
, "queryLedgerState/rewardsProvenance"
691692
, "queryLedgerState/stakePools"
693+
, "queryLedgerState/stakePoolsPerformances"
692694
, "queryLedgerState/utxo"
693695
, "queryLedgerState/tip"
694696
, "queryLedgerState/treasuryAndReserves"
@@ -740,6 +742,7 @@
740742
, "queryLedgerState/rewardAccountSummaries"
741743
, "queryLedgerState/rewardsProvenance"
742744
, "queryLedgerState/stakePools"
745+
, "queryLedgerState/stakePoolsPerformances"
743746
, "queryLedgerState/utxo"
744747
, "queryLedgerState/tip"
745748
, "queryLedgerState/treasuryAndReserves"
@@ -790,6 +793,7 @@
790793
, "queryLedgerState/rewardAccountSummaries"
791794
, "queryLedgerState/rewardsProvenance"
792795
, "queryLedgerState/stakePools"
796+
, "queryLedgerState/stakePoolsPerformances"
793797
, "queryLedgerState/utxo"
794798
, "queryLedgerState/tip"
795799
, "queryLedgerState/treasuryAndReserves"
@@ -1715,6 +1719,56 @@
17151719
]
17161720
}
17171721

1722+
, "QueryLedgerStateStakePoolsPerformances":
1723+
{ "title": "QueryLedgerStateStakePoolsPerformances"
1724+
, "description": "Query details about pools performances indicators for the ongoing epoch."
1725+
, "type": "object"
1726+
, "required": [ "jsonrpc", "method" ]
1727+
, "additionalProperties": false
1728+
, "properties":
1729+
{ "jsonrpc":
1730+
{ "type": "string"
1731+
, "enum": [ "2.0" ]
1732+
}
1733+
, "method":
1734+
{ "type": "string"
1735+
, "enum": [ "queryLedgerState/stakePoolsPerformances" ]
1736+
}
1737+
, "id":
1738+
{ "description": "An arbitrary JSON value that will be mirrored back in the response."
1739+
}
1740+
}
1741+
}
1742+
1743+
, "QueryLedgerStateStakePoolsPerformancesResponse":
1744+
{ "oneOf":
1745+
[ { "title": "QueryLedgerStateStakePoolsPerformancesResponse"
1746+
, "type": "object"
1747+
, "required": [ "jsonrpc", "method", "result" ]
1748+
, "additionalProperties": false
1749+
, "properties":
1750+
{ "jsonrpc":
1751+
{ "type": "string"
1752+
, "enum": [ "2.0" ]
1753+
}
1754+
, "method":
1755+
{ "type": "string"
1756+
, "enum": [ "queryLedgerState/stakePoolsPerformances" ]
1757+
}
1758+
, "result":
1759+
{ "$ref": "ogmios.json#/definitions/StakePoolsPerformances"
1760+
}
1761+
, "id":
1762+
{ "description": "Any value that was set by a client request in the 'id' field."
1763+
}
1764+
}
1765+
}
1766+
, { "$ref": "ogmios.json#/properties/QueryLedgerStateEraMismatch" }
1767+
, { "$ref": "ogmios.json#/properties/QueryLedgerStateUnavailableInCurrentEra" }
1768+
, { "$ref": "ogmios.json#/properties/QueryLedgerStateAcquiredExpired" }
1769+
]
1770+
}
1771+
17181772
, "QueryLedgerStateStakePools":
17191773
{ "title": "QueryLedgerStateStakePools"
17201774
, "description": "Query the list of all stake pools currently registered and active, optionally filtered by ids."
@@ -2919,6 +2973,37 @@
29192973
}
29202974

29212975
, "RewardsProvenance":
2976+
{ "type": "object"
2977+
, "additionalProperties": false
2978+
, "required": [ "totalStake", "activeStake", "fees", "incentives", "treasuryTax", "totalRewards", "efficiency", "pools" ]
2979+
, "properties":
2980+
{ "totalStake": { "$ref": "cardano.json#/definitions/Value<AdaOnly>" }
2981+
, "activeStake": { "$ref": "cardano.json#/definitions/Value<AdaOnly>" }
2982+
, "fees": { "$ref": "cardano.json#/definitions/Value<AdaOnly>" }
2983+
, "incentives": { "$ref": "cardano.json#/definitions/Value<AdaOnly>" }
2984+
, "treasuryTax": { "$ref": "cardano.json#/definitions/Value<AdaOnly>" }
2985+
, "totalRewards": { "$ref": "cardano.json#/definitions/Value<AdaOnly>" }
2986+
, "efficiency": { "$ref": "cardano.json#/definitions/Ratio" }
2987+
, "pools":
2988+
{ "type": "object"
2989+
, "propertyNames": { "$ref": "cardano.json#/definitions/StakePoolId" }
2990+
, "additionalProperties":
2991+
{ "title": "StakePoolRewardsProvenance"
2992+
, "type": "object"
2993+
, "additionalProperties": false
2994+
, "required": [ "relativeStake", "blocksMade", "totalRewards", "leaderReward"]
2995+
, "properties":
2996+
{ "relativeStake": { "$ref": "cardano.json#/definitions/Ratio" }
2997+
, "blocksMade": { "$ref": "cardano.json#/definitions/UInt32" }
2998+
, "totalRewards": { "$ref": "cardano.json#/definitions/Value<AdaOnly>" }
2999+
, "leaderReward": { "$ref": "cardano.json#/definitions/Value<AdaOnly>" }
3000+
}
3001+
}
3002+
}
3003+
}
3004+
}
3005+
3006+
, "StakePoolsPerformances":
29223007
{ "type": "object"
29233008
, "description": "Details about how rewards are calculated for the ongoing epoch."
29243009
, "additionalProperties": false

‎server/ogmios.cabal‎

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎server/package.yaml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ library:
6060
- cardano-ledger-core
6161
- cardano-ledger-mary
6262
- cardano-ledger-shelley
63+
- cardano-ledger-shelley
6364
- cardano-protocol-tpraos
6465
- cardano-slotting
6566
- cardano-strict-containers
@@ -107,20 +108,21 @@ library:
107108
- serialise
108109
- small-steps
109110
- sop-extras
110-
- strict-sop-core
111111
- stm
112+
- strict-sop-core
112113
- text
113114
- time
114115
- time-manager
115116
- transformers
116117
- typed-protocols
117118
- unix
118119
- vector
120+
- vector-map
119121
- wai
120122
- wai-websockets
121123
- warp
122-
- yaml
123124
- websockets
125+
- yaml
124126

125127
executables:
126128
ogmios:

0 commit comments

Comments
 (0)