V1 to V2 Migration Guide
This guide explains how to migrate assets from an older vault (v1Vault) to a newer vault (v2Vault) using the migrateToV2 function. The migration process allows users to transfer their vault shares securely and efficiently, ensuring compatibility between the vaults and maintaining the value of the migrated assets.
Prerequisites
Before initiating the migration, ensure that the following conditions are met:
-
Allowlisted Migration Route: The migration route between the old vault (
v1Vault) and the new vault (v2Vault) must be approved by the owner, otherwise the migration will fail. -
Same Underlying Asset: Both vaults must manage the same underlying asset.
Steps
Fetch values:
| Parameter | Description |
|---|---|
v1Vault | Address of the old vault proxy NOT vaultSupervisor, however uou can get this from the vaultSupervisor contract or here Addresses. |
v2Vault | Address of the new vault proxy, NOT implementation, that you want to deposit into. List of all vaults can be found here GET Vaults |
oldShares | Number of shares in the old v1 vault that you want to migrate. Call balanceOf(holderAddr) on the old vault to get this. |
minNewShares | Frontrunning protection mechanism. Usually set to oldShares amount minus 1 to account for any rounding. |
(Optional) Return Shares
If some or all the oldShares are tokenized, meaning not held on the behalf of the user/contract by the vaultSupervisor, you need to return them to the vaultSupervisor to convert them into internal shares. This is a prerequisite for migration to V2.
Call returnShares from the holder of the shares to convert them into internal shares.
vaultSupervisor.redeem(v1VaultProxyAddr, numSharesToReturn);Migrate
vaultSupervisor.migrateToV2(v1VaultProxy, v2VaultProxy, oldShares, minNewShares);Shares will be burned in the old vault, assets will be redeemed and deposited into the new vault, and new shares will be minted to the msg.sender
Events emitted during migration
The following events are emitted during the migration process:
| Definition | Emission |
|---|---|
event StartedWithdrawal(address indexed vault, address indexed staker, address indexed operator, address withdrawer, uint256 shares); | emit StartedWithdrawal(address(v1Vault), msg.sender, address(vaultSupervisorProxy), msg.sender, oldShares); |
event FinishedWithdrawal(address indexed vault,address indexed staker,address indexed operator,address withdrawer,uint256 shares,bytes32 withdrawRoot); | emit FinishedWithdrawal(address(v1Vault), msg.sender, address(vaultSupervisorProxy), msg.sender, oldShares, bytes32(0)); |
event MigratedToV2(address indexed user,address indexed v1Vault,address indexed v2Vault,uint256 oldShares,uint256 newShares,uint256 assets); | emit MigratedToV2(msg.sender, address(v1Vault), address(v2Vault), oldShares, newShares, withdrawnAssets); newShares: The number of new vault shares minted for the user. withdrawnAssets: The amount of underlying tokens redeemed from v1Vault and deposited into v2Vault. |