Semantic Versioning Compliance Checker for Contracts

WHAT IT DOES

This tool checks whether contract version upgrades follow semantic versioning (SemVer) rules by analyzing changes across multiple deployed versions. It compares ABIs, function signatures, storage layouts, and behavioral characteristics between consecutive versions, then determines if the version increment (MAJOR.MINOR.PATCH) correctly reflects the nature of the changes. The checker flags violations where breaking changes (function removals, signature changes, storage layout shifts) occur without a major version bump, where new features are added without a minor version bump, or where patch versions introduce non-backward-compatible changes. Results are presented as a compliance report showing pass/warn/fail status for each version transition, with detailed explanations of detected issues and recommendations for proper versioning. This is essential for teams managing contract upgrades, auditors verifying versioning discipline, and integrators assessing upgrade safety.

HOW TO USE

Connect your wallet (read-only, no transaction required) and select the target network. Enter the contract name and provide a JSON mapping of version tags to contract addresses (e.g., {"v1.0.0": "0x...", "v1.1.0": "0x..."}). Click "check semver compliance" and the tool will fetch source code and ABI data for each version, compare consecutive versions, and evaluate whether the version increments are semantically correct. Results display a summary with pass/warn/fail counts and an overall compliance status, detailed cards for each version transition showing detected issues and recommendations, and a table of all version comparisons. Use the report to identify versioning violations, plan corrections, and ensure your upgrade process follows SemVer best practices.

TECHNICAL MECHANISM

The checker uses ethers.js v5.7.2 and block explorer APIs to perform a multi-stage SemVer compliance analysis. First, it fetches verified source code and ABI data for all provided contract versions using eth_getCode to confirm deployment. The engine then parses each version's ABI to extract function signatures, parameter types, return types, and visibility modifiers. It compares consecutive versions using a diff algorithm that identifies additions, removals, and modifications across three categories: function signatures (signature changes), storage layout (variable reordering or insertion), and behavioral characteristics (semantic changes inferred from source code patterns). For each detected change, the checker applies SemVer rules: breaking changes (removed functions, signature changes, storage layout shifts) require a MAJOR version increment; new features or new functions require a MINOR version increment; bug fixes and internal optimizations require a PATCH increment. The tool also validates that version numbers are properly incremented (e.g., v1.1.0 → v1.2.0 is valid, v1.1.0 → v1.1.1 is valid, v1.1.0 → v2.0.0 is valid only with breaking changes). Each transition is flagged as pass (semver-compliant), warn (minor issues like no clear feature detected), or fail (violation such as major bump without breaking changes or patch bump with breaking changes). The implementation includes caching for ABI data to optimize repeated comparisons.

WHAT IT CANNOT SEE

This tool cannot analyze contracts that are not verified or have complex inheritance patterns that obscure version differences, as source code and ABI are required for accurate comparison. It is limited by the RPC provider's rate limits and block range availability for historical log queries. It cannot determine semantic versioning compliance without clear versioning conventions documented in the contract metadata—the checker relies on the provided version tags. It relies on the accuracy and completeness of source code verification and ABI data for all versions; incomplete verification may lead to incorrect compliance judgments. It cannot analyze contracts where version information is not stored on-chain or in accessible metadata. The tool is limited to the specific contract versions that are actually deployed on-chain—differences between source code versions that have not been deployed cannot be checked. It cannot detect versioning violations that depend on developer intent or undocumented breaking changes that are not captured in the ABI or storage layout. It cannot enforce semantic versioning rules—only checks compliance with the defined rules based on detected changes. Behavioral analysis is heuristic and may miss subtle semantic changes that are not visible in the ABI or storage layout.

PLEASE NOTE

This is a read‑only analytics tool—it never submits transactions or signs anything. It is designed for EVM‑compatible chains and works best with verified contracts that follow clear versioning conventions. The compliance report is for informational and audit purposes only and should not be considered a guarantee of correct versioning. Always review detected issues manually and consult the SemVer specification for definitive guidance. The tool's recommendations are based on common SemVer conventions and may need adjustment for your specific project's versioning policy.