Empirical Study on Smart Contract Upgradeability

This repository accompanies the EMSE submission “Immutable in Principle, Upgradeable by Design: Exploratory Study of Smart Contract Upgradeability.”
It focuses on the artifact bundle (datasets + analysis code).

The study empirically analyzes upgradeability patterns in Ethereum (e.g., proxy standards), observed upgrade events over time, and the nature of post-upgrade changes (e.g., fixes, features, gas optimizations). For the full methodology and results, see the PDF in paper/.

.
├─ paper/
│  └─ Immutable_in_Principle_.pdf
├─ artifact/
│  ├─ Dataset/
│  │  ├─ Evaluation/
│  │  ├─ Sample Data/
│  │  ├─ RQ2-RQ4.csv
│  │  └─ RQ4-top_20_proxies_data.csv
│  └─ Source-Code/
│     ├─ DataCollection.ipynb
│     ├─ RQ2-Events.ipynb
│     ├─ RQ3.ipynb
│     ├─ RQ4.ipynb
│     └─ Classification.py
└─ README.md

To keep the repository light and fast to clone, we excluded large data folders. Download the full dataset from the Release: https://github.com/IlhamQasse/empirical-study-smart-contract-upgradeability-artifacts/releases/tag/v1.0-artifacts

python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate

pip install pandas numpy tqdm requests web3 jupyter matplotlib

jupyter lab   # or: jupyter notebook
# Navigate to: artifact/EMSE-R2/Source-Code/

• Provide a folder of .txt decompiled contracts (one file per address).
• Edit the input folder path inside Classification.py and run:

python artifact/EMSE-R2/Source-Code/Classification.py

• CSVs may contain an automatic index column like Unnamed: 0; it is safe to drop:

  import pandas as pd
  df = pd.read_csv("file.csv").loc[:, lambda x: ~x.columns.str.startswith("Unnamed")]

• JSON pages under Dataset/RQ2-Events/ are raw event responses useful for reconstructing version lineages.
• Start with Dataset/Sample Data/ for quick execution before scaling up.

• Python ≥ 3.9 (tested with 3.10+)
• Suggested: pandas, numpy, tqdm, requests, web3, jupyter, matplotlib, scikit-learn
• Optional: Access to an Ethereum RPC/explorer API if you plan to refresh on-chain data

• Data & notebooks: CC BY 4.0
• Scripts: MIT

• Ilham Qasse — Reykjavik University — ilham20@ru.is

If you use these artifacts or build on this work, please cite the paper:

Plain text

Qasse, I., Hamdaqa, M., & Jónsson, B. Þ. (2025).
Immutable in Principle, Upgradeable by Design: Exploratory Study of Smart Contract Upgradeability.
Empirical Software Engineering (EMSE). Under review.

BibTeX

@article{Qasse2025ImmutableUpgradeability,
  title   = {Immutable in Principle, Upgradeable by Design: Exploratory Study of Smart Contract Upgradeability},
  author  = {Qasse, Ilham and Hamdaqa, Mohammad and Jónsson, Björn Þór},
  journal = {Empirical Software Engineering},
  note    = {Under review},
  year    = {2025}
}