base/contract-deployments

contract-deployments

This repo contains execution code and artifacts related to Base contract deployments, upgrades, and calls. For actual contract implementations, see base/contracts.

This repo is structured with each network having a high-level directory which contains subdirectories of any "tasks" (contract deployments/calls) that have happened for that network.

Setup

Toolchain (mise)

All required tooling (Foundry, Node.js, Bun, Go) is pinned in mise.toml so that every contributor — and especially every signer — runs identical versions. This eliminates a class of bugs where domain separators, build artifacts, or generated signatures differ between machines.

Signers and facilitators don't need to install anything. make sign-task (and make deps, make execute, etc.) automatically:

1. Installs mise to ~/.local/bin/mise if it's not already present, using the vendored installer at scripts/install-mise.sh.
2. Trusts the repo's mise.toml and runs mise install to fetch the pinned foundry, node, bun, and go versions.
3. Invokes every toolchain command through mise exec --, so the pinned versions are used without modifying your shell environment or PATH. This deliberately avoids conflicts with any existing foundryup or system-level installs.

Important — mise must be on your PATH for the signer-tool. The generated validation files contain a cmd field with mise exec -- (deliberately, so the JSON is portable across machines), and the signer-tool re-executes that command in a fresh shell. If mise is not on your PATH, that subprocess will fail with "command not found". make bootstrap-mise will warn you if this is the case. To fix it, add this to your shell config (e.g. ~/.zshrc or ~/.bashrc) and restart your shell:

export PATH="$HOME/.local/bin:$PATH"

Alternatively, install mise system-wide so it lands on your default PATH.

Verifying the pinned Foundry version (optional)

$ mise exec -- forge --version
forge Version: 1.5.1-...
Commit SHA: b0a9dd9ceda36f63e2326ce530c10e6916f4b8a2

The Commit SHA is the source of truth — it must match the commit pinned in mise.toml.

For contributors authoring new tasks (optional)

If you want bare forge/cast/bun/go invocations in your interactive shell to resolve to the pinned versions while you're working inside this repo, add mise's shell hook to your shell config:

# zsh
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
# bash
echo 'eval "$(mise activate bash)"' >> ~/.bashrc

This is purely a convenience for task authors — make targets work correctly without it.

Running a task

To execute a new task, run one of the following commands (depending on the type of change you're making):

• For gas increase tasks: make setup-gas-increase network=<network>
• For combined gas, elasticity, and DA footprint gas scalar tasks: make setup-gas-and-elasticity-increase network=<network>
• For safe management tasks: make setup-safe-management network=<network>
• For funding tasks: make setup-funding network=<network>
• For updating the partner threshold in Base Bridge: make setup-bridge-partner-threshold network=<network>
• For pausing / un-pausing Base Bridge: make setup-bridge-pause network=<network>
• For pausing SuperchainConfig: make setup-superchain-config-pause network=<network>

Each setup-* command also creates a matching <network>/signatures/<task-dir-basename>/ directory for task origin signing. The parent signatures/ directory is created automatically via mkdir -p for networks that do not yet have one.

Next, cd into the directory that was created for you and follow the steps listed below for the relevant template.

Please note, for some older tasks (that have not yet been adapted to use the signer tool) you will need to manually create validation file(s) for your task as they are bespoke to each task and therefore not created automatically as a part of the templates. We use one validation Markdown file per multisig involved in the task, so if there's only one multisig involved in your task, then you can simply create a VALIDATION.md file at the root of your task containing the validation instructions, while if there are multiple multisigs involved in the task, then create a validations/ sub-directory at the root of your task containing the corresponding validation Markdown files. If you need examples to work from, you can browse through similar past tasks in this repo and adapt them to your specific task. Also, please note that we have tooling to generate these files (like the task-signer-tool) which removes the manual aspect of creating these validation files, we will soon update these instructions to reflect how this process can be automated.

Network configuration

Each network directory (mainnet/, sepolia/, sepolia-alpha/, zeronet/) contains a .env file that defines all contract addresses and network metadata for that chain. These variables are automatically available to every task via the include ../.env directive in each task's Makefile, so there is no need to manually load addresses in individual tasks or templates.

The network .env files contain:

• Network metadata — NETWORK, L1_RPC_URL, L2_RPC_URL, L1_CHAIN_ID, L2_CHAIN_ID, LEDGER_ACCOUNT
• Admin addresses — multisig addresses, proposer, challenger, batch sender, etc.
• L1 contract addresses — proxy admin, bridges, dispute game factories, system config, etc.
• L2 contract addresses — fee vaults, cross-domain messenger, standard bridge, etc.

All address variables are prefixed with export so they are available to child shell processes (Forge scripts, shell commands, etc.). Foundry scripts can access them via vm.envAddress("VARIABLE_NAME").

Note: If you need to add or update a contract address, edit the corresponding {network}/.env file directly. Do not create per-task address definitions unless they are truly task-specific.

Directory structure

Active EVM tasks live under active/evm/, which is a single shared Foundry project rather than a standalone project per task. A single active/evm/Makefile selects the active task via TASK_ID / TASK_NETWORK, reusable operation scripts are shared across tasks under script/common/<category>/, and each task directory holds only its own config, docs, and (per-network) validations and signatures:

active/evm/
├── Makefile                     # shared; selects the task via TASK_ID / TASK_NETWORK
├── foundry.toml                 # shared Foundry config (base-contracts v8.2.1)
├── script/
│   └── common/                  # reusable scripts, shared across tasks
│       └── <category>/          # bridge, funding, gas, ownership, safe, superchain, verifier-update
└── tasks/
    └── <YYYY-MM-DD-task-name>/
        ├── FACILITATOR.md
        ├── config/
        │   └── <network>/
        │       ├── .env         # task inputs + BASE_CONTRACTS_COMMIT + RECORD_STATE_DIFF
        │       ├── network.env  # RPC, chain ids, Safe/contract addresses
        │       ├── README.md    # status + description (parsed by the signer tool)
        │       └── validations/ # generated per-signer validation JSON
        └── signatures/
            └── <network>/       # task-origin signatures (when required)

Task commands run from active/evm, selecting the task by TASK_ID / TASK_NETWORK (both default to the current task in the shared Makefile), e.g. TASK_ID=<task> TASK_NETWORK=<network> make gen-validation-cb. The shared Makefile runs Forge from active/evm using the shared foundry.toml and lib/, while task-specific files are read from tasks/<task-id>/config/<network>/. Reusable scripts are documented in active/evm/script/common/README.md; put a script under script/common/<category>/ when it will be reused across tasks, and keep one-off task glue out of common/.

The shared active/evm/Makefile selects a task (via TASK_ID / TASK_NETWORK) and sources that task's .env for BASE_CONTRACTS_COMMIT. To install dependencies for the shared project without selecting a task (e.g. to build the common scripts locally), invoke the root Makefile directly with a PROJECT_DIR override and an explicit BASE_CONTRACTS_COMMIT:

make deps PROJECT_DIR="$PWD/active/evm" BASE_CONTRACTS_COMMIT=<commit>

Legacy tasks

Each legacy task (under a network directory, or archive/legacy/) has a directory structure similar to the following:

• records/ Foundry will autogenerate files here from running commands
• script/ place to store any one-off Foundry scripts
• src/ place to store any one-off smart contracts (long-lived contracts should go in base/contracts)
• .env place to store task-specific environment variables (contract addresses are inherited from the network-level .env)

CI — Common Script Validation

A GitHub Actions workflow automatically validates the shared active/evm scripts on every pull request and on pushes to main.

What CI checks:

1. Solidity formatting — forge fmt --check script/ ensures formatting consistency.
2. Compilation — forge build verifies that imports resolve, types are correct, and all dependencies are present.

How it works:

• All tooling (Foundry, Node, Bun, Go) is installed by the jdx/mise-action GitHub Action using the versions pinned in mise.toml, so CI matches local signer environments.
• make deps PROJECT_DIR="$PWD/active/evm" installs dependencies into the shared active/evm Foundry project. BASE_CONTRACTS_COMMIT is supplied via the workflow's env block, since the shared project has no task .env of its own.
• forge fmt --check and forge build then run in active/evm against the shared foundry.toml and script/common/.

What CI does NOT do:

• Does not run forge script (requires RPC URLs, env vars, and hardware wallets).
• Does not run forge test (no test files exist for these scripts).
• Does not run signing or execution targets (they depend on network state and hardware wallets).

See .github/workflows/validate-common-scripts.yml for the full workflow definition.

Multisig macro convention

All task templates use global macros defined in Multisig.mk for multisig operations:

Two helper macros are also available for tasks that need nonce offset calculations or address manipulation:

Signing is handled externally by the task-signing-tool.

Every template Makefile should include Multisig.mk and define at least two variables for the macros to work:

include ../../Makefile
include ../../Multisig.mk
include ../.env
include .env

RPC_URL = $(L1_RPC_URL)       # or $(L2_RPC_URL)
SCRIPT_NAME = MyScript         # class name or .sol file path

Templates that generate validation files should use GEN_VALIDATION with the deps-signer-tool prerequisite (which checks out and installs the signer-tool):

gen-validation: validate-config deps-signer-tool
	$(call GEN_VALIDATION,$(SCRIPT_NAME),,$(SENDER),base-signer.json,)

Templates should use these macros rather than inline forge script / eip712sign / bun run invocations. The known exceptions are the incident-response pause templates, which pre-sign 20 future nonces in a loop using inline eip712sign; only their execute-* targets use MULTISIG_EXECUTE.

Task origin signing

The root Makefile provides three targets for generating cryptographic attestations (sigstore bundles) that prove who created and facilitated a task. These are inherited by all task Makefiles via include ../../Makefile.

Signatures are stored in <network>/signatures/<task-name>/, where <task-name> is auto-derived from the task directory name. This directory is created automatically when you run any setup-* target (in both the root and Solana Makefiles), so it is ready for the signing tool when you invoke one of the targets below. Two variables control this behavior and can be overridden in a task's Makefile if the defaults are not appropriate:

All three targets depend on deps-signer-tool, which checks out and installs the task-signing-tool automatically.

For active/evm tasks, the shared Makefile overrides TASK_ORIGIN_DIR and SIGNATURE_DIR: the signer tool signs over the active/evm/tasks/<task-id>/config/<network> directory (TASK_ORIGIN_DIR), while the signatures themselves are written to active/evm/tasks/<task-id>/signatures/<network>/ (SIGNATURE_DIR) — outside the signed directory, so generating signatures does not change the signed payload. A task may opt out of task-origin validation entirely by setting skipTaskOriginValidation: true at the root of each validation file (e.g. non-production networks such as zeronet).

Using the gas limit increase template

This template is increasing the throughput on Base Chain.

1. Ensure you have followed the instructions above in setup
2. Go to the folder that was created using the make setup-gas-increase network=<network> step
3. Fill in all TODOs (search for "TODO" in the folder) in the .env and README files. Tip: you can run make deps followed by make sign-upgrade to produce a Tenderly simulation which will help fill in several of the TODOs in the README (and also make sign-rollback).
4. Check in the task when it's ready to sign and collect signatures from signers
5. Once executed, check in the records files and mark the task EXECUTED in the README.

Using the combined gas limit, elasticity, and DA footprint gas scalar template

This template is used to update the gas limit, elasticity, and DA footprint gas scalar, or roll back the changes (if needed).

1. Ensure you have followed the instructions above in setup, including running make setup-gas-and-elasticity-increase network=<network> and then go to the folder that was created by this command.
2. Specify the commit of Base contracts code in the .env file.
3. Run make deps.
4. Fill in any task-specific variables in the .env file that have per-network comments (e.g., OWNER_SAFE, SENDER), using the value for your target network.
5. Ensure the SENDER variable in the .env file is set to a signer of OWNER_SAFE.
6. Set the FROM_* and TO_* values for gas limit and elasticity in the .env file.
7. Calculate the DA footprint gas scalar using the DA limits runbook at go/base-da-config. make da-scalar TARGET_BLOB_COUNT=<value> is the source of truth for the standard soft-cap policy and calculates gas_limit / (elasticity * da_soft_cap_blob_count * 32,000). Since BPO2, Base has used a DA soft-cap blob count of 21, passed as TARGET_BLOB_COUNT=21, to allow the chain to use all L1 DA before raising the L2 base fee. The command prints the .env value and the DA table to copy into the task README. Pass BUILDER_HARD_CAP=<value> after checking the target network's op_batcher_throttle_block_size_upper_limit Config Service value. The task README includes links for the standard network scopes. Set the FROM_DA_FOOTPRINT_GAS_SCALAR and TO_DA_FOOTPRINT_GAS_SCALAR values in the .env file.
8. Build the contracts with forge build.
9. Generate the validation file for signers with make gen-validation.
10. Generate the rollback validation file for signers with make gen-validation-rollback.
11. Double check the cmd field at the top of both of the generated validation files and ensure that the value passed to the --sender flag matches the SENDER env var already defined in the .env file.
12. Ensure that all of the fields marked as TODO in the tasks's README.md have been properly filled out.
13. Check in the task when it's ready to sign and request the facilitators to collect signatures from signers.
14. Once executed, check in the records files and mark the task EXECUTED in the README.

Using the safe management template

This template is used to perform ownership management on a Gnosis Safe, like the incident multisig, specifically it can be used to change the owners of the multisig.

1. Ensure you have followed the instructions above in setup, including running make setup-safe-management network=<network> and go to the folder that was created by this command.
2. Specify the commit of Base contracts code you intend to use in the .env file.
3. Enter the directory that was generated for the task (in the first step) and then run make deps.
4. Specify the OWNER_SAFE, which is the safe multisig where an owner will be replaced and the SENDER which should be the address of a current signer of the multisig.
5. Fill in the OwnerDiff.json inside the task's directory with the addresses to add to, and remove from, the multisig in their respective fields.
6. Ensure that the EXISTING_OWNERS_LENGTH constant value inside the script/UpdateSigners.s.sol script is set appropriately, in particular that it equals the exact number of current members of the Incident Multisig Safe (prior to running the task).
7. Build the contracts with forge build.
8. Generate the validation file for signers with make gen-validation.
9. Double check the cmd field at the top of the generated validation file at validations/base-signer.json and ensure that the value passed to the --sender flag matches the SENDER env var already defined in the .env file.
10. Check in the task when it's ready to sign and request the facilitators to collect signatures from signers.
11. Once executed, check in the records files and mark the task EXECUTED in the README.

Using the funding template

This template is used to fund addresses from a Gnosis Safe.

1. Ensure you have followed the instructions above in setup.
2. Run make setup-funding network=<network> and go to the folder that was created by this command.
3. Specify the commit of Base contracts code you intend to use in the .env file.
4. Run make deps.
5. Specify the SAFE, which is the safe that will fund the addresses in the .env file.
6. Specify the recipients and funds arrays (in 1e18 units) in the funding.json file.
7. Build the contracts with forge build.
8. Simulate the task with make sign and update the generic validations in VALIDATION.md with the real values.
9. Check in the task when it's ready to sign and request the facilitators to collect signatures from signers.
10. Once executed, check in the records files and mark the task EXECUTED in the README.

Using the Base Bridge set partner threshold template

This template is used to update the partner threshold in Base Bridge, affecting the amount of required partner signatures to approve bridge messages.

1. Ensure you have followed the instructions above in setup.
2. Run make setup-bridge-partner-threshold network=<network> and go to the folder that was created by this command.
3. Specify the commit of Base contracts code you intend to use in the .env file.
4. Run make deps.
5. Fill in any task-specific variables in the .env file that have per-network comments, using the value for your target network.
6. Set the NEW_THRESHOLD variable in the .env file.
7. Ensure the --sender flag in the make gen-validation command in the Makefile file is set to a signer for OWNER_SAFE in .env.
8. Build the contracts with forge build.
9. Generate the validation file for signers with make gen-validation.
10. Check in the task when it's ready to sign and request the facilitators to collect signatures from signers.
11. Once executed, check in the records files and mark the task EXECUTED in the README.

Using the pause Base Bridge template

This template is used to pause or un-pause Base Bridge.

1. Ensure you have followed the instructions above in setup.
2. Run make setup-bridge-pause network=<network> and go to the folder that was created by this command.
3. Specify the commit of Base contracts code you intend to use in the .env file.
4. Run make deps.
5. Fill in any task-specific variables in the .env file that have per-network comments (e.g., L2_BRIDGE), using the value for your target network.
6. Set the IS_PAUSED variable to true or false in the .env file depending on if you intend to pause or unpause the bridge.
7. Ensure the SENDER variable in the Makefile is set to a signer for OWNER_SAFE.
8. Build the contracts with forge build.
9. Generate the validation file for signers with make gen-validation.
10. Check in the task when it's ready to sign and request the facilitators to collect signatures from signers.
11. Once executed, check in the records files and mark the task EXECUTED in the README.

Using the pause SuperchainConfig template

This template is used to pause or un-pause the L1 SuperchainConfig contract.

1. Ensure you have followed the instructions above in setup.
2. Run make setup-superchain-config-pause network=<network> and go to the folder that was created by this command.
3. Specify the commit of Base contracts code you intend to use in the .env file.
4. Run make deps.
5. Fill in any task-specific variables in the .env file that have per-network comments, using the value for your target network.
6. Build the contracts with forge build.
7. Sign the pause transaction with make sign-pause or generate the validation file for un-pausing with make gen-validation-unpause.
8. Check in the task when it's ready to sign and request the facilitators to collect signatures from signers.
9. Once executed, check in the records files and mark the task EXECUTED in the README.