tezos-reward-distributor-organization/tezos-reward-distributor v13.0

Paris

on GitHub

The Paris update of Tezos ships with "Adaptive Issuance". As of cycle 749 of Tezos, Adaptive Issuance has kicked in. This significantly impacts staking, rewards and TRD.

For cycle 749 onwards, you must update TRD to this version. If you do not, things will look like they are still working, but you will be paying your delegators too much.

In tezos, rewards are derived from baking rights. In Oxford, baking rights come from delegation (including baker's own balance). In Paris, they are split in 2 unequal parts:

• 2/3 of rights come from staking. Staking is now an explicit operation: both bakers and their delegators can stake their tez (put them at stake). Staking rewards are paid in protocol, only tz account can bake (no smart contract can bake)
• 1/3 of rights come from delegation as before, however the methodology to calculate rewards is changing:
  • there is no more 5 cycle delay between delegation and reward accrual. this is replaced with a 1 cycle delay
  • there are no more concept of "snapshots" with balances taken at random, determining the stake (hence reward distribution). Instead, the lowest balance throughout the cycle is taken into account for reward calculation.
  • also, the fees collected in blocks by bakers (negligible today) are not taken into account for staking rewards. They all go to delegation rewards.

Note: this 2/3 / 1/3 distribution is global, not per baker. It is possible for a baker to have no delegators, only stakers, then their delegation rewards are nil.

There is no RPC to query this lowest balance. Therefore, the ability to implement a simple RPC-based reward distributor has been lost. This was already disabled in TRD - we have now removed the code completely.

For a while, the only supported backend of TRD has been tzkt. This will remain the only supported solution in Paris, however tzkt did not implement the same calculations as the protocol for minimal balance, because it was unable to (more details below).

As you deploy the new release, it is advised to do a dry-run first. Here is how to sanity-check your dry-run:

In the logs for your dry-run, you will see the following line:

INFO - Total rewards before processing is 100,000,000 mutez.

This value is no longer the total rewards. This is only the part of rewards attributable to delegation. You will get more rewards from staking.

This is not the same value as the one you can see in tzkt "rewards" page, which sums up up delegation and staking rewards. You can however check this value in the API by querying the following:

curl -s https://api.tzkt.io/v1/rewards/split/tz1xyz/749 | jq '(.blockRewardsDelegated + .endorsementRewardsDelegated) / 1000000'

(replace tz1xyz with your baker address)

A little below, in the logs, you will see the following:

Total estimated amount to pay out is 90,000,000 mutez.

This is what TRD will pay out.

As a public baker, most of your balance is probably staked (and if it is not, you should fix it by running the stake command). This has another effect: TRD no longer "carves out" some of the rewards for your own stake. Indeed, your own stake is paid for by the protocol, using the new mechanism.

Under AI, most of what TRD pays you is delegation fees. You can sanity check with the 2 values above: if the rewards attributable to delegation are 100 tez, and your fee is 10%, then you should expect TRD to pay out about 90 tez. This is assuming a normal config without any "owners" or "founders" set (I have not tested this). If the values you are seeing in the dry run are significantly outside of this, please reach out on slack.

The amount you will pay out at every cycle will probably be less than what you are used to paying prior to Adaptive Issuance activation. It's normal: in the new model, delegators will earn less, stakers earn more.

How this release was tested

The PR #703 (commit eaad513) was used to pay out rewards for cycle 749 for 2 small-ish mainnet bakers with no issues. One of them is accepting third-party stakers and the other is not. The values are looking good according to the rule of thumb above. Several bakers then used this commit to pay out cycle 749 and node reported issues.

Caveat emptor:

1. CI is failing. We are lacking workforce to fix it - in fact, the changes in Adaptive Issuance are of such magnitude that it might be better to start from an empty codebase and selectively import the python code that we still need, and write a new set of tests. This means, some things might be broken. We simply disabled pytest for this release.
2. The current PR has not been tested in every configuration - especially no distinct "owners" or "founders". I am tempted to delete these features as well, but I don't see why AI would break it, so I left them. use at own risk.
3. TRD accuracy is 100% downstream of tzkt accuracy. However, tzkt does not provide accurate data from the protocol, because this data is simply not accessible. Instead, it approximates it. This is discussed at length in this ticket. Specifially, the delegator balance is measured at the end of the cycle by tzkt. The protocol takes the minimum. This is potentially gameable by delegators.
4. This new way of calculating delegating balance by picking the maximum is breaking smart contracts such as kolibri ovens, for which balance goes to zero when you pay them out. Therefore, paying out kolibri ovens lowers your delegation rewards for the cycle where the payout takes place. A fix is coming for protocol Q. But for the time being, it's a good idea to not pay kolibri ovens, or pay them to the originator address rather than the contract iself. TRD has a feature for that called specials_map, see doc. It's also worth noting that TezPay has implemented some middleware that addresses the problem, but we are not making use of it, due to lack of time, mostly.
5. there is an edge case of rewards unstaked from one baker and pending finalize unstake. these ones are taken into account for delegation rewards by the protocol, but not by tzkt, and therefore these balances do not get payouts from TRD
6. keep in mind that the license for the software says that we make no guarantee, implicit of explicit of proper operation, or suitability for a particular purpose.

Changelog

• change sources for splitting up the delegation rewards
  • look at delegatedBalance instead of balance of bakers and delegators, as numerator
  • look at blockRewardsDelegated + endorsementRewardsDelegated as denominator
• do not include bakers' fees as reward as discussed in issue
• deprecate & remove code for "estimated" and "ideal" rewards. only "actual" rewards remain
• remove code for rpc and tzstats data source. only tzkt remains
• some doc updates
• disable CI - no resource to maintain the testing codeees as reward as discussed in issue
• update next proto Q date - do not prompt for confirrmation if this date is passed as this breaks docker
• updates blocks_per_cycle constant to fix continuous mode