Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ApeWorX/evm-trace
Ethereum Virtual Machine transaction tracing tool
https://github.com/ApeWorX/evm-trace
ethereum python smart-contracts web3
Last synced: about 1 month ago
JSON representation
Ethereum Virtual Machine transaction tracing tool
- Host: GitHub
- URL: https://github.com/ApeWorX/evm-trace
- Owner: ApeWorX
- License: apache-2.0
- Created: 2022-03-17T22:58:52.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-08-26T16:27:43.000Z (4 months ago)
- Last Synced: 2024-09-27T17:17:29.811Z (3 months ago)
- Topics: ethereum, python, smart-contracts, web3
- Language: Python
- Size: 1.09 MB
- Stars: 299
- Watchers: 5
- Forks: 28
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-web3-tools-and-dapps - ApeWorx EVM Trace - Trace the transactions of the Ethereum Virtual Machine using ApeWorx's tracing tool. (dApps directory / Debugging Tools)
- On-Chain-Investigations-Tools-List - evm-trace
README
# Quick Start
Ethereum Virtual Machine transaction tracing tool
## Dependencies
- [python3](https://www.python.org/downloads) version 3.9 to 3.12.
## Installation
### via `pip`
You can install the latest release via [`pip`](https://pypi.org/project/pip/):
```bash
pip install evm-trace
```
### via `setuptools`
You can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:
```bash
git clone https://github.com/ApeWorX/evm-trace.git
cd evm-trace
python3 setup.py install
```
## Quick Usage
### Geth Style Traces
If you are using a node that supports the `debug_traceTransaction` RPC, you can use `web3.py` to get trace frames:
```python
from web3 import HTTPProvider, Web3
from evm_trace import TraceFrame
web3 = Web3(HTTPProvider("https://path.to.my.node"))
txn_hash = "0x..."
struct_logs = web3.manager.request_blocking("debug_traceTransaction", [txn_hash]).structLogs
for item in struct_logs:
frame = TraceFrame.model_validate(item)
```
If you want to get the call-tree node, you can do:
```python
from evm_trace import CallType, get_calltree_from_geth_trace
root_node_kwargs = {
"gas_cost": 10000000,
"gas_limit": 10000000000,
"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"calldata": "0x00",
"value": 1000,
"call_type": CallType.CALL,
}
# Where `trace` is a `TraceFrame` (see example above)
calltree = get_calltree_from_geth_trace(trace, **root_node_kwargs)
```
### Parity Style Traces
If you are using a node that supports the `trace_transaction` RPC, you can use `web3.py` to get trace objects:
```python
from evm_trace import CallType, ParityTraceList
raw_trace_list = web3.manager.request_blocking("trace_transaction", [txn_hash])
trace_list = ParityTraceList.model_validate(raw_trace_list)
```
And to make call-tree nodes, you can do:
```python
from evm_trace import get_calltree_from_parity_trace
tree = get_calltree_from_parity_trace(trace_list)
```
### Gas Reports
If you are using a node that supports creating traces, you can get a gas report.
```python
from evm_trace.gas import get_gas_report
# see examples above for creating a calltree
calltree = get_calltree_from_geth_trace(trace, **root_node_kwargs)
gas_report = get_gas_report(calltree)
```
For a more custom report, use the `merge_reports` method to combine a list of reports into a single report.
Pass two or more `Dict[Any, Dict[Any, List[int]]]` to combine reports where `List[int]` is the gas used.
Customize the values of `Any` accordingly:
1. The first `Any` represents the bytes from the address.
2. The second `Any` represents the method selector.
For example, you may replace addresses with token names or selector bytes with signature call strings.
Import the method like so:
```python
from evm_trace.gas import merge_reports
```
## Development
This project is in development and should be considered a beta.
Things might not be in their final state and breaking changes may occur.
Comments, questions, criticisms and pull requests are welcomed.
## License
This project is licensed under the [Apache 2.0](LICENSE).