Add bytecode verification doc by maurelian · Pull Request #291 · ethereum-optimism/design-docs

maurelian · 2025-06-09T20:35:13Z

A proposal for incorporating bytecode verification into our release process.

Add some polish

mds1 · 2025-06-10T18:11:14Z

+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


nit, could combine these two args?

Suggested change

op-deployer verify-bytecode --dangerously-use-remote-artifacts --artifacts-locator tag://op-contracts/vX.Y.Z

op-deployer verify-bytecode --dangerously-set-artifacts-locator tag://op-contracts/vX.Y.Z

I somewhat prefer it as is because --artifacts-locator already exists, so we're just adding a new simple boolean flag, rather than a flag that is kind of an alternative to an existing one.

mds1 · 2025-06-10T18:16:59Z

+
+The specific points that we should include the process are:
+
+1. Automated in superchain-registry CI (as discussed above).


Does this create a circular dependency, in that the monorepo depends on the superchain-registry and now the superchain-registry depends on the monorepo for op-deployer? i.e. how do we know this will work in practice?

More broadly, what value does the op-deployer wrapper add? I can instead imagine the superchain-registry CI just cloning the monorepo at the required commit/tag, then running the forge script VerifyOPCM.s.sol script in CI

Good questions which clarify the reason for the op-deployer wrapper:

op-deployer can be easily/quickly installed from a binary by downloading, so we don't actually introduce a circular dependency.

I expect it will be pretty slow to clone/check out the monorepo at a commit, build the contracts, then run the script.

Although there is a sense in which rebuilding is safer than relying on a download, in both cases the build is occurring on cloud infrastructure, so I don't think we get a ton of benefit from the rebuild. That's why it is important to have it run in at least step 2 here.

Co-authored-by: Matt Solomon <matt@mattsolomon.dev>

bitwiseguy · 2025-06-18T13:58:57Z

+By default, `op-deployer verify-bytecode` will use locally built 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:


This seems contradictory to the Problem Statement, which states:

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.

If the above statement is true, it seems the command should default to verifying bytecode against an op-contracts git tag + remote artifacts and the flag should be --dangerously-use-local-artifacts

In other words, which do we think is more dangerous: verifying bytecode against local or remote artifacts?

bitwiseguy · 2025-06-18T14:05:41Z

+Superchain-registry flag:
+
+```
+--superchain-registry <path/to/registry>


If this flag is passed, where are the addresses pulled from? Assuming we'd still need the following addresses:

upgrade-controller

superchain-config: from standard-versions-<network>.toml>

protocol-versions: from standard-versions-<network>.toml>

superchain-proxy-admin

bitwiseguy · 2025-06-18T14:06:59Z

+It is important to ensure that the bytecode verification process is run by multiple people and on
+multiple different machines.


Why is it important for multiple people to run this? What are the risks if only one person runs the verification?

bitwiseguy · 2025-06-18T14:13:10Z

+#### 1. Automated in superchain-registry CI (as discussed above).
+
+For each `$TAG` listed in `standard-versions-[mainnet|sepolia].toml`, we should run the following
+command:
+
+```
+op-deployer verify-bytecode \
+  --dangerously-use-remote-artifacts \
+  --artifacts-locator tag://$TAG \
+  --superchain-registry .
+```


Should this ci job only be triggered when the standard-versions-[mainnet|sepolia].toml files are modified?

Yes, that makes sense.

More detail:

scheduled job that looks at each tag in the SCR's standard-versions*.toml

uses tag locator to get artifacts

calculates checksum and artifacts hash

compares to those in standard.go

Ideally we begin storing these hashes in the SCR.

maurelian · 2025-06-18T20:06:51Z

+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 need a strategy for ensuring that VerifyOPCM remains complete, so that if a new contract is added to the system, that will be identified.

maurelian · 2025-06-18T20:13:39Z

+The flag `--dangerously-use-remote-artifacts` is intended to discourge the use of remote artifacts
+when running locally, while still enabling a fast mechanism to run in CI.


Ideally we want to be ensuring parity between:

the remote tagged artifact

the locally built artifact

the actual deployed contract.

We should consider parallelization so that we can have that property in CI.

worst case, have the local process be the more complete of the two.

maurelian · 2025-06-18T20:38:06Z

+#### 3. Additionally for consideration: run by signers during the upgrade process.
+
+The command used here would be the same as the one used in the previous step.


Optional for signers but documented how to run opd verify-bytecode

Need a process in ops repo CI to ensure that the opcm being used in the config.toml is the correct one for the upgrade tag.

maurelian · 2025-06-18T20:41:11Z

+
+## Risks & Uncertainties
+
+- Reliance on Etherscan APIs.


in order to remove this reliance, we need to get the initcode another way.
Can do that with binary search on create2 deployer calls.

maurelian · 2025-07-16T17:29:05Z

general note to add codehash verification, with regard to this comment.

maurelian marked this pull request as ready for review June 9, 2025 21:07

Add bytecode verification doc

a5c15cb

Add some polish

maurelian force-pushed the bc-ver branch from a6f3f30 to a5c15cb Compare June 10, 2025 16:26

mds1 reviewed Jun 10, 2025

View reviewed changes

Comment thread protocol/opcm-bytecode-verification.md Outdated

mds1 reviewed Jun 10, 2025

View reviewed changes

Comment thread protocol/opcm-bytecode-verification.md Outdated

mds1 reviewed Jun 10, 2025

View reviewed changes

Comment thread protocol/opcm-bytecode-verification.md

mds1 reviewed Jun 10, 2025

View reviewed changes

maurelian and others added 2 commits June 10, 2025 12:29

Apply suggestions from code review

10a57a0

Co-authored-by: Matt Solomon <matt@mattsolomon.dev>

Clarify process integration specifics

c1eefac

maurelian mentioned this pull request Jun 11, 2025

Bytecode Verification for L1 Contract Releases #292

Closed

bitwiseguy reviewed Jun 18, 2025

View reviewed changes

maurelian commented Jun 18, 2025

View reviewed changes

maurelian commented Jul 16, 2025

View reviewed changes

	op-deployer verify-bytecode --dangerously-use-remote-artifacts --artifacts-locator tag://op-contracts/vX.Y.Z
	op-deployer verify-bytecode --dangerously-set-artifacts-locator tag://op-contracts/vX.Y.Z


		The specific points that we should include the process are:

		1. Automated in superchain-registry CI (as discussed above).

		It is important to ensure that the bytecode verification process is run by multiple people and on
		multiple different machines.

		The flag `--dangerously-use-remote-artifacts` is intended to discourge the use of remote artifacts
		when running locally, while still enabling a fast mechanism to run in CI.

		#### 3. Additionally for consideration: run by signers during the upgrade process.

		The command used here would be the same as the one used in the previous step.

Conversation

maurelian commented Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bitwiseguy Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

maurelian commented Jun 9, 2025 •

edited

Loading

bitwiseguy Jun 18, 2025 •

edited

Loading