# 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).
Raw data
{
"_id": null,
"home_page": "https://github.com/ApeWorX/evm-trace",
"name": "evm-trace",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.9",
"maintainer_email": null,
"keywords": "ethereum",
"author": "ApeWorX Ltd.",
"author_email": "admin@apeworx.io",
"download_url": "https://files.pythonhosted.org/packages/ac/82/a9773918d90963a3060c67522d96de7f81c79f1248d114ba9d57da5ba2b2/evm_trace-0.2.4.tar.gz",
"platform": null,
"description": "# Quick Start\n\nEthereum Virtual Machine transaction tracing tool\n\n## Dependencies\n\n- [python3](https://www.python.org/downloads) version 3.9 to 3.12.\n\n## Installation\n\n### via `pip`\n\nYou can install the latest release via [`pip`](https://pypi.org/project/pip/):\n\n```bash\npip install evm-trace\n```\n\n### via `setuptools`\n\nYou can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:\n\n```bash\ngit clone https://github.com/ApeWorX/evm-trace.git\ncd evm-trace\npython3 setup.py install\n```\n\n## Quick Usage\n\n### Geth Style Traces\n\nIf you are using a node that supports the `debug_traceTransaction` RPC, you can use `web3.py` to get trace frames:\n\n```python\nfrom web3 import HTTPProvider, Web3\nfrom evm_trace import TraceFrame\n\nweb3 = Web3(HTTPProvider(\"https://path.to.my.node\"))\ntxn_hash = \"0x...\"\nstruct_logs = web3.manager.request_blocking(\"debug_traceTransaction\", [txn_hash]).structLogs\nfor item in struct_logs:\n frame = TraceFrame.model_validate(item)\n```\n\nIf you want to get the call-tree node, you can do:\n\n```python\nfrom evm_trace import CallType, get_calltree_from_geth_trace\n\nroot_node_kwargs = {\n \"gas_cost\": 10000000,\n \"gas_limit\": 10000000000,\n \"address\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\",\n \"calldata\": \"0x00\",\n \"value\": 1000,\n \"call_type\": CallType.CALL,\n}\n\n# Where `trace` is a `TraceFrame` (see example above)\ncalltree = get_calltree_from_geth_trace(trace, **root_node_kwargs)\n```\n\n### Parity Style Traces\n\nIf you are using a node that supports the `trace_transaction` RPC, you can use `web3.py` to get trace objects:\n\n```python\nfrom evm_trace import CallType, ParityTraceList\n\nraw_trace_list = web3.manager.request_blocking(\"trace_transaction\", [txn_hash])\ntrace_list = ParityTraceList.model_validate(raw_trace_list)\n```\n\nAnd to make call-tree nodes, you can do:\n\n```python\nfrom evm_trace import get_calltree_from_parity_trace\n\ntree = get_calltree_from_parity_trace(trace_list)\n```\n\n### Gas Reports\n\nIf you are using a node that supports creating traces, you can get a gas report.\n\n```python\nfrom evm_trace.gas import get_gas_report\n\n# see examples above for creating a calltree\ncalltree = get_calltree_from_geth_trace(trace, **root_node_kwargs)\n\ngas_report = get_gas_report(calltree)\n```\n\nFor a more custom report, use the `merge_reports` method to combine a list of reports into a single report.\nPass two or more `Dict[Any, Dict[Any, List[int]]]` to combine reports where `List[int]` is the gas used.\n\nCustomize the values of `Any` accordingly:\n\n1. The first `Any` represents the bytes from the address.\n2. The second `Any` represents the method selector.\n\nFor example, you may replace addresses with token names or selector bytes with signature call strings.\n\nImport the method like so:\n\n```python\nfrom evm_trace.gas import merge_reports\n```\n\n## Development\n\nThis project is in development and should be considered a beta.\nThings might not be in their final state and breaking changes may occur.\nComments, questions, criticisms and pull requests are welcomed.\n\n## License\n\nThis project is licensed under the [Apache 2.0](LICENSE).\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "evm-trace: Ethereum Virtual Machine transaction tracing tool",
"version": "0.2.4",
"project_urls": {
"Homepage": "https://github.com/ApeWorX/evm-trace"
},
"split_keywords": [
"ethereum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6f80327de5d48b31179dc41ec349087db0ec1de8854bcf94e72837415a60b64e",
"md5": "6cb4b43f20ce2ed88541b4a3fe82df37",
"sha256": "697ef22cf50a0aede0e06cc6c236b381a9686d20eb969a807485985a9b027581"
},
"downloads": -1,
"filename": "evm_trace-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6cb4b43f20ce2ed88541b4a3fe82df37",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.9",
"size": 21073,
"upload_time": "2024-12-05T00:01:00",
"upload_time_iso_8601": "2024-12-05T00:01:00.591492Z",
"url": "https://files.pythonhosted.org/packages/6f/80/327de5d48b31179dc41ec349087db0ec1de8854bcf94e72837415a60b64e/evm_trace-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ac82a9773918d90963a3060c67522d96de7f81c79f1248d114ba9d57da5ba2b2",
"md5": "7b35ca12f5e1cc0e70a15930a8518b5d",
"sha256": "15b4e7986dd0d934ac9db3ce2a8ed418ff3b116c4ec3eb696d585366b4789866"
},
"downloads": -1,
"filename": "evm_trace-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "7b35ca12f5e1cc0e70a15930a8518b5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.9",
"size": 772929,
"upload_time": "2024-12-05T00:01:02",
"upload_time_iso_8601": "2024-12-05T00:01:02.453527Z",
"url": "https://files.pythonhosted.org/packages/ac/82/a9773918d90963a3060c67522d96de7f81c79f1248d114ba9d57da5ba2b2/evm_trace-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-05 00:01:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ApeWorX",
"github_project": "evm-trace",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "evm-trace"
}
JSON
