explore/client/MIGRATION_TASKS.md

# Architecture Migration — Task Backlog

Progress tracker for the `client/` architecture redesign.
Blueprint: `client/ARCH_REDESIGN.md`. Terminology: `docs/GLOSSARY.md`.

**Task ID format:** `<stage>-<index>` — stage number + sequential index within that stage.
Adding tasks to a stage: append the next index; no renumbering needed.

**Status:** `[ ]` to do · `[~]` in progress · `[x]` done  
**Base branch:** `main` — each task branches from `main`; PRs target `main`.  
**Parent issue:** [`blockscout/frontend#3341`](https://github.com/blockscout/frontend/issues/3341)

> `/arch-research <task-id>` creates the sub-issue and marks the task `[~]`.  
> `/arch-migrate <issue>` executes the task and opens a PR.  
> Change `[~]` → `[x]` after the PR is merged.

---

## Stage 0 — Pre-migration

### 0-1 · [~] Rename `configs/app/features/` files to kebab-case · [#3345](https://github.com/blockscout/frontend/issues/3345)

**Scope:** Rename every `.ts` file under `configs/app/features/` from camelCase to kebab-case
(e.g. `userOps.ts` → `user-ops.ts`, `adsBanner.ts` → `ads-banner.ts`).
Update all import paths repo-wide. Named exports inside files are unchanged — filenames only.  
**PR:** —

---

### 0-2 · [~] Enable ESLint `import/no-cycle` + `boundaries` rules · [#3348](https://github.com/blockscout/frontend/issues/3348)

**Scope:** Add `eslint-plugin-boundaries` (if not already installed). Configure rules so that:
- Imports within `client/` emit **errors** on violations.
- Imports in legacy `lib/` and `ui/` emit **warnings** only.
Fix all pre-existing errors (there should be none in `client/` yet). Confirm warnings in legacy code are expected and do not block CI.  
**PR:** —

---

## Stage 1 — Foundation

### 1-1 · [ ] Migrate `client/api/`

**Scope:** Move `lib/api/**` → `client/api/**` (preserve `services/` structure).
Additional moves in the same PR:
- `lib/socket/` → `client/api/socket/`
- `lib/hooks/useFetch.ts` → `client/api/`
- `lib/api/services/utils.ts` → `client/api/types.ts`

Update all repo-wide imports. Verify `client/api` has no runtime imports from `client/slices/*` or
`client/features/*` (`import type` is permitted).  
**PR:** —

---

### 1-2 · [ ] Migrate `client/shared/`

**Scope:** Move all cross-cutting utilities from `lib/` to `client/shared/<subfolder>/`.
Key moves (see `ARCH_REDESIGN.md §6` for full list):

| Source | Destination |
|--------|-------------|
| `lib/mixpanel/` | `client/shared/analytics/` |
| `lib/rollbar/` | `client/shared/monitoring/rollbar/` |
| `lib/growthbook/` | `client/shared/feature-flags/` |
| `lib/networks/` + `lib/units.ts` | `client/shared/chain/` (rename `network` → `chain` throughout) |
| `lib/router/` + filter-value helpers | `client/shared/router/` |
| `lib/errors/` + `lib/getErrorMessage.ts` | `client/shared/errors/` |
| `lib/web3/` | `client/shared/web3/` |
| `lib/metadata/` | `client/shared/metadata/` |
| `lib/hooks/useTimeAgoIncrement` | `client/shared/date-and-time/` |
| `lib/hooks/useLazyRenderedList`, `useInitialList`, `lib/getItemIndex.ts` | `client/shared/lists/` |
| `lib/cookies.ts` | `client/shared/storage/` |
| `lib/decodeJWT.ts` | `client/shared/auth/` |
| `lib/setLocale.ts` | `client/shared/i18n/` |
| `lib/capitalizeFirstLetter.ts`, `shortenString.ts`, `escapeRegExp.ts`, `highlightText.ts` | `client/shared/text/` |
| `lib/base64ToHex.ts` and other hex/bytes helpers | `client/shared/transformers/` |
| `lib/utils/stripUtmParams.ts` | `client/shared/links/utils/` |
| `lib/delay.ts`, `lib/isMetaKey.tsx` | `client/shared/utils/` |
| Remaining generic hooks from `lib/hooks/` | `client/shared/hooks/` |

Note: `lib/monitoring/` (server-side) → `nextjs/`, not `client/shared/`.  
**PR:** —

---

## Stage 2 — Pilot slice

### 2-1 · [ ] Pilot: migrate `slices/tx` end-to-end

**Scope:** Full migration of the `tx` slice. Canonical template for all subsequent slices.
- `lib/tx/` → `client/slices/tx/utils/`
- `lib/api/services/general/tx.ts` → `client/api/services/general/tx.ts` (if not already done in 1-1)
- `ui/tx/**` → `client/slices/tx/` (restructure into `pages/`, `components/`, `hooks/`, `utils/`, `types/`, `mocks.ts`, `stubs.ts`)
- Move associated `types/api/tx.ts` → `client/slices/tx/types/api.ts`
- Move associated `mocks/` and `stubs/` entries

Cross-slice dependencies (address types, rollup sub-types, etc.) may remain at their old `lib/` paths
after this PR — note each as an explicit follow-up in the PR description.  
**PR:** —

---

## Stage 3 — Core slices

Each slice follows the template established in 2-1.

### 3-1 · [ ] Slice: `block`
**Scope:** `lib/block/` (if any), `ui/block/**`, related `types/api/`, `mocks/`, `stubs/` → `client/slices/block/`  
**PR:** —

### 3-2 · [ ] Slice: `address`
**Scope:** `lib/address/`, `ui/address/**`, related types/mocks/stubs, `lib/hooks/useAddressProfileApiQuery`, `lib/contexts/addressHighlight.tsx` → `client/slices/address/`  
**PR:** —

### 3-3 · [ ] Slice: `search`
**Scope:** `lib/search/`, `ui/snippets/searchBar/`, `lib/recentSearchKeywords.ts`, related types/mocks/stubs → `client/slices/search/`  
**PR:** —

### 3-4 · [ ] Slice: `token`
**Scope:** `lib/token/`, `ui/token/**`, related types/mocks/stubs → `client/slices/token/`  
**PR:** —

### 3-5 · [ ] Slice: `contract`
**Scope:** `lib/contracts/`, `lib/solidityScan/`, `ui/contract/**`, related types/mocks/stubs → `client/slices/contract/`  
**PR:** —

### 3-6 · [ ] Slice: `internal-tx`
**Scope:** `ui/internalTxs/**` (and any `lib/` counterparts), related types/mocks/stubs → `client/slices/internal-tx/`  
**PR:** —

### 3-7 · [ ] Slice: `home`
**Scope:** `ui/home/**`, related types/mocks/stubs → `client/slices/home/`  
**PR:** —

### 3-8 · [ ] Slice: `tokens` (token list)
**Scope:** `ui/tokens/**`, related types/mocks/stubs → `client/slices/tokens/`  
**PR:** —

### 3-9 · [ ] Slice: `accounts`
**Scope:** `ui/accounts/**`, related types/mocks/stubs → `client/slices/accounts/`  
**PR:** —

### 3-10 · [ ] Slice: `token-instance`
**Scope:** `ui/tokenInstance/**`, related types/mocks/stubs → `client/slices/token-instance/`  
**PR:** —

---

## Stage 4 — Features: rollups

One PR per rollup type. Each goes under `client/features/rollup/<type>/`.

> Enumerate additional rollup tasks when this stage begins, based on what exists under `lib/rollups/` and `ui/`.

### 4-1 · [ ] Feature: `rollup/optimism`
**Scope:** All Optimism-specific UI, hooks, utils, types → `client/features/rollup/optimism/`. Includes fault proof system and dispute games.  
**PR:** —

### 4-2 · [ ] Feature: `rollup/arbitrum`
**Scope:** All Arbitrum-specific UI, hooks, utils, types → `client/features/rollup/arbitrum/`  
**PR:** —

### 4-3 · [ ] Feature: `rollup/zk-sync`
**Scope:** zkSync-specific UI, hooks, utils, types → `client/features/rollup/zk-sync/`. Check for other zk-based rollup types (scroll, polygon-zk-evm, etc.) and add tasks if needed.  
**PR:** —

---

## Stage 5 — Features: chain variants

One PR per chain variant. Each goes under `client/features/chain-variants/<name>/`.

### 5-1 · [ ] Feature: `chain-variants/celo`
**Scope:** All Celo-specific UI and logic including epochs → `client/features/chain-variants/celo/`. See `configs/app/features/celo.ts`.  
**PR:** —

### 5-2 · [ ] Feature: `chain-variants/tac`
**Scope:** TAC operations and bridge UI → `client/features/chain-variants/tac/`. See `configs/app/features/tac.ts`.  
**PR:** —

### 5-3 · [ ] Feature: `chain-variants/zeta-chain`
**Scope:** ZetaChain CCTX UI → `client/features/chain-variants/zeta-chain/`. See `configs/app/features/zetachain.ts`.  
**PR:** —

### 5-4 · [ ] Feature: `chain-variants/suave`
**Scope:** SUAVE Kettle UI → `client/features/chain-variants/suave/`. See `configs/app/features/suave.ts`.  
**PR:** —

### 5-5 · [ ] Feature: `chain-variants/mega-eth`
**Scope:** MegaETH Flashblocks UI → `client/features/chain-variants/mega-eth/`. See `configs/app/features/megaEth.ts` and `flashblocks.ts`.  
**PR:** —

### 5-6 · [ ] Feature: `chain-variants/beacon-chain`
**Scope:** Beacon chain deposits/withdrawals UI → `client/features/chain-variants/beacon-chain/`. See `configs/app/features/beaconChain.ts`.  
**PR:** —

---

## Stage 6 — Features: standalone

One PR per feature. Features that are pure infrastructure (analytics, monitoring, A/B flags) were
migrated to `client/shared/` in 1-2 and do not appear here.

### 6-1 · [ ] Feature: `user-ops`
**PR:** —

### 6-2 · [ ] Feature: `data-availability`
**PR:** —

### 6-3 · [ ] Feature: `multichain`
**Scope:** Includes `lib/multichain/`, `lib/contexts/multichain.tsx`, `ui/snippets/networkMenu/` → `client/features/multichain/`  
**PR:** —

### 6-4 · [ ] Feature: `name-domains` (BENS)
**Scope:** `configs/app/features/nameServices.ts` — use `name-domains` as folder name.  
**PR:** —

### 6-5 · [ ] Feature: `account`
**Scope:** Includes `lib/hooks/useGetCsrfToken`, `ui/snippets/auth/`, `ui/snippets/user/` → `client/features/account/`  
**PR:** —

### 6-6 · [ ] Feature: `stats`
**Scope:** `lib/stats/` and stats UI → `client/features/stats/`  
**PR:** —

### 6-7 · [ ] Feature: `gas-tracker`
**PR:** —

### 6-8 · [ ] Feature: `validators`
**PR:** —

### 6-9 · [ ] Feature: `marketplace`
**Scope:** Includes `lib/contexts/marketplace.tsx`, `lib/hooks/useGraphLinks` → `client/features/marketplace/`  
**PR:** —

### 6-10 · [ ] Feature: `rewards`
**Scope:** Includes `lib/contexts/rewards.tsx`, `lib/hooks/useRewardsActivity` → `client/features/rewards/`  
**PR:** —

### 6-11 · [ ] Feature: `advanced-filter`
**PR:** —

### 6-12 · [ ] Feature: `ad-banner`
**Scope:** Includes `lib/hooks/useAdblockDetect` → `client/features/ad-banner/`. Covers both `adsBanner.ts` and `adsText.ts` configs.  
**PR:** —

### 6-13 · [ ] Feature: `safe-address-tags`
**Scope:** Includes `lib/hooks/useIsSafeAddress` → `client/features/safe-address-tags/`. See `configs/app/features/safe.ts`.  
**PR:** —

### 6-14 · [ ] Feature: `metasuites`
**Scope:** Includes `lib/hooks/useNotifyOnNavigation` → `client/features/metasuites/`  
**PR:** —

### 6-15 · [ ] Feature: `csv-export`
**PR:** —

### 6-16 · [ ] Feature: `pools`
**PR:** —

### 6-17 · [ ] Feature: `hot-contracts`
**PR:** —

### 6-18 · [ ] Feature: `interchain-indexer`
**Scope:** Cross-chain message indexer (not ZetaChain). See `configs/app/features/crossChainTxs.ts`.  
**PR:** —

### 6-19 · [ ] Feature: `mud-framework`
**PR:** —

### 6-20 · [ ] Feature: `visualize`
**Scope:** Solidity-to-UML diagrams. See `configs/app/features/sol2uml.ts`.  
**PR:** —

### 6-21 · [ ] Feature: `tx-interpretation`
**PR:** —

### 6-22 · [ ] Feature: `public-tags`
**Scope:** Community address labels. See `configs/app/features/publicTagsSubmission.ts`.  
**PR:** —

### 6-23 · [ ] Feature: `address-widgets`
**Scope:** Third-party widgets on address pages. See `configs/app/features/address3rdPartyWidgets.ts`.  
**PR:** —

### 6-24 · [ ] Feature: `address-metadata`
**PR:** —

### 6-25 · [ ] Feature: `address-verification`
**Scope:** Covers `addressProfileAPI.ts` and `addressVerification.ts` configs.  
**PR:** —

### 6-26 · [ ] Feature: `bridged-tokens`
**PR:** —

### 6-27 · [ ] Feature: `web3-wallet`
**Scope:** Includes `blockchainInteraction.ts` config.  
**PR:** —

> Other small features (`externalTxs`, `xStarScore`, `deFiDropdown`, `getGasButton`, `easterEgg*`, `apiDocs`, `verifiedTokens`, `multichainButton`) — enumerate as separate tasks or group with related features when this stage begins.

---

## Stage 7 — Shell

### 7-1 · [ ] Migrate `client/shell`

**Scope:** Migrate after all slices and features it depends on are in place.
- `ui/snippets/header/`, `footer/`, `navigation/`, `topBar/` → `client/shell/`
- `lib/contexts/app.tsx`, `fallback.tsx` → `client/shell/`
- `lib/contexts/settings.tsx` → `client/shell/top-bar/`
- `lib/hooks/useNavItems` → `client/shell/`  
**PR:** —

---

## Stage 8 — Cleanup

### 8-1 · [ ] Remove legacy root directories

**Scope:** Confirm `lib/`, `ui/`, `mocks/`, `stubs/`, `types/` are empty (no remaining unconverted files).
Delete them. Fix any remaining lint warnings that referenced legacy paths.  
**PR:** —