Bakers Registry Discussion

Hi all,
we have been putting a lot of thought in how to describe the process of a staking service and developed our Terms & Conditions with a specialist for IT law. It is translated to English (I do not know if it sounds odd to a native speaker) and is first of all from a “German perspective” but I think it is valuable to have a detailed description of what happens in dPOS. A clear description is the basis of how to judge on the tax or legal impact of what happens. I completely agree with Arthur here that the payout is actually that the baker decides on because of an agreement that is out of the scope of the protocol. The protocol itself does say “give that baker my rights” and nothing more. The payment policy is completely up to the external agreement which is good because otherwise the contractual relation based on these terms is in my opinion happening the moment someone accepts the process as described and offered by the baker.

Best regards


I’m not sure if buying/renting baking rights from delegators is the correct term here. Usually buying/renting implies that the act is carried out by the initiator, in this case, the baker. However, delegating baking rights is initiated by the delegator, not the baker, and, therefore, the baker is not actively buying or renting baking rights from the delegator. If these terms are used, then this implies that the delegator forces the act of buying/renting onto the baker, without the latter having a choice to not buy/rent those baking rights.

I like neither expression. I think simply “pooling” describes best what happens at delegation-services. And for providing the Pooling infrastructure the delegation-services takes a fee. Not for the baking rights (which doesn’t even exist below 8k).

@cryptodad Both of you are correct that it is difficult to find the perfect terminology. This discussion is helpful in clarifying all the related issues and I’ve edited my terminology post to add clarity about the rights not existing yet at the time of delegation. Whether we call it rent/split or anything else matters less than making sure we are being clear of the following statement from my previous post:

The subtle but very important distinction is that the token holder is not paying the baker anything that resembles a fee for a service as this implies a relationship that does not truly exist and generates potential legal complications depending on your jurisdiction.

The protocol does not imply anything belonging to the token holder other than the power to perform the action of delegating on a per cycle basis. If bakers choose to describe their business as a service that is up to them if they want to deal with any issues that arise in their jurisdiction – the key point is that this is not implied by the protocol. What is implied is that bakers get value out of the delegation and thus it it can make sense for the baker to pay the delegation for the act of delegating.

1 Like

@tezit: Yes, I understand that we need to take care to not run into legal complications in any jurisdiction.

It is therefore important to not construct a relationship between baker and delegators that looks from the outside as something that was just constructed to avoid such complications.

I felt the need to point that out in my previous post, as the suggested terminology would be too easy to debunk.

The goal of avoiding legal complications is a ultimately a decision to be made by each individual baker. As you see earlier in the discussion Coinbase has taken a very different approach to these issues. I am not trying to suggest there is a one size fits all or that any baker should share these concerns if they choose not to do so.

My intention is to encourage us to discuss what actually exists in the protocol; and to find a way to describe it as best we can.

I only emphasize the potential for legal complications as there are still many people who don’t appreciate that side of things. Once people are aware, then they are more likely to see the value of describing the baker/delegator relationship as it actually exists in the protocol. Which is merely an independent act by a delegator with no compensation which can be undone at any time. This act can bring value to a baker and therefore it can make sense that the baker compensates the delegator for the act.

The direction of payment is important i.e. it is from baker to delegator (the protocol does not imply and it is not necessary to suggest that there is ever a payment from the delegator to the baker, and especially that there is ever a custodial relationship).

I don’t see how this is being constructed to avoid potential complications. It’s how the protocol works.

I was not referring to your posts, but rather to the buying/renting relationship between baker and delegators, which I found as sounding constructed.

So far I think the tldr is:
a payment for the act of delegating

Now hopefully more people will suggest effective terminology to that effect given that the calculation of said payment can either be generally “fixed” as implemented by CryptoDelegate or “dynamic” as done by the majority of bakers.

Until we have time to get more input, it seemed “rent” would be a reasonable start but please everyone suggest other ideas on how to describe this payment in a way that respects the directionality and non-custodial aspects of the protocol.

@cryptodad For the soon to be released beta of the Bakers Registry on mainnet, we were prepared to go forward with “rent” = 90% but maybe something as basic as “delegationPayment” = 90% would be a better place to start? It will take time for the community to standardize, for now my short term priority is what to put into the beta registry schema which is only the base layer of the stack, those on top can choose to call things whatever they wish.


What about „rewardShare“, which would imply the direction from baker to delegator imho, and does also not provide false connotations?


Pooling. Pooling is an “social act” and the one that is providing the pooling infra gets a compensation.
You could run it as a “pooling club” if the fee just covers the expenses.

Cross-posting given relevance to fee-for-service vs. rent-rights conversation above:

Btw. have you considered that some bakers are giving out different reward splits meaning it should maybe to called “splitRange”: “80-90”?

Should all the parameters with the name “fee” also change? E.g. “subtractLostFeesWhenAccused”.

Good work so far!

I think we are getting very close to a good definition. I vote for “rewardShare”.

The very soon to be released v1 of the Baker Registry is so we can have a concrete solution to test and learn from as we don’t expect to get it right the first time and even if we have done a good job it will need to evolve as the protocol and baker policies change over time.

Regarding a “splitRange”, you are correct, for many reasons a baker in fact is likely to have a range (e.g. grandfathering, size of delegation, etc). We will learn if eventually it will make sense to model the range or if its accpetable to only record the “primary” split. The purpose is to communicate to those looking for new delegation to express the the current policy and most bakers today have a single split value to communicate. For auditing it gets more complicated, and thats why we look forward to active engagement from those entities that audit and analyze the data to give us feedback on how to improve the registry.

Regarding the “subtractLostFeesWhenAccused” field, this is not a “fee” the baker charges. It’s a completely different category and it accurately refers to the protocol fees. The goal is to encourage people to use language which better aligns with the manner in which the protocol functions.

1 Like

Baker Registry v1 Details

Version 1 of the baker registry contract has been originated on the Tezos mainnet by the Tezos Commons Foundation (TCF).

The baker registry is a smart contract which allows a baker (and only that baker) to submit updates to their public data. To make it easier for bakers to generate the operation with parameters to submit to the contract we have created an initial version of a web form which has only been tested using Google Chrome; this is known as the baker registry app and can be found here. The web app can also be downloaded from the repo linked below and run from a local web server without public internet access if the user supplies their own indexer endpoint in the app settings.

The baker registry app is not a wallet and as such it does not put your baker key at risk as the user does not provide any secret information in the app. All it currently does is allow you to:

  1. Query the contract for a baker’s data by entering their public delegate account (baker pkh)
  2. Provide a web form to edit the data and generate the command text to be entered into the Tezos client command line

The baker registry contract was originated with the maximum amount of baker data that the current Tezos blockchain parameters allow. This resulted in a pre-populated list of 103 bakers generated from the public APIs of MyTezosBaker, BakingBad, and Tezos-Nodes. It was not possible to pre-populate all the fields as the public APIs did not contain all the data; it is up to bakers to go to the registry and make sure their data is accurate and complete. For more information on the type of information stored in the registry continue reading the full Baker Registry FAQ

The goal of this first version of the registry contract and app is to move forward in learning how the community should best address the sharing of this information. It is likely that we will agree that changes need to be made to the data schema, the contract, and the app.

The current baker registry repo can be found here.
The baker registry contract address is KT1ChNsEFxwyCbJyWGSL3KdjeXE28AY1Kaog

Q: What should I do now?

A: Everyone is encouraged to provide feedback on Agora and the baker slack. Depending on your role in the ecosystem you should do the following:

  • Bakers: Go to the registry app, find your baker using pkh. If not found, then add your baker to the registry. If found, carefully check all the fields for accuracy and enter any missing fields. In both cases, the app allows you to generate the command text, paste the text into your Tezos client to call the contract. (make sure to remove the --dry-run flag once you are ready to submit the actual operation). Note: The field “Offchain Baker Data Url” was originated as empty, it is a link to where the baker stores the off-chain JSON file with additional information as described in the FAQ. An initial version of this file was created for each baker and stored in the public repo folder named offchain. Each baker is expected to copy their matching file, edit it, rename it to what they want, host it where they want, and enter the new link to their self hosted file into the registry field to update the contract.
  • Aggregators (Listing Services): The registry app makes use of a simple parser library of JavaScript functions in a file named tcfBakerRegistry.js which retrieve the registry contract data, parse the big map using an indexer API, decode the UTF-8 fields from bytes, and return a list of bakers and their on-chain data. You should make use of these JavaScript functions to retrieve the data, filter it using your existing processes, and merge it into your workflow and databases. We will set up a channel for discussion on how to best improve and modularize this JavaScript code; we will also want to standardize the retrieval of the off-chain URLs for each baker – it’s likely that will move to include the off-chain retrieval into the the same js library, for now each aggregator must do this independently.
  • Auditors: There are two important things needed from auditors. First verify that the registry is capturing all the fields needed to effectively audit a baker’s payouts. Second review how effective the blockchain history of the contract storage will be in enabling historical audits. Additionally participate in the channel that will be created for Indexers as their APIs will be leveraged to effectively retrieve the history data.
  • Wallets, Apps, Tools, and Services (including Agora and the notifier bots) : We need to hear from all “consumers” of baker registry data that use it to display in their solutions. In particular there is still work to be done on how to best standardize the filtering and delivery of the data via reliable APIs to these solutions. Ultimately the Aggregators and Auditors will likely play a vital role in adding analysis and filtering to the raw registry data to make it more useful to all solution builders.
  • Indexers: The baker registry contract and app has the same needs that most other “app devs” will need – a reliable and consistent way to access the Tezos blockchain information. There is more work to do in parsing and decoding all the data, especially when it comes to the more complex data structures and areas that aren’t likely to be supported by the RPC. We will be setting up a channel to discuss how to best standardize the core indexer APIs needed by the registry (especially in regards to the contract’s use of big_map).

Moving Forward

The baker registry has been a collaborative effort by many entities in the Tezos community. But we still need to prove that the registry provides real value to the ecosystem before we can expect everyone to use it. It is important that the registry continue to be a community lead effort in order to have confidence in this vital source of data needed by many apps, tools, and services.

Next steps for the app

  • Add the ability to use other wallets to submit calls to the contract (e.g. Kiln aren’t likely to have access to the Tezos command line) – this can be supported by having the app output only the parameter string needed by wallets when calling a contract. But will need to work with wallet providers to make sure that the formatting works consistently across their implementations.
  • Add better data entry validation (currently mostly only command side validation, i.e. you will get an error when running the command on the Tezos client if you have entered invalid data)
  • Add better error messages and UX when app fails to successfully retrieve data from the blockchain

Next steps for the schema

  • Have bakers verify it captures all the data they want to share
  • Have auditors verify it captures all the data needed to audit payouts
  • Have auditors and indexers suggest any new fields needed for tracking history
  • Continue improving the terminology used in the baker ecosystem which is expressed in the schema
  • Based on usage and cost/benefit analysis, determine where the data should be optimally stored – the preference should always be to store data off-chain, and limit the on-chain data to what is really needed. One example would be only storing on-chain a hash of the data document.

Next steps for the contract

  • Incorporate feedback on entry points, annotations, rules checking
  • Optimize the data types
  • Review the current use of a single entry point for both updating the “baker data” and the “reporter” – related issue that the entire dataset for a single baker must be resubmitted on every update which makes the retrieval of the accurate data for display and command generation very important and a potential source of data entry error
  • Begin preparing how the registry contract will handle versioning issues as the schema eventually goes through changes (not only impacting the contract parameter and storage but possibly logic as well). Lambda vs Proxy approach to versioning.
  • Begin discussing how the contract can move from TCF control to either a multi-sig controlled by a collaborative group of community organizations or even a DAO

Next steps for the parser library

  • Determine if should add code to query the baker off-chain URLs and merge the on/off data into a single set of data for use by aggregators
  • Improve the use of promises and error handling
  • Modularize the JavaScript library of functions to make them easier to integrate with other code
  • Coordinate parser library versioning with the changes to schema/contract/indexers

Just updated our data using the generated tezos-client command.
Everything works like a charm!
Great work guys!


Very much in support of this initiative. Maybe my questions might be unripe at this moment as details are rolling out, but I am very interested in how the auditing process is going to occur. For instance, who are the auditors going to be? How will they get selected? What happens during perceivable conflicts of interest(s)? How often are audits going to be done? Is there going to be a formal auditing process including an appeal structure for bakers who feel like auditors have captured incorrect data?

As i’m not and never intend to be an auditor I can only give you what I have observed and understand so far.

First, auditing a baker in this sense really means verifying that a bakers payouts match their stated policy for a given cycle. As to “how will they get selected?”, this is a decentralized blockchain no one selects anyone for anything other than by known blockchain based action; some examples are delegating your account to a delegate, sending someone a transfer, bakers submitting a vote, calling a contract (same as sending a transfer but with parameter data).

So currently the main auditor that the ecosystem has seen appear thus far is Baking Bad. Eventually I would guess there are likely to be others. They decide what they want to audit, how they want to audit, when they want to audit and the community decides how much they value what the auditor produces.

The current audits are all based on blockchain data for payouts, and now with the TCF launched Baker Registry the audits can have access to blockchain (i.e. cryptographically signed by the baker themselves) based data for the policy at a given cycle. So there is no longer an issue with “captured incorrect data” as its now more realistic to audit the auditors by analyzing the blockchain history.

1 Like

I have updated our data and it works fine using tezos-client. Really well done and much appreciated!

The following questions arose while analysing the big map data stored on chain for LetzBake!:

  1. What does the “overDelegationThreshold”: “100” entry stands for, as I couldn’t identify a related entry in the baker registry app?
  2. I’m wondering where the “paymentConfig” data is stored, as it does not appear in the big map, yet it is displayed correctly in the app?

In addition, I found a minor typing error in the baker registry app. In the “Baking Rewards & Payment Details” section, line 6 (“Compensate Low Priority Endrosement Loss”), endorsement is wrongly typed.

1 Like

Thanks for the feedback, we really want to encourage everyone to ask any question they might have and to point out any potential issues.

  1. The “overDelegationThreshold” is not being used for anything by either the contract or the app. It is left over from an attempt to model overdelegation. It’s use might be revived in the app in v2 but for now it can be ignored.
  2. The “paymentConfig” you see defined in the FAQ schema and displayed in the app is a set of booleans. But for efficiency the contract storage uses a single integer value rather than multiple booleans. The field in the contract is “paymentConfigMask” and the bits of that integer are converted to booleans on retrieval of the data by code found in the tcfBakerRegistry.js and converted back to the mask in the app code found in HomeController.js

The typo you pointed out has been fixed. If you don’t see the change do a full refresh of the web page in your browser to ensure your local web page cache is being cleared for the registry app.

1 Like