Introducing Bäckerei– Automated Rewards Payment Manager for Tezos Bakers Written in Haskell

Awa Sun Yin

Published in

Cryptium Labs

8 min readNov 8, 2018

[TL;DR] Show us the code! Go directly to Bäckerei’s GitHub repository:

https://github.com/cryptiumlabs/backerei

Preamble

Cryptium Labs has been a baker on Tezos since Cycle 11. Some of the readers might know us from our community development activities, both physically (meetups in China and other Tezos events around the world) and virtually (blogposts, videos, and more to come).

However, we believe that Tezos bakers are also well-suited to contribute to the Tezos technological ecosystem. As such, we do our first bit by open-sourcing Bäckerei, marking the beginning of our team’s upcoming development and research efforts in Proof-of-Stake ecosystems.

Bäckerei — Automated Rewards Payment Manager for Tezos Bakers in Haskell

What is Bäckerei?

Bäckerei [bɛkəˈrai] means bakery in German. It is a collection of scripts written entirely in Haskell, a programming language known for being purely functional and strongly typed. Bäckerei’s purpose is to manage the payments of rewards from a Tezos baker to its delegators.

In order to do so, Bäckerei connects to a full-node, scans the entire transaction history, determines which delegators should be paid, performs calculations on exactly how much they should receive in rewards, and executes the transactions.

Other remarkable features include: generation of a database with the payouts history; monitoring of the baker’s baking and endorsement activities with notifications in case either failed; and automatic notification to a Telegram group after payments for a cycle have been successfully made.

The project is open-sourced under the GPLv3 license, has been tested and used in production to manage Cryptium Labs’s rewards payouts since Cycle 16.

Why is Bäckerei Useful?

At the time of writing, the Tezos protocol does not support in-built rewards distributions from baking and endorsement rewards to delegators. In other words, a baker in Tezos receives all the rewards generated and unlocked cycle after cycle. Its delegators, regardless of being entitled to receive a portion of the rewards, must trust that: 1) the baker will pay them, 2) will pay them on time, and 3) that the baker will pay them correctly.

Whilst Bäckerei cannot ensure 1), as it is still on the baker’s hand to execute the program; it can facilitate 2) and does ensure 3).

Calculating Rewards Correctly

Bäckerei calculates the exact rewards that a delegator is entitled to, considering parameters such as baker service fee, rewards earned during the cycle, and each delegator’s proportional contribution to the staking balance of the baker.

One could argue that alternative systems to perform these calculations exist, for instance, by creating a model using Excel and feeding it with manually retrieved data from a block explorer or public APIs. The risk with the latter and similar approaches is related to the error margin, trusting the correctness of the data source, in addition to the undetected changes in the data, for example, when a delegator changes the value of a delegation or other delegators join or leave.

Bäckerei scans the entire transaction history of a baker, which is later used for calculating the net rewards that every delegator should receive, in accordance with the parameters mentioned above (some of which are customisable, such as the baker service fee).

Making Payments Every Cycle Automatically

Assuming that all the parameters and calculations are correct, the baker can trigger manually the transactions. However, it increases substantially the resources dedicated to perform the transactions.

Even for smaller baking services (< 20 delegators), making 20 transactions manually every 2–3 days results in accumulating a significant amount of hours through cycles. This limitation becomes critical for larger bakers, who might have hundreds, even thousands of delegators.

A quick fix to the issue is by decreasing the frequency of payments, by releasing rewards every month or six months even, instead of every cycle. Nevertheless, knowing how sensitive the trust between a delegator and a baker is, every baker should release rewards as soon as they are available (unfrozen or unlocked). If operational capacity is what prevents your bakery from making payments every cycle, with Bäckerei, payments will be sent in a single batch transaction as soon as they are due whenever you run the payout command.

A bonus feature, coming with Bäckerei’s integration with Telegram Messenger’s API, sends automatically a notification to your chosen Telegram Group whenever the payments of a specific cycle are successfully made.

Providing More Transparency for Your Delegators

Another useful feature that Bäckerei supports is a payouts database. Bäckerei reads and updates a simple JSON file (see ours as example). You can directly share this file with your delegators, enabling them to search by KT1 address what cycle generated how many rewards.

Reading JSON might be slightly overwhelming to some. In that case, to provide a better user experience, you can use the JSON database as a data source and build end-user facing dashboard such as the Cryptium Labs Delegator Dashboard:

Ensuring Fairness in Payments

Besides the features described a priori, Bäckerei is characterised for two more things: it allows the baker to pay the delegators fairly.

What Does Fairness in Payments Mean?

Fairness is a property, interpretation of which might differ baker to baker. In our case, fair payments refers to the fact that: A) we apply automatic compounding interest and B) we guarantee idealised payments by insuring liveness. With Bäckerei, your bakery will also be able to:

A) Apply Automatic Compounding Interest

…to all delegations, as you will pay the rewards every cycle as soon as they are available, meaning that you will always use the most updated balance of the KT1 address. So, if a delegator that received the rewards has not moved the rewards from the delegation, you will consider automatically the new balance for baking.

For bakers that pay less frequently than every cycle, a good inquiry could be to find out if the baker is applying the compounding interest regardless or not. In the latter, a delegator that receives his or her rewards, for example, every month, means that he or she is nor earning the compounding interest of that period.

B) Guarantee Idealised Payments by Insuring Liveness

Our delegators are paid according to what our baker would have made if we had successfully baked and endorsed all scheduled blocks and endorsement slots, plus realised fees. So, even if we miss bakings or endorsements, we would still pay our delegators as if we did not.

We consider that missing baking and endorsement slots due to liveness (see next section) or due to consensus (see section below) are neither delegators’ responsibility, and thus, we pay our delegators as if we have successfully baked and endorsed in all our slots.

[Going Deeper In] Understanding Liveness Faults and Their Implications

Liveness is indirectly penalised by the Tezos protocol. In essence, it translates into the baker not earning the baking or endorsement rewards as expected, when the time to bake or endorse comes and the baker is offline or unable to perform the operation. Then the baking right is moved to the next baker in the priority list and the first baker missed the chance to earn the rewards from the operation.

Missing baking and endorsement slots is, most of the times, preventable by providing your baker with redundant electricity, as well as Internet connectivity.

[Going Deeper In] Understanding Nakamoto Consensus

In some occasions, missing baking and endorsement slots is hard to avoid due to Tezos’ consensus algorithm, which derives from Nakamoto Consensus. It states that the chain with the largest pool of electricity is the canonical one. In Tezos, this is the chain with the most endorsements or the heaviest chain.

Even if a baker has a perfect liveness score of 100% (has not gone offline since it started its activity), the baker might be on a fork for brief periods, in which happen to be baking or endorsement slots. It might take some time until the baker finds out about the canonical chain and readjusts to it. But until then, the baking and endorsement slots might have passed.

Integration with Telegram for Baker Activity Monitoring

Being able to react as fast as possible when a problem occurs with your Tezos baker is desirable, else the baker could be missing baking and endorsement slots. Bäckerei is integrated with the Telegram messaging app to provide a simple, yet direct form of monitoring for your baker while you are on the go.

The monitoring app sends messages that look like:

Next baking/endorsing right: Right (EndorsingRight {endorsingSlots = [11], endorsingDelegate = "tz1eEnQhbwf6trb8Q8mPb2RaPkNk2rN7BKi8", endorsingEstimatedTime = Just YYYY-DD-MM HH:MM:SS UTC, endorsingLevel = XXXXXX})

To inform about the upcoming endorsement slots in order. When the baker successfully bakes or endorses, it sends a message that looks like:

# successful endorsement
Endorsement of block at height XXXXXX OK!# successful baking
Baked block "BMS2Z1r2VMCoGKE243vXQRqso8JWLZYseqLL9GMiqUsymckzaH5" OK!

If the baker fails to endorse or bake, it will send a message similar to:

@admin1 @admin2 Expected to endorse block XXXXXX but did not.

Where you can configure which user accounts are pinged in the message.

It is likely that other development team have released more elegant monitoring applications. But if you are looking for a simple one, the Bäckerei monitoring app works — for us, at least!

Increasing the Operational Security of Payments

Bäckerei is agnostic to the baker’s usage of HSMs or Nano Ledger S (currently, the only publicly supported HSM for baking in Tezos). Nevertheless, we recommend using it to leverage its protection against safety faults, caused by double-baking or endorsing.

Bäckerei allows you to specify a separate address (instead of your baker address) as the source of funds for your payouts. This means that you do not need to pay directly from your baking account. Instead, you can setup a separate account and pay from its KT1 address in a separate server and avoid paying directly from your Nano Ledger S or the HSM that contains the signing keys of your baker.

Whom is Bäckerei for?

Unlike delegating or solo-baking, operating and offering a public delegation service in Tezos demands substantial amounts of resources, both technical and operational. In order to contribute to an increasing number of safe bakers in the Tezos community, we want to help fellow bakers save time by automating necessary, yet time-consuming tasks such as payments.

Even though Bäckerei is written in Haskell, using the tool does not require any Haskell knowledge. Nonetheless, it does assume familiarity with the command-line.

How to Contribute?

Following the ethos of open-sourced projects, we encourage both developers and non-developers who have tested Bäckerei to open issues on our GitHub repository, be it with feedback, suggestions or bugs to be fixed.