Skip to content

Commit a3ddbe6

Browse files
0xLucca0xLucca
committed
Improve text
1 parent 10d11f0 commit a3ddbe6

File tree

2 files changed

+169
-42
lines changed

2 files changed

+169
-42
lines changed

‎develop/parachains/maintenance/unlock-parachain.md‎

Lines changed: 34 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,32 @@
11
---
22
title: Unlock a Parachain
3-
description: TODO
3+
description: Learn how to unlock your parachain. This step-by-step guide covers verifying lock status, preparing calls, and executing the unlock process.
44
---
55

66
# Unlock a Parachain
77

88
## Introduction
99

10-
Parachain locks are designed in such way to ensure the decentralization of parachains. If parachains are not locked when it should be, it could introduce centralization risk for new parachains.
10+
Parachain locks are a critical security mechanism in the Polkadot ecosystem designed to maintain decentralization during the parachain lifecycle. These locks prevent potential centralization risks that could emerge during the early stages of parachain operation.
11+
The locking system follows strict, well-defined conditions that distribute control across multiple authorities:
1112

12-
A parachain can be locked only with following conditions:
13+
The locking system follows strict, well-defined conditions that distribute control across multiple authorities:
1314

14-
- Relaychain governance MUST be able to lock any parachain.
15-
- A parachain MUST be able to lock its own lock.
16-
- A parachain manager SHOULD be able to lock the parachain.
17-
- A parachain SHOULD be locked when it successfully produced a block for the first time.
15+
- Relay chain governance has the authority to lock any parachain
16+
- A parachain can lock its own lock
17+
- Parachain managers have permission to lock the parachain
18+
- Parachains are locked automatically when they successfully produce their first block
1819

19-
A parachain can be unlocked only with following conditions:
20-
- Relaychain governance MUST be able to unlock any parachain.
21-
- A parachain MUST be able to unlock its own lock.
20+
Similarly, unlocking a parachain follows controlled procedures:
2221

23-
## Check if a Parachain is Locked
22+
- Relay chain governance retains the authority to unlock any parachain
23+
- A parachain has the ability to unlock its own lock
2424

25-
To check if a parachain is locked:
25+
This document guides you through the process of checking a parachain's lock status and safely executing the unlock procedure from a parachain using XCM (Cross-Consensus Messaging).
26+
27+
## Check if the Parachain is Locked
28+
29+
Before attempting to unlock a parachain, you should verify its current lock status. This can be done through the Polkadot.js interface:
2630

2731
1. In [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer){target=\_blank}, connect to the relay chain, navigate to the **Developer** dropdown and select the **Chain State** option
2832

@@ -37,15 +41,15 @@ To check if a parachain is locked:
3741

3842
## How to Unlock a Parachain
3943

40-
Unlocking a parachain is then allowed by sending an XCM call to the relay chain with the parachain origin or by executing this from the governance of the relay chain as a roo call.
44+
Unlocking a parachain requires sending an XCM (Cross-Consensus Message) to the relay chain from the parachain itself, sending a message with Root origin, or this can be accomplished through the relay chain's governance mechanism executing a root call.
4145

42-
From a parachain, the XCM message has to be sent from the Root origin. Depending on the parachain, this can be done by using the Sudo pallet or by using the governance mechanism of the parachain.
46+
If sending an XCM, the parachain origin must have proper authorization, which typically comes from either the parachain's sudo pallet (if enabled) or through its governance system.
4347

44-
This guide explains how to send this message assuming your parachain has a Sudo pallet (and the XCM configuration/pallets).
48+
This guide demonstrates the unlocking process using a parachain with the sudo pallet. For parachains using governance-based authorization instead, the process will require adjustments to how the XCM is sent.
4549

46-
### Prepare the Call
50+
### Prepare the Unlock Call
4751

48-
First, you need to prepara the call that will be executed on the relay chain. To do this:
52+
Before sending the XCM, you need to construct the relay chain call that will be executed. Follow these steps to prepare the `registrar.removeLock` extrinsic:
4953

5054
1. In [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer){target=\_blank}, connect to the relay chain, navigate to the **Developer** dropdown and select the **Extrinsics** option
5155

@@ -57,14 +61,17 @@ First, you need to prepara the call that will be executed on the relay chain. To
5761

5862
![](/images/develop/parachains/maintenance/unlock-parachain/unlock-parachain-2.webp)
5963

60-
3. Check the transaction weight for executing the call. You can estimate this by executing the `transactionPaymentCallApi.queryCallInfo` runtime call with the encoded call data previously obtained:
64+
3. Determine the transaction weight required for executing the call. You can estimate this by executing the `transactionPaymentCallApi.queryCallInfo` runtime call with the encoded call data previously obtained:
6165

6266
![](/images/develop/parachains/deployment/coretime-renewal/coretime-renewal-3.webp)
6367

64-
### Fund Sovereign Account
68+
This weight information is crucial for properly configuring your XCM message's execution parameters in the next steps.
69+
70+
### Fund the Sovereign Account
6571

66-
The [sovereign account](https://github.com/polkadot-fellows/xcm-format/blob/10726875bd3016c5e528c85ed6e82415e4b847d7/README.md?plain=1#L50){target=\_blank} of your parachain on the relay chain needs adequate funding to cover the XCM transaction fees.
67-
To determine your parachain's sovereign account address, you can:
72+
For a successful XCM execution, the [sovereign account](https://github.com/polkadot-fellows/xcm-format/blob/10726875bd3016c5e528c85ed6e82415e4b847d7/README.md?plain=1#L50){target=\_blank} of your parachain on the relay chain must have sufficient funds to cover transaction fees. The sovereign account is a deterministic address derived from your parachain ID.
73+
74+
You can identify your parachain's sovereign account using either of these methods:
6875

6976
- Use the **"Para ID" to Address** section in [Substrate Utilities](https://www.shawntabrizi.com/substrate-js-utilities/){target=\_blank} with the **Sibling** option selected
7077

@@ -82,17 +89,17 @@ To determine your parachain's sovereign account address, you can:
8289

8390
- **Hex** - `0x70617261d6070000000000000000000000000000000000000000000000000000`
8491
- **SS58 format** - `5Ec4AhPW97z4ZyYkd3mYkJrSeZWcwVv4wiANES2QrJi1x17F`
92+
93+
You can transfer funds to this account from any account on the relay chain using a standard transfer.
8594

8695
### Craft and Submit the XCM
8796

88-
To unlock your parachain, you will submit an XCM from your parachain to the relay chain using Root origin.
89-
90-
The XCM needs to execute these operations:
97+
With the call data prepared and the sovereign account funded, you can now construct and send the XCM from your parachain to the relay chain. The XCM will need to perform several operations in sequence:
9198

92-
1. Withdraw DOT from your parachain's sovereign account on the relay chain
99+
1. Withdraw DOT from your parachain's sovereign account
93100
2. Buy execution to pay for transaction fees
94101
3. Execute the `registrar.removeLock` extrinsic
95-
4. Refund surplus DOT back to the sovereign account
102+
4. Return any unused funds to your sovereign account
96103

97104
Here's how to submit this XCM using Astar (Parachain 2006) as an example:
98105

@@ -119,6 +126,6 @@ Here's how to submit this XCM using Astar (Parachain 2006) as an example:
119126

120127
![](/images/develop/parachains/maintenance/unlock-parachain/unlock-parachain-5.webp)
121128

122-
After successful execution, your parachain should be unlocked. To verify this, check the status of the parachain lock again using the method described in the [Check if a Parachain is Locked](#check-if-a-parachain-is-locked) section. You should see that the lock has been removed.
129+
After submitting the transaction, wait for it to be finalized and then verify that your parachain has been successfully unlocked by following the steps described in the [Check if a Parachain is Locked](#check-if-a-parachain-is-locked) section. If the parachain shows as unlocked, your operation has been successful. If it still appears locked, verify that your XCM transaction was processed correctly and consider troubleshooting the XCM built.
123130

124131
![](/images/develop/parachains/maintenance/unlock-parachain/unlock-parachain-6.webp)

‎llms.txt‎

Lines changed: 135 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -693,7 +693,21 @@ decl_test_parachains! {
693693
- [**`decl_test_networks`**](https://github.com/paritytech/polkadot-sdk/blob/{{dependencies.repositories.polkadot_sdk.version}}/cumulus/xcm/xcm-emulator/src/lib.rs#L916){target=\_blank} - defines a testing network with relay chains, parachains, and bridges, implementing message transport and processing logic. Example:
694694

695695
```rust
696-
Failed to fetch snippet after 3 attempts
696+
decl_test_networks! {
697+
pub struct WestendMockNet {
698+
relay_chain = Westend,
699+
parachains = vec![
700+
AssetHubWestend,
701+
BridgeHubWestend,
702+
CollectivesWestend,
703+
CoretimeWestend,
704+
PeopleWestend,
705+
PenpalA,
706+
PenpalB,
707+
],
708+
bridge = ()
709+
},
710+
}
697711
```
698712

699713
By leveraging these macros, developers can customize their testing networks by defining relay chains and parachains tailored to their needs. For guidance on implementing a mock runtime for a Polkadot SDK-based chain, refer to the [Pallet Testing](/develop/parachains/testing/pallet-testing/){target=\_blank} article.
@@ -5600,30 +5614,136 @@ For a complete implementation example of multi-block migrations, refer to the [o
56005614
Doc-Content: https://docs.polkadot.com/develop/parachains/maintenance/unlock-parachain/
56015615
--- BEGIN CONTENT ---
56025616
---
5603-
title: Unlock Parachain
5604-
description: TODO
5617+
title: Unlock a Parachain
5618+
description: Learn how to unlock your parachain. This step-by-step guide covers verifying lock status, preparing calls, and executing the unlock process.
56055619
---
56065620

5607-
# Unlock Parachain
5621+
# Unlock a Parachain
56085622

56095623
## Introduction
56105624

5611-
Parachain locks are designed in such way to ensure the decentralization of parachains. If parachains are not locked when it should be, it could introduce centralization risk for new parachains.
5625+
Parachain locks are a critical security mechanism in the Polkadot ecosystem designed to maintain decentralization during the parachain lifecycle. These locks prevent potential centralization risks that could emerge during the early stages of parachain operation.
5626+
The locking system follows strict, well-defined conditions that distribute control across multiple authorities:
5627+
5628+
The locking system follows strict, well-defined conditions that distribute control across multiple authorities:
5629+
5630+
- Relay chain governance has the authority to lock any parachain
5631+
- A parachain can lock its own lock
5632+
- Parachain managers have permission to lock the parachain
5633+
- Parachains are locked automatically when they successfully produce their first block
5634+
5635+
Similarly, unlocking a parachain follows controlled procedures:
5636+
5637+
- Relay chain governance retains the authority to unlock any parachain
5638+
- A parachain has the ability to unlock its own lock
5639+
5640+
This document guides you through the process of checking a parachain's lock status and safely executing the unlock procedure from a parachain using XCM (Cross-Consensus Messaging).
5641+
5642+
## Check if the Parachain is Locked
5643+
5644+
Before attempting to unlock a parachain, you should verify its current lock status. This can be done through the Polkadot.js interface:
5645+
5646+
1. In [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer){target=\_blank}, connect to the relay chain, navigate to the **Developer** dropdown and select the **Chain State** option
5647+
5648+
2. Query the parachain locked status:
5649+
1. Select **`registrar`**
5650+
2. Choose the **`paras`** option
5651+
3. Input the parachain ID you want to check as a parameter (e.g. `2006`)
5652+
4. Click the **+** button to execute the query
5653+
5. Check the status of the parachain lock
5654+
5655+
![](/images/develop/parachains/maintenance/unlock-parachain/unlock-parachain-1.webp)
5656+
5657+
## How to Unlock a Parachain
5658+
5659+
Unlocking a parachain requires sending an XCM (Cross-Consensus Message) to the relay chain from the parachain itself, sending a message with Root origin, or this can be accomplished through the relay chain's governance mechanism executing a root call.
5660+
5661+
If sending an XCM, the parachain origin must have proper authorization, which typically comes from either the parachain's sudo pallet (if enabled) or through its governance system.
5662+
5663+
This guide demonstrates the unlocking process using a parachain with the sudo pallet. For parachains using governance-based authorization instead, the process will require adjustments to how the XCM is sent.
56125664

5613-
A parachain can be locked only with following conditions:
5665+
### Prepare the Unlock Call
5666+
5667+
Before sending the XCM, you need to construct the relay chain call that will be executed. Follow these steps to prepare the `registrar.removeLock` extrinsic:
5668+
5669+
1. In [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer){target=\_blank}, connect to the relay chain, navigate to the **Developer** dropdown and select the **Extrinsics** option
5670+
5671+
2. Build the `registrar.removeLock` extrinsic
5672+
1. Select the **registrar** pallet
5673+
2. Choose the **removeLock** extrinsic
5674+
3. Fill in the parachain ID parameter (e.g. `2006`)
5675+
4. Copy the encoded call data
5676+
5677+
![](/images/develop/parachains/maintenance/unlock-parachain/unlock-parachain-2.webp)
5678+
5679+
3. Determine the transaction weight required for executing the call. You can estimate this by executing the `transactionPaymentCallApi.queryCallInfo` runtime call with the encoded call data previously obtained:
5680+
5681+
![](/images/develop/parachains/deployment/coretime-renewal/coretime-renewal-3.webp)
5682+
5683+
This weight information is crucial for properly configuring your XCM message's execution parameters in the next steps.
5684+
5685+
### Fund the Sovereign Account
5686+
5687+
For a successful XCM execution, the [sovereign account](https://github.com/polkadot-fellows/xcm-format/blob/10726875bd3016c5e528c85ed6e82415e4b847d7/README.md?plain=1#L50){target=\_blank} of your parachain on the relay chain must have sufficient funds to cover transaction fees. The sovereign account is a deterministic address derived from your parachain ID.
5688+
5689+
You can identify your parachain's sovereign account using either of these methods:
5690+
5691+
- Use the **"Para ID" to Address** section in [Substrate Utilities](https://www.shawntabrizi.com/substrate-js-utilities/){target=\_blank} with the **Sibling** option selected
5692+
5693+
- Calculate it manually:
56145694

5615-
- Relaychain governance MUST be able to lock any parachain.
5616-
- A parachain MUST be able to lock its own lock.
5617-
- A parachain manager SHOULD be able to lock the parachain.
5618-
- A parachain SHOULD be locked when it successfully produced a block for the first time.
5695+
1. Identify the appropriate prefix:
5696+
5697+
- For parent/child chains use the prefix `0x70617261` (which decodes to `b"para"`)
5698+
5699+
2. Encode your parachain ID as a u32 [SCALE](https://docs.polkadot.com/polkadot-protocol/basics/data-encoding/#data-types){target=\_blank} value:
5700+
5701+
- For parachain 2006, this would be `d6070000`
5702+
5703+
3. Combine the prefix with the encoded ID to form the sovereign account address:
5704+
5705+
- **Hex** - `0x70617261d6070000000000000000000000000000000000000000000000000000`
5706+
- **SS58 format** - `5Ec4AhPW97z4ZyYkd3mYkJrSeZWcwVv4wiANES2QrJi1x17F`
5707+
5708+
You can transfer funds to this account from any account on the relay chain using a standard transfer.
5709+
5710+
### Craft and Submit the XCM
5711+
5712+
With the call data prepared and the sovereign account funded, you can now construct and send the XCM from your parachain to the relay chain. The XCM will need to perform several operations in sequence:
5713+
5714+
1. Withdraw DOT from your parachain's sovereign account
5715+
2. Buy execution to pay for transaction fees
5716+
3. Execute the `registrar.removeLock` extrinsic
5717+
4. Return any unused funds to your sovereign account
5718+
5719+
Here's how to submit this XCM using Astar (Parachain 2006) as an example:
5720+
5721+
1. In [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer){target=\_blank}, connect to the parachain, navigate to the **Developer** dropdown and select the **Extrinsics** option
5722+
5723+
2. Create a `sudo.sudo` extrinsic that executes `polkadotXcm.send`:
5724+
1. Use the `sudo.sudo` extrinsic to execute the following call as Root
5725+
2. Select the **polkadotXcm** pallet
5726+
3. Choose the **send** extrinsic
5727+
4. Set the **dest** parameter as the relay chain
5728+
5729+
![](/images/develop/parachains/maintenance/unlock-parachain/unlock-parachain-4.webp)
5730+
5731+
3. Construct the XCM and submit it:
5732+
1. Add a **WithdrawAsset** instruction
5733+
2. Add a **BuyExecution** instruction
5734+
3. Add a **Transact** instruction with the following parameters:
5735+
- **originKind** - use `Native`
5736+
- **requireWeightAtMost** - use the weight calculated previously
5737+
- **call** - use the encoded call data generated before
5738+
4. Add a **RefundSurplus** instruction
5739+
5. Add a **DepositAsset** instruction to send the remaining funds to the parachain sovereign account
5740+
6. Click the **Submit Transaction** button
56195741

5620-
A parachain can be unlocked only with following conditions:
5621-
- Relaychain governance MUST be able to unlock any parachain.
5622-
- A parachain MUST be able to unlock its own lock.
5742+
![](/images/develop/parachains/maintenance/unlock-parachain/unlock-parachain-5.webp)
56235743

5624-
## Check if a Parachain is Locked
5744+
After submitting the transaction, wait for it to be finalized and then verify that your parachain has been successfully unlocked by following the steps described in the [Check if a Parachain is Locked](#check-if-a-parachain-is-locked) section. If the parachain shows as unlocked, your operation has been successful. If it still appears locked, verify that your XCM transaction was processed correctly and consider troubleshooting the XCM built.
56255745

5626-
To check if a parachain is locked,
5746+
![](/images/develop/parachains/maintenance/unlock-parachain/unlock-parachain-6.webp)
56275747
--- END CONTENT ---
56285748

56295749
Doc-Content: https://docs.polkadot.com/develop/parachains/testing/benchmarking/

0 commit comments

Comments
 (0)