contract-deployments

This repo contains execution code and artifacts related to Base contract deployments, upgrades, and calls. For actual contract implementations, see base-org/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

First, install forge if you don't have it already:

• Run make install-foundry to install Foundry.

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

• For a generic task: make setup-task network=<network> task=<task-name>
• For gas increase tasks: make setup-gas-increase network=<network>
• For funding: make setup-funding network=<network>
• For fault proof upgrade: make setup-upgrade-fault-proofs 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>

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

👥 For Signers: Please read the Signer Guide for step-by-step instructions on using the validation UI.

Please note, 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.

Directory structure

Each task will have a directory structure similar to the following:

• inputs/ any input JSON files
• 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-org/contracts)
• .env place to store environment variables specific to this task

Using the incident response template

This template contains scripts that will help us respond to incidents efficiently.

To use the template during an incident:

1. Fill in the .env file with dependency commit numbers and any variables that need to be defined for the script you're running.
2. Delete the other scripts that are not being used so that you don't run into build issues.
3. Make sure the code compiles and check in the code.
4. Have each signer pull the branch, and run the relevant signing command from the Makefile.

To add new incident response scripts:

1. Any incident response-related scripts should be included in this template (should be generic, not specific to network), with specific TODOs wherever addresses or other details need to be filled in.
2. Add the relevant make commands that would need to be run for the script to the template Makefile
3. Add relevant mainnet addresses in comments to increase efficiency responding to an incident.

Using the generic template

This template can be used to do contract calls, upgrades, or one-off deployments.

1. Specify the commit of Optimism code and Base contracts code you intend to use in the .env file
2. Run make deps
3. Put scripts in the script directory (see examples that are part of the template, for example, there is a file BasicScript.s.sol). See note below if running a task that requires a multisig to sign.
4. Call scripts from the Makefile (see examples in the template Makefile that's copied over).

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 fault proof upgrade template

This template is used to upgrade the fault proof contracts. This is commonly done in conjunction with a hard fork.

1. Ensure you have followed the instructions above in setup
2. Go to the folder that was created using the make setup-upgrade-fault-proofs network=<network> step
3. Specify the commit of Optimism code and Base contracts code you intend to use in the .env file
4. Run make deps
5. Add the new absolute prestate to the .env file. This can be found in the op-program prestates releases.json file.
6. NOTE: If this task is for mainnet, the directory should work as-is. If this task is for testnet, you will need to follow the following steps:
   1. Comment out the mainnet environment variables and uncomment the testnet vars in .env
7. Build the contracts with forge build
8. Remove the unneeded validations from VALIDATION.md and update the relevant validations accordingly
9. Check in the task when it's ready to sign and collect signatures from signers
10. Once executed, check in the records files and mark the task EXECUTED in the README.

Using the swap owner template

This template is used to perform ownership management on a Gnosis Safe multisig, specifically it can swap owners on the multisig.

1. Ensure you have followed the instructions above in setup.
2. Run make setup-safe-management network=<network> and go to the folder that was created by this command.
3. Specify the commit of Optimism code and Base contracts code you intend to use in the .env file.
4. Run make deps.
5. Specify the OWNER_SAFE, which is the safe multisig where an owner will be replaced, the OLD_SIGNER (current owner) to remove, and the NEW_SIGNER (new owner) to be added in the .env file.
6. Build the contracts with forge build.
7. Simulate the task with make sign and update the generic validations in VALIDATION.md with the real values.
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.

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 Optimism code and 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 Optimism code and Base contracts code you intend to use in the .env file.
4. Run make deps.
5. Ensure only the Sepolia or Mainnet variables are in the .env file depending on what network this task is for.
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 Optimism code and Base contracts code you intend to use in the .env file.
4. Run make deps.
5. Ensure only the Sepolia or Mainnet variables are in the .env file depending on what network this task is for.
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 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.