Skip to content

Commit 92134fa

Browse files
0xth4nhclaude
andcommitted
docs(active-evm): add README and task-origin signing guide
Documents the active/evm shared-project layout, how tasks run against the shared Foundry setup, and the task-origin signing flow. Written generically (no task-specific references) so it stands alone with the foundation. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 035093b commit 92134fa

2 files changed

Lines changed: 100 additions & 0 deletions

File tree

active/evm/README.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Active EVM Tasks
2+
3+
Active EVM tasks live under `tasks/<task-id>/`. Shared Foundry setup and reusable
4+
scripts stay at this `active/evm` root so multiple active tasks can use the same
5+
`script/common/<category>/` implementations.
6+
7+
## Layout
8+
9+
```text
10+
active/evm/
11+
├── foundry.toml
12+
├── script/
13+
│ └── common/
14+
│ ├── bridge/
15+
│ ├── funding/
16+
│ ├── gas/
17+
│ ├── ownership/
18+
│ ├── safe/
19+
│ ├── superchain/
20+
│ └── verifier-update/
21+
└── tasks/
22+
└── <YYYY-MM-DD-task-name>/
23+
├── Makefile
24+
├── FACILITATOR.md
25+
└── config/
26+
└── <network>/
27+
├── .env
28+
├── network.env
29+
├── README.md
30+
├── validations/
31+
└── signatures/
32+
```
33+
34+
Shared, repo-wide infrastructure (toolchain bootstrap, `deps`, signer-tool
35+
checkout, task-origin signing targets) lives in the root `Makefile` and
36+
`Multisig.mk`, which each task Makefile includes.
37+
38+
## Running a task
39+
40+
Each task ships its own `Makefile` under `tasks/<task-id>/` that selects the
41+
task/network and wires the relevant `script/common` script. Run task commands
42+
from `active/evm`:
43+
44+
```bash
45+
cd active/evm
46+
make deps
47+
make gen-validation-cb
48+
make gen-validation-sc
49+
```
50+
51+
The root Makefile runs Forge from `active/evm` (shared `foundry.toml` and `lib/`),
52+
while task-specific files are read from `tasks/<task-id>/config/<network>/`. The
53+
signer tool discovers date-prefixed task directories containing
54+
`config/<network>/validations`. Task-origin signatures, when required, live under
55+
`tasks/<task-id>/config/<network>/signatures/` (see `TASK_ORIGIN.md`).
56+
57+
## Common scripts
58+
59+
Reusable operation scripts live under `script/common/<category>/` and are shared
60+
across tasks. See `script/common/README.md` for the inventory and conventions.

active/evm/TASK_ORIGIN.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Task Origin Signing
2+
3+
Task origin signatures prove who created and facilitated the task. They are
4+
stored with each network config under
5+
`active/evm/tasks/<task-id>/config/<network>/signatures/`.
6+
7+
The signatures cover `active/evm/tasks/<task-id>/config/<network>`, excluding the
8+
`signatures/` directory itself, so any change to `.env`, `network.env`, or the
9+
validation files after this step requires regenerating them.
10+
11+
Task-origin validation is enabled by default. A task may opt out by setting
12+
`skipTaskOriginValidation: true` at the root of each validation file (for
13+
example, non-production networks that do not require origin signatures).
14+
15+
Run these commands only after the network config is final. Select the task with
16+
`TASK_ID` / `TASK_NETWORK`:
17+
18+
## Task Creator
19+
20+
```bash
21+
cd active/evm
22+
make deps
23+
TASK_ID=<YYYY-MM-DD-task-name> TASK_NETWORK=<network> make sign-as-task-creator
24+
```
25+
26+
## Base Facilitator
27+
28+
```bash
29+
cd active/evm
30+
make deps
31+
TASK_ID=<YYYY-MM-DD-task-name> TASK_NETWORK=<network> make sign-as-base-facilitator
32+
```
33+
34+
## Security Council Facilitator
35+
36+
```bash
37+
cd active/evm
38+
make deps
39+
TASK_ID=<YYYY-MM-DD-task-name> TASK_NETWORK=<network> make sign-as-sc-facilitator
40+
```

0 commit comments

Comments
 (0)