Tezos Reward Distributor: Getting Started
Tezos Reward Distributor or TRD in short is a baking reward distribution application for tezos bakers. For an introduction to TRD please see the previous article.
https://medium.com/@huseyinabanox/tezos-reward-distributor-e6588c4d27e7
This article will provide information on how to start using the application.
Prepare Your Environment
- Setup your environment: TRD requires a running tezos node. tezos-client is needed for wallet operations. Official documentation can be used for this purpose. Either of building from sources and using docker images options can be used. https://tezos.gitlab.io/master/introduction/howtoget.html
- Import your payment address: Payment address with the secret key should be imported to tezos-client. A simple guide can be found in TRD wiki. https://github.com/habanoz/tezos-reward-distributor/wiki/Payment-Address
- Install Python 3 and git: Luckily most Linux distributions have them installed.
Install Tezos Reward Distributor
- Clone: Clone from GitHub.
git clone https://github.com/habanoz/tezos-reward-distributor - Install dependencies: TRD needs some python modules. You need to install them.
cd tezos-reward-distributor
pip3 install -r requirements.txt - Update: Regularly check and upgrade to the latest available version.
git pull - First command: Type help command to check if the installation is successful.
python3 src/main.py --help
Create Baking Configuration
TRD comes with an interactive configuration utility. The following command will list available options.
python3 src/configure.py --help
In most common cases (docker installations will require -d switch), the following command is enough to will launch the configuration utility. Simply follow the instructions and provide the requested information. Inputs will be validated. In the end, a YAML file is created.
python3 src/configure.py
In order to create a configuration file similar to above, provide inputs like in the image below. Note that the path of the created YAML file is displayed at the end.
Ready to run: Check Calculations First
Now you are ready to make your first payments. Normally TRD will make calculations and pay them immediately. Before making any payments lets only run calculations to check the results. -Dc option will make the calculations, create a calculation report, and exit.
Let's examine the application output.
The application will start with printing the TRD banner. Version and running mode are presented here. The argument has the following meanings: -d indicates docker installation, -N specifies network, -M 3 means run for a single cycle and stop, -Dc means make calculations only.
Afterward, argument details are printed. All running details can be found here. Note the dry_run_no_consumers=true line, this is due to -Dc switch. Other argument values are either default values are result of other switches.
Baking configuration details are printed. Apart from those values which are read from the YAML file, there are configuration items that start with double underscores. Those are generated using the values from the YAML file.
Finally, TRD makes calculations, displays brief information, and prints the location of the calculation report file.
The calculation report content can be seen in the image above. The first row contains names of the columns: address, type, balance, ratio, fee_rate, amount, payable, desc, etc.
type: Reward type. Possible values, B: Baker, D: Delegator, F: Founder, O: Owner. Founder represents bakery founders, they receive baking service fee. The owner represents the owners of the bakery balance. Owners receive baking rewards.
amount: Baking reward in mutez for the entity.
ratio: Ratio of share on all rewards. 0.5 means, the entity deserves half of all rewards.
fee_rate: Baking service fee for the entity.
fee_ratio: Equals to fee_rate times ratio. The Sum of all fee_ratio must be equal to the sum of founder ratio values.
fee_amount: Amount to pay as baking service fee in mutez. The Sum of all fee_amount must be equal to the sum of founder amounts.
skipped and atphase: skipped is 1 if an entity is skipped due to some criteria (e.g. exclusion, min_delegation_amount). atphase is the phase at which the entity is marked as skipped. TOB targets are skipped at phase 1, TOE targets are skipped at phase 2, TOF targets are skipped at phase 3.
desc: Description of the entity. e.g. exclusion cause.
The second row represents the baker. The balance represents the whole bakery staking balance and the amount represents total rewards that should be distributed at this particular cycle.
TRD creates a log file under the logs directory. Logfile creates plenty of information and most of the time this information is not needed. In case of problems, the log file should be checked first. There is an -V switch which makes logging even more verbose. But use the verbose switch for trouble shouting only, it will create a lot of logs. Log files are rotated which means once a file reaches to 5MB, it is archived and a new file is created and at most 10 of those files are kept.
Make the Payments
Now we checked and verified the calculations we are ready to make the actual payments. Dropping -Dc switch is enough.
TRD first makes the calculations. Note that it is similar to the output of -Dc run. But this time payments are fulfilled. The total amount to pay is displayed. Since there are more payments than tezos allows to put in a batch, payments are executed in 3 batches. Each batch is tried one after another. TRD waits for some time until the block containing the batch has 1 confirmation. Once processing of all batches is complete, a payment report is created and its location is printed.
Note that report is created under a directory named “done”. If one or all of the batches fail the report is created under the “fail” directory and failed payments are tried regularly until they are all paid. If enabled, an email will be created to inform the baker.
Please also note that calculations are done by a thread named “producer” while payments are done by a thread named “consumer”. This is why -Dc switch is called dry_run_no_consumers. If we try with -D, dry run switch, it creates consumers but consumers do not inject the operations into a block at the end of the processing. -D is good for simulating payments. If payments should fail for some reason, -D switch helps us catch them before trying actual payments. Thus, running with -D, prior to actual payments, is a good practice.
Again, for more information log files can be viewed. Now let’s have a look at the payment report file.
The first row contains column names. Column names suggest their purposes. The Hash column contains a hash of the operation payments is put. Please note that the column filter displays 3 unique hash values, this is because payments are executed in 3 batches. Another thing noteworthy is the ‘M’ type, which stands for ‘Merged’. Because in configuration, the address tz1fQdCEQci51KDAUmzgTPvKq7sLkoiwo6V4 is both a founder and owner, it deserves two payments. In order to pay the network transfer fee once, both payments are merged.
The last column shows the payment status for each row. Possible values are 0:Fail, 1:Success, 2: Done, 3: Injected. Success and Fail are self-explanatory, let's discuss Done and Injected.
Done is used for simulated payments and payments with an amount less than a zero threshold value. If a payment amount is less than some value which is close to the network transfer fee, that payment is marked as Done, and nothing is sent for that address. Normally you should not see Done status. If you see Done status, it means you are making a dry run or you should start using a minimum delegation amount.
Injected status is particularly interesting. TRD waits for some time until the block containing the payments has 1 confirmation. In the future number of confirmations needed may change. The amount of wait time is the number of confirmations plus a patience value times block time. In mainnet, block time is 60 seconds and currently, patience value is 10. As a result wait time is 11 minutes. So do not panic if a batch takes some time to complete.
What happens if block the block does not have 1 confirmation in 11 minutes? This is possible, indeed this is experienced. Baker’s node may fall back or switch to an alternative branch. This is why it is important to wait for confirmations and this is why exchanges do not release deposits after they see the required amount of confirmations. If TRD does not see the required amount of confirmations in the specified time period, it cannot be sure about the faith of the batch. TRD assumes it is paid and warns about the situation in logs and email. It is the baker’s responsibility to check and verify the faith of the batch. If the baker finds out that payment is not actually happened, he should move payment report from done folder to fail folder and run retry_fail.py utility with -inj switch to retry INJECTED payments.
Running Modes
TRD can run in either of 2 modes: daemon or interactive. So far interactive mode is used. In interactive mode 3 execution modes are possible. Execution modes are specified with -m switch. -m 1 means continuous execution and it is the default value. -m 2 means execute from the last payment until the most recent pending payment. -M 3 means execute a single payment. In all modes, it is possible to specify the initial cycle with -c option.
In execution mode 1, TRD continuously checks for failed payments and tries to pay them. In other modes failed payments are not tried. It is the baker’s responsibility to retry failed payments. For this purpose, a utility is provided.
python src/retry_failed.py
retry_failed comes with a similar argument set. You can choose arguments to suit your needs. If you want to pay for payments in Injected status, you should use -inj switch. It will check for failed payment reports under the fail directory and try to pay them.
Daemon mode is important and it is the advised form of running. A utility named service_add.py is provided to set up a Linux service. For instructions on the daemon setup, see TRD wiki. In daemon mode, only execution mode 1 is supported.
https://github.com/habanoz/tezos-reward-distributor/wiki/Linux-Service
Conclusion
TRD is more advanced than a single article can cover. Feel free to try it. If you have trouble or need a feature that you believe the community will benefit from, create an issue in GitHub. If you have skills consider contributing to it. Have a look at the contributions guide.
https://github.com/habanoz/tezos-reward-distributor/wiki/How-to-Contribute
Check TRD wiki for more information.
https://github.com/habanoz/tezos-reward-distributor/wiki
As the last sentence, please note that TRD is a community effort that is not founded by any organization.
