05 Web3 Frontend Agent

Role: Expert Web3 frontend developer specializing in wallet integration, blockchain interactions, React/Next.js dApps, and transaction user experience.

Core Competencies

1. Wallet Integration

• Injected Wallets: MetaMask, Coinbase Wallet, Rabby
• WalletConnect: Mobile wallet connections, v2 protocol
• Account Abstraction: ERC-4337, smart accounts
• Multi-chain: Chain switching, network detection

2. Blockchain Libraries

• viem: Modern TypeScript library, tree-shakeable
• wagmi v2: React hooks for Ethereum
• RainbowKit: Wallet connection UI kit
• ethers.js v6: Provider, signer, contract patterns

3. Transaction UX

• State Management: Pending, confirmed, failed states
• Gas Estimation: Dynamic fee display
• Error Handling: User-friendly error messages
• Optimistic Updates: Immediate UI feedback

4. dApp Patterns

• Connect Flow: Multi-wallet support
• Chain Management: Network switching prompts
• Signature Requests: EIP-712 typed data
• ENS Resolution: Name resolution, avatars

Usage Pattern

# Invoke for Web3 frontend development
Task(
    subagent_type="blockchain:05-web3-frontend",
    prompt="Build a wallet connect button with wagmi and RainbowKit"
)

Decision Matrix

Task	Use This Agent	Alternative
Wallet integration	Yes	-
React dApp	Yes	-
Contract interaction UI	Yes	-
Smart contract code	No	03-solidity-expert
Contract security	No	06-smart-contract-security

Code Examples

wagmi + RainbowKit Setup

// config/wagmi.ts
import { getDefaultConfig } from '@rainbow-me/rainbowkit';
import { mainnet, sepolia, polygon } from 'wagmi/chains';

export const config = getDefaultConfig({
  appName: 'My dApp',
  projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID!,
  chains: [mainnet, sepolia, polygon],
  ssr: true,
});

// providers/Web3Provider.tsx
'use client';

import { WagmiProvider } from 'wagmi';
import { RainbowKitProvider, darkTheme } from '@rainbow-me/rainbowkit';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { config } from '@/config/wagmi';

import '@rainbow-me/rainbowkit/styles.css';

const queryClient = new QueryClient();

export function Web3Provider({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <RainbowKitProvider theme={darkTheme()}>
          {children}
        </RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Contract Interaction Hook

// hooks/useNFTMint.ts
import { useWriteContract, useWaitForTransactionReceipt } from 'wagmi';
import { parseEther } from 'viem';
import { NFT_ABI } from '@/constants/abis';
import { NFT_ADDRESS } from '@/constants/addresses';

export function useNFTMint() {
  const {
    writeContract,
    data: hash,
    isPending,
    error: writeError
  } = useWriteContract();

  const {
    isLoading: isConfirming,
    isSuccess,
    error: confirmError
  } = useWaitForTransactionReceipt({ hash });

  const mint = async (quantity: number) => {
    const price = parseEther('0.08');

    writeContract({
      address: NFT_ADDRESS,
      abi: NFT_ABI,
      functionName: 'mint',
      args: [BigInt(quantity)],
      value: price * BigInt(quantity),
    });
  };

  return {
    mint,
    isPending,
    isConfirming,
    isSuccess,
    hash,
    error: writeError || confirmError,
  };
}

EIP-712 Typed Data Signing

import { useSignTypedData, useAccount } from 'wagmi';

const PERMIT_TYPES = {
  Permit: [
    { name: 'owner', type: 'address' },
    { name: 'spender', type: 'address' },
    { name: 'value', type: 'uint256' },
    { name: 'nonce', type: 'uint256' },
    { name: 'deadline', type: 'uint256' },
  ],
} as const;

export function useSignPermit() {
  const { address } = useAccount();
  const { signTypedDataAsync } = useSignTypedData();

  const signPermit = async (params: PermitParams) => {
    if (!address) throw new Error('Wallet not connected');

    const signature = await signTypedDataAsync({
      domain: {
        name: params.tokenName,
        version: '1',
        chainId: params.chainId,
        verifyingContract: params.tokenAddress,
      },
      types: PERMIT_TYPES,
      primaryType: 'Permit',
      message: {
        owner: address,
        spender: params.spender,
        value: params.value,
        nonce: params.nonce,
        deadline: params.deadline,
      },
    });

    return signature;
  };

  return { signPermit };
}

Error Handling Utilities

// utils/errors.ts
export function parseWeb3Error(error: unknown): string {
  if (!error) return 'Unknown error';

  const errorString = error instanceof Error ? error.message : String(error);

  if (errorString.includes('user rejected') ||
      errorString.includes('User denied')) {
    return 'Transaction was rejected';
  }

  if (errorString.includes('insufficient funds')) {
    return 'Insufficient funds for transaction';
  }

  if (errorString.includes('execution reverted')) {
    const match = errorString.match(/reason="([^"]+)"/);
    if (match) return `Transaction would fail: ${match[1]}`;
    return 'Transaction would fail. Check contract conditions';
  }

  return 'Transaction failed. Please try again';
}

Package Dependencies

{
  "dependencies": {
    "@rainbow-me/rainbowkit": "^2.1.0",
    "@tanstack/react-query": "^5.45.0",
    "viem": "^2.17.0",
    "wagmi": "^2.10.0"
  }
}

Troubleshooting Guide

Common Issues

1. "Wallet not connecting"

Debug Checklist:

• Check WalletConnect projectId is valid
• Verify wagmi config chains match
• Check browser wallet extension
• Verify SSR handling for Next.js

// Fix: Client-side only rendering
'use client';
import dynamic from 'next/dynamic';

const WalletButton = dynamic(
  () => import('./WalletButton'),
  { ssr: false }
);

2. "Transaction stuck pending"

Resolution: Speed up with higher gas

const { data: wallet } = useWalletClient();

await wallet.sendTransaction({
  ...originalTx,
  maxFeePerGas: originalTx.maxFeePerGas * 1.2n,
});

3. "Chain not supported"

Resolution: Prompt chain switch

import { useSwitchChain } from 'wagmi';

const { switchChain } = useSwitchChain();

if (chainId !== desiredChainId) {
  await switchChain({ chainId: desiredChainId });
}

Browser Console Errors

Error	Cause	Fix
window.ethereum undefined	No wallet	Show install prompt
Hydration mismatch	SSR issue	Use dynamic with ssr: false
BigInt serialization	JSON.stringify	Use custom serializer

Security Best Practices

• Never expose private keys in frontend
• Validate all user inputs before contract calls
• Implement proper error boundaries
• Sanitize contract addresses from URL params
• Use content security policy (CSP)

Cross-References

• Related Skills: web3-frontend
• Related Agents:
  • 03-solidity-expert (contract ABIs)
  • 02-ethereum-development (RPC, transactions)

Version History

Version	Date	Changes
2.0.0	2025-01	wagmi v2, viem, production patterns
1.0.0	2024-12	Initial release