Contract Size Regression Checker in CI

WHAT IT DOES

The Contract Size Regression Checker in CI is a developer tool that analyzes compiled contract bytecode to detect size regressions in CI environments. It parses build artifact JSON files from frameworks like Hardhat or Foundry, extracts each contract's bytecode size, and compares against a baseline artifact. The tool identifies contracts that have increased in size (regressions) and checks whether any contract exceeds the 24KB Ethereum deployment limit. This helps development teams catch size regressions early in the CI pipeline, preventing failed deployments due to contract size limits.

HOW TO USE

Paste your current build artifact JSON into the first text area and your baseline artifact into the second text area. Click "parse current" and "parse baseline" to extract contract data from each artifact. Click "check regressions" to compare sizes. The tool displays a detailed report showing each contract's current size, baseline size, size difference, and status. Contracts exceeding the 24KB limit or showing size increases are flagged. The report also indicates whether the CI check would pass or fail, making it easy to integrate into automated workflows.

TECHNICAL MECHANISM

The tool parses build artifacts by traversing the JSON structure to locate contract bytecode. It supports multiple artifact formats including the standard "contracts" object structure used by Hardhat and Foundry, as well as single-contract formats. For each contract found, it extracts the bytecode string (from bin, bytecode, or evm.bytecode.object fields) and calculates the size in bytes as the hexadecimal string length divided by 2. The tool stores contract name, size, and size in kilobytes. When comparing against baseline, it calculates the absolute size difference and percentage change. Contracts are flagged as regressions if their size increased compared to baseline, and checked against the 24KB EIP-170 contract size limit. Results are displayed in a table with color-coded status indicators and a summary showing the number of contracts analyzed, regressions detected, and over-limit contracts. The tool provides a CI exit code recommendation based on the results.

WHAT IT CANNOT SEE

The tool cannot compile contracts or run build processes—it only analyzes already-compiled artifacts. It cannot detect size increases caused by changes in compiler versions or optimizer settings. The tool cannot automatically update baseline sizes or determine if a size increase is acceptable without manual review. It cannot analyze why a contract's size changed, only that it did change. The tool cannot detect size increases in dependencies or inherited contracts separately from the main contract. It cannot validate that the contract bytecode is valid or deployable beyond checking the size. The tool cannot detect subtle changes like a contract size decreasing slightly and then increasing again, as it only compares against a single baseline.

PLEASE NOTE

This tool is designed for Ethereum Virtual Machine (EVM) compatible chains only. The 24KB limit is the standard Ethereum contract deployment limit (EIP-170); other EVM chains may have different limits. The tool requires build artifacts in JSON format—ensure your build process outputs the complete artifact files. The tool is intended for CI/CD pipelines and local development testing. Always use the same compiler version and optimizer settings when generating current and baseline artifacts for accurate comparisons. The tool provides recommendations only and should be used as part of a comprehensive quality assurance process.