Updating Nodes

Note

This information can be used by STRATO node administrators.

STRATO Platform Releases Overview

Semantic versioning with version numbers MAJOR.MINOR.PATCH
- A change in PATCH version implies backwards compatible bug fixes
- A Change in MINOR version implies an addition functionality in a backwards compatible manner
- A change in MAJOR version implies the breaking changes, usually requiring additional steps to upgrade the network nodes or making the upgrade impossible
New releases:
- Address security vulnerabilities
- Contain bug fixes
- Contain new features
- Contain performance improvements
When versions with critical bug fixes are released:
- We notify customers with a STRATO License and provide instructions for updating their nodes
- We mark releases accordingly on our release notes page at https://docs.blockapps.net/release-notes/
Average release cycle is 2 months
All STRATO release versions are tested to operate in "mixed networks" (networks with nodes of mixed release versions)

Node Update Process Highlights

The node update process requires some downtime of a node:
- Time to restart the STRATO containers
- Time for the restarted node to re-sync to the network
- Time for the restarted node to index the blockchain data (in parallel with sync)
On the high-level, the node update process is as follows:
- Stop blockchain node while keeping its Key Vault data
- Restart the blockchain node using the updated docker-compose.yml
- Wait for the node to synchronize to the network
Updating to some versions (usually major versions) may require custom steps - refer to STRATO Release Notes for more information
- When skipping versions between updates, make sure to check for special update requirements for each version skipped to ensure a proper updating process
Nodes in a network should be updated one at a time:
- Required for networks with private chains - to avoid all nodes having their private chain data from being wiped at the same time
- It is recommended that a majority of validators never be down on a network at the same time

Preparation steps

On each node:

Check if the node has any single-node private chains (private chains that are not shared with any other nodes in the network):
```
./strato --get-single-node-chains
```
(command available since STRATO Getting Started v3.3.0)
If there are any single-node private chains discovered, stop here and continue to the Update a Node with Single-Node Private Chains section first.
Fetch the docker-compose.yml of the newer version:
```
./strato --compose
```
Pull docker images of the new version (based on the docker-compose.yml):
```
./strato --pull
```
Check for additional requirements to update from previous version - for each version skipped
Confirm that the run.sh script that was initially used to deploy the node is in place
Continue with the same preparation steps on next node

Update nodes

Warning

The nodes should be stopped and resynced one at a time (see Node Update Process Highlights)

(Optional) If applicable, take actions required by your Application to prepare for STRATO downtime (e.g. Site maintenance warning, etc.)
Bring down the STRATO node by dropping the chains but keeping the Docker volume of the Key Vault:
```
./strato --drop-chains
```
(this command executes docker-compose down and the commands to remove unnecessary volumes that will be recreated with data from the network on the node’s restart)
Restart the node:
```
./run.sh
```
Re-enter the password when asked (unless provided in run.sh which is not recommended due to security risks)
Wait for the node to start
Wait for the node to fully sync to the network and for CMD health status to become green
(Optional) If applicable, revert the actions taken to prepare Application for downtime in step 1
Continue with the same steps on the next node

Update a Node with Single-Node Private Chains

Note

The following steps are only required for nodes with single-node private chains

High-level steps

Add a new temporary node to the network to be added as a member to the single-node private chains to keep their data for the time of the update process
Update the original node using the regular node update process (this will obtain the private chains from the temporary node)
Remove the temporary node as a member of all its private chains
Tear down the temporary node

Steps in Details

Note

As of STRATO 7.9, the process of adding a node to a private chain can be simplified using X.509 certificates. If a temporary node is booted with a registered certificate, it will pull all private chain data that is associated with the certificate's organization and organization unit. This eliminates the need to add and remove a member through a governance contract. The temporary node will sync to the network and the original node can be brought down and upgraded. Once the upgrade is complete, the node can be rebooted and the temporary node can be wiped.

Get the list of single-node private chains on the node:
```
./strato --get-single-node-chains
```
Add a new temporary node to the network using the same version as the original node being updated. Do not make the new node a validator.
Wait for the temporary node to synchronize with the network (to have the same number of blocks)

Add the temporary node as a member to the private chains listed in step (1), using the AutoApprove governance contract:

Obtain the Access Token for any user of the Identity Provider set-up on the node

Create a STRATO user account if does not exist:

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json" \
  'https://<strato_address>/strato/v2.3/key'

Add the temporary node as a member to each of the single-node private chains - repeat for every private chain from step (1).

curl -s -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json" \
  'https://<strato_address>/strato/v2.3/transaction/parallel?resolve=true' \
  --data-raw '{
    "txs": [
      {
        "payload": {
          "contractName": "Governance",
          "contractAddress": "0000000000000000000000000000000000000100",
          "method": "voteToAdd",
          "args": {
            "m": "<TEMPORARY_NODE_ADDRESS>",
            "e": "enode://<TEMPORARY_NODE_PUBLIC_KEY>@<TEMPORARY_NODE_IP>:30303"
          },
          "chainid": "<CHAIN_ID>"
        },
        "type": "FUNCTION"
      }
    ]
  }'

Note: depending on what governance contract is used for the private chain, the transaction's payload and the function call arguments may need to be different (see Governance section in Privacy topic)

Make sure the number of private chains on the temporary node is same as the number of single-node private chains in step (1). To check the number of private chains on a node:

docker exec strato_postgres_1 psql -U postgres -d `docker exec strato_postgres_1 psql -U postgres -t -c "select datname from pg_database where datname like '%eth_%';" | tr -d "[:space:]"` -c "select count(*) from chain_info_ref;"

Execute the normal steps to update the original node (see the previous topic)

Confirm that the updated node has the same number of private chains as the temporary node in step (4d):

docker exec strato_postgres_1 psql -U postgres -d `docker exec strato_postgres_1 psql -U postgres -t -c "select datname from pg_database where datname like '%eth_%';" | tr -d "[:space:]"` -c "select count(*) from chain_info_ref;"

Remove the temporary node as a member of all private chains. Repeat for all private chains from step (4d).

curl -s -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json" \
  'https://<strato_address>/strato/v2.3/transaction/parallel?resolve=true' \
  --data-raw '{
    "txs": [
      {
        "payload": {
          "contractName": "Governance",
          "contractAddress": "0000000000000000000000000000000000000100",
          "method": "voteToRemove",
          "args": {
            "m": "<TEMPORARY_NODE_ADDRESS>",
          },
          "chainid": "<CHAIN_ID>"
        },
        "type": "FUNCTION"
      }
    ]
  }'

Tear down the temporary node with:
```
./strato --wipe
```