Skip to main content
OP Deployer calls into precompiled contract artifacts. To make this work, OP Deployer uses artifacts locators to point to the location of contract artifacts. While locators are nothing more than URLs, they do encode some additional behaviors which are described here.

Locator Types

Locators can be one of three types. tag:// locators from older releases are no longer accepted.
  • embedded, the default, which uses the contract artifacts compiled into the OP Deployer binary. Each OP Deployer release embeds the artifacts of the contracts release it supports, so nothing is downloaded or verified at run time.
    • ex: embedded
  • https:// locators, which point to a gzip- or zstd-compressed tarball of a built Forge project. HTTP locators are cached on disk to avoid repeated downloads.
    • ex: https://<url-to-remote-forge-artifacts>
  • file:// locators, which point to a built Forge project on local disk, or its forge-artifacts subdirectory.
    • ex: file://<path-to-repo-root>/packages/contracts-bedrock/forge-artifacts
    • OP Deployer runs forge on a copy of the compiled forge project without the Solidity AST of the artifacts, which takes a fraction of the memory. The copies are in bundles/ of the cache directory, --cache-dir or ~/.op-deployer/cache by default: OP Deployer copies each build once and keeps the copies of the last few builds that it used. A run uses the build that it found at its start: a rebuild of the contracts during the run is not seen.
OP Deployer runs the deploy scripts of the artifacts with forge, and it never compiles them. So the artifacts must come from the contracts release of the same OP Deployer release, compiled with their compile cache. OP Deployer stops with an error if a script has no runWithBytes entrypoint, or if forge would have to compile. The default locator, embedded, uses the artifacts that OP Deployer was built with. To build artifacts for a file:// locator, run just build-no-tests in packages/contracts-bedrock. Artifacts-only directories and archives are not supported. Keep the complete built project, including foundry.toml, the Solidity sources and libraries, cache/solidity-files-cache.json, and forge-artifacts. For HTTP locators, these must be at the archive root, not inside an additional enclosing directory. To migrate an artifacts-only setup, use embedded or rebuild the matching contracts release and point the file:// locator at the full project instead of copying only its artifacts. Invalid project layouts fail when the locator is loaded, before deployment begins. A contracts bundle is code that runs on your machine and decides what OP Deployer deploys with your key. OP Deployer runs its scripts without the FFI cheatcode, with read access only to the artifacts, with only the environment variables that forge needs, and with only the settings of its forge config that compile or run the scripts. Use only bundles that you trust: embedded, or a bundle that you built.