Add bytecode verification doc

Author: maurelian

protocol/opcm-bytecode-verification.md

@@ -0,0 +1,124 @@
+# OPCM Bytecode Verification: Design Doc
+
+
+|                    |            |
+| -------------------- | ------------ |
+| Author             | Maurelian  |
+| Created at         | 2025-06-04 |
+| Initial Reviewers  | TBD        |
+| Need Approval From | TBD        |
+| Status             | Draft      |
+
+## Purpose
+
+Ensure that the contracts referenced in `OPContractsManager` (OPCM) are verifiably built from trusted source code by introducing a bytecode verification step into the release process.
+
+## Summary
+
+We propose integrating the `VerifyOPCM.s.sol` Foundry script into the release process via `op-deployer` to validate that deployed contract bytecode matches locally built artifacts. This prevents accidental or malicious mismatches and establishes trust in deployments originating from a known commit. The step will be automated in CI, and become part of the documented SDLC.
+
+## Problem Statement + Context
+
+Currently, there is no enforced mechanism to ensure that the OPCM used in an upgrade is built
+from a trusted commit, which should be one labelled as an `op-contracts/vX.Y.Z` tag, and approved
+by governance.
+
+This creates a risk of human error or maliciousness leading to an upgrade performed by an incorrect
+version of the OPCM (or the implementation contracts it sets). It also presents a risk of a failed upgrade
+resulting from a misconfigured OPCM (ie. if any [constructor vars](https://github.com/ethereum-optimism/optimism/blob/a10fd5259a3af9a465955b035e16f516327d51d5/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L266-L269) are set incorrectly).
+
+We want to eliminate this risk by automating the [Contract's Release Verification](https://www.notion.so/oplabs/Contracts-Release-Checklist-1f8f153ee162805e8236f022ebb8c868?source=copy_linkhttps:/) process, making it
+easy to demonstrate that an OPCM at a given address corresponds to a trusted commit.
+
+The solution should be:
+
+- contained within the release commit in the monorepo
+- easily runnable locally with a single command accepting only an RPC URL and the address of the OPCM
+- runnable in CI in the `superchain-registry` repo
+- incorporated into the upgrade process in a way that ensures it is run by multiple people
+
+## Proposed Solution
+
+### Bytecode verification against the local source
+
+A new command should be added to `op-deployer`.
+
+```
+op-deployer verify-bytecode <opcm-address>
+
+```
+
+This command will invoke the `VerifyOPCM.s.sol` script's [default entrypoint](https://github.com/ethereum-optimism/optimism/blob/158e990b76a85acbb018577bd4079190b2d97281/packages/contracts-bedrock/scripts/deploy/VerifyOPCM.s.sol#L126-L129) to verify the OPCM.
+
+```
+op-deployer verify-bytecode --single-contract <contract-name> <contract-address>
+```
+
+This command will invoke the `VerifyOPCM.s.sol` script's [runSingle entrypoint](https://github.com/ethereum-optimism/optimism/blob/158e990b76a85acbb018577bd4079190b2d97281/packages/contracts-bedrock/scripts/deploy/VerifyOPCM.s.sol#L135) in order to verify any contracts involved in the upgrade which are not included in the OPCM (ie.
+the new `DeputyPauseModule` introduced in upgrade 16.
+
+### Artifacts source
+
+By default, `op-deployer verify-bytecode` will use locally build forge-artifacts to check bytecode.
+In order to facilitate quickly running in CI, without having to checkout and rebuild different commits, the command will also accept a tag locator, with the following invocation:
+
+```
+op-deployer verify-bytecode --dangerously-use-remote-artifacts --artifacts-locator tag://op-contracts/vX.Y.Z
+
+```
+
+The flag `--dangerously-use-remote-artifacts` is intended to discourge the use of remote artifacts when running locally.
+
+### OPCM config verification
+
+Both of the commands above will accept the following arguments to confirm the configuration of
+
+```
+--upgrade-controller 0x... \
+  --superchain-config 0x... \
+  --protocol-versions 0x... \
+  --superchain-proxy-admin 0x...
+```
+
+###
+
+### Integration points
+
+This script will:
+
+- Build contract artifacts at the trusted commit.
+- Retrieve deployed bytecode via the OPCM.
+- Compare local vs deployed bytecode, including support for implementation, blueprint, and linked contracts.
+- Generate a verification artifact (e.g. JSON) that is checked into the monorepo and diffed in code review.
+
+This step will be:
+
+- Automated in CI (run in SCR or release-management repo).
+- Expected to be verified/redundantly run by multiple reviewers.
+
+### Resource Usage
+
+- Minimal: Only requires compilation and comparison of bytecode.
+- Optional Etherscan calls for constructor bytecode fetches (bounded network cost).
+
+### Single Point of Failure and Multi Client Considerations
+
+- No direct impact on clients like `op-geth` or `op-reth`.
+- Ensures that bytecode is consistent regardless of which client or deployer is used.
+
+## Impact on Developer Experience
+
+- No impact on app developers.
+- Protocol developers and release managers will have one additional verification step that is largely automated.
+
+## Alternatives Considered
+
+- A new op-deployer command. This approach would need to download artifacts and thus does not meet
+  the requirement of building locally.
+
+## Risks & Uncertainties
+
+- Build non-determinism could cause false negatives.
+- Reliance on Etherscan APIs (when used).
+- Risk of CI misconfiguration allowing bypass of the check.
+- Trust assumption that the build system and commit used for verification are secure.