[Tutorial] OAK Testnet Validator Upgrade Guide — v1.0.1

High priority release: validators should update within 6 hours.

Hi OAK Community members,

OAK’s node version has been upgraded to v1.0.1 in this release, and we require all validator runners on OAK Testnet to upgrade their node with the latest docker image. Please follow below instructions to perform the node upgrade.

We are preparing our canary network to become a parachain in Kusama, we have upgraded our Substrate and Polkadot to v0.9.10 and created a new release. As part of that, we ask all validators to please update their nodes to the latest docker image. Remember that our previous tutorial might be helpful in setting up validators.

All nodes should be upgraded to the latest version within 6 hours of its release if it is labeled “critical” or “high” priority and 24 hours if it is labeled “medium” or “low” priority. The v1.0.1 release is a high priority one, so please update your validators within 6 hours.

Context

There are 4 ways to update a standalone blockchain. The differences are important, and for this post, we are focused on #3.

1- RUNTIME: The blockchain logic or the state transition function. These upgrades are fairly straightforward and outlined in this Substrate tutorial. A given developer can update this in the PolkadotJS application. In lib.rs, you’ll find different versions that need to be set:

· spec_version needs to be bumped if consensus-critical logic has changed

· impl_version needs to be bumped if the changes applied do not affect consensus in the network.

2 - DATABASE MIGRATION FUNCTION: The blockchain logic’s way of storing into the storage (in #4).

· This is where a on_runtime_upgrade function is called (within your runtime files) when you change the schema of your database.

· If the new runtime logic (#1) does not understand your current blockchain storage (#4), the chain will break. This is the bridge between any interaction changes between #1 and #4.

3 - NODE CLIENT: Code that isn’t in the state transition function (aka runtime).

· This should be everything that isn’t in OAK-blockchain/runtime/. But more specifically, it’s whatever is in OAK-blockchain/node.

4 - DATABASE: The blockchain storage

· This is in the /data directory.

· Each validator has their own DB for the node that has the state of the chain. So when you query the “state chain” under the PolkadotJS Developer tab, you are viewing a finalized state chain where all X validators agree (from their respective /data DBs) on.

Upgrade Timeline

· 11/3 1600PST — Publish the guide on Medium and Discord.

· 11/3 1900PST — OAK dev team pilot the upgrade owned validators. (Built off of v1.0.1)

· 11/3 1930PST — Notify all community members on Discord and WeChat.

· 11/3–11/4 — Validate that the chain is in good health (producing blocks, data checks, etc.).

Instructions

Below are instructions to update your node client.

1. Backup the data. Existing validators need to copy blockchain data from the Docker container to a persistent disk volume. New users can skip this step.

# Create working directory
mkdir ~/oak-testnet
# Stop container 
docker stop <container_name>
# Copy the data directory to the host
docker cp <container_name>:/app/data ~/oak-testnet/data

2. Launch it!

2.1 Pull the latest Docker image.

docker pull oaknetwork/oak_testnet:latest

2.2 Stop your container (if you haven’t already).

docker stop <container_name>

2.3 Delete your old container.

docker rm <container_name>

2.4 Run the new image.

docker run -d --name <container_name> -v ~/oak-testnet/data:/app/data oaknetwork/oak_testnet:latest --name <node_name> --validator

3. Monitor the logs to make sure the node is syncing correctly.

docker logs -f --tail=200 <container_name>

4. Validate that the native runtime is: oak-testnet-268. For example,

2021–11–01 15:54:17 💾 Database: RocksDb at ./data/validator3/chains/oak_testnet_staging/db
2021–11–01 15:54:17 ⛓ Native runtime: oak-testnet-268 (substrate-node-1.tx2.au10)

Congratulations, you are all set! If you encounter people and problems during this process, please contact the developers of OAK Network in Discord Server.

Stay tuned for further information about the OAK Network here on Medium, Twitter and LinkedIn, as well as in our Discord Server!

Please check out our engineering and growth job openings, contact partner@oak.tech for partnerships, or contact@oak.tech for any general inquiries.