From 12e4eed1812956762a8e084c8d5f31dbc99b09f7 Mon Sep 17 00:00:00 2001 From: vishal <1117327+vishalchangrani@users.noreply.github.com> Date: Fri, 7 Jul 2023 11:37:15 -0700 Subject: [PATCH] adding a page for Height coordinated upgrade --- docs/concepts/nodes/node-operation/hcu.mdx | 40 ++++++++++++++++++++++ src/data/pathMapping/flow.yml | 1 + src/data/redirects.ts | 2 ++ 3 files changed, 43 insertions(+) create mode 100644 docs/concepts/nodes/node-operation/hcu.mdx diff --git a/docs/concepts/nodes/node-operation/hcu.mdx b/docs/concepts/nodes/node-operation/hcu.mdx new file mode 100644 index 0000000000..b3c64ec1be --- /dev/null +++ b/docs/concepts/nodes/node-operation/hcu.mdx @@ -0,0 +1,40 @@ +--- +title: Height coordinated upgrade (HCU) +sidebar_title: Height coordinated upgrade +--- + +## Overview + +To enables rapid development of the Flow Protocol, the height coordinated upgrade method is used to roll out non-breaking changes such as bug fixes, +feature implementations and security fixes. + +## HCU versus Spork + +A [spork](./spork.mdx) requires a coordinated network upgrade process where node operators upgrade their node software and +re-initialize with a consolidated representation of the previous spork's state. +It is used to roll out changes which may be non-backward compatible with respect to the protocol and the execution state. +Spork entails a network downtime as all nodes in the system are upgraded and brought back online. +Sporks are only executed once every quarter. + +A height coordinated upgrade (HCU) on the other hand allows the execution and the verification nodes to be upgraded without stopping the network. +There is no network downtime during an HCU but the transaction execution will stop for few minutes while the execution nodes restart. +Currently, an HCU is only used to update the execution and the verification nodes. +For other node types, a simple rolling upgrade is used where operators are asked to upgrade their nodes async. + +## HCU process + +The HCU is executed in two parts. + +The first part is executed by the service committee. In this, the version boundary at which the execution nodes and verification nodes should stop is set on chain by submitting the [set_version_boundary](https://github.com/onflow/flow-core-contracts/blob/master/transactions/nodeVersionBeacon/admin/set_version_boundary.cdc) transaction. +The version boundary includes the block height at which the two node types should stop and the new node software version that the nodes should compare after a restart. + + +The second part is executed by the node operator. In this the node operator, monitors the execution and verification node that they are running. When the nodes reach the height set on chain, they stop. +At this point, the operator should update the node version to the new node software version and start the node again. The node will continue from where it left off. + +The block height and the node version will be announced by the Flow team on Discord as well as the [forum page](https://forum.onflow.org/c/mainnet-sporks/36). +It can also be directly queried from the chain using the following, + +``` +TODO: insert flow cli command here to query the block version details. +``` diff --git a/src/data/pathMapping/flow.yml b/src/data/pathMapping/flow.yml index 5bd403119b..a605067ea1 100644 --- a/src/data/pathMapping/flow.yml +++ b/src/data/pathMapping/flow.yml @@ -101,6 +101,7 @@ ./docs/content/node-operation/observer-node.mdx: docs/concepts/nodes/node-operation/observer-node.mdx ./docs/content/node-operation/past-sporks.mdx: docs/concepts/nodes/node-operation/past-sporks.mdx ./docs/content/node-operation/spork.mdx: docs/concepts/nodes/node-operation/spork.mdx +./docs/content/node-operation/hcu.mdx: docs/concepts/nodes/node-operation/hcu.mdx ./docs/content/node-operation/upcoming-sporks.mdx: docs/concepts/nodes/node-operation/upcoming-sporks.mdx ./docs/content/nodes/access-api-rate-limits.mdx: docs/concepts/nodes/access-api-rate-limits.mdx ./docs/content/nodes/access-api.mdx: docs/concepts/nodes/access-api.mdx diff --git a/src/data/redirects.ts b/src/data/redirects.ts index 6dd82e7cc4..922b6bb60c 100644 --- a/src/data/redirects.ts +++ b/src/data/redirects.ts @@ -32,6 +32,8 @@ export const redirects = { "/emulator": "/tools/emulator", "/node-operation/spork/": "/nodes/node-operation/spork", "/node-operation/spork": "/nodes/node-operation/spork", + "/node-operation/hcu": "/nodes/node-operation/hcu", + "/node-operation/hcu/": "/nodes/node-operation/hcu", "/concepts/accessing-testnet/": "/concepts/accessing-testnet", "/flow-token/faq/": "/flow/flow-token/faq", "/node-operation/node-roles/": "/node-operation/node-roles",