History and notifications in EOSIO blockchain

  • How do I find all recent transactions relevant to my account?
  • How do I get notified of new transactions?

Legacy history_plugin

Although officially deprecated by Block.one, the original history plugin is still widely in use. For a small test network, it’s the easiest and fastest way to get the list of transactions for an account, and services like local.bloks.io work with it out of the box.


dfuse is a service provided by EOS Canada. The software is not open-source, but the service is used by many dApps and is proven to be reliable and flexible. It offers search queries on blockchain history, and subscription service in order to listen for specific events in real time. The free plan allows 250K documents per month, and there are paid plans for higher demands. EDIT: dfuse is now available as open source.


Hyperion is an open-source software solution offered by EOS Rio. It takes state_history_plugin (explained below) input and stores the blockchain history in Elastic Search database. The HTTP API of Hyperion is resembling that of the legacy history API, so it’s easy to adapt applications to use it as a replacement. Several BP provide public Hyperion endpoints for EOS and other blockchains.


State history plugin for nodeos is part of EOSIO distribution. It stores all transaction traces and table deltas in compressed archive files. Also it provides a Websocket interface for querying the traces and deltas for a specific block interval. If the end block number is in the future, the plugin delivers new traces as they become available in real time. It has also an option to deliver only traces from irreversible blocks.

  • history-tools by Block.one is a set of tools that store the state history data in a database and provide API for retrieving it. As of today, the software is in development and not ready for production.
  • Hyperion by EOS Rio implements the whole interpreter of state history in JavaScript. It stores ABI revisions in its database and decodes the traces into JSON documents which are sent to ElasticSearch for storing and indexing.
  • Chronicle by cc32d9 is a C++ program that serves as a bridge between the state history plugin and consumer. It stores ABI revisions in its own database (using the same chainbase software as used in nodeos), and it expects the consumer to open a Websocket server where it connects and pushes a stream of JSON objects. The development was sponsored by multiple BP and wallet teams, and also by Telos WPS.
  • eosio-statereceiver by EOSDAC is yet another interpreter of state history data written in JavaScript.

My scripts for Chronicle

I wrote a number of Perl scripts that take Chrionicle output for further processing. They can be used as a reference if you need to develop your own processor:

  • Light API is a production-ready piece of software. It stores current token balances and account security information in MySQL database, and provides an HTTP API for retrieving the data. It also provides a way to find all accounts controlled by a public key. The API is available for public, and is in use by Scatter, Bloks.io, and few others.
  • eosio-analytics is storing all token transfers and voting events in MySQL database.
  • eosio_chaindb is similar to analytics script, with a slightly different purpose. It stores all token transfers and history of all token balances (including REX and staking) in MySQL database for multiple blockchains.
  • dumper scripts are used mainly for testing the Chronicle itself. They can also be used to produce a sample output, so that it’s easier to design the consumer software.
  • history indexer POC is work in progress. Details and purpose are described in my fundraising article. The goal is to make a replacement for the history plugin, and the difference from Hyperion is that it doesn’t store transaction traces in the database, but keeps only an index of traces.

Iris client by CALEOS

Iris is an open-source project by CALEOS, with the goal to build an alternative to dfuse.

Other nodeos plugins

There’s a number of plugins for nodeos that are exporting transaction traces in JSON directly to some external receiver. There are two fundamental problems with them:

  1. nodeos is already quite busy with processing the network (for example, a full replay of EOS Mainnet would take several weeks), and these plugins add more work by producing JSON data within the same main thread, taking the CPU time from the actual blockchain processing. This slows down the whole process significantly.
  2. Microforks are typical and quite frequent in EOSIO blockchain. Mostly they are caused by time zone difference between block producers when they hand over the schedule. Also a BP may leave two producer nodes signing blocks concurrently, and that leads to microforks as well. Most of known plugins for nodeos are either handling the forks incorrectly or not handling them at all. As far as I know, only state_history_plugin and my own zmq_plugin are reacting to forks in a correct way: they inform the receiver about the fork, and roll back their internal state to the point of forking.


The original history plugin is phasing out, and there are several alternatives, based on top of state history plugin. Many dApp developers are still looking for possibilities to utilize the old history API, although new alternatives are offering much more possibilities and are future-proof.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store



Telegram: cc32d9, Discord: cc32d9#8327, EOS account: "cc32dninexxx"