Voting on Tezos Proposals with your Ledger Nano S

Obsidian Systems
5 min readFeb 28, 2019

In Tezos’ Liquid Proof of Stake (LPoS) consensus mechanism, token holders vote on proposed protocol amendments with their stake. Token holders storing their tez on a Ledger Nano S hardware wallet will need ways to exercise their vote while keeping their assets stored safely on the device. That’s why we’re excited to announce Tezos Wallet v1.5.0, currently available in Ledger Live, supports the two operations used to engage in Tezos’ amendment process: the Proposal Operation and the Ballot Operation.

Delegates should familiarize themselves with how they can participate in all four periods of the amendment process, as Nomadic Labs has now proposed two amendments to the protocol. It is up to the community to vote on these proposals, decide if one of them will be promoted to mainnet, and exercise one of Tezos’ most powerful features for the first time.

If you have not already, I recommend reading this piece by Jacob Arluck on Amending Tezos to establish a base understanding of how the Tezos protocol is amended. This article builds upon that piece by offering delegate’s instruction for taking part in all four periods of the amendment process.

The Proposal Period: Proposing Amendments

During the Proposal Period, delegates (bakers) can make proposals and ‘upvote’ proposals they support. Conveniently, the proposal operation is used for both making and upvoting a proposal:

tezos-client submit proposals for <DELEGATE> <PROTOCOL-HASH>

<DELEGATE> is the delegate making the proposal. This address must be a registered delegate with at least one role, i.e. one vote. Each baker can submit up to 20 proposals during the Proposal Period. Submitting the same proposal twice will not result in two votes for the same proposal, but it will count against a baker’s allowed proposals, so it advised that you do not vote for the same proposal twice.

<PROTOCOL-HASH> is the hash of the tarball of concatenated .ml/.mli files that constitute the proposed amendment. You can find the hash of both proposals submitted by Nomadic Labs in their blog post.

When submitting a proposal, the Ledger hardware wallet will display four screens:

Submit ProposalProtocol
<Protocol Hash>
Source
<Delegate>
Period
<Voting Period>

Be sure to confirm you are voting for the right proposal on the UI of the Ledger Nano S!

Note: tezos-client permits voting on up to 20 proposals at the same time by including multiple protocol hashes in the operation, but the Ledger Nano S only allows you to confirm operations with one proposal on the device. Sending an operation with more than one proposal to the Ledger Nano S will not cause the operation to fail; instead the device will display Unparsed Operation, Sign Unverified?. Since this does not allow you to confirm what you are voting for, we do not recommend voting on more than one proposal at a time with the Ledger Nano S.

The Exploration Vote Period: Deciding to Test a Proposal

The proposal with the most votes advances to the Exploration Period, where bakers vote on whether the proposal should be tested.

To vote on whether a proposal should be tested, use the ballot operation:

tezos-client submit ballot for <DELEGATE> <PROTOCOL-HASH> <yay|nay|pass>

<DELEGATE> and <PROTOCOL-HASH> in the ballot operation are the same as described in the proposal operation. Bakers should also include what their vote on the proposal is, either yay, nay, or pass (i.e. abstain). Be sure to check your vote on the Ledger Nano S UI before submitting! The device will display:

Confirm Vote
<Yea|Nay|Pass>
Source
<Delegate>
Protocol
<Protocol Hash>
Period
<Voting Period>

Baker’s can only vote once during the Exploration Period. A delegate’s vote is based on the number of rolls in their staking balance at the beginning of the Exploration Period, which may not be the same total as when their vote is cast!

The Testing Period: Observing the Proposal on a Test Chain

At the conclusion of the Exploration Vote Period, baker’s ballots are totalled. If a quorum (which begins at 80%) is reached and a supermajority (which also begins at 80%) of non-abstaining votes voted yay, the proposal advances to the Testing Period. If either of those conditions are not met, the network begins a new Proposal Period.

The Testing Period is the only period where no votes take place, but that does not mean it is a time for delegates to be passive! The test chain that forks from the main chain has all the same baking and endorsing rights as the main chain. Delegates should participate by running a separate baker and endorser on this test chain to ensure test conditions accurately resemble the main chain (you do not need to run a separate node). Your participation is critical to ensuring the test chain accurately resembles the main chain!

Baker’s using a signer with a high-water mark feature, such as Tezos Baking for the Ledger Nano S, should be conscious of how their high-water mark can be problematic if actively signing on two chains. Once a delegate signs a given right on one chain, the high-water mark will prevent them from signing the same right on the other chain.

For that reason, we will be releasing a new version of Tezos Baking that supports signing on two chains early next week! This new version uses some new tezos-client commands, so we’ll be providing detailed instructions for bakers with its release.

Promotion Period: Deciding to Accept a Proposal

Voting during the proposal period is nearly identical to ballots placed during the Exploration Vote Period: delegates use the ballot operation to cast votes weighted by rolls in their staking balance, and supermajority for quorum and non-abstaining yay votes must be reached for the amendment to advance.

tezos-client submit ballot for <DELEGATE> <PROTOCOL-HASH> <yay|nay|pass>

The difference is the outcome: if an amendment succeeds in obtaining both supermajorities, it will be promoted to mainnet in the form of a new protocol.

With the beginning of the new protocol, we concurrently begin a new Proposal Period, and participants in the Tezos network are free to propose new amendments!

Summary

Proposal Operation

tezos-client submit proposals for <DELEGATE> <PROTOCOL-HASH>
  • Used to propose amendments in the Proposal Period
  • Used to upvote proposed amendments in the Proposal Period

Ballot Operation

tezos-client submit ballot for <DELEGATE> <PROTOCOL-HASH> <yay|nay|pass>
  • Used to vote on whether a proposed amendment should be tested in the Exploration Vote Period
  • Used to vote on whether a proposed amendment should be promoted to mainnet in the Promotion Period

Have questions? Want to learn more? Send a tweet to @obsidian_llc or join our Baker Slack by emailing tezos@obsidian.systems!

--

--

Obsidian Systems

Software consultancy specializing in haskell, nix, curiosity, and innovation.