Artwork By Peter Kacherginsky at blockthreat.com
This repository contains the code for the core implementation of HOUSTON.
Note: This repository contains the research prototype used for the experiments in the paper. Some auxiliary components and internal tooling used during development are not included.
./install.sh
To properly emit storage layout reports for contracts, we had to perform some modifications to old version of the Solidity compiler. More specifically, we fixed the following solc versions:
solc-v0.5.8solc-v0.5.10solc-v0.5.11solc-v0.5.12
You can find these binaries in the solc-binaries folder.
be02011efd6c6afd27cda02871bd70b3 solc-v0.5.10
95a6e066632d86a3991ba647908a87aa solc-v0.5.11
81355fdac6ef2e8beecb272058d77e0d solc-v0.5.12
4821f4120ba07eb89166fcc31274e282 solc-v0.5.8
Place these binaries in ~/.ethcx/solc/.
To properly run, HOUSTON requires access to an Erigon archive node (there are some Erigon specific requests in the code).
Additionally, the Erigon node should install our plugin houston.go.
HOUSTON requires access to a blockchain index database that can provide historical information regarding Ethereum's transactions.
Specifically, the index database should provide 3 methods:
-
get_created_by_deployer(address)--> returns all the contracts created by a certain deployer. Refer to our implementation in thepg.pyfile. -
get_all_transactions_by_address_and_block(addr, max_block)--> returns all the transaction (and internal transaction) for which addr was either the sender or the receiver. Themax_blockset the last block to consider for collection. Refer to our implementation in thepg.pyfile. -
get_all_transactions_by_address_and_block_and_start_at(addr, min_block, max_block)--> returns all the transaction (and internal transaction) for which addr was either the sender or the receiver. Themin_blockset the first block to consider for collection. Themax_blockset the last block to consider for collection. Refer to our implementation in thepg.pyfile.
Finally, export the following enviornment variables:
export WEB3_ENDPOINT_URL="ws://yourErigonEndpointURL:8545"
export HOUSTON_WORKDIR="/path/to/houston-release/"The first step is collecting all the data regarding the transactions that interacted with the protocol prior to the attack. To do so, an entry in the defi-incidents.csv is required.
This is the format:
Protocol Name | Attacked Contract | Protocol Type | Attack Date | Attack Block | Attack Transaction
Polynetwork,0x838bf9e95cb12dd76a54c9f9d2e3082eaf928270,Bridge,08/10/2021,12996659,0xb1f70464bd95b774c6ce60fc706eb5f9e35cb5f06e6cfe7c17dcda46ffd59581
Then, simply:
python run.pyTo reproduce the setup for historical DeFi incidents, run the following:
python -m houston.protocol --proto <proto_name> [--noreload]
python -m houston.splitter --proto <proto_name>These commands generate intermediate data for the collected transactions under workspace/.
The Interaction Model also uses this step to generate the necessary transaction signatures.
We implemented a minimalistic invariant engine in carrot.py (we think it’s tastier than Daikon).
To extract invariants from past transactions, put the target protocols in input/targets.txt and run:
./run_bunny_run.sh --targets targets.txt --action train --jobs <n_jobs>Once invariants are extracted, check invariant violations on new transactions in the evaluation period:
./run_bunny_run.sh --targets targets.txt --action test --jobs <n_jobs>To view the results:
python -m houston.checker --target targets.txt --debugThis will start an interactive session where you can inspect:
df: a summary of the processed transactionsvios: invariant violationsinv_alarms: alerts raised by the Invariant Modelint_alarms: alerts raised by the Interaction Model
In the /dataset folder, we have shared the collection of DeFi incidents used to evaluate our work.
The dataset includes information about each attack analyzed by HOUSTON, including a write-up, the reference transaction hash, and the corresponding block number.
In this repo, we include only the Polynetwork example due to the large size of the raw data required.
Artwork By Peter Kacherginsky at blockthreat.com
In the folder example/polynetwork, we place all the data generated by running our pipeline on the Polynetwork protocol.
In example/polynetwork/proto you can find all the data generated when analyzing the protocol (e.g., contracts addresses, transactions, contracts' analyses).
In example/polynetwork/data you can find all the information
collected regarding Polynetwork transactions from block 0, up to block 12996659 - the block of the Polynetwork attack transaction.
For historical DeFi incident example Polynetwork, run the following:
python -m houston.protocol --proto polynetwork --noreload
python -m houston.splitter --proto polynetwork
./run_bunny_run.sh --targets targets.txt --action train --jobs 10
./run_bunny_run.sh --targets targets.txt --action test --jobs 10
python -m houston.checker --target targets.txt --debugNote that the code here assumes HOUSTON is initialized with historical transactions and evaluates on the last 30 days of traffic (instead of cold start with zero history). This behavior can be changed by setting EVAL_DAYS in input/config.py.
The LLM-based comparable-pair selection component is also not included in this repository.
For the PolyNetwork example:
- The Interaction Model raises no alerts during the evaluation period.
- The Invariant Model flags one single suspicious transaction — the actual attack.
✅ Result: HOUSTON successfully identifies the attack with zero false positives.

