Flextesa: Protocol Upgrades

In a previous post, we showed how to perform protocol changes using user-activated-upgrades (a.k.a. “hard-forks”). Now, we are making it easy to run sandboxes which go through the whole governance process.

In the latest release oxheadalpha/flextesa:20220321, we have modernized the "daemons-upgrade" scenario, which has been in the Octez repository for a long time (but is hard to build/manipulate by mere mortals), and included it in the main flextesa application.

This article walks through the daemons-upgrade sandbox scenario with a few Docker commands. The implementation can be found in this script, which is a call to flextesa daemons-upgrade (see its general documentation).

Starting the Sandbox

Let’s start with the following example:

$ image=oxheadalpha/flextesa:latest
$ script=hangzbox
$ docker run --rm --name my-sandbox -p 20000:20000 --detach \
             "$image" "$script" start_upgrade

As stated above, the image is oxheadalpha/flextesa:20220321 (also available as oxheadalpha/flextesa:latest). There are two script options available, each starts a sandbox with two nodes (bakers).

• hangzbox: Starts the Hangzhou protocol and upgrades to the Ithaca-2 protocol.
• ithacabox: Starts Ithaca-2 protocol and upgrades to the Alpha protocol.

With the start_upgrade command the sandbox network will do a full voting round over all five periods: proposal, exploration, cool down, promotion, and adoption. Each period, the bakers will vote "yay" for the next protocol, thus progressing to the next round of voting. The protocol will upgrade after the adoption period and continue baking for a few years, or until you kill the container (whichever comes first).

Interacting with the Sandbox

You can use any client, including the tezos-client. Its useful to setup an alias:

$ alias tcli='docker exec my-sandbox tezos-client'
$ tcli get balance for alice
2000000 ꜩ

With tcli above and jq you can keep checking the following to observe the protocol change:

$ tcli rpc get /chains/main/blocks/head/metadata | jq \
.level_info,.voting_period_info,.protocol
{
  "level": 22,
  "level_position": 21,
  "cycle": 2,
  "cycle_position": 5,
  "expected_commitment": false
}
{
  "voting_period": {
    "index": 1,
    "kind": "proposal",
    "start_position": 16
  },
  "position": 5,
  "remaining": 10
}
"PtHangz2aRngywmSRGGvrcTyMbbdpWdpFKuS4uMWxg2RaH9i1qx"

A list of the commands available is visible with:

$ docker exec my-sandbox $script help

Stop the sandbox, and clean-up your resources with:

$ docker kill my-sandbox

Options Available

There are a few useful environment variables that you can pass to docker run. For example:

$ docker run --rm --name my-sandbox -p 20000:20000 --detach \
             -e block_time=2 \
             -e blocks_per_voting_period=12 \
             -e extra_dummy_proposals_batch_level=2 \
             -e extra_dummy_proposals_batch_size=2,4 \
             "$image" itacazbox start_upgrade

With blocks_per_voting_period you can adjust the length of the voting periods. Batches of dummy proposals will be inserted with extra_dummy_proposals_batch_size. These proposals can be scheduled at specific block-levels within the first (Proposal) voting period, using the variable extra_dummy_proposals_batch_level.

The example above will result in 5 total proposals, ultimately upgrading to the Alpha proposal. The block_time option lets you to set the time between blocks in seconds.

The default values for these options are:

• block_time=5
• blocks_per_voting_period=16
• extra_dummy_proposals_batch_size=2
• extra_dummy_proposals_batch_level=3,5

Hopefully, the information in this article is enough to get your protocol-upgrade sandbox up and running. If you would like to read more on Flextesa, please see the repository.

Happy testing!