HackMDThe Asset Hub Migration - a primer
The Asset Hub Migration (AHM) is part of the Plaza project, working towards the next generation of the Polkadot Hub. In practice this means moving functionality off the Relay Chain onto Asset Hub, moving the pallets' state along with them.
Overview
From My high level talk from the parachains AMA:
tl;dr: The main goal is to migrate all the staking, governance and balances functionality from the Relay Chain to Asset Hub at minimal cost and risk to our integrated partners.
Average end users should interact only with AH, and be unaware of anything else behind the scenes
Migration will not require end user intervention
A core objective of Polkadot is to do everything on parachains, but originally things were done directly on the relay chain as we didn't have parachains yet and it removed some complexity to allow Polkadot launch faster. RFC-32 maps out path to a minimal relay to strip this functionality out an
- Minimal relay: move everything to parachains
- Iteration on this: move everything to the Asset Hub parachain - Plaza/Polkadot Hub and Cloud
Aims and wider context
tl;dr: Why are we doing this?
Balances migration overview
From a Forum thread explaining some implementation choices and details to Bryan:
We’re planning to move the funds off the relay chain in three phases.
Phase 1 primarily removes the main ways funds can be frozen/locked/reserved/put on hold. The exceptions are:
HRMP, parachain registration which will not be migrated or call filtered
Multisigs and proxies which will be migrated (funds and state moved to AH) but not call filtered, so people can recreate them if they need/want.
All other pallets which can create locks/holds/reserves/freezes will be call filtered and subsequently removed from the RC to mean that the only funds on the RC are free balances and the previously mentioned pallets. This phase will not increase the ED of the RC to 10 DOT yet, to allow integration partners time to make mistakes without hard penalties e.g. large numbers of users being dusted for ~50 USD each because an exchange has not had time/not been willing to change and the ED has been raised right away. The ED will be raised to 10 DOT for the incentive to still hold, but just not actually do it until phase 2.
The second migration (probably EOY 2025 or early 2026) will migrate all funds that have been teleported back to the RC in the intervening months back to AH and then increase the ED to 10 DOT
The third migration will move HRMP and parachains registration, migrate any proxies and multisigs to AH where they don’t already exist, again transfer ALL funds from the RC to AH and then remove the balances pallet from the RC.
This three step process balances our aims of:
Removing functionality from RC (the current AHM project)
Disincentivising usage of the RC for balance transfers
Minimising the impact on integration partners and end users (in phases to allow realistic timescales)
Eventually removing balances pallets from the RC
Staking
Staking on a parachain has been a project at Parity for over a year involving Kian, Gonçalo, Ankan and George (among others). Kian wrote the original staking system and Ankan and Gonçalo have been working on the staking system for around 2 years. They have designed and implemented the majority of the pieces required to transition to running on a parachain (more on those specific changes later).
Originally the project aim was left open as to which parachain it would be running on - recently the decision was made that it would be running on Asset Hub as part of the Plaza vision.
The way that staking on a parachain will be achieved has been planned out extensively by the staking team, with input from others and then combined with expertise in the other areas affected to create the overall migration.
All of the major changes in staking are related to:
-
how validators are elected
-
how election results are communicated to the Relay Chain
-
how slashes are communicated and enacted from the Relay Chain to AH
Much of this is a direct result of moving to a parachain, where there are different implications of overweight blocks on AH vs the RC - currently on the relay chain staking works by just accepting that sometimes it will produce overweight blocks, but if this were to happen on Asset Hub it would stall. We are putting bounds on storage, paginating where needed, and allowing the elections and snapshots to run across multiple blocks.
As far as the staking API goes: for any staking user (end user, liquid staking etc) the interface is the same, albeit on AH instead of RC. From this perspective the same staking pallet will be migrated and be running on AH. This means that during the migration, you just need to switch the liquid staking solution over from RC to AH. There will be an entry in the supervisor pallet’s state to note the stage of the migration.
The only major exception to this is that we are also tackling the long standing issue of nomination pool funds not being held in user accounts. We are changing this during the migration, and therefore allowing these funds to be usable in governance. This will impact wallets, as the funds staked in nomination pools will suddenly re-appear in the user account as an amount on hold.
The only detailed change for normal stakers would be that validators would have to set their session keys in relay, and the rest of the operations will happen as-is, just on AH instead of RC (validate, set_commission, etc.)
Overall migration
For the migration, we determined what needed to happen for the migration to be successful for staking and other parts of the system, discussed several options of how that would work and went through many steps of iteration to work out the kinks and where things overlapped to ensure that we have a smooth transition of the system as a whole. We considered going in multiple stages in the early discussions but after exploring it a bit we realised that it is much cleaner to do it in one go for a range of factors.
I'll not go too deep into those now, but on a high level:
-
It's not always possible to disentangle each pallet with a balances dependency from the others e.g. locks can overlap, so migrating one pallet's lock and the associated funds without the others means there are cases where the account no longer has the balance remaining to have the other locks.
-
Migrating staking moves 51% (currently) of the total issuance away from the chain where governance is ongoing - by moving staking or governance first and leaving the other behind would mean that the amount of funds usable for voting is diminished. This can be solved by either changing the curves or writing some method of remote locking, but the extra work and complexity can be avoided by just moving them together in one step. Since governance is relatively easy to move, we decided to go for this option.
Taken from a slide from my presentation at the parachains AHM AMA that we ran in November:
-
Add functionality to AH
-
Special supervisor pallet in runtimes to handle migration of state via XCM during one special era
-
Balances: Account by account, unlock, transfer, re-lock
-
Pallet states: chunked basically 1to1 replication
-
Referenda calls: converted where possible, sent back to RC where not possible
-
Extrinsics to recalculate deposits/locks (decreasing) called by bots
Staking migration
Election pallet - no need to migrate, recreated every era
Bags list - does not need to be transferred, can be recalculated, but needs to be done before the next snapshot
Staking migration steps:
-
Special era begins
-
Slashes applied
-
Migration starts
-
Balances move
-
Staking data moved
-
Bags list recalculated
-
Election pallet state recreated
(block new election signal if we overrun)
-
Migration ends signal
-
Send signal to relay chain to start new election
What calls will be disabled at which steps?
The Staking and Governance calls in particular will be disabled on the relay chain from the start of the special era in which this will all happen. These filters will remain on staking on the relay chain until the pallets are removed.
The supervisor pallet will control the flow of the overall migration and each of its subtasks. A rough order of operations is the following:
-
Temporarily filter all calls affecting balances, staking, governance or other pallets which are moving to avoid the state changing mid-migration
-
Migrate as mentioned above
-
Remove the call filter on calls temporarily filtered that are still allowed (broadly this is just the following pallets: Balances, Multisig, Proxies, HRMP ops and parachain registration)
Remove the state which has been migrated
Remove the pallets that have been moved
Depth
- AHM FAQ
- Project board
- High level plan from September
- Overview of the protocol migration also from september
There are other docs linked from those last two google docs which can be recursed into for more depth. The project board should be enough to get up to speed with what is being worked on, but for anything that is unclear just reach out to me and I'll let you know, then update the project board.
Testing
There are two overall aspects to the testing:
- Testing the future functionality of the system (Chopsticks via the ecosystem tests repo where possible) https://docs.google.com/document/d/1xiF3KwmRMa24bGrgliv6YRmFZYvaaF7OkLe2GgIxv9Q/edit?tab=t.0#heading=h.7ncey3c1eizr
- Testing the migration and ensuring the state is copied over successfully (Zombie-bite + chopsticks) https://docs.google.com/document/d/15dlkWa7g2W6NJq7OshFyEh8fBqmW5yK4OUd0hLXrvJ4/edit?tab=t.0#heading=h.ft0jt1o5cbip
Polkadot Ecosystem tests from Alexandre explains a bit about PET
