ressac-project (the toolset developed for the experiment for the paper of FC23)

Components

A transactions retriever from Ethereum Mainnet (modules in Transactions_Retriever/ here)
An EVM tracer (evm_tracing.js here)
An Ethereum transaction storage extractor depending on the EVM tracer (extract_storage.py here)
A hash dictionary file including Keccak256 key-value pairs, can be empty by default (hash_dict_backup.txt here)
The sliding-window detector (sliding_window_detector.py here), with the alert reporter integrated into it

Data and Results

Lists of transactions involved a subject contract, retrieved by the transactions retriever (in Transactions_Retriever/contracts_related_tx_idx_lists/ here)
Storage update facts (extraction results, in Folders_of_Storage_Update_Facts/ here)
Alert level plots, generated by the sliding-window detector (in Alert_Level_Plots/ here)
Alert reports, output of the detector and alert reporter (in Alert_Reports/ here)

Step-by-Step Guides

Transactions Retrieving (inside Transactions_Retriever/ folder)

First, run the bash script internal_txn_tracer.sh to fetch the raw transaction list, in which the variable "addr" can be customized;

Then, run the python script get_txn_detail.py to access the Ethereum Mainnet node to get the detailed transaction list;

Finally, if the list is in reverse order of timestamp, run "python3 reverse_list.py <list_of_transaction_filename>" to make it in order of timestamp.

Extraction

Usage of the extractor v1: command line, python3 extract_storage.py <list_of_transaction_filename> <hash_dictionary_file_name> [-n |-t <thread_count>|-h|]

Options: -n to give the contract name as a prefix of extraction facts' folder name, -t to specify the number of threads to run, -h to backup hash dictionary before extraction

Compatible with python 3.9 or older version

Detection and Alert Reporting

Usage of the sliding-window detector (integrated with the alert reporter): python3 sliding_window_detector.py <contract_address> [tx_idx_list_filename, [storage_update_facts_path, [width of slide window, [width of median filter, [threshold of absolute deviation]]]]]

The argument list:

1. 1st (Compulsory) - address of the subject contract
2. 2nd (Optional, default value "tx_idx_list.txt") - filename of txn list of the subject contract
3. 3rd (Optional, default value "Storage_Update_Facts/" - path of the facts files directory generated by the extractor
4. 4th (Optional, parameter of the sliding-window detector) - width of slide window
5. 5th (Optional, parameter of the sliding-window detector) - width of median filter
6. 6th (Optional, parameter of the sliding-window detector) - threshold of absolute deviation to determine abnormality

The detector and alert reporter first generates a plot of alert level of all the transactions, which can be saved in Alert_Level_Plots/; then it outputs alerted transactions with ordering, timestamp (if available) and hash, which can be saved in Alert_Reports/.