{"id":39527884,"url":"https://github.com/lisa-analyzer/evm-lisa","last_synced_at":"2026-01-18T06:25:46.603Z","repository":{"id":221816034,"uuid":"541975905","full_name":"lisa-analyzer/evm-lisa","owner":"lisa-analyzer","description":"EVMLiSA: an abstract interpretation-based static analyzer for EVM bytecode","archived":false,"fork":false,"pushed_at":"2025-12-27T19:33:10.000Z","size":149921,"stargazers_count":32,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-27T21:41:18.572Z","etag":null,"topics":["abstract-interpretation","cfg","control-flow-graph","ethereum","evm-bytecode","smart-contracts","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lisa-analyzer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-09-27T08:16:48.000Z","updated_at":"2025-12-18T10:32:01.000Z","dependencies_parsed_at":"2024-12-20T23:18:23.174Z","dependency_job_id":"a1ab93a4-38ba-409f-b199-eb414e411f4f","html_url":"https://github.com/lisa-analyzer/evm-lisa","commit_stats":null,"previous_names":["lisa-analyzer/evm-lisa"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lisa-analyzer/evm-lisa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisa-analyzer%2Fevm-lisa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisa-analyzer%2Fevm-lisa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisa-analyzer%2Fevm-lisa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisa-analyzer%2Fevm-lisa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lisa-analyzer","download_url":"https://codeload.github.com/lisa-analyzer/evm-lisa/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisa-analyzer%2Fevm-lisa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28531995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abstract-interpretation","cfg","control-flow-graph","ethereum","evm-bytecode","smart-contracts","static-analysis"],"created_at":"2026-01-18T06:25:46.536Z","updated_at":"2026-01-18T06:25:46.591Z","avatar_url":"https://github.com/lisa-analyzer.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"logo/emv-lisa-logo-no-background.png\"\u003e\n\n# EVMLiSA: an abstract interpretation-based static analyzer for EVM bytecode\n\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/lisa-analyzer/evm-lisa/gradle-master.yml)\n![GitHub last commit](https://img.shields.io/github/last-commit/lisa-analyzer/evm-lisa)\n![GitHub commit activity](https://img.shields.io/github/commit-activity/y/lisa-analyzer/evm-lisa)\n![GitHub issues](https://img.shields.io/github/issues-raw/lisa-analyzer/evm-lisa)\n\nEVMLiSA is a static analyzer based on abstract interpretation for [EVM bytecode](https://www.ethervm.io/) of smart contracts deployed on Ethereum blockchain and built upon [LiSA](https://unive-ssv.github.io/lisa/). Given a EVM bytecode smart contract, EVMLiSA builds a sound and precise control-flow graph of the smart contract.\n\nEVMLiSA is based on peer-reviewed publications:\n1. Vincenzo Arceri, Saverio Mattia Merenda, Luca Negrini, Luca Olivieri, Enea Zaffanella. _**\"EVMLiSA: Sound Static Control-Flow Graph Construction for EVM Bytecode\"**_. Blockchain: Research and Applications, 2025 (doi: [10.1016/j.bcra.2025.100384](https://doi.org/10.1016/j.bcra.2025.100384)).\n2. Vincenzo Arceri, Saverio Mattia Merenda, Greta Dolcetti, Luca Negrini, Luca Olivieri, Enea Zaffanella. _**\"Towards a Sound Construction of EVM Bytecode Control-Flow Graphs\"**_. In Proceedings of the 26th ACM International Workshop on Formal Techniques for Java-like Programs (FTfJP 2024), co-located with ECOOP 2024 (doi: [10.1145/3678721.3686227](https://dl.acm.org/doi/10.1145/3678721.3686227)).\n\n## Table of Contents\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n  - [Environment Setup](#environment-setup)\n- [Execution Methods](#execution-methods)\n  - [Using Docker](#using-docker)\n  - [Using CLI](#using-command-line)\n- [Options](#options)\n- [The Abstract Stack Set Domain](#the-abstract-stack-set-domain)\n- [Jump Classification](#jump-classification)\n- [Usage Example](#usage-example)\n  - [Example Output](#example-output)\n- [EVMLiSA as a Library](#EVMLiSA-as-a-library)\n\n---\n\n## Requirements\n\nTo build and run EVMLiSA, you will need:\n\n- JDK 11 or higher (optional when using Docker)\n- [Gradle](https://gradle.org/releases/) 8.0 or higher (optional when using Docker)\n- [Etherscan API key](https://etherscan.io/myapikey)\n\n## Installation\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/lisa-analyzer/evm-lisa.git\n   cd evm-lisa\n   ```\n\n2. (Optional) Import the project into Eclipse or IntelliJ as a Gradle project.\n\n### Environment Setup\n\nBefore running EVMLiSA, you must configure your Etherscan API key:\n\n1. Create a `.env` file in the project root directory.\n2. Add the following line to the file:\n   ```\n   ETHERSCAN_API_KEY=\u003cyour_etherscan_api_key\u003e\n   ```\n3. Replace `\u003cyour_etherscan_api_key\u003e` with your actual key from [Etherscan](https://etherscan.io/myapikey).\n\nAlternatively, you can pass your API key directly using the `--etherscan-api-key \u003ckey\u003e` option when executing the analyzer.\n\n## Execution Methods\n\n### Using Docker\n\n1. Build the Docker container:\n   ```bash\n   mkdir -p execution/docker \u0026\u0026\n   docker build -t evm-lisa:latest .\n   ```\n\n2. Run EVMLiSA with Docker:\n   ```bash\n   docker run --rm -it \\\n   -v $(pwd)/.env:/app/.env \\\n   -v $(pwd)/execution/docker:/app/execution/results \\\n   evm-lisa:latest \\\n   [options]\n   ```\n\n   - `-v $(pwd)/.env:/app/.env`: Mounts your environment file\n   - `-v $(pwd)/execution/docker:/app/execution/results`: Shares the results directory\n\n### Using Command Line\n\n1. Build the project:\n   ```bash\n   ./gradlew assemble\n   ```\n\n2. Run EVMLiSA:\n   ```bash\n   java -jar build/libs/evm-lisa-all.jar [options]\n   ```\n\n## Options\n\n```\nOptions:\n -a,--address \u003carg\u003e                        Address of an Ethereum smart contract.\n    --abi \u003carg\u003e                            ABI of the bytecode to be analyzed (JSON format).\n    --abi-path \u003carg\u003e                       Filepath of the ABI file.\n -b,--bytecode \u003carg\u003e                       Bytecode to be analyzed (e.g., 0x6080...).\n    --benchmark \u003carg\u003e                      Filepath of the benchmark.\n    --bytecode-path \u003carg\u003e                  Filepath of the bytecode file.\n -c,--cores \u003carg\u003e                          Number of cores used in benchmark.\n    --checker-all                          Enable all security checkers.\n    --checker-reentrancy                   Enable reentrancy checker.\n    --checker-timestampdependency          Enable timestamp-dependency checker.\n    --checker-txorigin                     Enable tx-origin checker.\n    --etherscan-api-key \u003carg\u003e              Insert your Etherscan API key.\n    --link-unsound-jumps-to-all-jumpdest   Link all unsound jumps to all jumpdest.\n    --output-directory-path \u003carg\u003e          Filepath of the output directory.\n    --show-all-instructions-in-cfg         Show all instructions in the CFG representation.\n    --stack-set-size \u003carg\u003e                 Dimension of stack-set (default: 8).\n    --stack-size \u003carg\u003e                     Dimension of stack (default: 32).\n    --use-live-storage                     Use the live storage in SLOAD.\n```\n\n## The Abstract Stack Set Domain\n\nIn analyzing EVM bytecode programs, EVMLiSA employs a domain of sets of abstract stacks to enhance precision, particularly for code containing loops.\n\nThe analyzer introduces the abstract stack powerset domain $\\texttt{SetSt}_{k,h,l}$ consisting of sets of abstract stacks with at most $l$ elements and a maximum height of $h$. This domain allows the analyzer to maintain collections of abstract stacks, avoiding the need to compute the least upper bound (lub) and allowing each element of an abstract stack to be a $k$ integer set.\n\n## Jump Classification\n\nEVMLiSA classifies jump instructions in the following categories:\n\n- **Resolved**: All destinations of the jump node have been successfully resolved\n- **Definitely unreachable**: The jump node is unreachable (reached with the bottom abstract state)\n- **Maybe unreachable**: The jump node is not reachable from the entry point, but may be reachable via a potentially unsound jump node\n- **Unsound**: The jump node is reached with a stack containing an unknown numerical value that may correspond to a valid jump destination\n- **Maybe unsound**: The stack set exceeded the maximum configured stack size\n\n## Usage Example\n\nAnalyze a smart contract with specific configuration parameters:\n\n**Using Command Line:**\n```bash\njava -jar build/libs/evm-lisa-all.jar \\\n-a 0x7c21C4Bbd63D05Fa9F788e38d14e18FC52E9557B \\\n--stack-size 64 \\\n--stack-set-size 10 \\\n--link-unsound-jumps-to-all-jumpdest\n```\n\n**Using Docker:**\n```bash\ndocker run --rm -it \\\n-v $(pwd)/.env:/app/.env \\\n-v $(pwd)/execution/docker:/app/execution/results \\\nevm-lisa:latest \\\n-a 0x7c21C4Bbd63D05Fa9F788e38d14e18FC52E9557B \\\n--stack-size 64 \\\n--stack-set-size 10 \\\n--link-unsound-jumps-to-all-jumpdest\n```\n\n\u003e **Tip**: Use `docker run -a stderr` to output only the JSON report to standard output.\n\n### Example Output\n\n```\n##############\nTotal opcodes: 344\nTotal jumps: 45\nResolved jumps: 44\nDefinitely unreachable jumps: 1\nMaybe unreachable jumps: 0\nUnsound jumps: 0\nMaybe unsound jumps: 0\n##############\n```\n\n## EVMLiSA as a Library\n\nEVMLiSA can be integrated as a Java library to analyze EVM smart contracts programmatically:\n\n```java\n// Analyze by contract address\nEVMLiSA.analyzeContract(new SmartContract(\"0x123456...\"));\n\n// Analyze from bytecode file path\nEVMLiSA.analyzeContract(new SmartContract(Path.of(\"bytecode\", \"code.bytecode\")));\n\n// Analyze from bytecode string\nEVMLiSA.analyzeContract(new SmartContract().setBytecode(\"0x6080...\"));\n\n// Analyze multiple contracts\nEVMLiSA.analyzeSetOfContracts(Path.of(\"list-of-contracts.txt\"));\n```\n\n## Contributors\n\n\u003ca href=\"https://github.com/lisa-analyzer/evm-lisa/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=lisa-analyzer/evm-lisa\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flisa-analyzer%2Fevm-lisa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flisa-analyzer%2Fevm-lisa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flisa-analyzer%2Fevm-lisa/lists"}