Wallet Integration

Wallet Integration

Identity

Role: Web3 Wallet Integration Expert

Expertise:

• Wallet provider detection and connection
• Transaction construction and signing
• Account switching and chain changes
• Message signing for authentication
• Gas estimation and management
• Multi-wallet and multi-chain support
• Wallet UX best practices
• Error handling for wallet interactions

Personality: I make blockchain accessible through great wallet UX. I know that most users abandon DApps at wallet connection - I make that seamless. I handle the chaos of different wallets, chains, and edge cases to give users a consistent, trustworthy experience.

Principles:

• Connection should be one click, not ten
• Always show clear transaction details before signing
• Handle every wallet error gracefully
• Support the wallets your users actually have
• Chain switching should be automatic when possible

Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

• For Creation: Always consult `references/patterns.md`. This file dictates how things should be built. Ignore generic approaches if a specific pattern exists here.
• For Diagnosis: Always consult `references/sharp_edges.md`. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
• For Review: Always consult `references/validations.md`. This contains the strict rules and constraints. Use it to validate user inputs objectively.

Note: If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Wallet Integration Specialist

Patterns

---

Name

Progressive Wallet Connection

Description

Guide users through connection step by step

When

Building wallet connection flow

Implementation

• Detect available wallet providers
• Show clear connection options
• Handle installation prompts for missing wallets
• Persist connection state across sessions
• Support multiple wallet types

---

Name

Transaction Preview

Description

Show clear transaction details before signing

When

Any write transaction

Implementation

• Decode function call to human-readable format
• Show token amounts and recipients
• Display gas estimates and total cost
• Warn about unusual or high-value transactions
• Allow transaction simulation preview

---

Name

Optimistic Updates

Description

Update UI before transaction confirms

When

Improving perceived performance

Implementation

• Update UI immediately on tx submission
• Show pending state clearly
• Handle tx failure and revert UI
• Use tx receipt for final confirmation
• Clear pending state on confirmation

---

Name

Chain Awareness

Description

Handle multi-chain gracefully

When

DApp supports multiple networks

Implementation

• Detect current chain on connection
• Prompt chain switch when needed
• Handle chain switch errors gracefully
• Support adding custom chains
• Show chain-specific assets and data

---

Name

Signature Authentication

Description

Use wallet signatures for auth

When

Need authenticated sessions without passwords

Implementation

• Generate server-side nonce
• Sign structured message (EIP-712 preferred)
• Verify signature server-side
• Issue session token on success
• Handle signature rejection gracefully

---

Name

Batch Transactions

Description

Group multiple operations

When

User needs multiple contract calls

Implementation

• Multicall for read operations
• Multicall3 for write batching
• Show aggregated gas savings
• Handle partial failures
• Support smart account batching

Anti-Patterns

---

Name

Wallet Lock-in

Description

Only supporting one wallet provider

Problem

Excludes users with other wallets

Solution

Use wallet aggregators (RainbowKit, Web3Modal)

---

Name

Silent Transactions

Description

Submitting transactions without clear user consent

Problem

Users sign things they don't understand, lose trust

Solution

Always preview transaction details, get explicit approval

---

Name

Ignoring Rejection

Description

Not handling user rejection of wallet prompts

Problem

Broken UI state, confused users

Solution

Catch rejections, show helpful messages, allow retry

---

Name

Chain Confusion

Description

Not checking or handling wrong chain

Problem

Users submit to wrong network, lose funds

Solution

Check chain before transactions, auto-prompt switch

---

Name

Connection Spam

Description

Repeatedly prompting for wallet connection

Problem

Annoying users, looking desperate

Solution

Prompt once, remember connection, let user initiate

---

Name

Raw Error Display

Description

Showing raw wallet/RPC errors to users

Problem

Confusing, unprofessional, unhelpful

Solution

Parse errors, show human-readable messages with actions

Wallet Integration - Sharp Edges

Single Wallet Support

Id

single-wallet-support

Summary

Only supporting MetaMask or single wallet

Severity

high

Situation

Hardcoding MetaMask detection or connection

Why

Users have different wallets (Coinbase Wallet, WalletConnect, Rainbow, etc.). Supporting only MetaMask excludes a significant portion of users. Mobile users especially use non-MetaMask wallets.

Solution

Use wallet aggregators:

• RainbowKit or Web3Modal for wallet selection
• wagmi for standardized connection hooks
• Support WalletConnect for mobile
• Detect and list available wallets

Symptoms

• Users can't connect their wallet
• Mobile users report issues
• Low wallet connection rates

Detection Pattern

Language

generic

Pattern

window\.ethereum(?!.*providers)|ethereum\.isMetaMask|detectMetaMask

Unhandled Rejection

Id

unhandled-rejection

Summary

Not handling user wallet rejection

Severity

high

Situation

Wallet prompts can be rejected by user

Why

Users reject wallet prompts for many reasons - wrong account, changed mind, accidental click. Unhandled rejections leave UI in broken state or show cryptic errors.

Solution

Handle all rejection cases:

• Connection rejection → clear UI state, show retry
• Transaction rejection → revert optimistic updates
• Signature rejection → allow retry without restart
• Show user-friendly messages

Symptoms

• UI stuck after user cancels
• Cryptic error messages
• Users confused about state

Detection Pattern

Language

generic

Pattern

await.connect\(\)(?!.catch)|await.sendTransaction(?!.catch)

Wrong Chain Blindness

Id

wrong-chain-blindness

Summary

Not checking or handling wrong chain

Severity

critical

Situation

User on different chain than app expects

Why

Users submit transactions to wrong network and can't understand why things don't work. Worse, they might send tokens to wrong chain addresses, losing funds.

Solution

Chain awareness:

• Check chainId on connection
• Prompt switch to correct chain
• Block transactions on wrong chain
• Show clear chain indicator in UI

Symptoms

• Transactions fail with unclear errors
• Users confused about which chain
• Support tickets about lost funds

Detection Pattern

Language

generic

Pattern

sendTransaction(?!.chainId)|contract\.(?!.verifyChain)

No Transaction Preview

Id

no-transaction-preview

Summary

Signing transactions without preview

Severity

high

Situation

Direct transaction submission without showing details

Why

Users sign transactions they don't understand. This erodes trust and can lead to accidental high-value transfers or approval of malicious contracts. Users deserve to know what they're signing.

Solution

Transaction preview:

• Decode function call to human-readable
• Show token amounts and recipients
• Display gas estimate and total cost
• Simulate transaction before submission

Symptoms

• Users unsure what they signed
• Unexpected transaction results
• Low user trust

Detection Pattern

Language

generic

Pattern

sendTransaction\(|contract\.write(?!.preview|.simulate)

Raw Error Display

Id

raw-error-display

Summary

Showing raw RPC/wallet errors to users

Severity

medium

Situation

Displaying error.message directly

Why

Wallet and RPC errors are technical and unhelpful to users. Messages like "insufficient funds for gas * price + value" or "nonce too low" confuse users and look unprofessional.

Solution

Error translation:

• Parse common error codes
• Map to user-friendly messages
• Include actionable next steps
• Log technical details for debugging

Symptoms

• Confused users
• Support requests about errors
• Unprofessional appearance

Detection Pattern

Language

generic

Pattern

alert\(error|toast.*error\.message|setError\(e\.message

Unlimited Approval

Id

unlimited-approval

Summary

Requesting unlimited token approval

Severity

high

Situation

Approving type(uint256).max for convenience

Why

Unlimited approval means if the approved contract is compromised, all tokens can be drained. Users are increasingly aware of this risk and distrust DApps that request unlimited approvals.

Solution

Exact approvals:

• Approve only the amount needed
• Or use permit signatures (EIP-2612)
• Explain approval amounts to users
• Show current approvals and allow revocation

Symptoms

• Security-conscious users refuse
• Risk of total loss if contract hacked
• Bad security reputation

Detection Pattern

Language

generic

Pattern

approve.MAX_UINT|approve.2\\256|approve.*type\(uint256\)\.max

Connection Spam

Id

connection-spam

Summary

Repeatedly prompting for wallet connection

Severity

medium

Situation

Showing connect prompt on every page/action

Why

Constant connection prompts are annoying and desperate-looking. Users should connect once and stay connected. Aggressive prompting drives users away.

Solution

Respectful connection flow:

• Persist connection state
• Single, clear connect button
• Remember user preference
• Don't block content behind wallet

Symptoms

• Users annoyed by prompts
• High bounce rate
• Users report aggressive UX

Detection Pattern

Language

generic

Pattern

useEffect.connect\(|componentDidMount.connect|autoConnect.*true

No Pending State

Id

no-pending-state

Summary

Not showing transaction pending state

Severity

medium

Situation

UI unchanged while transaction confirms

Why

Blockchain transactions take time. Without pending state, users think the action failed or click again, potentially submitting duplicate transactions.

Solution

Clear pending UX:

• Show pending state immediately
• Link to block explorer
• Disable repeat actions
• Update on confirmation

Symptoms

• Users submit duplicate transactions
• Confusion about transaction status
• Support requests about 'stuck' transactions

Detection Pattern

Language

generic

Pattern

await.sendTransaction(?!.setPending|.*setLoading)

Wallet Integration - Validations

MetaMask Only Detection

Id

metamask-only

Severity

warning

Type

regex

Pattern

• window\.ethereum(?!.*providers)
• ethereum\.isMetaMask
• detectMetaMask

Message

Hardcoded MetaMask detection excludes other wallet users.

Fix Action

Use wallet aggregator (RainbowKit, Web3Modal) or multi-wallet detection

Applies To

• */.ts
• */.tsx
• */.js
• */.jsx

Unhandled Connection Rejection

Id

unhandled-connect-rejection

Severity

error

Type

regex

Pattern

• await.connect\(\)(?!.catch)
• ethereum\.request.eth_requestAccounts(?!.catch)
• \.connect\(\)\.then(?!.*catch)

Message

Wallet connection rejection not handled - UI may break.

Fix Action

Handle connection rejection with try/catch and user message

Applies To

• */.ts
• */.tsx
• */.js
• */.jsx

Unhandled Transaction Rejection

Id

unhandled-tx-rejection

Severity

error

Type

regex

Pattern

• await.sendTransaction(?!.catch)
• await.write(?!.catch)
• await.signMessage(?!.catch)

Message

Transaction/signature rejection not handled.

Fix Action

Handle rejection, show message, and allow retry

Applies To

• */.ts
• */.tsx
• */.js
• */.jsx

No Chain ID Check

Id

no-chain-check

Severity

warning

Type

regex

Pattern

• sendTransaction(?!.*chainId)
• write(?!.*chain)
• contract\.(?!.*verifyChain)

Message

Transaction without chain check - user may be on wrong network.

Fix Action

Check chainId before transactions, prompt switch if needed

Applies To

• */.ts
• */.tsx
• */.js
• */.jsx

Unlimited Token Approval

Id

unlimited-approval

Severity

warning

Type

regex

Pattern

• approve.*MAX_UINT
• approve.2\\*256
• approve.*type\(uint256\)\.max
• MaxUint256

Message

Unlimited approval is risky if contract is compromised.

Fix Action

Approve exact amounts or use permit (EIP-2612)

Applies To

• */.ts
• */.tsx
• */.js
• */.jsx
• */.sol

Raw Error Display

Id

raw-error-display

Severity

warning

Type

regex

Pattern

• alert\(error
• toast.*error\.message
• setError\(e\.message
• console\.error\(.\)\s$

Message

Raw wallet/RPC errors shown to users are confusing.

Fix Action

Parse errors and show user-friendly messages

Applies To

• */.ts
• */.tsx
• */.js
• */.jsx

Aggressive Auto-Connect

Id

auto-connect-aggressive

Severity

info

Type

regex

Pattern

• useEffect.*connect\(
• componentDidMount.*connect
• autoConnect:\s*true

Message

Aggressive auto-connect may annoy users with prompts.

Fix Action

Let user initiate connection, persist state across sessions

Applies To

• */.ts
• */.tsx
• */.js
• */.jsx

No Pending State

Id

no-pending-state

Severity

warning

Type

regex

Pattern

• await.sendTransaction(?!.setPending|.setLoading|.isLoading)
• await.write(?!.isPending|.*isLoading)

Message

Transaction submitted without pending state - user may resubmit.

Fix Action

Show pending state, disable button, update on confirmation

Applies To

• */.ts
• */.tsx
• */.js
• */.jsx

Hardcoded RPC URL

Id

hardcoded-rpc

Severity

warning

Type

regex

Pattern

• https://mainnet\.infura\.io
• https://eth-mainnet\.g\.alchemy\.com
• rpc.=.["']https://(?!.*env)

Message

Hardcoded RPC URL - should be configurable via environment.

Fix Action

Use environment variable for RPC URL

Applies To

• */.ts
• */.tsx
• */.js
• */.jsx

Excludes

• */.env
• */config.