From cf6df5fa3374deb92539d77358552096018cea5a Mon Sep 17 00:00:00 2001 From: Erik de Castro Lopo Date: Fri, 11 Mar 2022 16:32:34 +1100 Subject: [PATCH 1/2] Add doc/ledger-reward-events.md --- doc/ledger-reward-events.md | 45 +++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 doc/ledger-reward-events.md diff --git a/doc/ledger-reward-events.md b/doc/ledger-reward-events.md new file mode 100644 index 000000000..5d6e17f69 --- /dev/null +++ b/doc/ledger-reward-events.md @@ -0,0 +1,45 @@ +# Ledger Reward Events + +This is an ambit claim of what data the ledger events should provide from the point of view of +`db-sync`. + +## Prologue + +In the context of `db-sync` and the `ledger`, the word "reward" is slightly misleading and should +not be narrowly defined as only being payments of staking rewards, but defined much more broadly as +any and all payments to a stake address. None of these payments are recorded on the block chain as +part of regular transactions. + +Payments to stake addresses are made for one of following reasons: +* Staking rewards for being a member of a stake pool. +* Staking rewards for being an owner of a stake pool. +* MIR payments from the treasury. +* MIR payments from the reserves. +* Refunds of the stake pool deposit payment when a pool is de-registered. + +Currently, the ledger provides the following reward related events: +* `LEDeltaReward` +* `LEMirTransfer` +* `LERetiredPools` +* `LETotalRewards` + +These events are currently only used by `db-sync` but it is my understanding that in the future, +other programs will also start using these. + + +## The Desired Ledger Event Functionality + +* Every event should carry an `EpochNo` field to make debugging and validation on the `db-sync` side + easier. +* A single `LETotalRewards` event should be emitted for every epoch in the Shelley era and later, + even if there are no rewards for that epoch (in which case the event reward map will be `mempty`). +* `LETotalRewards` should include all payments to stake addresses for a given epoch. That means + all staking rewards (member and owner), all MIR payments and all stake pool deposit refunds. +* `LEDeltaReward` should only ever contain pool membership or pool ownership rewards. +* The sum of all `LEDeltaReward`, `LEMirTransfer` and `LERetiredPools` amounts for an epoch should + always be the same as the sum of `LETotalRewards` event amounts for that epoch. +* The `LETotalRewards` must be the last reward related event for a given epoch to be emitted from + the ledger. +* For the Shelley Era (ie after Byron and before Mary), for the `LETotalRewards` event, all staking + addresses should only contain one staking reward amount (if an address receives both an ownership + and a membership reward, the later will be dropped). From ece92a75409657b4cbde7bbb10b378cb9affa49d Mon Sep 17 00:00:00 2001 From: Erik de Castro Lopo Date: Sat, 12 Mar 2022 10:50:58 +1100 Subject: [PATCH 2/2] doc/release-process.md: Specify handling of rewards to de-registered addresses --- doc/ledger-reward-events.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/ledger-reward-events.md b/doc/ledger-reward-events.md index 5d6e17f69..b184e8007 100644 --- a/doc/ledger-reward-events.md +++ b/doc/ledger-reward-events.md @@ -36,8 +36,10 @@ other programs will also start using these. * `LETotalRewards` should include all payments to stake addresses for a given epoch. That means all staking rewards (member and owner), all MIR payments and all stake pool deposit refunds. * `LEDeltaReward` should only ever contain pool membership or pool ownership rewards. +* `LEDeltaReward` may contain rewards to stake addresses that have been de-registered. * The sum of all `LEDeltaReward`, `LEMirTransfer` and `LERetiredPools` amounts for an epoch should always be the same as the sum of `LETotalRewards` event amounts for that epoch. +* `LETotalRewards` will not contain rewards to stake addresses that have been de-registered. * The `LETotalRewards` must be the last reward related event for a given epoch to be emitted from the ledger. * For the Shelley Era (ie after Byron and before Mary), for the `LETotalRewards` event, all staking