From 6a081386f4c972226a0182c1fdae10f2590fd0c1 Mon Sep 17 00:00:00 2001 From: Michael Amadi Date: Thu, 15 Jan 2026 17:24:45 +0100 Subject: [PATCH 1/6] Foundry Versioning Policy --- .../book/src/policies/foundry-upgrades.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 packages/contracts-bedrock/book/src/policies/foundry-upgrades.md diff --git a/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md b/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md new file mode 100644 index 0000000000000..c3817dce7e5cb --- /dev/null +++ b/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md @@ -0,0 +1,63 @@ +# Foundry Versioning Policy + +This document outlines the process for proposing and implementing Foundry version updates in the +OP Stack codebase. + +## Unified Foundry Version + +The OP Stack codebase maintains a single, unified Foundry version across all components. This ensures +consistency, simplifies maintenance, and reduces the risk of version-related issues. Foundry is a +critical dependency in our supply chain, and if compromised, it could result in draining the bridge. + +**Important**: New Foundry versions must not be introduced to any part of the codebase without +going through the formal version update proposal process outlined in this document. + +## Update Process + +1. **Minimum Delay Period**: A new Foundry version must be at least 1 month old before it can be + considered for adoption. +2. Only stable releases are recommended to be proposed for adoption. For upgrades to nightly builds, there must be a feature addition that improves the quality of our codebase considerably or a bug fix that addresses a non-trivial security vulnerability. +3. **Proposal Submission**: Before any Foundry version upgrades are made, a detailed proposal must + be submitted as a pull request to the [`ethereum-optimism/design-docs`][1] repository in a + `foundry/` subfolder, following the standardized format outlined below. This applies to the monorepo, superchain-ops, and any other repositories that use Foundry. +4. **Review and Approval**: A dedicated review panel will assess the proposal based on the + following criteria: + - Is the Foundry version at least 1 month old? + - Does the proposed upgrade provide clear value to the codebase? + - Do any new features or bug fixes pose an unnecessary risk to the codebase? + - Are there any security vulnerabilities addressed by this version? +5. **Implementation**: If the proposal receives unanimous approval from the review panel, the + Foundry version upgrade will be implemented across the entire OP Stack codebase, including: + - The monorepo (`mise.toml` and `op-deployer/pkg/deployer/forge/version.json`) + - The `superchain-ops` repository + +## Proposal Submission Guidelines + +To submit a Foundry version upgrade proposal, create a new pull request to the +[`ethereum-optimism/design-docs`][1] repository, adding a new file in the `foundry/` subfolder. +Please use a format similar to the [Foundry update proposal format][2], adapted for Foundry. +Ensure that all sections are filled out comprehensively. Incomplete proposals may be delayed or +rejected. + +## Review Process + +The review panel will evaluate each proposal based on the criteria mentioned in the "Review and +Approval" section above. They may request additional information or clarifications if needed. + +## Implementation + +If approved, the Foundry version upgrade will be implemented across the entire OP Stack codebase. +This process will be managed by the development team to ensure consistency and minimize potential +issues. The upgrade will apply to all components simultaneously, including: + +- `mise.toml`: Update `forge`, `cast`, and `anvil` version entries +- `op-deployer/pkg/deployer/forge/version.json`: Update the `forge` version and corresponding + checksums for all supported platforms +- `superchain-ops` repository: Update Foundry version configuration + +All version updates must be synchronized across these locations to maintain consistency. + + + +[1]: https://github.com/ethereum-optimism/design-docs +[2]: https://github.com/ethereum-optimism/design-docs/tree/main/assets/foundry-update-template.md From efcf33943d4f0171acb21adb731afc4295993d20 Mon Sep 17 00:00:00 2001 From: Michael Amadi Date: Thu, 15 Jan 2026 19:43:33 +0100 Subject: [PATCH 2/6] mods --- .../book/src/policies/foundry-upgrades.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md b/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md index c3817dce7e5cb..b9d88b9623b0e 100644 --- a/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md +++ b/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md @@ -14,22 +14,24 @@ going through the formal version update proposal process outlined in this docume ## Update Process -1. **Minimum Delay Period**: A new Foundry version must be at least 1 month old before it can be +1. **Minimum Delay Period**: A new Foundry version must be at least 3 month old before it can be considered for adoption. -2. Only stable releases are recommended to be proposed for adoption. For upgrades to nightly builds, there must be a feature addition that improves the quality of our codebase considerably or a bug fix that addresses a non-trivial security vulnerability. -3. **Proposal Submission**: Before any Foundry version upgrades are made, a detailed proposal must +2. Only stable releases are recommended to be proposed for adoption. +3. Nightly builds must only be considered for adoption if it includes a bug fix that addresses a non-trivial security vulnerability. This path does not need to follow the 3 month delay period. +4. **Proposal Submission**: Before any Foundry version upgrades are made, a detailed proposal must be submitted as a pull request to the [`ethereum-optimism/design-docs`][1] repository in a `foundry/` subfolder, following the standardized format outlined below. This applies to the monorepo, superchain-ops, and any other repositories that use Foundry. -4. **Review and Approval**: A dedicated review panel will assess the proposal based on the +5. **Review and Approval**: A dedicated review panel that must consist of **at least 2 members of the security team** will assess the proposal based on the following criteria: - - Is the Foundry version at least 1 month old? + - Is the Foundry version at least 3 month old? - Does the proposed upgrade provide clear value to the codebase? - Do any new features or bug fixes pose an unnecessary risk to the codebase? - Are there any security vulnerabilities addressed by this version? -5. **Implementation**: If the proposal receives unanimous approval from the review panel, the +6. **Implementation**: If the proposal receives unanimous approval from the review panel, the Foundry version upgrade will be implemented across the entire OP Stack codebase, including: - The monorepo (`mise.toml` and `op-deployer/pkg/deployer/forge/version.json`) - The `superchain-ops` repository +7. The PR that implements the bump MUST include a reference to the approved, merged design document that approves that foundry version for usage. ## Proposal Submission Guidelines From fabab2fdd92cec2e63038cd0ec57f65467aa0f72 Mon Sep 17 00:00:00 2001 From: Michael Amadi Date: Fri, 16 Jan 2026 16:03:46 +0100 Subject: [PATCH 3/6] Update packages/contracts-bedrock/book/src/policies/foundry-upgrades.md Co-authored-by: Matt Solomon --- .../contracts-bedrock/book/src/policies/foundry-upgrades.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md b/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md index b9d88b9623b0e..e424f8e68ecdb 100644 --- a/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md +++ b/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md @@ -37,7 +37,7 @@ going through the formal version update proposal process outlined in this docume To submit a Foundry version upgrade proposal, create a new pull request to the [`ethereum-optimism/design-docs`][1] repository, adding a new file in the `foundry/` subfolder. -Please use a format similar to the [Foundry update proposal format][2], adapted for Foundry. +Please use the [Foundry update proposal format][2]. Ensure that all sections are filled out comprehensively. Incomplete proposals may be delayed or rejected. From fd6ce5e53b5c0e75ec473d9e3cec0e3855b48dc5 Mon Sep 17 00:00:00 2001 From: Michael Amadi Date: Fri, 16 Jan 2026 16:05:58 +0100 Subject: [PATCH 4/6] Update packages/contracts-bedrock/book/src/policies/foundry-upgrades.md Co-authored-by: Matt Solomon --- .../contracts-bedrock/book/src/policies/foundry-upgrades.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md b/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md index e424f8e68ecdb..37e7756a088d5 100644 --- a/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md +++ b/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md @@ -7,7 +7,7 @@ OP Stack codebase. The OP Stack codebase maintains a single, unified Foundry version across all components. This ensures consistency, simplifies maintenance, and reduces the risk of version-related issues. Foundry is a -critical dependency in our supply chain, and if compromised, it could result in draining the bridge. +critical dependency in our supply chain, and if compromised can have severe consequences. **Important**: New Foundry versions must not be introduced to any part of the codebase without going through the formal version update proposal process outlined in this document. From 1504272326324786f7da2bae186d50e7f47ef9fa Mon Sep 17 00:00:00 2001 From: Michael Amadi Date: Fri, 16 Jan 2026 16:52:40 +0100 Subject: [PATCH 5/6] mods --- .../contracts-bedrock/book/src/policies/foundry-upgrades.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md b/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md index 37e7756a088d5..545de8544c329 100644 --- a/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md +++ b/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md @@ -15,7 +15,7 @@ going through the formal version update proposal process outlined in this docume ## Update Process 1. **Minimum Delay Period**: A new Foundry version must be at least 3 month old before it can be - considered for adoption. + considered for adoption. 3 Months is a good minimum delay period to allow for the community to use the new version and for any security vulnerabilities to be discovered and addressed. 2. Only stable releases are recommended to be proposed for adoption. 3. Nightly builds must only be considered for adoption if it includes a bug fix that addresses a non-trivial security vulnerability. This path does not need to follow the 3 month delay period. 4. **Proposal Submission**: Before any Foundry version upgrades are made, a detailed proposal must @@ -49,7 +49,7 @@ Approval" section above. They may request additional information or clarificatio ## Implementation If approved, the Foundry version upgrade will be implemented across the entire OP Stack codebase. -This process will be managed by the development team to ensure consistency and minimize potential +This process will be managed by the person who submitted the proposal to ensure consistency and minimize potential issues. The upgrade will apply to all components simultaneously, including: - `mise.toml`: Update `forge`, `cast`, and `anvil` version entries From b9a9ca5b79bea5fe67ebfa028fbd099fd77130e2 Mon Sep 17 00:00:00 2001 From: Michael Amadi Date: Mon, 19 Jan 2026 11:54:52 +0100 Subject: [PATCH 6/6] Update packages/contracts-bedrock/book/src/policies/foundry-upgrades.md Co-authored-by: Matt Solomon --- .../contracts-bedrock/book/src/policies/foundry-upgrades.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md b/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md index 545de8544c329..0d5e03887ffea 100644 --- a/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md +++ b/packages/contracts-bedrock/book/src/policies/foundry-upgrades.md @@ -17,7 +17,7 @@ going through the formal version update proposal process outlined in this docume 1. **Minimum Delay Period**: A new Foundry version must be at least 3 month old before it can be considered for adoption. 3 Months is a good minimum delay period to allow for the community to use the new version and for any security vulnerabilities to be discovered and addressed. 2. Only stable releases are recommended to be proposed for adoption. -3. Nightly builds must only be considered for adoption if it includes a bug fix that addresses a non-trivial security vulnerability. This path does not need to follow the 3 month delay period. +3. Nightly builds must only be considered for adoption if it includes a bug fix that addresses a non-trivial security vulnerability. This path does not need to follow the 3 month delay period, but must fill out the `notable bug fixes` section with rationale for why a nightly release is required. 4. **Proposal Submission**: Before any Foundry version upgrades are made, a detailed proposal must be submitted as a pull request to the [`ethereum-optimism/design-docs`][1] repository in a `foundry/` subfolder, following the standardized format outlined below. This applies to the monorepo, superchain-ops, and any other repositories that use Foundry.