Metadata-Version: 2.1
Name: eth-event
Version: 0.2.2
Summary: Ethereum event decoder and topic generator
Home-page: https://github.com/iamdefinitelyahuman/eth-event
Author: Benjamin Hauser
Author-email: b.hauser@zerolaw.tech
License: MIT
Keywords: ethereum
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.6, <4
Description-Content-Type: text/markdown
Requires-Dist: eth-abi (<3.0.0,>=2.0.0)
Requires-Dist: eth-hash[pycryptodome] (<1.0.0,>=0.2.0)
Requires-Dist: hexbytes (<1.0.0,>=0.2.0)

# eth-event

[![Pypi Status](https://img.shields.io/pypi/v/eth-event.svg)](https://pypi.org/project/eth-event/) [![Build Status](https://img.shields.io/travis/com/iamdefinitelyahuman/eth-event.svg)](https://travis-ci.com/iamdefinitelyahuman/eth-event) [![Coverage Status](https://coveralls.io/repos/github/iamdefinitelyahuman/eth-event/badge.svg?branch=master)](https://coveralls.io/github/iamdefinitelyahuman/eth-event?branch=master)

Tools for Ethereum event decoding and topic generation.

## Installation

You can install the latest release via ``pip``:

```bash
$ pip install eth-brownie
```

Or clone the repository and use ``setuptools`` for the most up-to-date version:

```bash
$ python3 setup.py install
```

## Usage

The package includes the following functions:

* `get_event_topic(event_abi)`: Given an event ABI, returns the 32 byte encoded topic as a string.

```python
>>> from eth_event import get_event_topic
>>> get_event_topic({'name': 'Approval', 'anonymous': False, 'type': 'event', 'inputs': [{'name': 'owner', 'type': 'address', 'indexed': True}, {'name': 'spender', 'type': 'address', 'indexed': True}, {'name': 'value', 'type': 'uint256', 'indexed': False}]})
'0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925'
```

* `get_topics(contract_abi)`: Given a contract ABI, returns a dictionary of `{'event name': "encrypted topic"}`.

```python
>>> from eth_event import get_topics
>>> abi = [{'name': 'Approval', 'anonymous': False, 'type': 'event', 'inputs': [{'name': 'owner', 'type': 'address', 'indexed': True}, {'name': 'spender', 'type': 'address', 'indexed': True}, {'name': 'value', 'type': 'uint256', 'indexed': False}]}, {'name': 'Transfer', 'anonymous': False, 'type': 'event', 'inputs': [{'name': 'from', 'type': 'address', 'indexed': True}, {'name': 'to', 'type': 'address', 'indexed': True}, {'name': 'value', 'type': 'uint256', 'indexed': False}]}]
>>> get_topics(abi)
{
    'Transfer': '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
    'Approval': '0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925'
}
```

* `get_event_abi(contract_abi)`: Given a contract ABI, returns a dictionary of `{'encrypted topic': "ABI"}`. Useful for stripping an ABI so that only event related data remains.

```python
>>> from eth_event import get_event_abi
>>> get_event_abi(abi)
{
    '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef': {
        'name': 'Transfer',
        'inputs': [{'name': 'from', 'type': 'address', 'indexed': True}, {'name': 'to', 'type': 'address', 'indexed': True}, {'name': 'value', 'type': 'uint256', 'indexed': False}]
    },
    '0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925': {
        'name': 'Approval',
        'inputs': [{'name': 'owner', 'type': 'address', 'indexed': True}, {'name': 'spender', 'type': 'address', 'indexed': True}, {'name': 'value', 'type': 'uint256', 'indexed': False}]
    }
}
```

* `decode_event(event, abi)`: Given a single event from a transaction log and an ABI, returns the decoded event. The ABI may supplied in the normal contract format, or as a dictionary value generated by `get_event_abi`

```python
>>> tx = token.transfer(account[1], 100, {'from': account[0]})
<Transaction object '0xd0b9f575747eafdce3ba6ee8d6c16146bfff35cb86bec0a1909ab04fa94fc024'>
>>> log = tx.logs[0]
>>> eth_event.decode_event(log, token.abi)
[{
    'name': 'Transfer',
    'data': [
        {'name': 'from', 'type': 'address', 'value': '0xbd4940951bfa463f8fb6db762e55686f6cfdb73a', 'decoded': True},
        {'name': 'to', 'type': 'address', 'value': '0xbd4940951bfa463f8fb6db762e55686f6cfdb73a', 'decoded': True},
        {'name': 'tokens', 'type': 'uint256', 'value': 100, 'decoded': True}
    ]
}]
```

* `decode_logs(logs, abi, skip_anonymous=True)`: Given an entire transaction log and an ABI, returns the decoded events. The ABI may be supplied in the normal format, or as a dictionary value generated by `get_event_abi`

```python
>>> tx = token.transfer(account[1], 100, {'from': account[0]})
<Transaction object '0x615a157e84715d5f960a38fe2a3ddb566c8393cfc71f15b06170a0eff74dfdde'>
>>> eth_event.decode_logs(tx.logs, token.abi)
[{
    'name': 'Transfer',
    'data': [
        {'name': 'from', 'type': 'address', 'value': '0xbd4940951bfa463f8fb6db762e55686f6cfdb73a', 'decoded': True},
        {'name': 'to', 'type': 'address', 'value': '0xbd4940951bfa463f8fb6db762e55686f6cfdb73a', 'decoded': True},
        {'name': 'tokens', 'type': 'uint256', 'value': 100, 'decoded': True}
    ]
}]
```

* `decode_trace(trace, abi)`: Given the `structLog` from a [debug_traceTransaction](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#debug_tracetransaction) RPC call, returns a list of the decoded events. Useful for obtaining events when a transaction reverts.

```python
>>> tx = token.transfer(accounts[1], 100, {'from': accounts[0]})
<Transaction object '0x71a7146996957b8a465a4e5dd41951d614254f8271fc9140b875c4fc55dde578'>
>>> trace = web3.provider.make_request("debug_traceTransaction", ['0x71a7146996957b8a465a4e5dd41951d614254f8271fc9140b875c4fc55dde578', {}])['result']['structLogs']
>>> eth_event.decode_trace(trace, token.abi)
[{
    'name': 'Transfer',
    'data': [
        {'name': 'from', 'type': 'address', 'value': '0xbd4940951bfa463f8fb6db762e55686f6cfdb73a', 'decoded': True},
        {'name': 'to', 'type': 'address', 'value': '0xbd4940951bfa463f8fb6db762e55686f6cfdb73a', 'decoded': True},
        {'name': 'tokens', 'type': 'uint256', 'value': 100, 'decoded': True}
    ]
}]
```

## Limitations

* If an array is indexed in an event, the topic is generated as a sha3 hash and so cannot be decrypted. In this case, the unencrypted topic is returned and `decoded` is set to `False`.

* Anonymous events cannot be decoded.

## Tests

To run the test suite:

```bash
$ tox
```

## Development

This project is still in development and should be considered an alpha. Comments, questions, criticisms and pull requests are welcomed.

## License

This project is licensed under the [MIT license](LICENSE).


