# Testing account balances migration to Asset Hub

This document focuses on testing the migration of account balances on Polkadot, with Holds (Reserves) and Locks (Freezes). There is also an overview of the current migration process.

**Reserved and frozen balances**

Notice that, initially, reserves on Polkadot were unnamed and they were later replaced by named reserves. Finally, all named reserves have been migrated to holds. Currently, we only have unnamed reserves and holds: the former are just counted into the amount of reserved balance for an account, the latter are also stored in the map `Holds`. However, they both contribute to the total amount of reserved balance for an account. The balance amount which is not reserved is also known as the _free_ balance of the account.

Besides reserved balance, Polkadot also used locks for locked balances, storing them in the map `Locks`. They have been now deprecated in favor of freezes, which are stored in the map `Freezes`, and locked balance is now referred to as _frozen_. However, locks and freezes both contribute to the amount of frozen balance for an account.

The Asset Hub Migration needs to migrate reserved and frozen balances together with the corresponding storage maps.

## Migrating Accounts with Balances

When possible, relay chain accounts should be fully migrated to Asset Hub with their whole balance, their holds, reserves, locks, and freezes. However, some accounts need to be kept on the relay chain, fully or in part.

### Accounts partially preserved on the relay chain

There are several categories of accounts that cannot be fully migrated to Asset Hub because they have reserves that need to be kept on the relay chain. Those reserves are:
- deposits for the sender and the receiver of existing HRMP channels
- deposits for requests for opening an HRMP channel
- deposits for registered parachains

Accounts having some balance reserved for one of these reasons need to be preserved on the relay chain with the corresponding reserved balance and the Relay Chain existential deposit as free balance. The remaining balance with all the holds/reserves and freezes/locks associated with the account is migrated to Asset Hub. It may happen than the account free balance is not enough to cover for both the Relay Chain existential deposit (1 DOT) and the Asset Hub existential deposit (0,01 DOT). This may cause problems on Asset Hub, like failures when migrating holds for unsufficient reservable balance. For this reason, in such cases we unreserve some of the reserved balance kept on the Relay Chain so that we have at least 1,01 DOT free balance to cover both existential deposits: 1 DOT free balance will be kept on the relay chain, while the remaining free balance (always ≥ 0,01 DOT) will be migrated to Asset Hub.

### Fully preserved accounts on the Relay Chain

The on-demand pallet account, which holds the funds from instantaneous coretime sale, must be fully preserved on the relay chain. Moreover, all accounts having total balance which is less than the Relay Chain existential deposit are also preserved on the Relay Chain.

### Checking Account

The checking account, which tracks the total amount of DOT stored outside of the relay chain, is also migrated to Asset Hub. Its balance is adjusted to reflect the total balance stored outside of Asset Hub. For more details, see [this](https://github.com/polkadot-fellows/runtimes/blob/dev-asset-hub-migration/pallets/rc-migrator/src/accounts.md#xcm-checking-account-and-dotksm-total-issuance-tracking).

### What happens on Asset Hub

After accounts have been migrated to Asset Hub, their holds may change and their reserved balance too. This is the case of multisig deposits, which are unreserved since multisigs are not migrated to Asset Hub. The same happens for deposits for legacy storage items for pallet preimage, while proxy announcements deposits may be unreserved if they cannot be converted to Asset Hub proxy announcements. Also notice that preimage deposits are re-computed and changed on Asset Hub during the migration, and so the corresponding holds are changed. For this reason, computing the total amount of reserved balance on Asset Hub after the migration for a single account is quite involved and has not been tested yet.

Instead, freezes and locks should not change, so they are easily predictable and can be tested on Asset Hub.

### Edge cases

After nomination pools have been changed to use holds from `pallet-delegated-staking`, many accounts ended up with holds that covered all their balance, leaving them with zero or close to zero free balance. This may cause issues when migrating those accounts to Asset Hub, like failures in applying unnamed reserves. Among those accounts, we noticed that account [5HBpFvUckfYEevbMnGXgGidcCRBygFww1FyksaJXYxjagPCK](https://polkadot.subscan.io/account/1687QFjgcSoi6TbsjuagQsTm43BdNZW55kiF2sHt73m6ronH) has ~ 0,0001 DOT free balance on the relay chain and a delegated staking hold of ~ 2,2084 DOT. When migrated to Asset Hub, at first its whole ~ 2,2085 DOT balance is minted correctly. However, when the delegated staking hold is applied, since the remaining free balance is less than the Asset Hub existential deposit, the free balance gets dusted and the account is left with 0 free balance. We need to take this into account for tests.

## Unit Tests

There is a tradeoff between the coverage of tests and their complexity. In general, we must avoid re-using the migration code in tests: this prevented us from noticing a bug in hold id translation. Here are some details about the tests.

### Accounts

For individual accounts, we check that all holds, locks, and freezes are correctly migrated to Asset Hub. Moreover, as for balances, we check that:
- partly migrated accounts keep only the minimun necessary balance on the relay chain (1 DOT existential deposit), while fully migrated accounts do not have any balance on the relay chain after migration
- partly and fully migrated accounts have their total relay chain balance correctly migrated to Asset Hub, allowing an error of at most the AH existential deposit (for dusted balances like the one mentioned in [Edge Cases](#edge-cases))
- the amount of reserved balance on Asset Hub for a single account is at most the amount of migrated reserved balance. Here we do not make more precise checks accounting for multisig deposits or other unreserved deposits, as mentioned in [this section](#what-happens-on-asset-hub).
- Holds are correctly migrated to Asset Hub (with Preimage deposits being re-computed correctly), as well as locks and freezes.

### Total issuance and Checking balance

We check the identities on total balances and checking accounts from [this doc](https://github.com/polkadot-fellows/runtimes/blob/dev-asset-hub-migration/pallets/rc-migrator/src/accounts.md#xcm-checking-account-and-dotksm-total-issuance-tracking). There is only a small error on total issuances, since we expect the total issuance on Asset Hub after migration to be equal to the total issuance on the Relay Chain before migration. However, they differ by ~ 0.010108 DOT, so we just assert the equality up to an error < 0,1 DOT. The difference may come from:
- 0,000108 DOT dusted for account [5HBpFvUckfYEevbMnGXgGidcCRBygFww1FyksaJXYxjagPCK](https://polkadot.subscan.io/account/1687QFjgcSoi6TbsjuagQsTm43BdNZW55kiF2sHt73m6ronH)
- 0,01 DOT probably from the DED airdrop to the checking account (this is just an hypothesis)