Skip to content

Commit 2d8e919

Browse files
KristenPireKristenPire
authored
Create migrating_V1_to_V2.md
1 parent 26ad540 commit 2d8e919

File tree

1 file changed

+155
-0
lines changed

1 file changed

+155
-0
lines changed

‎docs/migrating_V1_to_V2.md

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
v1) to the new version presents complexities.
2+
3+
This document outlines a plan to migrate funds safely from v1 to v2, ensuring the v1 token frontend's address remains operational as a legacy interface.
4+
5+
Our aim is to facilitate a seamless transition, maintaining continuity for our users while leveraging the enhancements of v2.
6+
## Requirements
7+
8+
To proceed with the migration process, ensure the following prerequisites are met:
9+
10+
- [ ] The SmartController is upgraded to version **1.2.2**, incorporating the `pausable` feature.
11+
- [ ] Possession of the `TokenFrontend `address.
12+
- [ ] Access to the **version 2 (v2) foundry repository**, including all dependencies.
13+
14+
## Versions
15+
16+
| Contract | Version |
17+
| ------------------------ | -------- |
18+
| Node.js | v18.17.0 |
19+
| Forge | v0.2.0 |
20+
| Monerium ControllerToken | v2.0.0 |
21+
| Monerium TokenFrontend | v1.0.0 |
22+
| Monerium SmartController | v1.2.2 |
23+
24+
## Architectural Overview
25+
*Legacy V1 architecture VS the new V2 architecture*
26+
![[Pasted image 20240329134835.png]]
27+
28+
*V2 architecture with retro compatibility with the legacy V1 frontend*
29+
![[Screenshot 2024-03-29 at 13.49.49.png]]
30+
31+
The objective is to migrate the assets currently held within `TokenStorage` to the storage system of the `Proxy`
32+
33+
By adopting proxy storage, we introduce a level of adaptability to our contract architecture, enabling the management of stored funds to evolve alongside technological advancements and users needs.
34+
35+
Moreover, the existing `Frontend` interface, with its standard `ERC20` capabilities, will maintain its functionality. User interactions with the `Frontend` will be seamlessly redirected to the `Proxy`, which in turn will communicate with the `Implementation` contract
36+
37+
This strategy allows us to present our partners and users with a modernised entry point to our currency, featuring updated functionalities, while still offering the familiar services and addresses they have come to rely on.
38+
39+
## Step-by-Step Migration Guide
40+
41+
The migration process involves a `JavaScript` script that creates a `Foundry` Solidity script, utilising a list of users acquired from an `Etherscan` service.
42+
43+
We will use one `wallet` to deploy and run the migration and set the final `roles` and `owner` after completion.
44+
45+
> This documentation focuses on the migration of a single token. It is recommended to deploy all four tokens simultaneously with the same implementation contract and then conduct each migration separately
46+
### 1. Deploying the `V2` contract.
47+
48+
To initiate the deployment of the V2 contract, follow these steps within the V2 foundry repository:
49+
50+
1. Set the following environment variables in your terminal:
51+
52+
```
53+
export PRIVATE_KEY=<your_key>
54+
export RPC_URL=<your_provider>
55+
export ETHERSCAN_API_KEY=<your_api_key>
56+
```
57+
> Note: When deploying to Polygon or Gnosis chain, place your `PolygonScan` or `GnosisScan` API key in the `ETHERSCAN_API_KEY` field. For deployments to other chains, additional details can be found in `script/deployAll.sh`
58+
59+
2. To deploy, execute the following command:
60+
```sh
61+
forge script script/deploy.s.sol:ControllerEUR --rpc-url $RPC_URL --broadcast --etherscan-api-key $ETHERSCAN_API_KEY --verify $VERIFIER_URL
62+
```
63+
3. Your V2 `Proxy` and `Implementation` contracts are now deployed and verified on the blockchain explorer.
64+
65+
### 2. Configuring the `V2` contract.
66+
67+
Provide `admin` and `system` roles to the `wallet` used for the migration (the same one used for deployment). These roles are crucial early in the fund migration process for adding `MintAllowance`.
68+
69+
1. Set the following environment variables in your terminal:
70+
```sh
71+
export TOKEN_ADDRESS=<proxy_address>
72+
export SYSTEM_ADDRESS=<your_wallet_address>
73+
export ADMIN_ADDRESS=<your_wallet_address>
74+
```
75+
76+
2. To launch, execute the following command:
77+
```sh
78+
forge script script/setAdminAndSystem.s.sol --rpc-url $RPC_URL --broadcast
79+
```
80+
3. Your `V2` contract is now ready to launch the Migration script.
81+
82+
### 3. Pause the `V1` token
83+
84+
During the migration, we will fetch a list of holders from `Etherscan`. To ensure this list remains unchanged, it's crucial to **pause** all operations such as `transfer`, `mint`, and `burn` on the `V1` token. This action will freeze the state of the token, securing the integrity of holder balances throughout the transition process to `V2`.
85+
86+
### 4. Download the `Holders` list
87+
88+
To obtain the list of current token holders, follow these steps:
89+
90+
1. Navigate to the Etherscan page by replacing `{YOUR-TOKEN-ADDRESS}` with your actual token `V1` contract address in the URL below:
91+
```
92+
https://etherscan.io/exportData?type=tokenholders&contract={YOUR-TOKEN-ADDRESS}&decimal=18
93+
```
94+
2. Choose `Token Holders (ERC-20)` as the export type from the available options.
95+
3. Ensure the Token Contract Address displayed is accurate and corresponds to your `V1` token.
96+
4. Download the `csv` file provided and move it to the `V2` foundry repository
97+
98+
### 5. Generate the migration script
99+
100+
A JavaScript script crafts a Solidity script by using `V1` and `V2` token addresses and hardcoding the `csv`-derived holder addresses.
101+
102+
The generated Solidity script then sets `V2`'s mint allowance to equal `V1`'s `totalSupply`.
103+
For each holder, the script uses `V1`'s `balanceOf` function to determine the amount to mint in `V2`.
104+
105+
The process concludes with `toalSupply` check between `V2` and `V1`.
106+
107+
1. To create the migration script, execute the following command:
108+
```sh
109+
node script/generateBatchMint.js <v2-address> <v1-address> holders.csv
110+
```
111+
> Note: the generated script will be located in the `script` directory, named `BatchMint-{v1-address}.s.sol`.
112+
113+
2. Begin the migration by running:
114+
```sh
115+
forge script script/BatchMint-{v1-address}.s.sol --rpc-url $RPC_URL --broadcast
116+
```
117+
3. Congratulations, your funds have been successfully migrated to your `V2` contract.
118+
119+
> Note: It's crucial to understand that the funds in `V1` remain unchanged. Instead, the migration process duplicates the balances into the `V2` contract.
120+
> The `V1` contract will be discontinued in favor of `V2`, hence the state of `V1` is preserved and not altered during this transition.
121+
122+
### 6. Redirecting `V1` `TokenFrontend` Calls to `V2` `Proxy`
123+
124+
With the funds successfully migrated to the `V2` contract, the next step involves setting up `V2`'s configurations—specifically, its roles and ownership. Additionally, we need to establish a connection between `V1`'s `TokenFrontend` and `V2`'s `Proxy`.
125+
126+
1. Remove the migration's `wallet` as `admin` and `sytem`
127+
```sh
128+
export TOKEN_ADDRESS=<proxy_address>
129+
export WALLET_ADDRESS=<your_wallet_address>
130+
forge script script/unsetAdminAndSystem.s.sol --rpc-url $RPC_URL --broadcast
131+
```
132+
2. Configure the `V2` token with `admins`, `system` and `maxMintAllowance`
133+
```sh
134+
export PRIVATE_KEY=<owner_key>
135+
export TOKEN_ADDRESS=<proxy_address>
136+
export SYSTEM_ADDRESS=<system_address>
137+
export ADMIN_ADDRESS=<admin_address>
138+
export MAX_MINT_ALLOWANCE=<amount_in_wei>
139+
forge script script/configureToken.s.sol --rpc-url $RPC_URL --broadcast
140+
```
141+
4. Configure the `V2` token with minting allowance
142+
143+
Refer to this page.
144+
145+
5. Connect the `V2` proxy as `controller` for the `V1` `TokenFrontend`
146+
```sh
147+
export PRIVATE_KEY=<owner_key>
148+
export TOKEN_ADDRESS=<v2_proxy_address>
149+
export FRONTEND_ADDRESS=<v1_frontend_address>
150+
export OWNER_ADDRESS=<final_owner_address>
151+
forge script script/connectV2toV1.s.sol --rpc-url $RPC_URL --broadcast
152+
```
153+
154+
> This marks the completion of our migration process. Henceforth, the `TokenFrontend` will direct its calls to the `V2` `Proxy`, ensuring that user funds, now migrated, are managed through the updated contract.
155+

0 commit comments

Comments
 (0)