{"id":29089606,"url":"https://github.com/openzeppelin/openzeppelin-foundry-upgrades","last_synced_at":"2025-06-28T04:04:13.308Z","repository":{"id":204555923,"uuid":"706388323","full_name":"OpenZeppelin/openzeppelin-foundry-upgrades","owner":"OpenZeppelin","description":"Foundry library for deploying and managing upgradeable contracts","archived":false,"fork":false,"pushed_at":"2025-05-12T21:22:44.000Z","size":407,"stargazers_count":217,"open_issues_count":9,"forks_count":40,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-06-13T09:44:41.364Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenZeppelin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-17T21:11:02.000Z","updated_at":"2025-05-31T07:31:37.000Z","dependencies_parsed_at":"2024-02-16T23:22:31.613Z","dependency_job_id":"c4497e09-ad2e-413c-a231-9eabf984e152","html_url":"https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades","commit_stats":null,"previous_names":["openzeppelin/openzeppelin-foundry-upgrades"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/OpenZeppelin/openzeppelin-foundry-upgrades","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fopenzeppelin-foundry-upgrades","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fopenzeppelin-foundry-upgrades/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fopenzeppelin-foundry-upgrades/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fopenzeppelin-foundry-upgrades/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenZeppelin","download_url":"https://codeload.github.com/OpenZeppelin/openzeppelin-foundry-upgrades/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fopenzeppelin-foundry-upgrades/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262371684,"owners_count":23300595,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-28T04:04:12.247Z","updated_at":"2025-06-28T04:04:13.282Z","avatar_url":"https://github.com/OpenZeppelin.png","language":"Solidity","readme":"# OpenZeppelin Foundry Upgrades\n\n[![Docs](https://img.shields.io/badge/docs-%F0%9F%93%84-blue)](https://docs.openzeppelin.com/upgrades-plugins/foundry-upgrades)\n\nFoundry library for deploying and managing upgradeable contracts, which includes upgrade safety validations.\n\n## Installing\n\nFollow one of the sections below depending on which version of OpenZeppelin Contracts you are using. OpenZeppelin Contracts v5 is required for new deployments.\n\n### Using OpenZeppelin Contracts v5\n\nRun these commands:\n```console\nforge install foundry-rs/forge-std\nforge install OpenZeppelin/openzeppelin-foundry-upgrades\nforge install OpenZeppelin/openzeppelin-contracts-upgradeable\n```\n\nSet the following in `remappings.txt`, replacing any previous definitions of these remappings:\n```\n@openzeppelin/contracts/=lib/openzeppelin-contracts-upgradeable/lib/openzeppelin-contracts/contracts/\n@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts/\n```\n\n\u003e **Note**\n\u003e The above remappings mean that both `@openzeppelin/contracts/` (including proxy contracts deployed by this library) and `@openzeppelin/contracts-upgradeable/` come from your installation of the `openzeppelin-contracts-upgradeable` submodule and its subdirectories, which includes its own transitive copy of `openzeppelin-contracts` of the same release version number. This format is needed for Etherscan verification to work. Particularly, any copies of `openzeppelin-contracts` that you install separately are NOT used.\n\n### Using OpenZeppelin Contracts v4\n\nRun these commands, replacing `v4.9.6` with the specific version of OpenZeppelin Contracts that you are using:\n```console\nforge install foundry-rs/forge-std\nforge install OpenZeppelin/openzeppelin-foundry-upgrades\nforge install OpenZeppelin/openzeppelin-contracts@v4.9.6\nforge install OpenZeppelin/openzeppelin-contracts-upgradeable@v4.9.6\n```\n\nSet the following in `remappings.txt`:\n```\n@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/\n@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts/\n```\n\n\u003e **Note**\n\u003e Use [LegacyUpgrades.sol](src/LegacyUpgrades.sol) instead of `Upgrades.sol` to upgrade existing deployments that were created with OpenZeppelin Contracts v4.\n\n### Optional: Alternative installation methods\n\n#### NPM\n\nFollow the steps above, but instead of running `forge install OpenZeppelin/openzeppelin-foundry-upgrades`, use this command instead:\n```\nnpm install @openzeppelin/foundry-upgrades\n```\n\nThen add the following additional line to `remappings.txt`, in addition to the ones described above:\n```\nopenzeppelin-foundry-upgrades/=node_modules/@openzeppelin/foundry-upgrades/src/\n```\n\n#### Soldeer\n\nFollow the steps above, but instead of running `forge install OpenZeppelin/openzeppelin-foundry-upgrades`, use one of the install commands described in https://soldeer.xyz/project/openzeppelin-foundry-upgrades\n\nThen add the following additional line to `remappings.txt`, in addition to the ones described above (replace `0.3.6` with the version of the plugin that you installed):\n```\nopenzeppelin-foundry-upgrades/=dependencies/openzeppelin-foundry-upgrades-0.3.6/src/\n```\n\n## OpenZeppelin Defender integration\n\nSee [DEFENDER.md](DEFENDER.md)\n\n## Foundry Requirements\n\nThis library requires [forge-std](https://github.com/foundry-rs/forge-std) version 1.9.5 or higher.\n\n## Before Running\n\nThis library uses the [OpenZeppelin Upgrades CLI](https://docs.openzeppelin.com/upgrades-plugins/api-core) for upgrade safety validations, which are run by default during deployments and upgrades.\n\nIf you want to be able to run upgrade safety validations, the following are needed:\n1. Install [Node.js](https://nodejs.org/).\n2. Configure your `foundry.toml` to enable ffi, ast, build info and storage layout:\n```toml\n[profile.default]\nffi = true\nast = true\nbuild_info = true\nextra_output = [\"storageLayout\"]\n```\n3. If you are upgrading your contract from a previous version, add the `@custom:oz-upgrades-from \u003creference\u003e` annotation to the new version of your contract according to [Define Reference Contracts](https://docs.openzeppelin.com/upgrades-plugins/api-core#define-reference-contracts) or specify the `referenceContract` option when calling the library's functions.\n4. Run `forge clean` before running your Foundry script or tests, or include the `--force` option when running `forge script` or `forge test`.\n\nIf you do not want to run upgrade safety validations, you can skip the above steps and use the [`unsafeSkipAllChecks` option](src/Options.sol) when calling the `Upgrades` library's functions, or use the `UnsafeUpgrades` library instead. Note that these are dangerous options meant to be used as a last resort.\n\n### Optional: Custom output directory\n\nBy default, this library assumes your Foundry output directory is set to \"out\".\n\nIf you want to use a custom output directory, set it in your `foundry.toml` and provide read permissions for the directory. For example (replace `my-output-dir` with the directory that you want to use):\n```toml\n[profile.default]\nout = \"my-output-dir\"\nfs_permissions = [{ access = \"read\", path = \"my-output-dir\" }]\n```\nThen in a `.env` at your project root, set the `FOUNDRY_OUT` environment variable to match the custom output directory, for example:\n```env\nFOUNDRY_OUT=my-output-dir\n```\n\n### Windows environments\n\nIf you are using Windows, set the `OPENZEPPELIN_BASH_PATH` environment variable to the fully qualified path of the `bash` executable.\nFor 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):\n```env\nOPENZEPPELIN_BASH_PATH=\"C:/Program Files/Git/bin/bash\"\n```\n\n## Usage\n\nDepending on which major version of OpenZeppelin Contracts you are using, and whether you want to run upgrade safety validations and/or use OpenZeppelin Defender, use the table below to determine which library to import:\n\n|     | OpenZeppelin Contracts v5 | OpenZeppelin Contracts v4 |\n| --- | --- | --- |\n| **Runs validations, supports Defender** | `import {Upgrades} from \"openzeppelin-foundry-upgrades/Upgrades.sol\";` | `import {Upgrades} from \"openzeppelin-foundry-upgrades/LegacyUpgrades.sol\";` |\n| **No validations, does not support Defender** | `import {UnsafeUpgrades} from \"openzeppelin-foundry-upgrades/Upgrades.sol\";` | `import {UnsafeUpgrades} from \"openzeppelin-foundry-upgrades/LegacyUpgrades.sol\";` |\n\n\nImport one of the above libraries in your Foundry scripts or tests, for example:\n```solidity\nimport {Upgrades} from \"openzeppelin-foundry-upgrades/Upgrades.sol\";\n```\n\nAlso import the implementation contract that you want to validate, deploy, or upgrade to, for example:\n```solidity\nimport {MyToken} from \"src/MyToken.sol\";\n```\n\nThen call functions from the imported library to run validations, deployments, or upgrades.\n\n## Examples\n\nThe following examples assume you are using OpenZeppelin Contracts v5 and want to run upgrade safety validations.\n\n### Deploy a proxy\n\nDeploy a UUPS proxy:\n```solidity\naddress proxy = Upgrades.deployUUPSProxy(\n    \"MyContract.sol\",\n    abi.encodeCall(MyContract.initialize, (\"arguments for the initialize function\"))\n);\n```\n\nDeploy a transparent proxy:\n```solidity\naddress proxy = Upgrades.deployTransparentProxy(\n    \"MyContract.sol\",\n    INITIAL_OWNER_ADDRESS_FOR_PROXY_ADMIN,\n    abi.encodeCall(MyContract.initialize, (\"arguments for the initialize function\"))\n);\n```\n\nDeploy an upgradeable beacon and a beacon proxy:\n```solidity\naddress beacon = Upgrades.deployBeacon(\"MyContract.sol\", INITIAL_OWNER_ADDRESS_FOR_BEACON);\n\naddress proxy = Upgrades.deployBeaconProxy(\n    beacon,\n    abi.encodeCall(MyContract.initialize, (\"arguments for the initialize function\"))\n);\n```\n\n### Use your contract\n\nCall your contract's functions as normal, but remember to always use the proxy address:\n```solidity\nMyContract instance = MyContract(proxy);\ninstance.myFunction();\n```\n\n### Upgrade a proxy or beacon\n\nUpgrade a transparent or UUPS proxy and call an arbitrary function (such as a reinitializer) during the upgrade process:\n```solidity\nUpgrades.upgradeProxy(\n    transparentProxy,\n    \"MyContractV2.sol\",\n    abi.encodeCall(MyContractV2.foo, (\"arguments for foo\"))\n);\n```\n\nUpgrade a transparent or UUPS proxy without calling any additional function:\n```solidity\nUpgrades.upgradeProxy(\n    transparentProxy,\n    \"MyContractV2.sol\",\n    \"\"\n);\n```\n\nUpgrade a beacon:\n```solidity\nUpgrades.upgradeBeacon(beacon, \"MyContractV2.sol\");\n```\n\n\u003e **Warning**\n\u003e When upgrading a proxy or beacon, ensure that the new contract either has its `@custom:oz-upgrades-from \u003creference\u003e` annotation set to the current implementation contract used by the proxy or beacon, or set it with the `referenceContract` option, for example:\n\u003e ```solidity\n\u003e Options memory opts;\n\u003e opts.referenceContract = \"MyContractV1.sol\";\n\u003e Upgrades.upgradeProxy(proxy, \"MyContractV2.sol\", \"\", opts);\n\u003e // or Upgrades.upgradeBeacon(beacon, \"MyContractV2.sol\", opts);\n\u003e ```\n\n\u003e **Tip**\n\u003e If possible, keep the old version of the implementation contract's source code somewhere in your project to use as a reference as above. This requires the new version to be in a different directory, Solidity file, or using a different contract name. Otherwise, if you want to use the same directory and name for the new version, keep the build info directory from the previous deployment (or build it from an older branch of your project repository) and reference it as follows:\n\u003e ```solidity\n\u003e Options memory opts;\n\u003e opts.referenceBuildInfoDir = \"/old-builds/build-info-v1\";\n\u003e opts.referenceContract = \"build-info-v1:MyContract\";\n\u003e Upgrades.upgradeProxy(proxy, \"MyContract.sol\", \"\", opts);\n\u003e // or Upgrades.upgradeBeacon(beacon, \"MyContract.sol\", opts);\n\u003e ```\n\n## Coverage Testing\n\nTo enable code coverage reports with `forge coverage`, use the following deployment pattern in your tests: instantiate your implementation contracts directly and use the `UnsafeUpgrades` library. For example:\n```solidity\naddress implementation = address(new MyContract());\naddress proxy = UnsafeUpgrades.deployUUPSProxy(\n    implementation,\n    abi.encodeCall(MyContract.initialize, (\"arguments for the initialize function\"))\n);\n```\n\n\u003e **Warning**\n`UnsafeUpgrades` is not recommended for use in Forge scripts. It does not validate whether your contracts are upgrade safe or whether new implementations are compatible with previous ones. Ensure you run validations before any actual deployments or upgrades, such as by using the `Upgrades` library in scripts.\n\n## Deploying and Verifying\n\nRun your script with `forge script` to broadcast and deploy. See Foundry's [Solidity Scripting](https://book.getfoundry.sh/guides/scripting-with-solidity) guide.\n\n\u003e **Important**\n\u003e Include the `--sender \u003cADDRESS\u003e` flag for the `forge script` command when performing upgrades, specifying an address that owns the proxy or proxy admin. Otherwise, `OwnableUnauthorizedAccount` errors will occur.\n\n\u003e **Note**\n\u003e Include the `--verify` flag for the `forge script` command if you want to verify source code such as on Etherscan. This will verify your implementation contracts along with any proxy contracts as part of the deployment.\n\n## API\n\nSee [Foundry Upgrades API](https://docs.openzeppelin.com/upgrades-plugins/api-foundry-upgrades) for the full API documentation.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzeppelin%2Fopenzeppelin-foundry-upgrades","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenzeppelin%2Fopenzeppelin-foundry-upgrades","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzeppelin%2Fopenzeppelin-foundry-upgrades/lists"}