# Quick Start
Ethereum Virtual Machine transaction tracing tool
## Dependencies
- [python3](https://www.python.org/downloads) version 3.8 to 3.11.
## 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.8",
"maintainer_email": null,
"keywords": "ethereum",
"author": "ApeWorX Ltd.",
"author_email": "admin@apeworx.io",
"download_url": "https://files.pythonhosted.org/packages/ce/78/7241a26ecf4b6a0334da407f4e0a57a67f09a05b2e8b87f5a4b5f7dbd75b/evm-trace-0.1.5.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.8 to 3.11.\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.1.5",
"project_urls": {
"Homepage": "https://github.com/ApeWorX/evm-trace"
},
"split_keywords": [
"ethereum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a6fa824368e499ee2759918602bfd1b960e92dc1f3ac11703be473a56da57cb0",
"md5": "9b4383b318e3c19febfede32d70ffe5a",
"sha256": "aed1c82c68e586c54286436944e2021bf0ff7b95cefb540b9b27ba38322b7e0a"
},
"downloads": -1,
"filename": "evm_trace-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9b4383b318e3c19febfede32d70ffe5a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 19789,
"upload_time": "2024-04-15T23:40:17",
"upload_time_iso_8601": "2024-04-15T23:40:17.459455Z",
"url": "https://files.pythonhosted.org/packages/a6/fa/824368e499ee2759918602bfd1b960e92dc1f3ac11703be473a56da57cb0/evm_trace-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ce787241a26ecf4b6a0334da407f4e0a57a67f09a05b2e8b87f5a4b5f7dbd75b",
"md5": "7a6e47c6b9929f26c436dc64394dcf21",
"sha256": "a6f8158a96b8440d42b02bafebc0bf4e7e504b9e7ca661de96968177d225cbc5"
},
"downloads": -1,
"filename": "evm-trace-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "7a6e47c6b9929f26c436dc64394dcf21",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 130696,
"upload_time": "2024-04-15T23:40:18",
"upload_time_iso_8601": "2024-04-15T23:40:18.805250Z",
"url": "https://files.pythonhosted.org/packages/ce/78/7241a26ecf4b6a0334da407f4e0a57a67f09a05b2e8b87f5a4b5f7dbd75b/evm-trace-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-15 23:40:18",
"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
