Uses for Komodo’s komodostate file

The komodostate file contains “events” that happened on the network. The file provides a quick way for the daemon to get back to where it was after a restart.

Some of the record types are for features that are no longer used. In this document I hope to detail the different record types and which functions use this data.

The komodo_state object

The komodo_state struct holds much of the “current state” of the chain. Things like height, notary checkpoints, etc. This object is built via the komodostate file, and then kept up-to-date by incoming blocks. Note that the komodo_state struct is not involved in writing the komodostate file. It does store its contents while the daemon is running.

Within the komodo_state struct are two collections that we are interested in. A vector of events, and a vector of notarized checkpoints.


komodo::event is the base class for all record types within the komodostate file.

event_rewind – if the height of the KMD chain goes backwards, an event_rewind object is added to the event collection. The following call walks backwards through the events, and when an event_kmdheight is found, it adjusts the komodo_state.SAVEDHEIGHT. That same routine also removes items from the events collection. So an event_rewind is added, and then immediately removed in the next function call (komodo_event_rewind).

event_notarized – when a notarization event happens on the asset chain of this daemon, this event is added to the collection. The subsequent method call does some checks to verify validity, and then updates the collection of notarization points called NPOINTS.

event_pubkeys – for chains that have KOMODO_EXTERNAL_NOTARIES turned on, this event modifies the active collection of valid notaries.

event_u – no longer used, unsure what it did.

event_kmdheight – Added to the collection when the height of the KMD chain advances or regresses. This eventually modifies values in the komodo_state struct that keeps track of the current height.

event_opreturn – Added to the collection when a transaction with an OP_RETURN is added to the chain. NOTE: While certain things happen when this event is fired, these are not stored in the komodostate file. So no “state” is updated relating to opreturn events on daemon restart. The komodo_opreturn function shows these are used to control KV & PAX Issuance/Withdrawal functionality.

event_pricefeed – This was part of the PAX project, which is no longer in use.


NPOINTS is another collection within komodo_state. These are notary checkpoints. This prevents chain reorgs beyond the previous notarization.

The collection is built from the komodostate file, and then maintained by incoming blocks.

Unlike much of the events mentioned earlier, several pieces of functionality search through this collection to find notarization data (i.e. which notarization “notarized” this block).

komodostate corruption

An error in version 0.7.1 of Komodo caused new records written to the komodostate file to be written incorrectly. Daemons that are restarted will only have the internal events and NPOINTS collections up to the point that the corruption starts. The impact is somewhat mitigated by the following:

New entries may be corrupted in the file, but are fine in memory. A long-running daemon will not notice the corruption until restart.

Most functionality does not need the events collection beyond the last few entries, which will be fine after the daemon runs for a time.

Data queried for within the NPOINTS collection will have a gap in history. As the daemon runs, the chances of needing data within that gap are reduced.

Reindexing Komodo ( -reindex ) will recreate the komodostate file based on the data within the blockchain. The fix for the corruption bug will hopefully be released very soon (in code review).

Leave a Reply

Your email address will not be published.