-
Notifications
You must be signed in to change notification settings - Fork 26
Deploy a New Protocol Testnet
Protocol testnets are required each time there is a new protocol proposal by the core teams.
Every testnet is specified by a values file, e.g. networks/oxfordnet/values.yaml
A good place to start is to copy the previous testnet file.
The network is defined by the constants passed at block 1. The activation job is creating block 1 based on constants.
In order to test the protocol migration in more real conditions, the test network for protocol N always starts from protocol N-1. Therefore, it is necessary to create a set of constants compatible with protocol N-1 (for oxford, this would be the Nairobi protocol).
Modify the existing activation section of the yaml file based on the new protocol. A working set of constants can be found in the tezos-k8s repo, as well as some examples in the octez source code's tezt test suite.
It is a good idea to test these constants in isolation in minikube or directly in the production cluster. The activation job must pass.
Once constants are ready, verify with the core teams. Commit your file and push it, then submit it to the #proto-proposal slack channel for validation.
The teztnets repo also has a script in scripts/ to compare constants between mainnet, ghostnet and the proposed network. This script might need editing each time you use it. This is useful to spot differences that would be missed by just reading constants one by one.
Make sure that the testnet_dictator constant is set to a public key hash of an account that you control. Otherwise, you can't upgrade.
They are defined in the accounts: object of your values file.
Ask on Discord #teztnets and in the dev slack #teztnets-xyz channels for volunteers. Do not presume that the volunteers from the last round will show up. Comment all the bootstrap bakers (denoted by is_bootstrap_baking_account: True in yaml) out, then request people to open pull request or let you know, to add them back in.
Once the network activates, and block 1 has propagated, it is difficult to revert. Measure twice, cut once.
We typically assign a larger number to teztnetsbaker (10 to 1 ratio). This is because not everyone is always ready, and we don't want the chain to get stalled. Right after chain start, we redistribute most of this stake to the bakers that were actually active.
In node_config_network object, put a timestamp for when the network will activate. It goes in two places: chain_name by convention contains the timestamp of the chain start, and genesis contains a timestamp object that must be in the past when you activate your network. Otherwise, activation will fail.
15:00 UTC works well for most timezones. Give at least 24 hours after the RC is out before starting the network. Don't activate on a Friday.
133 node_config_network:
134 activation_account_name: teztnetsbaker
135 chain_name: TEZOS_OXFORDNET_2023-12-07T15:00:00Z
136 genesis:
137 protocol: Ps9mPmXaRzmzk35gbAYNCAw6UXdE2qoABTHbN2oEEc1qM7CwT9P
138 timestamp: "2023-12-07T15:00:00Z"
Some non bootstrap bakers have funds. Just carry over from past networks, unless someone asks. If someone asks, make sure that the person never registers this account as baker, as this would tip the stake heavily towards them.
Typically, when a new protocol is announced, a release candidate is announced. You must run it:
255 images:
256 octez: tezos/tezos:v19.0-rc1
Initially, both N-1 and N protocol must run:
258 protocols:
259 - command: PtNairob
260 vote:
261 liquidity_baking_toggle_vote: "pass"
262 - command: Proxford
263 vote:
264 liquidity_baking_toggle_vote: "pass"
265 adaptive_issuance_vote: "on"
Copy and paste from the previous network:
249 new TezosFaucet(
250 oxfordnet_chain.name,
251 {
252 namespace: oxfordnet_chain.namespace,
253 humanName: "Oxfordnet",
254 helmValuesFile: "networks/oxfordnet/faucet_values.yaml",
255 faucetPrivateKey: faucetPrivateKey,
256 faucetRecaptchaSiteKey: faucetRecaptchaSiteKey,
257 faucetRecaptchaSecretKey: faucetRecaptchaSecretKey,
258 chartRepoVersion: "6.25.0",
259 },
260 provider
261 )
262
Do not deploy the faucet yet. It does not deploy cleanly before the chain actually runs.
Long before you actually activate, you want the webpage to be up announcing the network.
You can write free form text in `networks/<your_network>/README.md, it will be displayed. These are typically instructions that are only applicable on network start (see git history of these files for examples).
As you deploy this code, it is a good idea to comment out the activation sections of the values file. Otherwise, you will deploy an activate job that will fail until the start date, and you won't be able to have clean pulumi ups. Uncomment it shortly before activation.
To deploy the webpage, make sure that your chain is exported in the pulumi outputs networks and teztnets, e.g.
449 export const teztnets = {
450 ...getTeztnets([dailynet_chain, weeklynet_chain, nairobinet_chain, oxfordnet_chain]),
451 ...{ ghostnet: ghostnetTeztnet, mainnet: mainnetMetadata },
452 }
Verify in k9s in the node logs that your node is peering with peers.
At the right time, uncomment the activation section of your yaml file. Then, do pulumi up locally. It is possible to do it with commit and push, but doing it manually is slightly faster and you are able to preview.
The activation job should run. If it doesn't, see other runbook how to run activation job again(TODO).
In the baker logs, you should see the block 1 preendorsed, then endorsed. If you only see preendorsed, it means that you don't have quorum. Reach out to the other bakers.
You may now deploy the faucet. Instantiate the TezosFaucet class:
At the end of cycle 1, perform a dictator upgrade to the protocol that was just announced. Verify in Nomadic Labs blog post what the correct hash is.
This requires the dictator address to have funds and be revealed. The easiest way to achieve this is to do a transfer in and out.
Dictator upgrades are just like proposal submission, except that the proposal automatically becomes adopted and the governance phase moves to phase 5 (adoption). Read more.
The command:
octez-client --endpoint https://rpc.<teztnet name>.teztnets.xyz submit proposal for dictator <hash> --force
Force is necessary otherwise the CLI assumes that the proposal is erroneous due to the absence of baking rights.
In case of mistake, it is possible to submit a subsequent upgrade before the end of the cycle. The new protocol supercedes the old one. It is possible to cancel it altogether by submitting the empty string as proposal.
In the protocols: section, after governance upgrade has taken place, it is now possible to remove the old protocol. Just remove the relevant object.
When Tezos mainnet has moved to the next protocol, the testnet serves no purpose, even though people might stick to it. It is a good idea to force users to the new network by bricking the testnet. This is done by using dictator key again, to upgrade it to a protocol that does not exist.
TODO: explain how to make a vanity proposal