diff --git a/README.md b/README.md index 7d4d6296..75b9814b 100644 --- a/README.md +++ b/README.md @@ -105,37 +105,83 @@ All address variables are prefixed with `export` so they are available to child ## Directory structure -Each task will have a directory structure similar to the following: +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: + +```text +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 +│ └── / # bridge, funding, gas, ownership, safe, superchain, verifier-update +└── tasks/ + └── / + ├── FACILITATOR.md + ├── config/ + │ └── / + │ ├── .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/ + └── / # 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_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//config//`. +Reusable scripts are documented in [`active/evm/script/common/README.md`](active/evm/script/common/README.md); +put a script under `script/common//` 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`: + +```bash +make deps PROJECT_DIR="$PWD/active/evm" BASE_CONTRACTS_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](https://github.com/base/contracts)) - **.env** place to store task-specific environment variables (contract addresses are inherited from the network-level `.env`) -## CI — Template Validation +## CI — Common Script Validation -A GitHub Actions workflow automatically validates all 10 setup-templates on every pull request and on pushes to `main`. +A GitHub Actions workflow automatically validates the shared `active/evm` scripts on every pull request and on pushes to `main`. -**What CI checks for each template:** +**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. -Templates are validated in parallel using a matrix strategy, so failures are isolated per-template with clear error messages identifying the template and failure type. - **How it works:** - All tooling (Foundry, Node, Bun, Go) is installed by the [`jdx/mise-action`](https://github.com/jdx/mise-action) GitHub Action using the versions pinned in [`mise.toml`](mise.toml), so CI matches local signer environments. -- For each template, the corresponding `make setup-*` target creates a task directory from the template. -- `make deps` installs all dependencies (including base-contracts at the commit pinned in the template's `.env`). +- `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 in templates). +- 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-templates.yml`](.github/workflows/validate-templates.yml) for the full workflow definition. +> See [`.github/workflows/validate-common-scripts.yml`](.github/workflows/validate-common-scripts.yml) for the full workflow definition. ## Multisig macro convention @@ -196,6 +242,8 @@ Signatures are stored in `/signatures//`, where ` All three targets depend on `deps-signer-tool`, which checks out and installs the [task-signing-tool](https://github.com/base/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//config/` directory (`TASK_ORIGIN_DIR`), while the signatures themselves are written to `active/evm/tasks//signatures//` (`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.