coinbase / coinbase/onchainkit

Add built-in "Wrong Network" guard and switch prompt for Base networks

Open
#2,571 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
1k
Forks
520
Avg merge
32m
Merged PRs (30d)
2

Description

Acceptance criteria:
- Wrong-network state can be detected without custom app logic.
- Works correctly for Base and Base Sepolia.
- Provides clear UX when network switching is supported and when it is not.
- Includes at least one test covering detection and switch request behavior.

Steps to reproduce:
1. Create an app using OnchainKit wallet components.
2. Configure the app to target Base or Base Sepolia.
3. Connect a wallet while the wallet is set to a different network (e.g., Ethereum mainnet).
4. Observe that wrong-network handling must be implemented manually by the app.

Description:
Many apps built with OnchainKit need to handle the "wrong network" scenario when a user connects a wallet on an unsupported chain. Currently, developers must implement this logic themselves, leading to duplicated code and inconsistent UX across apps in the Base ecosystem.

Providing a built-in solution would improve developer experience and encourage consistent network handling patterns.

Proposed solution:
- Expose a hook (e.g. `useNetworkGuard`) that detects when the connected chain is not allowed.
- Optionally provide a small UI component for wrong-network messaging.
- Support triggering a network switch request when the wallet allows it.
- Document the recommended pattern in the Wallet documentation.

Expected behavior:
- The SDK clearly indicates when the user is connected to an unsupported network.
- The app can easily display which network is currently selected and which is expected.
- A “Switch network” action is available when supported by the wallet.
- If switching is unavailable or rejected, a friendly fallback message is shown.

### Describe alternatives you've considered.

_No response_

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the OnchainKit wallet components and the Wallet documentation mentioned in the issue, then identify the existing network and switch-request entry points. Add detection and switch behavior for Base and Base Sepolia, document the recommended pattern, and run a test covering wrong-network detection and switch requests, including unsupported or rejected switching.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript
Domain
developer-experience, frontend, web-dev
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.