client and server library
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

ethevents client and server library is a search index for the Ethereum blockchain. The blockchain data is indexed with Elasticsearch. The server part of exposes an API that can execute queries written with the Elasticsearch Query-DSL. Users can execute arbitrary queries against this API, however they will need to pay for each request with Microraiden payments.

The remainder of the README will focus on the user side / client library of the software.


Installation needs python3.

Runtime needs an Ethereum blockchain client with rpc enabled.


Clone this repository and run

cd ethevents && virtualenv .venv && source .venv/bin/activate && pip install .

First start



to start the client.

Upon first start, ethevents will create a hot-wallet for the user. In order to connect to the API, that newly created hot-wallet will require funding. A small amount of ETH for opening and closing channels (maximum 2.0 ETH) and some RDN tokens for paying actual requests.

There is an RDN vending machine at FIXME that can be used to acquire RDN tokens.

Requests to the search index will cost 1 REI per millisecond of the took portion of the Elasticsearch response. If the request took 3153 ms, the price will be 3153 REI or 3.153e-15 RDN.

Using the client

There are two ways to use the client, through a prepopulated ipython REPL and by connecting to the local proxy server.

Using the ipython REPL

After starting the client with


and unlocking the hot-wallet, an ipython REPL is started, prepopulated with some objects necessary for interacting with the blockchain index. For simplified discoverability, all prepopulated objects are mirrored in the ee. namespace, so typing ee. and hitting <TAB> will give insight into the available objects. For brevity, the following will use the user objects with their shorthand (i.e. without the ee. prefix).

Searching the blockchain index

The es object is an elasticsearch-py instance, that will automatically pay for any request via Microraiden payments. Calling'ethereum', 'block', body={})

will for example search for blocks in the index.


will return the configured index mapping for the Ethereum blockchain index.

The queries module contains a number of functions that generate example queries (see ethevents/examples/ They are meant as a quickstart helper for queries but they are in no way exhausting the space of potential queries against the search index.

The ipython ? operator is helpful to determine the available arguments for an example query, e.g.


will output:

Signature: queries.caller_for_event(event_sig='0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef', time_range={'gt': 0}, num_callers=10)
This query aggregates the most common caller addresses for all transactions
that lead to a certain `event_sig` topic:
- `caller` collects the `num_callers` most common sender addresses
- `gasprice_stats` aggregates gas price statistics per caller

Usage:'ethereum', 'tx', body=caller_for_event())

    event_sig (str): an event signature (topics[0])
    time_range (dict): a range query dictionary for the `timestamp` field (default: all time)
    num_callers (int): number of top caller addresses to return
    query (dict): an elasticsearch query body dictionary.

Calling'ethereum', 'tx', body=queries.caller_for_event(time_range=dict(gt='now/h - 1h')))

will for example aggregate the ten most common account addresses that generated an ERC20 transfer event in the last hour (opposed to the default value, "since all time", 'gt': 0).

Please refer to the Elasticsearch documentation if you want to learn more about the Query DSL.

Using the proxy server

Once the client is running, it exposes a forward proxy at http://localhost:5478 to the Elasticsearch API. The supported API endpoints are

POST /ethereum/<_type>/_search
POST /_msearch
GET /ethereum/<_type>/_mapping

Any Elasticsearch consumer API that is satisified with these endpoints can be connected to this proxy.

The client proxy implementation will automatically forward, and pay for, requests to the blockchain index.