From 836b920dfe9b3547763199a2ddb323a78620854e Mon Sep 17 00:00:00 2001 From: Eric Lau Date: Thu, 11 Apr 2024 14:01:27 -0400 Subject: [PATCH] Update Foundry Upgrades submodule (#1005) --- .../pages/foundry/pages/foundry-defender.adoc | 13 +++++--- .../pages/foundry/pages/foundry-upgrades.adoc | 32 ++++++++++++++++++- submodules/openzeppelin-foundry-upgrades | 2 +- 3 files changed, 40 insertions(+), 7 deletions(-) diff --git a/docs/modules/ROOT/pages/foundry/pages/foundry-defender.adoc b/docs/modules/ROOT/pages/foundry/pages/foundry-defender.adoc index 1ac14ef45..fd6b31466 100644 --- a/docs/modules/ROOT/pages/foundry/pages/foundry-defender.adoc +++ b/docs/modules/ROOT/pages/foundry/pages/foundry-defender.adoc @@ -7,13 +7,14 @@ The recommended pattern is to separate Defender scripts from scripts that rely o == Installation -See xref:foundry-upgrades#installion[Using with Foundry - Installation]. +See xref:foundry-upgrades#installation[Using with Foundry - Installation]. == Prerequisites 1. Install https://nodejs.org/[Node.js]. 2. Configure your `foundry.toml` to enable ffi, ast, build info and storage layout: -[source,toml] + +[source,json] ---- [profile.default] ffi = true @@ -26,6 +27,7 @@ NOTE: Metadata must also be included in the compiler output, which it is by defa [start=3] 3. Set the following environment variables in your `.env` file at your project root, using your Team API key and secret from OpenZeppelin Defender: + [source] ---- DEFENDER_KEY= @@ -36,6 +38,7 @@ DEFENDER_SECRET The network that is used with OpenZeppelin Defender is determined by the network that Foundry is connected to. If you want to ensure that a specific network is used with Defender, set the `DEFENDER_NETWORK` environment variable in your `.env` file, for example: + [source] ---- DEFENDER_NETWORK=my-mainnet-fork @@ -48,7 +51,7 @@ NOTE: This is required if you have multiple forked networks in Defender with the === Upgradeable Contracts -If you are deploying upgradeable contracts, use the `Upgrades` library as described in xref:foundry-upgrades#installion[Using with Foundry - Installation] but set the option `defender.useDefenderDeploy = true` when calling functions to cause all deployments to occur through OpenZeppelin Defender. +If you are deploying upgradeable contracts, use the `Upgrades` library as described in xref:foundry-upgrades#installation[Using with Foundry - Installation] but set the option `defender.useDefenderDeploy = true` when calling functions to cause all deployments to occur through OpenZeppelin Defender. **Example 1 - Deploying a proxy**: To deploy a UUPS proxy, create a script called `Defender.s.sol` like the following: @@ -91,7 +94,7 @@ contract DefenderScript is Script { Then run the following command: [source,console] ---- -forge script --ffi --rpc-url +forge script --force --rpc-url ---- The above example assumes the implementation contract takes an initial owner address as an argument for its `initialize` function. The script retrieves the address associated with the upgrade approval process configured in Defender (such as a multisig address), and uses that address as the initial owner so that it can have upgrade rights for the proxy. @@ -161,7 +164,7 @@ contract DefenderScript is Script { Then run the following command: [source,console] ---- -forge script --ffi --rpc-url +forge script --force --rpc-url ---- The above example calls the `Defender.deployContract` function to deploy the specified contract to the connected network using Defender. The function waits for the deployment to complete, which may take a few minutes, then returns with the deployed contract address. While the function is waiting, you can monitor your deployment status in OpenZeppelin Defender's https://defender.openzeppelin.com/v2/#/deploy[Deploy module]. diff --git a/docs/modules/ROOT/pages/foundry/pages/foundry-upgrades.adoc b/docs/modules/ROOT/pages/foundry/pages/foundry-upgrades.adoc index 338cc077b..6ce0f911d 100644 --- a/docs/modules/ROOT/pages/foundry/pages/foundry-upgrades.adoc +++ b/docs/modules/ROOT/pages/foundry/pages/foundry-upgrades.adoc @@ -5,13 +5,16 @@ Foundry library for deploying and managing upgradeable contracts, which includes == Installation Run these commands: + [source,console] ---- +forge install foundry-rs/forge-std forge install OpenZeppelin/openzeppelin-foundry-upgrades forge install OpenZeppelin/openzeppelin-contracts-upgradeable ---- Set the following in `remappings.txt`, replacing any previous definitions of these remappings: + [source] ---- @openzeppelin/contracts/=lib/openzeppelin-contracts-upgradeable/lib/openzeppelin-contracts/contracts/ @@ -24,6 +27,7 @@ NOTE: The above remappings mean that both `@openzeppelin/contracts/` (including If you are using Windows, set the `OPENZEPPELIN_BASH_PATH` environment variable to the fully qualified path of the `bash` executable. For example, if you are using https://gitforwindows.org/[Git for Windows], add the following line in the `.env` file of your project (using forward slashes): + [source] ---- OPENZEPPELIN_BASH_PATH="C:/Program Files/Git/bin/bash" @@ -31,6 +35,8 @@ OPENZEPPELIN_BASH_PATH="C:/Program Files/Git/bin/bash" == Version Limitations +This library requires https://github.com/foundry-rs/forge-std[forge-std] version 1.8.0 or higher. + This library currently only supports proxy contracts and upgrade interfaces from OpenZeppelin Contracts versions 5.0 or higher. == Before Running @@ -42,7 +48,8 @@ If you want to be able to run upgrade safety checks, the following are needed: 1. Install https://nodejs.org/[Node.js]. 2. Configure your `foundry.toml` to enable ffi, ast, build info and storage layout: -[source,toml] + +[source,json] ---- [profile.default] ffi = true @@ -58,6 +65,23 @@ extra_output = ["storageLayout"] If you do not want to run upgrade safety checks, you can skip the above steps and use the `unsafeSkipAllChecks` option when calling the library's functions. Note that this is a dangerous option meant to be used as a last resort. +=== Output directory configuration + +If your `foundry.toml` uses a non-default output directory, set the `FOUNDRY_OUT` environment variable to match your output directory. For example, if `foundry.toml` has: + +[source,json] +---- +[profile.default] +out = "my-output-dir" +---- + +Then set the following in the `.env` file of your project: + +[source] +---- +FOUNDRY_OUT=my-output-dir +---- + == Usage Import the library in your Foundry scripts or tests: @@ -66,6 +90,12 @@ Import the library in your Foundry scripts or tests: import {Upgrades} from "openzeppelin-foundry-upgrades/Upgrades.sol"; ---- +Also import the implementation contract that you want to validate, deploy, or upgrade to, for example: +[source,solidity] +---- +import {MyToken} from "src/MyToken.sol"; +---- + Then call functions from `Upgrades.sol` to run validations, deployments, or upgrades. === Examples diff --git a/submodules/openzeppelin-foundry-upgrades b/submodules/openzeppelin-foundry-upgrades index 359589365..8a7c35fca 160000 --- a/submodules/openzeppelin-foundry-upgrades +++ b/submodules/openzeppelin-foundry-upgrades @@ -1 +1 @@ -Subproject commit 359589365aeba6cf41d39bae69867446b194e582 +Subproject commit 8a7c35fca2a1fbe9be290ffde251491456ee3c4d