coinbase / coinbase/onchainkit

Feature Request: Add built-in network mismatch guard with customizable UX for transaction flows

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

Description

### Describe the solution you'd like

OnchainKit applications frequently require users to be connected to a specific network (e.g. Base Mainnet or Base Sepolia) before performing actions such as sending transactions or signing messages. Today, developers must manually detect network mismatches and implement their own UI/logic to handle them.

A first-class network mismatch guard would reduce boilerplate and provide a consistent, user-friendly experience across OnchainKit apps.

## Problem Description
Currently, when a user is connected to the wrong network:
- Transactions may fail with unclear wallet or RPC errors
- Developers must manually check `chainId` before every action
- Each app implements its own “Please switch network” UX

### Describe alternatives you've considered.

### Proposed Solution
- Add a first-class `TransactionGuard` component and/or hook to OnchainKit.
- Detect wallet `chainId` and compare it against a required or supported network list.
- Block execution of onchain actions when the network does not match.
- Provide a default UX to prompt users to switch networks, including optional support for `wallet_switchEthereumChain`.
- Allow developers to fully customize the guard behavior and UI via render props or hooks.
- Integrate the guard with existing OnchainKit provider configuration.

### Acceptance Criteria
- Network mismatches are detected before any onchain action is executed.
- Default guard behavior works with minimal configuration.
- Developers can override or customize the mismatch handling UX.
- No breaking changes for existing OnchainKit integrations.
- Docu

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.