Clusters Feature Integration

configs/app/apis.ts

@@ -100,26 +100,6 @@ const rewardsApi = (() => {
     endpoint: apiHost,
   });
 })();
-
-const multichainApi = (() => {
-  const apiHost = getEnvValue('NEXT_PUBLIC_MULTICHAIN_AGGREGATOR_API_HOST');
-  if (!apiHost) {
-    return;
-  }
-
-  try {
-    const url = new URL(apiHost);
-
-    return Object.freeze({
-      endpoint: apiHost,
-      socketEndpoint: `wss://${ url.host }`,
-    });
-  } catch (error) {
-    return;
-  }
-
-})();
-
 const statsApi = (() => {
   const apiHost = getEnvValue('NEXT_PUBLIC_STATS_API_HOST');
   if (!apiHost) {
@@ -166,6 +146,35 @@ const visualizeApi = (() => {
   });
 })();
 
+const clustersApi = (() => {
+  const apiHost = getEnvValue('NEXT_PUBLIC_CLUSTERS_API_HOST');
+  if (!apiHost) {
+    return;
+  }
+
+  return Object.freeze({
+    endpoint: apiHost,
+  });
+})();
+
+const multichainApi = (() => {
+  const apiHost = getEnvValue('NEXT_PUBLIC_MULTICHAIN_AGGREGATOR_API_HOST');
+  if (!apiHost) {
+    return;
+  }
+
+  try {
+    const url = new URL(apiHost);
+
+    return Object.freeze({
+      endpoint: apiHost,
+      socketEndpoint: `wss://${ url.host }`,
+    });
+  } catch (error) {
+    return;
+  }
+})();
+
 export type Apis = {
   general: ApiPropsFull;
 } & Partial<Record<Exclude<ApiName, 'general'>, ApiPropsBase>>;
@@ -174,6 +183,7 @@ const apis: Apis = Object.freeze({
   general: generalApi,
   admin: adminApi,
   bens: bensApi,
+  clusters: clustersApi,
   contractInfo: contractInfoApi,
   metadata: metadataApi,
   multichain: multichainApi,

configs/app/features/clusters.ts

@@ -0,0 +1,26 @@
+import type { Feature } from './types';
+
+import apis from '../apis';
+import { getEnvValue } from '../utils';
+
+const title = 'Clusters Universal Name Service';
+
+const config: Feature<{ cdnUrl: string }> = (() => {
+  const cdnUrl = getEnvValue('NEXT_PUBLIC_CLUSTERS_CDN_URL') || 'https://cdn.clusters.xyz';
+
+  if (apis.clusters) {
+    return Object.freeze({
+      title,
+      isEnabled: true,
+      cdnUrl,
+    });
+  }
+
+  return Object.freeze({
+    title,
+    isEnabled: false,
+    cdnUrl,
+  });
+})();
+
+export default config;

configs/app/features/index.ts

@@ -10,6 +10,7 @@ export { default as beaconChain } from './beaconChain';
 export { default as bridgedTokens } from './bridgedTokens';
 export { default as blockchainInteraction } from './blockchainInteraction';
 export { default as celo } from './celo';
+export { default as clusters } from './clusters';
 export { default as csvExport } from './csvExport';
 export { default as dataAvailability } from './dataAvailability';
 export { default as deFiDropdown } from './deFiDropdown';

configs/envs/.env.jest

@@ -50,3 +50,7 @@ NEXT_PUBLIC_STATS_API_HOST=https://localhost:3004
 NEXT_PUBLIC_CONTRACT_INFO_API_HOST=https://localhost:3005
 NEXT_PUBLIC_ADMIN_SERVICE_API_HOST=https://localhost:3006
 NEXT_PUBLIC_RE_CAPTCHA_APP_SITE_KEY=xxx
+
+# clusters feature
+NEXT_PUBLIC_CLUSTERS_API_HOST=https://api.clusters.xyz
+NEXT_PUBLIC_CLUSTERS_CDN_URL=https://cdn.clusters.xyz

configs/envs/.env.localhost

@@ -37,3 +37,7 @@ NEXT_PUBLIC_APP_ENV=development
 NEXT_PUBLIC_IS_ACCOUNT_SUPPORTED=true
 NEXT_PUBLIC_AUTH_URL=http://localhost:3000
 NEXT_PUBLIC_LOGOUT_URL=https://blockscoutcom.us.auth0.com/v2/logout
+
+# clusters feature
+NEXT_PUBLIC_CLUSTERS_API_HOST=https://api.clusters.xyz
+NEXT_PUBLIC_CLUSTERS_CDN_URL=https://cdn.clusters.xyz

configs/envs/.env.pw

@@ -60,4 +60,6 @@ NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=xxx
 NEXT_PUBLIC_VIEWS_ADDRESS_FORMAT=['base16','bech32']
 NEXT_PUBLIC_VIEWS_ADDRESS_BECH_32_PREFIX=tom
 NEXT_PUBLIC_HELIA_VERIFIED_FETCH_ENABLED=false
-NEXT_PUBLIC_GAS_TRACKER_UNITS=['usd','gwei']
+NEXT_PUBLIC_GAS_TRACKER_UNITS=['usd','gwei']
+NEXT_PUBLIC_CLUSTERS_API_HOST=https://api.clusters.xyz
+NEXT_PUBLIC_CLUSTERS_CDN_URL=https://cdn.clusters.xyz

deploy/tools/envs-validator/schema.ts

@@ -445,7 +445,7 @@ const rollupSchema = yup
       }),
   });
 
-const celoSchema = yup
+  const celoSchema = yup
   .object()
   .shape({
     NEXT_PUBLIC_CELO_ENABLED: yup.boolean(),
@@ -1050,6 +1050,8 @@ const schema = yup
     NEXT_PUBLIC_VISUALIZE_API_BASE_PATH: yup.string(),
     NEXT_PUBLIC_CONTRACT_INFO_API_HOST: yup.string().test(urlTest),
     NEXT_PUBLIC_NAME_SERVICE_API_HOST: yup.string().test(urlTest),
+    NEXT_PUBLIC_CLUSTERS_API_HOST: yup.string().test(urlTest),
+    NEXT_PUBLIC_CLUSTERS_CDN_URL: yup.string().test(urlTest),
     NEXT_PUBLIC_ADMIN_SERVICE_API_HOST: yup.string().test(urlTest),
     NEXT_PUBLIC_WEB3_WALLETS: yup
       .mixed()

deploy/values/review/values.yaml.gotmpl

@@ -79,6 +79,8 @@ frontend:
     PROMETHEUS_METRICS_ENABLED: true
     NEXT_PUBLIC_OG_ENHANCED_DATA_ENABLED: true
     NEXT_PUBLIC_VIEWS_TOKEN_SCAM_TOGGLE_ENABLED: true
+    NEXT_PUBLIC_CLUSTERS_API_HOST: https://api.clusters.xyz
+    NEXT_PUBLIC_CLUSTERS_CDN_URL: https://cdn.clusters.xyz
   envFromSecret:
     NEXT_PUBLIC_AUTH0_CLIENT_ID: ref+vault://deployment-values/blockscout/dev/review?token_env=VAULT_TOKEN&address=https://vault.k8s.blockscout.com#/NEXT_PUBLIC_AUTH0_CLIENT_ID
     NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID: ref+vault://deployment-values/blockscout/dev/review?token_env=VAULT_TOKEN&address=https://vault.k8s.blockscout.com#/NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID

docs/ENVS.md

@@ -56,6 +56,7 @@ All json-like values should be single-quoted. If it contains a hash (`#`) or a d
   - [Verified tokens info](#verified-tokens-info)
   - [Name service integration](#name-service-integration)
   - [Metadata service integration](#metadata-service-integration)
+  - [Clusters Universal Name Service](#clusters-universal-name-service)
   - [Public tag submission](#public-tag-submission)
   - [Data availability](#data-availability)
   - [Bridged tokens](#bridged-tokens)
@@ -672,6 +673,17 @@ This feature allows name tags and other public tags for addresses.
 
  
 
+### Clusters Universal Name Service
+
+This feature integrates Clusters.xyz universal naming service, enabling users to look up and track cross-chain identities through human-readable names like "vitalik/" or "uniswap/". Unlike traditional domain services that work on single chains, clusters span multiple blockchains - one cluster name can represent addresses on Ethereum, Base, Optimism, and other networks. This integration adds cluster lookup pages (/clusters/[name]), a clusters directory (/clusters), search functionality in the main search bar, and displays cluster profile information and images throughout the explorer.
+
+| Variable | Type| Description | Compulsoriness  | Default value | Example value | Version |
+| --- | --- | --- | --- | --- | --- | --- |
+| NEXT_PUBLIC_CLUSTERS_API_HOST | `string` | Clusters.xyz API endpoint for fetching cluster data, directory listings, and cross-chain address mappings | Required | - | `https://example.com/clusters-api` | v2.2.0+ |
+| NEXT_PUBLIC_CLUSTERS_CDN_URL | `string` | CDN base URL for serving cluster profile images and avatars displayed in search results and cluster pages | - | `https://cdn.clusters.xyz` | `https://your-cdn.example.com` | v2.2.0+ |
+
+ 
+
 ### Public tag submission
 
 This feature allows you to submit an application with a public address tag.

jest.config.ts

@@ -15,6 +15,9 @@ const config: JestConfigWithTsJest = {
   ],
   moduleNameMapper: {
     '^jest/(.*)': '<rootDir>/jest/$1',
+    '^nextjs-routes$': '<rootDir>/jest/mocks/nextjs-routes.js',
+    '\\.svg$': '<rootDir>/jest/mocks/svg.js',
+    '^@uidotdev/usehooks$': '<rootDir>/jest/mocks/usehooks.js',
   },
   modulePathIgnorePatterns: [
     'node_modules_linux',

jest/mocks/nextjs-routes.js

@@ -0,0 +1,18 @@
+module.exports = {
+  route: jest.fn((opts) => {
+    const pathname = opts?.pathname;
+    const query = opts?.query || {};
+
+    if (pathname === '/address/[hash]') {
+      return `/address/${ query.hash || 'test-hash' }`;
+    }
+    if (pathname === '/tx/[hash]') {
+      return `/tx/${ query.hash || 'test-hash' }`;
+    }
+    if (pathname === '/clusters/[name]') {
+      return `/clusters/${ query.name || 'test-cluster' }`;
+    }
+
+    return pathname || '/';
+  }),
+};

jest/mocks/svg.js

@@ -0,0 +1 @@
+module.exports = 'test-file-stub';

jest/mocks/usehooks.js

@@ -0,0 +1,12 @@
+module.exports = {
+  useClickAway: jest.fn(() => jest.fn()),
+  useEventListener: jest.fn(),
+  useLocalStorage: jest.fn(() => [ '', jest.fn() ]),
+  useSessionStorage: jest.fn(() => [ '', jest.fn() ]),
+  useToggle: jest.fn(() => [ false, jest.fn() ]),
+  useDebounce: jest.fn((value) => value),
+  useThrottle: jest.fn((value) => value),
+  usePrevious: jest.fn(),
+  useCounter: jest.fn(() => ({ count: 0, increment: jest.fn(), decrement: jest.fn(), reset: jest.fn() })),
+  useCopyToClipboard: jest.fn(() => [ '', jest.fn() ]),
+};

lib/address/isEvmAddress.ts

@@ -0,0 +1,6 @@
+import { ADDRESS_REGEXP } from 'toolkit/utils/regexp';
+
+export function isEvmAddress(address: string): boolean {
+  if (!address) return false;
+  return ADDRESS_REGEXP.test(address.trim());
+}

lib/api/resources.ts

@@ -4,6 +4,8 @@ import type { AdminApiResourceName, AdminApiResourcePayload } from './services/a
 import { ADMIN_API_RESOURCES } from './services/admin';
 import { BENS_API_RESOURCES } from './services/bens';
 import type { BensApiResourceName, BensApiResourcePayload, BensApiPaginationFilters, BensApiPaginationSorting } from './services/bens';
+import { CLUSTERS_API_RESOURCES } from './services/clusters';
+import type { ClustersApiResourceName, ClustersApiResourcePayload, ClustersApiPaginationFilters, ClustersApiPaginationSorting } from './services/clusters';
 import { CONTRACT_INFO_API_RESOURCES } from './services/contractInfo';
 import type { ContractInfoApiPaginationFilters, ContractInfoApiResourceName, ContractInfoApiResourcePayload } from './services/contractInfo';
 import { GENERAL_API_RESOURCES } from './services/general';
@@ -30,6 +32,7 @@ import type { VisualizeApiResourceName, VisualizeApiResourcePayload } from './se
 export const RESOURCES = {
   admin: ADMIN_API_RESOURCES,
   bens: BENS_API_RESOURCES,
+  clusters: CLUSTERS_API_RESOURCES,
   contractInfo: CONTRACT_INFO_API_RESOURCES,
   general: GENERAL_API_RESOURCES,
   metadata: METADATA_API_RESOURCES,
@@ -53,6 +56,7 @@ export type ResourcePath = string;
 export type ResourcePayload<R extends ResourceName> =
 R extends AdminApiResourceName ? AdminApiResourcePayload<R> :
 R extends BensApiResourceName ? BensApiResourcePayload<R> :
+R extends ClustersApiResourceName ? ClustersApiResourcePayload<R> :
 R extends ContractInfoApiResourceName ? ContractInfoApiResourcePayload<R> :
 R extends GeneralApiResourceName ? GeneralApiResourcePayload<R> :
 R extends MetadataApiResourceName ? MetadataApiResourcePayload<R> :
@@ -89,6 +93,7 @@ export type ResourceErrorAccount<T> = ResourceError<{ errors: T }>;
 /* eslint-disable @stylistic/indent */
 export type PaginationFilters<R extends ResourceName> =
 R extends BensApiResourceName ? BensApiPaginationFilters<R> :
+R extends ClustersApiResourceName ? ClustersApiPaginationFilters :
 R extends GeneralApiResourceName ? GeneralApiPaginationFilters<R> :
 R extends ContractInfoApiResourceName ? ContractInfoApiPaginationFilters<R> :
 R extends TacOperationLifecycleApiResourceName ? TacOperationLifecycleApiPaginationFilters<R> :
@@ -100,6 +105,7 @@ export const SORTING_FIELDS = [ 'sort', 'order' ];
 /* eslint-disable @stylistic/indent */
 export type PaginationSorting<R extends ResourceName> =
 R extends BensApiResourceName ? BensApiPaginationSorting<R> :
+R extends ClustersApiResourceName ? ClustersApiPaginationSorting :
 R extends GeneralApiResourceName ? GeneralApiPaginationSorting<R> :
 never;
 /* eslint-enable @stylistic/indent */

lib/api/services/clusters.ts

@@ -0,0 +1,57 @@
+import type { ApiResource } from '../types';
+import type {
+  ClustersByAddressResponse,
+  ClusterByNameResponse,
+  ClustersLeaderboardResponse,
+  ClustersDirectoryResponse,
+  ClustersByAddressQueryParams,
+  ClusterByNameQueryParams,
+  ClustersLeaderboardQueryParams,
+  ClustersDirectoryQueryParams,
+  ClusterByIdQueryParams,
+  ClusterByIdResponse,
+} from 'types/api/clusters';
+
+export const CLUSTERS_API_RESOURCES = {
+  get_clusters_by_address: {
+    path: '/v1/trpc/names.getNamesByOwnerAddress',
+    pathParams: [],
+  },
+  get_cluster_by_name: {
+    path: '/v1/trpc/names.get',
+    pathParams: [],
+  },
+  get_cluster_by_id: {
+    path: '/v1/trpc/clusters.getClusterById',
+    pathParams: [],
+  },
+  get_leaderboard: {
+    path: '/v1/trpc/names.leaderboard',
+    pathParams: [],
+  },
+  get_directory: {
+    path: '/v1/trpc/names.search',
+    pathParams: [],
+  },
+} satisfies Record<string, ApiResource>;
+
+export type ClustersApiResourceName = `clusters:${ keyof typeof CLUSTERS_API_RESOURCES }`;
+
+export type ClustersApiResourcePayload<R extends ClustersApiResourceName> =
+  R extends 'clusters:get_clusters_by_address' ? ClustersByAddressResponse :
+    R extends 'clusters:get_cluster_by_name' ? ClusterByNameResponse :
+      R extends 'clusters:get_cluster_by_id' ? ClusterByIdResponse :
+        R extends 'clusters:get_leaderboard' ? ClustersLeaderboardResponse :
+          R extends 'clusters:get_directory' ? ClustersDirectoryResponse :
+            never;
+
+export type ClustersApiQueryParams<R extends ClustersApiResourceName> =
+  R extends 'clusters:get_clusters_by_address' ? ClustersByAddressQueryParams :
+    R extends 'clusters:get_cluster_by_name' ? ClusterByNameQueryParams :
+      R extends 'clusters:get_cluster_by_id' ? ClusterByIdQueryParams :
+        R extends 'clusters:get_leaderboard' ? ClustersLeaderboardQueryParams :
+          R extends 'clusters:get_directory' ? ClustersDirectoryQueryParams :
+            never;
+
+export type ClustersApiPaginationFilters = never;
+export type ClustersApiPaginationSorting = never;

lib/api/types.ts

@@ -1,4 +1,7 @@
-export type ApiName = 'general' | 'admin' | 'bens' | 'contractInfo' | 'metadata' | 'multichain' | 'rewards' | 'stats' | 'tac' | 'userOps' | 'visualize';
+export type ApiName =
+'general' | 'admin' | 'bens' | 'contractInfo' | 'clusters' |
+'metadata' | 'multichain' | 'rewards' | 'stats' | 'tac' |
+'userOps' | 'visualize';
 
 export interface ApiResource {
   path: string;