indexedex-ui-refactor

name	indexedex-ui-refactor
description	Indexedex frontend deployment-environment and artifact-registry refactor. Use when switching the UI between live Sepolia and local supersim_sepolia, updating address artifact loading, changing wagmi transports, or touching the deployment environment toggle, address registry, or chain-id resolution helpers.

Indexedex UI Refactor

This skill documents the frontend refactor that made the UI environment-aware across live Sepolia and the local SuperSim rehearsal.

Use This Skill For

• adding or changing deployment environments
• updating address artifact imports or registry wiring
• fixing chain-id to artifact resolution
• adjusting wagmi transport selection for local versus live networks
• reviewing pages that consume deployment artifacts and token lists

Core Architecture

The frontend now has one central artifact registry and one central deployment-environment state.

Single Source of Truth

• frontend/app/addresses/index.ts owns the artifact registry.
• frontend/app/lib/addressArtifacts.ts owns chain-id resolution and typed access to bundles.
• frontend/app/lib/deploymentEnvironment.tsx owns the deployment-environment type, context contract, storage key, and toggle UI.
• frontend/app/providers.tsx owns persisted environment state and wagmi transport switching.

Do not scatter direct artifact JSON imports across feature pages when the data belongs in the shared registry.

Deployment Environment Model

Current supported environments:

type DeploymentEnvironment = 'sepolia' | 'supersim_sepolia'

Rules:

• Default to supersim_sepolia unless NEXT_PUBLIC_DEFAULT_DEPLOYMENT_ENVIRONMENT overrides it.
• Persist the current environment in localStorage under indexedex:deployment-environment.
• Keep environment switching in provider and context code, not in individual pages.

Artifact Registry Rules

In frontend/app/addresses/index.ts:

• Import each environment's JSON artifacts once.
• Build bundles with buildBundle(...) so every list is normalized consistently.
• Stamp chainId into normalized platform and token-list entries.
• Keep the registry keyed by environment and canonical chain id.

Canonical chain ids:

• 11155111 for Ethereum Sepolia
• 84532 for Base Sepolia

When adding a new artifact category, update:

1. the import set in frontend/app/addresses/index.ts
2. the ArtifactBundle type
3. buildBundle(...)
4. the registry entry for each supported environment

Chain Resolution Rules

In frontend/app/lib/addressArtifacts.ts:

• Treat canonical artifacts as Sepolia and Base Sepolia bundles.
• Resolve 31337 and 1337 to Sepolia artifacts for local development.
• Resolve chain id 8453 to Base Sepolia artifacts only when the selected environment is supersim_sepolia.
• Throw explicit errors for unsupported chain ids or missing bundles.

Do not duplicate ad hoc chain-id fallback logic in pages or hooks.

Provider Rules

In frontend/app/providers.tsx:

• Keep wagmi config dependent on the selected deployment environment.
• For supersim_sepolia, route Sepolia traffic to NEXT_PUBLIC_LOCAL_RPC_URL and Base Sepolia traffic to NEXT_PUBLIC_BASE_RPC_URL.
• For live sepolia, route Sepolia and Base Sepolia traffic to their normal RPC URLs.
• Update the in-memory default artifact environment whenever the UI environment changes.

This prevents the wallet layer and artifact lookup layer from drifting out of sync.

UI Pattern

The environment switcher is intentionally lightweight:

• fixed overlay
• explicit label
• simple select control
• no page-specific copies of the same control

Keep this as a shared control instead of re-implementing environment selection per page.

Refactor Checklist

When changing deployment-environment behavior:

1. Update the environment union and registry first.
2. Confirm chain-id resolution still maps local chains to the intended artifact bundle.
3. Confirm provider transports match the selected environment.
4. Confirm localStorage persistence still restores the previous selection.
5. Confirm both sepolia and supersim_sepolia render with the expected artifacts.

Source Files

• frontend/app/addresses/index.ts
• frontend/app/lib/addressArtifacts.ts
• frontend/app/lib/deploymentEnvironment.tsx
• frontend/app/providers.tsx

What To Avoid

• page-level direct imports of deployment JSON that bypass the shared registry
• duplicate environment state in multiple hooks or pages
• inconsistent chain-id mapping between wagmi transports and artifact lookup
• defaulting to live RPCs while still reading local supersim artifacts