Skip to content

op-deployer: Add design doc on using Forge #325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+71 −0
Open

op-deployer: Add design doc on using Forge #325

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions protocol/op-deployer-forge-engine.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Use Forge as the EVM for OP Deployer

## Summary

We propose switching out the Go-based EVM inside OP Deployer for a wrapper around Forge. This would reduce our
maintenance burden and allow us to take advantage of new Forge features without requiring us to reimplement them.

## Problem Statement + Context

OP Deployer was developed on top of a Golang-based EVM. This allows OP Deployer to execute Forge scripts and
simulate transactions prior to executing them like Forge does. Now that OP Deployer has been in production for over
a year, we're running into several issues with this approach:

1. **Difficulty debugging.** Rather than outputting a trace of the error, OP Deployer simply panics with
"revision ID 1 cannot be reverted." Users must then parse through the logs to determine the cause of the error.
2. **Incomplete featureset compared to Forge.** OP Deployer is often compared to Forge, since both deploy contracts.
Therefore, users perceive OP Deployer as incomplete from a feature perspective. For example, OP Deployer does not
support verifying all the contracts it can deploy, and the contracts it _does_ support can only be verified on
Etherscan.
3. **Maintenance burden.** The Golang EVM is a significant maintenance burden. Every new cheatcode in Forge must be
reimplemented in Go. Additionally, we must maintain a "bridge" to allow Golang to call into Solidity scripts.
This is a lot of work that provides no user benefit since the Golang EVM is simply a backend that allows contracts to
be deployed. This is table stakes for a deployment tool, and is much better solved in Forge.

We originally adopted the Golang solution because we wanted to avoid adding a dependency on Forge. However, there
are many ways around this that do not incur the maintenance burdens described above.

## Proposed Solution
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tactically, we could start by shelling out to forge for contract verification. That is a nice, isolated feature/cli-command. That would help us setup the forge invocation framework. Then we could extend it to invoke our solidity scripts via forge instead of via our golang evm code.


We propose switching all contract calls in OP Deployer to use Forge instead of the Golang EVM. OP Deployer would
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would this allow us to delete some Golang evm code that was previously used by op-deployer? Or is that same code used elsewhere (e.g. in-memory go acceptance tests and one-click deployments?)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can delete all of the Golang EVM code.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❤️

essentially become a thin, stateful wrapper around Forge. Think of it like an installer for our contracts. We've
outlined some implementation details of this approach below.

### Getting Forge

OP Deployer will autodetect Forge based on the following heuristics:

1. If Forge is already on the user's machine, and it is a supported version, use it.
2. Otherwise, download a pinned version of Forge and use that.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this check/download happen as part of the just build recipe for op-deployer, or as part of the op-deployer runtime?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking at runtime.


### Calling Forge

For now, OP Deployer will simply call the Forge binary as a CLI tool. To communicate with Forge, OP Deployer will
parse Forge's standard output stream. This will require updating some of our smart contracts to output JSON. We may
adopt solutions like calling Forge as a library via FFI, but that is currently out of scope.

Forge's output will otherwise be streamed directly to the user's terminal so that they can see the progress of the
deployment.

## Impact on Developer Experience

This change should make maintaining OP Deployer much easier:

1. The Platforms team would no longer need to maintain the Golang EVM.
2. Changes to Forge can be immediately adopted.
3. Smart contract devs don't need to worry about how their contracts will be called from Golang anymore.
4. Error messages and contract deployment output will be much better.

Users running OP Deployer in a container will either need to use a container that contains Forge, or allow that
container to download the Forge binary. We can provide a prebuilt container with Forge installed to avoid this issue.

## Alternatives Considered

### Continue Maintaining the Golang EVM

This is our default path. However, we're getting asked to build things like Blockscout contract verification, which
would be entirely duplicative of what Forge already does really well.

## Risks & Uncertainties

None really. This is a pretty straightforward change that reduces risk overall.
Comment on lines +69 to +71
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am definitely supportive of this. One flag is that we (and everyone else in the ecosystem) increasingly rely heavily on foundry, making it a good target for attackers, similar to the Safe UI. Out of scope for this design doc, but we should consider implementing a foundry update policy similar to our solidity upgrade policy to mitigate this risk

Copy link

@bitwiseguy bitwiseguy Aug 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I think the benefits far outweigh the negatives in this proposal, its probably still good to call out some of the risks/uncertainties:

  • parsing forge std output - not all forge commands provide the option to output results to json, therefore we will have to parse std output in some cases. Typically std output is not considered a reliable api, therefore it is more likely to change. This means we may take on the maintenance burden of adjusting to breaking changes to std output. This can be mitigated by pinning to known forge versions though, and the maintenance is likely much less effort than having to reimplement entire features

  • cross-platform compatibility complexity: go builds automatically handle cross-platform compilation for the go binary, but if we add forge binary as a dependency, then we must also ensure the forge binary supports the same OS the go binary is built for - do we want to embed the forge binary in the go binary, or treat forge as an external dependency? Do we want to leverage mise to help us manage the forge version so its consistent with the version used in other parts of the monorepo (maybe this would help reduce supply-chain risk if the versions managed by mise go through any sort of security check)? Or do we want op-deployer's forge version to be independent?

  • forge script works within the context of a full forge project: will it work with just the embedded forge-artifacts tar file that is currently embedded within op-deployer? Since we have the use_literal_content = "true" (ref) setting within our foundry.toml file, the solidity source code (including dependencies) is included in each forge-artifact. Hopefully this gives forge script everything it needs, but we should confirm

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • See the note in the doc - we'll need to modify contracts to output JSON (or some other parseable output) so that we don't need to parse the Forge output.
  • You're correct, we'll need to pull in the right binary based on the user's architecture/OS. This can happen at runtime and doesn't need mise.
  • It should work - forge has a --no-compile option that we can use.