feat (explorer): add wrapper designation to order details (#7404)

* feat (explorer): add wrapper designation to order details

Renders a "Wrappers" row in the verbose order details table for orders
whose appData references known wrapper contracts. Wrapper-specific UI
is code-split and loaded on demand; unknown addresses fall back to
fetching the contract name() on-chain.

Supported wrappers:
- OrderFlowFactory (bridge & swap)
- Euler EVC – Open Position, Close Position, Collateral Swap

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* remove references to orderflow

shouldn't be in this pr

* fix build error

* feat: improve explorer wrapper details display and code quality

- Add tooltip for unknown wrappers explaining missing details
- Lift contract name lookup into WrapperEntry header
- Key wrapper rows by address+data to avoid React reconciliation collisions
- Use getAddressKey() from cow-sdk for registry lookup
- Remove non-null assertions in _vaultLookup.ts with proper SWR guards
- Fix getPublicClient with explicit return type and early-return pattern
- Fix import ordering across touched files
- Extract *View sub-components to reduce per-function complexity
- Delete unused unknown.tsx wrapper component

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor: split eulerEvc.tsx into per-wrapper files

Move each wrapper component into its own file under eulerEvc/ with
shared styled components and helpers extracted to common.tsx.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor: move Euler vault hooks to hooks/euler/

Split _vaultLookup.ts into dedicated files under hooks/euler/:
abis.ts, client.ts, and one file per hook. Dropped three hooks that
had no callers (useVaultBalance, useVaultDebt, useNativePrice).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor: use AddressKey type, shortenAddress, direct React imports, multicall

- Type address parameters as AddressKey from @cowprotocol/cow-sdk
- Replace manual address slicing with shortenAddress from @cowprotocol/common-utils
- Import ComponentType/ReactElement directly instead of via React. prefix
- Batch ERC20 symbol/name/decimals reads in useVaultAsset into a single multicall

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* add import for detail row/tooltips

* use jotai for state management, and remove unnecessary orderflow file (should be separate PR)

* lint fix and resolve deprecated dependency

* fix design issues as suggested

* fix word wrap

* try to fix pnpm lock

* docs(explorer): add UI and code conventions to AGENTS.md (#7459)

* docs(explorer): add UI and code conventions to AGENTS.md

Standards identified through review feedback on #7404:
- Link display: ↗ suffix rules, parenthesis placement, flex gap pitfall
- Token display: TokenImg icon placement, orange link colour via Color.explorer_textActive
- Text wrapping: word-break override inside RenderedData
- State caching: use jotai/jotai-family instead of module-level Map
- Address utilities: AddressKey type, shortenAddress, getAddressKey for lookups
- React imports: named imports over React.X prefix
- Contract reads: batch with multicall instead of separate readContract calls
- Hook organisation: one hook per file under a domain directory
- Component shape: *View sub-component pattern for lint compliance
- Pre-commit checklist: lint and dead-code removal

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* try to fix pnpm lock

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: re-organize Euler wrapper-realted components and update layout to work on narrow vieports

* fix: rename Euler-related files

* fix: rename Euler-related files

* refactor: fix typo in function name

* fix: remove jotai-family and revert dependency changes

* feat: introduce FiniteMap and use it for Euler's getPublicClient cache

* fix: narrow down deps of useEffect in OrderWrapperDetailsItem

* fix: fix FiniteMap eviction logic when accessing missing keys

* fix: add wrapper to TokenLink

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: fairlight <31534717+fairlighteth@users.noreply.github.com>
Co-authored-by: Elena <70885163+elena-zh@users.noreply.github.com>
Co-authored-by: Dani Gámez Franco <gmzcodes@outlook.com>

Author: 5 people

apps/explorer/AGENTS.md

@@ -1,13 +1,13 @@
 ---
 author: agents
 status: normative
-last_reviewed: 2026-03-05
+last_reviewed: 2026-05-06
 ---
 
 # explorer AGENTS.md
 
 Root rules: [`../../AGENTS.md`](../../AGENTS.md) (global safety, workflow, and verification baseline).
-This file: explorer app-specific commands only.
+This file: explorer app-specific commands and UI conventions.
 
 ## App commands
 - Start dev server: `pnpm start:explorer`
@@ -16,3 +16,49 @@ This file: explorer app-specific commands only.
 - Lint: `pnpx nx run explorer:lint`
 - Test: `pnpx nx run explorer:test`
 - Cosmos: `pnpm start:cosmos:explorer`
+
+## Link and address display conventions
+
+- `MUST` append `↗` to link text for external links (block explorer, etherscan). Do this for address links and contract links.
+- `MUST NOT` append `↗` to token symbol links — token names are never suffixed with the external link indicator.
+- `MUST` render parentheses around address links as plain text nodes outside the `<a>` tag, not inside it. E.g. `(<a href={url}>{shortAddress}↗</a>)`.
+- `MUST` wrap `(link)` constructs in a single `<span>` when inside a flex container, otherwise `gap` inserts space between the parens and the link text.
+- `MUST` use `Color.explorer_textActive` (orange) explicitly for link `color` inside styled components. Do not use `color: inherit` on `a` elements inside styled components — it will inherit the surrounding prose color (grey) instead of the global orange.
+
+## Token display
+
+- `MUST` show a `TokenImg` icon before a linked token symbol. Size the icon to match the surrounding font-size context (e.g. `width: 2rem; height: 2rem` when `font-size: 2rem`).
+- Styled containers wrapping token links `MUST` use `display: flex; align-items: center` so the icon and text sit on the same baseline.
+
+## Text wrapping inside RenderedData
+
+- `RenderedData` sets `word-break: break-all`. Any child component that contains prose text `MUST` override this with `word-break: normal` to get word-level wrapping instead of character-level wrapping.
+
+## State caching outside React
+
+- Use `jotai` or `jotai-family` to handle any outside-react caching.
+
+## Address utilities
+
+- `MUST` type address parameters as `AddressKey` from `@cowprotocol/cow-sdk`, not plain `string`.
+- `MUST` use `shortenAddress` from `@cowprotocol/common-utils` to abbreviate addresses. `MUST NOT` manually slice (`address.slice(0, 6)…address.slice(-4)`).
+- `MUST` use `getAddressKey()` from `@cowprotocol/cow-sdk` when looking up addresses in registries or maps (e.g. `WRAPPERS_BY_ADDRESS`). `MUST NOT` use `address.toLowerCase()` for this purpose (root rule, repeated here for emphasis).
+
+## React imports
+
+- `MUST` import React types directly by name (`ComponentType`, `ReactElement`, `ReactNode`, etc.). `MUST NOT` use `React.ComponentType` / `React.ReactElement` prefix form — it couples the import to the default namespace unnecessarily.
+
+## Contract reads
+
+- `MUST` batch multiple reads from the same contract into a single `multicall` call rather than issuing separate `readContract` calls. For example, fetching `symbol`, `name`, and `decimals` for an ERC-20 should be one `multicall`.
+
+## Hook and component organisation
+
+- `MUST` put each hook in its own file under a domain directory (e.g. `hooks/euler/useVaultAsset.ts`). `MUST NOT` bundle unrelated hooks in one file.
+- Wrapper components that render decoded data `SHOULD` extract a `*View` sub-component with all props passed explicitly and no hooks, to satisfy lint complexity limits.
+
+## Before committing
+
+- `SHOULD` run `pnpm nx run explorer:lint` and fix all violations.
+- `SHOULD` delete any exports, hooks, or components with no callers introduced or left behind by the change.
+

apps/explorer/package.json

@@ -22,18 +22,18 @@
   },
   "dependencies": {
     "@apollo/client": "3.1.5",
-    "@cowprotocol/cow-sdk": "9.0.2",
-    "@cowprotocol/sdk-bridging": "4.0.2",
-    "@cowprotocol/sdk-ethers-v5-adapter": "0.4.4",
-    "@cowprotocol/sdk-subgraph": "1.0.7",
-    "@cowprotocol/sdk-contracts-ts": "3.0.1",
-    "@cowprotocol/sdk-viem-adapter": "0.3.18",
     "@cowprotocol/analytics": "workspace:*",
     "@cowprotocol/common-const": "workspace:*",
     "@cowprotocol/common-hooks": "workspace:*",
     "@cowprotocol/common-utils": "workspace:*",
     "@cowprotocol/core": "workspace:*",
+    "@cowprotocol/cow-sdk": "9.0.2",
     "@cowprotocol/hook-dapp-lib": "workspace:*",
+    "@cowprotocol/sdk-bridging": "4.0.2",
+    "@cowprotocol/sdk-contracts-ts": "3.0.1",
+    "@cowprotocol/sdk-ethers-v5-adapter": "0.4.4",
+    "@cowprotocol/sdk-subgraph": "1.0.7",
+    "@cowprotocol/sdk-viem-adapter": "0.3.18",
     "@cowprotocol/types": "workspace:*",
     "@cowprotocol/ui": "workspace:*",
     "@fortawesome/fontawesome-svg-core": "^6.7.1",

apps/explorer/src/components/orders/DetailsTable/VerboseDetails.tsx

@@ -12,9 +12,12 @@ import { OrderSurplusItem } from './items/OrderSurplusItem'
 import { SolvedByItem } from './items/SolvedByItem'
 
 import { Order } from '../../../api/operator'
+import { DetailRow } from '../../../components/common/DetailRow'
+import { DetailsTableTooltips } from '../../../components/orders/DetailsTable/detailsTableTooltips'
 import { OrderSolverInfo } from '../../../hooks/useOrderSolver'
 import { OrderHooksDetails } from '../OrderHooksDetails'
 import { OrderPriceDisplayProps } from '../OrderPriceDisplay'
+import { OrderWrapperDetails } from '../OrderWrapperDetails/OrderWrapperDetails.component'
 
 interface VerboseDetailsProps {
   order: Order
@@ -88,7 +91,13 @@ export function VerboseDetails({
           viewFills={viewFills}
         />
       )}
-
+      <OrderWrapperDetails fullAppData={fullAppData ?? undefined} order={order}>
+        {(content) => (
+          <DetailRow label="Wrappers" tooltipText={DetailsTableTooltips.wrappers}>
+            {content}
+          </DetailRow>
+        )}
+      </OrderWrapperDetails>
       <OrderHooksDetails appData={appData} fullAppData={fullAppData ?? undefined}>
         {(content) => <HooksItem>{content}</HooksItem>}
       </OrderHooksDetails>

apps/explorer/src/components/orders/DetailsTable/detailsTableTooltips.tsx

@@ -19,6 +19,7 @@ export const DetailsTableTooltips = {
     'The AppData hash for this order. It can denote encoded metadata with info on the app, environment and more, although not all interfaces follow the same pattern. Show more will try to decode that information.',
   status: 'The order status is either Signing, Open, Filled, Partially filled, Expired or Cancelled.',
   solvedBy: 'The solver that won and executed the settlement for this order.',
+  wrappers: 'Wrappers are smart contracts that execute as part of this order, as specified in the appData.',
   hooks: 'Hooks are interactions before/after order execution.',
   submission:
     'The date and time at which the order was submitted. The timezone is based on the browser locale settings.',

apps/explorer/src/components/orders/OrderWrapperDetails/OrderWrapperDetails.component.tsx

@@ -0,0 +1,33 @@
+import { ReactElement } from 'react'
+
+import { OrderWrapperDetailsItem } from 'components/orders/OrderWrapperDetails/item/OrderWrapperDetailsItem.component'
+
+import { OrderCtxProvider } from './OrderWrapperDetails.provider'
+import * as styledEl from './OrderWrapperDetails.styled'
+
+import { Order } from '../../../api/operator'
+import { getOrderWrappers } from '../../../utils/getOrderWrappers'
+
+interface OrderWrapperDetailsProps {
+  fullAppData: string | undefined
+  order?: Order
+  children: (content: ReactElement) => ReactElement
+}
+
+export function OrderWrapperDetails({ fullAppData, order, children }: OrderWrapperDetailsProps): ReactElement | null {
+  const wrappers = getOrderWrappers(fullAppData)
+
+  if (wrappers.length === 0) return null
+
+  return (
+    <OrderCtxProvider order={order ?? null}>
+      {children(
+        <styledEl.WrapperList>
+          {wrappers.map((wrapper) => (
+            <OrderWrapperDetailsItem key={`${wrapper.address}-${wrapper.data ?? ''}`} wrapper={wrapper} />
+          ))}
+        </styledEl.WrapperList>,
+      )}
+    </OrderCtxProvider>
+  )
+}

apps/explorer/src/components/orders/OrderWrapperDetails/OrderWrapperDetails.provider.tsx

@@ -0,0 +1,17 @@
+import { createContext, PropsWithChildren, useContext, ReactNode } from 'react'
+
+import { Order } from '../../../api/operator'
+
+export const OrderCtx = createContext<Order | null>(null)
+
+export function useOrderContext(): Order | null {
+  return useContext(OrderCtx)
+}
+
+export interface OrderCtxProviderProps extends PropsWithChildren {
+  order: Order | null
+}
+
+export function OrderCtxProvider({ order, children }: OrderCtxProviderProps): ReactNode {
+  return <OrderCtx.Provider value={order}>{children}</OrderCtx.Provider>
+}

apps/explorer/src/components/orders/OrderWrapperDetails/OrderWrapperDetails.styled.tsx

@@ -0,0 +1,17 @@
+import { Media } from '@cowprotocol/ui'
+
+import styled from 'styled-components/macro'
+
+export const WrapperList = styled.ul`
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-flow: column wrap;
+  gap: 24px;
+  min-width: 420px;
+
+  ${Media.upToExtraSmall()} {
+    min-width: 100%;
+  }
+`

apps/explorer/src/components/orders/OrderWrapperDetails/item/OrderWrapperDetailsItem.component.tsx

@@ -0,0 +1,65 @@
+import { ComponentType, ReactElement, Suspense, useEffect, useState } from 'react'
+
+import { getBlockExplorerUrl, shortenAddress } from '@cowprotocol/common-utils'
+import { getAddressKey, SupportedChainId } from '@cowprotocol/cow-sdk'
+
+import * as styledEl from './OrderWrapperDetailsItem.styled'
+
+import { useContractName } from '../../../../hooks/euler'
+import { usePopperDefault } from '../../../../hooks/usePopper'
+import { useNetworkId } from '../../../../state/network/hooks'
+import { ResolvedWrapper } from '../../../../utils/getOrderWrappers'
+import { WRAPPERS_BY_ADDRESS } from '../../../../utils/wrappers/wrapperRegistry.constants'
+import { Tooltip } from '../../../Tooltip'
+
+const UNKNOWN_WRAPPER_TOOLTIP =
+  'Explorer does not recognize this wrapper address yet, so it cannot decode wrapper-specific details. This may be a custom wrapper or a supported wrapper missing from the registry.'
+
+export function OrderWrapperDetailsItem({ wrapper }: { wrapper: ResolvedWrapper }): ReactElement {
+  const [Component, setComponent] = useState<ComponentType<{ data: string }> | null>(null)
+  const { info, address, data, loadComponent, isOmittable } = wrapper
+  const chainId = useNetworkId() as SupportedChainId | null
+  const isUnknown = !WRAPPERS_BY_ADDRESS[getAddressKey(address)]
+  const contractName = useContractName(isUnknown ? address : '')
+  const { tooltipProps, targetProps } = usePopperDefault<HTMLLIElement>('top')
+
+  useEffect(() => {
+    if (!data || !loadComponent) return
+    loadComponent().then((Comp) => setComponent(() => Comp))
+  }, [data, loadComponent])
+
+  const addressUrl = chainId ? getBlockExplorerUrl(chainId, 'contract', address) : undefined
+  const shortAddress = shortenAddress(address)
+  const displayName = isUnknown ? (contractName ?? shortAddress) : info.name
+
+  return (
+    <>
+      <styledEl.WrapperItem {...(isUnknown ? targetProps : {})}>
+        <styledEl.WrapperHeader>
+          {info.image && <img src={info.image} alt={info.name} />}
+          <strong>{displayName}</strong>
+          {addressUrl ? (
+            <span>
+              (
+              <a href={addressUrl} target="_blank" rel="noopener noreferrer" title={address}>
+                {shortAddress}↗
+              </a>
+              )
+            </span>
+          ) : (
+            <span title={address}>({shortAddress})</span>
+          )}
+          {isOmittable && <em>(omittable)</em>}
+        </styledEl.WrapperHeader>
+        {Component && data && (
+          <styledEl.RenderedData>
+            <Suspense fallback={<span>Loading…</span>}>
+              <Component data={data} />
+            </Suspense>
+          </styledEl.RenderedData>
+        )}
+      </styledEl.WrapperItem>
+      {isUnknown && <Tooltip {...tooltipProps}>{UNKNOWN_WRAPPER_TOOLTIP}</Tooltip>}
+    </>
+  )
+}

apps/explorer/src/components/orders/OrderWrapperDetails/item/OrderWrapperDetailsItem.styled.tsx

@@ -0,0 +1,50 @@
+import { Color } from '@cowprotocol/ui'
+
+import styled from 'styled-components/macro'
+
+export const WrapperItem = styled.li`
+  display: flex;
+  flex-flow: column wrap;
+  gap: 12px;
+`
+
+export const WrapperHeader = styled.p`
+  margin: 0;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+
+  > img {
+    width: 2rem;
+    height: 2rem;
+  }
+`
+
+export const RenderedData = styled.div`
+  border: 1px solid ${Color.explorer_tableRowBorder};
+  border-radius: 0.5rem;
+  background: ${Color.explorer_tableRowBorder};
+  overflow: auto;
+  word-break: break-all;
+  line-height: 1.5;
+
+  table {
+    border-collapse: collapse;
+    width: 100%;
+  }
+
+  td {
+    padding: 0.2rem 1rem 0.2rem 0;
+    vertical-align: top;
+
+    &:first-child {
+      font-weight: 500;
+      white-space: nowrap;
+    }
+  }
+
+  code {
+    font-size: 1.2rem;
+  }
+`

apps/explorer/src/hooks/euler/abis.ts

@@ -0,0 +1,16 @@
+export const ERC4626_ABI = [
+  { name: 'asset', type: 'function', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+  {
+    name: 'convertToAssets',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [{ name: 'shares', type: 'uint256' }],
+    outputs: [{ type: 'uint256' }],
+  },
+] as const
+
+export const ERC20_ABI = [
+  { name: 'symbol', type: 'function', stateMutability: 'view', inputs: [], outputs: [{ type: 'string' }] },
+  { name: 'name', type: 'function', stateMutability: 'view', inputs: [], outputs: [{ type: 'string' }] },
+  { name: 'decimals', type: 'function', stateMutability: 'view', inputs: [], outputs: [{ type: 'uint8' }] },
+] as const