🌐 Web3 TypeScript Types

Complete TypeScript type definitions for Web3, smart contracts, wallets, and blockchain interactions. Fully typed for safety and IntelliSense.

🪙Token Types

Token Interface

interface Token {
  address: ContractAddress;
  name: string;
  symbol: string;
  decimals: number;
  chainId: number;
  logoUrl?: string;
}

type ContractAddress = Address;
type WalletAddress = Address;
type TransactionHash = Hash;

Example Usage

const usdc: Token = {
  address: "0xA0b86a33E6...",
  name: "USD Coin",
  symbol: "USDC",
  decimals: 6,
  chainId: 1,
  logoUrl: "https://tokens.1inch.io/0xa0b86a33e..."
};

// Type-safe token operations
const tokenBalance = await getTokenBalance(usdc.address);
const formattedAmount = formatTokenAmount(amount, usdc.decimals);

📝Transaction Types

Transaction Status

interface TransactionStatus {
  hash: TransactionHash;
  status: "pending" | "confirmed" | "failed";
  blockNumber?: bigint;
  confirmations?: number;
}

interface ContractCall {
  address: ContractAddress;
  functionName: string;
  args?: any[];
  value?: bigint;
}

Usage Example

// Contract interaction
const transferCall: ContractCall = {
  address: tokenAddress,
  functionName: "transfer",
  args: [recipient, amount],
  value: BigInt(0)
};

// Monitor transaction
const txStatus: TransactionStatus = {
  hash: "0xabc...",
  status: "pending",
  blockNumber: BigInt(18500000),
  confirmations: 0
};

👛Wallet & Connection Types

Wallet State

interface WalletState {
  isConnected: boolean;
  isConnecting: boolean;
  isReconnecting: boolean;
  address?: WalletAddress;
  chainId?: number;
  connector?: any;
}

// Wallet connection hooks
const { address, isConnected, chainId } = useAccount();
const { connect } = useConnect();
const { disconnect } = useDisconnect();

Network Configuration

interface NetworkConfig {
  chainId: number;
  name: string;
  rpcUrl: string;
  blockExplorer: string;
  nativeCurrency: {
    name: string;
    symbol: string;
    decimals: number;
  };
}

const ethereum: NetworkConfig = {
  chainId: 1,
  name: "Ethereum Mainnet",
  rpcUrl: "https://mainnet.infura.io/v3/...",
  blockExplorer: "https://etherscan.io",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 }
};

🚨Error Types & Handling

Web3 Error Interface

interface Web3Error {
  code: string;
  message: string;
  cause?: unknown;
}

// Common error codes
type ErrorCode =
  | "ACTION_REJECTED"
  | "INSUFFICIENT_FUNDS"
  | "NETWORK_ERROR"
  | "CONTRACT_ERROR"
  | "INVALID_ADDRESS";

Error Handling Pattern

function isWeb3Error(error: unknown): error is Web3Error {
  return error instanceof Error &&
    'code' in error &&
    'message' in error;
}

try {
  await contractWrite();
} catch (error) {
  if (isWeb3Error(error)) {
    switch (error.code) {
      case "ACTION_REJECTED":
        toast.error("Transaction was rejected");
        break;
      case "INSUFFICIENT_FUNDS":
        toast.error("Insufficient funds");
        break;
      default:
        toast.error(error.message);
    }
  }
}

Interactive Examples

Web3 Type Examples

Type Output

Select an example to see the typed data...

🪝Custom Hooks with Types

useWalletInfo Hook

function useWalletInfo() {
  const { address, isConnected, chainId } = useAccount();
  const { data: balance } = useBalance({ address });

  const walletState: WalletState = {
    isConnected,
    isConnecting: false,
    isReconnecting: false,
    address,
    chainId,
  };

  return {
    address,
    chainId,
    balance: balance?.value,
    formattedAddress: formatAddress(address),
    walletState,
  };
}

useContractWrite Hook

function useContractWrite<T extends ContractABI>(
  contract: { address: Address; abi: T }
) {
  const [status, setStatus] = useState<TransactionStatus | null>(null);

  const writeContract = async (call: ContractCall) => {
    try {
      const hash = await writeContract({
        address: call.address,
        abi: contract.abi,
        functionName: call.functionName,
        args: call.args,
        value: call.value,
      });

      setStatus({
        hash,
        status: "pending",
        confirmations: 0,
      });

      return hash;
    } catch (error) {
      if (isWeb3Error(error)) {
        throw error;
      }
      throw new Error("Unknown error");
    }
  };

  return { writeContract, status };
}

Web3 TypeScript Best Practices

✅ Do

  • • Use strict typing for addresses and hashes
  • • Handle BigInt types properly in JSON
  • • Implement proper error type guards
  • • Type your contract ABIs
  • • Use branded types for safety

❌ Don't

  • • Use 'any' for Web3 method returns
  • • Ignore BigInt conversion in serialization
  • • Skip error handling for transactions
  • • Use strings for addresses without validation
  • • Forget to handle network switching