Sync upstream v2.9.0 (merge conflicts)

.agents/AGENTS.md

@@ -1,5 +1,18 @@
 # Frontend application for Blockscout
 
+## Per-directory context
+
+Some directories have a `CONTEXT.md` documenting non-obvious patterns specific to that area. Read the relevant one before working in (or reaching into) that directory:
+
+- `deploy/scripts/` — how the frontend container is built and starts up (Dockerfile stages, entrypoint).
+- `deploy/tools/envs-validator/` — startup validation of `NEXT_PUBLIC_*` envs against yup schemas.
+- `src/slices/` — slice ownership model (who owns an entity's rendering).
+- `src/sprite/` — SVG sprite build pipeline and which outputs are tracked vs. generated.
+- `src/toolkit/` — the `@blockscout/ui-toolkit` workspace package structure.
+- `tools/dev-server/` — how the dev server and demo deploy get their env vars from a running instance config.
+
+If you encounter a `CONTEXT.md` not listed here, read it too (and consider adding it to this list).
+
 ## Architecture
 
 See `./rules/architecture.mdc`.

.agents/GLOSSARY.md

@@ -0,0 +1,64 @@
+# Ubiquitous Language Glossary
+
+Domain terms used in the Blockscout frontend codebase.
+
+The glossary carries only what isn't already in code or other docs:
+disambiguation between easily-confused terms, etymology, and scope. Folder
+paths and env var names are intentionally **not** listed — paths follow
+predictably from feature names (`src/features/<kebab-case-name>/`), and env
+vars are documented in `docs/ENVS.md`. Architectural concepts like
+**slice** and **feature** are defined in `.agents/rules/architecture.mdc`.
+
+**Kinds** in the table below:
+
+- *entity* — blockchain object that appears as a first-class UI element (detail page, list row, API resource)
+- *feature* — a config-gated product area
+- *service* — an external service (Blockscout-operated or third-party) backing a feature
+- *chain* — a specific chain or chain concept
+- *concept* — architectural / structural term
+
+---
+
+| Term | Kind | Definition |
+|------|------|------------|
+| **Account** | feature | Authenticated-user area covering watchlist, private tags, custom ABI, API keys, verified addresses, and profile. See also: **Watchlist**, **Public Tags**. |
+| **Address Metadata** | feature | Provides address labels, metadata enrichment, and label-based address search. Backs the metadata panel on address pages and the Label Search page. **Public Tags** is one sub-feature. Distinct from **Address Profile API**. |
+| **Address Profile API** | feature | Integration with a third-party API that decorates address pages with external profile tags and links. Distinct from **Address Metadata**, which surfaces Blockscout-managed labels. |
+| **Advanced Filter** | feature | UI for filtering transactions using multi-criteria queries; distinct from the basic filter controls on most list pages. |
+| **Alternative Explorers** | feature | "Verify with other explorers" menu linking to third-party explorers (e.g. Etherscan). |
+| **Beacon Chain** | chain | The Ethereum Proof-of-Stake consensus layer. When enabled, exposes beacon-chain deposits and withdrawals alongside regular transactions. Not a rollup — it is the Ethereum L1 consensus mechanism. |
+| **BENS (Blockscout Name Service)** | service | Blockscout's own chain-agnostic address naming service. Distinct from ENS (Ethereum-specific). Co-located with **Clusters** in the name-services UI. |
+| **Blob** | entity | An individual EIP-4844 data blob attached to a transaction; a single tx can carry multiple. The entity is `Blob`; the feature folder/flag that surfaces it uses the name `data-availability`. |
+| **Block Reward** | entity | On-chain payout to a block producer (miner, validator, etc.). Entirely distinct from the **Rewards** (Merits) program — no shared code, API, or folder. |
+| **CCTX (Cross-Chain Transaction)** | entity | ZetaChain-specific transaction type that spans multiple chains. Displayed as a separate tab on the transactions list. Distinct from the general cross-chain transactions feature (**Interchain Indexer**). |
+| **Chain Variant** | concept | A non-rollup chain that ships custom UI or domain entities (e.g. Celo, TAC, ZetaChain, Beacon Chain, Zilliqa). Contrast with **Rollup**, which implies an L1/L2 settlement relationship. |
+| **Clusters** | service | Address identity and grouping service: aggregates multiple addresses under a named cluster (individual, protocol, organization). Co-located with **BENS** in the name-services UI. |
+| **Connect Wallet** | feature | Lets users write to contracts, sign transactions, and connect a wallet to the explorer. Previously named `blockchain-interaction`; the current config key is `connectWallet`. Distinct from **Web3 Wallet**. |
+| **Dispute Games** | entity | Part of the Optimism **Fault Proof System**. On-chain games used to challenge and resolve disputed L2 output roots. |
+| **Easter Eggs** | feature | Hidden mini-games wired to claim links for badge rewards. |
+| **Epoch** | entity | A consensus time period specific to **Celo**. Has its own index and detail pages. Always refers to a Celo epoch in this codebase — not a generic blockchain concept. |
+| **Fault Proof System** | feature | Optimism's mechanism for proving the correctness of L2 state transitions on L1 via **Dispute Games**. |
+| **Flashblocks** | feature | MegaETH's sub-second block streaming mechanism. |
+| **Hot Contracts** | feature | Ranked list of the most recently and frequently interacted-with smart contracts on the network. |
+| **Interchain Indexer** | service | Microservice that indexes cross-chain messages and token transfers across heterogeneous chains. General-purpose interop indexer, not ZetaChain-specific. Provides "Cross chain txs" feature. Distinct from **CCTX**. |
+| **Interop Messages** | entity | **Deprecated** Cross-rollup messages passed between OP Stack chains using the native interoperability protocol. Distinct from **Interchain Indexer** messages. |
+| **Kettle** | entity | In the **SUAVE** architecture, a Kettle is a trusted execution environment (TEE) node that processes MEV bundles. SUAVE transactions are associated with a Kettle. |
+| **Marketplace** | feature | Curated directory of dApps and DeFi applications integrated with Blockscout. |
+| **MetaSuites** | service | Third-party browser extension that enhances the Blockscout UI with additional data and links. |
+| **Multichain** | feature | Aggregates data across multiple Blockscout-indexed chains into a single explorer view. |
+| **Operation** | entity | **TAC**-specific entity representing a bridge operation between the TON and EVM ecosystems. No equivalent on standard EVM chains. |
+| **Pools** | entity | DEX liquidity pool positions tracked on-chain. |
+| **Public Tags** | feature | Community-submitted labels for addresses, visible on address pages. A sub-feature of **Address Metadata**. |
+| **Rewards** | feature | The Blockscout Merits program — a token rewards and incentives system operated by Blockscout. Entirely distinct from **Block Reward** (on-chain block-producer payouts). |
+| **Rollup** | concept | A chain that settles transactions on a parent (L1) chain. Introduces specific entities: deposits, withdrawals, transaction batches, output roots. Contrast with **Chain Variant**. |
+| **SolidityScan** | service | Third-party smart contract security vulnerability scanner integrated into contract detail pages. |
+| **SUAVE** | chain | MEV-focused chain developed by Flashbots, built around a trusted execution environment (TEE) architecture. Introduces the **Kettle** entity. |
+| **TAC (Ton Application Chain)** | chain | A chain that bridges the TON blockchain and EVM ecosystems. Introduces the **Operation** entity. |
+| **Tx Actions** | feature | Structured per-transaction action breakdown rendered on the tx details page — a first-party Blockscout interpretation of what a tx did. Distinct from **Tx Interpretation** (natural-language summary) and from raw calldata. |
+| **Tx Interpretation** | feature | Natural-language summary of a transaction shown on detail pages. Distinct from **Tx Actions**. |
+| **User Op (User Operation)** | entity | ERC-4337 account-abstraction operation — a transaction-like object submitted to a bundler rather than directly to the network. |
+| **Validators** | feature | The set of active block validators on chains that expose this concept (e.g. zkSync Era, Celo). Not present on standard PoW/PoS EVM chains without explicit support. |
+| **Visualize** | service | Service that converts Solidity source code into UML diagrams (class and storage layout). |
+| **Watchlist** | feature | An **Account** feature that lets authenticated users track a set of addresses and receive notifications for their activity. |
+| **Web3 Wallet** | feature | Lets users add tokens and networks directly from the explorer to their browser wallet. Distinct from **Connect Wallet** (signing/writing). |
+| **X-Star Score** | feature | Third-party reputation score shown on address pages, linking out to the X-Star service. |

.agents/rules/architecture.mdc

@@ -1,5 +1,5 @@
 ---
-description: Project overview, tech stack, directory layout, data flow, and ongoing client/ architecture migration
+description: Project overview, tech stack, and directory layout
 globs:
 alwaysApply: true
 ---
@@ -25,60 +25,72 @@ Blockscout frontend — a blockchain explorer UI. Distributed as a Docker image;
 
 ## Domain terminology
 
-Feature and product codenames used throughout the codebase are defined in `docs/GLOSSARY.md`. Consult it whenever you encounter an unfamiliar term — e.g. `tac`, `bens`, `cctx`, `kettle`, `epoch`, `blobs`.
+Feature and product codenames used throughout the codebase are defined in `.agents/GLOSSARY.md`. Consult it whenever you encounter an unfamiliar term — e.g. `tac`, `bens`, `cctx`, `kettle`, `epoch`, `blobs`.
 
 ## Directory layout
 
-```
-pages/          Next.js file-based routes — thin wrappers only (dynamic import + getServerSideProps)
-ui/             Legacy React UI components organized by feature (~65 subdirectories) → being migrated to client/
-lib/            Legacy business logic, API utilities, custom hooks, context providers → being migrated to client/
-client/         New home for all product code (see Migration section below)
-toolkit/        Design system — Chakra wrappers, theme tokens, shared hooks/components (stays here permanently)
-configs/app/    Runtime app configuration; must not import from client/
-nextjs/         Next.js config utilities: headers, rewrites, redirects, type-safe routes
-mocks/          Shared mock data for tests → being co-located under client/ slices/features
-deploy/         Docker scripts, env validator, build tools
-docs/           ENVS.md, GLOSSARY.md, CONTRIBUTING.md
-```
+All application source lives under `/src`. Code is co-located by **slice** (core explorer domain) or **feature** (optional / config-gated area).
 
-## Data flow
+### Top-level repo
 
-- **Getting data:** pages fetch data via React Query. Query keys and fetcher functions live in `lib/api/` (moving to `client/api/`).
-- **Global UI state:** React Context providers initialized in `pages/_app.tsx` — `AppContextProvider`, `SettingsContextProvider`, `MarketplaceContextProvider`, etc.
-- **Real-time data:** WebSocket via `SocketProvider` (moving to `client/api/socket/`).
-- **App config:** always read via `configs/app/` (which reads `window.__envs` at runtime) — never `process.env.*` directly in component code.
+| Path | Role |
+|---|---|
+| `/src` | All application source — product UI, server plumbing, routing, config, design system, and code-imported assets |
+| `/tools/` | Developer tooling — local dev utilities and scripts (e.g. `tools/dev-server/`, which loads the dev server's env vars) |
+| `/deploy/` | CI/CD scripts, Docker, env validator, build tools |
+| `/public/` | Static assets served as-is (sprite output, etc.) — never bundled |
+| `/docs/` | ENVS.md, CONTRIBUTING.md, etc. |
+| Root config files | `next.config.js`, `tsconfig.json`, `eslint.config.mjs`, `package.json` |
 
----
+### Inside `/src`
 
-## Ongoing migration: `client/` architecture
+| Path | Role |
+|---|---|
+| `src/api/` | Transport, fetch utilities, query client, WebSocket, data-fetching hooks |
+| `src/shell/` | App chrome: layout, header, footer, navigation, top-bar, root contexts |
+| `src/slices/` | Core explorer entities — always present on any vanilla EVM chain |
+| `src/features/` | Optional / config-gated product areas |
+| `src/shared/` | Cross-cutting utilities with no single domain owner |
+| `src/config/` | Runtime app configuration (aggregator + cross-cutting parts) |
+| `src/services/` | Third-party integrations: analytics, error reporting, A/B flags |
+| `src/pages/` | Next.js file-based routes — thin wrappers only |
+| `src/server/` | Next.js server plumbing: SSR helpers, middleware, CSP, headers, rewrites |
+| `src/sprite/` | SVG sprite runtime component + icon source files |
+| `src/toolkit/` | Design system — pnpm workspace package, published as `@blockscout/ui-toolkit` |
 
-The codebase is being progressively restructured. The long-term target moves all product code from `ui/` and `lib/` into a new `client/` directory with a clear domain-based layout.
+### Slice vs feature
 
-**Blueprint:** `client/ARCH_REDESIGN.md`
-**Task backlog and current status:** `client/MIGRATION_TASKS.md`
+Key classification question: *"Can this area exist on a vanilla EVM chain with no feature flag?"*
 
-### Target layout inside `client/`
+- **Slice** — yes. Always present. Examples: `tx`, `block`, `address`, `token`, etc.
+- **Feature** — no. Config-gated or chain-specific. Examples: `rollup/optimism`, `chain-variants/celo`, `account`, `stats`, `gas-tracker`. Every config-gated feature with user-facing UI gets its own folder under `src/features/`, regardless of size.
+- **Service, not feature** — config-gated infrastructure with no user-facing UI (analytics, error reporting, A/B flags) lives under `src/services/`, not `src/features/`.
 
-| Directory | Contents |
-|---|---|
-| `client/shell/` | App chrome: layout, header, footer, navigation, top-bar, root contexts |
-| `client/api/` | API transport, fetch utilities, query client, WebSocket; migrated from `lib/api/` and `lib/socket/` |
-| `client/slices/` | Core explorer entities always present on any EVM chain (tx, block, address, token, contract, search, …) |
-| `client/features/` | Optional / config-gated areas: rollups, chain variants, account, rewards, marketplace, stats, … |
-| `client/shared/` | Cross-cutting utilities with no single domain owner (analytics, errors, hooks, router helpers, text utils, …) |
+Both slices and features share the same internal shape: `pages/`, `components/`, `hooks/`, `utils/`, `types/`, `config.ts`, `mocks.ts` or `mocks/`, `stubs.ts` or `stubs/`.
 
-### Slice vs feature
+### Naming conventions
 
-- **Slice** — present on every vanilla EVM chain, no feature flag required. Examples: `tx`, `block`, `address`, `token`, `contract`.
-- **Feature** — config-gated or chain-specific. Examples: `rollup/optimism`, `chain-variants/celo`, `account`, `stats`, `gas-tracker`.
+| Artifact | Convention |
+|---|---|
+| Directories | `kebab-case` |
+| React components | `PascalCase.tsx` |
+| Hooks | `use` + `camelCase.ts` |
+| Helper / util modules | `kebab-case.ts` |
+| Role files | lowercase — `types.ts`, `mocks.ts`, `stubs.ts`, `config.ts` |
+
+### Key rules
+
+- **No re-export-only barrel `index.ts` files** inside `/src`. Aggregator files that curate a genuine public surface are fine.
+- **`src/api/resources` must not have runtime imports** from `src/slices/*` or `src/features/*`; `import type` is allowed.
+- **`config.ts` and `types/config.ts` files** must not import React, browser APIs, or code from other slices/features — they are executed by the Node.js env validator.
+- **`src/pages/` files are thin wrappers** — a dynamic import and optionally `getServerSideProps`; no UI components or business logic inline.
+- **Cross-domain type imports** go through `<slice|feature>/types/api.ts`, never deeper internal paths.
+- **Compose at the page level** when optional feature UI plugs into a core slice — the slice page renders the feature's component, not the other way around. Avoids cycles and keeps the feature opt-in.
+- **No files directly at the root of `src/shared/`** — only subfolders grouped by purpose.
 
-### Key rules for migrated code
+## Data flow
 
-- **No barrel `index.ts` files** inside `client/` unless the file defines a genuine public facade (not just `export * from ...`).
-- **`client/api` must not have runtime imports** from `client/slices/*` or `client/features/*`; `import type` is allowed.
-- **`configs/` never imports `client/`.**
-- **`pages/` files are thin wrappers** — a dynamic import and optionally `getServerSideProps`; no UI components or business logic inline.
-- **Naming:** kebab-case for directories and non-component modules; `PascalCase.tsx` for React components; `useCamelCase.ts` for hooks.
-- **Types:** each slice/feature owns its API response types in `<slice|feature>/types/api.ts`. Do not import from deeper internal paths across domain boundaries.
-- **When editing legacy `lib/` or `ui/` code:** check `client/MIGRATION_TASKS.md` to see if that area has a migration task in progress or planned. If so, note the target destination in your PR description.
+- **Getting data:** pages fetch data via React Query. Query keys and fetcher functions live in `src/api/hooks` and `src/api/utils`.
+- **Global UI state:** React Context providers initialized in `src/pages/_app.tsx` — `AppContextProvider`, `SettingsContextProvider`, `MarketplaceContextProvider`, etc.
+- **Real-time data:** WebSocket via `SocketProvider` in `src/api/socket/`.
+- **App config:** always read via `src/config/` (which reads `window.__envs` at runtime) — never `process.env.*` directly in component code, except for server code (`src/server/`).

.agents/rules/code-quality.mdc

@@ -128,11 +128,11 @@ Remove commented-out code blocks. The git history preserves anything that might
 ### Links
 
 - Use `toolkit/chakra/link` instead of `next/link`. Never import `Link` from `next/link` directly.
-- When links to **application pages** are constructed, verify that `nextjs-routes` or `nextjs/routes` utilities are used instead of string concatenation or template literals. The full list of application routes is available in `nextjs/nextjs-routes.d.ts`.
+- When links to **application pages** are constructed, verify that `nextjs-routes` or `src/shared/router/routes` utilities are used instead of string concatenation or template literals. The full list of application routes is available in `src/shared/router/nextjs-routes.d.ts`.
 
 ### Date and time
 
-- Import `dayjs` only via `lib/date/dayjs.ts` — never directly from the `dayjs` package.
+- Import `dayjs` only via `client/shared/date-and-time/dayjs.ts` — never directly from the `dayjs` package.
 - Render all dates and times through the shared `Time` or `TimeWithTooltip` components. Do not format timestamps inline.
 
 ### Strict comparison