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

Jump to bottom

Ambit claim for ledger event rewards #1080

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Ambit claim for ledger event rewards #1080

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cf6df5f
Add doc/ledger-reward-events.md
erikd Mar 11, 2022
ece92a7
doc/release-process.md: Specify handling of rewards to de-registered …
erikd Mar 11, 2022
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
47 changes: 47 additions & 0 deletions doc/ledger-reward-events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# 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:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's probably worth noting that the list below is the name of the wrapped events from the Cardano API. The corresponding ledger events are currently nested according to the ledger rule hierarchy (though we may change this is the near future, a clean up is on order)

  • ShelleyLedgerEventTICK . NewEpochEvent . DeltaRewardEvent . RupdEvent
  • ShelleyLedgerEventTICK . NewEpochEvent . MirEvent
  • ShelleyLedgerEventTICK . NewEpochEvent . EpochEvent . PoolReapEvent
  • ShelleyLedgerEventTICK . NewEpochEvent . TotalRewardEvent

* `LEDeltaReward`
* `LEMirTransfer`
* `LERetiredPools`
* `LETotalRewards`
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* `LETotalRewards`
* `LERewardEvent`


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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is currently no such LETotalRewards event in the Cardano API, do you meant the LERewardEvent? The MIR payments and pool deposit refunds come from totally different ledger rules, we cannot make the event described here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is currently no such LETotalRewards event in the Cardano API,

db-sync currently does not use cardano-api for anything ledger event related.

Is there any accomodation ledger might make the use of these events by the current one and only consumer of these events easier?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

currently does not use cardano-api for anything ledger event related.

oh! Where does LETotalRewards come from? It's not from cardano-ledger.

Is there any accomodation ledger might make the use of these events by the current one and only consumer of these events easier?

Absolutely! We just can't glue these events together in the way you are proposing, not with serious consequences

* `LEDeltaReward` should only ever contain pool membership or pool ownership rewards.
* `LEDeltaReward` may contain rewards to stake addresses that have been de-registered.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here are some extra details that might be helpful.

In the Alonzo era, and previous eras:

  • any stake address inside the stake distribution snapshot which is deregestered at the time the reward calculation begins will not be included in this event.
  • any stake address inside the stake distribution snapshot which is deregestered after the reward calculation begins, and is not registered at the time of the epoch boundary, will have it's lovelace given to the treasury.

In the Babbage era:

  • any stake address inside the stake distribution snapshot which is not registered at the time of the epoch boundary will have it's lovelace given to the treasury.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Era specific behavior for any event is a huge pain in the neck for db-sync.

* 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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This requirement (that the total reward event sum is equal to the sum of the other events) is inconsistent with the idea that the LETotalRewards does not contain the de-registered accounts, but the LEDeltaReward might include them.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

😢 Do we have a different idea of the meaning of the word "total"?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

LEDeltaReward may contain rewards to stake addresses that have been de-registered.

LETotalRewards will not contain rewards to stake addresses that have been de-registered.

These three requirements are inconsistent. A reward for a stake addresses that has been de-registered would be in the sum of "all LEDeltaReward, LEMirTransfer and LERetiredPools amounts" by the second quote above, but not in the sum of "LETotalRewards event amounts" by the third quote above. Therefore the sums will not be the same in the presence of stake addresses that have been de-registered.

* The `LETotalRewards` must be the last reward related event for a given epoch to be emitted from
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The ledger will make no guarantees about the ordering of the events corresponding to a given block.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So I can theoretically get an LEDeltaReward for epoch N after I get the LETotalRewards for that same epoch? That does not make a lot of sense. More importantly, it makes the LETotalRewards useless from the POV of db-sync using it for validation.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes that is theoretically possible. The event is still useful, we use it in the ledger property tests to ensure that the delta rewards are what we expect.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The goal of all of these events is to be used by db-sync which is currently the only consumer of ledger events. If its not useful for db-sync is not useful.

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).