Implement guided, validated chain-switching UX

[Lakes41]

Difficulty: Advanced | Type: Feature / Architecture

Background: NEXT_PUBLIC_WALLET_CHAINS restricts supported chains to a subset of mainnet, base, sepolia, validated by lib/wallet/config.ts.

Problem: If a user's wallet is connected to a chain outside the configured NEXT_PUBLIC_WALLET_CHAINS set (e.g. connected to Polygon while the app only supports mainnet/base), the app's behavior in that scenario isn't described — it likely either silently misbehaves or shows a generic wagmi error.

Expected Outcome: The app detects an unsupported connected chain and guides the user through switching to a supported one via wagmi's switchChain, with a clear explanatory UI rather than a silent failure or cryptic error.

Suggested Implementation: Add a chain-mismatch detector (comparing wagmi's active chainId against the configured supported set from lib/wallet/config.ts) rendered as a persistent banner with a "Switch to " button calling useSwitchChain(), handling the case where the wallet doesn't support programmatic switching (fallback to manual instructions).

Acceptance Criteria:

• Connecting on an unsupported chain shows a clear banner naming the required chain(s).
• "Switch" button successfully changes chain via wagmi where supported.
• Manual-switch instructions are shown for wallets/chains where programmatic switching isn't available.
• Covered by a test simulating an unsupported active chain.

Likely Affected Files/Directories: lib/wallet/config.ts, lib/wallet/providers.tsx, components/wallet/connect-button.tsx

Labels: feature, architecture, GrantFox OSS, Maybe Rewarded, Official Campaign | FWC26

[Lixzon]

Approach:

1. Add a chain-mismatch detector comparing wagmi's active chainId (via useChainId or useAccount) against the supported set already defined in lib/wallet/config.ts — no new source of truth, just reusing the existing config.
2. Render a persistent banner (not a dismissible toast, since staying on an unsupported chain is a persistent state, not a one-off event) naming the required chain(s) whenever there's a mismatch.
3. Wire the "Switch to " button to useSwitchChain(). Where the connected wallet doesn't support programmatic switching (switchChain throwing or the connector not supporting it), fall back to manual instructions (chain name + expected chain ID) rather than a silent failure or raw wagmi error.
4. Banner logic lives close to components/wallet/connect-button.tsx / lib/wallet/providers.tsx so it reacts to connection/chain changes in real time, not just on initial connect.
5. Will add a test simulating an active unsupported chain to confirm the banner renders, the switch button calls switchChain correctly, and the manual-instruction fallback path is covered separately.

Will open a PR against a dedicated branch for this once ready.

[grantfox-oss]

🦊 GrantFox — @Lixzon has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #246)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@Lixzon's PR #362 was approved and merged by @Lakes41.

🏆 @Lixzon: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (484 total points). Track your full progress on GrantFox.

👏 Great work, @Lixzon! Keep contributing to Adamantine-guild.