Tezos Reward Distributor: Introduction

Hüseyin ABANOZ
5 min readJun 9, 2019

--

TRD is an open source reward distribution software for tezos bakers. It is simple to use. On the other hand, it has many configuration options available for those who need them. Its motto is Run&Forget. It is actively developed with an active community.

TRD is suitable for small to large scale bakers. It is suitable for home bakers to staking as a service providers. For more information see our getting starting article.

https://medium.com/@huseyinabanox/tezos-reward-distributor-getting-started-8e7030ff121f

Key Features

  • Batch payments: Payments are split into batches due to block size limitations. Each batch is paid independent of another.
  • Linux service: It is possible and advisable to configure TRD run as a systemctl daemon. service_add.py is there to make this setup a breeze. Once service is configured and launched it will silently run in the background and do its work. It will remind himself from payment to payment via report emails.
  • Reliability: Each batch is tried persistently until it is paid. Payments are logged to avoid double/repeated payments. Multiple instance lock to avoid unintended payment activity.
  • Multiple backends: Delegator data can be taken from RPC API or Tzscan API. Even though Tzscan API is not very reliable, TRD Tzscan backed is advanced enough to search for live mirrors and retry silently until delegator data is retrieved completely.
  • Custom payments: Ability to exclude delegators, apply special service fees and set a minimum delegation amount. Share of uneligible delegators can be shared among other delegators, or founders or can be left at staking balance. Ability to pay to a custom address other than delegator’s address. Payments to a single address are merged into a single payment to pay less transfer fee.
  • Custom baker policy: The transfer fee can be paid by the delegator or the delegate. Ability to choose after how many cycles following the baking should payments go. Paying for unfrozen cycles is possible. Ability to set a minimum delegation amount. Founders and their shares of the baking fee are configurable. Staking balance owners and their shares of the baking reward are also configurable. It is possible to leave the share of owners and founders to staking balance.
  • Baker configuration: Baker configuration is kept in a yaml file which is easy to edit and view. An interactive command line tool can be used to generate/edit a configuration file. Before each launch of TRD, the baking configuration is validated to ensure input data is valid. Input validation is an important part to improve user experience by avoiding hard to trace errors due to incorrect input.
  • Traceability: TRD keeps delegator data and calculation details in CSV files, calculation reports, for each cycle. Calculation reports are detailed enough to understand and verify. Payment activity is also kept in CSV files, payment reports. Payment reports show batch contents, their final status, and the hash of the operations. Payment reports are also important to prevent double/repetitive payments. CSV files can be opened with any spreadsheet application which makes it possible to run extensive analysis on them.
  • Phased calculation logic: Reward calculations are done is so-called phases. Phase 0: raw data from tzscan/rpc. Phase 1: Calculate the total rewards. Phase 2: Calculate the reward ratio of each delegator. Phase 3: Calculate the reward ratio of founders as a whole. Phase 4: if configured for payment, calculate the reward ratio of each founders/owners. Phase 5: If there are custom payment destinations apply them. Phase 6: If there are multiple payments to an address, merge them. Final Phase: Convert ratios to actual payment amounts. This phased approach makes calculations easier to understand and customize. More phases e.g. taxation can easily be added.
  • Battle tested: TRD is not a new application. It has been actively used and developed since the past 10 (as of writing this article) months. Some of the major bakers relies on TRD for their reward distribution.

Open Source

TRD is developed using python programming language. Python is widely known and very easy to understand. Choice of Python makes TRD source base open to a large audience. It is neatly coded.

https://github.com/habanoz/tezos-reward-distributor

Source code is hosted on Github. Development activity can be tracked. The number of issues open/closed may give an idea about the amount of effort given.

Over the time community members contributed to the development of TRD which makes it a community effort.

Simple To Use

TRD is designed to require a very little technical background. A configuration tool can be used to generate baking configuration. Once the configuration file is present, TRD can be either run in background service mode or in regular mode.

Background service mode is advised. It requires the least attention from the delegate. This way, the delegate can focus on other tasks. Report emails can help the delegate monitor if everything is running fine. A tool to set up the Linux service is provided with TRD. For set up steps please refer to the related page in TRD wiki.

https://github.com/habanoz/tezos-reward-distributor/wiki/Linux-Service

Calculation and payment details are reported in form of CSV files. CSV files can be opened with any spreadsheet application from which report can be filtered, formatted and analysed.

TRD has many command line options. If it is run in source code built tezos environment to pay mainnet rewards beginning from the latest unfrozen rewards, which is the most common use case, then no option is needed.

If docker environment is used, run with -d switch. If you are running tests in zeronet or alphanet environments run with -N to specify the network. If you want to pay for a single cycle and exit, run with -M 3. If you want to pay for a specific cycle run with -C to specify the cycle. Please note that, even if a cycle is explicitly specified with -C option, it will not be paid if there is an existing payment report.

If you want to make a dry run before actual run, run with -D option. With this switch, TRD will make calculations and run payment steps but do not inject the operation to the node, avoiding any actual payments. If you just want to create calculation report without any simulated payments run with -Dc switch.

In order to choose calculation back end, run with -P option. If you want to use custom configuration or reporting base directories run with -f or -r options to specify. If you want to pay for unfrozen cycles, run with -R option. To see more options run with ” — help” option.

https://github.com/habanoz/tezos-reward-distributor/wiki/How-to-Run

Run&Forget

TRD is here to take reward distribution burden from your shoulders. Try TRD now, ask questions, create issue reports and feature requests in GitHub. Once satisfied with it, setup Linux service and forget about it. Just check report emails and make deposit to your wallet.

https://github.com/habanoz/tezos-reward-distributor

--

--

Responses (1)