Remove Truffle, add placeholders for Foundry documentation (#956)

Co-authored-by: Ernesto García <[email protected]>

Author: ericglau

README.md

@@ -3,124 +3,62 @@
 [![Docs](https://img.shields.io/badge/docs-%F0%9F%93%84-blue)](https://docs.openzeppelin.com/upgrades-plugins)
 [![Coverage Status](https://codecov.io/gh/OpenZeppelin/openzeppelin-upgrades/graph/badge.svg)](https://codecov.io/gh/OpenZeppelin/openzeppelin-upgrades)
 
-**Integrate upgrades into your existing workflow.** Plugins for [Hardhat](https://hardhat.org/) and [Truffle](https://www.trufflesuite.com/truffle) to deploy and manage upgradeable contracts on Ethereum.
+**Integrate upgrades into your existing workflow.** Plugins for [Hardhat](https://hardhat.org/) and [Foundry](https://book.getfoundry.sh/) to deploy and manage upgradeable contracts on Ethereum.
 
 - Deploy upgradeable contracts.
 - Upgrade deployed contracts.
 - Manage proxy admin rights.
 - Easily use in tests.
 
-## Installation
+## Installation and Usage
 
-### Hardhat
+See the documentation for each plugin:
 
-```
-npm install --save-dev @openzeppelin/hardhat-upgrades
-npm install --save-dev @nomicfoundation/hardhat-ethers ethers # peer dependencies
-```
-
-```js
-// hardhat.config.js
-require('@openzeppelin/hardhat-upgrades');
-```
-
-### Truffle
-
-```
-npm install --save-dev @openzeppelin/truffle-upgrades
-```
-
-## Usage
-
-See the documentation for each plugin, or take a look at the sample code snippets below.
-
-| [<img src="assets/hardhat.svg" height="20px" width="30px" alt="">Hardhat](./packages/plugin-hardhat/README.md)| [<img src="assets/truffle.svg" height="20px" width="30px" alt="">Truffle](./packages/plugin-truffle/README.md) |
+| [<img src="assets/hardhat.svg" height="20px" width="30px" alt="">Hardhat](./packages/plugin-hardhat/README.md)| [<img src="https://avatars.githubusercontent.com/u/99892494?s=20&v=4" height="20px" width="20px" alt=""> Foundry](https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades) |
 |-|-|
 
-Hardhat users will be able to write [scripts](https://hardhat.org/guides/scripts.html) that use the plugin to deploy or upgrade a contract, and manage proxy admin rights.
-
-```js
-const { ethers, upgrades } = require("hardhat");
-
-async function main() {
-  // Deploying
-  const Box = await ethers.getContractFactory("Box");
-  const instance = await upgrades.deployProxy(Box, [42]);
-  await instance.waitForDeployment();
-
-  // Upgrading
-  const BoxV2 = await ethers.getContractFactory("BoxV2");
-  const upgraded = await upgrades.upgradeProxy(await instance.getAddress(), BoxV2);
-}
-
-main();
-```
-
-Truffle users will be able to write [migrations](https://www.trufflesuite.com/docs/truffle/getting-started/running-migrations) that use the plugin to deploy or upgrade a contract, or manage proxy admin rights.
-
-```js
-const { deployProxy, upgradeProxy } = require('@openzeppelin/truffle-upgrades');
-
-const Box = artifacts.require('Box');
-const BoxV2 = artifacts.require('BoxV2');
-
-module.exports = async function (deployer) {
-  const instance = await deployProxy(Box, [42], { deployer });
-  const upgraded = await upgradeProxy(instance.address, BoxV2, { deployer });
-}
-```
-
-Whether you're using Hardhat or Truffle, you can use the plugin in your tests to ensure everything works as expected.
-
-```js
-it('works before and after upgrading', async function () {
-  const instance = await upgrades.deployProxy(Box, [42]);
-  assert.strictEqual(await instance.retrieve(), 42);
-  
-  await upgrades.upgradeProxy(instance, BoxV2);
-  assert.strictEqual(await instance.retrieve(), 42);
-});
-```
-
 ## How do the plugins work?
 
 The plugins provide functions which take care of managing upgradeable deployments of your contracts.
 
 For example, `deployProxy` does the following:
 
-1. Validate that the implementation is [upgrade safe](https://docs.openzeppelin.com/upgrades-plugins/faq#what-does-it-mean-for-a-contract-to-be-upgrade-safe)
+1. Validates that the implementation is [upgrade safe](https://docs.openzeppelin.com/upgrades-plugins/faq#what-does-it-mean-for-a-contract-to-be-upgrade-safe).
 
-2. Check if there is an [implementation contract](https://docs.openzeppelin.com/upgrades-plugins/faq#what-is-an-implementation-contract) deployed with the same bytecode, and deploy one if not
+2. Deploys the [implementation contract](https://docs.openzeppelin.com/upgrades-plugins/faq#what-is-an-implementation-contract). Note that the Hardhat plugin first checks if there is an implementation contract deployed with the same bytecode, and skips this step if one is already deployed.
 
-3. Create and initialize the proxy contract, along with a [proxy admin](https://docs.openzeppelin.com/upgrades-plugins/faq#what-is-a-proxy-admin) (if needed)
+3. Creates and initializes the proxy contract, along with a [proxy admin](https://docs.openzeppelin.com/upgrades-plugins/faq#what-is-a-proxy-admin) (if needed).
 
 And when you call `upgradeProxy`:
 
-1. Validate that the new implementation is [upgrade safe](https://docs.openzeppelin.com/upgrades-plugins/faq#what-does-it-mean-for-a-contract-to-be-upgrade-safe) and is [compatible](https://docs.openzeppelin.com/upgrades-plugins/faq#what-does-it-mean-for-an-implementation-to-be-compatible) with the previous one
+1. Validates that the new implementation is [upgrade safe](https://docs.openzeppelin.com/upgrades-plugins/faq#what-does-it-mean-for-a-contract-to-be-upgrade-safe) and is [compatible](https://docs.openzeppelin.com/upgrades-plugins/faq#what-does-it-mean-for-an-implementation-to-be-compatible) with the previous one.
 
-2. Check if there is an [implementation contract](https://docs.openzeppelin.com/upgrades-plugins/faq#what-is-an-implementation-contract) deployed with the same bytecode, and deploy one if not
+2. Deploys the new [implementation contract](https://docs.openzeppelin.com/upgrades-plugins/faq#what-is-an-implementation-contract). Note that the Hardhat plugin first checks if there is an implementation contract deployed with the same bytecode, and skips this step if one is already deployed.
 
-3. Upgrade the proxy to use the new implementation contract
+3. Upgrades the proxy to use the new implementation contract.
 
-The plugins will keep track of all the implementation contracts you have deployed in an `.openzeppelin` folder in the project root. You will find one file per network there. It is advised that you commit to source control the files for all networks except the development ones (you may see them as `.openzeppelin/unknown-*.json`).
+The Hardhat plugin keeps track of all the implementation contracts you have deployed in an `.openzeppelin` folder in the project root. You will find one file per network there. It is advised that you commit to source control the files for all networks except the development ones (you may see them as `.openzeppelin/unknown-*.json`).
 
-> Note: the format of the files within the `.openzeppelin` folder is not compatible with those of the [OpenZeppelin CLI](https://docs.openzeppelin.com/cli). If you want to use these plugins for an existing OpenZeppelin CLI project, we will be sharing soon a guide on how to migrate.
+The Foundry plugin does not keep track of implementation contracts, but requires you to [define reference contracts](https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades?tab=readme-ov-file#before-running) in order to validate new versions of implementations for upgrade safety.
 
 ## Proxy patterns
 
-The plugins support the UUPS, transparent, and beacon proxy patterns. UUPS and transparent proxies are upgraded individually, whereas any number of beacon proxies can be upgraded atomically at the same time by upgrading the beacon that they point to. For more details on the different proxy patterns available, see the documentation for [Proxies](https://docs.openzeppelin.com/contracts/4.x/api/proxy).
+The plugins support the UUPS, transparent, and beacon proxy patterns. UUPS and transparent proxies are upgraded individually, whereas any number of beacon proxies can be upgraded atomically at the same time by upgrading the beacon that they point to. For more details on the different proxy patterns available, see the documentation for [Proxies](https://docs.openzeppelin.com/contracts/api/proxy).
 
-For UUPS and transparent proxies, use `deployProxy` and `upgradeProxy` as shown above. For beacon proxies, use `deployBeacon`, `deployBeaconProxy`, and `upgradeBeacon`. See the documentation for [Hardhat Upgrades](./packages/plugin-hardhat/README.md) and [Truffle Upgrades](./packages/plugin-truffle/README.md) for examples.
+For UUPS and transparent proxies, use `deployProxy` and `upgradeProxy`. For beacon proxies, use `deployBeacon`, `deployBeaconProxy`, and `upgradeBeacon`. See the documentation for [Hardhat Upgrades](./packages/plugin-hardhat/README.md) and [Foundry Upgrades](https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades) for examples.
 
 ## Managing ownership
 
 Transparent proxies have an _admin_ address which has the rights to upgrade them. By default, the admin is a [proxy admin contract](https://docs.openzeppelin.com/upgrades-plugins/faq#what-is-a-proxy-admin) deployed behind the scenes. Keep in mind that the _admin_ of a proxy can only upgrade it, but not interact with the implementation contract. Read [here](https://docs.openzeppelin.com/upgrades-plugins/proxies#transparent-proxies-and-function-clashes) for more info on this restriction.
 
-The proxy admin contract also defines an _owner_ address which has the rights to operate it. By default, this address is the `initialOwner` address used during deployment of the transparent proxy if provided, otherwise it is the externally owned account used during deployment. You can change the proxy admin owner by calling the `admin.transferProxyAdminOwnership` function in the plugin. Refer to each plugin documentation for more details on the `admin` functions.
+The proxy admin contract also defines an _owner_ address which has the rights to operate it. By default, the proxy admin's owner is the `initialOwner` address used during deployment of the transparent proxy if provided, otherwise it is the externally owned account used during deployment. You can change the proxy admin owner by calling the `admin.transferProxyAdminOwnership` function in the Hardhat plugin, or the `transferOwnership` function of the proxy admin contract if using Foundry.
+
+> [!WARNING]
+> Do not reuse an already deployed `ProxyAdmin`. Before `@openzeppelin/contracts` version 5.x, the address provided to transparent proxies was an `initialAdmin` as opposed to an `initialOwner` of a newly deployed `ProxyAdmin`. Reusing a `ProxyAdmin` will disable upgradeability in your contract.
 
-UUPS and beacon proxies do not use admin addresses. UUPS proxies rely on an [`_authorizeUpgrade`](https://docs.openzeppelin.com/contracts/4.x/api/proxy#UUPSUpgradeable-_authorizeUpgrade-address-) function to be overridden to include access restriction to the upgrade mechanism, whereas beacon proxies are upgradable only by the owner of their corresponding beacon.
+UUPS and beacon proxies do not use admin addresses. UUPS proxies rely on an [`_authorizeUpgrade`](https://docs.openzeppelin.com/contracts/api/proxy#UUPSUpgradeable-_authorizeUpgrade-address-) function to be overridden to include access restriction to the upgrade mechanism, whereas beacon proxies are upgradable only by the owner of their corresponding beacon.
 
-Once you have transferred the rights to upgrade a proxy or beacon to another address, you can still use your local setup to validate and deploy the implementation contract. The plugins include a `prepareUpgrade` function that will validate that the new implementation is upgrade-safe and compatible with the previous one, and deploy it using your local Ethereum account. You can then execute the upgrade itself from the admin or owner address. You can also use the `proposeUpgrade` function to automatically set up the upgrade in [Defender Admin](https://docs.openzeppelin.com/defender/admin).
+Once you have transferred the rights to upgrade a proxy or beacon to another address, you can still use your local setup to validate and deploy the implementation contract. The plugins include a `prepareUpgrade` function that will validate that the new implementation is upgrade-safe and compatible with the previous one, and deploy it using your local Ethereum account. You can then execute the upgrade itself from the admin or owner address. You can also use the `defender.proposeUpgrade` or `defender.proposeUpgradeWithApproval` functions to automatically set up the upgrade in [OpenZeppelin Defender](https://docs.openzeppelin.com/defender/).
 
 ## Community
 

assets/truffle.svg

@@ -1,13 +1,13 @@
 * xref:index.adoc[Overview]
 * xref:hardhat-upgrades.adoc[Using with Hardhat]
 ** xref:defender-deploy.adoc[OpenZeppelin Defender integration]
-* xref:truffle-upgrades.adoc[Using with Truffle]
+** xref:network-files.adoc[Network Files]
+* xref:foundry-upgrades.adoc[Using with Foundry]
 * xref:writing-upgradeable.adoc[Writing Upgradeable Contracts]
 * xref:proxies.adoc[Proxy Upgrade Pattern]
-* xref:network-files.adoc[Network Files]
 * xref:faq.adoc[Frequently Asked Questions]
 
 .API Reference
 * xref:api-hardhat-upgrades.adoc[Hardhat Upgrades]
-* xref:api-truffle-upgrades.adoc[Truffle Upgrades]
+* xref:api-foundry-upgrades.adoc[Foundry Upgrades]
 * xref:api-core.adoc[Upgrades Core & CLI]

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,3 @@
+= OpenZeppelin Foundry Upgrades API
+
+See function documentation in https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades/blob/main/src/Upgrades.sol[Upgrades.sol] from the https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades[OpenZeppelin Foundry Upgrades] repository for API reference.

docs/modules/ROOT/pages/api-foundry-upgrades.adoc

@@ -712,7 +712,7 @@ Silences all subsequent warnings about the use of unsafe flags. Prints a last wa
 [[verify]]
 == verify
 
-Extends https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-verify[hardhat-verify]'s `verify` task to completely verify a proxy on Etherscan.  This supports verifying proxy contracts that were deployed by the Hardhat Upgrades or Truffle Upgrades plugin.
+Extends https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-verify[hardhat-verify]'s `verify` task to completely verify a proxy on Etherscan.  This supports verifying proxy contracts that were deployed by the Hardhat Upgrades plugin.
 
 The arguments are the same as for hardhat-verify's `verify` task.  If the provided address is a proxy, this task will verify the proxy's implementation contract, the proxy itself and any proxy-related contracts, as well as link the proxy to the implementation contract's ABI on Etherscan.  If the provided address is not a proxy, the regular `verify` task from hardhat-verify will be run on the address instead.
 

docs/modules/ROOT/pages/api-hardhat-upgrades.adoc

@@ -210,13 +210,6 @@ Past versions of the plugins did not support upgradeable contracts that used cus
 
 Some users who have already deployed proxies with structs and/or enums and who need to upgrade those proxies may need to use the override flag `unsafeAllowCustomTypes` for their next upgrade, after which it will no longer be necessary. If the project contains the source code for the implementation currently in use by the proxy, the plugin will attempt to recover the metadata that it needs before the upgrade, falling back to the override flag if this is not possible.
 
-[[why-do-i-have-to-recompile-all-contracts-for-truffle]]
-== Why do I have to recompile all contracts for Truffle?
-
-Truffle artifacts (the JSON files in `build/contracts`) contain the AST (abstract syntax tree) for each of your contracts. Our plugin uses this information to validate that your contracts are <<what-does-it-mean-for-a-contract-to-be-upgrade-safe, upgrade safe>>.
-
-Truffle sometimes partially recompiles only the contracts that have changed. We will ask you to trigger a full recompilation either using `truffle compile --all` or deleting the `build/contracts` directory when this happens. The technical reason is that since Solidity does not produce deterministic ASTs, the plugins are unable to resolve references correctly if they are not from the same compiler run.
-
 [[how-to-rename]]
 == How can I rename a variable, or change its type?
 

docs/modules/ROOT/pages/faq.adoc

@@ -0,0 +1,3 @@
+= Using with Foundry
+
+See the https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades[OpenZeppelin Foundry Upgrades] repository for usage information.