Thoth, the Cairo/Starknet bytecode analyzer, disassembler and decompiler

Thoth (pronounced "toss") is a Cairo/Starknet analyzer, disassembler & decompiler written in Python 3. Thoth's features also include the generation of the call graph and control-flow graph (CFG) of a given Cairo/Starknet compilation artifact. Demo video

Installation

sudo apt install graphviz

git clone https://github.com/FuzzingLabs/thoth && cd thoth

pip install .

thoth -h

Disassemble the contract's compilation artifact (json)

thoth -f tests/json_files/cairo_array_sum.json

To get a pretty colored version:

thoth -f tests/json_files/cairo_array_sum.json -color

To get a verbose version with more details about decoded bytecodes:

thoth -f tests/json_files/cairo_array_sum.json -vvv

Decompile the contract's compilation artifact (json)

thoth -f tests/json_files/cairo_test_addition_if.json --decompile

Example 1 with strings:

source code

decompiler code

Example 2 with function call:

source code

decompiler code

Print the contract's call graph

The call flow graph represents calling relationships between functions of the contract. We tried to provide a maximum of information, such as the entry-point functions, the imports, decorators, etc.

thoth -f tests/json_files/cairo_array_sum.json -call

The output file (pdf/svg/png) and the dot file are inside the output-callgraph folder. If needed, you can also visualize dot files online using this website. The legend can be found here.

A more complexe callgraph:

For a specific output format (pdf/svg/png):

thoth -f tests/json_files/cairo_array_sum.json -call -format png

Print the contract's control-flow graph (CFG)

thoth -f tests/json_files/cairo_double_function_and_if.json -cfg

The output file (pdf/svg/png) and the dot file are inside the output-cfg folder.

For a specific function:

thoth -f tests/json_files/cairo_double_function_and_if.json -cfg -function "__main__.main"

For a specific output format (pdf/svg/png):

thoth -f tests/json_files/cairo_double_function_and_if.json -cfg -format png

F.A.Q

How to find a Cairo/Starknet compilation artifact (json file)?

Thoth support cairo and starknet compilation artifact (json file) generated after compilation using cairo-compile or starknet-compile. Thoth also support the json file returned by: starknet get_full_contract.

How to run the tests?

python3 tests/test.py

How to build the documentation?

# Install sphinx
apt-get install python3-sphinx

#Create the docs folder
mkdir docs & cd docs

#Init the folder
sphinx-quickstart docs

#Modify the `conf.py` file by adding
import thoth

#Generate the .rst files before the .html files
sphinx-apidoc -f -o . ..

#Generate the .html files
make html

#Run a python http server
cd _build/html; python3 -m http.server

Why my bytecode is empty?

First, verify that your JSON is correct and that it contains a data section. Second, verify that your JSON is not a contract interface. Finally, it is possible that your contract does not generate bytecodes, for example:

%lang starknet

from starkware.cairo.common.cairo_builtins import HashBuiltin

@storage_var
func balance() -> (res : felt):
end

License

Thoth is licensed and distributed under the AGPLv3 license. Contact us if you're looking for an exception to the terms.

Rog3rSm1th / thoth