From 6b82b04495f88fa72f898c875b3f07edf4eee8fe Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Wed, 14 Aug 2024 18:23:40 -0400 Subject: [PATCH 1/9] add parachain / solochain section --- docs/learn/learn-runtime-upgrades.md | 36 +++++++++++++++++++++------- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/docs/learn/learn-runtime-upgrades.md b/docs/learn/learn-runtime-upgrades.md index b3906d32cc34..c7afb4d835f4 100644 --- a/docs/learn/learn-runtime-upgrades.md +++ b/docs/learn/learn-runtime-upgrades.md @@ -8,7 +8,9 @@ slug: ../learn-runtime-upgrades --- Runtime upgrades allow {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} to change the -logic of the chain without the need for a hard fork. +logic of a Substrate-based chain without the need for a hard fork. + +:::info Substrate is part of the Polkadot SDK ::: ## Forkless Upgrades @@ -20,15 +22,16 @@ thousands) of nodes in the network that need to upgrade their software. Thus, ha inefficient, and error-prone due to the levels of offline coordination required and, therefore, the propensity to bundle many upgrades into one large-scale event. -By using Wasm in Substrate (the framework powering Polkadot, Kusama, and many connecting chains), -parachains are given the ability to upgrade their runtime (a chain's "business logic") without hard -forking. +The usage of [WebAssembly](./learn-wasm.md) in the Polkadot SDK (the framework powering Polkadot, +Kusama, and its respective parachains/rollups), gives any relay chains, parachains, and any other +chains built with the Polkadot SDK the ability to upgrade their runtime (a chain's "business logic") +without hard forking. Rather than encoding the runtime in the nodes, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} nodes contain a WebAssembly [execution host](learn-polkadot-host). They maintain consensus on a very low-level and well-established instruction set. Upgrades can be small, isolated, and very specific by deploying -Wasm on-chain and having nodes auto-enact the new logic at a particular block height. +WebAssembly on-chain and having nodes auto-enact the new logic at a particular block height. The {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} runtime is stored on the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} blockchain itself. @@ -36,13 +39,28 @@ The {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} runtime is st the logic stored on-chain and removes the coordination challenge of requiring thousands of node operators to upgrade in advance of a given block number. Polkadot stakeholders propose and approve upgrades through the [on-chain governance](./learn-polkadot-opengov.md) system, which also enacts -them autonomously. +them autonomously once voted through. -As a result of storing the Runtime as part of the state, the Runtime code itself becomes state -sensitive, and calls to Runtime can change the Runtime code itself. Therefore, the Polkadot Host -must always ensure it provides the Runtime corresponding to the state in which the entry point has +As a result of storing the runtime as part of the state, the runtime code itself becomes state +sensitive, and calls to runtime can change the runtime code itself. Therefore, the Polkadot Host +must always ensure it provides the runtime corresponding to the state in which the entry point has been called. +### Forkless Upgrades - Parachains & Solo Chains + +The architecture for parachains and solo chains is the same as the relay chain, with the runtime +code being stored on-chain. Solo chains, which are blockchains which are not secured by / following +the relay chain's consensus, are able to be update with whatever governance that solo chain has +implemented. This could either be a governance system like [OpenGov](./learn-polkadot-opengov.md), +or a simple sudo/multisig setup. + +Parachains must notify the relay chain whenever a new upgrade is to be enacted. This is done using +two key extrinsics: + +- The first notifies the relay chain that an upgrade is to take place, and thus a new state + transition function is going to be introduced for that parachain to be validated with. +- The second enacts the upgrade, assuming it has been approved. + ## Client Releases The existing runtime logic is followed to update the [Wasm](./learn-wasm.md) runtime stored on the From d2ed5499522fcd9812c25b2b07064de9311c0f4f Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Wed, 14 Aug 2024 18:29:02 -0400 Subject: [PATCH 2/9] formatting --- docs/learn/learn-runtime-upgrades.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/learn/learn-runtime-upgrades.md b/docs/learn/learn-runtime-upgrades.md index c7afb4d835f4..4382ad1f8528 100644 --- a/docs/learn/learn-runtime-upgrades.md +++ b/docs/learn/learn-runtime-upgrades.md @@ -10,7 +10,12 @@ slug: ../learn-runtime-upgrades Runtime upgrades allow {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} to change the logic of a Substrate-based chain without the need for a hard fork. -:::info Substrate is part of the Polkadot SDK ::: +:::info Substrate is part of the Polkadot SDK + +Substrate is one of the core parts of the Polkadot SDK, containing libraries used to build +blockchains. + +::: ## Forkless Upgrades From 1dff5cc42704b4239ba93a383b3c16de8ef292c3 Mon Sep 17 00:00:00 2001 From: bader y Date: Fri, 16 Aug 2024 10:34:12 -0400 Subject: [PATCH 3/9] Update docs/learn/learn-runtime-upgrades.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/learn/learn-runtime-upgrades.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/learn-runtime-upgrades.md b/docs/learn/learn-runtime-upgrades.md index 4382ad1f8528..030a5e4de279 100644 --- a/docs/learn/learn-runtime-upgrades.md +++ b/docs/learn/learn-runtime-upgrades.md @@ -12,7 +12,7 @@ logic of a Substrate-based chain without the need for a hard fork. :::info Substrate is part of the Polkadot SDK -Substrate is one of the core parts of the Polkadot SDK, containing libraries used to build +Substrate is one of the core components of the Polkadot SDK, containing libraries used to build blockchains. ::: From f9a68b62b6504ed6e1974c46b66077867c8058e0 Mon Sep 17 00:00:00 2001 From: bader y Date: Fri, 16 Aug 2024 10:35:18 -0400 Subject: [PATCH 4/9] Update docs/learn/learn-runtime-upgrades.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/learn/learn-runtime-upgrades.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/learn/learn-runtime-upgrades.md b/docs/learn/learn-runtime-upgrades.md index 030a5e4de279..1ca204818819 100644 --- a/docs/learn/learn-runtime-upgrades.md +++ b/docs/learn/learn-runtime-upgrades.md @@ -28,9 +28,9 @@ inefficient, and error-prone due to the levels of offline coordination required propensity to bundle many upgrades into one large-scale event. The usage of [WebAssembly](./learn-wasm.md) in the Polkadot SDK (the framework powering Polkadot, -Kusama, and its respective parachains/rollups), gives any relay chains, parachains, and any other -chains built with the Polkadot SDK the ability to upgrade their runtime (a chain's "business logic") -without hard forking. +Kusama and their respective parachains), give the relay chain, its parachains, as well as any other standalone solo +chains built with the Polkadot SDK the ability to upgrade their runtime (the chain's "business logic") +without a hard fork of the respective network. Rather than encoding the runtime in the nodes, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} nodes contain a WebAssembly From 26473ae5bec5a23801d3b96c8300fb04b3b17ac8 Mon Sep 17 00:00:00 2001 From: bader y Date: Fri, 16 Aug 2024 10:35:54 -0400 Subject: [PATCH 5/9] Update docs/learn/learn-runtime-upgrades.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/learn/learn-runtime-upgrades.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/learn-runtime-upgrades.md b/docs/learn/learn-runtime-upgrades.md index 1ca204818819..e9d07d8bcd04 100644 --- a/docs/learn/learn-runtime-upgrades.md +++ b/docs/learn/learn-runtime-upgrades.md @@ -44,7 +44,7 @@ The {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} runtime is st the logic stored on-chain and removes the coordination challenge of requiring thousands of node operators to upgrade in advance of a given block number. Polkadot stakeholders propose and approve upgrades through the [on-chain governance](./learn-polkadot-opengov.md) system, which also enacts -them autonomously once voted through. +them autonomously once the runtime upgrade referendum is approved through on-chain voting. As a result of storing the runtime as part of the state, the runtime code itself becomes state sensitive, and calls to runtime can change the runtime code itself. Therefore, the Polkadot Host From 898bb281baa7f14a3b75702689dfbf8b108fd9ce Mon Sep 17 00:00:00 2001 From: bader y Date: Fri, 16 Aug 2024 10:36:04 -0400 Subject: [PATCH 6/9] Update docs/learn/learn-runtime-upgrades.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/learn/learn-runtime-upgrades.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/learn-runtime-upgrades.md b/docs/learn/learn-runtime-upgrades.md index e9d07d8bcd04..32e398305c55 100644 --- a/docs/learn/learn-runtime-upgrades.md +++ b/docs/learn/learn-runtime-upgrades.md @@ -53,7 +53,7 @@ been called. ### Forkless Upgrades - Parachains & Solo Chains -The architecture for parachains and solo chains is the same as the relay chain, with the runtime +The node architectural design for parachains and solo chains is similar to that of the relay chain, with the runtime code being stored on-chain. Solo chains, which are blockchains which are not secured by / following the relay chain's consensus, are able to be update with whatever governance that solo chain has implemented. This could either be a governance system like [OpenGov](./learn-polkadot-opengov.md), From 3cb43c2c50f50ebf49515e30512fd84f45368b99 Mon Sep 17 00:00:00 2001 From: bader y Date: Fri, 16 Aug 2024 10:38:37 -0400 Subject: [PATCH 7/9] Update docs/learn/learn-runtime-upgrades.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/learn/learn-runtime-upgrades.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/learn-runtime-upgrades.md b/docs/learn/learn-runtime-upgrades.md index 32e398305c55..413ef936466a 100644 --- a/docs/learn/learn-runtime-upgrades.md +++ b/docs/learn/learn-runtime-upgrades.md @@ -54,7 +54,7 @@ been called. ### Forkless Upgrades - Parachains & Solo Chains The node architectural design for parachains and solo chains is similar to that of the relay chain, with the runtime -code being stored on-chain. Solo chains, which are blockchains which are not secured by / following +code being a Wasm blob that is stored in chain state. Solo chains built with Polkadot SDK, which are blockchains that have a native consensus mechanism that is independent of the relay chain's consensus, are able to be update with whatever governance that solo chain has implemented. This could either be a governance system like [OpenGov](./learn-polkadot-opengov.md), or a simple sudo/multisig setup. From 9f30819d96b72de2dc993ac4929c0c31a26e5272 Mon Sep 17 00:00:00 2001 From: bader y Date: Fri, 16 Aug 2024 10:39:19 -0400 Subject: [PATCH 8/9] Update docs/learn/learn-runtime-upgrades.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/learn/learn-runtime-upgrades.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/learn/learn-runtime-upgrades.md b/docs/learn/learn-runtime-upgrades.md index 413ef936466a..4402c9ff71aa 100644 --- a/docs/learn/learn-runtime-upgrades.md +++ b/docs/learn/learn-runtime-upgrades.md @@ -55,9 +55,7 @@ been called. The node architectural design for parachains and solo chains is similar to that of the relay chain, with the runtime code being a Wasm blob that is stored in chain state. Solo chains built with Polkadot SDK, which are blockchains that have a native consensus mechanism that is independent of -the relay chain's consensus, are able to be update with whatever governance that solo chain has -implemented. This could either be a governance system like [OpenGov](./learn-polkadot-opengov.md), -or a simple sudo/multisig setup. +the relay chain's consensus, can be updated through an on-chain governance system like [OpenGov](./learn-polkadot-opengov.md) or a simple sudo/multisig setup. Parachains must notify the relay chain whenever a new upgrade is to be enacted. This is done using two key extrinsics: From e1611ee6cc931cfa6878e07ad52633b3fd689f73 Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Fri, 16 Aug 2024 10:46:49 -0400 Subject: [PATCH 9/9] rephrase and add exts --- docs/learn/learn-runtime-upgrades.md | 34 +++++++++++++--------------- 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/docs/learn/learn-runtime-upgrades.md b/docs/learn/learn-runtime-upgrades.md index 4402c9ff71aa..30aa31f1feec 100644 --- a/docs/learn/learn-runtime-upgrades.md +++ b/docs/learn/learn-runtime-upgrades.md @@ -7,15 +7,9 @@ keywords: [runtime, upgrades, releases, forkless] slug: ../learn-runtime-upgrades --- -Runtime upgrades allow {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} to change the -logic of a Substrate-based chain without the need for a hard fork. - -:::info Substrate is part of the Polkadot SDK - -Substrate is one of the core components of the Polkadot SDK, containing libraries used to build -blockchains. - -::: +Runtime upgrades allow the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} relay +chain, parachains, and solo blockchains built with the Polkadot SDK to change their core business +logic (referred to as the **runtime**) without the need for a hard fork. ## Forkless Upgrades @@ -28,9 +22,9 @@ inefficient, and error-prone due to the levels of offline coordination required propensity to bundle many upgrades into one large-scale event. The usage of [WebAssembly](./learn-wasm.md) in the Polkadot SDK (the framework powering Polkadot, -Kusama and their respective parachains), give the relay chain, its parachains, as well as any other standalone solo -chains built with the Polkadot SDK the ability to upgrade their runtime (the chain's "business logic") -without a hard fork of the respective network. +Kusama and their respective parachains), give the relay chain, its parachains, as well as any other +standalone solo chains built with the Polkadot SDK the ability to upgrade their runtime (the chain's +"business logic") without a hard fork of the respective network. Rather than encoding the runtime in the nodes, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} nodes contain a WebAssembly @@ -53,16 +47,20 @@ been called. ### Forkless Upgrades - Parachains & Solo Chains -The node architectural design for parachains and solo chains is similar to that of the relay chain, with the runtime -code being a Wasm blob that is stored in chain state. Solo chains built with Polkadot SDK, which are blockchains that have a native consensus mechanism that is independent of -the relay chain's consensus, can be updated through an on-chain governance system like [OpenGov](./learn-polkadot-opengov.md) or a simple sudo/multisig setup. +The node architectural design for parachains and solo chains is similar to that of the relay chain, +with the runtime code being a Wasm blob that is stored in chain state. Solo chains built with +Polkadot SDK, which are blockchains that have a native consensus mechanism that is independent of +the relay chain's consensus, can be updated through an on-chain governance system like +[OpenGov](./learn-polkadot-opengov.md) or a simple sudo/multisig setup. Parachains must notify the relay chain whenever a new upgrade is to be enacted. This is done using two key extrinsics: -- The first notifies the relay chain that an upgrade is to take place, and thus a new state - transition function is going to be introduced for that parachain to be validated with. -- The second enacts the upgrade, assuming it has been approved. +- [`system.authorizeUpgrade`](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method.authorize_upgrade) - + notifies the relay chain that an upgrade is to take place, and thus a new state transition + function is going to be introduced for that parachain to be validated with. +- [`system.applyAuthorizedUpgrade`](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method.apply_authorized_upgrade) - + enacts the upgrade, assuming it has been approved. ## Client Releases