Deploying a Custom Protocol in Tezos

Jeremy Ornelas
Jun 7 · 6 min read

The Tezos white paper takes the view that blockchains can be viewed as the synthesis of three distinct protocols; namely network, transaction, and consensus. However, for many blockchains the network protocol is just a detail that must be figured out before being able to deploy the more novel consensus and/or transaction systems. Tezos realized this and created a generic shell that is agnostic to these two protocols. Thus, it may be advantageous for such chains to first model themselves inside of Tezos before dealing with such plumbing. This, however, is predicated on the deployment and creation of the protocols being easier than dealing with the networking plumbing.

This blogpost sets out to show that deploying a custom protocol in Tezos is rather simple. A future post will be a detailed walkthrough of creating a protocol.

Requirements

For active development, Tezos currently supports

  • macOS/x86_64
  • Linux/armv7h (32 bits) (Raspberry Pi3, etc.)
  • Linux/aarch64 (64 bits) (Raspberry Pi3, etc.)

Currently Windows development is not supported.

For deployment of Tezos, a working installation of OCaml, Dune, and Opam are required.

Prepping the environment

We will first need to clone the Tezos code base.

Now I would suggest running make build-dev-dep.

  • build-dev-deps installs Merlin which is useful for OCaml development.
  • This will also create an Opam switch with the Tezos custom compiler.

Run eval $(opam env), to properly go to the correct OCaml compiler version.

We can now run make install, and finish the environment preparations.

Constructing a dummy protocol

For the purposes of this tutorial, we will be copying the proto_demo protocol, and modifying the bare minimum to make a distinct protocol. The new protocol's name is proto_custom_demo, feel free to replace any mention of proto_custom_demo with your own protocols name. This section will also cover the essentials for getting the development environment working properly.

  1. Copy the demo protocol over to the new folder.
  • cp -r src/proto_demo src/proto_custom_demo

2. Cd into the new directory

  • cd src/proto_custom_demo/
  • The new directory should look like this

3. In this directory we will need to change/remove a few file names to make this protocol distinct, namely:

  • Thus we need to run

4. The Contents of some of these files need to be slightly altered as well. In the dune file of lib_client, any mention of _demo or-demo should be changed to _custom_demo and -custom-demo

The opam files in both directories will also need to be changed, mentions of demo should be changed to custom_demo. lib_client should also first change-demo to -custom-demo first to avoid a naming error

  1. The last thing that needs to be changed for now is the lib_client/proto_demo.ml, namely
  • to

5. Now we need to generate a new dune.inc file, this will serve as the injection of how the rest of Tezos sees your code, setups environments, and allows auto completion to run. This file is normally completely automatically generated, however since we copied over proto-demo, we must first run a few sed commands on it before it will actually change

  • We can now generate our new dune.inc file
  • Every time you make a new file, I’d suggest rerunning this last command!

6. Now we should change lib_protocol/TEZOS_PROTOCOL, by default the file looks something like this

For any new modules (i.e. new files), we will need to include them here.

We will also need to change the hash of this JSON structure, as proto_demo already has this hash registered. Note that we can not insert an arbitrary hash, by say turning the 9 into 0, instead it must be a valid hash.

Thankfully, Tezos comes with a script that can automatically generate the hash for us.

tezos-protocol-compiler -hash-only ./lib_protocol/

  • This generates a hash of the protocol, replace the hash of json file shown above with this newly generated hash.

7. Change lib_client/client_proto_main.ml to reflect the new hash.

The file contains the following line

Change it so it includes the new hash!

8. Now rerun

9. We will need to tell Tezos about our protocol now, we can do this in multiple ways, first we’ll cd back to the root directory and run scripts/activate_protocol.sh

Like above you’ll want to say yes to the first prompt and no to the second.

This command however has some draw backs, in particular it’ll add the following unwanted lines to src/bin_client/dune and src/bin_client/tezos-client.opam

  • "tezos-client-custom-demo-commands"
  • "tezos-baking-custom-demo-commands"
  • "tezos-client-custom-demo-commands"
  • tezos-baking-custom-demo-commands.registration
  • tezos-client-custom-demo-commands.registration

For a fully functioning client, this may be ideal, however since our protocol is a dummy one, all we need is the tezos-client-custom-demo links.

Go to these files and delete the offending lines.

Now the custom protocol should be able to be built!

Deploying your protocol

Now that we’ve constructed a protocol, all that is left is to test it. First, let’s go back to the root directory of the project and rerun.

A good guide with more details on the following steps can be found here.

  1. create a new terminal and run.

2. On your previous terminal run.

3. Now, if the instructions of the last section were followed correctly, you should be able to see your protocol in the following command

4. Inject the protocol.

5. Bake a block.

6. Check the head to confirm you are on the new protocol.

You’ve now deployed your own protocol on Tezos.

Cryptium Labs Tezos

Cryptium Labs offers secure and highly available digital signatures for Proof-of-Stake networks, such as Tezos, Cøsmos, and Polkadot. This blog is dedicated to anyone in the blockchain ecosystem and aims to provide educational content for all audiences on topics such as security.

Jeremy Ornelas

Written by

Cryptium Labs Tezos

Cryptium Labs offers secure and highly available digital signatures for Proof-of-Stake networks, such as Tezos, Cøsmos, and Polkadot. This blog is dedicated to anyone in the blockchain ecosystem and aims to provide educational content for all audiences on topics such as security.