Ethereum Event Explorer for Smart Contracts
BY MARKUS SPRUNCK
1. Motivation
Ethereum-Event-Scan is a lightweight Ethereum event explorer for smart contracts. Highly helpful when you develop smart contracts and your source code is not yet submitted to Etherscan.
Also in the case you work with a private Ethereum blockchain, you will need a monitor to see what happens in your contract. You can use the code as a basis for your own web3.js explorer implementation.
The following article describes the key ideas, design behind the implementation and also the usage as out of the box docker image. You may find the complete source code on GitHub and there is a complete docker container ready on DockerHub.
Figure 1: Main Screen of Ethereum-Event-Scan
2. Ethereum Monitoring Basics
In principle there are two approaches to find out what happens in your deployed smart contract. The first way is just to monitor all transactions of your contract and the second is to monitor events emitted by your smart contract.
2.1 Transactions show just the method call parameter
It is easy to get all incoming transactions of your contract — but in this case you have to decode the transaction input based on the ABI description.
Decoding is not rocket science, however you see just the input parameters of the method calls. With this approach you never see what happens in the smart contract.
In most cases you are also interested in the internal states of your contract , so a kind of logging would be needed.
2.2 Events can show also internal states
When your smart contract emits events you can also add information of the transaction result, e.g., updated balance, statistics, success state. These internal states can give you the needed information for monitoring.
3. Solidity Event Basics
An event will be emitted in Solidity by emit keyword, followed by the name of the event and the arguments in parentheses. The invocation can be detected from the JavaScript API.
3.1 Let's have a look at an example contract
When the method bee is called, the internal attribute _count will be incremented. This attribute represents an internal state of the contract.
The emitted Bee events can output this internal state information. You may use the keyword indexed to filter later by this parameter.
Figure 2: Example smart contract coded in Solidity
3.2 How are events stored in the blockchain?
The needed storage for all events in the blockchain would be very expensive. How can we get events without actually storing them in the blockchain?
When a smart contract emits events, like in the bee method, just the contract address is stored in the transactions receipt as so called logsBloom. This data structure has a size of 2048 bytes and is part of the block hash calculation. So, it can't be changed after the block has been mined.
3.3 How can we find events data?
The addresses of events emitting contracts are as well as indexed fields added to the bloom filter. A bloom filter of the given size can store about 200 contract addresses with less than 2% expected false positive results (bloom filters have no false negative results).
When you query the log entries for a given contract address, it can be scanned in a very fast way over all the block headers, checking the bloom filter to find out this block may contain the entries.
In this case all transactions from that block will be re-executed and this execution recreates the expected logged events.
3.4 Let's talk about expense
The use of Ethereum events will cost some extra GAS, but in most of the cases it is a good investment. Usually, emitting an event from your contract costs less than 1000 GAS. In the case the smart contract doesn't need the stored data for processing — it's a good alternative to store data in logs.
The total cost of event logs are much more smaller than contract storage. According to the Yellow Paper the difference in cost for logs and storage is significant.
Storage Cost for Contract
Store a word in standard storage costs 20.000 GAS
Storage Cost for Events
Store a word in the indexed event storage costs about 1000 GAS (375 + 32*8 +375)
3.5 How to use events in your contract?
Find more information about events and logs in the Solidity Documentation which provides a detailed description of how to use events.
4. PULL Docker Image
In the case you don't like to spend time with the implementation, just pull the complete software of Ethereum-Event-Scan from DockerHub.
4.1 DockerHub Page
https://cloud.docker.com/u/sprunck/repository/docker/sprunck/ethereum-event-scan
Figure 3: DockerHub page of Ethereum-Event-Scan
4.2 Start Container
Use the following docker command to get the container started
$ docker run \
-dit \
-p 55226:80 \
--name ethereum-event-scan \
sprunck/ethereum-event-scan:latest
Check the exposed port - you may change it in the case you have conflicts.
The default URL is
http://localhost:55226
5. Find Code on GitHub
Fetch the project sources (published under MIT License) from GitHub.
5.1 Development Environment
The project has been developed and tested with following configuration:
macOS 10.15.4
IDEA IntelliJ (Ultimate Edition)
Package Manager Brew (see https://brew.sh)
Docker Desktop (Community Edition) v2.2.0.4
Parity Node v2.5.7
Ganache v2.0.1
Web3.js v1.2.6
Node v12.13.1
Angular v9.0.4
5.4 Connect to Kovan via Blockchain Gateway
Use Infura.io to connect to a Blockchain is the fastest way to get events from a deployed contract. You will need an account and project id.
The following three steps will be needed:
Create an Infura.io Project
Update the Start Script
Enter ABI and Contract Address
Create an Infura.io Project
Open Infura.io page and sign up for an account. On your dashboard, you can create a new project.
Figure 6: Infura Project Dashboard
Usually, you change the endpoint to Kovan and directly copy the endpoint URL for connecting to blockchain. But, to get events via infura you must use the web socket connection provider, in the Ethereum-Event-Explorer.
The web socket URl is slightly different from the http interface — the correct pattern for web services is:
wss://kovan.infura.io/ws/v3/{your-infura-project-id}
Please, be aware that your personal API key to use Infura should be secret. So, don’t give it away to anyone else.
Enter ABI and Contract Address
Enter the ABI array and contract address can be done directly in the user interface or you can click on Import link. In the case you stored the ABI array in a file with the file name of the contract address.
Figure 8: Ethereum-Event-Scan Settings
5.5 Connect to Kovan via Local Parity Node
The installation of a parity node on your machine is simple. Three steps are needed:
Install Parity Node
Start and Synchronise Parity Node
Start Ethereum-Event-Scan
Install Parity Node
For MacOS open terminal and enter the following two commands:
$ brew tap paritytech/paritytech
$ brew install parity
After parity has been installed you can start the partiy node and fetch the blockchain from Kovan network.
Start and Synchronise Parity Node
The following start script (see start-parity.sh) enables just the needed api for the Ethereum event scan for web socket connections:
Figure 9: Start Script for Parity Node
The synchronisation may need a day. In the case the synchronisation got stuck, just restart. You should see an output of the Parity Node after complete sync and restart should look like this:
Figure 10: Output of Parity Node
Please, be aware that the Public node URL has been slightly changed. So, don't try to connect to this node.
In the logging of this parity node you see also the open connection of the configured web service interface — here 127.0.0.1 with port 8546.
Software-Engineering-Candies is completely ads free and no sponsored content will ever be published. In the case you like to support this concept, you may donate Ether (ETH) using the address below.
0x9405d9E64ef617c15d732F17b7abe90562A48216
