diff --git a/AGENTS.md b/AGENTS.md index f42c2567..bbe6c2dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,7 @@ Task writing: - Good: `pragma solidity 0.8.15` - Bad: `pragma solidity ^0.8.20` - Always use "onchain" instead of "on-chain" +- Do not artificially wrap Markdown prose; keep each paragraph and list item on one logical line - Config values loaded from a `.env` should be stored as immutable variables in the solidity script(s) - We only need task origin validation for mainnet scripts that go through proxy admin owner - `RECORD_STATE_DIFF=true` is needed in the task `.env` file in order for the signer tool to work diff --git a/README.md b/README.md index 75b9814b..a6511219 100644 --- a/README.md +++ b/README.md @@ -4,28 +4,19 @@ This repo contains execution code and artifacts related to Base contract deployments, upgrades, and calls. For actual contract implementations, see [base/contracts](https://github.com/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. +Active EVM tasks live under `active/evm/tasks/`. Shared network configuration lives under `config/`, and completed historical tasks live under `archive/`. -[![GitHub contributors](https://img.shields.io/github/contributors/base/contract-deployments)](https://github.com/base/contract-deployments/graphs/contributors) -[![GitHub commit activity](https://img.shields.io/github/commit-activity/w/base/contract-deployments)](https://github.com/base/contract-deployments/graphs/contributors) -[![GitHub Stars](https://img.shields.io/github/stars/base/contract-deployments.svg)](https://github.com/base/contract-deployments/stargazers) -![GitHub repo size](https://img.shields.io/github/repo-size/base/contract-deployments) -[![GitHub](https://img.shields.io/github/license/base/contract-deployments?color=blue)](https://github.com/base/contract-deployments/blob/main/LICENSE) +[![GitHub contributors](https://img.shields.io/github/contributors/base/contract-deployments)](https://github.com/base/contract-deployments/graphs/contributors) [![GitHub commit activity](https://img.shields.io/github/commit-activity/w/base/contract-deployments)](https://github.com/base/contract-deployments/graphs/contributors) [![GitHub Stars](https://img.shields.io/github/stars/base/contract-deployments.svg)](https://github.com/base/contract-deployments/stargazers) ![GitHub repo size](https://img.shields.io/github/repo-size/base/contract-deployments) [![GitHub](https://img.shields.io/github/license/base/contract-deployments?color=blue)](https://github.com/base/contract-deployments/blob/main/LICENSE) -[![Website base.org](https://img.shields.io/website-up-down-green-red/https/base.org.svg)](https://base.org) -[![Blog](https://img.shields.io/badge/blog-up-green)](https://base.mirror.xyz/) -[![Docs](https://img.shields.io/badge/docs-up-green)](https://docs.base.org/) -[![Discord](https://img.shields.io/discord/1067165013397213286?label=discord)](https://base.org/discord) -[![Twitter BuildOnBase](https://img.shields.io/twitter/follow/BuildOnBase?style=social)](https://x.com/BuildOnBase) +[![Website base.org](https://img.shields.io/website-up-down-green-red/https/base.org.svg)](https://base.org) [![Blog](https://img.shields.io/badge/blog-up-green)](https://base.mirror.xyz/) [![Docs](https://img.shields.io/badge/docs-up-green)](https://docs.base.org/) [![Discord](https://img.shields.io/discord/1067165013397213286?label=discord)](https://base.org/discord) [![Twitter BuildOnBase](https://img.shields.io/twitter/follow/BuildOnBase?style=social)](https://x.com/BuildOnBase) -[![GitHub pull requests by-label](https://img.shields.io/github/issues-pr-raw/base/contract-deployments)](https://github.com/base/contract-deployments/pulls) -[![GitHub Issues](https://img.shields.io/github/issues-raw/base/contract-deployments.svg)](https://github.com/base/contract-deployments/issues) +[![GitHub pull requests by-label](https://img.shields.io/github/issues-pr-raw/base/contract-deployments)](https://github.com/base/contract-deployments/pulls) [![GitHub Issues](https://img.shields.io/github/issues-raw/base/contract-deployments.svg)](https://github.com/base/contract-deployments/issues) ## Setup @@ -72,25 +63,19 @@ This is purely a convenience for task authors — `make` targets work correctly ### Running a task -To execute a new task, run one of the following commands (depending on the type of change you're making): +Each active task owns its Makefile, signer README, facilitator guide, configuration, and validations. Run task commands from the task directory: -- For gas increase tasks: `make setup-gas-increase network=` -- For combined gas, elasticity, and DA footprint gas scalar tasks: `make setup-gas-and-elasticity-increase network=` -- For safe management tasks: `make setup-safe-management network=` -- For funding tasks: `make setup-funding network=` -- For updating the partner threshold in Base Bridge: `make setup-bridge-partner-threshold network=` -- For pausing / un-pausing Base Bridge: `make setup-bridge-pause network=` -- For pausing SuperchainConfig: `make setup-superchain-config-pause network=` - -Each `setup-*` command also creates a matching `/signatures//` directory for [task origin signing](#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. +```bash +cd active/evm/tasks/ +make deps +make +``` -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. +Signers run `make sign-task` from the repository root, select the network and task in the UI, and follow the task README. ## 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. +Shared network values live in `config/mainnet.env`, `config/sepolia.env`, and `config/zeronet.env`. Task Makefiles include the appropriate shared file and load operation-specific values from `config//.env` inside the task. The network `.env` files contain: @@ -101,51 +86,36 @@ The network `.env` files contain: 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. +> **Note:** Update `config/.env` when a known shared address changes. Keep task-specific values, including `BASE_CONTRACTS_COMMIT`, in the task `.env`. ## 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//`, and each task -directory holds only its own config, docs, and (per-network) validations and -signatures: +Active EVM tasks use one shared Foundry project. Dependencies and reusable Solidity are shared; Make targets, configuration, documentation, signatures, and execution records stay with each task: ```text active/evm/ -├── Makefile # shared; selects the task via TASK_ID / TASK_NETWORK ├── foundry.toml # shared Foundry config (base-contracts v8.2.1) +├── lib/ # generated shared dependencies; not committed ├── script/ │ └── common/ # reusable scripts, shared across tasks │ └── / # bridge, funding, gas, ownership, safe, superchain, verifier-update └── tasks/ └── / - ├── FACILITATOR.md + ├── Makefile # task dependencies, validation, approvals, execution + ├── FACILITATOR.md # facilitator runbook ├── config/ │ └── / - │ ├── .env # task inputs + BASE_CONTRACTS_COMMIT + RECORD_STATE_DIFF - │ ├── network.env # RPC, chain ids, Safe/contract addresses + │ ├── .env # task inputs + BASE_CONTRACTS_COMMIT │ ├── README.md # status + description (parsed by the signer tool) │ └── validations/ # generated per-signer validation JSON - └── signatures/ - └── / # task-origin signatures (when required) + ├── signatures/ + │ └── / # task-origin signatures (when required) + └──