Skip to content

Commit 227ae48

Browse files
nhussein11nhussein11
committed
fix: runtime upgrade wip
1 parent 4a501cc commit 227ae48

File tree

3 files changed

+354
-0
lines changed

3 files changed

+354
-0
lines changed

‎llms.txt‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,7 @@ Doc-Page: https://docs.polkadot.com/tutorials/polkadot-sdk/parachains/zero-to-he
168168
Doc-Page: https://docs.polkadot.com/tutorials/polkadot-sdk/parachains/zero-to-hero/obtain-coretime/
169169
Doc-Page: https://docs.polkadot.com/tutorials/polkadot-sdk/parachains/zero-to-hero/pallet-benchmarking/
170170
Doc-Page: https://docs.polkadot.com/tutorials/polkadot-sdk/parachains/zero-to-hero/pallet-unit-testing/
171+
Doc-Page: https://docs.polkadot.com/tutorials/polkadot-sdk/parachains/zero-to-hero/runtime-upgrade/
171172
Doc-Page: https://docs.polkadot.com/tutorials/polkadot-sdk/parachains/zero-to-hero/set-up-a-template/
172173
Doc-Page: https://docs.polkadot.com/tutorials/polkadot-sdk/system-chains/asset-hub/asset-conversion/
173174
Doc-Page: https://docs.polkadot.com/tutorials/polkadot-sdk/system-chains/asset-hub/
@@ -33339,6 +33340,184 @@ test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; fini
3333933340
</div>
3334033341
--- END CONTENT ---
3334133342

33343+
Doc-Content: https://docs.polkadot.com/tutorials/polkadot-sdk/parachains/zero-to-hero/runtime-upgrade/
33344+
--- BEGIN CONTENT ---
33345+
---
33346+
title: Runtime Upgrades
33347+
description: Learn how to safely and efficiently perform runtime upgrades for your Substrate-based blockchain, including best practices and step-by-step instructions.
33348+
tutorial_badge: Intermediate
33349+
---
33350+
33351+
# Runtime Upgrades
33352+
33353+
## Introduction
33354+
33355+
Upgrading the runtime of your Substrate-based blockchain is a core feature that enables you to add new functionality, fix bugs, or optimize performance without requiring a hard fork. Runtime upgrades are performed by submitting a special extrinsic that replaces the existing Wasm runtime code on-chain. This process is trustless, transparent, and can be executed via governance or sudo, depending on your chain's configuration.
33356+
33357+
This tutorial will guide you through the process of preparing, submitting, and verifying a runtime upgrade for your parachain or standalone Substrate chain.
33358+
33359+
## Prerequisites
33360+
33361+
Before proceeding, ensure you have:
33362+
33363+
- A working Substrate-based chain (local or testnet)
33364+
- The latest source code for your runtime, with desired changes implemented and tested
33365+
- [Rust toolchain](https://www.rust-lang.org/) and [wasm32-unknown-unknown target](https://substrate.dev/docs/en/knowledgebase/getting-started/#add-the-wasm-target) installed
33366+
- Sufficient privileges to submit a runtime upgrade (sudo or governance access)
33367+
- [Polkadot.js Apps](https://polkadot.js.org/apps/) or another compatible tool for submitting extrinsics
33368+
33369+
## Step 1: Prepare Your Runtime Upgrade
33370+
33371+
1. **Implement and Test Changes**
33372+
- Make your desired changes to the runtime code (e.g., add a pallet, update logic, fix bugs).
33373+
- Thoroughly test your changes locally using unit tests and integration tests.
33374+
- Optionally, run your chain locally with the new runtime to ensure it works as expected.
33375+
33376+
---
33377+
33378+
### Example: Making a Meaningful Runtime Upgrade (Custom Pallet)
33379+
33380+
Suppose you have followed the Zero to Hero tutorials and already have a custom pallet integrated into your runtime. Here's how you could make a meaningful upgrade by extending your custom pallet and updating the runtime:
33381+
33382+
#### 1. Add a New Feature to the Custom Pallet
33383+
33384+
For example, add a new dispatchable function to reset the counter to zero:
33385+
33386+
**In `pallets/custom-pallet/src/lib.rs`:**
33387+
33388+
```rust
33389+
#[pallet::call]
33390+
impl<T: Config> Pallet<T> {
33391+
// ... existing calls ...
33392+
33393+
/// Reset the counter to zero. Only callable by Root.
33394+
#[pallet::weight(T::WeightInfo::reset_counter())]
33395+
pub fn reset_counter(origin: OriginFor<T>) -> DispatchResult {
33396+
ensure_root(origin)?;
33397+
<CounterValue<T>>::put(0u32);
33398+
Self::deposit_event(Event::CounterValueSet { new_value: 0 });
33399+
Ok(())
33400+
}
33401+
}
33402+
```
33403+
33404+
- Update your pallet's `Event` and `WeightInfo` as needed.
33405+
- Add unit tests for the new function in `tests.rs`.
33406+
33407+
#### 2. Update the Runtime to Use the New Pallet Version
33408+
33409+
- If you changed the pallet's public API, ensure the runtime's configuration is updated accordingly (e.g., in `runtime/src/lib.rs` and `runtime/src/configs/mod.rs`).
33410+
- Re-export the updated pallet if needed.
33411+
33412+
#### 3. Bump the Runtime Version
33413+
33414+
- In your runtime's `Cargo.toml` and `lib.rs`, increment the `spec_version` and `impl_version` fields. For example:
33415+
33416+
**In `runtime/src/lib.rs`:**
33417+
```rust
33418+
sp_version::runtime_version! {
33419+
pub const VERSION: RuntimeVersion = RuntimeVersion {
33420+
spec_name: create_runtime_str!("parachain_template_runtime"),
33421+
impl_name: create_runtime_str!("parachain_template_runtime"),
33422+
authoring_version: 1,
33423+
spec_version: 2, // <-- increment this
33424+
impl_version: 2, // <-- and this
33425+
// ...
33426+
};
33427+
}
33428+
```
33429+
33430+
#### 4. Build and Test the New Runtime
33431+
33432+
- Run your tests to ensure everything works:
33433+
```bash
33434+
cargo test --package custom-pallet
33435+
```
33436+
- Build the new Wasm runtime as described below.
33437+
33438+
---
33439+
33440+
2. **Build the Wasm Runtime**
33441+
- Navigate to your runtime directory (commonly `runtime/` or `parachain-template/runtime/`).
33442+
- Build the Wasm blob:
33443+
```bash
33444+
cargo build --release --target wasm32-unknown-unknown
33445+
```
33446+
- The compiled Wasm file is usually located at:
33447+
```
33448+
./target/wasm32-unknown-unknown/release/<runtime_name>.wasm
33449+
```
33450+
- For parachain templates, you may also find the compressed Wasm at:
33451+
```
33452+
./target/release/wbuild/parachain-template-runtime/parachain_template_runtime.compact.compressed.wasm
33453+
```
33454+
33455+
## Step 2: Submit the Runtime Upgrade
33456+
33457+
You can submit a runtime upgrade using the Sudo pallet (for development/testnets) or via on-chain governance (for production chains).
33458+
33459+
### Using Sudo (Development/Testnet)
33460+
33461+
1. Open [Polkadot.js Apps](https://polkadot.js.org/apps/).
33462+
2. Connect to your node (local or remote).
33463+
3. Navigate to **Developer > Sudo**.
33464+
4. In the **sudo** call dropdown, select `system > setCode`.
33465+
5. Upload your new Wasm runtime file.
33466+
6. Click **Submit Sudo** and sign the transaction with the sudo key.
33467+
33468+
### Using Governance (Production)
33469+
33470+
1. Open [Polkadot.js Apps](https://polkadot.js.org/apps/).
33471+
2. Navigate to **Democracy > Propose** (or the relevant governance module).
33472+
3. Select the `system > setCode` call and upload the new Wasm runtime.
33473+
4. Submit the proposal and follow the governance process (referenda, council, etc.).
33474+
33475+
## Step 3: Verify the Upgrade
33476+
33477+
1. After the extrinsic is included in a block, your chain will schedule the upgrade.
33478+
2. The runtime will be upgraded at the start of the next block.
33479+
3. Verify the upgrade:
33480+
- Check the **Explorer** tab for events like `system.CodeUpdated`.
33481+
- Confirm the runtime version has incremented (see **Developer > Chain state > system > version**).
33482+
- Test new features or changes to ensure they are live.
33483+
33484+
## Best Practices
33485+
33486+
- Always test your runtime thoroughly before upgrading a live chain.
33487+
- Back up your chain data before performing upgrades on production networks.
33488+
- Increment the `spec_version` and `impl_version` in your runtime's `Cargo.toml` and `lib.rs`.
33489+
- Communicate upgrade plans with your community and validators.
33490+
- Monitor the chain closely after the upgrade for unexpected issues.
33491+
33492+
## Troubleshooting
33493+
33494+
- **Upgrade fails to apply:** Ensure the Wasm blob is correct and compatible with your chain's state.
33495+
- **Chain halts after upgrade:** Check for breaking changes or missing migrations in your runtime code.
33496+
- **Extrinsic rejected:** Verify you have sufficient privileges and that the Wasm file is not too large.
33497+
33498+
## Where to Go Next
33499+
33500+
<div class="grid cards" markdown>
33501+
33502+
- <span class="badge tutorial">Tutorial</span> __Deploy on Paseo TestNet__
33503+
33504+
---
33505+
33506+
Deploy your Polkadot SDK blockchain on Paseo! Follow this step-by-step guide for a seamless journey to a successful TestNet deployment.
33507+
33508+
[:octicons-arrow-right-24: Get Started](/tutorials/polkadot-sdk/parachains/zero-to-hero/deploy-to-testnet/)
33509+
33510+
- <span class="badge tutorial">Tutorial</span> __Obtain Coretime__
33511+
33512+
---
33513+
33514+
Get coretime for block production now! Follow this guide to explore on-demand and bulk options for seamless and efficient operations.
33515+
33516+
[:octicons-arrow-right-24: Get Started](/tutorials/polkadot-sdk/parachains/zero-to-hero/obtain-coretime/)
33517+
33518+
</div>
33519+
--- END CONTENT ---
33520+
3334233521
Doc-Content: https://docs.polkadot.com/tutorials/polkadot-sdk/parachains/zero-to-hero/set-up-a-template/
3334333522
--- BEGIN CONTENT ---
3334433523
---

‎tutorials/polkadot-sdk/parachains/zero-to-hero/.pages‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ nav:
66
- 'Pallet Unit Testing': pallet-unit-testing.md
77
- 'Add Pallets to the Runtime': add-pallets-to-runtime.md
88
- 'Pallet Benchmarking': pallet-benchmarking.md
9+
- 'Runtime Upgrade': runtime-upgrade.md
910
- 'Deploy to Paseo TestNet': deploy-to-testnet.md
1011
- 'Obtain Coretime': obtain-coretime.md

‎tutorials/polkadot-sdk/parachains/zero-to-hero/runtime-upgrade.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
---
2+
title: Runtime Upgrades
3+
description: Learn how to safely and efficiently perform runtime upgrades for your Substrate-based blockchain, including best practices and step-by-step instructions.
4+
tutorial_badge: Intermediate
5+
---
6+
7+
# Runtime Upgrades
8+
9+
## Introduction
10+
11+
Upgrading the runtime of your Substrate-based blockchain is a core feature that enables you to add new functionality, fix bugs, or optimize performance without requiring a hard fork. Runtime upgrades are performed by submitting a special extrinsic that replaces the existing Wasm runtime code on-chain. This process is trustless, transparent, and can be executed via governance or sudo, depending on your chain's configuration.
12+
13+
This tutorial will guide you through the process of preparing, submitting, and verifying a runtime upgrade for your parachain or standalone Substrate chain.
14+
15+
## Prerequisites
16+
17+
Before proceeding, ensure you have:
18+
19+
- A working Substrate-based chain (local or testnet)
20+
- The latest source code for your runtime, with desired changes implemented and tested
21+
- [Rust toolchain](https://www.rust-lang.org/) and [wasm32-unknown-unknown target](https://substrate.dev/docs/en/knowledgebase/getting-started/#add-the-wasm-target) installed
22+
- Sufficient privileges to submit a runtime upgrade (sudo or governance access)
23+
- [Polkadot.js Apps](https://polkadot.js.org/apps/) or another compatible tool for submitting extrinsics
24+
25+
## Step 1: Prepare Your Runtime Upgrade
26+
27+
1. **Implement and Test Changes**
28+
- Make your desired changes to the runtime code (e.g., add a pallet, update logic, fix bugs).
29+
- Thoroughly test your changes locally using unit tests and integration tests.
30+
- Optionally, run your chain locally with the new runtime to ensure it works as expected.
31+
32+
---
33+
34+
### Example: Making a Meaningful Runtime Upgrade (Custom Pallet)
35+
36+
Suppose you have followed the Zero to Hero tutorials and already have a custom pallet integrated into your runtime. Here's how you could make a meaningful upgrade by extending your custom pallet and updating the runtime:
37+
38+
#### 1. Add a New Feature to the Custom Pallet
39+
40+
For example, add a new dispatchable function to reset the counter to zero:
41+
42+
**In `pallets/custom-pallet/src/lib.rs`:**
43+
44+
```rust
45+
#[pallet::call]
46+
impl<T: Config> Pallet<T> {
47+
// ... existing calls ...
48+
49+
/// Reset the counter to zero. Only callable by Root.
50+
#[pallet::weight(T::WeightInfo::reset_counter())]
51+
pub fn reset_counter(origin: OriginFor<T>) -> DispatchResult {
52+
ensure_root(origin)?;
53+
<CounterValue<T>>::put(0u32);
54+
Self::deposit_event(Event::CounterValueSet { new_value: 0 });
55+
Ok(())
56+
}
57+
}
58+
```
59+
60+
- Update your pallet's `Event` and `WeightInfo` as needed.
61+
- Add unit tests for the new function in `tests.rs`.
62+
63+
#### 2. Update the Runtime to Use the New Pallet Version
64+
65+
- If you changed the pallet's public API, ensure the runtime's configuration is updated accordingly (e.g., in `runtime/src/lib.rs` and `runtime/src/configs/mod.rs`).
66+
- Re-export the updated pallet if needed.
67+
68+
#### 3. Bump the Runtime Version
69+
70+
- In your runtime's `Cargo.toml` and `lib.rs`, increment the `spec_version` and `impl_version` fields. For example:
71+
72+
**In `runtime/src/lib.rs`:**
73+
```rust
74+
sp_version::runtime_version! {
75+
pub const VERSION: RuntimeVersion = RuntimeVersion {
76+
spec_name: create_runtime_str!("parachain_template_runtime"),
77+
impl_name: create_runtime_str!("parachain_template_runtime"),
78+
authoring_version: 1,
79+
spec_version: 2, // <-- increment this
80+
impl_version: 2, // <-- and this
81+
// ...
82+
};
83+
}
84+
```
85+
86+
#### 4. Build and Test the New Runtime
87+
88+
- Run your tests to ensure everything works:
89+
```bash
90+
cargo test --package custom-pallet
91+
```
92+
- Build the new Wasm runtime as described below.
93+
94+
---
95+
96+
2. **Build the Wasm Runtime**
97+
- Navigate to your runtime directory (commonly `runtime/` or `parachain-template/runtime/`).
98+
- Build the Wasm blob:
99+
```bash
100+
cargo build --release --target wasm32-unknown-unknown
101+
```
102+
- The compiled Wasm file is usually located at:
103+
```
104+
./target/wasm32-unknown-unknown/release/<runtime_name>.wasm
105+
```
106+
- For parachain templates, you may also find the compressed Wasm at:
107+
```
108+
./target/release/wbuild/parachain-template-runtime/parachain_template_runtime.compact.compressed.wasm
109+
```
110+
111+
## Step 2: Submit the Runtime Upgrade
112+
113+
You can submit a runtime upgrade using the Sudo pallet (for development/testnets) or via on-chain governance (for production chains).
114+
115+
### Using Sudo (Development/Testnet)
116+
117+
1. Open [Polkadot.js Apps](https://polkadot.js.org/apps/).
118+
2. Connect to your node (local or remote).
119+
3. Navigate to **Developer > Sudo**.
120+
4. In the **sudo** call dropdown, select `system > setCode`.
121+
5. Upload your new Wasm runtime file.
122+
6. Click **Submit Sudo** and sign the transaction with the sudo key.
123+
124+
### Using Governance (Production)
125+
126+
1. Open [Polkadot.js Apps](https://polkadot.js.org/apps/).
127+
2. Navigate to **Democracy > Propose** (or the relevant governance module).
128+
3. Select the `system > setCode` call and upload the new Wasm runtime.
129+
4. Submit the proposal and follow the governance process (referenda, council, etc.).
130+
131+
## Step 3: Verify the Upgrade
132+
133+
1. After the extrinsic is included in a block, your chain will schedule the upgrade.
134+
2. The runtime will be upgraded at the start of the next block.
135+
3. Verify the upgrade:
136+
- Check the **Explorer** tab for events like `system.CodeUpdated`.
137+
- Confirm the runtime version has incremented (see **Developer > Chain state > system > version**).
138+
- Test new features or changes to ensure they are live.
139+
140+
## Best Practices
141+
142+
- Always test your runtime thoroughly before upgrading a live chain.
143+
- Back up your chain data before performing upgrades on production networks.
144+
- Increment the `spec_version` and `impl_version` in your runtime's `Cargo.toml` and `lib.rs`.
145+
- Communicate upgrade plans with your community and validators.
146+
- Monitor the chain closely after the upgrade for unexpected issues.
147+
148+
## Troubleshooting
149+
150+
- **Upgrade fails to apply:** Ensure the Wasm blob is correct and compatible with your chain's state.
151+
- **Chain halts after upgrade:** Check for breaking changes or missing migrations in your runtime code.
152+
- **Extrinsic rejected:** Verify you have sufficient privileges and that the Wasm file is not too large.
153+
154+
## Where to Go Next
155+
156+
<div class="grid cards" markdown>
157+
158+
- <span class="badge tutorial">Tutorial</span> __Deploy on Paseo TestNet__
159+
160+
---
161+
162+
Deploy your Polkadot SDK blockchain on Paseo! Follow this step-by-step guide for a seamless journey to a successful TestNet deployment.
163+
164+
[:octicons-arrow-right-24: Get Started](/tutorials/polkadot-sdk/parachains/zero-to-hero/deploy-to-testnet/)
165+
166+
- <span class="badge tutorial">Tutorial</span> __Obtain Coretime__
167+
168+
---
169+
170+
Get coretime for block production now! Follow this guide to explore on-demand and bulk options for seamless and efficient operations.
171+
172+
[:octicons-arrow-right-24: Get Started](/tutorials/polkadot-sdk/parachains/zero-to-hero/obtain-coretime/)
173+
174+
</div>

0 commit comments

Comments
 (0)