From 8a7c35fca2a1fbe9be290ffde251491456ee3c4d Mon Sep 17 00:00:00 2001 From: Eric Lau Date: Thu, 11 Apr 2024 13:41:38 -0400 Subject: [PATCH] Improve docs and highlighting (#42) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Ernesto García --- DEFENDER.md | 14 +++++++------- README.md | 16 ++++++++++++++-- docs/modules/pages/foundry-defender.adoc | 9 ++++++--- docs/modules/pages/foundry-upgrades.adoc | 23 ++++++++++++++++++++++- 4 files changed, 49 insertions(+), 13 deletions(-) diff --git a/DEFENDER.md b/DEFENDER.md index c2b870b..c4601bf 100644 --- a/DEFENDER.md +++ b/DEFENDER.md @@ -17,7 +17,7 @@ See [README.md#installing](README.md#installing) 1. Install [Node.js](https://nodejs.org/). 2. Configure your `foundry.toml` to enable ffi, ast, build info and storage layout: -``` +```toml [profile.default] ffi = true ast = true @@ -27,16 +27,16 @@ extra_output = ["storageLayout"] **Note**: Metadata must also be included in the compiler output, which it is by default. 3. Set the following environment variables in your `.env` file at your project root, using your Team API key and secret from OpenZeppelin Defender: -``` -DEFENDER_KEY= -DEFENDER_SECRET +```env +DEFENDER_KEY="" +DEFENDER_SECRET="" ``` ## Network Selection 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: -``` +```env DEFENDER_NETWORK=my-mainnet-fork ``` If set, this must be the name of a public, private or forked network in Defender. If the `chainId` parameter corresponds to a different network while this is set, the deployment will not occur and will throw an error instead. @@ -89,7 +89,7 @@ contract DefenderScript is Script { Then run the following command: ```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. @@ -156,7 +156,7 @@ contract DefenderScript is Script { Then run the following command: ```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 [Deploy module](https://defender.openzeppelin.com/v2/#/deploy). diff --git a/README.md b/README.md index b5349b4..b9cb9aa 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Set the following in `remappings.txt`, replacing any previous definitions of the 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 [Git for Windows](https://gitforwindows.org/), add the following line in the `.env` file of your project (using forward slashes): -``` +```env OPENZEPPELIN_BASH_PATH="C:/Program Files/Git/bin/bash" ``` @@ -47,7 +47,7 @@ This library uses the [OpenZeppelin Upgrades CLI](https://docs.openzeppelin.com/ If you want to be able to run upgrade safety checks, the following are needed: 1. Install [Node.js](https://nodejs.org/). 2. Configure your `foundry.toml` to enable ffi, ast, build info and storage layout: -``` +```toml [profile.default] ffi = true ast = true @@ -59,6 +59,18 @@ 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: +```toml +[profile.default] +out = "my-output-dir" +``` +Then set the following in the `.env` file of your project: +```env +FOUNDRY_OUT=my-output-dir +``` + ## Usage Import the library in your Foundry scripts or tests: diff --git a/docs/modules/pages/foundry-defender.adoc b/docs/modules/pages/foundry-defender.adoc index 71fcd0c..fd6b314 100644 --- a/docs/modules/pages/foundry-defender.adoc +++ b/docs/modules/pages/foundry-defender.adoc @@ -13,7 +13,8 @@ See xref:foundry-upgrades#installation[Using with Foundry - Installation]. 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 @@ -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/pages/foundry-upgrades.adoc b/docs/modules/pages/foundry-upgrades.adoc index 026870d..6ce0f91 100644 --- a/docs/modules/pages/foundry-upgrades.adoc +++ b/docs/modules/pages/foundry-upgrades.adoc @@ -5,6 +5,7 @@ Foundry library for deploying and managing upgradeable contracts, which includes == Installation Run these commands: + [source,console] ---- forge install foundry-rs/forge-std @@ -13,6 +14,7 @@ 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/ @@ -25,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" @@ -45,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 @@ -61,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: