# EVM Indexer
EVM Indexer is a Python package designed to interact with the Ethereum Virtual Machine (EVM). It facilitates the fetching, decoding, and tracing of transactions on the Ethereum blockchain. This package is particularly useful for analyzing transaction data, including ERC20 token transfers, native Ethereum transactions, and internal contract calls with value.
## Features
* Fetching Transactions: Retrieve transactions from a specific block on the Ethereum blockchain.
* Decoding ERC20 Transfers: Extract and decode ERC20 token transfer events from transaction receipts.
* Tracing Internal Transactions: Trace internal Ethereum contract calls and operations.
* Handling Native Ethereum Transfers: Identify and process native Ethereum (ETH) transfers.
## Installation
To install the EVM Indexer package, use pip:
```bash
pip install evm_indexer
```
## Usage
Here's a quick example to demonstrate the basic functionality of the EVM Indexer package:
```python
from evm_indexer.fetcher import Fetcher
from evm_indexer.decoder import Decoder
from evm_indexer.internal_tracer import InternalTracer
from web3 import Web3
# Set the node URL
NODE_URL = 'https://seed.omchain.io'
# Initialize fetcher, decoder, and internal tracer
fetcher = Fetcher(NODE_URL, is_poa=True)
decoder = Decoder(fetcher=fetcher)
internal_tracer = InternalTracer(NODE_URL)
# Fetch transactions from a specific block
fetched_transactions = fetcher.fetch_transactions_in_block(32582884)
# Process each transaction
tx_receipts = [internal_tracer.get_tx_receipt(tx['hash'])['result'] for tx in fetched_transactions]
tx_data = {tx_receipt['transactionHash']: [internal_tracer.get_trace(tx_receipt['transactionHash']), tx_receipt] for tx_receipt in tx_receipts if tx_receipt['status'] == '0x1'}
# Extract different types of transactions
erc20_transactions = [decoder.get_erc20_transfers_from_tx(tx_data[tx][1]) for tx in tx_data]
native_transactions = [decoder.get_native_transfers_from_tx(tx_data[tx][1]['transactionHash']) for tx in tx_data]
internal_transactions = [internal_tracer.capture_internal_calls(tx_data[tx][0], tx_data[tx][1]) for tx in tx_data]
# Print the transactions
print('ERC20 Transactions:', erc20_transactions)
print('Native Transactions:', native_transactions)
print('Internal Transactions:', internal_transactions)
```
And the example output;
```bash
ERC20 Transactions:
{'from': '0xe6F4967DD4F6dC31DE2c5C047cE931f74d92ba8C', 'to': '0x7c6ed537aa6348aF18AbCdf3Cf417882c95060de', 'amount': 148062317306291907612, 'token_address': '0x779da1b95e81de928fbe9f293629a346f88e86f7'}
Native Transactions:
{'from': '0xe210a02ED752624d70c325688c9fdC1ccC97d81F', 'to': '0xcDa8C9991f725fF4fa6369FBC0A4F1Ab51Eae354', 'amount': 20000000000000000000000, 'token_address': None}
Internal Transactions:
{'op': 'CALL', 'from': '0xe6f4967dd4f6dc31de2c5c047ce931f74d92ba8c', 'to': '0x779da1b95e81de928fbe9f293629a346f88e86f7', 'value': 0}
```
## Modules and Methods
### Fetcher (`fetcher.py`)
**Class Description:**
Handles the retrieval of blockchain data from an Ethereum node.
- **`__init__(self, node_endpoint, is_poa=True)`**
Constructor for the Fetcher class.
**Parameters:**
- `node_endpoint` (str): The URL of the Ethereum node.
- `is_poa` (bool, optional): Indicates if the node is part of a Proof of Authority network. Default is `True`.
- **`fetch_block(self, block_number)`**
Fetches a complete block using its number.
**Parameters:**
- `block_number` (int): The number of the block to fetch.
**Returns:**
- `dict`: The block data, or `None` if fetching fails.
- **`fetch_latest_block_number(self)`**
Retrieves the number of the most recent block on the blockchain.
**Returns:**
- `int`: The latest block number.
- **`fetch_blocks_in_range(self, start_block, end_block)`**
Fetches all blocks within a specified range.
**Parameters:**
- `start_block` (int): The starting block number.
- `end_block` (int): The ending block number.
**Returns:**
- `list`: A list of block data within the specified range.
- **`fetch_transactions_in_block(self, block_number)`**
Retrieves all transactions from a specific block.
**Parameters:**
- `block_number` (int): The block number to fetch transactions from.
**Returns:**
- `list`: A list of transactions in the specified block.
- **`fetch_transactions_in_range(self, start_block, end_block)`**
Fetches transactions within a specified block range.
**Parameters:**
- `start_block` (int): The starting block number.
- `end_block` (int): The ending block number.
**Returns:**
- `list`: A list of transactions across the specified range of blocks.
### Decoder (`decoder.py`)
**Class Description:**
Decodes transaction data to extract specific information, such as ERC20 token transfers and native Ethereum transfers.
- **`__init__(self, fetcher)`**
Constructor for the Decoder class.
**Parameters:**
- `fetcher` (Fetcher): An instance of the Fetcher class used to fetch blockchain data.
- **`get_erc20_transfers_from_tx(self, tx_receipt)`**
Extracts ERC20 token transfers from a transaction receipt.
**Parameters:**
- `tx_receipt` (dict): The transaction receipt containing logs.
**Returns:**
- `list`: A list of decoded ERC20 transfer events.
- **`get_native_transfers_from_tx(self, tx_hash)`**
Retrieves and decodes native Ethereum (ETH) transfers from a transaction.
**Parameters:**
- `tx_hash` (str): The hash of the transaction.
**Returns:**
- `list`: A list containing the details of native ETH transfers, if any.
### InternalTracer (`internal_tracer.py`)
**Class Description:**
Traces internal Ethereum transactions and contract calls for detailed analysis.
- **`__init__(self, node_endpoint)`**
Constructor for the InternalTracer class.
**Parameters:**
- `node_endpoint` (str): The URL of the Ethereum node.
- **`get_tx_receipt(self, tx_hash)`**
Fetches the receipt of a given transaction.
**Parameters:**
- `tx_hash` (str): The hash of the transaction.
**Returns:**
- `dict`: The transaction receipt, or `None` if fetching fails.
- **`get_trace(self, tx_hash)`**
Retrieves the trace of a given transaction.
**Parameters:**
- `tx_hash` (str): The hash of the transaction.
**Returns:**
- `dict`: The transaction trace data, or `None` if fetching fails.
- **`capture_internal_calls(self, trace_response, tx_receipt)`**
Captures and processes internal contract calls and operations from a transaction trace.
**Parameters:**
- `trace_response` (dict): The response object from `get_trace`.
- `tx_receipt` (dict): The transaction receipt object.
**Returns:**
- `list`: A list of captured internal calls with their details.
## Contributing
Contributions to the EVM Indexer package are welcome. Please feel free to fork the repository, make changes, and submit pull requests.
## License
This project is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": "https://github.com/OmchainFoundation/evm-indexer",
"name": "evm-indexer",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Omchain Foundation",
"author_email": "info@omchain.io",
"download_url": "https://files.pythonhosted.org/packages/b1/b8/ed6e7dbd2e70314c7e4a3aca99ad04578195b1593ab949d2cf0d4e40cda6/evm_indexer-0.0.2.tar.gz",
"platform": null,
"description": "# EVM Indexer\r\nEVM Indexer is a Python package designed to interact with the Ethereum Virtual Machine (EVM). It facilitates the fetching, decoding, and tracing of transactions on the Ethereum blockchain. This package is particularly useful for analyzing transaction data, including ERC20 token transfers, native Ethereum transactions, and internal contract calls with value.\r\n\r\n## Features\r\n* Fetching Transactions: Retrieve transactions from a specific block on the Ethereum blockchain.\r\n* Decoding ERC20 Transfers: Extract and decode ERC20 token transfer events from transaction receipts.\r\n* Tracing Internal Transactions: Trace internal Ethereum contract calls and operations.\r\n* Handling Native Ethereum Transfers: Identify and process native Ethereum (ETH) transfers.\r\n\r\n## Installation\r\nTo install the EVM Indexer package, use pip:\r\n\r\n```bash\r\npip install evm_indexer\r\n```\r\n\r\n## Usage\r\nHere's a quick example to demonstrate the basic functionality of the EVM Indexer package:\r\n\r\n```python\r\nfrom evm_indexer.fetcher import Fetcher\r\nfrom evm_indexer.decoder import Decoder\r\nfrom evm_indexer.internal_tracer import InternalTracer\r\nfrom web3 import Web3\r\n\r\n# Set the node URL\r\nNODE_URL = 'https://seed.omchain.io'\r\n\r\n# Initialize fetcher, decoder, and internal tracer\r\nfetcher = Fetcher(NODE_URL, is_poa=True)\r\ndecoder = Decoder(fetcher=fetcher)\r\ninternal_tracer = InternalTracer(NODE_URL)\r\n\r\n# Fetch transactions from a specific block\r\nfetched_transactions = fetcher.fetch_transactions_in_block(32582884)\r\n\r\n# Process each transaction\r\ntx_receipts = [internal_tracer.get_tx_receipt(tx['hash'])['result'] for tx in fetched_transactions]\r\ntx_data = {tx_receipt['transactionHash']: [internal_tracer.get_trace(tx_receipt['transactionHash']), tx_receipt] for tx_receipt in tx_receipts if tx_receipt['status'] == '0x1'}\r\n\r\n# Extract different types of transactions\r\nerc20_transactions = [decoder.get_erc20_transfers_from_tx(tx_data[tx][1]) for tx in tx_data]\r\nnative_transactions = [decoder.get_native_transfers_from_tx(tx_data[tx][1]['transactionHash']) for tx in tx_data]\r\ninternal_transactions = [internal_tracer.capture_internal_calls(tx_data[tx][0], tx_data[tx][1]) for tx in tx_data]\r\n\r\n# Print the transactions\r\nprint('ERC20 Transactions:', erc20_transactions)\r\nprint('Native Transactions:', native_transactions)\r\nprint('Internal Transactions:', internal_transactions)\r\n```\r\n\r\nAnd the example output;\r\n\r\n```bash\r\nERC20 Transactions:\r\n{'from': '0xe6F4967DD4F6dC31DE2c5C047cE931f74d92ba8C', 'to': '0x7c6ed537aa6348aF18AbCdf3Cf417882c95060de', 'amount': 148062317306291907612, 'token_address': '0x779da1b95e81de928fbe9f293629a346f88e86f7'}\r\nNative Transactions:\r\n{'from': '0xe210a02ED752624d70c325688c9fdC1ccC97d81F', 'to': '0xcDa8C9991f725fF4fa6369FBC0A4F1Ab51Eae354', 'amount': 20000000000000000000000, 'token_address': None}\r\nInternal Transactions:\r\n{'op': 'CALL', 'from': '0xe6f4967dd4f6dc31de2c5c047ce931f74d92ba8c', 'to': '0x779da1b95e81de928fbe9f293629a346f88e86f7', 'value': 0}\r\n```\r\n\r\n## Modules and Methods\r\n\r\n### Fetcher (`fetcher.py`)\r\n\r\n**Class Description:** \r\nHandles the retrieval of blockchain data from an Ethereum node.\r\n\r\n- **`__init__(self, node_endpoint, is_poa=True)`** \r\n Constructor for the Fetcher class. \r\n **Parameters:**\r\n - `node_endpoint` (str): The URL of the Ethereum node.\r\n - `is_poa` (bool, optional): Indicates if the node is part of a Proof of Authority network. Default is `True`.\r\n\r\n- **`fetch_block(self, block_number)`** \r\n Fetches a complete block using its number. \r\n **Parameters:**\r\n - `block_number` (int): The number of the block to fetch. \r\n **Returns:** \r\n - `dict`: The block data, or `None` if fetching fails.\r\n\r\n- **`fetch_latest_block_number(self)`** \r\n Retrieves the number of the most recent block on the blockchain. \r\n **Returns:** \r\n - `int`: The latest block number.\r\n\r\n- **`fetch_blocks_in_range(self, start_block, end_block)`** \r\n Fetches all blocks within a specified range. \r\n **Parameters:**\r\n - `start_block` (int): The starting block number.\r\n - `end_block` (int): The ending block number. \r\n **Returns:** \r\n - `list`: A list of block data within the specified range.\r\n\r\n- **`fetch_transactions_in_block(self, block_number)`** \r\n Retrieves all transactions from a specific block. \r\n **Parameters:**\r\n - `block_number` (int): The block number to fetch transactions from. \r\n **Returns:** \r\n - `list`: A list of transactions in the specified block.\r\n\r\n- **`fetch_transactions_in_range(self, start_block, end_block)`** \r\n Fetches transactions within a specified block range. \r\n **Parameters:**\r\n - `start_block` (int): The starting block number.\r\n - `end_block` (int): The ending block number. \r\n **Returns:** \r\n - `list`: A list of transactions across the specified range of blocks.\r\n\r\n### Decoder (`decoder.py`)\r\n\r\n**Class Description:** \r\nDecodes transaction data to extract specific information, such as ERC20 token transfers and native Ethereum transfers.\r\n\r\n- **`__init__(self, fetcher)`** \r\n Constructor for the Decoder class. \r\n **Parameters:**\r\n - `fetcher` (Fetcher): An instance of the Fetcher class used to fetch blockchain data.\r\n\r\n- **`get_erc20_transfers_from_tx(self, tx_receipt)`** \r\n Extracts ERC20 token transfers from a transaction receipt. \r\n **Parameters:**\r\n - `tx_receipt` (dict): The transaction receipt containing logs. \r\n **Returns:** \r\n - `list`: A list of decoded ERC20 transfer events.\r\n\r\n- **`get_native_transfers_from_tx(self, tx_hash)`** \r\n Retrieves and decodes native Ethereum (ETH) transfers from a transaction. \r\n **Parameters:**\r\n - `tx_hash` (str): The hash of the transaction. \r\n **Returns:** \r\n - `list`: A list containing the details of native ETH transfers, if any.\r\n\r\n### InternalTracer (`internal_tracer.py`)\r\n\r\n**Class Description:** \r\nTraces internal Ethereum transactions and contract calls for detailed analysis.\r\n\r\n- **`__init__(self, node_endpoint)`** \r\n Constructor for the InternalTracer class. \r\n **Parameters:**\r\n - `node_endpoint` (str): The URL of the Ethereum node.\r\n\r\n- **`get_tx_receipt(self, tx_hash)`** \r\n Fetches the receipt of a given transaction. \r\n **Parameters:**\r\n - `tx_hash` (str): The hash of the transaction. \r\n **Returns:** \r\n - `dict`: The transaction receipt, or `None` if fetching fails.\r\n\r\n- **`get_trace(self, tx_hash)`** \r\n Retrieves the trace of a given transaction. \r\n **Parameters:**\r\n - `tx_hash` (str): The hash of the transaction. \r\n **Returns:** \r\n - `dict`: The transaction trace data, or `None` if fetching fails.\r\n\r\n- **`capture_internal_calls(self, trace_response, tx_receipt)`** \r\n Captures and processes internal contract calls and operations from a transaction trace. \r\n **Parameters:**\r\n - `trace_response` (dict): The response object from `get_trace`.\r\n - `tx_receipt` (dict): The transaction receipt object. \r\n **Returns:** \r\n - `list`: A list of captured internal calls with their details.\r\n\r\n\r\n\r\n## Contributing\r\nContributions to the EVM Indexer package are welcome. Please feel free to fork the repository, make changes, and submit pull requests.\r\n\r\n## License\r\nThis project is licensed under the MIT License.\r\n",
"bugtrack_url": null,
"license": "LICENSE",
"summary": "EVM compatible blockchain indexer",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/OmchainFoundation/evm-indexer"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "76b5d98e3dd2bea017e6c637a4bc282aedab58e06a85e60175c621a17031c8b9",
"md5": "dd020b6b21d870b91d982aae26eae9cd",
"sha256": "baf579c698fdca580530d2e4348f0aca5a996f623fd7081077a65fd57c6df2a7"
},
"downloads": -1,
"filename": "evm_indexer-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dd020b6b21d870b91d982aae26eae9cd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6925,
"upload_time": "2023-12-28T14:40:57",
"upload_time_iso_8601": "2023-12-28T14:40:57.915041Z",
"url": "https://files.pythonhosted.org/packages/76/b5/d98e3dd2bea017e6c637a4bc282aedab58e06a85e60175c621a17031c8b9/evm_indexer-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b1b8ed6e7dbd2e70314c7e4a3aca99ad04578195b1593ab949d2cf0d4e40cda6",
"md5": "f964fca350173f01ae235f1273ec627e",
"sha256": "108eb40c9175913a52b82a0badcaf325e3d89229fd21e42722c28454e8c15794"
},
"downloads": -1,
"filename": "evm_indexer-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "f964fca350173f01ae235f1273ec627e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7167,
"upload_time": "2023-12-28T14:40:59",
"upload_time_iso_8601": "2023-12-28T14:40:59.945637Z",
"url": "https://files.pythonhosted.org/packages/b1/b8/ed6e7dbd2e70314c7e4a3aca99ad04578195b1593ab949d2cf0d4e40cda6/evm_indexer-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-28 14:40:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OmchainFoundation",
"github_project": "evm-indexer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "evm-indexer"
}
JSON
