Ethereum Event Listener

Motivation

ITAM team currently uses BSC event listener internally. But, our listener faced performance issue when updating massive transaction on same blocknumber. We have been tried to find other solution for blockchain event listener solutions.

Most popular ethereum event listener solution is Eventeum. But we have faced missing event especially on bsc and Eventeum is not ideal solution. We need to update Eventeum internally to solve missing event case but it is written in Java. Our team has confidence to javascript so there is a learning curve to update Eventeum.

So we have planed to update our bsc event listener written in javascript. And also we will open our event listener to public to listen user's feedback and improve it.

Getting Started

install dependencies Ethereum Event listener use yarn as package manager

$ yarn install ethereum-antenna

you can use npm alternatively

$ npm install ethereum-antenna

initialize Some environment variables used in code are not opened to repository.

import EthereumAntenna from 'ethereum-antenna';

import 'dotenv/config'; // In case of using environment variables such as `AWS_ACCESS_KEY_ID`;

const antenna = new EthereumAntenna({
  eventStore: {
    type: 'mongodb',
    uri: <MONGO_URI>,
  },
  producer: {
    type: 'sqs',
    region: <AWS_REGION>,
    queueUrl: <BLOCKCHAIN_QUEUE_URL>,
  },
  http: {
    type: 'koa',
  },
  rpc: <BLOCKCHAIN_RPC_URL>,
});

await antenna.run();

You should add some parameters to initialize Ethereum Antenna; After initialization, you can listen event with this instance.

Deep dive into Ethereum Antenna

Initialization

To run Ethereum Antenna, you should add parameters to create instance. Below is description of parameters.

Name	Type	Required	Default	Description
eventSync	boolean	false	undefined	listening event with sync or async
eventStore.type	`mongodb`	true		type of persistence
eventStore.url	string	true		url of persistence
producer.type	`sqs`	true		type of event publisher
producer.fifo	boolean	false	undefined	`true` if event queue is `FIFO` queue
producer.region	string	true		region of event publisher, currently only affected on AWS
producer.queueUrl	string	true		queue url of event publisher
http.type	`koa`	true		type of http service
http.port	number	false	3000	port number of http service
http.prefix	string	false		prefix of routing url
rpc	string	true		url of EVM chain RPC
limit	number	false	1000	total range of each event query
blockPerSecond	number	false	0	delay after each query
delayBlock	number	false	0	distance from latest block number
backOffBlock	number	false	50	distance from specific block number
threshold	number	false	50	range from specific block number

If eventSync is true, event listening and broadcasting will occur synchronous. If some events are delayed from other events, wait until delayed events follow event block. If eventSync is false, event listening asynchronously and event query concurrently. And concurrency will affect only eventSync is false.

Notice: If you have to use AWS SQS on outside of AWS infrastructure, you SHOULD WRITE AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. (LINK) If you're using AWS SQS on infrastructure, follow AWS guide to get grant to send SQS Messages.

Methods

Ethereum Antenna includes two features. First one is listening event from blockchain. Another one helps event structure that uses on block event listener by handling it with REST api.

antenna.run() run event listener and helper API both.
antenna.listen() run event listener only.
antenna.api() run helper API only.

Todo

Below list may change due to our direction of development

create test cases
add api interface for contract listening
add contribution guide

BarrySauce / ethereum-antenna