Contract ABI Backward Compatibility Scorer

WHAT IT DOES

Contract ABI Backward Compatibility Scorer analyzes two versions of a smart contract's ABI—typically an old deployed version and a new upgrade—and produces a quantitative compatibility score. It retrieves on-chain contract bytecode via eth_getCode and fetches verified source code and ABI from block explorer APIs for both the current and previous contract versions. The tool compares function signatures, state variable declarations, event definitions, error types, and modifiers across the two ABIs. It categorizes differences into three classes: breaking changes (removed functions, modified signatures, reordered parameters), non-breaking changes (renamed parameters, reordered events with aliases), and additive changes (new functions, events, or errors). The tool computes a weighted score that penalizes breaking changes heavily, moderately penalizes non-breaking changes, and rewards additive improvements. The output includes a percentage score, a compatibility level (Excellent, Moderate, Poor), and a detailed list of all detected differences with their severity classification.

HOW TO USE

Connect your BGWallet to the target EVM chain. Paste the address of the current contract version you want to evaluate. Optionally, paste the address of the previous contract version for direct comparison; if left blank, the tool attempts to fetch version history from block explorer data or bytecode deployment history. Optionally supply a GitHub repository URL to pull existing ABI version histories, upgrade documentation, or migration guides for additional context. The tool fetches both ABIs, performs a structural comparison, and displays a compatibility score along with a categorized list of differences. Use the score and difference list to assess the risk of upgrading to the new contract version and to plan migration strategies for dependent applications.

STRUCTURAL ABI DIFF ENGINE WITH SEMANTIC AWARENESS

The real technical mechanism is the structural ABI diff engine that combines syntactic comparison with semantic awareness of Solidity and EVM ABI evolution patterns. The tool parses both ABIs into a normalized intermediate representation, resolving function selector collisions and handling overloaded function names. It then performs a multi-pass diff: first comparing function signatures using canonical encoding (name, parameter types, return types), then comparing event definitions, error definitions, and state variable layouts. The engine applies a set of Solidity-specific compatibility rules: adding a new function is always additive (non-breaking), changing a function's parameter type is breaking, adding an overloaded function is non-breaking if the original signature remains, and reordering event parameters is breaking unless an indexed ordering alias is present. It also detects changes in modifiers and custom errors, which can affect client-side error handling. The scoring algorithm uses a weighted sum where breaking changes reduce the score by 15 points each, non-breaking changes by 5 points, and additive changes increase the score by 2 points each, capped at 100. The engine also provides a machine-readable JSON diff output for integration into CI/CD pipelines, enabling automated compatibility checks in upgrade workflows. This approach reduces the risk of deploying breaking ABI changes in production upgrades, catching issues that would otherwise cause client applications to fail silently.

WHAT IT CANNOT SEE

This tool cannot score backward compatibility without access to multiple ABI versions or bytecode histories. It is limited by your RPC provider's rate limits for bytecode retrieval, which may delay analysis on congested networks. It cannot detect semantic breaking changes that do not alter the ABI surface—for example, changed business logic, modified invariants, or altered security assumptions—all of which can break application behavior even when the ABI remains identical. The score relies on the completeness and accuracy of ABI verification across versions; unverified contracts or incomplete verification data will produce incomplete or inaccurate scores. The score is based on structural ABI differences and may not reflect runtime behavioral compatibility, such as changes in gas costs or reentrancy risks. The tool cannot account for changes in external dependencies or system contracts that affect contract behavior. It may produce false positives for reordered events or renamed parameters that are semantically equivalent, requiring manual review. The tool does not execute the contract to validate compatibility; all scores should be supplemented with integration testing.

PLEASE NOTE

This tool works exclusively with EVM-compatible chains. It requires active internet connectivity to access block explorer APIs and RPC endpoints. Some block explorers may require API keys for high-volume bytecode retrieval. The scorer is read-only and does not modify or deploy any code—it only produces compatibility assessments. Always validate compatibility scores with integration tests and manual review before performing contract upgrades in production environments.