diff --git a/docs/billing-import/design.md b/docs/billing-import/design.md
new file mode 100644
index 000000000..5eadc67a6
--- /dev/null
+++ b/docs/billing-import/design.md
@@ -0,0 +1,68 @@
+# Import billing-contracts into the monorepo
+
+## Intent
+
+`graphprotocol/billing-contracts` (Graph Studio billing: Billing, BillingConnector, BanxaWrapper) lives outside this monorepo only because it used to belong to a different GitHub organization. It has now moved to `graphprotocol`, so it comes into the monorepo as a new package. This is repository housekeeping: nothing about the contracts changes. The old repo is then marked deprecated and keeps its history.
+
+## Goals
+
+- A new private workspace package, `@graphprotocol/billing` in `packages/billing`, holding everything from billing-contracts `main` (`8b063db`), as is: contracts (including `contracts/arbitrum/` and `contracts/tests/`), tests, Hardhat deploy and ops tasks, `scripts/`, `utils/`, address books (`addresses.json`, `addresses-staging.json`), `hardhat.config.ts`, `tsconfig.json`, README and LICENSE.
+- Contract source files are byte-identical to the originals, and the compiled bytecode equals the original repo's build, metadata hash ignored.
+- The package builds and its tests run in the monorepo CI, like the other packages.
+- One PR targeting `chore/contracts-removal-phase-0` (#1373), the branch going to audit. It joins the stack after Phase 2a (base head `dfc25afd`).
+- The billing contracts are in the audit's scope. The PR merges into the base before the audit commit is fixed.
+- The package stays operational: billing deployments and ops will be run from it once the original repo is deprecated. Its deploy and ops tasks and scripts work under pnpm, and the address books in `packages/billing` become the source of truth.
+
+## Non-goals
+
+- Keeping git history. One import commit; the history stays in the deprecated original repo.
+- Publishing to npm. The package is `"private": true` with no changeset. The old npm name `graph-studio-billing-contracts` was never really published (npm shows only a `0.0.1-security` placeholder).
+- Upgrading the toolchain or dependencies beyond what's needed to install, build and test in the monorepo.
+- Integrating with `@graphprotocol/address-book`, toolshed, the `deployment` package or Ignition. Moving billing deployments into `packages/deployment` may come later as its own project.
+- Deprecating the old repo. That's a manual GitHub step after the import lands.
+
+## Anti-goals
+
+- Any edit to a `.sol` file, or to the compiler settings: solc `0.8.16`, optimizer enabled, 200 runs, default EVM version.
+- Reformatting imported files. Root `prettier`, `eslint`, `solhint` and `markdownlint` must not touch `packages/billing`. The precedent is `packages/legacy/verified/` in the root `.prettierignore`.
+- Resolving a different OpenZeppelin or `arb-bridge-peripherals` version than the original lockfile. Those versions decide the bytecode.
+
+## Constraints
+
+- **Pinned contract dependencies:** the original `yarn.lock` resolves `@openzeppelin/contracts` to `4.7.3` and `arb-bridge-peripherals` to `1.0.11`. The package pins both exactly. The monorepo already holds OpenZeppelin 3.4.2 (graph-core alias) and 5.x elsewhere; pnpm keeps them per package.
+- **Toolchain as in the original where it works:** Hardhat 2 (the lockfile has 2.11.2), ethers v5, typechain for ethers v5, mocha and chai, `hardhat-abi-exporter`, `solidity-coverage`. Change a version only if it fails to install or run on the monorepo's Node version, and record each change in the PR.
+- **Repo-root files are not imported:** `yarn.lock`, `.husky/`, `commitlint.config.js`, `.github/`, and the package-level `.eslintrc`, `.eslintignore`, `.prettierrc.json`, `.prettierignore`, `.solhint.json`, `.solhintignore`, `lint-staged` config and `prepare`/husky script. The monorepo's root setup replaces them. `.example.env`, `.gitattributes`, `.gitignore` and `.solcover.js` come over if the package still uses them.
+- **No secrets:** `scripts/test` contains a well-known ganache test mnemonic. That one is fine. Nothing else with keys or RPC URLs is added, and `hardhat.config.ts` keeps reading them from the environment.
+- **Commits and PR:** conventional commits, no attribution lines. The PR is a draft on #1373's branch.
+
+## Verification
+
+- **Source:** every `.sol` file is byte-identical to `8b063db`, and so is every other imported file except `package.json` and the shell scripts in `scripts/` that call `yarn`. Those scripts change only as far as pnpm needs: `yarn <script>` becomes `pnpm <script>`, `yarn` (install) becomes `pnpm install`. A `diff -r` against a checkout of the original, excluding the dropped root files, shows only those changes, and the PR lists them.
+- **Tasks:** every Hardhat task under `tasks/deployment` and `tasks/ops` loads (`npx hardhat --help` lists it). `deployAll` and each deploy task run on the in-process Hardhat network, or on a local `hardhat node` where the task needs one. `pullAll` and `addToMany` run against the contracts that deploy produced. Nothing touches a live network.
+- **Bytecode:** build the original repo at `8b063db` with its own `yarn.lock` (in a scratch directory, not committed). Then compare, for every non-test contract, the monorepo build's `bytecode` and `deployedBytecode` with metadata stripped. The comparison is added to the existing `pnpm check:bytecode` (`scripts/contracts-migration/manifest.json` and `reference.json`), so CI keeps checking it.
+- **Deployed code (informational):** compare runtime code with the address books' deployments of Billing on Arbitrum One, BillingConnector on mainnet and BanxaWrapper on Arbitrum One. Report the result in the PR without blocking on it. A deployment may predate `8b063db`.
+- **Tests:** `pnpm --filter @graphprotocol/billing test:self` runs the original mocha suite on the in-process Hardhat network and passes with the original test count. The ganache gas-report mode (`RUN_EVM=true`) can stay as an unused script.
+- **CI:** the package's `build`, `test:self` and `test:coverage:self` run in the existing `Build and Test` workflow through `pnpm -r`. Its coverage output is uploaded with the others.
+- **Lint:** `pnpm lint` at the root leaves `git status` clean.
+
+## Notes from the builder check
+
+- The `Lint` workflow lints changed files, not root `pnpm lint`, so the exclusion has to cover `.github/workflows/lint.yml` too.
+- `check:bytecode` fails on contracts with empty bytecode, so interfaces and the abstract `L1ArbitrumMessenger` stay out of the manifest.
+- The original `scripts/test` always exits 0 (`result=0` after the run), so the original suite's pass count is confirmed by running `npx hardhat test` directly before it's used as the reference.
+
+## Left to the builder
+
+- How root lint is excluded: ignore files, glob changes or eslint config `ignores`.
+- Which package scripts map to the monorepo conventions (`build`, `build:self`, `test`, `test:self`, `test:coverage:self`, `clean`, `lint`), and whether `scripts/build` and `scripts/test` are called or replaced with equivalent package.json scripts.
+- The minimal toolchain fixes, within the constraints above.
+- How the original reference build is produced and the hashes recorded, using the same hashing as `scripts/lib/bytecode.mjs`.
+- Whether the root README's package table and `CLAUDE.md` get a line for the new package. Expected: yes, one line each.
+
+## Calls made without explicit confirmation
+
+- Package name `@graphprotocol/billing` and path `packages/billing`.
+- The bytecode bar: equal to the original repo's build, the same bar as the frozen moves.
+- Which repo-root files are dropped.
+- Adding the billing contracts to `check:bytecode`.
+- This document lives on the docs branch (#1372), next to the contracts-removal docs.
diff --git a/docs/billing-import/plan.md b/docs/billing-import/plan.md
new file mode 100644
index 000000000..a1caa9739
--- /dev/null
+++ b/docs/billing-import/plan.md
@@ -0,0 +1,144 @@
+# billing-contracts Import Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Import `graphprotocol/billing-contracts` at `8b063db` into the monorepo as the private package `@graphprotocol/billing`, unchanged, building and tested in CI, with its deploy and ops tasks working under pnpm.
+
+**Architecture:**
+
+- One draft PR on `chore/contracts-removal-phase-0` (#1373, head `dfc25afd`) with two commits.
+- The first commit is a verbatim copy of the kept files, plus the root lint exclusions that stop hooks from reformatting them. The second adapts the package to the monorepo.
+- Task 1 produces the reference numbers in a scratch directory and commits nothing.
+
+**Tech Stack:** pnpm workspaces, Hardhat 2, ethers v5, typechain (ethers-v5), mocha/chai, solc 0.8.16, OpenZeppelin 4.7.3, `arb-bridge-peripherals` 1.0.11, Node 24 (`.nvmrc`).
+
+**Spec:** `docs/billing-import/design.md`.
+
+## Global Constraints
+
+- No `.sol` file and no compiler setting changes: solc `0.8.16`, optimizer enabled, 200 runs, default EVM version.
+- `@openzeppelin/contracts` is pinned to `4.7.3` and `arb-bridge-peripherals` to `1.0.11`, exact versions.
+- Every other dependency keeps the original's version, unless it fails to install or run on Node 24. Each change is recorded in the PR.
+- The package is `"private": true`, with no changeset.
+- Repo-root files are not imported: `yarn.lock`, `.husky/`, `commitlint.config.js`, `.github/`, `.eslintrc`, `.eslintignore`, `.prettierrc.json`, `.prettierignore`, `.solhint.json`, `.solhintignore`.
+- Edits to imported files are limited to:
+  - `package.json`;
+  - in `scripts/`, `yarn <script>` becomes `pnpm <script>`, `yarn` (install) becomes `pnpm install`, and `yarn clean:all` becomes `pnpm clean:all`.
+- Root lint never touches `packages/billing`. This covers root `pnpm lint`, root `lint-staged`, `.github/workflows/lint.yml` in both `changed` and `all` modes, and `pnpm -r` solhint runs.
+- No RPC URL or API key is written to any file, commit, log or PR. RPC URLs are passed only as inline env vars. The ganache test mnemonic already in `scripts/test` is the only key material, and it stays as it is.
+- Conventional commits, with no Co-Authored-By line and no AI attribution. Never `git stash`. Push or open the PR only when the controller says so.
+- Smoke tests never touch a live network. Deploy tasks write only to a scratch copy of the address book.
+
+## Review Focus
+
+1. **A root hook silently reformats imported files.** lint-staged runs on every commit, so the source check in Task 3 (`diff -r` after both commits) must show only the allowed edits.
+2. **pnpm resolves a different OpenZeppelin or arb-bridge version than yarn did.** The bytecode check fails, and it is pinned in `check:bytecode` (Task 3).
+3. **The original `scripts/test` hides failures.** It sets `result=0` before exit. Task 1 gets the pass count from `npx hardhat test` directly, and `test:self` must fail when a test fails (Task 3, Step 6).
+4. **A task loads only when `SKIP_LOAD` is unset,** so `build` passing proves nothing about the tasks. Task 3's smoke run lists and runs them.
+5. **CI's solhint loop (`pnpm -r exec ... if [ -d contracts ]`) picks up billing.** Task 2 excludes it, and Task 2, Step 4 checks `lint.yml` in `all` mode locally.
+
+---
+
+### Task 1: Reference build of the original (no commit)
+
+**Files:** scratch only: `<scratch>/billing-ref/` (clone) and `<scratch>/billing-ref.json` (results).
+
+**Interfaces:**
+
+- Produces `<scratch>/billing-ref.json` with these fields:
+  - `hashes`: for each non-test contract with non-empty bytecode, `bytecodeHash` (from `scripts/lib/bytecode.mjs`) of `bytecode` and `deployedBytecode`;
+  - `tests`: the passing count;
+  - `deployed`: for each address-book deployment checked, whether the runtime code matches with metadata stripped.
+- Contracts in `hashes`: `Billing`, `BillingConnector`, `BanxaWrapper`, plus any other contract under `contracts/` (not `contracts/tests/`) whose bytecode is non-empty. Interfaces and the abstract `L1ArbitrumMessenger` are excluded.
+
+- [ ] **Step 1:** Clone `https://github.com/graphprotocol/billing-contracts` into scratch and check out `8b063db`. Run `yarn install --frozen-lockfile` with corepack yarn 1 on Node 18, through `npx -p node@18` or similar; Node 24 is acceptable only if it works. Then run `SKIP_LOAD=true npx hardhat compile`. Expected: exit 0.
+- [ ] **Step 2:** Run `SKIP_LOAD=true npx hardhat test`. Record the passing count. Expected: 0 failing. If any fail, stop and report.
+- [ ] **Step 3:** Compute the hashes with `node -e` importing `<repo>/scripts/lib/bytecode.mjs` over `build/artifacts/contracts/**/<Name>.json`, and write `billing-ref.json`.
+- [ ] **Step 4: Deployed code, informational.** Fetch runtime code with `cast code <address> --rpc-url "$RPC"`, with `RPC` given inline. Check Billing (`0x1B07D3344188908Fb6DEcEac381f3eE63C48477a`) and BanxaWrapper (`0xc9E1Aa57223aDD21cC88A03088aF552f1ea8A34a`) on Arbitrum One, and BillingConnector (`0x8017B9AF3F199CC6b08A48DA3859410F20bbea72`) on mainnet. Compare with `deployedBytecode`, metadata stripped and immutables masked if any. Record match or mismatch. No step blocks on this.
+
+### Task 2: Verbatim import and lint exclusions (commit 1)
+
+**Files:**
+
+- Create: `packages/billing/**`, copied byte-for-byte from `8b063db`, minus the root files listed in Global Constraints. It includes `package.json` as is.
+- Modify: root `.prettierignore`, `.solhintignore`, `eslint.config.mjs` (global `ignores`), markdownlint ignore (`.markdownlintignore`, or the `lint:md` ignore path), `.github/workflows/lint.yml`, and `scripts/lint-staged-run.sh` or the `lint-staged` globs.
+
+**Interfaces:**
+
+- Produces the exclusion glob `packages/billing/`, used the same way as `packages/legacy/verified/` today.
+
+- [ ] **Step 1:** Create the worktree `../worktrees-contracts/billing-import` on the new branch `feat/billing-import`, from `origin/chore/contracts-removal-phase-0`. Run `pnpm install --frozen-lockfile`.
+- [ ] **Step 2:** Add the exclusions:
+  - `packages/billing/` in `.prettierignore` and `.solhintignore`, plus `'packages/billing/**'` in eslint's global `ignores`;
+  - in markdownlint;
+  - in `lint.yml`: every `CHANGED_*` filter, the `all`-mode `git ls-files` lists, and the `pnpm -r exec` solhint loop (skip the package by directory);
+  - in lint-staged: files under `packages/billing/` pass through untouched.
+- [ ] **Step 3:** Copy the files with `git -C <scratch>/billing-ref archive 8b063db | tar -x -C packages/billing`, then delete the excluded root files.
+- [ ] **Step 4:** Verify before committing. Commit 1 adds a workspace package that the lockfile doesn't know, with the original `package.json` (its `lint:*` and `prepare` scripts). So it doesn't install or build, and the PR says so, as port PRs did. Root `pnpm lint` (which runs `pnpm -r run lint:sol`) is checked in Task 3. Here, run the file-level linters directly:
+  - `pnpm lint:ts`, `pnpm lint:md`, `pnpm lint:json`, `pnpm lint:yaml` and `npx prettier -w --cache --log-level warn 'packages/**/*.sol'`, then `git status --porcelain packages/billing`. Expected: empty.
+  - The `lint.yml` `all`-mode file lists, run locally. Expected: no `packages/billing` path.
+  - `diff -r <scratch>/billing-ref packages/billing`, excluding `.git`, `node_modules`, `build`, `cache` and the dropped files. Expected: no differences.
+- [ ] **Step 5:** Commit `chore(billing): import billing-contracts at 8b063db`. Then rerun the Step 4 `diff -r`. Expected: still no differences. This proves lint-staged left the files alone.
+
+### Task 3: Adapt to the monorepo (commit 2)
+
+**Files:**
+
+- Modify: `packages/billing/package.json`, and `packages/billing/scripts/{build,test,coverage,deployAll,prepublish,security}`, the `yarn` lines only.
+- Modify: `scripts/contracts-migration/{manifest,reference}.json`, root `README.md` (package table), root `CLAUDE.md` (package list), `pnpm-lock.yaml`.
+
+**Interfaces:**
+
+- Consumes `billing-ref.json` (Task 1).
+- Produces these `package.json` scripts:
+  - `build` = `pnpm build:self`;
+  - `build:self` = `SKIP_LOAD=true scripts/build`;
+  - `test` = `pnpm build && pnpm test:self`;
+  - `test:self`, which runs the mocha suite and exits non-zero on failure;
+  - `test:coverage` and `test:coverage:self`, which write `coverage/coverage-final.json` so the CI upload step finds it;
+  - `clean`;
+  - `deploy:all` = `scripts/deployAll`;
+  - and the original `compile`, `flatten`, `typechain` and `verify`.
+
+  The package has no `lint*` script and no `prepare` script.
+
+- [ ] **Step 1: `package.json`.**
+  - Set the name to `@graphprotocol/billing`, add `"private": true`, and keep the version `1.1.0`.
+  - Pin `@openzeppelin/contracts` to `4.7.3` and `arb-bridge-peripherals` to `1.0.11`.
+  - Drop `husky`, `lint-staged`, `@commitlint/*`, `eslint*`, `prettier*`, `solhint*` and the `lint-staged` block.
+  - Add the scripts listed under Interfaces.
+  - Run `pnpm install`. Then check that `node -p "require('@openzeppelin/contracts/package.json').version"`, run in the package, prints `4.7.3`.
+- [ ] **Step 2: `scripts/` edits**, as Global Constraints allow. `scripts/test` keeps `result=0`, because it is imported unchanged. `test:self` is therefore `SKIP_LOAD=true hardhat test`, not `scripts/test`.
+- [ ] **Step 3: Minimal toolchain fixes.** Run `pnpm --filter @graphprotocol/billing build`. Expected: exit 0. Fix install or run failures only by changing dependency versions in `package.json` or adding missing devDependencies such as `ganache-cli`, `ts-node` or `@types/*`. Record each change with its reason. If a fix needs an edit to `hardhat.config.ts`, `tsconfig.json`, a task or a test, stop and report.
+- [ ] **Step 4: Bytecode.**
+  - Add each contract in `billing-ref.json` `hashes` to `manifest.json` as `"<Name>": "packages/billing/build/artifacts/contracts/<path>/<Name>.sol/<Name>.json"`.
+  - Add its hashes to `reference.json`, keeping keys sorted. Copy them from Task 1; never `--write`.
+  - Run `pnpm check:bytecode`. Expected: `OK: <18 + N> contracts match`.
+- [ ] **Step 5: Tests.** Run `pnpm --filter @graphprotocol/billing test:self`. Expected: the same passing count as Task 1, 0 failing.
+- [ ] **Step 6: Failure check.** Temporarily break one assertion, then run `test:self`. Expected: non-zero exit. Revert.
+- [ ] **Step 7: Coverage.** Run `pnpm --filter @graphprotocol/billing test:coverage:self`. Expected: exit 0, and `packages/billing/coverage/coverage-final.json` exists.
+- [ ] **Step 8: Task smoke run**, on a local `npx hardhat node` with its default accounts and a scratch copy of `addresses.json` (`ADDRESS_BOOK=<scratch>/addresses.json`, chainId 1337 entries added there).
+  - `npx hardhat --help` lists every task in `tasks/deployment` and `tasks/ops`.
+  - `deploy-token`, then `deploy-billing` (collector, token and gateway from the local accounts or mock deployments), `deploy-billing-connector` (with `L1TokenGatewayMock` and `InboxMock` from `contracts/tests`), `configure-billing` and `deploy-banxa` run, each with `--network localhost`. Expected: exit 0, with addresses written to the scratch book.
+  - `ops:add-to-many --dry-run`, then without `--dry-run`, with a two-entry depositors file in scratch. Expected: exit 0, and `Billing.userBalances` reflects the deposits.
+  - `ops:pull-all` needs the billing subgraph, whose default URL is the retired hosted service, so only `--help` is run. The PR notes the dead default URL.
+  - `deployAll` isn't run end to end, because it needs two networks and mnemonics. `bash -n scripts/deployAll` must exit 0. Report how far a local run gets.
+- [ ] **Step 9: Docs.** Add one line for `@graphprotocol/billing` in the root README package table and in `CLAUDE.md`'s package list.
+- [ ] **Step 10: Source check.** Run `diff -r <scratch>/billing-ref packages/billing`, with Task 2's exclusions. Expected: only `package.json` and the `yarn` lines in `scripts/`.
+- [ ] **Step 11: Commit** `chore(billing): build and test in the monorepo`.
+- [ ] **Step 12: Verification.**
+  - `pnpm -r --sequential run build`, `pnpm test:scripts`, `pnpm check:bytecode` and `pnpm -r --sequential run test:self` all exit 0.
+  - `pnpm lint`, then `git status --porcelain`. Expected: clean.
+  - Rerun Step 10's `diff -r`. Expected: the same result.
+
+## PR description
+
+The PR description says:
+
+- the two-commit structure, and that auditors read commit 1 as the original code and commit 2 as monorepo glue;
+- the source `diff -r` result;
+- the bytecode result and the deployed-code comparison;
+- the test counts;
+- every dependency version change, with its reason;
+- the smoke-run results;
+- the dead hosted-service URL in `ops:pull-all`.
diff --git a/docs/contracts-removal/design.md b/docs/contracts-removal/design.md
new file mode 100644
index 000000000..f19683e35
--- /dev/null
+++ b/docs/contracts-removal/design.md
@@ -0,0 +1,443 @@
+# Removing `packages/contracts` — Design
+
+Status: draft for review (revision 4: lifecycle rule, ports to 0.8, Ignition and `legacy` simplified)
+Date: 2026-11-03
+
+## Goal
+
+Delete `packages/contracts` (`@graphprotocol/contracts`) and `packages/contracts-test` from the monorepo. Every contract that is still in use moves to a package, its unit tests are rewritten in Foundry, and dead code is deleted. Nothing is deployed by this work.
+
+### Lifecycle rule
+
+Where a contract goes depends on whether we expect to change it:
+
+- **Living contracts**, which we expect to upgrade, are ported to Solidity 0.8 and live in their domain package, next to the 0.8 code they work with. The port preserves behaviour and storage layout, and is audited. It ships onchain only with the contract's next real upgrade.
+- **Frozen contracts**, which we don't expect to change, move unchanged and must produce identical bytecode, ignoring the metadata hash. They stay 0.7.6 in `graph-core` or `graph-token`. If one ever needs a change, it is ported and moved to its domain package as part of that upgrade.
+
+A contract is living if it has been upgraded since Horizon launched or has planned work. Of the contracts in `packages/contracts`, that is RewardsManager, L2Curation and L2GNS, the three whose implementations changed on Arbitrum One and Arbitrum Sepolia after the Horizon deployment. Everything else is frozen.
+
+No package compiles both 0.7.6 and 0.8 contracts.
+
+Out of scope:
+
+- Porting frozen contracts to Solidity 0.8.
+- Any functional change to contract behaviour. Ports change the language version and the compiler pipeline, not what the contracts do. The only observable difference is revert data (§3).
+- Bringing `billing-contracts` into the monorepo. That is a separate sub-project with its own spec.
+
+## Decisions
+
+### 1. npm
+
+- `@graphprotocol/contracts` is frozen at 7.3.0, marked deprecated with `npm deprecate`, and never published again. The git tag `@graphprotocol/contracts@7.3.0` preserves its source, CHANGELOG and docs (`DEPLOYMENT.md`, `TESTING.md`).
+- horizon's and subgraph-service's Ignition modules keep only `deploy:protocol`, which builds fresh stacks for local-network and tests. They read live artifacts from the package that owns each contract. The one-off `deploy:migrate` flow, the Ignition deployment records and the suites that depend on them are deleted. The git tag `ignition-records-final`, on the parent commit of Phase 1 step 6, preserves them (§5). The 7.3.0 tag predates the records, so it doesn't.
+- `@graphprotocol/sdk` is already deprecated in its README (which points to `@graphprotocol/toolshed`). It also gets `npm deprecate`.
+- Known external consumers (graph-network-subgraph, subgraph-studio, network-monitor) pin old versions and are migrated as needed. Addresses come from `@graphprotocol/address-book`, ABIs from `@graphprotocol/interfaces`.
+
+### 2. Package layout
+
+Final dependency graph (arrow = "depends on"):
+
+```
+graph-core          → interfaces
+graph-token         → graph-core, interfaces
+issuance            → graph-core, interfaces
+toolshed            → issuance                         (exists today)
+horizon             → graph-token, graph-core, issuance, toolshed, interfaces
+subgraph-service    → horizon, graph-token, graph-core, toolshed, interfaces
+testing             → graph-core, graph-token, horizon, issuance, subgraph-service, interfaces
+deployment          → graph-core, graph-token, issuance, horizon, subgraph-service
+
+legacy              (new, private, no workspace dependencies)
+```
+
+`subgraph-discovery` is omitted: it is a private, test-only package (`→ graph-token, graph-core, contracts`) that exists until Phase P moves its suite to subgraph-service and deletes it.
+
+Edges to `toolshed`, `hardhat-graph-protocol` and `interfaces` that exist today and don't change are omitted.
+
+Rules that keep this acyclic:
+
+- `issuance` depends on `graph-core` and `interfaces` only. Its code and tests never use horizon, subgraph-service or graph-token, because `horizon → toolshed → issuance` already exists.
+- The 0.7.6 packages (`graph-core`, `graph-token`) do not use `toolshed` or `hardhat-graph-protocol`. They have their own small Hardhat configs. `legacy` has no Hardhat config.
+- `horizon → issuance` is only for deploying RewardsManager from Ignition. It already exists transitively through toolshed.
+- `horizon → graph-token` covers TokenUtils and the artifacts its Ignition modules deploy, including GraphCurationToken and SubgraphNFT.
+- horizon's Ignition modules also deploy L2GNS and L2Curation, which end up in subgraph-service. horizon can't depend on subgraph-service, so those two modules take their artifacts as inputs, and subgraph-service's `deploy:protocol` passes them in (§5).
+
+| Package            | Contracts                                                                                                                                                                                                                                                                                                | Compiler        |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `graph-core`       | Controller, Governed, Pausable, Managed, GraphProxy, GraphProxyAdmin, GraphProxyStorage, GraphUpgradeable, EpochManager, EpochManagerStorage                                                                                                                                                             | solc 0.7.6 only |
+| `graph-token`      | GraphToken (mainnet), L2GraphToken, GraphTokenUpgradeable, TokenUtils, GraphTokenGateway (base), L1GraphTokenGateway, L2GraphTokenGateway, BridgeEscrow, L1ArbitrumMessenger, L2ArbitrumMessenger, AddressAliasHelper, GraphCurationToken, SubgraphNFT, SubgraphNFTDescriptor, HexStrings, Base58Encoder | solc 0.7.6 only |
+| `subgraph-service` | L2GNS, L2GNSStorage, GNS, GNSStorage, L2Curation, CurationStorage, Multicall, ported to 0.8                                                                                                                                                                                                              | solc 0.8 only   |
+| `issuance`         | RewardsManager, RewardsManagerStorage, MathUtils, ported to 0.8                                                                                                                                                                                                                                          | solc 0.8 only   |
+| `legacy`           | Verified source of the seven mainnet implementations, as plain files (see "legacy package" below)                                                                                                                                                                                                        | none            |
+
+Why the frozen discovery contracts go to `graph-token`:
+
+- GraphCurationToken is an ERC20 and SubgraphNFT is an ERC721, so `graph-token` holds the protocol's token contracts. The NFT helpers (SubgraphNFTDescriptor, HexStrings, Base58Encoder) go with SubgraphNFT.
+- `graph-token` already uses OpenZeppelin 3.4.2 under its real name, which both need, and already depends on `graph-core` for Governed.
+- The ported contracts reach them only through interfaces (`ISubgraphNFT`, `IGraphCurationToken`) and addresses, never through source.
+
+Deleted, with no replacement:
+
+- Staking: L2Staking. The Arbitrum proxy now runs HorizonStaking.
+- AllocationExchange, EthereumDIDRegistry, SubgraphAvailabilityManager.
+- The Arbitrum DisputeManager and ServiceRegistry, along with their storage contracts.
+- Mocks under `contracts/tests/` that no ported test needs: ArbSysMock, `tests/ens/*`, LegacyGNSMock, MockERC165, MockIssuanceAllocator, MockRewardsEligibilityOracle, MockSubgraphService, and both L1GraphTokenLockTransferTool mocks.
+- Each mainnet-only contract is deleted from `packages/contracts` only after its verified source exists in `legacy`.
+
+The test-only `subgraph-discovery` package created in Phase T is deleted in Phase P, when its tests move to subgraph-service.
+
+#### legacy package
+
+- A frozen, private archive of the source that actually runs on mainnet, for GraphToken, L1GraphTokenGateway, BridgeEscrow, L1GNS, Curation, L1Staking and StakingExtension. Mainnet is deprecated: only the GRT contracts are still in use there.
+- Current source reproduces only Curation. GraphToken was built with solc 0.7.4, and nine files shared between the implementations, including `Managed.sol`, differ from one implementation to the next. So each contract keeps its own bundle.
+- Each bundle is `verified/<Contract>/`: the Sourcify-verified sources, unchanged, with the compiler version and settings. All seven were compiled locally and reproduce mainnet when the package was created. The README links each one to its Etherscan and Sourcify pages, which remain the authority.
+- No compiler, no RPC and no mainnet comparison. The only check left is `test:self` hashing every file under `verified/` against the `sourceHashes` in its bundle's `compiler.json`, so an edit or a formatter run on archived source fails CI. It has no Solidity imports from the workspace and no Hardhat config. Formatters and linters must not touch `verified/`; the root and package ignore files that D2 added stay.
+- `addresses.json` holds every L1 entry (see address-book in §5).
+- graph-token keeps its current source for GraphToken, L1GraphTokenGateway and BridgeEscrow, and its README says this is not the code running on mainnet.
+- Historical audit reports from `packages/contracts/audits/` (29 PDFs) move to `packages/legacy/audits/`.
+
+### 3. Compiler
+
+Frozen contracts move unchanged, so moving them changes no bytecode. For mainnet-only implementations, the record of what is deployed is `legacy`, not the package that holds the current source. Some frozen contracts can't be upgraded in place and stay 0.7.6 forever:
+
+- GraphToken (mainnet)
+- Controller
+- GraphProxyAdmin
+- SubgraphNFT
+- GraphCurationToken (the clone master; `setCurationTokenMaster` can point new pools at a new master, but existing pools keep theirs)
+
+The 0.7.6 settings must reproduce the current build exactly: solc 0.7.6, optimizer enabled, 200 runs, no `evmVersion`, no `viaIR`, default metadata. Everything else follows from that.
+
+#### graph-core and graph-token
+
+- Each has a single Hardhat compiler: 0.7.6 with the settings above.
+- graph-token depends on OpenZeppelin `contracts` and `contracts-upgradeable` 3.4.2 under their real names.
+- graph-core has no OpenZeppelin imports of its own except EpochManager's SafeMath. It reaches `IERC20` through `IGraphToken`, so it depends on OpenZeppelin `^5.4`, whose `IERC20` uses `>=0.4.16`. That keeps graph-core importable from 0.7.6 code, 0.8 code and 0.8 Foundry tests. EpochManager's SafeMath import is rewritten to the alias `@openzeppelin/contracts-v3` (OpenZeppelin 3.4.2), listed in `dependencies` because graph-core publishes its sources. This combination was verified to produce identical creation and runtime bytecode for EpochManager. The alias is allowed only in graph-core (CI grep check), and its warnings are filtered in graph-core's Hardhat config.
+- `packages/deployment` always uses these packages' own 0.7.6 artifacts. That includes GraphProxy, GraphProxyAdmin and Controller, which are deployed from 0.7.6 builds.
+- The graph-core files that 0.8 code imports keep the dual pragma `^0.7.6 || ^0.8.27`. Managed has had it since Phase 1 step 1; it was verified to compile under 0.8.35.
+- graph-token adds `arbos-precompiles` (needed by L2ArbitrumMessenger).
+- `TokenUtils` (in graph-token) also keeps its dual pragma. It is imported as source by 0.8 code in horizon (HorizonStaking, GraphPayments, PaymentsEscrow) and subgraph-service (SubgraphService, DisputeManager, AllocationManager, AllocationHandler), and, after Phase P, by L2Curation and GNS.
+
+#### Ports to 0.8 (Phase P)
+
+- **What changes:** pragma, SafeMath calls replaced by checked arithmetic, OpenZeppelin 3 imports replaced by OpenZeppelin 5 or local equivalents, and whatever 0.8 requires syntactically (`override` specifiers, `type(uint256).max`, explicit conversions). Nothing else.
+- **Known port points**, from a trial compile of all three under 0.8:
+  - Non-SafeMath arithmetic exists only at `RewardsManager.sol:482` (`+=`), `L2GNS.sol:238` (`+`), `L2GNS.sol:245` (`-`) and `Multicall.sol:23` (`++`). The two L2GNS lines compute the L1-to-L2 subgraph ID alias and rely on wrapping (about 6.7% of IDs would revert under checked arithmetic), so they go in `unchecked`. `test_GetAliasedL2SubgraphID_WrapsAroundMaxUint256` covers it.
+  - OpenZeppelin 5 has no `Address.isContract`. `GNS.sol:838` and `L2Curation.sol:469` use `.code.length` instead.
+  - `GNS._buildSubgraphID` reads `chainid()`, so it changes from `pure` to `view`. This was the only compile error.
+  - The ported contracts are compiled without `viaIR`, like the 0.7.6 build, so the port changes the language version but not the code generation pipeline (see Compiler settings).
+- **Storage layout is identical.** `CurationV2Storage` and `GNSV3Storage` inherit OpenZeppelin 3's `Initializable`, whose `_initialized` and `_initializing` sit in ordinary storage slots (slot 16 in L2Curation). OpenZeppelin 5's `Initializable` uses namespaced storage, so it can't be used. The ports keep a local copy with the v3 layout and behaviour under a distinct name, `InitializableV3`, because subgraph-service also compiles OpenZeppelin 5's. RewardsManager has no OpenZeppelin storage. A trial port showed identical layouts slot for slot.
+- **Graph-core and graph-token sources stay as they are.** The ported contracts inherit Managed and GraphUpgradeable (dual pragma) and use TokenUtils (dual pragma). All of them, and every interface they reach, compile under 0.8.
+- **`interfaces` moves to OpenZeppelin 5 (Pa).** Issuance runs Hardhat 3, which resolves imports per package, so `IGraphToken`'s `IERC20` resolves to `interfaces`' own OpenZeppelin. Today that is 3.4.2 (`<0.8.0`), which a 0.8 RewardsManager can't compile. OpenZeppelin 5's `IERC20` and `IERC165` (`>=0.4.16`) and `IERC721` (`>=0.6.2`) still compile under 0.7.6. Hardhat 2 and Foundry packages resolve OpenZeppelin from their own root and are unaffected.
+  - `IGraphCurationToken` stops importing `IERC20Upgradeable`, which OpenZeppelin 5 doesn't have, and extends `IERC20`. Selectors are unchanged, and L2GNS and L2Curation bytecode is identical.
+  - It changes the published package: the generated `IERC20Upgradeable` types disappear, the `IERC165` types move to `utils/introspection`, and ABI parameter names change (for example `transfer(recipient, amount)` becomes `transfer(to, value)`, and `setApprovalForAll`'s `_approved` becomes `approved`). That flows into the wagmi ABIs. Pa ships a `major` changeset for `@graphprotocol/interfaces` that says so.
+  - OpenZeppelin becomes a regular dependency of `interfaces`, not a devDependency, so published Hardhat 3 consumers can resolve it. `@openzeppelin/contracts-upgradeable` is removed.
+- **Revert data changes.** SafeMath reverts with strings; 0.8 reverts with `Panic(0x11)`. Also, `Multicall` re-throws only revert data of at least 68 bytes, so a `Panic` or a short custom error inside a multicall surfaces as empty revert data. Tests that expect the old data are updated, and each Phase P PR lists them.
+- **Compiler settings:** 0.8.35 with `evmVersion: cancun`, optimizer enabled, and no `viaIR`. subgraph-service and issuance both compile with `viaIR` by default, so each adds a per-file `solidity.overrides` entry for its ported files. Neither the language version nor the size limit needs `viaIR`, and keeping the legacy pipeline leaves the auditors one less change to review. Trial sizes with optimization: RewardsManager 10.6KB, L2GNS 16.9KB, L2Curation 9.6KB, all under the 24KB limit; Pb and Pc confirm them without `viaIR`.
+
+### 4. Tests
+
+- `packages/contracts-test` is deleted. Each package owns its unit tests, written in **Foundry**, following the existing suites in horizon, subgraph-service and issuance:
+  - a shared base test contract (`GraphBase.t.sol`, `SubgraphBaseTest.t.sol`);
+  - `shared/` helpers and `mocks/`;
+  - the same directory layout, naming and fuzzing style.
+
+  Each new package copies the conventions of its nearest neighbour.
+
+- Tests are written **before** the contracts move (Phase T):
+  - Test files are 0.8, because forge-std needs `>=0.8.13`. They never import 0.7.6 source.
+  - They deploy the contracts under test from compiled artifacts:
+    - **Before the move:** the Hardhat JSON in `@graphprotocol/contracts/artifacts`, read with `vm.readFile` + `vm.parseJsonBytes(".bytecode")` and deployed with `create`. `packages/testing/test/harness/RealRewardsHarness.t.sol` is the template.
+    - **After a frozen move:** in graph-core and graph-token, Foundry compiles the 0.7.6 sources itself, and tests switch to `deployCode("X.sol:X")` so coverage registers. Each package pins its sources with `compilation_restrictions` and sets the optimizer to 200 runs. Unpinned, Foundry compiles dual-pragma contracts as 0.8.35, so tests would exercise code that isn't deployed. Contracts from another package stay on that package's Hardhat artifacts.
+    - **After a port:** the contract is 0.8 source in its package, and tests use it directly.
+  - Tests interact through interfaces they can compile under 0.8:
+    - In graph-core and in OpenZeppelin-5 packages (horizon, subgraph-service, issuance), they use `@graphprotocol/interfaces`.
+    - In graph-token (OpenZeppelin 3.4.2), `IGraphToken`, `ISubgraphNFT` and `IGraphCurationToken` can't be imported from 0.8. Tests there use local minimal interfaces or OpenZeppelin 5's `IERC20` from a test-only remapping.
+  - Mocks are 0.8 contracts in the test tree. If a mock needs a 0.7.6 base, it is deployed from an artifact instead.
+  - Each package lists its artifact folders explicitly in `foundry.toml` `fs_permissions`, because pnpm symlinks point outside the package.
+  - `forge test` depends on Hardhat artifacts, so each package's `test` script builds first. That already holds where `test` runs `pnpm build`.
+- **Differential tests for ports.** The suites for ported contracts were written against the 0.7.6 artifacts. After the `git mv`, nothing builds those artifacts any more, and the 7.3.0 npm package is stale (its RewardsManager has no `reclaimRewards`). So each Phase P PR first commits the pre-port Hardhat artifacts of its contracts as test fixtures under `test/fixtures/pre-port/`, with `fs_permissions` entries. The same suite then runs against those fixtures and against the new 0.8 build, and both must pass. Expected differences are limited to revert data, and are listed.
+- **Shared fixture.** Upgradeable contracts have an `onlyImpl` `initialize`, so they must sit behind a GraphProxy and be activated through GraphProxyAdmin `upgrade` + `acceptProxyAndCall`. Each package's base test contract has a small helper that:
+  - deploys Controller and GraphProxyAdmin from graph-core's artifacts;
+  - unpauses the protocol (the Controller constructor leaves it paused);
+  - registers mocks with `setContractProxy` and calls `syncAllContracts`;
+  - deploys the contract under test behind a proxy.
+
+  Contract-specific setup the ports must reproduce:
+  - **L2GNS:** SubgraphNFT (minter and descriptor set), a real L2Curation with a GraphCurationToken master, an L2GraphToken with a minter, and a registered L2 gateway.
+  - **L2Curation:** `setSubgraphService` before `collect`.
+  - **L2GraphTokenGateway:** `vm.mockCall` / `vm.etch` at ArbSys `0x64`.
+
+- **Unit tests use mocks, not the full network.** A test deploys only the contract under test plus mocks for its dependencies. Issuance tests in particular mock EpochManager, Curation, Staking, GRT and the subgraph service, and never load artifacts from horizon or subgraph-service (see the acyclicity rules in §2). The old rewards tests that went through legacy Staking (restaking, rewards destination, delegation cut) keep their RewardsManager assertions as mock-based unit tests. Their Staking assertions are dropped: that is legacy Staking behaviour, and the Horizon equivalent is already tested in subgraph-service. `packages/testing` stays the home for new cross-package flows.
+- **Coverage.** Phase 0d records per-contract **line** coverage from `contracts-test` (solidity-coverage) before anything changes. Branch numbers aren't comparable between solidity-coverage and `forge coverage`, so they're informative only.
+  - Every function the baseline hits must still be hit by `forge coverage` once the contract is in its final package: after the move for frozen contracts, after the port for living ones. Line percentages aren't gated, because the two tools count lines differently (Multicall is 6/8 in the baseline and 6/9 in forge with the same 6 hits), so any file below its baseline percentage is listed in the PR with a reason.
+  - Frozen contracts whose behaviour is exercised from another package's tests (SubgraphNFT and GraphCurationToken through the L2GNS and L2Curation suites) get direct unit tests in graph-token for any baseline function those suites no longer reach there.
+
+#### Test assignment
+
+| Destination      | Source tests (`contracts-test/tests/unit`)                                                                                                                | Approx. lines |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| issuance         | `rewards/*` except `subgraphAvailability.test.ts`                                                                                                         | 6.8k          |
+| subgraph-service | `l2/l2GNS.test.ts`, `l2/l2Curation.test.ts`, `lib/gnsUtils.ts` (written in the test-only `subgraph-discovery` package in T3; moved in Phase P)            | 1.8k          |
+| graph-token      | `gateway/*`, `l2/l2GraphToken.test.ts`, `l2/l2GraphTokenGateway.test.ts`, `l2/l2ArbitrumMessengerMock.ts`, `graphToken.test.ts`, `lib/graphTokenTests.ts` | 1.6k          |
+| graph-core       | `governance/*`, `upgrade/admin.test.ts`, `epochs.test.ts` (written in horizon in T4; moved in Phase 1 step 4)                                             | 0.7k          |
+
+Notes:
+
+- Today `l2GNS.test.ts` stakes and allocates through L2Staking. Its port uses a staking mock instead.
+- `controller.test.ts`, `pausing.test.ts` and `admin.test.ts` use EpochManager, Staking and Curation. Their ports use Managed or GraphUpgradeable mocks instead.
+- `l2GraphTokenGateway.test.ts` uses RewardsManager. Its port uses a plain callhook receiver mock.
+- `lib/gnsUtils.ts` is also imported by `gns.test.ts`, which is dropped. T3 deletes `gns.test.ts` together with `gnsUtils.ts`.
+
+Dropped, because their contracts are deleted or legacy:
+
+- `gns.test.ts`: it tests L1GNS and is already `describe.skip`.
+- `curation/*` (L1 Curation), `disputes/*`, `payments/*`, `serviceRegisty.test.ts`.
+- `staking/*`, `l2/l2Staking.test.ts`, `rewards/subgraphAvailability.test.ts`.
+
+#### Mocks needed by ported tests
+
+| Mock                                                                                 | Destination          |
+| ------------------------------------------------------------------------------------ | -------------------- |
+| GovernedMock, ManagedMock (new, 0.7.6)                                               | graph-core           |
+| BridgeMock, InboxMock, OutboxMock, CallhookReceiverMock, TokenUtilsMock (new, 0.7.6) | graph-token          |
+| New 0.8 test mocks for the issuance allocator, eligibility oracle and rewards issuer | issuance's test tree |
+
+ManagedMock and TokenUtilsMock are added to `packages/contracts/contracts/tests/` in Phase T, because 0.8 tests can't compile a Managed contract or call the TokenUtils library. They move with their packages in Phase 1. ArbSysMock is not used (ArbSys is faked with `vm.mockCall`), so it stays on the delete list.
+
+Every test-port PR includes a table mapping each old test case to its new Foundry test, or to "dropped" with a reason. Every Phase P PR includes the list of tests whose expected revert data changed.
+
+### 5. Tooling and infrastructure
+
+#### Ignition
+
+Ignition deployed Horizon in 2025. Since then, RewardsManager, L2Curation and L2GNS have been upgraded through `packages/deployment`, so the Ignition deployment records already don't describe what's onchain. Ignition's only remaining job is `deploy:protocol`: building a fresh protocol on a local chain, for local-network (`containers/core/graph-contracts/run.sh`) and tests. `packages/deployment` can't do that today, because it only deploys implementations into existing proxies and new components; replacing Ignition there is out of scope.
+
+- **Deleted:**
+  - the `deploy:migrate` tasks, `ignition/modules/migrate/`, the `migrate.*` configs, and the `Migrate*` modules exported from shared module files;
+  - the `ServiceRegistry` module, the `LegacyDisputeManager` reference in the `DisputeManager` module, and the `legacyDisputeManagerAddress` and `legacyServiceRegistryAddress` parameters in the protocol configs (local-network writes those address-book stubs itself);
+  - `ignition/deployments/` (horizon-arbitrumOne, horizon-arbitrumSepolia, subgraph-service-arbitrumOne, subgraph-service-arbitrumSepolia);
+  - `scripts/pre-verify`, `post-verify`, `flatten-verify` and `verify-debug`, which exist only to verify Ignition deployments on live networks;
+  - Tenderly's `externalArtifacts` and the `L2Curation` and `RewardsManager` entries in horizon's `verifyList`, and subgraph-service's `tenderly.config.json` if it holds nothing else. `tenderly:upload` itself works from `addresses.json` and stays. If toolshed's Tenderly exports change, toolshed gets a changeset;
+  - the integration suites and everything that only serves them: `test/integration`, `scripts/integration`, the `test:integration` task, `addresses-integration-tests.json`, `tasks/test/{seed,ownership}.ts`, and `tasks/transitions/delegation-slashing.ts` (after checking ops don't use it), in both packages. They replay the migration on a fork and depend on data seeded before it;
+  - the deployment tests: `test/deployment` and the `test:deployment` scripts in both packages. They load the `migrate.*` configs and are gated on migration steps;
+  - the README and `CLAUDE.md` sections for `deploy:migrate`, `test:integration` and `test:deployment`.
+- **Kept:** `deploy:protocol` and its modules. Every artifact import reads the live artifact from the package that owns the contract. No npm alias for 7.3.0 is used. A CI job runs `deploy:protocol` on a local Hardhat network, since it's Ignition's only remaining job and local-network depends on it.
+- **L2GNS and L2Curation after Phase P.** Their deployment stays in horizon's periphery modules, which already handle ownership: the governor accepts Controller and GraphProxyAdmin at the end of the horizon module, and the periphery wiring runs before that. Only their artifacts change package. horizon can't import subgraph-service's artifacts, so the two modules take the L2GNS and L2Curation artifacts as inputs, and subgraph-service's `deploy:protocol` passes them. The address-book writes don't change, so local-network keeps reading `L2Curation` and `L2GNS` from `horizon.json`. horizon's own `deploy:protocol` task, which deploys without the subgraph service and isn't used by local-network, is deleted in Pc.
+
+#### `packages/deployment`
+
+- The `'contracts'` artifact source is replaced by one source per package: `graph-core`, `graph-token`, `issuance`, `horizon`, `subgraph-service`. This touches:
+  - `lib/artifact-loaders.ts`, `lib/contract-registry.ts`, `lib/deploy-implementation.ts`, `lib/deployment-validation.ts`
+  - `scripts/generate-abis.ts`, `test/bytecode-comparison.test.ts`
+  - `docs/Design.md`, and the `package.json` dependency and `build:clean` script
+- `tasks/verify-contract.ts` gets cases for the new packages. Each new package has a Hardhat config with `hardhat-verify`.
+- Phase 1 step 1 also added `subgraph-discovery` cases. Step 3 removes them, since no artifact comes from that package any more.
+- After Phase P, the RewardsManager, L2Curation and L2GNS registry entries point at their 0.8 artifacts. Their next deployment ships the port, and `sync` against a fork reports them as changed until then.
+
+#### `packages/testing`
+
+- Imports switch to `graph-core`.
+- The RewardsManager artifact path moves to issuance in Phase P, along with `foundry.toml` `fs_permissions`.
+- The PR checks that `RealRewardsHarness` loads the real RewardsManager. Today it silently falls back to a mock if the artifact is missing.
+
+#### Removed tooling and CI
+
+- `packages/contracts/task` (`@graphprotocol/contracts-task`, the old sdk-based ops tooling) is deleted, not ported. `packages/deployment` replaces it.
+- `.github/workflows/verifydeployed.yml` is deleted. It depends on contracts-task.
+- `publish.yml` drops `contracts` and adds `graph-core` and `graph-token`.
+- The root `lint:yaml` drops `packages/contracts/task/config`.
+- `count-patterns.txt` paths are updated.
+- `@graphprotocol/sdk` is removed from the `pnpm-workspace.yaml` catalog and from `minumumReleaseAgeExclude` (the key's real, misspelled name).
+- `build-test.yml` finds coverage files itself, so it needs no change for the removed packages or the new ones.
+- The Docker image (`Dockerfile`, `publish-image.yml`) is checked for use of `packages/contracts` or the sdk before deletion.
+
+#### token-distribution
+
+- Its three tests that import `Staking` / `Staking__factory` switch to an interface from `@graphprotocol/interfaces` or a local mock.
+- The `@graphprotocol/contracts` dependency is removed.
+
+#### address-book
+
+Address books are copied from each package into `address-book/src/<name>/addresses.json`, tracked as regular files, and listed in `address-book/scripts/sources.js`.
+
+- New `packages/legacy/addresses.json` with every L1 entry from `packages/contracts/addresses.json`:
+  - mainnet (1) and Sepolia (11155111);
+  - including Controller, EpochManager, RewardsManager, DisputeManager, ServiceRegistry, GraphProxyAdmin and SubgraphNFT. It is the L1 deployment record, even for contracts whose source isn't in `legacy`.
+- `'legacy'` is added to `sources.js`.
+- GraphCurationToken and SubgraphNFTDescriptor (live on Arbitrum One and Arbitrum Sepolia, today only in `packages/contracts/addresses.json`) are added to `horizon/addresses.json`.
+- L2 entries stay in `horizon/`, where they are today, including L2GNS and L2Curation after they move to subgraph-service. The address book doesn't follow the source package.
+- Dropped:
+  - Goerli (5) and Arbitrum Goerli (421613);
+  - Arbitrum entries for deleted contracts;
+  - `arbitrum-addresses.json` (Arbitrum bridge infra, used only by the sdk);
+  - `addresses-staging.json` and `addresses-local.json`.
+
+#### Publishing
+
+`graph-core` and `graph-token` follow issuance's package setup:
+
+- `files`: contracts, artifacts, types and README
+- `license: GPL-2.0-or-later`
+- starting version 1.0.0
+- an initial changeset
+
+horizon and subgraph-service add the new packages as devDependencies, the same way they list `@graphprotocol/contracts` today. They publish build output only. `legacy` is `"private": true`.
+
+#### Docs and references updated
+
+- Root `CLAUDE.md`, `README.md` and `.gitignore`.
+- `docs/IGraphProxyAdminInterfaceFix.md`, `docs/ForgeLintSymlinkIssue.md`, `docs/Linting.md`.
+- `issuance/docs/testing/reo/*TestPlan.md`.
+- toolshed's `src/deployments/{horizon,subgraph-service}/contracts.ts` comments.
+
+## PR sequence
+
+Tests are ported first, against the contracts where they are today. Then dead code and the old suite are removed. Then the frozen contracts move, bottom-up, and the tooling is simplified. Then the living contracts are ported and moved. Last, `packages/contracts` is deleted. Because of this order, `packages/contracts` never imports from a package that depends on it, so there are no cyclic workspace dependencies. Every PR leaves the build, all test suites and `packages/deployment` working.
+
+### Phase 0: preparation
+
+- **0a.** Delete `packages/contracts/task`, `verifydeployed.yml`, and the root `lint:yaml` entry.
+- **0b.** Move token-distribution's tests off the `Staking` types and drop its `@graphprotocol/contracts` dependency.
+- **0c.** Add a bytecode equivalence check that builds on the existing `scripts/compare-repo-contract-bytecode-excluding-metadata.mjs` and `scripts/bytecode-diff.sh`. It compares bytecode with metadata stripped for:
+  - every moved 0.7.6 contract, against a reference committed from the current `packages/contracts` build;
+  - the 0.8 contracts whose imports change (HorizonStaking, GraphPayments, PaymentsEscrow, SubgraphService, DisputeManager and their libraries), against the current horizon and subgraph-service builds.
+
+  Every later PR that moves frozen contracts must pass it. Ported contracts leave the check in their Phase P PR, which replaces it with the port checks (Verification).
+
+- **0d.** Run `contracts-test` coverage and commit the per-contract line coverage as the parity baseline.
+
+### Phase T: Foundry test ports (parallel)
+
+Each PR:
+
+- creates the destination package skeleton if needed: `package.json`, `foundry.toml` and `test/`. The 0.7.6 Hardhat config (graph-core and graph-token don't use toolshed) comes in Phase 1 with the contracts, since there is nothing to compile before then;
+- adds `@graphprotocol/contracts` as a temporary devDependency;
+- writes the Foundry tests against its artifacts, following §4;
+- deletes the matching TypeScript tests from `contracts-test`.
+
+New packages aren't published yet: they stay `"private": true` until their contracts move in Phase 1.
+
+- **T1.** graph-core. Also proves the 0.8-tests-against-0.7.6-artifacts pattern and the shared proxy/Controller fixture.
+- **T2.** graph-token.
+- **T3.** L2GNS and L2Curation, in a test-only `subgraph-discovery` package. Also deletes `gns.test.ts` and `lib/gnsUtils.ts`.
+- **T4.** horizon (epochs).
+- **T5.** issuance (rewards, with mocks only). This PR may be split by test file group.
+
+The detailed task split is in `phase-t-plan.md`.
+
+### Phase D: removal of dead code
+
+- **D1.** Delete `packages/contracts-test` and the `test` / `test:coverage` scripts in `packages/contracts`. Remove `@graphprotocol/sdk` (catalog and `minumumReleaseAgeExclude`). `build-test.yml` finds coverage files itself, so it needs no change. All live tests have been ported by now.
+- **D2.** Create `legacy` from the verified bundles. Add `legacy/addresses.json` and the `sources.js` entry, and move the audits to `legacy/audits/`.
+- **D3.** Delete from `packages/contracts` exactly these contract files, plus their storage contracts where listed:
+  - L1GNS, L1GNSStorage, Curation, BancorFormula;
+  - Staking, L1Staking, L1StakingStorage, StakingExtension, StakingStorage, Stakes, Exponential, LibFixedMath, L2Staking;
+  - DisputeManager, DisputeManagerStorage, ServiceRegistry, ServiceRegistryStorage;
+  - AllocationExchange, EthereumDIDRegistry, SubgraphAvailabilityManager.
+
+  Also delete:
+  - the unused mocks listed in §2;
+  - `addresses-staging.json`, `arbitrum-addresses.json`;
+  - `config/`, and `configDir` in `index.js`.
+
+  Live files that also appear in `legacy` bundles stay: Multicall, GNS, GNSStorage, CurationStorage, Managed, GraphUpgradeable, TokenUtils and MathUtils. Nothing that remains imports a deleted file. L1GNS, Curation, L1Staking, StakingExtension and LibExponential leave the 0c manifest.
+
+After D3, `packages/contracts` contains only live contracts and the mocks ported tests use.
+
+Phase D landed with two pieces that revision 4 simplifies: D2's `test:self` check against mainnet bytecode, and an npm alias that made Ignition read 7.3.0 artifacts. Phase 1 steps 5 and 6 remove them.
+
+### Phase 1: frozen moves and tooling cleanup (one PR each, `git mv` to keep history)
+
+Each move PR:
+
+- moves the files;
+- switches every consumer's Solidity imports, `deployment` sources and test artifact paths;
+- passes 0c;
+- removes the moved package's temporary `@graphprotocol/contracts` devDependency;
+- flips the moved package to published (drops `"private"`, adds a `publish.yml` option and an initial changeset).
+
+| Step | What                                                                                            | Edges added                                                                                                                                              |
+| ---- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | graph-core: governance and proxy contracts                                                      | contracts, horizon, subgraph-service, testing, deployment → graph-core. graph-token, subgraph-discovery, issuance → graph-core (test devDependency)      |
+| 2    | graph-token: token and bridge contracts                                                         | contracts, horizon, subgraph-service, testing, deployment → graph-token. graph-token → graph-core. subgraph-discovery → graph-token (test devDependency) |
+| 3    | graph-token: GraphCurationToken, SubgraphNFT, SubgraphNFTDescriptor, HexStrings, Base58Encoder  | none                                                                                                                                                     |
+| 4    | graph-core: EpochManager, EpochManagerStorage                                                   | none                                                                                                                                                     |
+| 5    | `legacy`: remove the mainnet bytecode check                                                     | none                                                                                                                                                     |
+| 6    | Ignition: delete the migrate flow and verification tooling, read live artifacts, drop the alias | none                                                                                                                                                     |
+
+Per-step notes:
+
+1. **graph-core.**
+   - Generalizes `deployment`'s artifact loader to one source per package, and adds the new package cases to `tasks/verify-contract.ts`.
+   - Points `CORE_ARTIFACTS` in the Foundry fixtures of graph-token, subgraph-discovery, horizon and issuance at graph-core, with `fs_permissions` entries, because Controller, GraphProxy and GraphProxyAdmin leave `packages/contracts` here while those packages' own contracts don't.
+   - Switches `packages/testing`'s Solidity imports.
+2. **graph-token.**
+   - Adds `testing → graph-token`, because `packages/testing` compiles horizon's sources, which import TokenUtils.
+   - Changes the L2GraphToken path in subgraph-discovery's `DiscoveryTest.t.sol` to a `TOKEN_ARTIFACTS` constant pointing at graph-token's artifacts, with its `fs_permissions` entry and a test devDependency.
+3. **Frozen discovery contracts into graph-token.**
+   - Nothing left in `packages/contracts` imports these files' source. L2GNS and L2Curation use them through interfaces.
+   - subgraph-discovery's tests load them from `TOKEN_ARTIFACTS`.
+   - Adds GraphCurationToken and SubgraphNFTDescriptor to `horizon/addresses.json`.
+   - Adds graph-token unit tests for any baseline function of these files that its own suite doesn't hit (§4 Coverage).
+   - Removes the `subgraph-discovery` cases from `packages/deployment`.
+   - Keeps the `RewardsHook.t.sol` and `Multicall.t.sol` tests that #1396 added to subgraph-discovery's suite. #1396 itself is closed.
+4. **EpochManager into graph-core.**
+   - Adds the `@openzeppelin/contracts-v3` alias to graph-core for EpochManager's SafeMath, and a CI grep rule limiting the alias to graph-core.
+   - Moves horizon's EpochManager tests (T4) to graph-core, on `deployCode`, so coverage registers.
+5. **`legacy` simplified.** Deletes the compile and mainnet scripts, `mainnet.json`, `targets.json` and the solc-js dependencies. `test:self` keeps only the source-hash check (§2). Keeps `verified/`, `addresses.json` and `audits/`, and rewrites the README with Etherscan and Sourcify links for each bundle.
+6. **Ignition simplified** as §5 describes. Before the change, tag its parent commit `ignition-records-final`, once that commit is in the base branch and won't be rewritten. Every remaining module imports live artifacts: Controller, GraphProxy, GraphProxyAdmin and EpochManager from graph-core; L2GraphToken, L2GraphTokenGateway, GraphCurationToken, SubgraphNFT and SubgraphNFTDescriptor from graph-token; RewardsManager, L2GNS and L2Curation from `@graphprotocol/contracts` until Phase P. Removes the `@graphprotocol/contracts-7.3.0` alias. Adds the `deploy:protocol` CI job.
+
+### Phase P: ports of living contracts to 0.8
+
+Each port PR has two commits: a `git mv` into the destination package, then the port. Reviewers and auditors read the second commit. The first commit doesn't build on its own; the PR says so. Before the first PR, tag the last commit where these contracts are 0.7.6, so the deployed source is one checkout away.
+
+Like the rest of this stack, Phase P PRs reach `main` only after the audit covers their port commits. From then on, `main` holds only audited code. A hotfix to one of these contracts can either ship the audited 0.8 version or branch from the pre-port tag and patch the 0.7.6 code that is deployed; the second avoids making an emergency fix the port's first deployment. A hotfix made from the tag is ported into `main` afterwards.
+
+- **Pa. interfaces to OpenZeppelin 5.** Raises `interfaces`' OpenZeppelin to `^5.4` as a regular dependency, removes `contracts-upgradeable`, and changes `IGraphCurationToken` to extend OpenZeppelin 5's `IERC20` (§3). Adds a `major` changeset describing the type and parameter-name changes. Checks that the 0.7.6 builds in graph-core and graph-token, and the bytecode check, are unaffected.
+- **Pb. RewardsManager, RewardsManagerStorage and MathUtils into issuance.**
+  - Issuance stays 0.8 only.
+  - Its T5 suite runs against both builds (§4 Differential tests).
+  - Ignition's RewardsManager import and `packages/testing`'s `RM_ARTIFACT` move to issuance's artifacts. The deployment registry entry moves to `issuance`. `RealRewardsHarness` must report 0 skipped.
+  - Scheduled when no RewardsManager PRs are in flight.
+- **Pc. L2GNS, GNS, L2Curation, their storage contracts and Multicall into subgraph-service.**
+  - Adds `InitializableV3`.
+  - Moves the T3 suite from `subgraph-discovery` to subgraph-service, runs it against both builds, and deletes the `subgraph-discovery` package.
+  - horizon's L2GNS and L2Curation modules take their artifacts as inputs, subgraph-service's `deploy:protocol` passes them, and horizon's own `deploy:protocol` task is deleted (§5).
+  - The deployment registry entries move to `subgraph-service`.
+  - Scheduled when no L2GNS or L2Curation PRs are in flight.
+
+### Phase 2: final removal
+
+- **2a.** Delete the now-empty `packages/contracts` and every remaining reference:
+  - `count-patterns.txt` and the `publish.yml` `contracts` option;
+  - the docs listed in §5;
+  - after checking that the Docker image no longer uses `packages/contracts`.
+- **2b.** Run `npm deprecate` on `@graphprotocol/contracts` and `@graphprotocol/sdk`. This is a manual step after 2a.
+
+## Verification
+
+- **Every frozen move:**
+  - 0c passes.
+  - `pnpm build` and `pnpm test` pass across the workspace.
+  - `packages/deployment` sync against an Arbitrum Sepolia fork reports the same output as the parent commit. Some contracts already differ from what's deployed, so the output is compared rather than required to show no changes. A deployment test loads every registry artifact, because sync can't see a missing one.
+- **Every port:**
+  - The storage layout of the 0.8 build equals the 0.7.6 build's, slot for slot, compared with `forge inspect <Contract> storageLayout` (Hardhat 2 doesn't emit layouts by default).
+  - The ported contract's suite passes against both builds, with only the listed revert-data differences.
+  - The 0.8 build fits the 24KB limit.
+  - `pnpm build` and `pnpm test` pass across the workspace, and the `deploy:protocol` CI job passes.
+  - Fork sync reports only the ported contracts as changed, compared with the parent commit.
+- **Test-port PRs:**
+  - the mapping table is complete;
+  - every function the 0d baseline hits is still hit once the contract is in its final package.
+- **Final:** a repo-wide search for `@graphprotocol/contracts` returns nothing outside the root `@graphprotocol/contracts-monorepo` name, the lockfile, the CHANGELOGs, this design folder, the test-mapping tables and `packages/legacy/verified`.
+
+## Risks
+
+- **Merge conflicts.** RewardsManager, L2GNS and L2Curation are under active development. Keep Phase P PRs short-lived, and coordinate timing with open work.
+- **A port changes behaviour.** Mitigated by the storage-layout check, differential tests against the 0.7.6 build, and the audit of the port commit. `InitializableV3` and the L2GNS alias arithmetic are the most sensitive pieces.
+- **Repo source differs from what's deployed for ported contracts until their next upgrade.** The pre-port git tag and Sourcify hold the deployed source, and a hotfix can branch from the tag (Phase P).
+- **OpenZeppelin 5 in `interfaces`.** Hardhat 3 consumers resolve `interfaces`' imports with its own OpenZeppelin, and the published types and ABI parameter names change. Pa checks that every package still builds with identical frozen bytecode, and its changeset tells external consumers.
+- **Mainnet source drift.** Current source does not reproduce most mainnet implementations. `legacy` therefore archives the verified source, and graph-token's README says its mainnet contracts aren't the deployed code.
+- **Test port fidelity.** A rewrite can silently drop behaviours. The mapping table and the coverage baseline guard against this.
+- **Library link references.** None of the live moved contracts link libraries.
diff --git a/docs/contracts-removal/phase-0-plan.md b/docs/contracts-removal/phase-0-plan.md
new file mode 100644
index 000000000..8e1dfe09f
--- /dev/null
+++ b/docs/contracts-removal/phase-0-plan.md
@@ -0,0 +1,372 @@
+# Contracts Removal — Phase 0 (Preparation) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Land the four preparation PRs that every later phase depends on:
+
+- 0a: delete the legacy task package.
+- 0b: decouple token-distribution.
+- 0c: a bytecode equivalence check.
+- 0d: a coverage baseline.
+
+**Architecture:**
+
+- 0a and 0b are pure removals and import swaps.
+- 0c adds a small Node script with a committed manifest (contract → artifact path) and reference (contract → hashes of metadata-stripped bytecode). Every later move PR updates the manifest and must keep the hashes identical. CI runs it after the build.
+- 0d adds an lcov summarizer and commits the per-file line coverage of `contracts-test` as the parity baseline for the Foundry ports.
+
+**Tech Stack:** pnpm workspaces, Node 24 (`node:test`, `node:crypto`), Hardhat 2 / solidity-coverage (contracts-test), GitHub Actions.
+
+**Spec:** `docs/contracts-removal/design.md` (sections "PR sequence → Phase 0", §5 "Removed tooling and CI", §5 "token-distribution", §4 "Coverage").
+
+Later phases (T, D, 1, 2) get their own plans, written once Phase 0 has landed, because they depend on what 0c and 0d produce.
+
+## Global Constraints
+
+- **Prerequisite:** merge the `docs/contracts-package-removal-spec` branch (spec and this plan) to `main` before starting, so every task branch has both documents.
+- Package manager: pnpm. Run `pnpm install` after any `package.json` change and commit `pnpm-lock.yaml`.
+- One PR per task. Branch off `main`: `chore/contracts-removal-0a-delete-task`, `…-0b-token-distribution`, `…-0c-bytecode-check`, `…-0d-coverage-baseline`.
+- Commits use conventional messages (`chore:`, `test:`, `feat:`, `ci:`). Do NOT add `Co-Authored-By` lines.
+- No contract source changes in Phase 0.
+- Bytecode comparison strips the exact CBOR metadata blob `a264697066735822<68 hex>64736f6c6343<6 hex>0033`, wherever it occurs. Any other difference, including bytes after the metadata, is a failure.
+- `reference.json` hashes never change. Later PRs may change `manifest.json` paths. Entries are removed from both files only when their contract is deleted.
+- Migration helper files live in `scripts/contracts-migration/`. They are deleted in Phase 2a.
+- Node test runner: always pass a glob such as `node --test 'scripts/**/*.test.mjs'`. On Node 24, a directory argument is treated as a single test file and fails.
+
+## Review Focus
+
+1. **Missing artifact** (package not built, or a stale manifest path). `check-bytecode` must exit 1 and name the missing path on stderr. It must never skip the entry and pass. → Task 3 test `fails when an artifact is missing`.
+2. **Partial reference on `--write`.** If any manifest artifact is missing, `--write` must exit 1 without touching `reference.json`. → Task 3 test `write refuses to produce a partial reference`.
+3. **Metadata-only vs code differences.**
+   - Artifacts that differ only in the metadata hash must pass.
+   - A one-byte difference before the metadata must fail, and so must one after it (GraphProxy, PaymentsEscrow and others have real bytes after the metadata in their creation bytecode).
+   - → Task 3 tests `ignores metadata-only differences`, `detects code differences` and `detects differences after the metadata`.
+4. **Empty bytecode.** A manifest entry pointing at an interface or abstract contract (`bytecode` = `0x`) must fail, not hash the empty string. → Task 3 test `rejects empty bytecode`.
+5. **lcov path normalization.** solidity-coverage writes absolute `SF:` paths whose ancestors can also be named `contracts`; locally and in CI the repo root itself is `contracts`. Keys must be `contracts/…` measured from the _last_ `contracts` segment. `LF:0` gets `pct: null`. → Task 4 tests.
+
+---
+
+### Task 1 (PR 0a): Delete `packages/contracts/task` and `verifydeployed.yml`
+
+**Files:**
+
+- Delete: `packages/contracts/task/` (entire directory; package `@graphprotocol/contracts-task`)
+- Delete: `.github/workflows/verifydeployed.yml`
+- Modify: `package.json` (root) — in `scripts.lint:yaml`, remove `packages/contracts/task/config/*.yml`
+- Modify: `packages/testing/foundry.toml:35-38` — the comment's example path mentions `@graphprotocol/contracts/task/...`. Reword it to "this package's pnpm-hoisted node_modules" without that example, and keep `lint_on_build = false`.
+- Modify: `pnpm-lock.yaml` (regenerated)
+
+**Interfaces:**
+
+- Consumes: nothing.
+- Produces: no `@graphprotocol/contracts-task` package in the workspace.
+
+- [ ] **Step 1: Confirm nothing else depends on the package**
+
+Run: `grep -rn "contracts-task\|contracts/task" --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=artifacts --exclude-dir=cache . | grep -v '^./packages/contracts/task/' | grep -v '^./docs/contracts-removal/'`
+Expected: only `package.json` (lint:yaml), `pnpm-lock.yaml` and `packages/testing/foundry.toml`.
+
+- [ ] **Step 2: Delete the directory and workflow, then edit the root `lint:yaml` and the `testing/foundry.toml` comment as listed above**
+
+- [ ] **Step 3: Reinstall and build**
+
+Run: `pnpm install && pnpm build`
+Expected: install succeeds with no reference to `@graphprotocol/contracts-task`, and the build succeeds.
+
+- [ ] **Step 4: Run the affected suites**
+
+Run: `pnpm --filter @graphprotocol/contracts-tests test:self && pnpm --filter @graphprotocol/testing test:self && pnpm lint:yaml`
+Expected: all pass. contracts-tests only uses `configDir` from `@graphprotocol/contracts`, never the task package.
+
+- [ ] **Step 5: Commit and open PR**
+
+```bash
+git add -A packages/contracts/task .github/workflows/verifydeployed.yml package.json packages/testing/foundry.toml pnpm-lock.yaml
+git commit -m "chore: remove legacy contracts-task package and verifydeployed workflow"
+```
+
+PR description:
+
+- The task package is replaced by `packages/deployment`.
+- `verifydeployed.yml` is already broken: its `verify-defender` task exists only in the task package. Its network options include dead networks.
+
+---
+
+### Task 2 (PR 0b): Move token-distribution tests off `@graphprotocol/contracts`
+
+**Files:**
+
+- Modify: `packages/token-distribution/test/tokenLockWallet.test.ts:4,215,263`
+- Modify: `packages/token-distribution/test/l2TokenLockManager.test.ts:4,78`
+- Modify: `packages/token-distribution/test/l1TokenLockTransferTool.test.ts:4`
+- Modify: `packages/token-distribution/package.json` — remove the `"@graphprotocol/contracts": "workspace:^"` devDependency
+- Modify: `pnpm-lock.yaml`
+
+**Interfaces:**
+
+- Consumes: the IStaking ABI from `@graphprotocol/interfaces/artifacts/contracts/contracts/staking/IStaking.sol/IStaking.json`, and ethers v5's `Contract` (token-distribution's own `ethers`, 5.8.0). The tests call only `stake(uint256)` and `setController(address)` through `lockAsStaking`, plus the `.address` property.
+- Do NOT use `@graphprotocol/interfaces/types-v5`. At runtime its factories `require("ethers")` from the interfaces package, which is v6, and return v6 contracts without `.address`. Under token-distribution's node10 resolution it also fails to type-check.
+- Produces: token-distribution no longer depends on `@graphprotocol/contracts`.
+
+- [ ] **Step 1: Record the current state on `main`**
+
+Run:
+
+```bash
+cd packages/token-distribution && pnpm build && npx tsc --noEmit --incremental false > /tmp/td-tsc-before.txt
+STUDIO_API_KEY=<key> pnpm test:self 2>&1 | tail -40
+```
+
+Expected: `td-tsc-before.txt` holds the existing type errors, which are pre-existing and unrelated. Record the mocha `passing` count.
+
+- [ ] **Step 2: Swap the imports in all three files**
+
+- Remove the `@graphprotocol/contracts/types` import.
+- Add `import { Contract } from 'ethers'` (merge it into an existing `ethers` import if there is one) and `import IStakingArtifact from '@graphprotocol/interfaces/artifacts/contracts/contracts/staking/IStaking.sol/IStaking.json'`.
+- Replace each `Staking__factory.connect(tokenLock.address, deployer.signer)` with `new Contract(tokenLock.address, IStakingArtifact.abi, deployer.signer)`.
+- Type `lockAsStaking` as `Contract` (in `l2TokenLockManager.test.ts:78`, replace `Staking`).
+
+If `resolveJsonModule` is not enabled in token-distribution's `tsconfig.json`, use `require(...)` the same way other JSON is loaded in that package, rather than changing the tsconfig.
+
+- [ ] **Step 3: Remove the dependency and reinstall**
+
+Remove the devDependency from `packages/token-distribution/package.json`, then run `pnpm install`.
+Expected: the lockfile no longer links `@graphprotocol/contracts` into token-distribution.
+
+- [ ] **Step 4: Type-check for new errors only**
+
+Run: `cd packages/token-distribution && npx tsc --noEmit --incremental false > /tmp/td-tsc-after.txt; diff /tmp/td-tsc-before.txt /tmp/td-tsc-after.txt`
+Expected: no lines that appear only in the "after" file. Hardhat's ts-node runs without type checking, so this is the only type gate.
+
+- [ ] **Step 5: Run the tests**
+
+Run: `cd packages/token-distribution && STUDIO_API_KEY=<key> pnpm test:self 2>&1 | tail -40`
+Expected: the same `passing` count as Step 1, with 0 failing and a non-zero exit code on failure. Without `STUDIO_API_KEY` the script prints a warning and exits 0 without running anything. If no key is available locally, say so in the PR and confirm the count in CI's log, where the key is set.
+
+- [ ] **Step 6: Commit and open PR**
+
+```bash
+git add packages/token-distribution/test packages/token-distribution/package.json pnpm-lock.yaml
+git commit -m "test(token-distribution): use IStaking ABI from interfaces instead of contracts types"
+```
+
+PR description: mention that `scripts/test` skips everything and exits 0 when `STUDIO_API_KEY` is unset. That's out of scope here.
+
+---
+
+### Task 3 (PR 0c): Bytecode equivalence check
+
+**Files:**
+
+- Create: `scripts/lib/bytecode.mjs`
+- Modify: `scripts/compare-repo-contract-bytecode-excluding-metadata.mjs` — delete its local `stripMetadata` and import it from `./lib/bytecode.mjs`
+- Create: `scripts/contracts-migration/check-bytecode.mjs`
+- Create: `scripts/contracts-migration/check-bytecode.test.mjs`
+- Create: `scripts/contracts-migration/manifest.json`
+- Create: `scripts/contracts-migration/reference.json` (generated)
+- Modify: `package.json` (root) — add scripts `"check:bytecode": "node scripts/contracts-migration/check-bytecode.mjs"` and `"test:scripts": "node --test 'scripts/**/*.test.mjs'"`
+- Modify: `.github/workflows/build-test.yml` — add a step `Check bytecode equivalence` (`pnpm check:bytecode`) right after "Build all packages", and a step `Test scripts` (`pnpm test:scripts`)
+
+**Interfaces:**
+
+- Produces, from `scripts/lib/bytecode.mjs`:
+  - `stripMetadata(bytecode: string): string`. Lowercases the input, strips a leading `0x`, then removes every match of `/a264697066735822[0-9a-f]{68}64736f6c6343[0-9a-f]{6}0033/g`. That pattern covers the 0.7.6 suffix (`…430007060033`) and the 0.8.35 suffix (`…430008230033`). Bytes before or after a blob are kept.
+  - `bytecodeHash(bytecode: string): string`. Returns the sha256 hex of `stripMetadata(bytecode)`.
+- Produces, from `scripts/contracts-migration/check-bytecode.mjs`:
+  - `computeHashes(manifest: Record<string,string>, repoRoot: string): { hashes: Record<string,{bytecode:string,deployedBytecode:string}>, missing: string[], empty: string[] }`.
+    - Reads each artifact JSON's `bytecode` and `deployedBytecode`.
+    - A missing file goes to `missing`.
+    - A missing, `''` or `'0x'` `bytecode` or `deployedBytecode` goes to `empty`.
+  - `compare(reference, hashes): string[]`. Returns one line per mismatch (`EpochManager: deployedBytecode differs`) and one per entry present on only one side (`X: not in reference` / `X: not in manifest`).
+  - CLI, optional flags `--root <dir> --manifest <file> --reference <file>`; defaults are the repo root and the two files next to the script.
+    - Without `--write`: if `missing` or `empty` is non-empty, print each entry to **stderr** and exit 1. Otherwise print the mismatches to stderr and exit 1 if there are any, else print `OK: <n> contracts match` to stdout and exit 0.
+    - With `--write`: exit 1 without writing if `missing` or `empty` is non-empty. Otherwise write `reference.json` with keys sorted, 2-space indent and a trailing newline.
+  - Run the CLI only when the file is executed directly: `import.meta.url === pathToFileURL(process.argv[1]).href`.
+- Produces `manifest.json`: contract name → artifact path relative to the repo root.
+
+Initial `manifest.json` (26 entries; every path was confirmed to exist after `pnpm build`):
+
+| Name                  | Artifact path                                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Controller            | `packages/contracts/artifacts/contracts/governance/Controller.sol/Controller.json`                           |
+| GraphProxy            | `packages/contracts/artifacts/contracts/upgrades/GraphProxy.sol/GraphProxy.json`                             |
+| GraphProxyAdmin       | `packages/contracts/artifacts/contracts/upgrades/GraphProxyAdmin.sol/GraphProxyAdmin.json`                   |
+| GraphToken            | `packages/contracts/artifacts/contracts/token/GraphToken.sol/GraphToken.json`                                |
+| L2GraphToken          | `packages/contracts/artifacts/contracts/l2/token/L2GraphToken.sol/L2GraphToken.json`                         |
+| L1GraphTokenGateway   | `packages/contracts/artifacts/contracts/gateway/L1GraphTokenGateway.sol/L1GraphTokenGateway.json`            |
+| L2GraphTokenGateway   | `packages/contracts/artifacts/contracts/l2/gateway/L2GraphTokenGateway.sol/L2GraphTokenGateway.json`         |
+| BridgeEscrow          | `packages/contracts/artifacts/contracts/gateway/BridgeEscrow.sol/BridgeEscrow.json`                          |
+| L2GNS                 | `packages/contracts/artifacts/contracts/l2/discovery/L2GNS.sol/L2GNS.json`                                   |
+| L2Curation            | `packages/contracts/artifacts/contracts/l2/curation/L2Curation.sol/L2Curation.json`                          |
+| GraphCurationToken    | `packages/contracts/artifacts/contracts/curation/GraphCurationToken.sol/GraphCurationToken.json`             |
+| SubgraphNFT           | `packages/contracts/artifacts/contracts/discovery/SubgraphNFT.sol/SubgraphNFT.json`                          |
+| SubgraphNFTDescriptor | `packages/contracts/artifacts/contracts/discovery/SubgraphNFTDescriptor.sol/SubgraphNFTDescriptor.json`      |
+| EpochManager          | `packages/contracts/artifacts/contracts/epochs/EpochManager.sol/EpochManager.json`                           |
+| RewardsManager        | `packages/contracts/artifacts/contracts/rewards/RewardsManager.sol/RewardsManager.json`                      |
+| L1GNS                 | `packages/contracts/artifacts/contracts/discovery/L1GNS.sol/L1GNS.json`                                      |
+| Curation              | `packages/contracts/artifacts/contracts/curation/Curation.sol/Curation.json`                                 |
+| L1Staking             | `packages/contracts/artifacts/contracts/staking/L1Staking.sol/L1Staking.json`                                |
+| StakingExtension      | `packages/contracts/artifacts/contracts/staking/StakingExtension.sol/StakingExtension.json`                  |
+| LibExponential        | `packages/contracts/artifacts/contracts/staking/libs/Exponential.sol/LibExponential.json`                    |
+| HorizonStaking        | `packages/horizon/build/contracts/contracts/staking/HorizonStaking.sol/HorizonStaking.json`                  |
+| GraphPayments         | `packages/horizon/build/contracts/contracts/payments/GraphPayments.sol/GraphPayments.json`                   |
+| PaymentsEscrow        | `packages/horizon/build/contracts/contracts/payments/PaymentsEscrow.sol/PaymentsEscrow.json`                 |
+| SubgraphService       | `packages/subgraph-service/build/contracts/contracts/SubgraphService.sol/SubgraphService.json`               |
+| DisputeManager        | `packages/subgraph-service/build/contracts/contracts/DisputeManager.sol/DisputeManager.json`                 |
+| AllocationHandler     | `packages/subgraph-service/build/contracts/contracts/libraries/AllocationHandler.sol/AllocationHandler.json` |
+
+The horizon and subgraph-service paths are Hardhat outputs (`build/contracts`, mirroring the source tree), not Foundry's flat `build/`.
+
+Library link placeholders (L1Staking → LibExponential; SubgraphService → AllocationHandler and others) encode the library's fully qualified source path. They stay stable as long as those libraries don't move; a later PR that moves a linked library must expect to update the reference and justify it in its description.
+
+- [ ] **Step 1: Write the failing tests in `scripts/contracts-migration/check-bytecode.test.mjs`**
+
+Use `node:test` and `node:assert/strict`. Write fixtures to a temp dir (`fs.mkdtempSync`). Constants:
+
+- `META_A = 'a264697066735822' + '1220' + 'ab'.repeat(32) + '64736f6c63430007060033'`
+- `META_B`: the same with `'cd'.repeat(32)`
+
+Tests:
+
+- `stripMetadata removes the CBOR blob`: `stripMetadata('0x6080' + META_A) === '6080'`.
+- `stripMetadata keeps bytes after the blob`: `stripMetadata('0x6080' + META_A + 'ff'.repeat(32)) === '6080' + 'ff'.repeat(32)`.
+- `stripMetadata leaves code without metadata unchanged`: `stripMetadata('0x6080') === '6080'`.
+- `ignores metadata-only differences`:
+  - artifact A `{bytecode:'0x6080'+META_A, deployedBytecode:'0x60aa'+META_A}`, artifact B the same with `META_B`;
+  - `a = computeHashes({X: 'a.json'}, dir)` and `b = computeHashes({X: 'b.json'}, dir)`;
+  - `compare(a.hashes, b.hashes)` deep-equals `[]`.
+- `detects code differences`: as above, but B's `deployedBytecode` is `'0x60ab'+META_B`. `compare` deep-equals `['X: deployedBytecode differs']`.
+- `detects differences after the metadata`: B's `bytecode` is `'0x6080'+META_B+'01'` versus A's `'0x6080'+META_A+'00'`. `compare` deep-equals `['X: bytecode differs']`.
+- `rejects empty bytecode`: an artifact with `bytecode: '0x'`. `computeHashes(...).empty` deep-equals `['X']`.
+- `fails when an artifact is missing`:
+  - `computeHashes({X: 'nope.json'}, dir).missing` deep-equals `['nope.json']`;
+  - spawning the CLI (`child_process.spawnSync(process.execPath, [script, '--root', dir, '--manifest', m, '--reference', r])`) exits with status 1, and stderr contains `nope.json`.
+- `write refuses to produce a partial reference`: write a reference file with content `'{"keep":true}\n'`, then spawn the CLI with `--write` and a manifest containing a missing entry. It exits with status 1, and the reference file still reads `'{"keep":true}\n'`.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `node --test 'scripts/contracts-migration/*.test.mjs'`
+Expected: FAIL with `ERR_MODULE_NOT_FOUND` for `check-bytecode.mjs` / `../lib/bytecode.mjs`.
+
+- [ ] **Step 3: Implement `scripts/lib/bytecode.mjs` and `scripts/contracts-migration/check-bytecode.mjs` per the Interfaces block, and switch the compare script to the shared `stripMetadata`**
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `node --test 'scripts/**/*.test.mjs'`
+Expected: all PASS, including the existing `scripts/verify-solhint-disables.test.mjs`.
+
+- [ ] **Step 5: Check that the compare script still works**
+
+The script refuses to compare identical paths, so give it a symlink:
+
+```bash
+ln -sfn "$PWD" /tmp/repo-link && node scripts/compare-repo-contract-bytecode-excluding-metadata.mjs . /tmp/repo-link
+```
+
+Expected: `FUNCTIONAL DIFFERENCES (0 contracts)`.
+
+- [ ] **Step 6: Build and generate the reference**
+
+Run: `pnpm build && pnpm check:bytecode --write && pnpm check:bytecode`
+Expected: `reference.json` has 26 entries, each with two 64-hex-character hashes, and the check prints `OK: 26 contracts match`.
+
+- [ ] **Step 7: Prove determinism**
+
+Run: `pnpm clean && pnpm build && pnpm check:bytecode`
+Expected: `OK: 26 contracts match`.
+
+- [ ] **Step 8: Wire into CI**
+
+Add the two steps to `.github/workflows/build-test.yml` as listed in Files.
+
+- [ ] **Step 9: Commit and open PR**
+
+```bash
+git add scripts/lib/bytecode.mjs scripts/compare-repo-contract-bytecode-excluding-metadata.mjs scripts/contracts-migration package.json .github/workflows/build-test.yml
+git commit -m "ci: add bytecode equivalence check for the contracts package migration"
+```
+
+PR description:
+
+- Later move PRs update `manifest.json` paths only.
+- `reference.json` hashes never change. Entries are removed only when their contract is deleted.
+- The shared `stripMetadata` is now exact (it matches the full blob, not "everything to the end"). The repo comparison script is therefore slightly stricter: it no longer ignores the bytes some contracts have after the metadata in their creation bytecode.
+- The onchain comparison for `legacy` and graph-token's mainnet contracts comes in Phase D (D2).
+
+---
+
+### Task 4 (PR 0d): Coverage baseline from `contracts-test`
+
+**Files:**
+
+- Create: `scripts/contracts-migration/summarize-coverage.mjs`
+- Create: `scripts/contracts-migration/summarize-coverage.test.mjs`
+- Create: `scripts/contracts-migration/coverage-baseline.json` (generated)
+
+**Interfaces:**
+
+- Produces `parseLcov(text: string): Record<string, { linesFound: number, linesHit: number, pct: number | null }>`:
+  - Each record starts at `SF:` and ends at `end_of_record`.
+  - The key is the `SF:` path from its **last** path segment that equals `contracts`. For example, `/home/runner/work/contracts/contracts/packages/contracts-test/contracts/rewards/RewardsManager.sol` becomes `contracts/rewards/RewardsManager.sol`. Paths that already start with `contracts/` are unchanged.
+  - The values come from the record's `LF:` and `LH:` lines, with `pct = linesFound === 0 ? null : Math.round(linesHit / linesFound * 10000) / 100`.
+- Produces a CLI: `node scripts/contracts-migration/summarize-coverage.mjs <lcov.info> <out.json>` writes `parseLcov` output with keys sorted, 2-space indent and a trailing newline. Later phases run the same parser on `forge coverage --report lcov` output.
+
+- [ ] **Step 1: Write the failing tests in `summarize-coverage.test.mjs`**
+
+- `parses one record with an absolute CI path`: `SF:/home/runner/work/contracts/contracts/packages/contracts-test/contracts/rewards/RewardsManager.sol`, `LF:200`, `LH:150`, `end_of_record` gives `{ 'contracts/rewards/RewardsManager.sol': { linesFound: 200, linesHit: 150, pct: 75 } }`.
+- `keeps relative contracts paths`: `SF:contracts/upgrades/GraphProxy.sol` gives the key `contracts/upgrades/GraphProxy.sol`.
+- `keeps records separate`: two records (`LF:10/LH:10` and `LF:4/LH:1`) give two keys with `pct` 100 and 25.
+- `zero lines yields null pct`: `LF:0`, `LH:0` gives `pct: null`.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `node --test 'scripts/contracts-migration/summarize-coverage.test.mjs'`
+Expected: FAIL with `ERR_MODULE_NOT_FOUND`.
+
+- [ ] **Step 3: Implement `parseLcov` and the CLI in `summarize-coverage.mjs`**
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `node --test 'scripts/**/*.test.mjs'`
+Expected: all PASS.
+
+- [ ] **Step 5: Run contracts-test coverage**
+
+`scripts/coverage` does not create the address book that the sdk fixture needs; only `scripts/test` does. So run the regular tests first:
+
+```bash
+pnpm --filter @graphprotocol/contracts-tests test:self
+pnpm --filter @graphprotocol/contracts-tests test:coverage:self
+```
+
+Expected: both complete. solidity-coverage writes to `packages/coverage/lcov.info`, because `.solcover.js` sets `istanbulFolder: '../coverage'`, even though its log says `./coverage/`. If it runs out of memory, retry with `NODE_OPTIONS=--max-old-space-size=8192`. Don't run `pnpm install` between the two commands; it can remove the address book again.
+
+- [ ] **Step 6: Generate the baseline**
+
+Run: `node scripts/contracts-migration/summarize-coverage.mjs packages/coverage/lcov.info scripts/contracts-migration/coverage-baseline.json`
+Expected: the JSON has entries with `linesFound > 0` for at least these files:
+
+- `contracts/rewards/RewardsManager.sol`
+- `contracts/l2/discovery/L2GNS.sol`
+- `contracts/discovery/GNS.sol`
+- `contracts/l2/curation/L2Curation.sol`
+- `contracts/governance/Controller.sol`
+- `contracts/upgrades/GraphProxyAdmin.sol`
+- `contracts/epochs/EpochManager.sol`
+- `contracts/l2/gateway/L2GraphTokenGateway.sol`
+- `contracts/gateway/L1GraphTokenGateway.sol`
+
+No key contains `packages/`.
+
+- [ ] **Step 7: Commit and open PR**
+
+```bash
+git add scripts/contracts-migration/summarize-coverage.mjs scripts/contracts-migration/summarize-coverage.test.mjs scripts/contracts-migration/coverage-baseline.json
+git commit -m "test: record contracts-test line coverage baseline for the Foundry ports"
+```
+
+PR description:
+
+- List the baseline line % for every file that will move to graph-core, graph-token and subgraph-discovery, and for EpochManager and RewardsManager. These are the parity targets from spec §4.
+- Note that `.solcover.js` skips `contracts/arbitrum/` and `contracts/tests/`. L1ArbitrumMessenger, L2ArbitrumMessenger and AddressAliasHelper therefore have no baseline, and their parity is checked by the test mapping table only.
+- Delete `packages/coverage/` locally after generating; it's not committed.
diff --git a/docs/contracts-removal/phase-1-plan.md b/docs/contracts-removal/phase-1-plan.md
new file mode 100644
index 000000000..f26a6e0c7
--- /dev/null
+++ b/docs/contracts-removal/phase-1-plan.md
@@ -0,0 +1,286 @@
+# Contracts Removal — Phase 1 (Frozen Moves and Tooling Cleanup) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Move every frozen contract out of `packages/contracts` into graph-core or graph-token, with identical bytecode ignoring metadata. Simplify `legacy` and Ignition. RewardsManager, L2GNS, L2Curation and their storage contracts stay in `packages/contracts` until Phase P ports them.
+
+**Architecture:**
+
+- Moves run bottom-up, one PR per step: graph-core, graph-token, the frozen discovery contracts into graph-token, then EpochManager into graph-core. Each step removes a dependency on `packages/contracts`, so no cycle forms.
+- Both packages keep the same subpaths under `contracts/`, so artifact paths and coverage-baseline keys don't change. They get their own Hardhat 2 config, and Foundry compiles their sources pinned to 0.7.6.
+- Steps 5 and 6 don't move contracts. They remove `legacy`'s bytecode check, and Ignition's migrate flow, deployment records, verification tooling, migration-based test suites and 7.3.0 alias.
+
+**Tech Stack:** pnpm workspaces, Hardhat 2, Foundry 1.8.3, solc 0.7.6 and 0.8.35, OpenZeppelin 3.4.2 and 5.4, Node 24.
+
+**Spec:** `docs/contracts-removal/design.md` (§2, §3, §4, §5, "PR sequence → Phase 1").
+
+**Revision 4:** P1 and P2 are done (#1394, #1395). The old P3 (#1396, everything into subgraph-discovery) is replaced; its `RewardsHook.t.sol` and `Multicall.t.sol` tests are kept. The old P4 (EpochManager into horizon) is replaced. The old P5 (RewardsManager into issuance) and P6 (Phase 2a) move to the Phase P plan, written when that phase starts. Counts marked `TBD` are filled in by a dry run before each task starts.
+
+## Global Constraints
+
+- Each task is a draft PR in one chain, the same way as Phase D: P1 targets `chore/contracts-removal-phase-0` (#1373), and each later task targets the one before. Nothing goes to main before the audit.
+- Conventional commits, no Co-Authored-By line and no Claude attribution in commits or PRs.
+- Moves use `git mv`. The only source edits allowed in moved `.sol` files are import paths, and Managed's pragma going from `^0.7.6` to `^0.7.6 || ^0.8.27`.
+- 0.7.6 settings are exactly solc 0.7.6, optimizer enabled, 200 runs, no `evmVersion`, no `viaIR`, default metadata.
+- Cross-package Solidity imports use `@graphprotocol/<package>/contracts/<subpath>`. Imports within a package stay relative.
+- Until P6, `@graphprotocol/contracts-7.3.0` imports and `ignition/deployments/` don't change.
+- RewardsManager, RewardsManagerStorage, MathUtils, L2GNS, L2GNSStorage, GNS, GNSStorage, L2Curation, CurationStorage and Multicall don't move in Phase 1.
+- Issuance's code and tests never use horizon, subgraph-service or graph-token.
+- No RPC URL or API key is ever written to a file, commit, report or PR. RPC URLs are passed only as inline env vars.
+- `reference.json` and `coverage-baseline.json` are never regenerated. Only `manifest.json` paths change.
+- Run `pnpm install --no-frozen-lockfile` right after any `package.json` edit, before the next build. The lockfile picks up unrelated patch bumps, so don't require an additive diff. Instead, check that it changes no solc, OpenZeppelin, Hardhat or forge-std version.
+
+**Verification for every PR**, run from the repo root after committing. It doesn't replace CI's lint job (`lint.yml`):
+
+```bash
+pnpm install --frozen-lockfile
+pnpm --filter @graphprotocol/contracts clean
+pnpm -r --sequential run build
+pnpm test:scripts
+pnpm check:bytecode
+pnpm -r --sequential run test:self
+pnpm lint:sol; git status --short
+git diff -M HEAD~1 -- 'packages/*/contracts/**/*.sol' | grep -E '^[-+]' | grep -vE '^(\+\+\+|---)|^[-+]\s*(import|pragma|\}? ?from)|^[-+]\s+\w+,?$'
+rm -rf packages/deployment/fork
+FORK_NETWORK=arbitrumSepolia pnpm --filter @graphprotocol/deployment exec hardhat deploy --tags sync --skip-prompts --network fork
+```
+
+Expected:
+
+- All exit 0 except the `grep` line. `check:bytecode` prints `OK: 21 contracts match` throughout Phase 1: the manifest already lists EpochManager and the moved discovery contracts, and only their paths change.
+- `git status` prints nothing. `lint:sol`'s exit code only reflects its final `pnpm todo`, so `git status` is the real check that nothing was reformatted.
+- The `grep` line prints nothing: moved and consumer contracts changed only in import and pragma lines. If it prints anything, the commit hook rewrote a file. The moved files pass prettier and solhint today, so this shouldn't happen. Stop and report rather than bypass the hook.
+- From P5, `legacy`'s `test:self` runs only the source-hash check. From P6, the `deploy:protocol` CI job passes.
+
+The sync copies the address books into `packages/deployment/fork/` on first run and reuses that copy, so the `rm -rf` is required: without it, a run after an address-book change reads the old copy. For the fork check, run the last two commands once on the parent commit and save its output to the scratchpad before starting the task. The two outputs must match. The public RPC default needs no secret, and a private one goes in as an inline `ARBITRUM_SEPOLIA_RPC=`. This check can't see a missing artifact, because `tryLoadArtifactFromSource` swallows the error, so P1 adds a registry test that can.
+
+**Rebuild rule:** after a failed Hardhat compile in horizon or subgraph-service, run `rm -rf build cache` before retrying. `isProjectBuilt` passes on a partial build, and `loadTasks` then crashes on missing artifacts.
+
+**TypeScript check:** `npx tsc --noEmit | grep TS2307`, in the named package, must print nothing. Plain `tsc` can't exit 0, because horizon and subgraph-service have unrelated errors today.
+
+**Coverage gate** for P1 to P4, run in the moved package:
+
+```bash
+forge coverage --report lcov --report-file /tmp/<pkg>.lcov
+node ../../scripts/contracts-migration/summarize-coverage.mjs /tmp/<pkg>.lcov /tmp/<pkg>.json
+node ../../scripts/contracts-migration/compare-coverage.mjs ../../scripts/contracts-migration/coverage-baseline.json /tmp/<pkg>.json <moved contract paths>
+```
+
+solidity-coverage and forge count lines differently (Multicall is 6/8 in the baseline and 6/9 in forge with the same 6 hits), so line percentages can't be gated directly. The gate fails if a function hit in the baseline isn't hit now. It also prints each file whose line percentage is below baseline. List those files in the PR with a reason, or add a test. Never lower the baseline.
+
+## Review Focus
+
+1. **A test runs different code from what deploys.** Foundry compiles dual-pragma contracts as 0.8.35 with the optimizer off unless pinned, and they would still pass. P1 to P4 each have a test that Foundry's bytecode equals the Hardhat artifact's, ignoring metadata.
+2. **The commit hook rewrites moved files.** lint-staged runs on renamed `.sol` files, and comment or formatting edits don't change bytecode, so `check:bytecode` can't see them. The `grep` line in the verification block catches this.
+3. **A package loads only when a command runs.** `require.resolve` in `packages/deployment` can pass `build`. P1's registry test and the TypeScript check cover it.
+4. **Something outside the deleted files still uses them.** P6 deletes tasks, scripts, configs and suites that docs, other tasks or local-network might reference. P6 Step 2 lists every user before deleting.
+
+---
+
+### Task P1: Move the governance and proxy contracts to graph-core
+
+Done: #1394.
+
+**Files:**
+
+- Move: from `packages/contracts/contracts/` to `packages/graph-core/contracts/`, same subpaths: `governance/{Controller,Governed,Managed,Pausable}.sol`, `upgrades/{GraphProxy,GraphProxyAdmin,GraphProxyStorage,GraphUpgradeable}.sol`, `tests/{GovernedMock,ManagedMock}.sol`
+- Create: `packages/graph-core/hardhat.config.ts`, `README.md`, `.solhint.json` and `prettier.config.cjs` (the last two copied from `packages/contracts`), `.changeset/graph-core-initial.md` (`major`)
+- Modify: `packages/graph-core/package.json`, `foundry.toml`, its tests
+- Modify: remaining `packages/contracts/contracts/**` imports and `packages/contracts/package.json`
+- Modify: horizon `contracts/staking/HorizonStakingBase.sol`, `test/unit/GraphBase.t.sol`, `test/unit/escrow/constructor.t.sol`; subgraph-service `test/unit/SubgraphBaseTest.t.sol`; testing `test/harness/{FullStackHarness,RealRewardsHarness}.t.sol`
+- Modify: `ProtocolFixture.t.sol` and `foundry.toml` `fs_permissions` in graph-token, subgraph-discovery, horizon and issuance
+- Modify: `package.json` of graph-token, subgraph-discovery, issuance, horizon, subgraph-service, testing, deployment
+- Modify: `packages/deployment/lib/{artifact-loaders,contract-registry,deploy-implementation,deployment-validation}.ts`, `scripts/generate-abis.ts`, `tasks/verify-contract.ts`, `test/bytecode-comparison.test.ts`
+- Modify: `scripts/contracts-migration/manifest.json`, `.github/workflows/publish.yml`, `.gitignore`, `pnpm-lock.yaml`
+- Create: `scripts/contracts-migration/compare-coverage.mjs`, `compare-coverage.test.mjs`, `packages/deployment/test/registry-artifacts.test.ts`
+
+**Interfaces:**
+
+- Consumes: nothing.
+- Produces:
+  - `@graphprotocol/graph-core/contracts/...` and `@graphprotocol/graph-core/artifacts/...`.
+  - `ProtocolFixture._deployPkg(string memory id, bytes memory args) returns (address)`, wrapping `deployCode` and honouring an active prank. `id` has the form `"Controller.sol:Controller"`. `_deployArtifact` stays for Hardhat JSON. Each package has its own copy of `ProtocolFixture`, so P2 and P3 add the same helper.
+  - `ArtifactSource` members `{ type: 'graph-core' | 'graph-token' | 'subgraph-discovery'; path: string; name: string }`, all served by `loadPackageArtifact(pkg, path, name)`.
+  - `compareCoverage(baseline, current, files)` returning `{ regressions, belowLines }`.
+
+**New package setup**, also used by P2 and P3:
+
+- `files` of contracts, artifacts, types and README; `exports` of `./artifacts/*`, `./contracts/*`, `./types` and `./types/*`; version `0.0.0` (the `major` changeset takes it to 1.0.0); no `"private"` and no `"type": "module"`.
+- Scripts: `build` is `pnpm build:dep && pnpm build:self`, `build:self` is `hardhat compile --quiet`, `prepack` is `pnpm build` (`publish.yml` has no build step, and artifacts and types are gitignored), `clean` is `rm -rf artifacts/ cache/ types/ forge-artifacts/ cache_forge/ coverage/`, and `lint:sol` matches `packages/contracts`.
+- dependencies: `@graphprotocol/interfaces`, because the published sources import it.
+- devDependencies: `hardhat`, `hardhat-ignore-warnings`, `@nomicfoundation/hardhat-verify` 2.1.1, `@typechain/hardhat`, `@typechain/ethers-v5`, `typechain`, `ethers ^5.7.2`, `@ethersproject/{abi,bytes,providers}`, `ts-node`, `typescript`, `solhint`, `prettier`, `prettier-plugin-solidity`, `forge-std`, each at the version `packages/contracts` uses. Remove `@graphprotocol/contracts`.
+- Add `packages/<pkg>/types/` to root `.gitignore`.
+- `hardhat.config.ts` has the exact 0.7.6 settings, the Arbitrum networks, `etherscan`, `typechain` (target `ethers-v5`, outDir `types`) and `warnings` from `packages/contracts/hardhat.config.ts`.
+
+graph-core also has `@openzeppelin/contracts ^5.4.0`.
+
+- [ ] **Step 1: Write `compare-coverage` tests first.** Test: a baseline function missing from `current`'s `functionsHit`, comparing after stripping a `Contract.` prefix, is a regression; a named file absent from `current` is a regression unless its baseline `linesFound` is 0; a file absent from the baseline throws; a line percentage below baseline appears in `belowLines` and isn't a regression. Run `pnpm test:scripts`. Expected: FAIL.
+- [ ] **Step 2: Implement `compare-coverage.mjs`** with a CLI of `<baseline.json> <current.json> <file...>` that prints both lists and exits 1 only on regressions. Run `pnpm test:scripts`. Expected: PASS.
+- [ ] **Step 3: Record the fork output on the parent commit** as the verification block says.
+- [ ] **Step 4: Make the move.** `git mv` the files, change Managed's pragma, and rewrite imports of these files in `packages/contracts` to `@graphprotocol/graph-core/contracts/...`. Add `@graphprotocol/graph-core` as a devDependency of contracts, horizon, subgraph-service, testing, graph-token, subgraph-discovery and issuance, and as a dependency of deployment. Apply the package setup, then install.
+- [ ] **Step 5: Build the package.** Run `pnpm --filter @graphprotocol/graph-core build:self`. Expected: compiles 27 files.
+- [ ] **Step 6: Set the graph-core Foundry config.** Set `src = 'contracts'`, remove `solc_version`, add the remapping `@openzeppelin/=node_modules/@openzeppelin/`, and add:
+
+  ```toml
+  optimizer = true
+  optimizer_runs = 200
+  compilation_restrictions = [
+      { paths = "contracts/**", version = "=0.7.6" },
+      { paths = "test/**", version = "=0.8.35" },
+  ]
+  fs_permissions = [{ access = "read", path = "artifacts" }]
+  ```
+
+- [ ] **Step 7: Switch graph-core's tests to `deployCode`.** Add `_deployPkg`, and replace `CORE_ARTIFACTS`/`PKG_ARTIFACTS` uses with ids such as `"Controller.sol:Controller"`, `"GovernedMock.sol:GovernedMock"`. Remove the constants. Rewrite `test_Fixture_ArtifactReadable` and `test_Fixture_RevertWhen_ArtifactMissing` around `vm.getCode`, keeping the external wrapper, because `vm.expectRevert` needs the call one level down.
+- [ ] **Step 8: Pin Review Focus 1.** Add `test_Fixture_FoundryControllerMatchesHardhat`: `vm.getCode("Controller.sol:Controller")` equals `.bytecode` in `artifacts/contracts/governance/Controller.sol/Controller.json`, each with the CBOR metadata tail stripped using its final two length bytes. `forge coverage` compiles with the optimizer off, so the test starts with `vm.skip(vm.isContext(VmSafe.ForgeContext.Coverage))`.
+- [ ] **Step 9: Cover `GraphProxy.receive()`.** Baseline coverage hit it and the port doesn't. Add a test sending ETH to a proxy, with the expected result read from `GraphProxy.sol:65-66`. Run `pnpm --filter @graphprotocol/graph-core test:self`. Expected: 51 passing or more, 0 failing.
+- [ ] **Step 10: Repoint other packages' fixtures.** In graph-token, subgraph-discovery, horizon and issuance, set `CORE_ARTIFACTS` to `node_modules/@graphprotocol/graph-core/artifacts/contracts/` and add that path to `fs_permissions`. `PKG_ARTIFACTS` stays on `packages/contracts` for now. Rewrite the horizon, subgraph-service and testing imports to graph-core.
+- [ ] **Step 11: Generalize the deployment loader.** Add `loadPackageArtifact`, the new `ArtifactSource` members, and the `getLibraryResolver`, `getPackageDir` and `getFullyQualifiedContractName` cases. Keep `type: 'contracts'` and `loadContractsArtifact` working. Change no registry entry yet: none of them point at graph-core. Update `manifest.json` for Controller, GraphProxy, GraphProxyAdmin.
+- [ ] **Step 12: Pin Review Focus 5.** Add `test/registry-artifacts.test.ts`, calling the throwing `loadArtifactFromSource` for every entry in `CONTRACT_REGISTRY` that has an `artifact`, and asserting non-empty bytecode. Make the `before` hook at `bytecode-comparison.test.ts:172-188` throw instead of skipping when the import fails. Run `pnpm --filter @graphprotocol/deployment test:self`. Expected: PASS.
+- [ ] **Step 13: Add `graph-core` to the `publish.yml` options,** and check the lockfile.
+- [ ] **Step 14: Commit.** `refactor(graph-core): move governance and proxy contracts`
+- [ ] **Step 15: Run the verification block and the coverage gate** for `contracts/governance/*.sol` and `contracts/upgrades/*.sol`.
+
+---
+
+### Task P2: Move the token and bridge contracts to graph-token
+
+Done: #1395.
+
+**Files:**
+
+- Move: `token/GraphToken.sol`, `l2/token/{L2GraphToken,GraphTokenUpgradeable}.sol`, `utils/TokenUtils.sol`, `gateway/{GraphTokenGateway,L1GraphTokenGateway,BridgeEscrow}.sol`, `l2/gateway/L2GraphTokenGateway.sol`, `arbitrum/{L1ArbitrumMessenger,L2ArbitrumMessenger,AddressAliasHelper}.sol`, `arbitrum/{Arbitrum,README}.md`, `tests/{CallhookReceiverMock,TokenUtilsMock}.sol`, `tests/arbitrum/{BridgeMock,InboxMock,OutboxMock}.sol`
+- Create: `packages/graph-token/hardhat.config.ts`, `README.md`, `.solhint.json`, `prettier.config.cjs`, `.changeset/graph-token-initial.md` (`major`)
+- Modify: `packages/graph-token/{package.json,foundry.toml}` and tests
+- Modify: remaining `packages/contracts/contracts/**` imports, `packages/contracts/package.json`
+- Modify: horizon `contracts/payments/{GraphPayments,PaymentsEscrow}.sol`, `contracts/staking/HorizonStaking.sol`; subgraph-service `contracts/{DisputeManager,SubgraphService}.sol`, `contracts/libraries/AllocationHandler.sol`, `contracts/utilities/AllocationManager.sol`
+- Modify: `packages/subgraph-discovery/test/unit/shared/DiscoveryTest.t.sol`, `foundry.toml`, `package.json`
+- Modify: `package.json` of horizon, subgraph-service, testing, deployment
+- Modify: `packages/deployment/lib/contract-registry.ts` (L2GraphToken), `test/bytecode-comparison.test.ts:239`
+- Modify: `manifest.json`, `publish.yml`, `.gitignore`, `pnpm-lock.yaml`
+
+**Interfaces:**
+
+- Consumes: `@graphprotocol/graph-core/contracts/...`, the same `_deployPkg` helper, `{ type: 'graph-token' }`, `compare-coverage.mjs`, the new package setup.
+- Produces: `@graphprotocol/graph-token/contracts/utils/TokenUtils.sol` and `@graphprotocol/graph-token/artifacts/...`; `TOKEN_ARTIFACTS` in `DiscoveryTest.t.sol`.
+
+Package setup follows P1, plus `@openzeppelin/contracts` and `contracts-upgradeable` at exactly 3.4.2, `arbos-precompiles ^1.0.2`, and `@graphprotocol/graph-core` as a dependency. Foundry config follows P1 Step 6, plus the remapping `arbos-precompiles/=node_modules/arbos-precompiles/` and `fs_permissions` for graph-core's artifacts. Fixtures keep reading `CORE_ARTIFACTS` as Hardhat JSON, because forge doesn't compile Controller here. Tests still can't import IGraphToken and keep their local `Like` interfaces.
+
+The README states that GraphToken, L1GraphTokenGateway and BridgeEscrow here aren't the code running on mainnet, which `packages/legacy` holds.
+
+- [ ] **Step 1: Make the move** and rewrite imports, including `packages/contracts`' remaining uses of TokenUtils. Rewrite the seven 0.8 importers to `@graphprotocol/graph-token/contracts/utils/TokenUtils.sol`. Add `@graphprotocol/graph-token` as a devDependency of contracts, horizon, subgraph-service, testing and subgraph-discovery, and as a dependency of deployment. `testing` needs it because horizon's sources are compiled through its remappings. Install.
+- [ ] **Step 2: Build the package.** Run `pnpm --filter @graphprotocol/graph-token build:self`. Expected: exit 0.
+- [ ] **Step 3: Switch `PKG_ARTIFACTS` to `_deployPkg` ids** in `test/unit/**`, adding the helper and keeping `CORE_ARTIFACTS`. Add the Review Focus 1 test for L2GraphToken, reading graph-token's own Hardhat artifact. Run `pnpm --filter @graphprotocol/graph-token test:self`. Expected: 125 passing, 0 failing.
+- [ ] **Step 4: Add `TOKEN_ARTIFACTS` to `DiscoveryTest.t.sol`**, pointing at `node_modules/@graphprotocol/graph-token/artifacts/contracts/`, with its `fs_permissions` entry, and load L2GraphToken from it. Run `pnpm --filter @graphprotocol/subgraph-discovery test:self`. Expected: 82 passing.
+- [ ] **Step 5: Update deployment.** Set the L2GraphToken registry entry to `{ type: 'graph-token', path: 'l2/token', name: 'L2GraphToken' }`. In `bytecode-comparison.test.ts`, load L2GraphToken through `loadPackageArtifact`. Update `manifest.json` for GraphToken, L2GraphToken, L1GraphTokenGateway, L2GraphTokenGateway and BridgeEscrow.
+- [ ] **Step 6: Add `graph-token` to `publish.yml`,** and check the lockfile.
+- [ ] **Step 7: Commit.** `refactor(graph-token): move token and bridge contracts`
+- [ ] **Step 8: Run the verification block and the coverage gate** for the moved contracts, excluding `contracts/arbitrum/*`, which the baseline doesn't list, and mocks. Expected: `packages/testing` reports 24 passing with 0 skipped.
+
+---
+
+### Task P3: Move the frozen discovery contracts to graph-token
+
+**Files:**
+
+- Move: from `packages/contracts/contracts/` to `packages/graph-token/contracts/`, same subpaths: `discovery/{SubgraphNFT,SubgraphNFTDescriptor}.sol`, `curation/GraphCurationToken.sol`, `libraries/{Base58Encoder,HexStrings}.sol`
+- Modify: `packages/subgraph-discovery/test/unit/shared/DiscoveryTest.t.sol` (load the moved contracts from `TOKEN_ARTIFACTS`)
+- Create: `packages/subgraph-discovery/test/unit/**/{RewardsHook,Multicall}.t.sol`, taken from #1396
+- Modify: `packages/horizon/addresses.json`, `packages/address-book/src/horizon/addresses.json`; create `.changeset/horizon-curation-addresses.md` (`@graphprotocol/address-book: minor`)
+- Modify: `packages/deployment/lib/{artifact-loaders,contract-registry,deploy-implementation,deployment-validation}.ts`, `scripts/generate-abis.ts`, `tasks/verify-contract.ts` (remove the `subgraph-discovery` cases P1 added)
+- Modify: `scripts/contracts-migration/manifest.json` (paths of SubgraphNFT, SubgraphNFTDescriptor and GraphCurationToken)
+- Create: graph-token tests under `test/unit/discovery/` and `test/unit/curation/`, only for baseline functions not hit otherwise (see Step 4)
+
+**Interfaces:**
+
+- Consumes: graph-token's package setup and `_deployPkg` from P2.
+- Produces: `@graphprotocol/graph-token/artifacts/contracts/{discovery,curation}/...`.
+
+No Ignition change: the modules read these three artifacts from the 7.3.0 alias until P6.
+
+- [ ] **Step 1: Record the fork output on the parent commit.**
+- [ ] **Step 2: Make the move.** `git mv` the five files. Their imports are Governed (already graph-core), OpenZeppelin 3.4.2, `@graphprotocol/interfaces` and each other (relative, unchanged), all available in graph-token. Expected: `git grep -nE "(SubgraphNFT|GraphCurationToken|SubgraphNFTDescriptor|HexStrings|Base58Encoder)\.sol" -- packages/contracts/contracts` prints nothing. Run `pnpm --filter @graphprotocol/graph-token build:self`, then `pnpm --filter @graphprotocol/contracts build`. Expected: both exit 0.
+- [ ] **Step 3: Repoint subgraph-discovery's tests** to `TOKEN_ARTIFACTS` for SubgraphNFT, SubgraphNFTDescriptor and GraphCurationToken, and add the two test files from #1396. Run `pnpm --filter @graphprotocol/subgraph-discovery test:self`. Expected: `TBD` passing (82 before the added tests).
+- [ ] **Step 4: Coverage.** Run the coverage gate in graph-token for the five moved files. For each regression, add a direct test in graph-token, with `_deployPkg`. Add a Review Focus 1 test for SubgraphNFT. Run `pnpm --filter @graphprotocol/graph-token test:self`. Expected: `TBD` passing, 0 failing.
+- [ ] **Step 5: Add the addresses.** Add GraphCurationToken and SubgraphNFTDescriptor for chains `421614` and `42161` to `packages/horizon/addresses.json`, copied unchanged from `packages/contracts/addresses.json`, and copy the file to `address-book/src/horizon/addresses.json`. Expected: `diff` prints nothing. Note the toolshed name-list warning in the PR.
+- [ ] **Step 6: Remove `subgraph-discovery` from deployment.** Delete the cases P1 added. Expected: `git grep -n "subgraph-discovery" -- packages/deployment` prints nothing. Run `pnpm --filter @graphprotocol/deployment test:self`. Expected: PASS.
+- [ ] **Step 7: Update `manifest.json`.**
+- [ ] **Step 8: Commit.** `refactor(graph-token): move curation token and subgraph NFT contracts`
+- [ ] **Step 9: Run the verification block.**
+
+---
+
+### Task P4: Move EpochManager to graph-core
+
+**Files:**
+
+- Move: `packages/contracts/contracts/epochs/{EpochManager,EpochManagerStorage}.sol` to `packages/graph-core/contracts/epochs/`
+- Move: `packages/horizon/test/unit/epochs/EpochManager.t.sol` to `packages/graph-core/test/unit/epochs/`
+- Modify: `packages/graph-core/package.json` (add `"@openzeppelin/contracts-v3": "npm:@openzeppelin/contracts@3.4.2"` to `dependencies`), `hardhat.config.ts` (filter warnings from `@openzeppelin/contracts-v3/**`). The existing Foundry remapping `@openzeppelin/=node_modules/@openzeppelin/` already covers the alias.
+- Modify: `packages/horizon/test/unit/shared/ProtocolFixture.t.sol`, `foundry.toml`, `package.json` (EpochManager no longer loaded from `packages/contracts`)
+- Modify: `.github/workflows/lint.yml` (`-v3` grep rule)
+- Modify: `manifest.json`, `pnpm-lock.yaml`
+
+**Interfaces:**
+
+- Consumes: graph-core from P1.
+- Produces: `@graphprotocol/graph-core/artifacts/contracts/epochs/EpochManager.sol/EpochManager.json`.
+
+- [ ] **Step 1: Record the fork output on the parent commit.**
+- [ ] **Step 2: Make the move.** Rewrite EpochManager's `@openzeppelin/contracts/math/SafeMath.sol` import to `@openzeppelin/contracts-v3/math/SafeMath.sol`. The Managed and GraphUpgradeable imports become relative. Add the alias and install. Point EpochManager in `manifest.json` at the new path. Run `pnpm --filter @graphprotocol/graph-core build:self`. Expected: exit 0. Run `pnpm --filter @graphprotocol/contracts clean && pnpm --filter @graphprotocol/contracts build`, then `pnpm check:bytecode`. Expected: EpochManager matches (the review compiled this layout and got identical creation and runtime bytecode).
+- [ ] **Step 3: Move the tests.** Move the T4 suite to graph-core and switch it to `_deployPkg("EpochManager.sol:EpochManager")`. Add a Review Focus 1 test for EpochManager. Run `pnpm --filter @graphprotocol/graph-core test:self`. Expected: `TBD` passing. Run horizon's `test:self`. Expected: `TBD` passing, 2 skipped, and nothing loads EpochManager from `packages/contracts`.
+- [ ] **Step 4: Add the CI rule.** Add a `lint.yml` step that fails when `git grep -l '@openzeppelin/contracts-v3' -- '*.sol' ':!packages/graph-core/**'` prints anything.
+- [ ] **Step 5: Coverage gate** for `contracts/epochs/*.sol` in graph-core.
+- [ ] **Step 6: Check the lockfile.**
+- [ ] **Step 7: Commit.** `refactor(graph-core): move EpochManager`
+- [ ] **Step 8: Run the verification block.**
+
+---
+
+### Task P5: Remove `legacy`'s mainnet bytecode check
+
+**Files:**
+
+- Delete: `packages/legacy/scripts/{fetch-verified,record-mainnet,verify}.mjs`, `mainnet.json`, `targets.json`
+- Create: `packages/legacy/scripts/check-sources.mjs`
+- Modify: `packages/legacy/scripts/{lib,lib.test}.mjs` (keep only what the source-hash check uses), `package.json` (`test:self` runs `node --test 'scripts/*.test.mjs' && node scripts/check-sources.mjs`; remove the solc-js dependencies), `README.md`, `pnpm-lock.yaml`
+
+The check runs in CI only through `test:self`; there is no separate CI job.
+
+- [ ] **Step 1: Reduce the scripts to the source-hash check.** `check-sources.mjs` runs `checkSources` on every bundle under `verified/` and exits 1 listing any changed, extra or missing file. Keep the `lib.test.mjs` cases for `checkSources` and drop the rest. Expected: `git grep -nE 'solc|mainnet\.json|targets\.json|RPC' -- packages/legacy ':!packages/legacy/verified' ':!packages/legacy/audits'` prints only README lines. Edit one byte of a file under `verified/`, run `test:self`, and confirm it fails naming that file; restore the file. The ignore entries for `verified/` stay.
+- [ ] **Step 2: Rewrite the README.** One section per bundle with the contract, its mainnet address, compiler version, and its Etherscan and Sourcify links. State that the files were verified to reproduce mainnet bytecode when the package was created (the D2 commit), and that Sourcify and Etherscan are the authority.
+- [ ] **Step 3: Check the lockfile** drops the solc-js entries and nothing else of note.
+- [ ] **Step 4: Commit.** `chore(legacy): keep only the source-hash check`
+- [ ] **Step 5: Run the verification block.**
+
+---
+
+### Task P6: Simplify Ignition
+
+**Files:**
+
+- Delete, in both `packages/horizon` and `packages/subgraph-service`:
+  - `ignition/modules/migrate/`, `ignition/configs/migrate.*`, `ignition/deployments/`
+  - `scripts/{pre-verify,post-verify,integration}`, and in horizon `scripts/{flatten-verify,verify-debug}`
+  - `test/integration/`, `test/deployment/`, `addresses-integration-tests.json`
+  - `tasks/test/{seed,ownership}.ts`, `tasks/transitions/delegation-slashing.ts`
+- Delete: `packages/subgraph-service/ignition/modules/ServiceRegistry.ts`, and `packages/subgraph-service/tenderly.config.json` if it holds only `externalArtifacts`
+- Modify: `tasks/deploy.ts` in both (remove `deploy:migrate`), the task files that register `test:integration`, the module files that export `Migrate*` modules, `packages/subgraph-service/ignition/modules/DisputeManager.ts` (remove `LegacyDisputeManager`), the protocol configs (remove `legacyDisputeManagerAddress`, `legacyServiceRegistryAddress`)
+- Modify: every module importing `@graphprotocol/contracts-7.3.0/...`
+- Modify: `package.json` in both (remove the alias and the `test:integration`, `test:deployment` and verify scripts)
+- Modify: `packages/horizon/tenderly.config.json` (remove `externalArtifacts`, and the `L2Curation` and `RewardsManager` entries from `verifyList`), `packages/toolshed/src/hardhat/tenderly.ts` if `externalArtifacts` support is removed, plus a toolshed changeset if its exports change
+- Modify: root `CLAUDE.md` and both packages' `README.md` (remove `deploy:migrate`, `test:integration`, `test:deployment`)
+- Create: a CI job that runs `deploy:protocol` on a local Hardhat network
+- Modify: `pnpm-lock.yaml`
+
+- [ ] **Step 1: Tag the parent commit** `ignition-records-final`, so the deleted records and flows are one checkout away. Tag it only once P5 is merged into the base branch, so the tagged commit is never rewritten. Mention the tag in the PR. The tag is pushed only with the user's approval.
+- [ ] **Step 2: List what uses each file before deleting it.** Run `git grep` for every task, script and module name above, outside the files being deleted. Expected: only `deploy.ts` task registrations, `package.json` scripts, docs and the files themselves. Check `local-network/containers/core/graph-contracts/run.sh` uses only `deploy:protocol`. Check whether any ops runbook uses `transition:enable-delegation-slashing`; if one does, keep that task and report it. Report anything else before continuing.
+- [ ] **Step 3: Delete the migrate flow, the deployment records, the verification scripts and the migration-based suites.** Update the docs.
+- [ ] **Step 4: Repoint imports.** Controller, GraphProxy, GraphProxyAdmin and EpochManager go to `@graphprotocol/graph-core/artifacts/...`. L2GraphToken, L2GraphTokenGateway, GraphCurationToken, SubgraphNFT and SubgraphNFTDescriptor go to `@graphprotocol/graph-token/artifacts/...`. RewardsManager, L2GNS and L2Curation stay on `@graphprotocol/contracts/artifacts/...`. Remove the alias and install. Expected: `git grep -n 'contracts-7.3.0' -- . ':!docs/contracts-removal' ':!**/CHANGELOG.md'` prints nothing. Run the TypeScript check in both packages.
+- [ ] **Step 5: Add the CI job.** It builds the workspace and runs `npx hardhat deploy:protocol --network hardhat --subgraph-service-config localNetwork` in subgraph-service. Run the same command locally. Expected: exit 0, and the written address books contain `L2Curation`, `L2GNS`, `SubgraphNFT` and `RewardsManager` with code at each address, and `L2Curation.curationTokenMaster()` has code (the Curation module deploys GraphCurationToken without writing it to the address book). Delete any journal it creates.
+- [ ] **Step 6: Commit.** `chore(ignition): keep only deploy:protocol and read live artifacts`
+- [ ] **Step 7: Run the verification block.**
+
+---
+
+Phase 2a (deleting `packages/contracts`) and Phase 2b (`npm deprecate`) follow Phase P and are planned with it.
diff --git a/docs/contracts-removal/phase-d-plan.md b/docs/contracts-removal/phase-d-plan.md
new file mode 100644
index 000000000..0734c2211
--- /dev/null
+++ b/docs/contracts-removal/phase-d-plan.md
@@ -0,0 +1,256 @@
+# Contracts Removal — Phase D (Dead Code Removal) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Delete the old test suite and every dead contract from `packages/contracts`, after archiving the source that actually runs on mainnet in a new private `legacy` package.
+
+**Architecture:**
+
+- D1 removes `contracts-test` and `@graphprotocol/sdk`.
+- D2a creates `legacy` as per-contract bundles of Sourcify-verified source, each compiled with its exact compiler and compared with committed hashes of the on-chain code. D2b adds its address book and audits.
+- D3a points the Ignition modules whose bytecode is unchanged since 7.3.0 at an npm alias of it, so they survive the deletions. D3b deletes the dead contracts.
+
+**Tech Stack:** pnpm workspaces, Node 24 (`node:test`, `node:crypto`), solc-js 0.7.4 and 0.7.6 from npm, Hardhat 2, Foundry 1.8.3.
+
+**Spec:** `docs/contracts-removal/design.md` (§2 "legacy package", §5 "Ignition", §5 "address-book", "PR sequence → Phase D").
+
+## Global Constraints
+
+- Each task is a draft PR in one chain, the same way as Phase T: D1 targets `chore/contracts-removal-phase-0` (#1373), D2a targets D1's branch, then D2b, D3a and D3b each target the one before. Nothing goes to main before the audit.
+- Conventional commits, no Co-Authored-By line and no Claude attribution in commits or PRs.
+- Sources under `packages/legacy/verified/` are never edited, formatted or linted.
+- No RPC URL or API key is ever written to a file, commit, report or PR. RPC URLs are passed only as inline env vars.
+- D3b's list comes from the spec. Do not delete any other contract.
+- `packages/legacy` never gets a `.solhint.json`: CI's changed-files mode runs solhint from that package and passes only because it loads no rules there.
+- The spec's Arbitrum Sepolia fork check for `packages/deployment` doesn't run in this phase: nothing moves, and the unchanged bytecode hashes show no live bytecode changed. It starts with Phase 1.
+- Ignition module changes are limited to the package name in import lines, for the 11 artifacts whose bytecode is unchanged since 7.3.0. RewardsManager, L2GNS and L2Curation stay on live artifacts. Journals under `ignition/deployments/` don't change.
+
+**Verification for every PR**, run from the repo root after committing. It runs CI's build and test steps, except coverage, and doesn't replace CI's lint job (`lint.yml`):
+
+```bash
+pnpm install --frozen-lockfile
+pnpm -r --sequential run build
+pnpm test:scripts
+pnpm check:bytecode
+pnpm -r --sequential run test:self
+pnpm lint:sol && git status --short
+```
+
+Expected: all exit 0, and `git status` prints nothing. `lint:sol`'s exit code only reflects its final `pnpm todo`, so `git status` is the real check on that line: nothing was reformatted.
+
+## Review Focus
+
+1. **A formatter or linter rewrites a verified source.** `lint:sol`, the lint-staged commit hook and CI's Solidity lint must all leave `verified/` alone. Compiling can't detect this, because formatting doesn't change bytecode, so D2a compares source hashes after the commit.
+2. **A changed verified source goes unnoticed.** Verification must fail, whether or not the code changes. D2a has a test for each case.
+3. **An implementation on mainnet has been replaced since the addresses were listed.** `record-mainnet` must fail rather than hash a stale one. It reads each proxy's slot, and for StakingExtension, which has no proxy, L1Staking's `extensionImpl`.
+4. **The alias changes what Solidity compiles.** Foundry's remapping auto-detection or Hardhat could pick up the alias's sources. D3a pins this with `check:bytecode` and the horizon and subgraph-service suites.
+5. **Modules fail only when loaded.** Hardhat loads `tasks/deploy.ts` only in a built project, so a broken import can pass `build`. `npx hardhat --help` catches most modules, but `migrate/*` and subgraph-service's `ServiceRegistry.ts` load dynamically, so D3a also runs `tsc`, which catches those.
+
+---
+
+### Task D1: Delete `contracts-test` and the sdk
+
+**Files:**
+
+- Delete: `packages/contracts-test/` (with `rm -rf`, because `git rm` leaves `node_modules`, `artifacts` and `types`)
+- Delete: `packages/contracts/.mocharc.json`
+- Delete: `packages/contracts/scripts/ops/20240208-migrate-legacy-subgraphs/`, `packages/contracts/scripts/ops/testDisputeConflict/` (their only sdk users outside `contracts-test`; the package doesn't depend on the sdk, so they can't run today)
+- Modify: `packages/contracts/package.json` (remove the `test` and `test:coverage` scripts, and `test/node_modules/` from `clean`)
+- Modify: `packages/contracts/tsconfig.json` (remove the `test/**/*.ts` include), `packages/contracts/hardhat.config.ts` (remove `paths.tests`)
+- Modify: `pnpm-workspace.yaml` (remove `'@graphprotocol/sdk'` from the catalog, and the whole `minumumReleaseAgeExclude` key, whose only entry it is)
+- Modify: `.gitignore` (remove `packages/contracts-test/types/`)
+- Modify: `pnpm-lock.yaml`
+
+**Interfaces:**
+
+- Consumes: nothing.
+- Produces: no package runs `contracts-test`. `scripts/contracts-migration/coverage-baseline.json` and `summarize-coverage.mjs` stay, for the Phase 1 coverage gate.
+
+`packages/contracts/test/` no longer exists, and `build-test.yml` finds coverage files with `find`, so neither needs a change. Say so in the PR.
+
+- [ ] **Step 1: Confirm the deleted suite covers only dead code.** Run `pnpm -r --sequential run build`, then `pnpm --filter @graphprotocol/contracts-tests test:self`. Expected: `361 passing`, 0 failing. Run `git ls-files packages/contracts-test/tests`. Expected: only `curation/`, `disputes/`, `l2/l2Staking.test.ts`, `lib/`, `payments/`, `rewards/subgraphAvailability.test.ts`, `serviceRegisty.test.ts` and `staking/`.
+- [ ] **Step 2: Make the deletions and edits above.**
+- [ ] **Step 3: Update the lockfile.** Run `pnpm install --no-frozen-lockfile`. Expected: `@graphprotocol/sdk` no longer appears in `pnpm-lock.yaml`.
+- [ ] **Step 4: Check no reference is left.** Run `git grep -nE "contracts-tests?\b|@graphprotocol/sdk" -- ':!docs/contracts-removal' ':!**/CHANGELOG.md' ':!scripts/contracts-migration'`. Expected: no output.
+- [ ] **Step 5: Commit.** `chore: remove contracts-test and the sdk`
+- [ ] **Step 6: Run the verification block.** Expected: `test:self` no longer runs `contracts-tests`, and `check:bytecode` prints `OK: 26 contracts match`.
+
+---
+
+### Task D2a: Create `legacy` with verified bundles
+
+**Files:**
+
+- Create: `packages/legacy/package.json`, `packages/legacy/README.md`
+- Create: `packages/legacy/scripts/lib.mjs`, `scripts/fetch-verified.mjs`, `scripts/record-mainnet.mjs`, `scripts/verify.mjs`, `scripts/lib.test.mjs`
+- Create: `packages/legacy/targets.json`, `packages/legacy/mainnet.json`
+- Create: `packages/legacy/verified/<Contract>/compiler.json`, `verified/<Contract>/sources/**`
+- Modify: `.prettierignore`, `.solhintignore` (create it), both adding `packages/legacy/verified/`
+- Create: `.gitattributes` with `packages/legacy/verified/** -text`. `GraphToken.sol` has CRLF line endings, and with `core.autocrlf=input` git would rewrite it on commit and fail its source hash
+- Modify: `scripts/lint-staged-run.sh` (add `"/packages/legacy/verified/"` to `IGNORE_SUBSTRINGS`), `package.json` (wrap both `*.sol` lint-staged commands in `scripts/lint-staged-run.sh`). Without this the commit hook fails: `solhint` exits 255 when every staged file is ignored
+- Modify: `pnpm-lock.yaml`
+
+**Interfaces:**
+
+- Consumes: nothing.
+- Produces: `pnpm --filter @graphprotocol/legacy test:self`, which later tasks rely on to prove the archive still reproduces mainnet.
+
+`package.json`: name `@graphprotocol/legacy`, `"private": true`, version `0.0.0`, license `GPL-2.0-or-later`, devDependencies exactly `"solc-0.7.4": "npm:solc@0.7.4"` and `"solc-0.7.6": "npm:solc@0.7.6"`, script `"test:self": "node --test 'scripts/*.test.mjs' && node scripts/verify.mjs"`. No `build` script. CI's `pnpm -r run test:self` is its CI job, so no workflow changes.
+
+`targets.json`, the implementations to archive, as `{ "<Contract>": { "implementation": "0x...", "proxy": "0x..." | null } }`:
+
+| Contract            | Implementation                               | Proxy                                        | solc  |
+| ------------------- | -------------------------------------------- | -------------------------------------------- | ----- |
+| GraphToken          | `0xc944E90C64B2c07662A292be6244BDf05Cda44a7` | none                                         | 0.7.4 |
+| L1GraphTokenGateway | `0xD41ca6A1d034D178c196DFa916f22f7D1a1B8222` | `0x01cDC91B0A9bA741903aA3699BF4CE31d6C5cC06` | 0.7.6 |
+| BridgeEscrow        | `0xBcD54513aa593646d72aEA31406c633C235Ad6EA` | `0x36aFF7001294daE4C2ED4fDEfC478a00De77F090` | 0.7.6 |
+| L1GNS               | `0x83A5B6C542aB20436087Fc79724bdF06ea80f836` | `0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825` | 0.7.6 |
+| Curation            | `0xDeb46851907fd85DD475780CcE2eE0D67c969825` | `0x8FE00a685Bcb3B2cc296ff6FfEaB10acA4CE1538` | 0.7.6 |
+| L1Staking           | `0x20a14D78848BC8B3F3d4B77239F2adC3C0259A10` | `0xF55041E37E12cD407ad00CE2910B8269B01263b9` | 0.7.6 |
+| StakingExtension    | `0xA479c00cDa8C07bce458D7a826C7b091672EB92C` | none                                         | 0.7.6 |
+
+Functions in `scripts/lib.mjs`:
+
+- `normalizeRuntime(hex: string, ranges: {start: number, length: number}[]): string`: lowercases, drops `0x`, zeroes each byte range, and removes the trailing CBOR metadata using the length in the last 2 bytes.
+- `runtimeRanges(deployedBytecode): {start, length}[]`: every entry of `immutableReferences` and `linkReferences`.
+- `compileBundle(dir: string): {object: string, ranges: {start, length}[], storageLayout}`: builds a solc standard-JSON input from `compiler.json` and the files under `sources/`, with each path relative to `sources/` as the source key and `settings.outputSelection` set to `evm.deployedBytecode.{object,immutableReferences,linkReferences}` and `storageLayout`. It sets `language: 'Solidity'`, loads `solc-0.7.4` or `solc-0.7.6` (the version without `+commit...`) through `createRequire`, asserts `solc.version()` starts with the full version string, throws on any error-severity output, and returns the target's output.
+- `runtimeHash(normalized: string): string`: sha256 hex.
+
+- `checkSources(dir: string): string[]`: compares the files under `sources/` with `sourceHashes` in `compiler.json` and returns each path that is missing, extra or changed.
+
+`compiler.json` keeps `version` (the full `0.7.6+commit.7338295f` string), `settings` (everything from Sourcify except `outputSelection`, including `evmVersion` and `libraries`), `target` (`{source, name}`, split from `fullyQualifiedName`), `sourcifyMatch` (Sourcify's `match` field: a partial match reads `match`, an exact one `exact_match`) and `sourceHashes` (path to sha256).
+
+- [ ] **Step 1: Write the failing tests** in `scripts/lib.test.mjs`:
+
+```js
+test('normalizeRuntime zeroes ranges and removes metadata', () => {
+  // 4 code bytes, then a 2-byte CBOR blob and its 2-byte length
+  assert.equal(normalizeRuntime('0xAABBCCDD' + 'eeff' + '0002', [{ start: 1, length: 2 }]), 'aa0000dd')
+})
+
+test('runtimeRanges reads immutable and link references', () => {
+  const ranges = runtimeRanges({
+    immutableReferences: { 1: [{ start: 3, length: 32 }] },
+    linkReferences: { 'a.sol': { Lib: [{ start: 40, length: 20 }] } },
+  })
+  assert.deepEqual(ranges, [
+    { start: 3, length: 32 },
+    { start: 40, length: 20 },
+  ])
+})
+
+test('verified BridgeEscrow matches mainnet.json', () => {
+  const { object, ranges } = compileBundle(BRIDGE_ESCROW_DIR)
+  assert.equal(runtimeHash(normalizeRuntime(object, ranges)), mainnet.BridgeEscrow.runtimeHash)
+})
+
+test('a code change no longer matches mainnet.json', () => {
+  // Copy the bundle to a temp dir and insert a function right after the target contract's opening brace
+  const { object, ranges } = compileBundle(copyOfBridgeEscrowWithFunctionInserted())
+  assert.notEqual(runtimeHash(normalizeRuntime(object, ranges)), mainnet.BridgeEscrow.runtimeHash)
+})
+
+test('a comment-only change fails the source check', () => {
+  // Bytecode doesn't change here, so only the hashes can catch it
+  assert.deepEqual(checkSources(copyOfBridgeEscrowWithCommentAdded()), [TARGET_SOURCE_PATH])
+})
+```
+
+Read `mainnet.json` inside the tests that use it, because it doesn't exist until Step 5.
+
+- [ ] **Step 2: Run them.** Create `package.json`, run `pnpm install --no-frozen-lockfile` to install the solc aliases, then `cd packages/legacy && node --test scripts/lib.test.mjs`. Expected: FAIL, with `lib.mjs` not implemented.
+- [ ] **Step 3: Implement `scripts/lib.mjs`.** The first two tests pass.
+- [ ] **Step 4: Implement and run `scripts/fetch-verified.mjs`.** For each target, it reads `https://sourcify.dev/server/v2/contract/1/<implementation>?fields=stdJsonInput,compilation` and writes `compiler.json`, including `sourceHashes`, and each source's `content` byte for byte. It reads `stdJsonInput.{sources,settings}`, `compilation.{compilerVersion,fullyQualifiedName}` and `match`. Expected: 7 folders. `verified/GraphToken/sources/` has 1 file, and the file counts of the others are, in the table's order, 26, 18, 38, 33, 35 and 23.
+- [ ] **Step 5: Implement and run `scripts/record-mainnet.mjs`.** It requires `MAINNET_RPC_URL` and exits 1 without it. For each target with a proxy, it reads the EIP-1967 slot `0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc` and exits 1 if it isn't the target's implementation (Review Focus 3). For StakingExtension, it reads `extensionImpl` on the L1Staking proxy, with the slot taken from L1Staking's compiler `storageLayout`, and exits 1 if the slot's low 20 bytes aren't the target (the slot is packed with other values). It reads everything at one pinned block and records that block in `mainnet.json`. It then calls `eth_getCode`, normalizes with the ranges from `compileBundle`, and writes `mainnet.json` as `{ "block": <number>, "contracts": { <Contract>: { implementation, proxy, runtimeHash } } }`. Run `MAINNET_RPC_URL=<url> node scripts/record-mainnet.mjs`. Any public mainnet RPC works, because the data is public.
+- [ ] **Step 6: Implement `scripts/verify.mjs`.** For each folder under `verified/` it runs `checkSources`, then compiles, normalizes and compares with `mainnet.json`. It prints each mismatch and exits 1 on any, and fails if `targets.json`, `verified/` and `mainnet.json` don't list the same contracts. On success it prints the real count: `OK: 7 mainnet implementations reproduce`.
+- [ ] **Step 7: Run it.** `pnpm --filter @graphprotocol/legacy test:self`. Expected: all tests pass and the `OK` line prints.
+- [ ] **Step 8: Add the ignore entries and `.gitattributes`,** run `npx eslint packages/legacy/scripts` by hand (CI's changed-files filter skips paths containing `lib`), and write `README.md`: what the archive is, the table above, that current source reproduces only Curation, that GraphToken and L1Staking are Sourcify partial matches so their sources may differ from the deployed ones outside the code, how to re-run the fetch and record scripts, and that the sources must stay unformatted.
+- [ ] **Step 9: Commit,** with the hook enabled so lint-staged runs (never `--no-verify`). `feat(legacy): archive verified mainnet implementations`
+- [ ] **Step 10: Prove the hook and linters left the sources alone.** Run `pnpm --filter @graphprotocol/legacy test:self`, then the verification block. Expected: the `OK` line prints, so every source hash still matches, and `git status` stays empty. If the hook reformatted a source, fix the ignore file and re-fetch before amending.
+
+---
+
+### Task D2b: Add the legacy address book and audits
+
+**Files:**
+
+- Create: `packages/legacy/addresses.json`
+- Create: `packages/address-book/src/legacy/addresses.json`
+- Move: `packages/contracts/audits/` to `packages/legacy/audits/` (`git mv`)
+- Modify: `packages/address-book/scripts/sources.js` (add `'legacy'`, and correct its comment), `packages/address-book/README.md` (the sources are regular files, not symlinks)
+- Create: a minor changeset for `@graphprotocol/address-book`, which gains a published export
+- Modify: `packages/legacy/README.md`
+
+**Interfaces:**
+
+- Consumes: the `legacy` package from D2a.
+- Produces: `@graphprotocol/address-book` exposes `src/legacy/addresses.json`.
+
+`legacy/addresses.json` holds the `1` and `11155111` entries of `packages/contracts/addresses.json`, unchanged and complete, including Controller, EpochManager, RewardsManager, DisputeManager, ServiceRegistry, GraphProxyAdmin and SubgraphNFT. Copy `packages/legacy/addresses.json` to `packages/address-book/src/legacy/addresses.json` as a regular file, like the other four (mode 100644, byte-identical to their sources). `postpublish` still runs `restore-symlinks`, so the README should say the sources are tracked as regular files and become symlinks only after a publish, and its Features and usage sections should list `legacy`. Don't run `restore-symlinks`.
+
+Adding GraphCurationToken and SubgraphNFTDescriptor to `horizon/addresses.json` is Phase 1 step 3, not this task.
+
+- [ ] **Step 1: Generate `addresses.json`** with a one-off Node command, then compare: `node -e` that deep-equals `addresses.json['1']` and `['11155111']` with `packages/contracts/addresses.json`. Expected: equal, and the top-level keys are exactly `1` and `11155111`. Run prettier on both copies, then `cmp packages/legacy/addresses.json packages/address-book/src/legacy/addresses.json`. Expected: identical.
+- [ ] **Step 2: Make the other changes.**
+- [ ] **Step 3: Check the audits moved.** Run `git ls-files packages/legacy/audits | wc -l`. Expected: `29`. Run `git grep -n "contracts/audits" -- ':!**/CHANGELOG.md' ':!docs/contracts-removal'`, and update any link it finds.
+- [ ] **Step 4: Commit.** `feat(legacy): add address book and historical audits`
+- [ ] **Step 5: Run the verification block.**
+
+---
+
+### Task D3a: Point Ignition at the 7.3.0 alias
+
+**Files:**
+
+- Modify: `packages/horizon/package.json`, `packages/subgraph-service/package.json` (add the devDependency `"@graphprotocol/contracts-7.3.0": "npm:@graphprotocol/contracts@7.3.0"`; keep the `@graphprotocol/contracts` workspace dependency)
+- Modify: the 15 import-holding files under `ignition/modules/`: in horizon `core/HorizonStaking.ts`, `migrate/migrate-4.ts`, `proxy/GraphProxy.ts` and `periphery/{Controller,Curation,EpochManager,GNS,GraphProxyAdmin,GraphToken,GraphTokenGateway,RewardsManager}.ts`; in subgraph-service `Curation.ts`, `DisputeManager.ts`, `GNS.ts`, `ServiceRegistry.ts`
+- Modify: `packages/horizon/scripts/pre-verify`, `packages/subgraph-service/scripts/pre-verify` (copy from `node_modules/@graphprotocol/contracts-7.3.0/artifacts`, then the three live contracts' folders and the workspace `build-info` over them). `tenderly.config.json` doesn't change, because its only external contracts are L2Curation and RewardsManager
+- Modify: `pnpm-lock.yaml`
+
+**Interfaces:**
+
+- Consumes: nothing.
+- Produces: the modules and their verification tooling no longer read artifacts from the workspace package, so D3b and Phase 1 can remove them.
+
+- [ ] **Step 1: Add the dependency,** and run `pnpm install --no-frozen-lockfile`.
+- [ ] **Step 2: Replace the package name.** First run `git grep -l "@graphprotocol/contracts/artifacts" -- 'packages/*/ignition/modules/**' | wc -l`. Expected: `15`. In the listed files only, `@graphprotocol/contracts/artifacts/` becomes `@graphprotocol/contracts-7.3.0/artifacts/`, except imports of RewardsManager, L2GNS and L2Curation, which stay on live artifacts.
+- [ ] **Step 3: Check the diff is only that.** Run `git diff -- 'packages/*/ignition/**' | grep -E '^[-+][^-+]' | grep -v "@graphprotocol/contracts"`. Expected: no output. Run `git diff --stat -- 'packages/*/ignition/deployments/**'`. Expected: no output. Run `git grep -n "@graphprotocol/contracts/artifacts" -- 'packages/*/ignition/modules/**'`. Expected: exactly 5 lines, the three live contracts.
+- [ ] **Step 4: Point the verification tooling at the alias.** Edit both `pre-verify` scripts as listed under Files. CI never runs them, so Step 7 checks them.
+- [ ] **Step 5: Commit.** `chore(ignition): read deployment artifacts from published contracts 7.3.0`
+- [ ] **Step 6: Run the verification block.** Expected: `check:bytecode` still prints `OK: 26 contracts match`, and horizon's and subgraph-service's suites pass unchanged (Review Focus 4).
+- [ ] **Step 7: Run `pre-verify`.** In `packages/horizon` and `packages/subgraph-service`, run `bash scripts/pre-verify review-tmp && rm -rf ignition/deployments/review-tmp`. Expected: exit 0, and `git status` stays empty.
+- [ ] **Step 8: Load the modules.** Run `npx hardhat --help` and `npx tsc --noEmit -p .` in `packages/horizon` and `packages/subgraph-service`. Expected: `--help` exits 0 in both, and `tsc` reports no error mentioning `contracts-7.3.0`.
+
+---
+
+### Task D3b: Delete the dead contracts
+
+**Files:**
+
+- Delete, under `packages/contracts/contracts/`:
+  - `discovery/L1GNS.sol`, `discovery/L1GNSStorage.sol`, `curation/Curation.sol`, `bancor/BancorFormula.sol`
+  - `staking/Staking.sol`, `staking/L1Staking.sol`, `staking/L1StakingStorage.sol`, `staking/StakingExtension.sol`, `staking/StakingStorage.sol`, `staking/libs/Stakes.sol`, `staking/libs/Exponential.sol`, `staking/libs/LibFixedMath.sol`, `l2/staking/L2Staking.sol`
+  - `disputes/DisputeManager.sol`, `disputes/DisputeManagerStorage.sol`, `discovery/ServiceRegistry.sol`, `discovery/ServiceRegistryStorage.sol`
+  - `payments/AllocationExchange.sol`, `discovery/erc1056/EthereumDIDRegistry.sol`, `rewards/SubgraphAvailabilityManager.sol`
+  - `tests/arbitrum/ArbSysMock.sol`, `tests/ens/IENS.sol`, `tests/ens/IPublicResolver.sol`, `tests/ens/ITestRegistrar.sol`, `tests/LegacyGNSMock.sol`, `tests/MockERC165.sol`, `tests/MockIssuanceAllocator.sol`, `tests/MockRewardsEligibilityOracle.sol`, `tests/MockSubgraphService.sol`, `tests/L1GraphTokenLockTransferToolMock.sol`, `tests/L1GraphTokenLockTransferToolBadMock.sol`
+- Delete: `packages/contracts/addresses-staging.json`, `packages/contracts/arbitrum-addresses.json`, `packages/contracts/config/` (`addresses-local.json` is not tracked)
+- Modify: `packages/contracts/index.js`, `packages/contracts/index.d.ts` (remove `configDir`)
+- Modify: `packages/deployment/test/bytecode-comparison.test.ts:235,239` (load `('l2/curation', 'L2Curation')` and `('l2/token', 'L2GraphToken')` instead of the deleted Staking and Curation, and rename the two variables to match)
+- Modify: `packages/issuance/test/unit/rewards-manager/mocks/RMEligibilityOracleMock.sol`, `RMIssuanceAllocatorMock.sol` (their `///` comments name the deleted mocks; say they are the test's own mocks without pointing at a deleted file)
+- Modify: `packages/contracts/hardhat.config.ts` (remove the `StakingExtension` warnings entry)
+- Modify: `scripts/contracts-migration/manifest.json`, `scripts/contracts-migration/reference.json` (remove `L1GNS`, `Curation`, `L1Staking`, `StakingExtension`, `LibExponential`)
+
+**Interfaces:**
+
+- Consumes: `legacy` from D2a, and the Ignition alias from D3a.
+- Produces: `packages/contracts` holds only live contracts and the mocks ported tests use: 43 Solidity files. Other leftovers that point at deleted things (`.env.example`, `scripts/upgrade`) stay until Phase 2a deletes the package.
+
+Edit `reference.json` by removing those 5 keys. Don't regenerate it with `--write`: leaving the other 21 hashes untouched is what shows the deletions changed no live bytecode.
+
+- [ ] **Step 1: Make the deletions and edits.**
+- [ ] **Step 2: Rebuild from clean.** Run `pnpm --filter @graphprotocol/contracts clean && pnpm --filter @graphprotocol/contracts build`. Expected: exit 0. A stale artifact mustn't hide a broken import.
+- [ ] **Step 3: Commit.** `refactor(contracts): delete dead contracts now archived in legacy`
+- [ ] **Step 4: Run the verification block.** Expected: `check:bytecode` prints `OK: 21 contracts match`, and `test:self` includes `OK: 7 mainnet implementations reproduce`.
+- [ ] **Step 5: Count what's left.** Run `git ls-files 'packages/contracts/contracts/*.sol' | wc -l`. Expected: `43`.
+- [ ] **Step 6: Load the modules.** Run `npx hardhat --help` in `packages/horizon` and `packages/subgraph-service`. Expected: exit 0 (Review Focus 5).
+- [ ] **Step 7: Check nothing else consumed them.** Run `git grep -nE "(@graphprotocol/contracts/(artifacts/)?contracts/|_ARTIFACTS, \"|ARTIFACTS \+ \"|loadContractsArtifact\(')(staking/(Staking|L1Staking|StakingExtension|StakingStorage|libs/(Stakes|Exponential|LibFixedMath))|staking'|l2/staking|disputes|payments|curation/Curation\.|curation'|bancor|discovery/(L1GNS|ServiceRegistry|erc1056)|rewards/SubgraphAvailability|tests/(arbitrum/ArbSysMock|ens/|LegacyGNSMock|MockERC165|MockIssuanceAllocator|MockRewardsEligibilityOracle|MockSubgraphService|L1GraphTokenLock))" -- ':!**/CHANGELOG.md' ':!docs/contracts-removal' ':!packages/*/ignition/deployments/**' ':!scripts/contracts-migration/test-mapping/**'`. Expected: no output.
diff --git a/docs/contracts-removal/phase-p-plan.md b/docs/contracts-removal/phase-p-plan.md
new file mode 100644
index 000000000..cef2a5d04
--- /dev/null
+++ b/docs/contracts-removal/phase-p-plan.md
@@ -0,0 +1,332 @@
+# Contracts Removal — Phase P (Ports to 0.8) and Phase 2 (Final Removal) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Port RewardsManager, L2GNS and L2Curation to Solidity 0.8 in their domain packages without changing behaviour or storage layout, then delete `packages/contracts`.
+
+**Architecture:**
+
+- Pa moves `interfaces` to OpenZeppelin 5, so a 0.8 RewardsManager can compile in issuance's Hardhat 3 build.
+- Pb ports RewardsManager, RewardsManagerStorage and MathUtils into issuance. Pc ports L2GNS, GNS, L2Curation, their storage contracts and Multicall into subgraph-service, adds `InitializableV3`, and deletes `subgraph-discovery`.
+- Each port keeps the files' subpaths under `contracts/`, so coverage-baseline keys don't change. The ported files compile with their own per-file settings, without `viaIR`. The T3 and T5 suites run against both the pre-port 0.7.6 artifact (a committed fixture) and the 0.8 build.
+- 2a deletes the then-empty `packages/contracts` and every reference to it. 2b is a manual `npm deprecate`.
+
+**Tech Stack:** pnpm workspaces, Hardhat 2 (subgraph-service, horizon), Hardhat 3 (issuance), Foundry 1.8.3, solc 0.7.6 and 0.8.35, OpenZeppelin 3.4.2 and 5.4, Ignition, Node 24.
+
+**Spec:** `docs/contracts-removal/design.md` (§3 "Ports to 0.8", §4 "Differential tests for ports", §5, "PR sequence → Phase P" and "Phase 2", Verification).
+
+Phase 1 is merged into #1373 (head `813cac0a`). Counts marked `TBD` are filled in by a dry run before each task starts.
+
+## Global Constraints
+
+- Each task is a draft PR in one chain: Pa targets `chore/contracts-removal-phase-0` (#1373), and each later task targets the one before. Nothing goes to main before the audit.
+- Conventional commits, no Co-Authored-By line and no Claude attribution in commits or PRs.
+- A port PR has exactly two commits. The first is a pure `git mv` of the ported contracts: every entry in `git show --name-status -M HEAD~1` is `R100`. It doesn't build; the PR says so. The second holds the port and everything else. Auditors read `git show <second> -- 'packages/<pkg>/contracts/**' <compile config files>`.
+- Allowed source changes in a port, and nothing else:
+  - the pragma becomes `^0.8.27`;
+  - SafeMath calls become checked operators, one operator per call: `a.mul(b).div(c)` becomes `(a * b) / c` and `x.mul(y.sub(z))` becomes `x * (y - z)`. Each receiver and argument keeps its grouping, explicit casts stay, and no terms are merged, reordered or simplified, so every intermediate value that could overflow or underflow is the same;
+  - OpenZeppelin 3 imports become OpenZeppelin 5 or local equivalents;
+  - whatever 0.8 requires to compile;
+  - the design's known port points (§3);
+  - `// forge-lint: disable-next-line(<lint>)` comments for `lint:forge` findings on unchanged code, each listed in the PR.
+- Ported files compile with solc 0.8.35, optimizer enabled, 200 runs (the 0.7.6 build's value), `evmVersion: cancun`, no `viaIR`. They keep their subpaths under `contracts/`. If a compile without `viaIR` fails with stack too deep, stop and report.
+- Tests never import a ported contract's source. They reach it through interfaces or `*Like` interfaces, and deploy it with `deployCode` or from a fixture.
+- Issuance's code and tests never use horizon, subgraph-service or graph-token.
+- `reference.json` and `coverage-baseline.json` are never regenerated. A ported contract's entries are deleted from `manifest.json` and `reference.json` by hand, and nothing else changes in them.
+- No RPC URL or API key is ever written to a file, commit, report or PR. RPC URLs are passed only as inline env vars.
+- Run `pnpm install --no-frozen-lockfile` right after any `package.json` edit. Check the lockfile changes no solc, OpenZeppelin, Hardhat or forge-std version, except the `interfaces` OpenZeppelin change in Pa.
+- Before Pb and Pc, list open PRs and security advisories that touch the contracts being ported, and stop for the user's decision if there are any. If main changes a living contract before its port is merged into the base, the port is redone on top of that change.
+- The pre-port tag is `pre-port-0.7.6`, on Pb's parent commit, once Pa is merged into the base branch. If any of Pc's seven contracts change on the base after that, Pc's parent also gets `pre-port-0.7.6-l2`, once Pb is merged. Tags are pushed only with the user's approval.
+
+**Verification for every PR**, run from the repo root after committing. It doesn't replace CI's lint job (`lint.yml`):
+
+```bash
+pnpm install --frozen-lockfile
+pnpm -r --sequential run clean
+pnpm -r --sequential run build
+pnpm test:scripts
+pnpm check:bytecode
+pnpm -r --sequential run test:self
+pnpm lint:sol; git status --short
+pnpm --filter @graphprotocol/issuance --filter @graphprotocol/subgraph-service lint:forge
+(cd packages/subgraph-service && npx hardhat deploy:protocol --network hardhat --subgraph-service-config localNetwork)
+rm -rf packages/deployment/fork
+FORK_NETWORK=arbitrumSepolia pnpm --filter @graphprotocol/deployment exec hardhat deploy --tags sync --skip-prompts --network fork
+```
+
+Expected:
+
+- All exit 0. `check:bytecode` prints `OK: 21 contracts match` in Pa, `OK: 20` from Pb and `OK: 18` from Pc.
+- `git status` prints nothing after `lint:sol`. `deploy:protocol` may write address books and an Ignition journal: delete the untracked files it creates and restore the tracked address books it changed, nothing else.
+- `lint:forge` reports nothing. Expected findings in ported files (for example `erc20-unchecked-transfer` at the old `L2GNS.sol:157,301`) are silenced with `forge-lint: disable-next-line` comments, as subgraph-service already does (`DisputeManager.sol:6`). Code is never changed to satisfy a lint.
+- In each port, `npx solhint --max-warnings=0 <ported files>`, run in the destination package, exits 0, as CI's `lint.yml` requires for changed files.
+- Fork sync, compared with the parent commit's output: identical in Pa and 2a; only `RewardsManager` differs in Pb; only `L2GNS` and `L2Curation` differ in Pc. Record the parent's output in the scratchpad before starting. The public RPC default needs no secret, and a private one goes in as an inline `ARBITRUM_SEPOLIA_RPC=`. The `rm -rf` is required: the sync caches address books.
+
+**Rebuild rule:** after a failed Hardhat compile in horizon or subgraph-service, run `rm -rf build cache` before retrying.
+
+**TypeScript check:** in the named package, `npx tsc --noEmit | grep -c 'error TS'` is no higher than on the parent commit, and no new error mentions a changed file. Plain `tsc` can't exit 0, because horizon and subgraph-service have unrelated errors today.
+
+**Fresh-stack check**, for Pb and Pc. The verification block's `--network hardhat` run leaves no chain to query, so run against a node:
+
+1. Start `npx hardhat node` in subgraph-service in the background.
+2. Run `npx hardhat deploy:protocol --network localhost --subgraph-service-config localNetwork`.
+3. Check with `cast code --rpc-url http://127.0.0.1:8545 <address>` that `L2Curation`, `L2GNS`, `SubgraphNFT` and `RewardsManager` in the written address books have code. Check with `cast call <L2Curation> "curationTokenMaster()(address)"` that the master it returns has code.
+4. Stop the node. Delete the untracked files the run created and restore the tracked address books it changed, nothing else.
+
+**Coverage gate** for each port, run in the destination package:
+
+```bash
+forge coverage --report lcov --report-file /tmp/<pkg>.lcov
+node ../../scripts/contracts-migration/summarize-coverage.mjs /tmp/<pkg>.lcov /tmp/<pkg>.json
+node ../../scripts/contracts-migration/compare-coverage.mjs ../../scripts/contracts-migration/coverage-baseline.json /tmp/<pkg>.json <ported contract paths>
+```
+
+The gate fails if a baseline function isn't hit. Add a test for each regression, through the contract's public interface. If a test can't reach one, stop and report. List files below their baseline line percentage in the PR with a reason. Coverage compiles without the optimizer, so if a ported contract fails to deploy with `CreateContractSizeLimit`, add `--disable-code-size-limit` to the package's `test:coverage` and `test:coverage:self`.
+
+**Port PR description** lists: the `forge-lint` comments added; that the first commit doesn't build; the tests whose expected revert data differs between the builds (or "none"); the storage-layout comparison output; the 0.8 deployed sizes; files below baseline coverage; and the fork-sync difference.
+
+## Review Focus
+
+1. **A ported contract compiles with other settings than intended.** An override key that doesn't match its file falls back to the package default (`viaIR` on), and a Foundry pin that doesn't apply leaves the optimizer off. Each ported deployable gets `test_Build_FoundryMatchesHardhat`, and each port step checks the Hardhat build-info.
+2. **The suite runs a different build from the one requested.** If `PRE_PORT` were ignored, or the fixture were stale, both runs would pass while testing one build. `test_Build_DeploysRequestedBuild` compares the deployed implementation with reference deployments of both builds, and the fixture's bytecode hashes are checked against `reference.json`.
+3. **Subgraph ID aliasing stops wrapping.** About 6.7% of L1 IDs wrap when aliased, and unaliasing wraps the other way. `test_GetAliasedL2SubgraphID_WrapsAroundMaxUint256` exists; Pc adds `test_GetUnaliasedL1SubgraphID_WrapsBelowZero`. Both run on both builds.
+4. **`InitializableV3` changes initializer state.** L2Curation's `_initialized` and `_initializing` must stay in slot 16, and re-initialization must revert the same way. Pc adds slot and re-initialization tests that run on both builds, and compares storage layouts.
+5. **The fresh-stack deployment loses a contract.** After Pc, horizon's modules are built by factories that receive the L2GNS and L2Curation artifacts from subgraph-service's task, and every module that used the periphery module must get the same instance. The fresh-stack check runs in Pb and Pc.
+
+---
+
+### Task Pa: Move `interfaces` to OpenZeppelin 5
+
+**Files:**
+
+- Modify: `packages/interfaces/package.json` (`@openzeppelin/contracts` `^5.4.0` in `dependencies`; remove both OpenZeppelin `devDependencies`)
+- Modify: `packages/interfaces/contracts/contracts/curation/IGraphCurationToken.sol`
+- Modify: `packages/deployment/scripts/generate-abis.ts:32` (IERC165 artifact path)
+- Create: `.changeset/interfaces-openzeppelin-5.md` (`@graphprotocol/interfaces: major`)
+- Modify: `pnpm-lock.yaml`
+
+**Interfaces:**
+
+- Consumes: nothing.
+- Produces: `IGraphCurationToken is IERC20` (OpenZeppelin 5), and `interfaces` resolving `@openzeppelin/contracts` 5.4 for Hardhat 3 consumers.
+
+- [ ] **Step 1: Record the fork output and selectors on the parent commit.** Save the fork output, and for `IGraphCurationToken`, `IGraphToken` and `ISubgraphNFT` save the sorted function and event signatures from their `interfaces` artifacts: `jq -r '[.abi[] | select(.type=="function" or .type=="event") | .name + "(" + ([.inputs[].type] | join(",")) + ")"] | sort[]'`.
+- [ ] **Step 2: Change the dependency** and install. Expected: the lockfile changes `interfaces`' OpenZeppelin entries and nothing else of note. `node -p "require('@openzeppelin/contracts/package.json').version"`, run in `packages/interfaces`, `packages/issuance` and `packages/subgraph-service`, prints the same 5.4 version in all three; Hardhat 3 would otherwise compile two `IERC20`s.
+- [ ] **Step 3: Change `IGraphCurationToken`** to import `IERC20` from `@openzeppelin/contracts/token/ERC20/IERC20.sol` and extend it. Run `pnpm --filter @graphprotocol/interfaces clean && pnpm --filter @graphprotocol/interfaces build`. Expected: exit 0; `artifacts/@openzeppelin/` holds `contracts/token/ERC20/IERC20.sol`, `contracts/token/ERC721/IERC721.sol` and `contracts/utils/introspection/IERC165.sol`, and no `contracts-upgradeable`. The three signature lists equal Step 1's.
+- [ ] **Step 4: Update `generate-abis.ts`** to `@graphprotocol/interfaces/artifacts/@openzeppelin/contracts/utils/introspection/IERC165.sol/IERC165.json`. Run `pnpm --filter @graphprotocol/deployment build:self`, which regenerates the gitignored ABIs, then `pnpm --filter @graphprotocol/deployment test:self`. Expected: both PASS.
+- [ ] **Step 5: Write the changeset.** It says the generated `IERC20Upgradeable` types are gone, the `IERC165` types moved to `utils/introspection`, and ABI parameter names follow OpenZeppelin 5 (for example `transfer(to, value)`, `setApprovalForAll(operator, approved)`), which changes the wagmi ABIs.
+- [ ] **Step 6: Commit.** `feat(interfaces)!: use OpenZeppelin 5`
+- [ ] **Step 7: Run the verification block.** `check:bytecode` passing shows graph-core, graph-token, L2GNS and L2Curation are unaffected.
+
+---
+
+### Task Pb: Port RewardsManager to issuance
+
+**Files:**
+
+- Move: `packages/contracts/contracts/rewards/{RewardsManager,RewardsManagerStorage}.sol` to `packages/issuance/contracts/rewards/`, and `staking/libs/MathUtils.sol` to `packages/issuance/contracts/staking/libs/`
+- Create: `packages/issuance/test/fixtures/pre-port/RewardsManager.json` and `RewardsManager.storage.json`, `packages/issuance/test/unit/rewards-manager/build.t.sol`, `.changeset/issuance-rewards-manager.md` (`@graphprotocol/issuance: minor`)
+- Create: `scripts/contracts-migration/compare-storage-layout.mjs`, `compare-storage-layout.test.mjs`
+- Modify: issuance `hardhat.base.config.ts`, `foundry.toml`, `package.json`, `test/unit/shared/ProtocolFixture.t.sol`, `test/unit/rewards-manager/shared.t.sol`, `docs/testing/reo/{RewardsConditions,SubgraphDenial}TestPlan.md`
+- Modify: horizon `ignition/modules/periphery/RewardsManager.ts`, `package.json`
+- Modify: testing `test/harness/RealRewardsHarness.t.sol`, `test/integration/IndexingRewardsCollection.t.sol`, `foundry.toml`, `package.json`
+- Modify: deployment `lib/contract-registry.ts:142`, `test/bytecode-comparison.test.ts`
+- Modify: `scripts/contracts-migration/{manifest,reference}.json`, root `count-patterns.txt:10` and `.prettierignore`, `pnpm-lock.yaml`
+- Create: `packages/issuance/.prettierignore` (`test/fixtures/pre-port/`), because package-level `prettier -w` reads only its own directory's ignore file
+
+**Interfaces:**
+
+- Consumes: `interfaces` on OpenZeppelin 5 (Pa).
+- Produces:
+  - `@graphprotocol/issuance/artifacts/contracts/rewards/RewardsManager.sol/RewardsManager.json`.
+  - In each package's `ProtocolFixture`: `_isPrePort() returns (bool)`, which is `vm.envOr("PRE_PORT", false)`, and `_deployPorted(string memory id, string memory fixture) returns (address)`, which returns `deployCode(id)` or, when `_isPrePort()`, `_deployArtifact(fixture, "")`. `id` has the form `"RewardsManager.sol:RewardsManager"`. Pc copies both.
+  - `compareLayouts(before, after)` in `compare-storage-layout.mjs`, returning a list of differences. The CLI is `<before.json> <after.json>`, prints them, and exits 1 if there are any.
+  - Fixture layout: `test/fixtures/pre-port/<Contract>.json` (the Hardhat artifact, unchanged) and `<Contract>.storage.json` (`forge inspect` storage layout).
+
+- [ ] **Step 1: Check in-flight work.** List open PRs whose files touch `packages/contracts/contracts/{rewards,staking/libs}/`, and the open security advisories for RewardsManager. If there are any, stop and report.
+- [ ] **Step 2: Record the parent commit's outputs.** Ask the controller to tag the parent `pre-port-0.7.6` (Global Constraints). Then:
+  - Run `pnpm --filter @graphprotocol/contracts clean && pnpm --filter @graphprotocol/contracts build`, then `pnpm check:bytecode`. Expected: `OK: 21`. Copy `packages/contracts/artifacts/contracts/rewards/RewardsManager.sol/RewardsManager.json` to the scratchpad.
+  - Write the storage layout to the scratchpad. Run it in `packages/contracts`. `--root .` is needed because the package has no `foundry.toml`. `--out` and `--cache-path` go in the scratchpad, because forge's default `cache/` would overwrite Hardhat's cache file:
+
+    ```bash
+    forge inspect contracts/rewards/RewardsManager.sol:RewardsManager storageLayout --json --use 0.7.6 --root . \
+      --contracts contracts --lib-paths node_modules \
+      --remappings @openzeppelin/=node_modules/@openzeppelin/ --remappings @graphprotocol/=node_modules/@graphprotocol/ \
+      --out <scratch>/out --cache-path <scratch>/cache
+    ```
+
+  - Record the fork output.
+
+- [ ] **Step 3: Move.** `git mv` the three files. Run `git show --name-status -M HEAD` after committing. Expected: three `R100` lines. Commit `refactor(issuance): move RewardsManager from contracts`.
+- [ ] **Step 4: Write the storage-layout tests first.** Cases:
+  - identical layouts give `[]`;
+  - a changed `slot` or `offset` is reported, naming the variable's `label`;
+  - layouts that differ only in `astId`, `contract` and type ids (such as `t_contract(IRewardsIssuer)1234`) give `[]`;
+  - a struct member moved inside a struct is reported;
+  - a struct member moved inside a struct reached only as a mapping's value is reported;
+  - two variables with the same label (L2GNS has three `__gap`s) are compared separately, and a change to the second is reported;
+  - a variable added at the end is reported.
+
+  `storage` entries are compared by position, `storage[i]` with `storage[i]`, plus a length check. Each pair compares `label`, `slot`, `offset`, and the referenced type's `label`, `encoding` and `numberOfBytes`. Types are compared recursively through `members`, `key`, `value` and `base`. Run `pnpm test:scripts`. Expected: FAIL.
+
+- [ ] **Step 5: Implement `compare-storage-layout.mjs`.** Run `pnpm test:scripts`. Expected: PASS.
+- [ ] **Step 6: Port the three files** within the allowed changes: SafeMath and its import go, `IERC165` comes from `@openzeppelin/contracts/utils/introspection/IERC165.sol`, and RewardsManagerStorage's dual pragma becomes `^0.8.27`. The `+=` at the old `RewardsManager.sol:482` stays checked.
+- [ ] **Step 7: Set the compile config.**
+  - In `hardhat.base.config.ts`, change `issuanceBaseConfig.solidity` to `{ compilers: [issuanceSolidityConfig], overrides }`. `overrides` maps each of `contracts/rewards/RewardsManager.sol`, `contracts/rewards/RewardsManagerStorage.sol` and `contracts/staking/libs/MathUtils.sol` to `{ version: '0.8.35', settings: { optimizer: { enabled: true, runs: 200 }, evmVersion: 'cancun' } }`. Hardhat 3 keys overrides by the user source name, without a `project/` prefix.
+  - In `foundry.toml`, add an `additional_compiler_profiles` entry and a `compilation_restrictions` entry that pin `contracts/rewards/**` and `contracts/staking/**` to the same settings. If Foundry can't express them, stop and report.
+  - In `package.json`, move `@graphprotocol/graph-core` and `@graphprotocol/interfaces` to `dependencies`, because the published sources import both, and remove `@graphprotocol/contracts`. Install.
+  - Run `pnpm --filter @graphprotocol/issuance build:self`. Expected:
+    - exit 0;
+    - in the build-info for RewardsManager, `viaIR` is absent or false, the optimizer is enabled with 200 runs, and the version is 0.8.35;
+    - the `deployedBytecode` is under 24,576 bytes.
+- [ ] **Step 8: Compare storage layouts.** Run `forge inspect RewardsManager storageLayout --json` in issuance, and pass its output and Step 2's to `compare-storage-layout.mjs`. Expected: exit 0. Commit Step 2's layout as `test/fixtures/pre-port/RewardsManager.storage.json`.
+- [ ] **Step 9: Switch the suite to both builds.**
+  - Copy Step 2's artifact to `test/fixtures/pre-port/RewardsManager.json`. Add `packages/*/test/fixtures/pre-port/` to the root `.prettierignore`, and create the package `.prettierignore`. Expected: `bytecodeHash` from `scripts/lib/bytecode.mjs`, applied to the fixture's `bytecode` and `deployedBytecode`, equals `RewardsManager`'s entries in the parent commit's `reference.json`.
+  - Add `_isPrePort` and `_deployPorted` to `ProtocolFixture`, and remove `PKG_ARTIFACTS` and its `fs_permissions` entry. In `shared.t.sol`, deploy with `_deployPorted("RewardsManager.sol:RewardsManager", "test/fixtures/pre-port/RewardsManager.json")`.
+  - Set `test:self` to `forge test && PRE_PORT=true forge test --match-path 'test/unit/rewards-manager/**'`.
+- [ ] **Step 10: Pin Review Focus 1 and 2** in `build.t.sol`:
+  - `test_Build_FoundryMatchesHardhat`: `vm.getCode("RewardsManager.sol:RewardsManager")` equals `.bytecode` of `artifacts/contracts/rewards/RewardsManager.sol/RewardsManager.json`, each with its CBOR metadata tail stripped. It starts with `vm.skip(_isPrePort() || vm.isContext(VmSafe.ForgeContext.Coverage))`.
+  - `test_Build_DeploysRequestedBuild`: deploy one reference of each build, the fixture with `_deployArtifact` and the port with `deployCode(id)`. The suite's implementation has the requested build's code hash and not the other's. Artifact `deployedBytecode` can't be compared directly, because Managed's `immutable`s are patched into the runtime code at deployment.
+
+  Run `pnpm --filter @graphprotocol/issuance test:self`. Expected: `TBD` passing in each run, 0 failing. Where the builds' revert data differ, the test expects `_isPrePort() ? pre : port`, and the PR lists it.
+
+- [ ] **Step 11: Coverage gate** for `contracts/rewards/RewardsManager.sol`, `contracts/rewards/RewardsManagerStorage.sol` and `contracts/staking/libs/MathUtils.sol`. Run `pnpm --filter @graphprotocol/issuance test:coverage:self`. Expected: exit 0.
+- [ ] **Step 12: Repoint consumers.**
+  - horizon: change the RewardsManager module import to `@graphprotocol/issuance/artifacts/contracts/rewards/RewardsManager.sol/RewardsManager.json`, and add `@graphprotocol/issuance` as a devDependency.
+  - testing:
+    - `RM_ARTIFACT` points at issuance's artifact, with an `fs_permissions` entry for `node_modules/@graphprotocol/issuance/artifacts`; remove the `contracts` entry and devDependency.
+    - Replace the mock fallback with `require(vm.exists(RM_ARTIFACT), "RewardsManager artifact missing: build issuance")`. Remove `realRmAvailable` and the skip in `IndexingRewardsCollection.t.sol`, and update the harness comment.
+  - deployment: set the registry entry to `{ type: 'issuance', path: 'contracts/rewards/RewardsManager.sol/RewardsManager' }`. Load RewardsManager in `bytecode-comparison.test.ts` from issuance with `loadIssuanceArtifact`.
+  - Delete the `RewardsManager` entries from `manifest.json` and `reference.json`, and line 10 of `count-patterns.txt`. Change the RewardsManager path in the two REO test plans.
+  - Write the changeset. Install.
+
+  Expected:
+  - `git grep -nI "contracts/rewards/RewardsManager" -- . ':!docs/contracts-removal' ':!**/CHANGELOG.md' ':!scripts/contracts-migration/coverage-baseline.json' ':!scripts/contracts-migration/test-mapping' ':!scripts/contracts-migration/*.test.mjs'` lists only issuance paths, the comment at `packages/deployment/tasks/verify-contract.ts:55`, and `packages/contracts/scripts/flatten`, which 2a deletes.
+  - `pnpm --filter @graphprotocol/testing test:self` reports `TBD` passing, 0 skipped.
+  - `pnpm --filter @graphprotocol/deployment test:self` passes.
+  - The fresh-stack check passes.
+
+- [ ] **Step 13: Commit.** `refactor(issuance): port RewardsManager to Solidity 0.8`
+- [ ] **Step 14: Run the verification block.**
+
+---
+
+### Task Pc: Port L2GNS and L2Curation to subgraph-service
+
+**Files:**
+
+- Move: from `packages/contracts/contracts/` to `packages/subgraph-service/contracts/`, same subpaths: `base/Multicall.sol`, `curation/CurationStorage.sol`, `discovery/{GNS,GNSStorage}.sol`, `l2/curation/L2Curation.sol`, `l2/discovery/{L2GNS,L2GNSStorage}.sol`
+- Move: `packages/subgraph-discovery/test/unit/` to `packages/subgraph-service/test/unit/discovery/`, keeping its inner layout; delete the rest of `packages/subgraph-discovery/`
+- Create: `packages/subgraph-service/contracts/upgrades/InitializableV3.sol`; `test/fixtures/pre-port/{L2GNS,L2Curation}.json` and `.storage.json`; `test/unit/discovery/Build.t.sol`; `.prettierignore` (`test/fixtures/pre-port/`); `.changeset/subgraph-service-discovery.md` (`@graphprotocol/subgraph-service: minor`)
+- Modify: subgraph-service `hardhat.config.ts`, `foundry.toml`, `package.json`, `tasks/deploy.ts`, `ignition/modules/{GNS,Curation}.ts`
+- Modify: horizon `ignition/modules/{deploy,index}.ts`, `ignition/modules/periphery/{periphery,Curation,GNS}.ts`, `ignition/modules/core/{core,HorizonProxies,HorizonStaking,GraphPayments,PaymentsEscrow,GraphTallyCollector,RecurringCollector}.ts`, `package.json`, `README.md`; delete `tasks/deploy.ts`
+- Modify: deployment `lib/contract-registry.ts:179,205`, `tasks/verify-contract.ts`, `test/bytecode-comparison.test.ts`, `package.json`
+- Modify: `scripts/contracts-migration/{manifest,reference}.json`, root `CLAUDE.md`, `pnpm-lock.yaml`
+
+**Interfaces:**
+
+- Consumes:
+  - `_isPrePort` and `_deployPorted` (Pb), copied into `test/unit/discovery/shared/ProtocolFixture.t.sol`;
+  - `compare-storage-layout.mjs` and the fixture layout from Pb.
+- Produces:
+  - `buildHorizonModule(artifacts: { L2Curation: Artifact; L2GNS: Artifact })` exported from `@graphprotocol/horizon/ignition`, replacing `HorizonModule`. `Artifact` comes from `@nomicfoundation/ignition-core`.
+  - `InitializableV3`: OpenZeppelin 3.4.2's `contracts-upgradeable/proxy/Initializable.sol`, renamed, with `_isConstructor()` returning `address(this).code.length == 0`. The `_initialized`/`_initializing` layout, the `initializer` modifier and its revert string are unchanged.
+
+- [ ] **Step 1: Check in-flight work** for these seven files, as in Pb Step 1.
+- [ ] **Step 2: Record the parent commit's outputs** as in Pb Step 2, for `L2GNS` and `L2Curation`: the artifacts, the storage layouts and the fork output. `check:bytecode` prints `OK: 20`.
+- [ ] **Step 3: Move.** `git mv` the seven contracts. Expected: seven `R100` lines. Commit `refactor(subgraph-service): move L2GNS and L2Curation from contracts`.
+- [ ] **Step 4: Port the seven files** within the allowed changes:
+  - `SafeMathUpgradeable` goes.
+  - The returns at the old `L2GNS.sol:238` and `:245` go in `unchecked` blocks.
+  - `AddressUpgradeable.isContract(x)` becomes `x.code.length > 0` (old `GNS.sol:838`, `L2Curation.sol:469`).
+  - `ClonesUpgradeable` becomes OpenZeppelin 5's `Clones`.
+  - `CurationStorage` and `GNSStorage` inherit `InitializableV3` instead of `Initializable`.
+  - `GNS._buildSubgraphID` goes from `pure` to `view`.
+
+  Add `InitializableV3`.
+
+- [ ] **Step 5: Set the compile config.**
+  - `hardhat.config.ts` sets `solidity: { compilers: [baseConfig.solidity], overrides }`, using the Pb settings. Hardhat 2 keys are project-relative source names: `contracts/base/Multicall.sol`, `contracts/curation/CurationStorage.sol`, `contracts/discovery/GNS.sol`, `contracts/discovery/GNSStorage.sol`, `contracts/l2/curation/L2Curation.sol`, `contracts/l2/discovery/L2GNS.sol`, `contracts/l2/discovery/L2GNSStorage.sol` and `contracts/upgrades/InitializableV3.sol`.
+  - `foundry.toml` pins `contracts/{base,curation,discovery,l2,upgrades}/**` the same way as Pb. It adds `fs_permissions` entries for `node_modules/@graphprotocol/graph-core/artifacts` and `node_modules/@graphprotocol/graph-token/artifacts`.
+  - `@graphprotocol/contracts` stays a devDependency until Step 10. toolshed loads `tasks/` whenever `build/contracts` exists, and the Ignition modules still import from it.
+  - Run `pnpm --filter @graphprotocol/subgraph-service build:self`. Expected: exit 0; the build-info check from Pb Step 7 holds for L2GNS and L2Curation; both `deployedBytecode`s are under 24,576 bytes.
+- [ ] **Step 6: Compare storage layouts** for L2GNS and L2Curation, as in Pb Step 8. Expected: exit 0. In L2Curation's layout, `_initialized` is at slot 16.
+- [ ] **Step 7: Move the suite and switch it to both builds.**
+  - `git mv` the test tree.
+  - In `DiscoveryTest.t.sol`, deploy L2Curation and L2GNS with `_deployPorted("L2Curation.sol:L2Curation", "test/fixtures/pre-port/L2Curation.json")` and `_deployPorted("L2GNS.sol:L2GNS", "test/fixtures/pre-port/L2GNS.json")`. Remove `PKG_ARTIFACTS`.
+  - Copy the fixtures, and check their hashes against the parent's `reference.json` as in Pb Step 9.
+  - Set `test:self` to `forge test && PRE_PORT=true forge test --match-path 'test/unit/discovery/**'`.
+  - Delete `packages/subgraph-discovery/`.
+- [ ] **Step 8: Pin Review Focus 1 to 4.**
+  - `Build.t.sol` has `test_Build_FoundryMatchesHardhat` and `test_Build_DeploysRequestedBuild` for both contracts, as in Pb. The Hardhat artifacts are at `build/contracts/contracts/l2/...`.
+  - Add `test_GetUnaliasedL1SubgraphID_WrapsBelowZero`: for `x < OFFSET`, the result is `type(uint256).max - OFFSET + x + 1`.
+  - Add `test_L2Curation_InitializedFlagsInSlot16`: after setup, the low two bytes of `vm.load(address(curation), bytes32(uint256(16)))` are `0x0001`, so `_initialized` is true and `_initializing` false. Later variables may pack into the same slot.
+  - Add `test_L2Curation_RevertWhen_InitializedTwice` and `test_L2GNS_RevertWhen_InitializedTwice`. Each pranks as the implementation, so `onlyImpl` passes, calls `initialize` on the proxy, and expects `"Initializable: contract is already initialized"`.
+
+  Run `pnpm --filter @graphprotocol/subgraph-service test:self`. Expected: `TBD` passing in each run (`TBD` before the move), 0 failing. Revert-data differences are listed, as in Pb.
+
+- [ ] **Step 9: Coverage gate** for the seven moved files. Run `pnpm --filter @graphprotocol/subgraph-service test:coverage:self`. Expected: exit 0.
+- [ ] **Step 10: Pass the artifacts into horizon's modules.** `buildModule` builds a module as soon as it is called, and Ignition rejects two different modules with the same id. So every module that uses the periphery module, directly or through `after:`, becomes a factory that receives the instances it uses:
+  - `periphery/Curation.ts` exports `buildCurationModule(artifact)`, and `periphery/GNS.ts` exports `buildGNSModule(artifact, curation)`.
+  - `periphery.ts` exports `buildPeripheryModule(artifacts)`. It builds Curation once and passes that object to GNS.
+  - `core/HorizonProxies.ts` exports `buildHorizonProxiesModule(periphery)`.
+  - `core/{HorizonStaking,GraphPayments,PaymentsEscrow,GraphTallyCollector,RecurringCollector}.ts` each export `build<Name>Module(periphery, proxies)`, and `core/core.ts` exports `buildCoreModule(periphery, proxies)`.
+  - `deploy.ts` exports `buildHorizonModule(artifacts)`. It builds periphery once and proxies once, then the core modules from those two objects. Every `useModule` and `after:` refers to those same instances. `index.ts` exports `buildHorizonModule` in place of `HorizonModule`.
+  - Delete horizon's `tasks/deploy.ts`, and remove `@graphprotocol/contracts` from horizon and subgraph-service.
+  - Import paths in subgraph-service: `tasks/deploy.ts` imports both artifacts from `../build/contracts/contracts/l2/curation/L2Curation.sol/L2Curation.json` and `../build/contracts/contracts/l2/discovery/L2GNS.sol/L2GNS.json`, and calls `buildHorizonModule`. `ignition/modules/{GNS,Curation}.ts` import `../../build/contracts/contracts/l2/...`. The PR notes that a `build/` left over from before this change needs `pnpm clean` first.
+  - Update horizon's README and the root `CLAUDE.md`: `deploy:protocol` runs from subgraph-service only.
+  - Run the TypeScript check in horizon and subgraph-service, and the fresh-stack check. Expected: both pass.
+- [ ] **Step 11: Update deployment.**
+  - Registry entries: `{ type: 'subgraph-service', name: 'l2/curation/L2Curation' }` and `{ type: 'subgraph-service', name: 'l2/discovery/L2GNS' }`.
+  - In `verify-contract.ts`, `getFullyQualifiedContractName` uses the basename after `.sol:` for `subgraph-service`. Export it and test that it returns `contracts/l2/curation/L2Curation.sol:L2Curation`.
+  - `bytecode-comparison.test.ts` loads L2Curation with `loadSubgraphServiceArtifact`.
+  - `build:clean` becomes `pnpm --filter @graphprotocol/issuance --filter @graphprotocol/subgraph-service clean && pnpm build:deps`. Remove `@graphprotocol/contracts` from deployment.
+
+  Run `pnpm --filter @graphprotocol/deployment test:self`. Expected: PASS.
+
+- [ ] **Step 12: Finish.**
+  - Delete the `L2GNS` and `L2Curation` entries from `manifest.json` and `reference.json`. Write the changeset. Install.
+  - Expected: `git grep -n '"@graphprotocol/contracts"' -- 'packages/*/package.json'` lists only the `name` line in `packages/contracts/package.json`, and `packages/contracts/contracts/` holds only `.gitattributes`.
+- [ ] **Step 13: Commit.** `refactor(subgraph-service): port L2GNS and L2Curation to Solidity 0.8`
+- [ ] **Step 14: Run the verification block.**
+
+---
+
+### Task 2a: Delete `packages/contracts`
+
+**Files:**
+
+- Delete: `packages/contracts/`
+- Modify: deployment `lib/{artifact-loaders,contract-registry,deploy-implementation,deployment-validation}.ts`, `scripts/generate-abis.ts`, `tasks/verify-contract.ts`, `test/bytecode-comparison.test.ts`, `docs/{Design,Architecture}.md`
+- Modify: root `CLAUDE.md`, `README.md`, `.gitignore:32,43`, `count-patterns.txt:20`, `.github/workflows/publish.yml` (`contracts` option)
+- Modify: `docs/IGraphProxyAdminInterfaceFix.md`, `docs/ForgeLintSymlinkIssue.md`, `docs/Linting.md`, toolshed `src/deployments/{horizon,subgraph-service}/contracts.ts` comments
+- Modify: `pnpm-lock.yaml`
+
+- [ ] **Step 1: Record the fork output on the parent commit.**
+- [ ] **Step 2: List every remaining reference.**
+  - Run `git grep -nIE "@graphprotocol/contracts\b|packages/contracts\b" -- . ':!packages/contracts' ':!docs/contracts-removal' ':!**/CHANGELOG.md' ':!pnpm-lock.yaml' ':!packages/legacy/verified' ':!scripts/contracts-migration/test-mapping' | grep -v contracts-monorepo`.
+  - Expected: only the files listed above, plus `scripts/contracts-migration/summarize-coverage.test.mjs`, whose fixture paths are test data and stay. Report anything else before continuing.
+  - Confirm that `Dockerfile` and `.dockerignore` don't reference `packages/contracts`. The design asks for this check before deletion.
+- [ ] **Step 3: Delete the package and its loader support.**
+  - Remove `'contracts'` from `ContractsPackage` and `ArtifactSource`, and delete `loadContractsArtifact` and every `case 'contracts'`.
+  - Make `ImplementationDeployConfig.artifact` required and delete the `artifactPath` fallback in `deployImplementation`. No caller uses it.
+  - Rename the `loadContractsArtifact` describe block in `bytecode-comparison.test.ts` to test `loadPackageArtifact`.
+- [ ] **Step 4: Update the references.**
+  - Root `CLAUDE.md`: drop the `contracts` package entry and its test command.
+  - Docs that use `packages/contracts` as an example now use graph-core.
+  - Toolshed comments name the package that now owns each contract.
+- [ ] **Step 5: Install and check the lockfile.** Expected: it drops the `packages/contracts` importer and its exclusive dependencies, and changes no remaining importer's solc, OpenZeppelin, Hardhat or forge-std version.
+- [ ] **Step 6: Final search.** Run the design's final check: `git grep -nI '@graphprotocol/contracts' -- . ':!pnpm-lock.yaml' ':!**/CHANGELOG.md' ':!docs/contracts-removal' ':!scripts/contracts-migration/test-mapping' ':!packages/legacy/verified' | grep -v contracts-monorepo`. Expected: prints nothing.
+- [ ] **Step 7: Commit.** `chore: remove packages/contracts`
+- [ ] **Step 8: Run the verification block.**
+
+---
+
+### Task 2b: Deprecate the npm packages
+
+Manual, done by the user once 2a is on main after the audit:
+
+```bash
+npm deprecate @graphprotocol/contracts "No longer maintained. ABIs: @graphprotocol/interfaces. Addresses: @graphprotocol/address-book."
+npm deprecate @graphprotocol/sdk "No longer maintained. Use @graphprotocol/toolshed."
+```
diff --git a/docs/contracts-removal/phase-t-plan.md b/docs/contracts-removal/phase-t-plan.md
new file mode 100644
index 000000000..8fd3b7984
--- /dev/null
+++ b/docs/contracts-removal/phase-t-plan.md
@@ -0,0 +1,962 @@
+# Contracts Removal — Phase T (Foundry Test Ports) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Rewrite every live `contracts-test` unit test as a Foundry test in the package that will own the contract, and delete the TypeScript originals. The tests run against the `@graphprotocol/contracts` artifacts, so no contract moves yet.
+
+**Architecture:**
+
+- Each destination package gets a copy of `ProtocolFixture`, a small test base contract. It deploys 0.7.6 contracts from Hardhat JSON artifacts, sets up Controller and GraphProxyAdmin, and puts contracts behind a GraphProxy.
+- Tests are Solidity 0.8 and reach the contracts through 0.8-compilable interfaces.
+- Every dependency that isn't under test is a mock.
+- Artifact paths are always built from two constants, `CORE_ARTIFACTS` (Controller, GraphProxy, GraphProxyAdmin) and `PKG_ARTIFACTS` (the package's own contracts and mocks). In Phase T both point at `@graphprotocol/contracts`. Phase 1 repoints them, and in graph-core, graph-token and subgraph-discovery switches `_deployArtifact` to `deployCode`. The test bodies don't change, except subgraph-discovery's `DiscoveryTest.t.sol`, which loads L2GraphToken from graph-token's artifacts (design, Phase 1 step 3).
+
+**Tech Stack:** Foundry 1.8.3 (CI's version: `foundryup -i 1.8.3`), forge-std 1.14, solc 0.8.35, pnpm workspaces, Hardhat 2 artifacts from `packages/contracts`, Node 24 (T0 script).
+
+**Spec:** `docs/contracts-removal/design.md`:
+
+- §4 "Tests" (test rules, shared fixture, test assignment, mocks);
+- "PR sequence → Phase T";
+- "Verification → Test-port PRs".
+
+The executors read the spec and this plan together.
+
+## Global Constraints
+
+### Branching
+
+- Base branch: `chore/contracts-removal-phase-0` (draft PR #1373). Nothing merges to `main` until the audit.
+- Every task branches off the current tip of that branch, and its PR targets it: `gh pr create --draft --base chore/contracts-removal-phase-0`.
+- The spec and plans are on branch `docs/contracts-package-removal-spec` (PR #1372), not on the base branch. Read them from the main checkout at `~/dev/the-graph/contracts`.
+- One PR per task. Branch names are `test/contracts-removal-<id>`, where `<id>` is one of:
+  - `t0-coverage-functions`
+  - `t1-graph-core`
+  - `t2a-graph-token`, `t2b-gateways`
+  - `t3a-l2-curation`, `t3b-l2-gns`
+  - `t4-epochs`
+  - `t5a-rewards-config`, `t5b-rewards-distribution`, `t5c-rewards-issuers`, `t5d-rewards-eligibility`, `t5e-rewards-accounting`, `t5f-rewards-legacy-suite`
+- Order:
+  1. T0, then T1.
+  2. T2a, T3a, T4 and T5a in parallel.
+  3. T2b after T2a. T3b after T3a. T5b–T5e after T5a; they can run in parallel with each other.
+  4. T5f after T5b–T5e.
+- When a sibling PR lands first, rebase onto the new base. For a `pnpm-lock.yaml` conflict:
+
+  ```bash
+  git checkout origin/chore/contracts-removal-phase-0 -- pnpm-lock.yaml && pnpm install && git add pnpm-lock.yaml
+  ```
+
+### Commits and PRs
+
+- Conventional commits (`test:`, `chore:`). Do NOT add `Co-Authored-By` lines, and do not add any Claude or "Generated with" attribution to commits or PR bodies.
+- Run `pnpm install` after any `package.json` change and commit `pnpm-lock.yaml`.
+
+### Scope
+
+- No production contract changes. The only changes to `packages/contracts` in this phase are two test mocks under `contracts/tests/`: `ManagedMock` (T1) and `TokenUtilsMock` (T2a).
+- `pnpm check:bytecode` must still print `OK: 26 contracts match`.
+- New packages (`graph-core`, `graph-token`, `subgraph-discovery`) are `"private": true` and `"version": "0.0.0"`. Phase 1 makes them publishable.
+- They have no Hardhat config yet (nothing to compile). Their Foundry `src` is `test`. This deviates from the spec's Phase T skeleton list: the Hardhat config arrives in Phase 1 with the contracts.
+- New packages have no `test:coverage:self`. Foundry can't measure coverage of artifact-deployed bytecode. Coverage is measured in Phase 1.
+
+### Test-file rules (all tasks)
+
+- **Header.** `// SPDX-License-Identifier: MIT` and `pragma solidity ^0.8.27;`, the same as the horizon and issuance tests.
+- **No 0.7-only imports.** Never import 0.7-only source. Deploy contracts under test only through `_deployArtifact`.
+- **Imports in graph-token and subgraph-discovery:**
+  - Test files never import `@openzeppelin/*`, or any `@graphprotocol/interfaces` file that imports `@openzeppelin/*` (`IGraphToken`, `ISubgraphNFT`, `IGraphCurationToken`).
+  - They use the local interfaces under `test/unit/interfaces/`.
+  - Allowed `@graphprotocol/interfaces` files:
+    - `contracts/contracts/governance/{IController,IGoverned,IManaged}.sol`
+    - `contracts/contracts/upgrades/{IGraphProxy,IGraphProxyAdmin}.sol`
+    - `contracts/contracts/arbitrum/{ITokenGateway,IBridge,IInbox,IOutbox}.sol`
+    - `contracts/contracts/gateway/ICallhookReceiver.sol`
+  - These packages don't depend on OpenZeppelin, so a violation fails to compile.
+- **Naming:**
+  - Test functions are `test_<Area>_<Behavior>` and `test_<Area>_RevertWhen_<Condition>`, where `<Area>` is the innermost old `describe` name in PascalCase (as in T1's `Controller.t.sol`).
+  - The test contract is named after its file (`Controller.t.sol` → `ControllerTest`).
+  - Shared setup lives in `shared.t.sol` or `shared/`.
+- **Translating a TS test:**
+  - Each `it` becomes one test function with the same assertions.
+  - `revertedWith("X")` becomes `vm.expectRevert(bytes("X"))`. A bare `.reverted` becomes `vm.expectRevert()`.
+  - `vm.expectRevert` must come right before an external call. To expect a revert from an internal helper, call it through an external wrapper (`this.wrapper(...)`).
+  - `emit(...).withArgs(...)` becomes `vm.expectEmit(address(target))` plus a locally declared event with the same signature. `not.emit` becomes `vm.recordLogs` plus an assertion that the event's topic is absent.
+  - `beforeEach` becomes `setUp` or a modifier. Snapshot and restore are dropped, because Foundry isolates each test.
+- **Blocks and time:**
+  - Hardhat mines a block per transaction. Foundry runs a whole test in one block until `vm.roll`.
+  - Every `helpers.mine`, `mineUpTo` or `mineEpoch` becomes an explicit `vm.roll`.
+  - Hand-counted block totals in the old tests are replaced by values computed from the explicit rolls.
+  - Every `setUp` calls `vm.warp(1_700_000_000)`. Foundry's default timestamp is 1, which defeats deadline checks.
+- **Accounts.** Use `makeAddr` / `makeAddrAndKey`. Random values in the old tests become fixed values, or fuzz parameters where the old test was explicitly randomized.
+- **Tolerances.** Keep each old tolerance (`assertApproxEqAbs` / `assertApproxEqRel`). Where Foundry makes a value exact, assert it exactly.
+- **No new behaviour tests,** except the ones this plan names and the coverage additions.
+- **Formatting.** All Solidity in this plan is shown unformatted. Files are formatted by the repo's prettier (4 spaces, double quotes), and "copy verbatim" means copy the formatted file.
+
+### Mapping tables
+
+- Each port PR adds `scripts/contracts-migration/test-mapping/<task-id>.md` (for example `t2a.md`). Phase 2a deletes the folder with the other migration helpers.
+- The table has one row per deleted `it`, with columns `Old file | Old test (describe › it) | New test (file::function) | Note`.
+  - `Old file` is the repo-relative path. `New test` is `test/unit/.../<File>.t.sol::<function>`, relative to the package.
+  - A dropped test says `dropped: <reason>`. A duplicate points at the test that already covers it.
+  - T3b may map all of `gns.test.ts` in one `dropped` row, with the note `88 cases, L1GNS`.
+- The file ends with a `## Coverage` section (see the checklist below).
+- **Checks** (run them in every port PR):
+
+  ```bash
+  BASE=origin/chore/contracts-removal-phase-0
+  MAP=scripts/contracts-migration/test-mapping/<task-id>.md
+  # 1. cases in the deleted files (repo-relative paths)
+  for f in <deleted files>; do git show "$BASE:$f" | grep -cE '\bit(\.only|\.skip)?\('; done
+  # 2. rows in the table
+  grep -c '^| packages/contracts-test' "$MAP"
+  # 3. every referenced test function exists
+  grep -oE '[A-Za-z0-9_/.-]+\.t\.sol::[A-Za-z0-9_]+' "$MAP" | while IFS=: read -r file _ fn; do grep -q "function $fn(" "packages/<pkg>/$file" || echo "MISSING $file::$fn"; done
+  ```
+
+  Expected: check 1 sums to the PR's case count (in each task), check 2 matches it (T3b: 35 + 1), and check 3 prints nothing.
+
+### Coverage checklist
+
+- After T0, `coverage-baseline.json` lists, per contract, the functions the old suite executed (`functionsHit`).
+- **Rule.** Every listed external or public function of the contracts a PR owns is called directly by at least one new test. Internal functions and modifiers in the list count as covered when a test reaches them through a public path.
+- The list is a floor. It undercounts: some old tests deployed uninstrumented sdk artifacts. The mapping table is the real completeness guard.
+- Print the list, and the external/public names no test mentions yet:
+
+  ```bash
+  node -e 'const b=require("./scripts/contracts-migration/coverage-baseline.json");for(const k of process.argv.slice(1))console.log(k, b[k].functionsHit.join(" "))' <keys>
+  for fn in <external/public names from the list>; do grep -rqE "\.$fn\(" packages/<pkg>/test || echo "MISSING $fn"; done
+  ```
+
+- The `## Coverage` section of the mapping file lists every `MISSING` name with a reason (for example: only reached through a dropped legacy contract). An empty section means none.
+
+## Shared fixture (`test/unit/shared/ProtocolFixture.t.sol` in each package)
+
+Exact API. T1 writes it. T2a, T3a, T4 and T5a copy it verbatim.
+
+```solidity
+abstract contract ProtocolFixture is Test {
+  string internal constant CORE_ARTIFACTS = 'node_modules/@graphprotocol/contracts/artifacts/contracts/';
+  string internal constant PKG_ARTIFACTS = 'node_modules/@graphprotocol/contracts/artifacts/contracts/';
+
+  address internal governor; // makeAddr("governor"), set in _deployProtocolBase
+  IController internal controller; // @graphprotocol/interfaces/contracts/contracts/governance/IController.sol
+  IGraphProxyAdmin internal proxyAdmin; // @graphprotocol/interfaces/contracts/contracts/upgrades/IGraphProxyAdmin.sol
+
+  /// path is a full artifact path, e.g. string.concat(CORE_ARTIFACTS, "governance/Controller.sol/Controller.json").
+  /// Deploys `.bytecode ++ args` with CREATE (honours an active vm.prank).
+  /// Reverts "artifact needs linking" if `.linkReferences` has any key (vm.parseJsonKeys),
+  /// and "artifact deploy failed" if CREATE returns 0.
+  function _deployArtifact(string memory path, bytes memory args) internal returns (address);
+
+  /// As governor: deploys Controller and GraphProxyAdmin from CORE_ARTIFACTS, then controller.setPaused(false).
+  /// Must be called with no active prank.
+  function _deployProtocolBase() internal;
+
+  /// As governor: deploys GraphProxy(address(0), proxyAdmin) from CORE_ARTIFACTS,
+  /// proxyAdmin.upgrade(proxy, impl), proxyAdmin.acceptProxyAndCall(impl, proxy, initData).
+  /// Must be called with no active prank.
+  function _deployBehindProxy(address impl, bytes memory initData) internal returns (address proxy);
+
+  /// As governor: controller.setContractProxy(keccak256(bytes(name)), addr).
+  function _registerContract(string memory name, address addr) internal;
+}
+```
+
+Each `foundry.toml` gets an explicit read permission for the artifact folder. pnpm symlinks point outside the package, so `"./"` does not cover them:
+
+```toml
+fs_permissions = [{ access = "read", path = "node_modules/@graphprotocol/contracts/artifacts" }]
+```
+
+(Existing packages add it to their current `fs_permissions` list.)
+
+### Shared local token interface (`test/unit/interfaces/IGraphTokenLike.sol`, T2a and T3a)
+
+Both packages write the same file, from this list, so they don't depend on each other:
+
+- ERC20: `totalSupply`, `balanceOf`, `transfer`, `transferFrom`, `approve`, `allowance`, and the `Transfer` and `Approval` events.
+- Burning: `burn(uint256)`, `burnFrom(address,uint256)`.
+- Minting: `mint(address,uint256)`, `addMinter`, `removeMinter`, `renounceMinter`, `isMinter`, and the `MinterAdded(address indexed)` and `MinterRemoved(address indexed)` events.
+- Permit: `permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)`, `nonces(address)`.
+- Governance: `governor()`, `transferOwnership`, `acceptOwnership`.
+
+The domain separator is private in both tokens. Tests compute it locally (see T2a).
+
+## Review Focus
+
+1. **Missing or stale artifact.** A missing artifact must fail loudly. It must never skip, and never fall back to a mock (the `RealRewardsHarness` fallback is the anti-pattern). A missing `fs_permissions` entry also makes reads revert, which must not pass for a missing-file test.
+   - → T1 `test_Fixture_ArtifactReadable`: `assertTrue(vm.isFile(<Controller artifact>))`.
+   - → T1 `test_Fixture_RevertWhen_ArtifactMissing`: an external wrapper around `_deployArtifact` on a nonexistent path, expecting a revert.
+2. **Constructor or initializer wiring silently wrong.** GraphProxy args are appended in the wrong order, or the implementation is never accepted, so calls hit a proxy with no implementation.
+   - → T1 `test_Fixture_ProxyWiredToImplementation` asserts `getProxyAdmin(proxy) == proxyAdmin`, `getProxyImplementation(proxy) == impl` and `getProxyPendingImplementation(proxy) == address(0)`.
+3. **Controller left paused.** The Controller constructor pauses the protocol. Any `notPaused` path would then revert with "Paused" and mask the behaviour under test.
+   - → T1 `test_Fixture_ControllerUnpaused`.
+4. **Same-block semantics.** A port that forgets `vm.roll` asserts zero accrual where the old test expected per-block accrual, or the reverse. Fails silently if the expected value is copied from the TS test instead of derived from the rolls.
+   - → T4 `test_EpochManager_SameBlockDoesNotAdvance`.
+   - → T5b `test_Rewards_ZeroWhenNoBlocksElapsed`: two calls with no roll in between return an equal `accRewardsPerSignal`.
+5. **Default timestamp of 1.** A deadline of 1 is not expired in Foundry, so an "expired permit" test passes for the wrong reason.
+   - → T2a `test_Permit_RevertWhen_Expired` warps to `1_700_000_000` and uses `deadline = block.timestamp - 1`.
+
+---
+
+### Task 0 (PR T0): Record covered functions in the coverage baseline
+
+**Files:**
+
+- Modify: `scripts/contracts-migration/summarize-coverage.mjs`
+- Modify: `scripts/contracts-migration/summarize-coverage.test.mjs`
+- Modify: `scripts/contracts-migration/coverage-baseline.json` (regenerated)
+
+**Interfaces:**
+
+- Consumes: nothing.
+- Produces: `parseLcov(text)` returns `{ [key]: { linesFound, linesHit, pct, functionsHit: string[] } }`.
+  - `functionsHit` is sorted and de-duplicated.
+  - Empty names are left out (solidity-coverage gives fallback and receive an empty name).
+  - Every later task reads `functionsHit`.
+
+The current `parseLcov` reads `LF`/`LH` and overwrites repeated `SF:` records for the same key. The new one computes from `DA:` and `FNDA:` records and merges duplicates:
+
+- a line counts as found if any record has it;
+- it counts as hit if any record hit it;
+- functions are the union of `FNDA:<n>,<name>` with `n > 0`.
+
+`LF`/`LH` records are ignored.
+
+- [ ] **Step 1: Write failing tests** in `summarize-coverage.test.mjs`. Keep the existing tests.
+
+  ```js
+  test('computes lines from DA records', ...)            // DA:1,3 DA:2,0 DA:3,1 → linesFound 3, linesHit 2, pct 66.67
+  test('merges duplicate SF records', ...)               // same SF twice: {DA:1,0 DA:2,1} and {DA:1,2 DA:3,0} → found 3, hit 2
+  test('lists hit functions sorted and unique', ...)     // FNDA:2,b FNDA:0,c FNDA:1,a (+ dup record FNDA:1,b) → ['a','b']
+  test('drops empty function names', ...)                // FNDA:1, (empty name) → []
+  test('file without functions has empty functionsHit', ...)
+  ```
+
+- [ ] **Step 2: Run** `pnpm test:scripts`. Expected: the new tests fail.
+- [ ] **Step 3: Implement** the new `parseLcov` (same exported name and signature). `main` is unchanged.
+- [ ] **Step 4: Run** `pnpm test:scripts`. Expected: all pass.
+- [ ] **Step 5: Regenerate the baseline** from the unmodified suite on this branch. solidity-coverage writes `packages/coverage/lcov.info` (`istanbulFolder: '../coverage'`).
+
+  ```bash
+  pnpm build && pnpm --filter @graphprotocol/contracts-tests test:coverage:self
+  node scripts/contracts-migration/summarize-coverage.mjs packages/coverage/lcov.info scripts/contracts-migration/coverage-baseline.json
+  ```
+
+  Expected: `git diff` only adds `functionsHit` arrays. `linesFound` and `linesHit` stay the same for every key, except keys that had duplicate `SF:` records.
+  - If anything else changes, stop and report the keys.
+  - If duplicates changed a value, keep the merged value and list those keys in the PR body.
+
+- [ ] **Step 6: Commit and open the PR.**
+
+  ```bash
+  git commit -am "test: record covered functions in the contracts-test coverage baseline"
+  ```
+
+---
+
+### Task 1 (PR T1): graph-core package and governance/upgrade tests
+
+**Cases:** 36 (`governed` 2, `controller` 12, `pausing` 8, `admin` 14).
+
+**Files:**
+
+- Create:
+  - `packages/graph-core/package.json`
+  - `packages/graph-core/foundry.toml`
+- Create, under `packages/graph-core/test/unit/`:
+  - `shared/ProtocolFixture.t.sol`
+  - `shared/GraphCoreTest.t.sol` (base: `_deployProtocolBase` plus a `ManagedMock` behind a proxy)
+  - `shared/Fixture.t.sol` (Review Focus 1–3)
+  - `interfaces/IManagedMock.sol`
+  - `governance/Governed.t.sol`
+  - `governance/Controller.t.sol`
+  - `governance/Managed.t.sol`
+  - `governance/Pausing.t.sol`
+  - `upgrades/GraphProxyAdmin.t.sol`
+  - `upgrades/GraphProxy.t.sol`
+- Create: `packages/contracts/contracts/tests/ManagedMock.sol`
+- Create: `scripts/contracts-migration/test-mapping/t1.md`
+- Delete, under `packages/contracts-test/tests/unit/`:
+  - `governance/governed.test.ts`
+  - `governance/controller.test.ts`
+  - `governance/pausing.test.ts`
+  - `upgrade/admin.test.ts`
+- Modify: `pnpm-lock.yaml`
+
+**Interfaces:**
+
+- Consumes: T0 `functionsHit`.
+- Produces:
+  - the `ProtocolFixture` API above;
+  - `ManagedMock` at `PKG_ARTIFACTS + "tests/ManagedMock.sol/ManagedMock.json"`;
+  - the `package.json` and `foundry.toml` templates, which T2a and T3a copy, changing only the name, description and devDependencies.
+
+`package.json`:
+
+```json
+{
+  "name": "@graphprotocol/graph-core",
+  "version": "0.0.0",
+  "private": true,
+  "description": "The Graph governance and proxy contracts",
+  "license": "GPL-2.0-or-later",
+  "scripts": {
+    "build": "pnpm build:dep",
+    "build:dep": "pnpm --filter '@graphprotocol/graph-core^...' run build:self",
+    "clean": "rm -rf forge-artifacts/ cache_forge/",
+    "test": "pnpm build && pnpm test:self",
+    "test:self": "forge test"
+  },
+  "devDependencies": {
+    "@graphprotocol/contracts": "workspace:^",
+    "@graphprotocol/interfaces": "workspace:^",
+    "forge-std": "catalog:"
+  }
+}
+```
+
+`foundry.toml`:
+
+- Same as `packages/testing/foundry.toml`, except:
+  - `src = 'test'`
+  - `auto_detect_remappings = false`
+  - remappings `@graphprotocol/=node_modules/@graphprotocol/` and `forge-std/=node_modules/forge-std/src/` only
+  - the `fs_permissions` line above
+  - `ignored_warnings_from = ["node_modules"]`
+- Keep `solc_version = '0.8.35'`, `evm_version = 'cancun'` and the `[lint]` block. Reword the `[lint]` comment so it doesn't mention `forge lint contracts/` (there is no `contracts/` folder yet).
+- No `[profile.prod]`.
+
+`ManagedMock.sol` (0.7.6, in `contracts/tests/` next to `GovernedMock.sol`):
+
+- Header: the SPDX line, `pragma solidity ^0.7.6;` and `// solhint-disable use-natspec`.
+- No `TODO` line: `pnpm todo` (part of `lint:sol`) fails on it.
+
+```solidity
+contract ManagedMock is Managed, GraphUpgradeable {
+  function initialize(address _controller) external onlyImpl {
+    Managed._initialize(_controller);
+  }
+  function checkNotPartialPaused() external view notPartialPaused {}
+  function checkNotPaused() external view notPaused {}
+  function checkOnlyGovernor() external view onlyGovernor {}
+  /// curation, epochManager, rewardsManager, staking, graphToken, graphTokenGateway, gns — in that order
+  function resolveAll() external view returns (address[7] memory);
+}
+```
+
+It replaces the EpochManager, Staking and Curation contracts the old tests used as "some Managed / some GraphUpgradeable contract" (spec §4 notes). Phase 1 moves it to graph-core with `GovernedMock`.
+
+- [ ] **Step 1: Write the fixture and its tests.** Write `ProtocolFixture`, `IManagedMock`, `GraphCoreTest` and `shared/Fixture.t.sol` (the four Review Focus 1–3 tests).
+  - `GraphCoreTest.setUp`: `vm.warp(1_700_000_000)`, `_deployProtocolBase()`, then two `ManagedMock` implementations (`implA`, `implB`).
+  - `managed = IManagedMock(_deployBehindProxy(implA, abi.encodeCall(IManagedMock.initialize, (address(controller)))))`.
+- [ ] **Step 2: Run** `pnpm --filter @graphprotocol/graph-core test`. Expected: the build succeeds and the four fixture tests pass.
+- [ ] **Step 3: Port the four TS files.** Old → new:
+
+  | Old                                          | New                                                                                                                                                                                                                                     |
+  | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `governed.test.ts`                           | `governance/Governed.t.sol`. Deploys `PKG_ARTIFACTS + "tests/GovernedMock.sol/GovernedMock.json"` as governor.                                                                                                                          |
+  | `controller.test.ts` (`describe('Managed')`) | `governance/Controller.t.sol`. `setUp` registers the `ManagedMock` proxy under the `EpochManager` id. Without it, `updateController` calls address zero. `setController` is called directly on the proxy.                               |
+  | `pausing.test.ts`                            | `governance/Pausing.t.sol`. "fails when partialPause is set": `checkNotPartialPaused` reverts `Partial-paused`. "fails when pause is set": `checkNotPartialPaused` and `checkNotPaused` both revert `Paused`.                           |
+  | `admin.test.ts`                              | `upgrades/GraphProxyAdmin.t.sol`. "Staking proxy" becomes the `ManagedMock` proxy, and "Curation implementation" becomes `implB`. Reading `implementation()` / `admin()` / `pendingImplementation()` directly from a non-admin reverts. |
+
+- [ ] **Step 4: Cover the checklist.** Run the checklist commands for:
+  - `contracts/governance/Controller.sol`
+  - `contracts/governance/Governed.sol`
+  - `contracts/governance/Managed.sol`
+  - `contracts/governance/Pausable.sol`
+  - `contracts/upgrades/GraphProxy.sol`
+  - `contracts/upgrades/GraphProxyAdmin.sol`
+  - `contracts/upgrades/GraphProxyStorage.sol`
+  - `contracts/upgrades/GraphUpgradeable.sol`
+
+  Add a test for every `MISSING` name. Expected additions:
+  - `Managed.t.sol`:
+    - `syncAllContracts` emits `ContractSynced` per changed id, and nothing on a second call;
+    - `resolveAll` returns the controller's addresses before the sync and the cached addresses after it;
+    - `checkOnlyGovernor` reverts `Only Controller governor`.
+  - `GraphProxy.t.sol`:
+    - `acceptUpgradeAndCall` reverts `Impl call failed` on failing calldata;
+    - the admin calling the fallback reverts `Cannot fallback to proxy target`;
+    - `setAdmin(0)` reverts `Admin cant be the zero address`;
+    - `acceptUpgrade` with `vm.prank(address(proxyAdmin))` and no pending implementation reverts `Impl cannot be zero address`;
+    - from a non-pending implementation, it reverts `Only pending implementation`.
+  - `Governed.t.sol`: `transferOwnership(0)` reverts `Governor must be set`.
+
+- [ ] **Step 5: Run** `pnpm --filter @graphprotocol/graph-core test` and `pnpm --filter @graphprotocol/contracts-tests test:self`. Expected: all pass.
+- [ ] **Step 6: Lint and check bytecode.** Run:
+  - `pnpm check:bytecode` (expect `OK: 26 contracts match`);
+  - `(cd packages/contracts && npx solhint --max-warnings=0 contracts/tests/ManagedMock.sol)` (expect exit 0);
+  - `pnpm lint:sol && git status --short` (expect exit 0 and no files changed; commit any formatting fixes first).
+- [ ] **Step 7:** Write `t1.md` and run the mapping checks. Expected: 36 cases, 36 rows, no `MISSING`.
+- [ ] **Step 8: Commit and open the PR.**
+
+  ```bash
+  git commit -m "test(graph-core): port governance and proxy tests to Foundry"
+  ```
+
+---
+
+### Task 2a (PR T2a): graph-token package, tokens, BridgeEscrow and TokenUtils
+
+**Cases:** 30 (`lib/graphTokenTests.ts` 15, `l2/l2GraphToken.test.ts` 11, `gateway/bridgeEscrow.test.ts` 4, `graphToken.test.ts` 0).
+
+**Files:**
+
+- Create:
+  - `packages/graph-token/package.json`
+  - `packages/graph-token/foundry.toml`
+- Create, under `packages/graph-token/test/unit/`:
+  - `shared/ProtocolFixture.t.sol` (copy of T1's)
+  - `interfaces/IGraphTokenLike.sol` (shared list above)
+  - `interfaces/IL2GraphTokenLike.sol`
+  - `interfaces/IBridgeEscrowLike.sol`
+  - `interfaces/ITokenUtilsMock.sol`
+  - `token/GraphTokenShared.t.sol` (abstract)
+  - `token/GraphToken.t.sol`
+  - `token/L2GraphToken.t.sol`
+  - `gateway/BridgeEscrow.t.sol`
+  - `utils/TokenUtils.t.sol`
+- Create: `packages/contracts/contracts/tests/TokenUtilsMock.sol`
+- Create: `scripts/contracts-migration/test-mapping/t2a.md`
+- Delete, under `packages/contracts-test/tests/unit/`:
+  - `graphToken.test.ts`
+  - `lib/graphTokenTests.ts`
+  - `l2/l2GraphToken.test.ts`
+  - `gateway/bridgeEscrow.test.ts`
+
+**Interfaces:**
+
+- Consumes: `ProtocolFixture`.
+- Produces: the graph-token package with `ProtocolFixture` and `IGraphTokenLike`, which T2b uses.
+- devDependencies: `@graphprotocol/contracts`, `@graphprotocol/interfaces`, `forge-std`. No OpenZeppelin.
+- `IL2GraphTokenLike is IGraphTokenLike`, adding:
+  - `initialize(address)`, `gateway()`, `l1Address()`, `setGateway`, `setL1Address`, `bridgeMint`, `bridgeBurn`;
+  - the `GatewaySet`, `L1AddressSet`, `BridgeMinted` and `BridgeBurned` events, with the contract's signatures.
+- `IBridgeEscrowLike`: `initialize(address)`, `approveAll(address)`, `revokeAll(address)`.
+- `TokenUtilsMock.sol` (0.7.6, in `contracts/tests/`, same header rules as `ManagedMock`):
+
+  ```solidity
+  contract TokenUtilsMock {
+    function pullTokens(IGraphToken token, address from, uint256 amount) external {
+      TokenUtils.pullTokens(token, from, amount);
+    }
+    function pushTokens(IGraphToken token, address to, uint256 amount) external {
+      TokenUtils.pushTokens(token, to, amount);
+    }
+    function burnTokens(IGraphToken token, uint256 amount) external {
+      TokenUtils.burnTokens(token, amount);
+    }
+  }
+  ```
+
+  - In the live code, TokenUtils is only used by GNS and L2Curation, which aren't in graph-token. Without this mock, graph-token can't reach TokenUtils' baseline coverage in Phase 1.
+  - Phase 1 moves the mock to graph-token with TokenUtils.
+
+**Artifacts and setup** (`PKG_ARTIFACTS` +):
+
+| Contract       | Path                                           |
+| -------------- | ---------------------------------------------- |
+| GraphToken     | `token/GraphToken.sol/GraphToken.json`         |
+| L2GraphToken   | `l2/token/L2GraphToken.sol/L2GraphToken.json`  |
+| BridgeEscrow   | `gateway/BridgeEscrow.sol/BridgeEscrow.json`   |
+| TokenUtilsMock | `tests/TokenUtilsMock.sol/TokenUtilsMock.json` |
+
+- **GraphToken** is not proxied: deploy as governor with `abi.encode(10_000_000_000 ether)`.
+- **L2GraphToken** is behind a proxy: `initialize(governor)`.
+- **BridgeEscrow** is behind a proxy: `initialize(controller)`. Register `GraphToken` in the controller first, then call `syncAllContracts()`.
+- **`GraphTokenSharedTest`** carries every `lib/graphTokenTests.ts` case once:
+  - abstract hooks `_token() returns (IGraphTokenLike)` and `_salt() returns (bytes32)`;
+  - L1 salt `0x51f3d585afe6dfeb2af01bba0889a36c1db03beec88c6a4d0c53817069026afa`;
+  - L2 salt `0xe33842a7acd1d5a1d28f25a931703e5605152dc48d64dc4716efdae1f5659591`;
+  - `_domainSeparator()` computes `keccak256(abi.encode(keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract,bytes32 salt)"), keccak256("Graph Token"), keccak256("0"), block.chainid, address(_token()), _salt()))`;
+  - the permit digest is `keccak256(abi.encodePacked("\x19\x01", _domainSeparator(), keccak256(abi.encode(keccak256("Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)"), owner, spender, value, nonce, deadline))))`;
+  - permits are signed with `vm.sign` using the key from `makeAddrAndKey("me")`;
+  - `GraphToken.t.sol` and `L2GraphToken.t.sol` inherit it. The L2 file also holds the "Extended L2 behavior" cases, with the gateway and L1 address as plain `makeAddr` accounts.
+- **`TokenUtils.t.sol`**:
+  - `pullTokens` moves tokens from an approved holder to the mock;
+  - `pullTokens` and `pushTokens` with amount 0 do nothing;
+  - `pushTokens` moves tokens from the mock;
+  - `burnTokens` lowers `totalSupply`.
+
+Steps:
+
+- [ ] **Step 1: Scaffold.** Write the package, copy `ProtocolFixture`, and write the interfaces and `GraphTokenSharedTest`, including Review Focus 5.
+- [ ] **Step 2: Run** `pnpm --filter @graphprotocol/graph-token test`. Expected: the shared tests pass for both tokens.
+- [ ] **Step 3: Port** the L2 extensions and BridgeEscrow. Write `TokenUtilsMock` and `TokenUtils.t.sol`. Run the package tests after each file. Expected: pass.
+- [ ] **Step 4: Cover the checklist** for:
+  - `contracts/token/GraphToken.sol`
+  - `contracts/l2/token/L2GraphToken.sol`
+  - `contracts/l2/token/GraphTokenUpgradeable.sol`
+  - `contracts/gateway/BridgeEscrow.sol`
+  - `contracts/utils/TokenUtils.sol`
+- [ ] **Step 5: Run** the package tests, `pnpm --filter @graphprotocol/contracts-tests test:self`, `pnpm check:bytecode`, `(cd packages/contracts && npx solhint --max-warnings=0 contracts/tests/TokenUtilsMock.sol)`, and `pnpm lint:sol && git status --short`. Expected: all pass, and no files changed.
+- [ ] **Step 6:** Write `t2a.md` and run the mapping checks. Expected: 30 cases, 30 rows (the two identically titled permit cases are two rows), no `MISSING`.
+- [ ] **Step 7: Commit and open the PR.**
+
+  ```bash
+  git commit -m "test(graph-token): port token, escrow and token utils tests to Foundry"
+  ```
+
+---
+
+### Task 2b (PR T2b): graph-token gateway tests
+
+**Cases:** 74 (`gateway/l1GraphTokenGateway.test.ts` 46, `l2/l2GraphTokenGateway.test.ts` 28).
+
+**Files:**
+
+- Create, under `packages/graph-token/test/unit/`:
+  - `interfaces/IL1GraphTokenGatewayLike.sol`
+  - `interfaces/IL2GraphTokenGatewayLike.sol`
+  - `interfaces/IArbitrumMocksLike.sol`
+  - `gateway/L1GraphTokenGatewayShared.t.sol`
+  - `gateway/L1GraphTokenGatewayConfig.t.sol`
+  - `gateway/L1GraphTokenGatewayTransfers.t.sol`
+  - `gateway/L2GraphTokenGatewayShared.t.sol`
+  - `gateway/L2GraphTokenGatewayConfig.t.sol`
+  - `gateway/L2GraphTokenGatewayTransfers.t.sol`
+  - `mocks/NoCallhookReceiver.sol` (an empty 0.8 contract: no fallback, so any call reverts)
+- Create: `scripts/contracts-migration/test-mapping/t2b.md`
+- Delete, under `packages/contracts-test/tests/unit/`:
+  - `gateway/l1GraphTokenGateway.test.ts`
+  - `l2/l2GraphTokenGateway.test.ts`
+  - `l2/l2ArbitrumMessengerMock.ts` (imported by nothing)
+
+**Interfaces:**
+
+- Consumes: T2a's package, `ProtocolFixture` and `IGraphTokenLike`.
+- Produces: nothing for other tasks.
+- `IL1GraphTokenGatewayLike`:
+  - `initialize(address)`;
+  - `setArbitrumAddresses(address inbox, address router)`, `setL2TokenAddress`, `setL2CounterpartAddress`, `setEscrowAddress`;
+  - `addToCallhookAllowlist`, `removeFromCallhookAllowlist`, `callhookAllowlist(address)`;
+  - `updateL2MintAllowance(uint256 l2IssuancePerBlock, uint256 updateBlockNum)`, `setL2MintAllowanceParametersManual(uint256 accumulatedAllowance, uint256 l2IssuancePerBlock, uint256 lastUpdateBlock)`, `accumulatedL2MintAllowanceAtBlock(uint256)`;
+  - getters: `accumulatedL2MintAllowanceSnapshot`, `l2MintAllowancePerBlock`, `lastL2MintAllowanceUpdateBlock`, `totalMintedFromL2`, `l2GRT`, `inbox`, `l1Router`, `l2Counterpart`, `escrow`, `counterpartGateway`, `calculateL2TokenAddress`;
+  - pause: `setPaused`, `paused`, `setPauseGuardian`, `pauseGuardian`;
+  - transfers: `outboundTransfer` and `finalizeInboundTransfer` with `ITokenGateway`'s signatures;
+  - every event the contract declares.
+- `IL2GraphTokenGatewayLike`:
+  - `initialize(address)`;
+  - `setL2Router`, `setL1TokenAddress`, `setL1CounterpartAddress`, their getters, and `calculateL2TokenAddress`;
+  - the 4-argument `outboundTransfer(address l1Token, address to, uint256 amount, bytes data)` and the `ITokenGateway` overloads;
+  - the same pause functions as L1;
+  - every event the contract declares (`DepositFinalized`, `WithdrawalInitiated`, `TxToL1`, `L2RouterSet`, …).
+- `IArbitrumMocksLike`:
+  - BridgeMock: `setInbox(address,bool)`, `setOutbox(address,bool)`;
+  - InboxMock and OutboxMock: `setBridge(address)`;
+  - OutboxMock: `executeTransaction(...)`, with the mock's exact parameter list;
+  - CallhookReceiverMock: the `TransferReceived(address from, uint256 amount, uint256 foo, uint256 bar)` event.
+- Copy exact parameter lists and event signatures from the 0.7.6 sources in `packages/contracts/contracts/`.
+
+**Artifacts and setup** (`PKG_ARTIFACTS` +):
+
+| Contract                          | Path                                                          |
+| --------------------------------- | ------------------------------------------------------------- |
+| L1GraphTokenGateway               | `gateway/L1GraphTokenGateway.sol/L1GraphTokenGateway.json`    |
+| L2GraphTokenGateway               | `l2/gateway/L2GraphTokenGateway.sol/L2GraphTokenGateway.json` |
+| BridgeMock, InboxMock, OutboxMock | `tests/arbitrum/<Name>.sol/<Name>.json`                       |
+| CallhookReceiverMock              | `tests/CallhookReceiverMock.sol/CallhookReceiverMock.json`    |
+
+- **Gateways:** behind a proxy, `initialize(controller)`. Register `GraphToken` and `GraphTokenGateway`, then call `syncAllContracts()`. Gateways start paused.
+- **Counterpart contracts** (the other layer's token and gateway, routers): `makeAddr` plus `vm.etch(addr, hex"1234")`.
+- **L1 bridge mocks:**
+  - Wiring: `bridge.setInbox(inbox, true)`, `bridge.setOutbox(outbox, true)`, `inbox.setBridge(bridge)`, `outbox.setBridge(bridge)`.
+  - Inbound calls go through `outbox.executeTransaction(...)`.
+- **ArbSys:** don't use the ArbSysMock artifact. The spec deletes it in D3.
+  - `vm.etch(address(0x64), hex"00")` gives the address code, which 0.7.6's extcodesize check needs.
+  - `vm.mockCall(address(0x64), abi.encodeWithSignature("sendTxToL1(address,bytes)"), abi.encode(uint256(1)))`.
+  - Outbound tests add `vm.expectCall(address(0x64), abi.encodeWithSignature("sendTxToL1(address,bytes)", l1Gateway, data))`.
+- **L2 inbound:** `vm.prank(address(uint160(l1Counterpart) + uint160(0x1111000000000000000000000000000000001111)))`, as an unchecked add.
+- **"Any contract" for the callhook allowlist:** any deployed address. Replaces RewardsManager.
+- **"Contract without onTokenTransfer":** `NoCallhookReceiver`, asserted with a bare `vm.expectRevert()`.
+- **Mint allowance test:** derive block numbers from explicit `vm.roll`s. For example: update the allowance at block B, roll to B + 4, then expect an allowance of 8 GRT at 2 GRT per block.
+
+Steps:
+
+- [ ] **Step 1: Write the interfaces and the L1 shared base.** Port the L1 `> immediately after deploy` cases into `L1GraphTokenGatewayConfig.t.sol`. Run `pnpm --filter @graphprotocol/graph-token test`. Expected: pass.
+- [ ] **Step 2: Port** the L1 `> after configuring and unpausing` cases into `L1GraphTokenGatewayTransfers.t.sol`. Run the package tests. Expected: pass.
+- [ ] **Step 3: Port** the L2 gateway the same way, split into config and transfers. Run the package tests. Expected: pass.
+- [ ] **Step 4: Cover the checklist** for:
+  - `contracts/gateway/GraphTokenGateway.sol`
+  - `contracts/gateway/L1GraphTokenGateway.sol`
+  - `contracts/l2/gateway/L2GraphTokenGateway.sol`
+
+  The L2 gateway's baseline lacks `getOutboundCalldata`, because the old test skipped it under coverage. Cover it anyway; it's in the TS test.
+
+- [ ] **Step 5: Run** the package tests, `pnpm --filter @graphprotocol/contracts-tests test:self`, `pnpm check:bytecode` and `pnpm lint:sol && git status --short`. Expected: all pass, and no files changed.
+- [ ] **Step 6:** Write `t2b.md` and run the mapping checks. Expected: 74 cases, 74 rows, no `MISSING`.
+- [ ] **Step 7: Commit and open the PR.**
+
+  ```bash
+  git commit -m "test(graph-token): port gateway tests to Foundry"
+  ```
+
+---
+
+### Task 3a (PR T3a): subgraph-discovery package and L2Curation tests
+
+**Cases:** 43 (`l2/l2Curation.test.ts`).
+
+**Files:**
+
+- Create:
+  - `packages/subgraph-discovery/package.json` (devDependencies as in T2a)
+  - `packages/subgraph-discovery/foundry.toml`
+- Create, under `packages/subgraph-discovery/test/unit/`:
+  - `shared/ProtocolFixture.t.sol`
+  - `shared/DiscoveryTest.t.sol` (full setup below; used by T3b too)
+  - `mocks/L2GatewayMock.sol`
+  - `interfaces/IGraphTokenLike.sol` (shared list above)
+  - `interfaces/IL2GNSLike.sol`
+  - `interfaces/IL2CurationLike.sol`
+  - `interfaces/ISubgraphNFTLike.sol`
+  - `interfaces/IERC20Like.sol` (`balanceOf`, `totalSupply`; for curation-token balances)
+  - under `l2-curation/`:
+    - `Config.t.sol`
+    - `BondingCurve.t.sol`
+    - `Curate.t.sol`
+    - `CurateTaxFree.t.sol`
+    - `Collect.t.sol`
+    - `Burn.t.sol`
+    - `Conservation.t.sol`
+    - `MultipleMinting.t.sol`
+- Create: `scripts/contracts-migration/test-mapping/t3a.md`
+- Delete: `packages/contracts-test/tests/unit/l2/l2Curation.test.ts`
+
+**Interfaces:**
+
+- Consumes: `ProtocolFixture`.
+- Produces, used by T3b:
+  - `DiscoveryTest`;
+  - `L2GatewayMock`;
+  - `IL2GNSLike`, `IL2CurationLike`, `ISubgraphNFTLike`.
+- `DiscoveryTest` fields:
+  - contracts: `grt` (`IGraphTokenLike`), `curation` (`IL2CurationLike`), `gns` (`IL2GNSLike`), `nft` (`ISubgraphNFTLike`), `gatewayMock`, `curationTokenMaster`;
+  - accounts, all from `makeAddr`: `me`, `other`, `curator`, `attacker`, `l1GNS`, `subgraphService`.
+- `IL2GNSLike`:
+  - the entries of `IGNS` and `IL2GNS` the tests call, both overloads of `publishNewVersion`, and `onTokenTransfer`;
+  - `initialize(address,address)`, `approveAll()`, `setCounterpartGNSAddress(address)`, `counterpartGNSAddress()`;
+  - `ownerTaxPercentage()`, `setOwnerTaxPercentage(uint32)`, `nextAccountSeqID(address)`;
+  - `subgraphs(uint256) returns (uint256 vSignal, uint256 nSignal, bytes32 subgraphDeploymentID, uint32 reserveRatio, bool disabled, uint256 withdrawableGRT)`;
+  - `subgraphL2TransferData(uint256) returns (uint256 tokens, bool l2Done, uint256 subgraphReceivedOnL2BlockNumber)`;
+  - `getAliasedL2SubgraphID(uint256)`;
+  - every event the tests assert.
+- `IL2CurationLike`:
+  - the entries of `ICuration` the tests call;
+  - `initialize(address,address,uint32,uint256)`;
+  - `pools(bytes32) returns (uint256 tokens, uint32 reserveRatio, address gcs)`;
+  - `defaultReserveRatio()`, `setDefaultReserveRatio(uint32)`;
+  - `minimumCurationDeposit()`, `setMinimumCurationDeposit(uint256)`, `setCurationTaxPercentage(uint32)`;
+  - `curationTokenMaster()`, `setCurationTokenMaster(address)`;
+  - `subgraphService()`, `setSubgraphService(address)`, `collect(bytes32,uint256)`;
+  - `mintTaxFree`, `tokensToSignalNoTax`, `tokensToSignalToTokensNoTax`;
+  - the `Signalled`, `Burned` and `Collected` events.
+- `ISubgraphNFTLike`: `ownerOf`, `setMinter`, `setTokenDescriptor`, `tokenURI`.
+- `L2GatewayMock` (0.8):
+  - `constructor(address token)`;
+  - `function deliver(address gns, address l1From, uint256 amount, bytes calldata data) external`. It calls `IGraphTokenLike(token).mint(gns, amount)` and then `ICallhookReceiver(gns).onTokenTransfer(l1From, amount, data)`. Mint first, then forward, like `L2GraphTokenGateway.finalizeInboundTransfer`.
+
+**`DiscoveryTest.setUp`** (spec §4 "L2GNS" and "L2Curation" setup), all artifacts from `PKG_ARTIFACTS`:
+
+1. `vm.warp(1_700_000_000)`, then `_deployProtocolBase()`.
+2. L2GraphToken behind a proxy (`initialize(governor)`). As governor, `addMinter(gatewayMock)` and `addMinter(governor)`.
+3. GraphCurationToken master (`curation/GraphCurationToken.sol/GraphCurationToken.json`, deployed uninitialized).
+4. L2Curation behind a proxy: `initialize(controller, curationTokenMaster, 0, 1)`.
+5. SubgraphNFT (`discovery/SubgraphNFT.sol/SubgraphNFT.json`, `abi.encode(governor)`). Deploy SubgraphNFTDescriptor (`discovery/SubgraphNFTDescriptor.sol/SubgraphNFTDescriptor.json`) and set it with `setTokenDescriptor`.
+6. L2GNS behind a proxy: `initialize(controller, nft)`. `nft.setMinter(gns)`.
+7. Register `GraphToken`, `Curation`, `GNS` and `GraphTokenGateway` (= `gatewayMock`), then call `syncAllContracts()` on curation and GNS.
+8. `gns.approveAll()`, `gns.setCounterpartGNSAddress(l1GNS)`, `curation.setSubgraphService(subgraphService)`.
+
+- There is no staking, rewards manager or epoch manager. L2Curation skips the rewards hook when RewardsManager resolves to zero (`L2Curation.sol` `_updateRewards`).
+- Tests that need curation as the caller use `vm.prank(address(gns))` (it replaces the old impersonation of the GNS proxy). Tests that need curator funds mint as governor.
+
+Steps:
+
+- [ ] **Step 1: Scaffold.** Write the package, `DiscoveryTest`, `L2GatewayMock` and the interfaces. Add `test_Setup_Wired`: `nft` minter is `gns`, `curation.subgraphService() == subgraphService`, and `gns.counterpartGNSAddress() == l1GNS`.
+- [ ] **Step 2: Run** `pnpm --filter @graphprotocol/subgraph-discovery test`. Expected: pass.
+- [ ] **Step 3: Port** `l2Curation.test.ts`, one `describe` block per file, as listed above.
+  - `Config.t.sol`: the `L2Curation:Config` describe.
+  - `MultipleMinting.t.sol`: the `multiple minting` describe.
+  - The leftover `setContractProxy("Staking")` lines in the collect tests are dropped, because `collect` only checks `subgraphService`.
+  - `Conservation.t.sol` is pinned as `testFuzz_Conservation_DepositsAndRedeemsMatch(uint256[10] memory depositCuts, uint256[10] memory redeemCuts)`:
+    - Split exactly `1_000_000_000 ether` into 10 deposit chunks, cutting at `bound(cut, 0, remaining)`; the last chunk takes the remainder.
+    - Skip zero chunks (no call).
+    - Split the curator's resulting signal into 10 redeem chunks the same way.
+    - Assert that the pool and the curator end with exactly the initial token balances.
+- [ ] **Step 4: Cover the checklist** for:
+  - `contracts/l2/curation/L2Curation.sol`
+  - `contracts/curation/GraphCurationToken.sol`
+- [ ] **Step 5: Run** the package tests, `pnpm --filter @graphprotocol/contracts-tests test:self`, `pnpm check:bytecode` and `pnpm lint:sol && git status --short`. Expected: all pass, and no files changed.
+- [ ] **Step 6:** Write `t3a.md` and run the mapping checks. Expected: 43 cases, 43 rows, no `MISSING`.
+- [ ] **Step 7: Commit and open the PR.**
+
+  ```bash
+  git commit -m "test(subgraph-discovery): port L2Curation tests to Foundry"
+  ```
+
+---
+
+### Task 3b (PR T3b): L2GNS tests
+
+**Cases:** 35 live (`l2/l2GNS.test.ts`), plus 88 dropped (`gns.test.ts`, in one row).
+
+**Files:**
+
+- Create, under `packages/subgraph-discovery/test/unit/`:
+  - `shared/GNSHelpers.t.sol`
+  - under `l2-gns/`:
+    - `PublishNewVersion.t.sol`
+    - `ReceiveSubgraphFromL1.t.sol` (also holds the `onTokenTransfer with invalid codes` case)
+    - `FinishSubgraphTransfer.t.sol`
+    - `ReceiveCuratorBalance.t.sol`
+    - `AliasedSubgraphId.t.sol`
+- Create: `scripts/contracts-migration/test-mapping/t3b.md`
+- Delete, under `packages/contracts-test/tests/unit/`:
+  - `l2/l2GNS.test.ts`
+  - `lib/gnsUtils.ts`
+  - `gns.test.ts` (L1GNS, already `describe.skip`; spec §4)
+
+**Interfaces:**
+
+- Consumes: T3a's `DiscoveryTest`, `L2GatewayMock` and interfaces.
+- Produces: nothing for other tasks.
+- `abstract contract GNSHelpers is DiscoveryTest`. It ports the `lib/gnsUtils.ts` helpers that `l2GNS.test.ts` uses, assertions included:
+  - `_publishNewSubgraph(address account, bytes32 deploymentId) returns (uint256 subgraphId)`. The id is `uint256(keccak256(abi.encodePacked(account, gns.nextAccountSeqID(account), block.chainid)))`.
+  - `_publishNewVersion(address account, uint256 subgraphId, bytes32 newDeploymentId)`
+  - `_mintSignal(address account, uint256 subgraphId, uint256 tokensIn)`
+  - `_burnSignal(address account, uint256 subgraphId)`
+  - `_deprecateSubgraph(address account, uint256 subgraphId)`
+  - Helpers act as `account` with `vm.startPrank` / `vm.stopPrank`.
+- Callhook data: `abi.encode(uint8 code, uint256 l1SubgraphID, address beneficiary)`, with code `0` for a subgraph and `1` for a curator balance. L1 deliveries go through `gatewayMock.deliver(address(gns), l1GNS, amount, data)`.
+
+Steps:
+
+- [ ] **Step 1: Write `GNSHelpers`** and `test_Setup_PublishNewSubgraph`. Run `pnpm --filter @graphprotocol/subgraph-discovery test`. Expected: pass.
+- [ ] **Step 2: Port** `l2GNS.test.ts`, one `describe` block per file, as listed above.
+  - **Front-running test:** the slippage case keeps its curation inflation (mint to curation, then `collect` as `subgraphService`). It drops the staking lines, which never affected the assertions.
+  - **`DepositFinalized`:** the old assertions on `emit(l2GraphTokenGateway, 'DepositFinalized')` map to `covered by t2b L2GraphTokenGatewayTransfers`. The mock gateway doesn't emit it.
+  - **`getAliasedL2SubgraphID`:** keeps the exact L1 id `68799548758199140224151701590582019137924969401915573086349306511960790045480` and the wrap-around case.
+- [ ] **Step 3: Cover the checklist** for:
+  - `contracts/l2/discovery/L2GNS.sol`
+  - `contracts/discovery/GNS.sol`
+  - `contracts/discovery/SubgraphNFT.sol`
+  - `contracts/base/Multicall.sol`
+  - `contracts/utils/TokenUtils.sol`, reached through GNS and L2Curation
+
+  GNS functions that only L1GNS reached go in `## Coverage` with a reason. Add `test_GNS_Multicall` if `multicall` is listed.
+
+- [ ] **Step 4: Run** the package tests, `pnpm --filter @graphprotocol/contracts-tests test:self`, `pnpm check:bytecode` and `pnpm lint:sol && git status --short`. Expected: all pass, and no files changed.
+- [ ] **Step 5:** Write `t3b.md` and run the mapping checks. Expected: 123 cases, 36 rows (35 plus the `gns.test.ts` row), no `MISSING`.
+- [ ] **Step 6: Commit and open the PR.**
+
+  ```bash
+  git commit -m "test(subgraph-discovery): port L2GNS tests to Foundry"
+  ```
+
+---
+
+### Task 4 (PR T4): EpochManager tests in horizon
+
+**Cases:** 11 (`epochs.test.ts`).
+
+**Files:**
+
+- Modify: `packages/horizon/foundry.toml` (add the artifact read permission to `fs_permissions`)
+- Create, under `packages/horizon/test/unit/`:
+  - `shared/ProtocolFixture.t.sol`
+  - `epochs/IEpochManagerLike.sol`
+  - `epochs/EpochManager.t.sol`
+- Create: `scripts/contracts-migration/test-mapping/t4.md`
+- Delete: `packages/contracts-test/tests/unit/epochs.test.ts`
+
+**Interfaces:**
+
+- Consumes: `ProtocolFixture`.
+- horizon already depends on `@graphprotocol/contracts`.
+- EpochManager: `PKG_ARTIFACTS + "epochs/EpochManager.sol/EpochManager.json"`, behind a proxy, `initialize(controller, 60)`. 60 is the old fixture's `lengthInBlocks`.
+- `IEpochManagerLike is IEpochManager`, adding:
+  - `initialize(address,uint256)`;
+  - `epochLength()`, `lastRunEpoch()`, `lastLengthUpdateEpoch()`, `lastLengthUpdateBlock()`;
+  - `event EpochRun(uint256 indexed epoch, address caller)`;
+  - `event EpochLengthUpdate(uint256 indexed epoch, uint256 epochLength)`.
+
+Steps:
+
+- [ ] **Step 1: Write `EpochManager.t.sol`.** Include every `epochs.test.ts` case, plus Review Focus 4: `test_EpochManager_SameBlockDoesNotAdvance` (no roll means the same `currentEpoch` and `currentEpochBlock`).
+  - The lifecycle block uses `setEpochLength(3)`.
+  - Block positions use `vm.roll` relative to `currentEpochBlock()`.
+- [ ] **Step 2: Run** `cd packages/horizon && forge test --match-path 'test/unit/epochs/*'`. Expected: pass. Then run `pnpm --filter @graphprotocol/horizon test`. Expected: the full horizon suite still passes.
+- [ ] **Step 3: Cover the checklist** for `contracts/epochs/EpochManager.sol`. The baseline lacks `runEpoch` and `isCurrentEpochRun`, because the old test used uninstrumented sdk artifacts. The ported cases cover them anyway. Expected additions:
+  - `setEpochLength` with the same value reverts `Epoch length must be different to current`;
+  - `blockHash` reverts `Can only retrieve past block hashes` and `Can only retrieve hashes for last 256 blocks`;
+  - `epochsSince`, `epochsSinceUpdate` and `currentEpochBlockSinceStart` return the expected values after the rolls.
+- [ ] **Step 4: Run** `pnpm --filter @graphprotocol/contracts-tests test:self`, `pnpm check:bytecode` and `pnpm lint:sol && git status --short`. Then write `t4.md` and run the mapping checks. Expected: all pass, and 11 cases, 11 rows, no `MISSING`.
+- [ ] **Step 5: Commit and open the PR.**
+
+  ```bash
+  git commit -m "test(horizon): port EpochManager tests to Foundry"
+  ```
+
+---
+
+### Task 5a (PR T5a): RewardsManager fixture, mocks, interface and config tests in issuance
+
+**Cases:** 35 (`rewards-interface` 14, `rewards-config` 21).
+
+**Files:**
+
+- Modify:
+  - `packages/issuance/package.json`:
+    - add the devDependency `"@graphprotocol/contracts": "workspace:^"` (no cycle: contracts depends only on interfaces);
+    - change `"test"` to `"pnpm build && pnpm test:self"`. Spec §4: `test` builds first, so the RewardsManager artifact exists.
+  - `packages/issuance/foundry.toml` (add the artifact read permission)
+  - `packages/issuance/test/unit/mocks/MockGraphToken.sol` (add `function burn(uint256 amount) external`, burning from `msg.sender`)
+- Create, under `packages/issuance/test/unit/`:
+  - `shared/ProtocolFixture.t.sol`
+  - under `rewards-manager/`:
+    - `shared.t.sol` (`RewardsManagerSharedTest`)
+    - `IRewardsManagerLike.sol`
+    - `mocks/RMCurationMock.sol`
+    - `mocks/RMIssuerMock.sol`
+    - `mocks/RMIssuanceAllocatorMock.sol`
+    - `mocks/RMEligibilityOracleMock.sol`
+    - `interface.t.sol`
+    - `config.t.sol`
+- Create: `scripts/contracts-migration/test-mapping/t5a.md`
+- Delete, under `packages/contracts-test/tests/unit/rewards/`:
+  - `rewards-interface.test.ts`
+  - `rewards-config.test.ts`
+
+**Interfaces:**
+
+- Consumes: `ProtocolFixture`, and issuance's `contracts/test/allocate/MockERC165.sol` and `test/unit/mocks/MockGraphToken.sol`.
+- Mock names carry an `RM` prefix, because issuance already has `MockIssuanceAllocator`, `MockSubgraphService` and `RewardsEligibilityOracleMock`.
+- Produces, used by T5b–T5f:
+  - `RewardsManagerSharedTest`:
+    - fields: `rm` (`IRewardsManagerLike`), `token` (`MockGraphToken`), `curation` (`RMCurationMock`), `issuer` (`RMIssuerMock`), `allocator` (`RMIssuanceAllocatorMock`), `oracle` (`RMEligibilityOracleMock`), and `indexer` (`makeAddr`);
+    - constants: `ISSUANCE_PER_BLOCK = 200 ether`, `SIGNAL = 1500 ether`, `ALLOCATION = 12_500 ether`.
+  - Helpers on `RewardsManagerSharedTest`:
+    - `_signal(bytes32 sd, uint256 tokens)` calls `curation.signal`.
+    - `_allocate(address allocationId, bytes32 sd, uint256 tokens)` calls `issuer.allocate(allocationId, indexer, sd, tokens)`.
+    - `_close(address allocationId) returns (uint256)` calls `issuer.close`.
+    - `_expectedRewardsPerSignal(uint256 blocks, uint256 totalSignal) returns (uint256)` is `blocks * ISSUANCE_PER_BLOCK * 1e18 / totalSignal`.
+  - `IRewardsManagerLike is IRewardsManager, IRewardsManagerDeprecated, IManaged, IIssuanceTarget, IProviderEligibilityManagement, IERC165`. Leave out any base that `IRewardsManager` already inherits.
+    - All bases come from `@graphprotocol/interfaces`, except `IERC165`, which comes from OZ5 `utils/introspection/IERC165.sol`.
+    - It adds:
+      - `initialize(address)`;
+      - `accRewardsPerSignal()`, `accRewardsPerSignalLastBlockUpdated()`;
+      - `subgraphAvailabilityOracle()`, `subgraphs(bytes32)`, `denylist(bytes32)`, `minimumSubgraphSignal()`;
+      - `event ParameterUpdated(string param)`.
+    - Interface-id tests use `type(IRewardsManager).interfaceId` etc., never the `Like` type.
+  - `RMCurationMock(MockGraphToken token)`:
+    - `setRewardsManager(address)`;
+    - `signal(bytes32 sd, uint256 tokens)`: calls `rm.onSubgraphSignalUpdate(sd)`, then bumps pool tokens and mints `tokens` to itself;
+    - `unsignal(bytes32 sd, uint256 tokens)`: hook first, then lowers pool tokens and burns `tokens` from itself;
+    - `addFees(bytes32 sd, uint256 tokens)`: no hook; bumps pool tokens and mints;
+    - `getCurationPoolTokens(bytes32) view returns (uint256)`.
+  - `RMIssuerMock is IRewardsIssuer`:
+    - `setRewardsManager(address)`;
+    - `allocate(address allocationId, address indexer, bytes32 sd, uint256 tokens)`: `snapshot = rm.onSubgraphAllocationUpdate(sd)`, stores an active allocation `(indexer, sd, tokens, snapshot, pending 0)`, then bumps allocated tokens.
+    - `close(address allocationId) returns (uint256)`: `rm.takeRewards(allocationId)` while still active, then deactivates and lowers allocated tokens. Doc comment: legacy Staking called `onSubgraphAllocationUpdate` instead for a zero POI or an allocation under one epoch old. The ported tests never hit that case.
+    - `setAllocation(address allocationId, bool isActive, address indexer, bytes32 sd, uint256 tokens, uint256 accRewardsPerAllocatedToken, uint256 accRewardsPending)`;
+    - `setSubgraphAllocatedTokens(bytes32, uint256)`;
+    - `reclaim(bytes32 reason, address allocationId) returns (uint256)`: calls `rm.reclaimRewards`;
+    - `getAllocationData` and `getSubgraphAllocatedTokens`, per `IRewardsIssuer`.
+  - `RMIssuanceAllocatorMock` and `RMEligibilityOracleMock`: 0.8 ports of `packages/contracts/contracts/tests/` `MockIssuanceAllocator.sol` and `MockRewardsEligibilityOracle.sol`, with the same functions and ERC-165 answers.
+
+**`setUp`:**
+
+1. `vm.warp(1_700_000_000)`, `vm.roll(1_000_000)`, `_deployProtocolBase()`.
+2. RewardsManager from `PKG_ARTIFACTS + "rewards/RewardsManager.sol/RewardsManager.json"` behind a proxy: `initialize(controller)`.
+3. Register `GraphToken` (the MockGraphToken) and `Curation` (RMCurationMock), then call `rm.syncAllContracts()`.
+4. `curation.setRewardsManager(rm)`, `issuer.setRewardsManager(rm)`.
+5. As governor: `setSubgraphService(issuer)`, `setIssuancePerBlock(ISSUANCE_PER_BLOCK)`.
+
+No artifact from horizon, subgraph-discovery or graph-token is loaded (spec §2 acyclicity).
+
+Steps:
+
+- [ ] **Step 1: Scaffold.** Write the mocks, `IRewardsManagerLike` and `RewardsManagerSharedTest`, plus `test_Setup_RewardsManagerWired`: `subgraphService() == issuer` and `issuancePerBlock() == 200 ether`.
+- [ ] **Step 2: Run** `pnpm --filter @graphprotocol/issuance test`. Expected: the new test and the existing issuance suite pass.
+- [ ] **Step 3: Port** `rewards-interface.test.ts` into `interface.t.sol`. Keep the exact interface ids: IERC165 `0x01ffc9a7`, IIssuanceTarget `0x19f6601a`, IRewardsManager `0x8469b577`.
+- [ ] **Step 4: Port** `rewards-config.test.ts` into `config.t.sol`. The "initialize on implementation" case calls `initialize` on the proxy, as the old test did, and expects `Only implementation`.
+- [ ] **Step 5: Run** the package tests, `pnpm --filter @graphprotocol/contracts-tests test:self`, `pnpm check:bytecode` and `pnpm lint:sol && git status --short`. Then write `t5a.md` and run the mapping checks. Expected: all pass, and 35 cases, 35 rows.
+- [ ] **Step 6: Commit and open the PR.**
+
+  ```bash
+  git commit -m "test(issuance): add RewardsManager Foundry fixture and port interface and config tests"
+  ```
+
+---
+
+### Tasks 5b–5f (PRs T5b–T5f): remaining RewardsManager tests
+
+Each PR:
+
+- adds `.t.sol` files under `packages/issuance/test/unit/rewards-manager/`;
+- writes its own mapping file (`t5b.md` … `t5f.md`);
+- deletes its TS files.
+
+Use T5a's `RewardsManagerSharedTest`. Add a helper there only when two files need it. If two parallel PRs add the same helper, the second to rebase keeps one.
+
+| PR  | Cases | New files                                                                           | Deleted TS files (`packages/contracts-test/tests/unit/rewards/`)                 |
+| --- | ----- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| T5b | 25    | `calculations.t.sol`, `distribution.t.sol`                                          | `rewards-calculations.test.ts`, `rewards-distribution.test.ts`                   |
+| T5c | 32    | `issuanceAllocator.t.sol`, `subgraphService.t.sol`                                  | `rewards-issuance-allocator.test.ts`, `rewards-subgraph-service.test.ts`         |
+| T5d | 56    | `eligibility.t.sol`, `reclaim.t.sol` (split further by describe if over ~800 lines) | `rewards-eligibility-oracle.test.ts`, `rewards-reclaim.test.ts`                  |
+| T5e | 21    | `signalAllocationUpdate.t.sol`, `snapshotInversion.t.sol`                           | `rewards-signal-allocation-update.test.ts`, `rewards-snapshot-inversion.test.ts` |
+| T5f | 42    | `legacySuite.t.sol` (unique cases only)                                             | `rewards.test.ts`                                                                |
+
+Decisions each port must follow:
+
+- **Translations:**
+  - `staking.allocateFrom` becomes `_allocate`, and `closeAllocation` becomes `_close`.
+  - `curation.mint` becomes `_signal`.
+  - `helpers.mineEpoch` and `mine(n)` become `vm.roll`.
+  - The old suite set the legacy Staking contract as the subgraph service. `issuer` plays that role.
+  - `staking.collect` query fees become `curation.addFees` with the curation share only. The old test set `setCurationPercentage(100000)`, so collecting 10,000 GRT is `addFees(sd, 1_000 ether)`.
+- **Legacy-Staking cases** (`should distribute rewards on closed allocation and stake`, `…and send to destination`, `…w/delegators`, in T5b's distribution file and again in T5f):
+  - Port the RewardsManager half: the `HorizonRewardsAssigned` amount, the mint to the issuer and the total supply.
+  - Drop the stake, destination and delegation-pool assertions as `dropped: legacy Staking behaviour; Horizon equivalent in subgraph-service test/unit/subgraphService/collect/indexing/indexing.t.sol`.
+  - Name the matching test functions there, such as `test_SubgraphService_Collect_Indexing_WithDelegation`.
+- **`two allocations in the same block with a GRT burn in the middle`:** use `MockGraphToken.burn`.
+- **T5b** also adds Review Focus 4: `test_Rewards_ZeroWhenNoBlocksElapsed`.
+- **Snapshot inversion (T5e):** `vm.store` replaces `hardhat_setStorageAt`.
+  - The `subgraphs` mapping is at slot 16, with fields at `+0..+3` (`accRewardsForSubgraph`, `accRewardsForSubgraphSnapshot`, `accRewardsPerSignalSnapshot`, `accRewardsPerAllocatedToken`) from `keccak256(abi.encode(sd, uint256(16)))`.
+  - `test_SnapshotInversion_StorageSlotsMatchLayout` checks this before the other tests rely on it.
+- **Same-block cases (T5e):** batched Hardhat automine cases become consecutive calls with no `vm.roll` in between.
+- **`rewards.test.ts` (T5f).** Most of its cases duplicate files T5a–T5e already ported.
+  - For each case, find the same-titled test and diff the assertions, not just the titles.
+  - If the assertions match, the row points at the existing test. If they differ, port the difference into `legacySuite.t.sol`.
+  - Known unique cases:
+    - the 75/25 split variant of `accrued for each subgraph` (±1%);
+    - `should handle zero rewards with denylist and reclaim address`;
+    - `should handle zero rewards with eligibility oracle and reclaim address`;
+    - `should allow collecting pre-denial rewards after undeny`;
+    - `allocation created while denied should only earn post-undeny rewards`;
+    - `should reclaim denied-period rewards via onSubgraphAllocationUpdate`.
+- **Coverage checklist.**
+  - Each of T5b–T5e runs it for `contracts/rewards/RewardsManager.sol` and records its `MISSING` names.
+  - T5f closes it: every listed RewardsManager function is reached, or listed with a reason.
+  - For `contracts/staking/libs/MathUtils.sol`, only `diffOrZero` is reachable from RewardsManager. `min` and `weightedAverageRoundingUp` are listed as `reached only through legacy Staking`.
+
+Steps (each of T5b–T5f):
+
+- [ ] **Step 1: Port** the first file listed for the PR. Run `cd packages/issuance && forge test --match-path 'test/unit/rewards-manager/<file>'`. Expected: pass.
+- [ ] **Step 2: Port** the second file, if the PR has one. Run the same command for it. Expected: pass.
+- [ ] **Step 3: Run** `pnpm --filter @graphprotocol/issuance test`, `pnpm --filter @graphprotocol/contracts-tests test:self`, `pnpm check:bytecode` and `pnpm lint:sol && git status --short`. Expected: all pass, and no files changed.
+- [ ] **Step 4:** Write the mapping file and run the mapping checks. Expected: rows equal the PR's case count in the table, and no `MISSING`.
+- [ ] **Step 5: Commit and open the PR.**
+
+  ```bash
+  git commit -m "test(issuance): port RewardsManager <area> tests to Foundry"
+  ```
+
+---
+
+## After Phase T
+
+- `contracts-test` contains only tests for deleted or legacy contracts, plus `subgraphAvailability.test.ts`. D1 deletes them.
+- The temporary `@graphprotocol/contracts` devDependencies are removed one by one by the Phase 1 moves.
+- The spec (`design.md`) was amended to match this plan: ManagedMock and TokenUtilsMock in the mocks table, ArbSysMock still deleted, no Hardhat config before Phase 1, and no allocation-flow cases moved to `packages/testing`.