tessl/npm-wagmi

React Hooks for Ethereum providing reactive primitives for wallet connections, smart contract interactions, and blockchain data

—

Pending

Overview

Eval results

Files

Transaction Management

Name: tessl/npm-wagmi
Author: tessl

Transaction lifecycle management including sending, monitoring, and receipt handling. This module provides comprehensive transaction functionality from creation through confirmation with full type safety and error handling.

Capabilities

useSendTransaction

Hook to send transactions with comprehensive parameter support and transaction lifecycle tracking.

/**
 * Hook to send a transaction
 * @param parameters - Transaction sending configuration with mutation callbacks
 * @returns Send transaction mutation with transaction state
 */
function useSendTransaction<config = Config, context = unknown>(
  parameters?: UseSendTransactionParameters<config, context>
): UseSendTransactionReturnType<config, context>;

interface UseSendTransactionParameters<config = Config, context = unknown> {
  config?: Config | config;
  mutation?: {
    onMutate?: (variables: SendTransactionVariables) => Promise<context> | context;
    onError?: (error: SendTransactionErrorType, variables: SendTransactionVariables, context?: context) => Promise<void> | void;
    onSuccess?: (data: SendTransactionData, variables: SendTransactionVariables, context?: context) => Promise<void> | void;
    onSettled?: (data?: SendTransactionData, error?: SendTransactionErrorType, variables?: SendTransactionVariables, context?: context) => Promise<void> | void;
  };
}

interface UseSendTransactionReturnType<config = Config, context = unknown> {
  /** Send transaction */
  sendTransaction: (variables: SendTransactionVariables, options?: SendTransactionMutateOptions) => void;
  /** Async version of sendTransaction */
  sendTransactionAsync: (variables: SendTransactionVariables, options?: SendTransactionMutateAsyncOptions) => Promise<SendTransactionData>;
  /** Transaction hash */
  data?: SendTransactionData;
  /** Send transaction error */
  error: SendTransactionErrorType | null;
  /** Transaction status flags */
  isError: boolean;
  isIdle: boolean;
  isPending: boolean;
  isSuccess: boolean;
  /** Reset transaction state */
  reset: () => void;
  /** Current status */
  status: 'error' | 'idle' | 'pending' | 'success';
  /** Additional variables */
  variables?: SendTransactionVariables;
}

interface SendTransactionVariables {
  /** Recipient address */
  to: Address;
  /** Transaction value in wei */
  value?: bigint;
  /** Transaction data */
  data?: Hex;
  /** Account to send from */
  account?: Address;
  /** Chain ID */
  chainId?: number;
  /** Gas limit */
  gas?: bigint;
  /** Gas price (legacy) */
  gasPrice?: bigint;
  /** Max fee per gas (EIP-1559) */
  maxFeePerGas?: bigint;
  /** Max priority fee per gas (EIP-1559) */
  maxPriorityFeePerGas?: bigint;
  /** Nonce override */
  nonce?: number;
}

type SendTransactionData = Hash;

Usage Example:

import { useSendTransaction, useWaitForTransactionReceipt } from "wagmi";
import { parseEther } from "viem";

function SendEther() {
  const { sendTransaction, data: hash, isPending } = useSendTransaction();

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

  const handleSend = () => {
    sendTransaction({
      to: '0x742d35Cc6634C0532925a3b8D',
      value: parseEther('0.1'), // 0.1 ETH
    });
  };

  return (
    <div>
      <button onClick={handleSend} disabled={isPending || isConfirming}>
        {isPending ? 'Preparing...' : isConfirming ? 'Confirming...' : 'Send 0.1 ETH'}
      </button>
      {hash && <p>Hash: {hash}</p>}
      {isConfirmed && <p>Transaction confirmed!</p>}
    </div>
  );
}

useTransaction

Hook to get detailed transaction information by hash.

/**
 * Hook to get transaction by hash
 * @param parameters - Transaction query parameters
 * @returns Transaction data with all details
 */
function useTransaction<config = Config, selectData = UseTransactionReturnType>(
  parameters: UseTransactionParameters<config, selectData>
): UseTransactionReturnType<selectData>;

interface UseTransactionParameters<config = Config, selectData = UseTransactionReturnType> {
  /** Transaction hash to fetch */
  hash: Hash;
  /** Block number hint for faster lookup */
  blockNumber?: bigint;
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
  /** Chain to use */
  chainId?: config['chains'][number]['id'];
  config?: Config | config;
  query?: {
    enabled?: boolean;
    staleTime?: number;
    gcTime?: number;
    refetchInterval?: number;
    select?: (data: UseTransactionReturnType) => selectData;
  };
}

interface UseTransactionReturnType {
  /** Transaction hash */
  hash: Hash;
  /** Block hash (null for pending) */
  blockHash?: Hash;
  /** Block number (null for pending) */
  blockNumber?: bigint;
  /** Transaction index in block */
  transactionIndex?: number;
  /** Sender address */
  from: Address;
  /** Recipient address */
  to?: Address;
  /** Transaction value */
  value: bigint;
  /** Gas limit */
  gas: bigint;
  /** Gas price */
  gasPrice?: bigint;
  /** Max fee per gas */
  maxFeePerGas?: bigint;
  /** Max priority fee per gas */
  maxPriorityFeePerGas?: bigint;
  /** Transaction input data */
  input: Hex;
  /** Nonce */
  nonce: number;
  /** Transaction type */
  type: 'legacy' | 'eip2930' | 'eip1559';
  /** Access list (EIP-2930/1559) */
  accessList?: AccessList;
  /** Chain ID */
  chainId?: number;
}

useTransactionReceipt

Hook to get transaction receipt with execution details and status.

/**
 * Hook to get transaction receipt
 * @param parameters - Transaction receipt query parameters
 * @returns Transaction receipt with execution details
 */
function useTransactionReceipt<config = Config, selectData = UseTransactionReceiptReturnType>(
  parameters: UseTransactionReceiptParameters<config, selectData>
): UseTransactionReceiptReturnType<selectData>;

interface UseTransactionReceiptParameters<config = Config, selectData = UseTransactionReceiptReturnType> {
  /** Transaction hash */
  hash: Hash;
  /** Chain to use */
  chainId?: config['chains'][number]['id'];
  config?: Config | config;
  query?: {
    enabled?: boolean;
    staleTime?: number;
    gcTime?: number;
    refetchInterval?: number;
    select?: (data: UseTransactionReceiptReturnType) => selectData;
  };
}

interface UseTransactionReceiptReturnType {
  /** Transaction hash */
  transactionHash: Hash;
  /** Block hash */
  blockHash: Hash;
  /** Block number */
  blockNumber: bigint;
  /** Transaction index */
  transactionIndex: number;
  /** Sender address */
  from: Address;
  /** Recipient address */
  to?: Address;
  /** Contract address (for deployments) */
  contractAddress?: Address;
  /** Cumulative gas used */
  cumulativeGasUsed: bigint;
  /** Gas used by this transaction */
  gasUsed: bigint;
  /** Effective gas price */
  effectiveGasPrice: bigint;
  /** Transaction status (1 = success, 0 = failure) */
  status: 'success' | 'reverted';
  /** Transaction type */
  type: 'legacy' | 'eip2930' | 'eip1559';
  /** Event logs */
  logs: Log[];
  /** Logs bloom filter */
  logsBloom: Hex;
}

useWaitForTransactionReceipt

Hook to wait for a transaction to be confirmed and get its receipt.

/**
 * Hook to wait for transaction receipt
 * @param parameters - Transaction wait parameters
 * @returns Transaction receipt when confirmed
 */
function useWaitForTransactionReceipt<config = Config, selectData = UseWaitForTransactionReceiptReturnType>(
  parameters: UseWaitForTransactionReceiptParameters<config, selectData>
): UseWaitForTransactionReceiptReturnType<selectData>;

interface UseWaitForTransactionReceiptParameters<config = Config, selectData = UseWaitForTransactionReceiptReturnType> {
  /** Transaction hash to wait for */
  hash: Hash;
  /** Number of confirmations to wait for */
  confirmations?: number;
  /** Polling interval in milliseconds */
  pollingInterval?: number;
  /** Timeout in milliseconds */
  timeout?: number;
  /** Chain to use */
  chainId?: config['chains'][number]['id'];
  config?: Config | config;
  query?: {
    enabled?: boolean;
    gcTime?: number;
    refetchInterval?: number;
    retry?: boolean | number;
    select?: (data: UseWaitForTransactionReceiptReturnType) => selectData;
  };
}

type UseWaitForTransactionReceiptReturnType = UseTransactionReceiptReturnType;

Usage Example:

import { useWaitForTransactionReceipt } from "wagmi";

function TransactionStatus({ hash }: { hash: `0x${string}` }) {
  const { 
    data: receipt,
    isLoading,
    isSuccess,
    isError,
    error 
  } = useWaitForTransactionReceipt({
    hash,
    confirmations: 2, // Wait for 2 confirmations
  });

  if (isLoading) return <div>Waiting for confirmation...</div>;
  if (isError) return <div>Error: {error?.message}</div>;
  if (isSuccess && receipt) {
    return (
      <div>
        <p>Transaction confirmed!</p>
        <p>Block: {receipt.blockNumber.toString()}</p>
        <p>Gas used: {receipt.gasUsed.toString()}</p>
        <p>Status: {receipt.status}</p>
      </div>
    );
  }
  return null;
}

useTransactionCount

Hook to get account transaction count (nonce) for a specific address.

/**
 * Hook to get account transaction count (nonce)
 * @param parameters - Transaction count query parameters
 * @returns Transaction count for the address
 */
function useTransactionCount<config = Config, selectData = UseTransactionCountReturnType>(
  parameters: UseTransactionCountParameters<config, selectData>
): UseTransactionCountReturnType<selectData>;

interface UseTransactionCountParameters<config = Config, selectData = UseTransactionCountReturnType> {
  /** Address to get transaction count for */
  address: Address;
  /** Block number to check count at */
  blockNumber?: bigint;
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
  /** Chain to use */
  chainId?: config['chains'][number]['id'];
  config?: Config | config;
  query?: {
    enabled?: boolean;
    staleTime?: number;
    gcTime?: number;
    select?: (data: UseTransactionCountReturnType) => selectData;
  };
}

type UseTransactionCountReturnType = number;

useTransactionConfirmations

Hook to get the number of confirmations for a transaction.

/**
 * Hook to get transaction confirmations
 * @param parameters - Transaction confirmations query parameters
 * @returns Number of confirmations for the transaction
 */
function useTransactionConfirmations<config = Config, selectData = UseTransactionConfirmationsReturnType>(
  parameters: UseTransactionConfirmationsParameters<config, selectData>
): UseTransactionConfirmationsReturnType<selectData>;

interface UseTransactionConfirmationsParameters<config = Config, selectData = UseTransactionConfirmationsReturnType> {
  /** Transaction hash */
  hash: Hash;
  /** Chain to use */
  chainId?: config['chains'][number]['id'];
  config?: Config | config;
  query?: {
    enabled?: boolean;
    staleTime?: number;
    refetchInterval?: number;
    select?: (data: UseTransactionConfirmationsReturnType) => selectData;
  };
}

type UseTransactionConfirmationsReturnType = bigint;

usePrepareTransactionRequest

Hook to prepare and validate transaction parameters before sending.

/**
 * Hook to prepare transaction request
 * @param parameters - Transaction preparation parameters
 * @returns Prepared transaction with estimated gas and fees
 */
function usePrepareTransactionRequest<config = Config, selectData = UsePrepareTransactionRequestReturnType>(
  parameters: UsePrepareTransactionRequestParameters<config, selectData>
): UsePrepareTransactionRequestReturnType<selectData>;

interface UsePrepareTransactionRequestParameters<config = Config, selectData = UsePrepareTransactionRequestReturnType> {
  /** Recipient address */
  to: Address;
  /** Transaction value */
  value?: bigint;
  /** Transaction data */
  data?: Hex;
  /** Account to send from */
  account?: Address;
  /** Chain ID */
  chainId?: config['chains'][number]['id'];
  /** Gas limit */
  gas?: bigint;
  /** Gas price */
  gasPrice?: bigint;
  /** Max fee per gas */
  maxFeePerGas?: bigint;
  /** Max priority fee per gas */
  maxPriorityFeePerGas?: bigint;
  /** Nonce */
  nonce?: number;
  config?: Config | config;
  query?: {
    enabled?: boolean;
    staleTime?: number;
    select?: (data: UsePrepareTransactionRequestReturnType) => selectData;
  };
}

interface UsePrepareTransactionRequestReturnType {
  /** Prepared transaction parameters */
  to: Address;
  value?: bigint;
  data?: Hex;
  account: Address;
  chainId: number;
  gas: bigint;
  gasPrice?: bigint;
  maxFeePerGas?: bigint;
  maxPriorityFeePerGas?: bigint;
  nonce: number;
  type: 'legacy' | 'eip2930' | 'eip1559';
}

Advanced Transaction Patterns

Transaction with Confirmation Tracking

import { 
  useSendTransaction, 
  useWaitForTransactionReceipt, 
  useTransactionConfirmations 
} from "wagmi";

function AdvancedTransaction() {
  const { sendTransaction, data: hash, isPending } = useSendTransaction();
  
  const { data: receipt, isLoading: isConfirming } = useWaitForTransactionReceipt({
    hash,
    confirmations: 1,
  });

  const { data: confirmations } = useTransactionConfirmations({
    hash: hash || '0x',
    query: { 
      enabled: !!hash && !!receipt,
      refetchInterval: 4000, // Check every 4 seconds
    }
  });

  const handleSend = () => {
    sendTransaction({
      to: '0x742d35Cc6634C0532925a3b8D',
      value: parseEther('0.01'),
    });
  };

  return (
    <div>
      <button onClick={handleSend} disabled={isPending}>
        Send Transaction
      </button>
      
      {hash && (
        <div>
          <p>Hash: {hash}</p>
          {isConfirming && <p>Confirming...</p>}
          {receipt && (
            <div>
              <p>Status: {receipt.status}</p>
              <p>Confirmations: {confirmations?.toString() || '0'}</p>
            </div>
          )}
        </div>
      )}
    </div>
  );
}

Common Types

type Hash = `0x${string}`;
type Hex = `0x${string}`;
type Address = `0x${string}`;

interface AccessList {
  address: Address;
  storageKeys: Hex[];
}

interface Log {
  address: Address;
  topics: Hash[];
  data: Hex;
  blockHash: Hash;
  blockNumber: bigint;
  transactionHash: Hash;
  transactionIndex: number;
  logIndex: number;
  removed: boolean;
}

interface SendTransactionMutateOptions {
  onError?: (error: Error, variables: SendTransactionVariables, context?: unknown) => void;
  onSuccess?: (data: Hash, variables: SendTransactionVariables, context?: unknown) => void;
  onSettled?: (data?: Hash, error?: Error, variables?: SendTransactionVariables, context?: unknown) => void;
}

interface SendTransactionMutateAsyncOptions {
  onError?: (error: Error, variables: SendTransactionVariables, context?: unknown) => void;
  onSuccess?: (data: Hash, variables: SendTransactionVariables, context?: unknown) => void;
  onSettled?: (data?: Hash, error?: Error, variables?: SendTransactionVariables, context?: unknown) => void;
}

type SendTransactionErrorType = Error;

Install with Tessl CLI