You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/src/content/ignition/docs/guides/upgradeable-proxies.md
+82-19
Original file line number
Diff line number
Diff line change
@@ -60,7 +60,7 @@ Because we're using the OpenZeppelin proxy contracts, we need to import them her
60
60
61
61
## Writing our Ignition modules
62
62
63
-
Inside our `ignition` directory, we'll create a directory called `modules`, if one doesn't already exist. Inside this directory, we'll create a file called `ProxyModule.js` (or `ProxyModule.ts` if you're using TypeScript). Inside this file, we'll break up our Ignition module into three parts.
63
+
Inside our `ignition` directory, we'll create a directory called `modules`, if one doesn't already exist. Inside this directory, we'll create a file called `ProxyModule.js` (or `ProxyModule.ts` if you're using TypeScript). Inside this file, we'll break up our first Ignition module into two parts.
64
64
65
65
### Part 1: Deploying our proxies
66
66
@@ -140,11 +140,53 @@ Then, we deploy our `TransparentUpgradeableProxy` contract. This contract will b
140
140
141
141
When we deploy the proxy, it will automatically create a new `ProxyAdmin` contract within its constructor. We'll need to get the address of this contract so that we can interact with it later. To do this, we'll use the `m.readEventArgument(...)` method to read the `newAdmin` argument from the `AdminChanged` event that is emitted when the proxy is deployed.
142
142
143
-
Finally, we'll use the `m.contractAt(...)` method to get the `ProxyAdmin` contract at the address we retrieved from the event and return it along with the proxy.
143
+
Finally, we'll use the `m.contractAt(...)` method to tell Ignition to use the `ProxyAdmin`ABI for the contract at the address we just retrieved. This will allow us to interact with the`ProxyAdmin` contract when we upgrade our proxy.
144
144
145
-
### Part 2: Upgrading our proxy
145
+
### Part 2: Interacting with our proxy
146
146
147
-
Now that we have our proxy deployed, we want to upgrade it. To do this, within the same file, we'll create a new module called `UpgradeModule`:
147
+
Now that we have our proxy deployed, we're ready to interact with it. To do this, we'll create a new module called `DemoModule`:
First, we use the `m.useModule(...)` method to get the proxy contract from the previous module. This will ensure that the proxy is deployed before we try to upgrade it.
160
+
161
+
Then, similar to what we did with our `ProxyAdmin` above, we use `m.contractAt("Demo", proxy)` to tell Ignition to use the `Demo` ABI for the contract at the address of the proxy. This will allow us to interact with the `Demo` contract through the proxy when we use it in tests or scripts.
162
+
163
+
Finally, we return the `Demo` contract instance so that we can use it in other modules, or tests and scripts. We also return the `proxy` and `proxyAdmin` contracts so that we can use them to upgrade our proxy in the next module.
164
+
165
+
As a last step, we'll export `demoModule` from our file so that we can deploy it and use it in our tests or scripts:
166
+
167
+
::::tabsgroup{options="TypeScript,JavaScript"}
168
+
169
+
:::tab{value="TypeScript"}
170
+
171
+
```typescript
172
+
exportdefaultdemoModule;
173
+
```
174
+
175
+
:::
176
+
177
+
:::tab{value="JavaScript"}
178
+
179
+
```javascript
180
+
module.exports= demoModule;
181
+
```
182
+
183
+
:::
184
+
185
+
::::
186
+
187
+
### Part 3: Upgrading our proxy
188
+
189
+
Next it's time to upgrade our proxy to a new version. To do this, we'll create a new file within our `ignition/modules` directory called `UpgradeModule.js` (or `UpgradeModule.ts` if you're using TypeScript). Inside this file, we'll again break up our module into two parts. To start, we'll write our `UpgradeModule`:
This module begins the same way as the previous one, by getting the account that owns the `ProxyAdmin` contract. We'll use this in a moment to upgrade the proxy.
207
+
This module begins the same way as `ProxyModule`, by getting the account that owns the `ProxyAdmin` contract. We'll use this in a moment to upgrade the proxy.
166
208
167
-
Next, we use the `m.useModule(...)` method to get the `ProxyAdmin` and proxy contracts from the previous module. This will ensure that the proxy is deployed before we try to upgrade it.
209
+
Next, we use the `m.useModule(...)` method to get the `ProxyAdmin` and proxy contracts from the previous module.
168
210
169
211
Then, we deploy our `DemoV2` contract. This will be the contract that we'll upgrade our proxy to.
170
212
171
213
Finally, we call the `upgradeAndCall` method on the `ProxyAdmin` contract. This method takes three arguments: the proxy contract, the new implementation contract, and a data parameter that can be used to call an additional function. We don't need it right now, so we'll leave it blank by setting it to an empty hex string (`"0x"`). We also provide the `from` option to ensure that the upgrade is called from the owner of the `ProxyAdmin` contract.
172
214
173
215
Lastly, we again return the `ProxyAdmin` and proxy contracts so that we can use them in our next module.
174
216
175
-
### Part 3: Interacting with our proxy
217
+
### Part 4: Interacting with our upgraded proxy
176
218
177
-
Now that we have our proxy deployed and upgraded, we're ready to interact with it. To do this, we'll create a new module called `InteractableModule`:
219
+
Finally, in the same file, we'll create our module called `DemoV2Module`:
First, as before, we use the `m.useModule(...)` method to get the proxy contract from the previous module.
190
-
191
-
Then, we use `m.contractAt("DemoV2", proxy)` to get the `DemoV2` contract at the address of the proxy. This will allow us to interact with the proxy as if it were the `DemoV2` contract itself.
232
+
This module is similar to `DemoModule`, but instead of using the `Demo` contract, we use the `DemoV2` contract. Though the `Demo` contracts are contrived for this example and don't actually change the ABI between upgrades, this module demonstrates how you can interact with different versions of your contract ABI through the same proxy.
192
233
193
-
Finally, we return the `DemoV2` contract instance so that we can use it in other modules or tests.
234
+
As before, we return the `DemoV2` contract instance so that we can use it in other modules, or tests and scripts. We could also return the `proxy` and `proxyAdmin` contracts if we needed to interact with them further, but for the purposes of this example, we left them out.
194
235
195
-
As a final step, we'll export `interactableModule` from our file so that we can deploy it and use it in our tests:
236
+
As a last step, we'll export `demoV2Module` from our file so that we can deploy it and use it in our tests or scripts:
Now that we've written our Ignition modules for deploying and interacting with our proxy, let's write a simple test to make sure everything works as expected.
260
+
Now that we've written our Ignition modules for deploying and interacting with our proxy, let's write a couple of simple tests to make sure everything works as expected.
220
261
221
262
Inside our `test` directory, we'll create a file called `ProxyDemo.js` (or `ProxyDemo.ts` if you're using TypeScript):
222
263
@@ -228,8 +269,19 @@ Inside our `test` directory, we'll create a file called `ProxyDemo.js` (or `Prox
@@ -268,7 +331,7 @@ describe("Demo Proxy", function () {
268
331
269
332
::::
270
333
271
-
Here we use Hardhat Ignition to deploy our imported module. Then, we use the `demo` contract instance that is returned to call the `version` method and make sure that it returns the correct version string.
334
+
Here we use Hardhat Ignition to deploy our imported modules. First, we deploy our base `ProxyModule` that returns the first version of our `Demo` contract and test it to ensure the proxy worked and retrieves the appropriate version string. Then, we deploy our `UpgradeModule` that returns the second version of our `Demo` contract and test it to ensure the proxy now returns the updated version string.
0 commit comments