ABI Diff Tool Between Contract Versions

WHAT IT DOES

ABI Diff Tool Between Contract Versions is a read-only developer tool that compares the Application Binary Interfaces (ABIs) of two deployed EVM contract versions to identify changes that could affect client integration. It analyzes contract bytecode to extract function signatures, detects added, removed, and modified functions, identifies event changes, and provides a severity assessment for each change. The tool helps developers understand whether a contract upgrade is backward compatible, determine if dApps and clients need to update their ABIs, and assess the risk level of upgrading to a new version without breaking existing integrations.

HOW TO USE

Connect your EVM-compatible wallet via the BGWallet bridge and select the network where both contracts are deployed. Enter the old (original) contract address and the new (upgraded) contract address, then click "Compare ABIs". The tool fetches bytecode for both addresses, extracts selectors using PUSH4 opcode detection, maps them to function signatures using a common function database, and generates a structured diff report. Results include a summary of total changes, breaking changes count, lists of added/removed/changed functions, event changes, and a severity recommendation. All analysis is read-only—no signatures or transactions are submitted.

TECHNICAL MECHANISM

The tool uses ethers.js v5.7.2 to fetch contract bytecode via provider.getCode(address) for both contract addresses. For each contract, it scans bytecode hex for the PUSH4 opcode pattern (0x63), which indicates a function selector is being pushed onto the stack. Each 4-byte selector (8 hex characters) is extracted and added to a unique set. The tool then maps each selector to a function signature using a built-in database of common EVM functions including transfer, approve, balanceOf, totalSupply, allowance, deposit, withdraw, mint, burn, swap, addLiquidity, removeLiquidity, stake, unstake, claim, pause, unpause, initialize, and upgrade. Standard event definitions (Transfer, Approval, Deposit, Withdraw) and a constructor are also added to simulate a complete ABI. The two ABIs are then compared by grouping functions by name and detecting which functions are present in one version but not the other, or have different signatures/modifiers. Changes are categorized as breaking (removed or changed functions) or non-breaking (added functions or event changes). The tool does not execute any contract functions or simulate transactions.

WHAT IT CANNOT SEE

This tool has fundamental limitations that users must understand. It cannot detect semantic differences in functions with identical signatures but different implementation logic—two contracts can have the same ABI but completely different behavior. It cannot detect changes in event parameters that are not captured in the ABI—if an event's indexed parameters change but the event name remains the same, the ABI diff may not fully capture the impact. It cannot verify that the ABI matches the actual deployed bytecode without source verification—the tool generates mock ABIs based on selector extraction and may miss functions that do not match the common function database. It cannot detect changes in error definitions that are not reflected in the standard ABI format—custom errors are not captured by the standard ABI format used for comparison. It cannot analyze ABI differences for contracts that are not source-verified or that do not expose a complete ABI. It cannot detect changes in storage layout that affect upgrade safety—storage collisions are a separate concern from ABI compatibility. It cannot predict the impact of ABI changes on off-chain systems or frontend code. The tool's function mapping is heuristic and may produce false positives or miss functions that are not in the common database.

PLEASE NOTE

This tool only supports EVM-compatible blockchains (Ethereum, Polygon, BSC, Avalanche C-Chain, Optimism, Arbitrum, and their testnets). Solana, Tron, Starknet, SUI, TON, Aptos, Bitcoin, Cosmos, and XRP are not supported. The tool is free, open-source, requires no API keys, and uses the wallet's native provider for all read operations. Always validate ABI differences with actual contract source code and test upgrades thoroughly in a testnet environment before deploying to production.