Telos Governance Explained : The “regproducer” Human-language Contract

This contract was voted into effect by members of the Telos Blockchain Network contributors group on October 12, 2018 with a vote of: Yes — 20, No — 0, Abstain — 0.

Read the full document here: https://medium.com/@teloslogical/telos-regarb-human-language-contract-e1a4d0650128

Telos governance documents are thorough in an effort to give clarity about what is and isn’t allowed in our network, and when something is not allowed, what is to be done about it. This is different than the approach taken by EOS, and it yields long, boring documents. The hope is, however, that when people need to know how the network is supposed to run, they will have a very clear set of rules and procedures.

To help in understanding these governance documents and what problems they are intended to solve, I am writing an explainer for each, going clause-by-clause. This one is for the “regproducer” contract that is the primary way that block producer rules are set and enforced.

— Douglas Horn

Data Structures

Producer account name: {{producer}}
Producer signing key: {{producer_key}}
Producer ownership information: {owner:{name}, percentage_owned{percentage}, identity_provider_service {idprovider}, ID_hash {idhash}}
Candidate Name: {{producer_name}}
Candidate Website URL: {{producer_URL}}
Candidate Domicile Country (2-letter country code): {{entity_domicile_country}}
Candidate server location(s): {server:{location_name}, {server_location_country}, {server_location_latitude}, {server_location_longitude}}

Feel free to skip this one. These are JSON data structures that are filled-in by the person executing the contract. This way block producer information will be stored in this contract instead of on a bp.json file stored on the internet. Wherever a data value name like {{producer}} shows up in the text below, it will be replaced with the name of the producer account that was input by the block producer candidate, such as ‘goodblocktls’.

1. Intent of Action — {{ regproducer }} The intent of the {{ regproducer }} action is to register an account as a block producer candidate, to enumerate the obligations and rules of block producer candidacy and operation, and to inform producers about the penalties and penalty process for violation of these rules and obligations.

The “regproducer” action is how someone nominates themselves to be a block producer candidate. In doing so, they must agree to the terms of the contract.

2. Nomination

I, {{producer}}, hereby nominate myself for consideration as an elected block producer. This nomination includes the express agreement to all terms of this human-language contract by the block producer candidate entity and all of its owners.

So here is where they nominate themselves. It binds all of the owners of the entity to the contract terms.

3. Disclosure of Producer Key

If {{producer}} is selected to produce blocks by the “eosio” contract, I will sign blocks with {{producer_key}} and I hereby attest that I will keep this key secret and secure. If I suspect my key has been compromised, I will call this contract again with a new secure key.

Each producer account will use a specific public/private key pair to securely sign blocks. Here, the BP candidate agrees to keep their key secret and secure and use a new one if it has been compromised.

4. Disclosure of Entity and Server Information

I, {{producer}}, acknowledge that I have disclosed accurate information about my block producer entity and server location(s). Server location data is accurate to within two degrees of latitude and longitude. The country of domicile of my ownership entity, expressed as a 2-letter ISO code is {{entity_domicile_country}}. The location(s) or my block producer server(s) is {{location_name}}, location country, expressed as a 2-letter ISO code is {{server_location_country}}. The location of my block producer server(s), expressed as latitude and longitude is {{server_location_latitude}}, {{server_location_longitude}}.

Here, the BP candidate promises that the information revealed in the data structures is accurate. Some of this information may be used to optimize arranging BPs within a rotation schedule so it should be accurate. However, accuracy needn’t be perfect and giving some leeway means that BPs don’t need to reveal their exact location, which could be a potential exploit.

5. Penalty Enforcement via “enforcebprules” Contract

I, {{producer}}, acknowledge that if I fail to fulfill the obligations or violate the rules set forth in this contract, that the other block producers shall impose upon me the penalties enumerated for the corresponding violation. The vehicle for this enforcement shall be the “enforcebprules” contract or the votes of block producers, until the “enforcebprules” contract shall be accepted by a vote of 2/3+1 of all block producers. Proceedings, whereby contract or block producers, shall commence when 3 or more block producers allege a violation of the rules and present evidence of the violation. The “enforcebprules” contract shall alert me if I am accused of a violation or I will be alerted by an on-chain message from the accusing block producers and I will have a maximum of 200,000 blocks (approximately 28 hours) to post a rebuttal to the evidence presented against me prior to other block producers voting. If I elect to refer the matter to arbitration rather than enforcement from the “enforcebprules” contract or by the block producers, then I will remove myself from service until an emergency arbitration by Elected Arbitrators can be performed. If I am found to have not violated the rules as alleged, then the Assigned Arbitrator may consider restitution of lost revenue to me from either the accusers or the WPS. If a 2/3+1 majority of elected block producers votes that they are convinced the infraction did occur, then the associated penalty shall be imposed.

What happens if someone breaks a rule? It’s important that we all agree going in not only what the rules are, but also the expected punishments, and the means of enforcement. Without that, there is no clear way to agree what is a fair punishment. (One thing that makes it fair is that everyone agreed to it going in.)

This clause clarifies that any punishments will be done by the block producers using the “enforcebprules” contract, once it is deemed ready by a 2/3+1 vote of the block producers. Until then, the block producers will vote directly. Once a BP has been accused, they will have about 28 hours to respond. That may seem like not much time, but BPs need to be able to respond to system crises quickly. And frankly, if a BP has been accused for some infraction, there need to be a resolution quickly. Moreover, the accusation is meant to be accompanied by evidence, such as on-chain proof. Without this evidence, no other BP will likely vote for punishment, and with it, the question really comes down to whether the prohibited action was intentional or not. Many of the proscribed actions here occur accidentally from time to time in the normal operations of the blockchain. This is one reason why the block producers are called on to judge these actions — because they are in the best position to determine if something happened due to a reasonable mistake or from bad intentions. In this context, 28 hours is plenty of time to become aware of the accusation and write up some response. If the accused block producer prefers to be heard by emergency arbitration, they may request this and remove themselves from block production during the time the case is being heard. The arbitrator may assign damages for lost production revenues.

6. Obligation to Enforce Block Producer Rules

I, {{producer}}, acknowledge that at any time I serve as a block producer, I shall enforce the rules and associated penalties set forth in this human-language contract when another block producer reports evidence of an alleged violation in the form of executing the “enforcebprules” contract. When “enforcebprules” is executed by any block producer, I have the obligation to assess all evidence presented both by the accuser and the accused and vote whether the evidence persuades me that the alleged infraction has occurred. I shall, within 150,000 blocks (approximately 24 hours) of the rebuttal from the accused having been provided or the time period for providing a rebuttal expiring, cast a definitive yes or no vote via the “enforcebprules” contract or otherwise vote to enact a penalty, as to whether I am convinced the violation occurred, unless the accused has requested arbitration to settle the matter. Failure to vote within 150,000 blocks shall place me in violation of the block producer minimum requirements until either I vote, or the “enforcebprules” contract or penalty is enacted by a majority of 2/3+1 of all block producers. If I discover evidence of a violation of this human-language contract by another block producer, I am obligated to execute the “enforcebprules” contract or otherwise inform the block producers of my knowledge of the accusation and provide evidence of the alleged violation as quickly as I may fully investigate and collect evidence.

All the rules and enforcement schemes in the world don’t help if they aren’t enforced. The last piece of having a good set of rules for self-regulation by the BPs is to obligate them to actually enforce the rules. This clause binds BPs to enforce both by reporting apparent infractions and by casting a vote one way or another when another BP is accused. If a BP does not vote on enforcement, then they are out of compliance with the BP minimum requirements and will, themselves, be unable to serve as BPs soon. Naturally, BPs can vote that they either believe the charges or not. The point is that they must make a public decision.

7. Resignation and Removal for Inability to Perform Obligations

If {{producer}} is unable to perform obligations under this human-language contract I will resign my position by resubmitting this contract with the null producer key. If {{producer}} fails to resign when unable to perform said obligations, {{producer}} shall be removed by automated contract or by actions of the remaining block producers. {{producer}} may be removed at any time when it fails to produce 15% or more of its assigned blocks in a rotation of the block producer scheduling routine, or when 1/3-1 block producers are failing to produce blocks on the current schedule and {{producer}} is the block producer with the highest number of missed blocks or the lowest percentage of Member votes among the group of block producers that is failing to produce blocks.

BPs are expected to remove themselves from service any time they cannot produce blocks. They can return again by running “regproducer” and will not lose their accumulated votes. As promised in the Telos white paper, BPs who are not producing regularly will be removed from service so that another BP can step in. This is a major improvement in network security. The white paper envisioned this happening after 30 minutes of missed blocks, but once we actually got into the code, it became clear that this was not the ideal way, so we made revisions. Now, a BP is removed whenever it fails to produce 15% of the blocks in its current schedule. A BP can also be removed whenever a number of BPs are suddenly down to quickly clear out the non-performers and get more active ones in. The non-performing BPs can’t be kicked out all at once, so one at a time they get replaced, searching for others who are operational, until the crisis is resolved. This is essentially a crisis situation response to prevent the chain from locking up.

8. Objectively Valid and Invalid Blocks

I, {{producer}}, acknowledge that a block is “objectively valid” if it conforms to the deterministic blockchain rules in force at the time of its creation, and is “objectively invalid” if it fails to conform to those rules.

This is the same definition used in the EOS “regproducer” contract. (In fact “regproducer” is the only one of the Telos governance docs that still bears much resemblance to its EOS counterpart.) The reason for this clause is to give us some objective definition of what a “good” and “bad” block are.

9. Signing of Messages with Producer Key

I, {{producer}}, hereby agree to only use {{producer_key}} to sign messages under the following scenarios: proposing an objectively valid block at the time appointed by the block scheduling algorithm, pre-confirming a block produced by another producer in the schedule when I find said block objectively valid, confirming a block for which {{producer}} has received 2/3+1 pre-confirmation messages from other producers. Apparent intentional violation of the preceding, as judged by a majority of 2/3+1 of all block producers, shall be cause for my disqualification from all service as a block producer for 16,000,000 blocks (approximately 90 days) on first offence or 63,000,000 blocks (approximately 365 days) on second or subsequent offenses. I may also be liable for liabilities due to this action.

Now that the preliminaries are handled, we move into a number of clauses that list things that BPs can’t do. They are all quite similar: they start with the proscribed action, add a bit about how it will be determined if they violate this, and what the penalties are for violating them on first and subsequent offenses.

Here, we lay out what is acceptable in signing a block: it has to be the BP’s turn and that block has to be valid. If the BP is found to have signed non-valid blocks or signed out of turn (intentionally — because this happens accidentally sometimes) then the punishment is restriction from serving as a BP for 90 day the first time and 1 year after that.

10. Acceptance of Liability and Damages

I, {{producer}}, hereby accept liability for any and all provable damages that result from my: signing two different block proposals with the same timestamp with {{producer_key}}, signing two different block proposals with the same block number with {{producer_key}}, signing any block proposal which builds off of an objectively invalid block, signing a pre-confirmation for an objectively invalid block, signing a confirmation for a block for which I do not possess pre-confirmation messages from 2/3+1 other producers. Apparent intentional violation of the preceding, as judged by a majority of 2/3+1 of all block producers, shall be cause for my disqualification from all service as a block producer for 16,000,000 blocks (approximately 90 days) on first offence or 63,000,000 blocks (approximately 365 days) on second or subsequent offenses. I may also be liable for damages due to this action.

More stuff BPs can’t do: sign invalid blocks or extend a fork that builds on invalid blocks. Also, for making an irrevocable block that doesn’t have all the necessary signatures from previous BPs in the schedule. For intentional violators, the punishment is restriction from serving as a BP for 90 day the first time and 1 year after that.

11. Malicious Collusion

I, {{producer}}, hereby agree that double-signing for a timestamp or block number in concert with 2 or more other producers shall automatically be deemed malicious and subject to a fine equal to the past year of compensation received, and other damages. An exception may be made if {{producer}} can demonstrate that the double-signing occurred due to a bug in the reference software; the burden of proof is on {{producer}}. Apparent intentional violation of the preceding, as judged by a majority of 2/3+1 of all block producers, shall be cause for my disqualification from all service as a block producer for 63,000,000 blocks (approximately 365 days) on first offence or 315,000,000 blocks (approximately 5 years) on second or subsequent offenses.

BPs can’t collude to fork the chain. If found to be working together with other BPs to do this, the act will be assumed to be malicious unless proven otherwise. This has a big penalty: 1 year the first time, 5 years each time after that.

12. Interference with Block Producer Election Process

I, {{producer}}, hereby agree not to interfere with the producer election process. I agree to process all producer election transactions that occur in blocks I create, to sign all objectively valid blocks I create that contain election transactions, and to sign all pre-confirmations and confirmations necessary to facilitate transfer of control to the next set of producers as determined by the system contract. Apparent intentional violation of the preceding, as judged by a majority of 2/3+1 of all block producers, shall be cause for my disqualification from all service as a block producer for shall be cause for my disqualification from all service as a block producer for 16,000,000 blocks (approximately 90 days) on first offence or 63,000,000 blocks (approximately 365 days) on second or subsequent offenses.

To maintain fair elections, BPs cannot change how votes are recorded on the network. Penalties are 90 days and 1 year.

13. Adherence to Block Producer Minimum Requirements

I, {{producer}}, hereby acknowledge that violation of the Telos Block Producer Minimum Requirements shall be cause for disqualification from service of {{producer}} as a block producer until {{producer}} is once again in compliance. Compliance shall be monitored and enforced by smart contract, oracle, other objective, or disinterested party as the network developers shall initially designate on network launch or subsequently amend. The current Telos Block Producer Minimum Requirements shall be recorded on chain at a publicly disclosed address.

BPs need to be in compliance with the BP Minimum Requirements, which are recorded on the blockchain. BPs can be removed from service for being out of compliance no matter how many votes they have. Generally they get 24 hours to cure this first — otherwise it’s possible that this could become a point of failure for the network. In the future we intend for this to be monitored and automated on-chain. However, at the moment it is likely to include outside oracles, and even intervention from other BPs to remove a BP that is out of compliance. These minimums include not being under penalty for violations, which is how the violation penalties are enforced.

14. Authentication of Network Peers

The community agrees to allow {{producer}} to authenticate peers as necessary to prevent abuse and denial of service attacks; however, {{producer}} agrees not to discriminate against non-abusive peers. Apparent intentional violation of the preceding, as judged by a majority of 2/3+1 of all block producers, shall be cause for my disqualification from all service as a block producer for 5,000,000 blocks (approximately 29 days) on first offence or 32,000,000 block (approximately 180 days) on second or subsequent offenses.

Normally, BPs are supposed to let anyone peer with their nodes (BPs run different kinds of nodes and the block producer node itself is usually not connected directly to the internet, but only through a trusted Full Node.) However, when there is an apparent network attack such as DDOS, then BPs are allowed to block certain abusive peers. Otherwise everyone should be allowed to connect, and blocking nodes that aren’t abusive is punishable by 29 days / 180 days off the network.

15. Fair Dealing in Processing Transactions

I, {{producer}}, agree to process transactions on a first-in, first-out, best-effort basis and to honestly bill transactions for measured execution time. Apparent intentional violation of the preceding, as judged by a majority of 2/3+1 of all block producers, shall be cause for my disqualification from all service as a block producer for 5,000,000 blocks (approximately 29 days) on first offence or 32,000,000 block (approximately 180 days) on second or subsequent offenses.

BPs can’t play favorites and execute some people’s transactions before others. This prevents them from charging some Dapps fees in order to streamline the processing of transactions from them. That would be a type of ransom and is not allowed. So this is essentially our “net neutrality” clause. Violations are punishable by 29 days / 180 days off the network.

16. No Reordering Transactions

I, {{producer}}, agree not to manipulate the contents of blocks from the order in which transactions are included in the hash of the block that is produced. Apparent intentional violation of the preceding, as judged by a 2/3+1 majority of all block producers,shall be cause for my disqualification from all service as a block producer for 16,000,000 blocks (approximately 90 days) on first offence or 63,000,000 blocks (approximately 365 days) on second or subsequent offenses.

BPs may not reorder transactions in a block or subsequent blocks in order to profit. For example, a BP could theoretically see a huge exchange purchase order for a token in its queue and rather than execute it immediately, it could delay it a few blocks until the BP is able to buy a lot of that same token before the big order made the price jump. This is called front-running and Telos does not allow it or any other ways that BPs could enrich themselves through reordering transactions. Violations are punishable by 90 days / 1 year off the network.

17. Ownership

I, {{producer}}, hereby agree to disclose and attest under penalty of perjury all ultimate beneficial owners of my ownership entity who own more than 5% and all direct shareholders. When required by the Telos Block Producer Minimum Requirements, I shall also provide an identity verification hash from an accepted third-party identity verification service along with the name of that service. All owners of my ownership entity are listed herein:{{owner{name}, (percentage}, (idprovider}, {idhash}}. I will not misrepresent ownership or the penalty status of any owners in an attempt to evade penalties. No owner is currently under penalty for violating the human language terms of the “regproducer” contract. Misrepresentation includes misspelling or using an alternate writing of the same person or entity’s name, listing the name of an entity owned or controlled by more than 5% of a listed owner, or by listing the name of any person or entity who is not the true beneficial owner or their fiduciary. Apparent intentional violation of the preceding, as judged by a majority of 2/3+1 of all block producers, shall be cause for my disqualification from all service as a block producer for 16,000,000 blocks (approximately 90 days) on first offence or 63,000,000 blocks (approximately 365 days) on second or subsequent offenses.

BPs have to honestly report who their owners are (anyone over 5%). They cannot misrepresent their ownership by coming up with a fake owner or hiding behind a company name in an attempt to evade penalties. We expect to soon require an identity verification service for all owners that would allow a hashed value to prove each owner’s identity. Violations are punishable by 90 days / 1 year off the network.

18. Ownership of More than One Block Producer

I, {{producer}}, acknowledge that no entity, whether an individual, corporation, nonprofit, or decentralized organization, shall own any interest in more than one block producer candidate at any time. For the purpose of this paragraph, spouses, parents, children and siblings of an owner shall be considered the same as the owner. Any block producer with any owner currently under penalty by the “enforcebprules" contract is disqualified for the entire term of the penalty.

No one can own more than one BP, or any part of more than one at any time. This is also extended to immediate family members so that someone can’t just put BPs in several family members’ names. Also, no owner whatsoever may be currently penalized under the “enforcebprules” contract.

19. Producing Blocks on Schedule

I, {{producer}}, agree not to produce blocks before my scheduled time unless I have received all blocks produced by the prior producer. Apparent intentional violation of the preceding, as judged by a majority of 2/3+1 of all block producers, shall be cause for my disqualification from all service as a block producer for 5,000,000 blocks (approximately 29 days) on first offence or 32,000,000 block (approximately 180 days) on second or subsequent offenses.

BPs can’t produce blocks before their scheduled time unless all the blocks before them have been produced already. Violations are punishable by 29 days / 180 days off the network.

20. Producing Blocks on Accurate Time

I, {{producer}}, agree not to publish blocks with timestamps more than 500ms in the past or future unless the prior block is more than 75% full by either CPU or network bandwidth metrics. Apparent intentional or negligent violation of the preceding, as judged by a majority of 2/3+1 of all block producers, shall be cause for my disqualification from all service as a block producer for 5,000,000 blocks (approximately 29 days) on first offence or 32,000,000 block (approximately 180 days) on second or subsequent offenses.

BPs need to stick to accurate time. This is important because bad time sync throws everything off and actually makes it look like other BPs are the ones causing problems — mostly the BPs producing just before or after the one with the time-sync problem. (the BP Minimum Requirements also specify that they must sync their time to a NTP server at least once per day.) Violation is punishable by 29 days / 180 days off the network.

21. Setting Accurate RAM Supply

I, {{producer}}, agree not to set the RAM supply to more RAM than my block producing nodes can currently support. Apparent intentional violation of the preceding, as judged by a majority of 2/3+1 of all block producers, shall be cause for my disqualification from all service as a block producer for 5,000,000 blocks (approximately 29 days) on first offence or 32,000,000 block (approximately 180 days) on second or subsequent offenses.

BPs inform the network how much RAM they are able to provide. It’s important that they provide accurate amounts of RAM allocated on their nodes. Violation is punishable by 29 days / 180 days off the network.

22. Voter-confusing Block Producer Names

I, {{producer}}, agree not to register a block producer name intended or deemed likely to create confusion among Telos voters as to their identity compared to other Telos block producers. Priority of names will be granted to the block producer candidate who first registered on the Telos network or Telos pre-launch testnet. Until the Telos network has been activated for six months, the same priority will be granted to block producer candidates who registered a block producer name during the first 30 days of the original EOS mainnet. Violation of the preceding, as judged by a majority of 2/3+1 of all block producers, shall be cause for my disqualification from all service as a block producer until a new block producer name is registered. There shall be no further penalty for this violation.

We don’t want situations where a block producer candidate comes in and tries to confuse voters either by changing just one letter of a BP account name or by taking on the name and apparent identity of an existing Telos or prominent EOS block producer. We’ve seen this happen and it does not honor the votes of the token holders. Therefore, if a block producer candidate comes on to the system with a name that the other BPs think will confuse voters, that BP can be removed until it comes back with a name that is not deemed misleading. There’s no other penalty, though.

23. Amending “regproducer” Human-language Contract

I, {{producer}}, acknowledge that the terms of this human-language contract may be amended from time to time by Telos owners voting on the “ratifyamend” contract as described in the Telos Network Operating Agreement. If I do not consent to the new terms of the amended human-language contract, I must remove my block producer candidate from service. Remaining registered as a block producer more than 180,000 blocks (approximately 25 hours) after this human-language contract is amended indicates my acceptance of the new version.

The Telos governance documents can be amended. If this contract is amended, and a BP candidate doesn’t agree with the changes that candidate must remove themselves from the network. Remaining as a BP for more than a day means that they accept the new terms.

24. Definitions

The term “block producer” shall be deemed to mean one of the up to 21 block producer candidates actually validating transactions on the Telos network, including any non-elected block producer candidate serving the validating function due to the failure of another block producer, or rotation schemes intended to aid network health, or any other reason. The term “second or subsequent offences” shall refer to violations of any offence described within the same paragraph of this human-language contract, but not to offences described in different paragraphs. A second or subsequent offence shall only apply if a majority of 2/3+1 block producers voted to impose a penalty on a previous alleged offence. A majority of “2/3+1” shall mean a number greater than or equal to 2/3rds of the total number plus one additional. For clarity, when the total is 21 block producers, a 2/3+1 majority would require the votes of 15 block producers. A “human-language contract” means the portion of a smart contract that is written in a human language such as English or Korean as opposed to a computer language such as C++, with the goal of clearly expressing the intent of the transaction between the user executing the contract and the person or entity that controls it. An “accepted third-party verification service” means a service or entity providing identification verification as a cryptographic hashed value that is listed on a list maintained on-chain by the Telos Block Producers and amended by a vote of 2/3+1 Block Producers. The “‘regproducer’ contract” means any Telos system contract or contracts that is designed to nominate an entity as a block producer candidate, whether or not the contract is actually named “regproducer”. The “‘enforcebprules’ contract” means any Telos system contract or contracts that is designed to enforce the Block Producer Minimum Requirements or “regproducer” contract, whether or not the contract is actually named “enforcebprules”. The “‘ratifyamend’ contract” means any Telos system contract or contracts that is designed to allow Telos Members to ratify or amend any of the Telos Governance Documents, whether or not the contract is actually named “ratifyamend”. The terms “‘eosio’ contract” and “system contract” mean the core operating system contract or contracts of the Telos EOSIO system, whether or not the contract is actually named “eosio”.

These are just a bunch of definitions: block producer, second and subsequent offenses, 2/3+1, human language contract, and accepted third-party verification service. They all mean exactly what you probably think they mean, but we make it super clear so no one can complain about technicalities. Where the contract mentions “regproducer”, “enforcebprules”, “ratifyamend”, and “eosio” contracts so we make it clear that any contract or contracts that perform these intended functions are what is meant, even if the name is different.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Telos Foundation

Telos Foundation

Telos Foundation is an entity charged with promoting Telos, a networked ecosystem for turning purpose into reality. http://www.telosfoundation.io/