SoliDiffy: AST Differencing for Solidity Smart Contracts

SoliDiffy is a tool for performing AST differencing of two Solidity files. It produces an high level edit script about the AST differences.

Viewing the Results

The results of our extensive experiments are available at here.

To easily review the results, we have prepared a web form at SoliDiffy.github.io where you can select the project, the severity of modifications to the original file, and the corresponding edit scripts generated by our tool SoliDiffy to transform the original smart contract to the modified version.

Replication/Installation via SoliDiffy's Docker Container

You need to have Docker

Installation and Setup

1. Clone the Repository

First, clone the SoliDiffy repository:

git clone https://github.com/mojtaba-eshghie/SoliDiffy
cd SoliDiffy

2. Build the Docker Image

Build the Docker image using the provided Dockerfile. This step will compile necessary dependencies, including the Tree-sitter parser, to speed up future runs.

docker build -t solidiffy-replication .

This will create a Docker image named solidiffy-replication that includes everything you need to run SoliDiffy.

3. Run SoliDiffy with Docker

To run SoliDiffy and compare two Solidity files, use the following Docker command. The files must be located on your host machine, and Docker will mount them into the container.

docker run --rm \
  -v $(realpath example/original.sol):/app/original.sol \
  -v $(realpath example/modified.sol):/app/modified.sol \
  solidiffy-replication textdiff /app/original.sol /app/modified.sol

This will run the diff and output the differences between the two Solidity files.

Explanation:

• example/original.sol: Path to your original Solidity file on your local machine.
• example/modified.sol: Path to your modified Solidity file on your local machine.
• solidiffy-replication: The Docker image you built.
• textdiff: SoliDiffy to run the diff comparison between the two files.

Dataset(s)

The project creates and maintains two main datasets to assist with research and evaluation of Solidity smart contract differencing:

Mutated Contracts Dataset:

The mutated contracts dataset contains Solidity smart contract pairs generated through mutation testing. Using the SuMo mutation testing tool, we applied 44 mutation operators to original smart contracts, creating up to 10 mutated versions for each file. The dataset includes a diverse range of changes, from simple syntax modifications to complex structural transformations, enabling robust evaluation of differencing tools.

• Location: Mutated Contracts Dataset
• Details: This dataset consists of pairs of original and mutated smart contracts, facilitating the comparison of contract pairs with controlled and specific syntactic changes.

Differencing Results Dataset:

This dataset contains the output of the SoliDiffy tool after running it on the mutated contract pairs. Each pair of Solidity contracts has been analyzed by SoliDiffy (and Difftastic for comparison), and the differencing results, including edit scripts and summaries of changes, are provided. This dataset is invaluable for understanding how SoliDiffy captures and represents changes between two versions of a contract.

• Location: Differencing Results Dataset
• Details: Each entry in this dataset includes detailed diff results including the time it took to calculate the edit script and edit script itself.

Citing SoliDiffy

Please use the following bibtex entry if citing us in your reports/papers:

@misc{SoliDiffy,
      title={SoliDiffy: AST Differencing for Solidity Smart Contracts}, 
      author={Mojtaba Eshghie and Viktor Åryd and Cyrille Artho and Martin Monperrus},
      year={2025},
      eprint={2411.07718},
      archivePrefix={arXiv},
      primaryClass={cs.SE},
      url={https://arxiv.org/abs/2411.07718}, 
}