skillbase/web3-wagmi-viem

## Configuration

```typescript

import { http, createConfig } from "wagmi"

import { mainnet, sepolia, arbitrum } from "wagmi/chains"

import { injected, walletConnect, coinbaseWallet } from "wagmi/connectors"

export const config = createConfig({

  chains: [mainnet, arbitrum, sepolia],

  connectors: [

    injected(),

    walletConnect({ projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID! }),

    coinbaseWallet({ appName: "MyDApp" }),

  ],

  transports: {

    [mainnet.id]: http(),

    [arbitrum.id]: http(),

    [sepolia.id]: http(),

  },

})

```

- Define all supported chains explicitly.

- Include multiple connectors for wallet diversity — users have different wallets.

- Use environment variables for API keys.

## Wallet connection

Handle all connection states:

```typescript

"use client"

import { useAccount, useConnect, useDisconnect, useSwitchChain } from "wagmi"

function ConnectWallet() {

  const { address, isConnected, chain } = useAccount()

  const { connect, connectors, isPending, error } = useConnect()

  const { disconnect } = useDisconnect()

  const { switchChain } = useSwitchChain()

  if (isConnected) {

    return (

      <div>

        <span>{address}</span>

        {chain?.unsupported && (

          <Button onClick={() => switchChain({ chainId: mainnet.id })}>

            Switch to Mainnet

          </Button>

        )}

        <Button variant="outline" onClick={() => disconnect()}>Disconnect</Button>

      </div>

    )

  }

  return (

    <div className="flex flex-col gap-2">

      {connectors.map((connector) => (

        <Button key={connector.uid} onClick={() => connect({ connector })} disabled={isPending}>

          {isPending ? "Connecting..." : connector.name}

        </Button>

      ))}

      {error && <p className="text-sm text-destructive">{error.message}</p>}

    </div>

  )

}

```

- Show current connection state.

- Handle unsupported chain with a switch prompt.

- Show connector name from the connector object.

- Disable buttons during pending operations — prevents duplicate wallet popups.

## Contract reads

Use `useReadContract` with ABIs defined as `const` for full type inference — viem maps ABI definitions to TypeScript types, so `as const` gives you type-safe args and return values at compile time:

```typescript

const erc20Abi = [

  {

    name: "balanceOf",

    type: "function",

    stateMutability: "view",

    inputs: [{ name: "account", type: "address" }],

    outputs: [{ name: "", type: "uint256" }],

  },

] as const

function TokenBalance({ token, account }: { readonly token: Address; readonly account: Address }) {

  const { data: balance, isLoading, error } = useReadContract({

    address: token,

    abi: erc20Abi,

    functionName: "balanceOf",

    args: [account],

  })

  if (isLoading) return <Skeleton className="h-6 w-24" />

  if (error) return <span className="text-destructive">Failed to load balance</span>

  return <span>{formatUnits(balance ?? 0n, 18)} tokens</span>

}

```

- Handle `isLoading` and `error` states in UI.

- Use `formatUnits`/`parseUnits` for token decimals — `Number()` on BigInt silently loses precision for values > 2^53, which means wrong balances displayed to users.

- Use `useReadContracts` (plural) for batched multicall reads.

## Contract writes and transaction lifecycle

Every write: idle → pending approval → pending confirmation → success/error:

```typescript

import { useWriteContract, useWaitForTransactionReceipt } from "wagmi"

import { parseUnits } from "viem"

function TransferToken({ token }: { readonly token: Address }) {

  const [to, setTo] = useState("")

  const [amount, setAmount] = useState("")

  const { writeContract, data: hash, isPending: isApproving, error: writeError } = useWriteContract()

  const { isLoading: isConfirming, isSuccess: isConfirmed, error: receiptError } =

    useWaitForTransactionReceipt({ hash })

  function handleSubmit(e: React.FormEvent) {

    e.preventDefault()

    writeContract({

      address: token,

      abi: erc20Abi,

      functionName: "transfer",

      args: [to as Address, parseUnits(amount, 18)],

    })

  }

  return (

    <form onSubmit={handleSubmit}>

      <Input placeholder="Recipient address" value={to} onChange={(e) => setTo(e.target.value)} />

      <Input placeholder="Amount" value={amount} onChange={(e) => setAmount(e.target.value)} />

      <Button type="submit" disabled={isApproving || isConfirming}>

        {isApproving ? "Confirm in wallet..." : isConfirming ? "Waiting for confirmation..." : "Transfer"}

      </Button>

      {writeError && <Alert variant="destructive"><AlertDescription>{getErrorMessage(writeError)}</AlertDescription></Alert>}

      {receiptError && <Alert variant="destructive"><AlertDescription>Transaction failed on-chain</AlertDescription></Alert>}

      {isConfirmed && <Alert><AlertDescription>Transfer confirmed!</AlertDescription></Alert>}

    </form>

  )

}

```

**Transaction state machine:**

1. **Idle** → button says "Transfer"

2. **Pending approval** (`isPending`) → "Confirm in wallet...", disabled

3. **Pending confirmation** (`isLoading`) → "Waiting for confirmation...", disabled

4. **Success** → show success message

5. **Error** → show error at the step where it failed

## Error handling

```typescript

import { BaseError, ContractFunctionRevertedError, UserRejectedRequestError } from "viem"

function getErrorMessage(error: Error): string {

  if (error instanceof BaseError) {

    if (error.walk((e) => e instanceof UserRejectedRequestError)) {

      return "Transaction cancelled by user"

    }

    const revertError = error.walk(

      (e) => e instanceof ContractFunctionRevertedError,

    ) as ContractFunctionRevertedError | null

    if (revertError?.data?.errorName) {

      return `Contract error: ${revertError.data.errorName}`

    }

  }

  return error.message.length > 100 ? `${error.message.slice(0, 100)}...` : error.message

}

```

- Differentiate user rejection from actual errors — rejection is normal user behavior, not a failure to alert about.

- Extract revert reasons from contract errors.

- Truncate raw error messages — RPC errors can be very long and unreadable.

## Chain switching

```typescript

function NetworkGuard({

  requiredChainId,

  children,

}: {

  readonly requiredChainId: number

  readonly children: React.ReactNode

}) {

  const { chain, isConnected } = useAccount()

  const { switchChain, isPending } = useSwitchChain()

  if (!isConnected) return <ConnectWallet />

  if (chain?.id !== requiredChainId) {

    return (

      <div className="flex flex-col items-center gap-3 p-6 text-center">

        <p className="text-muted-foreground">Please switch to the correct network.</p>

        <Button onClick={() => switchChain({ chainId: requiredChainId })} disabled={isPending}>

          {isPending ? "Switching..." : "Switch Network"}

        </Button>

      </div>

    )

  }

  return <>{children}</>

}

```

## viem direct usage

For server-side or non-React contexts:

```typescript

import { createPublicClient, http, formatUnits } from "viem"

import { mainnet } from "viem/chains"

const publicClient = createPublicClient({

  chain: mainnet,

  transport: http(),

})

const balance = await publicClient.readContract({

  address: tokenAddress,

  abi: erc20Abi,

  functionName: "balanceOf",

  args: [userAddress],

})

const unwatch = publicClient.watchContractEvent({

  address: tokenAddress,

  abi: erc20Abi,

  eventName: "Transfer",

  onLogs: (logs) => {

    for (const log of logs) {

      console.log(log.args.from, log.args.to, formatUnits(log.args.value, 18))

    }

  },

})

```

- `createPublicClient` for reads, `createWalletClient` for writes.

- Use `formatUnits`/`parseUnits`, `formatEther`/`parseEther` for all BigInt conversions.

## Token amounts

BigInt is the only safe type for on-chain values — floating point loses precision for large token amounts:

```typescript

const amount = parseUnits("1.5", 18)     // 1500000000000000000n

const display = formatUnits(1500000000000000000n, 18) // "1.5"

const ethAmount = parseEther("0.1")

```

- Store amounts as `bigint` throughout. Convert to string only at display boundary.

- Use the token's actual decimals — not all tokens are 18 decimals (USDC is 6, WBTC is 8).