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).

Komodo Notarization OP_RETURN parsing

An issue recently popped up that required a review of notarization OP_RETURNs between chains. As I hadn’t gone through that code as yet, it was a good time to jump in.

NOTE: Consider this entry a DRAFT, as there are a few areas I am still researching.


For notarizations, the OP_RETURN will be a 0-value transaction in vOut position 1. vOut position 0 will be the transaction that contains the value.

The scriptSig of the vOut[1] will start with 6e, which is the OP_RETURN opcode. Immediately after will be the size, which will be a value up to 75, OP_PUSHDATA1 followed by a 1 byte size for values over 75, or OP_PUSHDATA2 followed by 2 bytes of size for numbers that do not fit in 1 byte. And then the “real” data begins.

Block / Transaction / height

The next 32 bytes is a block hash, followed by 4 bytes of the block height. This should correspond to an existing block at a specific height on the chain that wishes to be notarized.

If the chain that wishes to be notarized is the chain that we are currently the daemon of, the next 32 bytes will be the transaction on the foreign “parent” chain that has the OP_RETURN verifying this notarization. <– Note to self: Verify this!

Next comes the coin name. This will be ASCII characters up to 65 bytes in length, and terminated with a NULL (ASCII 0x00). Note that this is what determines if the transaction hash is included. So we actually have to look ahead, attempt to get the coin name, and if it doesn’t match our current chain, look for the coin name 32 bytes prior.

Sidebar: What are the chances that the same sequence of bytes coincidentally end up in the wrong spot so we get a “false positive” of our own chain? Answer: mathematically possible, but beyond the realm of possibility.

MoM and MoM depth

The next set of data is the MoM hash and its depth. This is 32 bytes followed by 4 bytes, and corresponds to the data in the chain that wishes to be notarized.

Note that the depth is the 4 byte value filtered with “& 0xffff”. I am not sure why just yet.

CCid Data

Finally, we get to any CCid data that the asset chain that wishes to be notarized includes. The KMD chain will never include this when notarizing its chain to the foreign “parent” chain (currently LTC).

CCid data contains a starting index (4 bytes), ending index (4 bytes), an MoMoM hash (32 bytes), depth (4 bytes), and the quantity of ccdata pairs to follow (4 bytes).

Afterward is the ccdata pairs. which are the height (4 bytes), and the offset (4 bytes).

Additional Processing

If all of that works, and we are processing our own notarization, the komdo_state struct and the komodostate file is updated with the latest notarization data.


To follow along, look for the komodo_voutupdate function within komodo.cpp.

Komodo Hardfork History

This post is mainly for me to keep track of which hardforks did what.

The main hardforks in Komodo are for the election of notaries. But there are other purposes. I will add to the list as I learn more. Eventually these should be documented within the code (comments near the declaration of a #define or something).

Note that the KMD chain hardforks are normally based on chain height. Asset chains are normally based on time. Hence season hardforks have both.

  • nStakedDecemberHardforkTimestamp – December 2019
    • Modifies block header to include segid if it is a staked chain (chain.h)
    • Many areas use komodo_newStakerActive(), which uses this hardfork
  • nDecemberHardforkHeight – December 2019
    • Many areas use komodo_hardfork_active() which uses this hardfork and the above
    • Disable the nExtraNonce in the miner (miner.cpp)
    • Add merkle root check in CheckBlock() for notaries (main.cpp)
  • nS4Timestamp / nS4HardforkHeight – 2020-06-14 Season 4
    • Only for notary list
  • nS5Timestamp 2021-06-14 Season 5
    • ExtractDestination fix (see komodo_is_vSolutionsFixActive() in komodo_utils.cpp)
    • Notary list updated
  • nS5HardforkHeight 2021-06-14 Season 5
    • Add merkle root check in CheckBlock() for everyone (main.cpp)

Many areas have hardfork changes without much detail. Here are some heights found by searching the code base for “height >”:

  • 792000 does some finagling with notaries on asett chains in komodo_checkPOW (komodo_bitcoind.cpp). See also CheckProofOfWork() in pow.cpp and komodo_is_special() in komodo_bitcoind.cpp.
  • 186233 komodo_eligiblenotary() (komodo_bitcoind.cpp)
  • 82000 komodo_is_special() (komodo_bitcoind.cpp)
  • 792000 komdo_is_special() and komodo_checkPOW()
  • 807000 komodo_is_special()
  • 34000 komodo_is_special()
  • limit is set to different values based on being under 79693 or 82000 in komodo_is_special()
  • 225000 komodo_is_special()
  • 246748 komodo_validate_interest() starts to work (komodo_bitcoind.cpp)
  • 225000 komodo_commission() (komodo_bitcoind.cpp)
  • 10 komodo_adaptivepow_target() (komodo_bitcoind.cpp)
  • 100 (KOMODO_EARLYTXID_HEIGHT) komodo_commission() (komodo_bitcoind.cpp)
  • 2 PoS check in komodo_checkPOW() and komodo_check_deposit()
  • 100 komodo_checkPOW() (komodo_bitcoind.cpp)
  • 236000 komodo_gateway_deposits() (komodo_gateway.cpp)
  • 1 komodo_check_deposit() (komodo_gateway.cpp) (a few places)
  • 800000 komodo_check_deposit() (komodo_gateway.cpp)
  • 814000 (KOMODO_NOTARIES_HEIGHT1) fee stealing check in komodo_check_deposit() as well as another check a little below.
  • 1000000 komodo_check_deposit() (2 places in that method)
  • 195000 komodo_operturn() (komodo_gateway.cpp)
  • 225000 komodo_opreturn() (komodo_gateway.cpp)
  • 238000 komodo_operturn()
  • 214700 komodo_opreturn()

I need to continue searching for “height >” in komodo_interest.cpp, komodo_kv.cpp, komodo_notary.cpp, komodo_nSPV_superlite.h, komodo_nSPV_wallet.h, komodo_pax.cpp, komodo.cpp, main.cpp, metrics.cpp, miner.cpp, net.cpp, pow.cpp, rogue_rpc.cpp, cc/soduko.cpp as well as more searches like “height <” and “height =” to catch more.

Komodo and Notaries in Testnet

I recently deployed an unofficial testnet for Komodo. This will allow me to perform system tests of notary functionality without affecting the true Komodo chain. The idea is to change as little code as possible, test the notary functionality from start to finish, and gain knowledge of the code base and intricacies of notarizations within Komodo.

The plan is to set up a notary node, wire it to Litecoin’s test chain, and do actual notarizations that can be verified on both chains. The first step will focus on the Komodo-Litecoin interaction. Later I will look at how asset chains use the Komodo chain to notarize their chain.

If you wish to follow along, the majority of the changes are in this PR.

A write-up of some of the technical details of becoming a notary can be found here.

Details to test / learn:

  • Notary pay
  • Difficulty reduction
  • Irreversibility
  • Checks and balances (how does a notary know which fork to notarize?)

Unit tests will reside in my jmj_testutils_notary branch for now.

Komodo Core and Bitcoin v0.20.0 refactoring

Note: The following are my thoughts as a developer of Komodo Core. This is not a guarantee the work will be done in this manner, or even be done at all. This is me “typing out loud”.

The Komodo Core code has diverged quite a bit from the Bitcoin codebase. Of course, Komodo is not a clone. There is quite a bit of functionality added to Komodo which requires the code to be different.

However, there are areas where Komodo could benefit from merging in the changes that Bitcoin has since made to their code base. Some of the biggest benefits are:

  • Modularization – Functionality within the code base is now more modular. Interfaces are better defined, and some of the ties between components have been eliminated.
  • Reduction in global state – Global state makes certain development tasks difficult. Modularization, testing, and general maintainability are increased when state is pushed down into the components that use them instead of exposed for application-wide modification.
  • Testability – When large processes are broken into smaller functions, testing individual circumstances (i.e. edge cases) becomes less cumbersome, and sometimes trivial.
  • Maintainability – With improvements in the points above, modifications to the code base are often more limited in scope and easier to test. This improves developer productivity and code base stability.

Plan of Attack

“Upgrading” Komodo to implement the changes to the Bitcoin code base sounds great. But to do a simple git merge will not work. The extent of the changes is too great.

My idea is to merge in these changes in smaller chunks. Looking at the NodeContext object (a basic building block of a Bitcoin application), we can divide functionality into 3 large pieces.

  • P2P – The address manager, connection manager, ban manager, and peer manager
  • Chain – The chain state, persistence, and mempool
  • Glue – Smaller components that wire things together. Examples are the fee estimator, task scheduler, config file and command line argument processing, client (i.e. wallet) connectivity and functionality.

Building a NodeContext object will be the first step. Each piece will have access to an object of this type. This will provide the state of the system, as well as be where components update state when necessary.

The “glue” components often require resources from both “p2p” and “chain” components. Hence they should probably be upgraded last.

The task of upgrading the “chain” piece is probably smaller in scope than upgrading “p2p”. I will attempt to attack that first.

The “p2p” pieces do not seem to be too difficult. Most of the work seems to be in wrapping much of the functionality of main.cpp and bitcoind.cpp into appropriate classes. The communication between components are now better defined behind interfaces. The pimpl idiom is also in use in a few places.

Note: Bitcoin 0.22 requires C++17. For more information, click here.

Branching Strategy for Komodo Core

A bit of background…

The current branching strategy used in Komodo Core is somewhat informal. The idea is to formalize ideas so that everyone agrees on the procedures to follow, and those coming after us know what should be followed.

This is a living document. If the procedures below do not serve their intended purpose, they (or portions of them) should be replaced.

Why this and not that?

There are a number of branching strategies available. This Komodo Core branching strategy is heavily based on Git Flow. This was chosen because the existing strategies match the style of the code base (long lived branches, multiple versions deployed and supported, etc.).

How it works

There are a number of long-lived branches within the Komodo Core repository. The primary ones are:

  • master – The main production branch. This should remain stable and is where code for official releases are built.
  • dev – The development branch. This is where work is done between branches. Non-hotfix bug fixes and new features should branch off this branch.
  • test – The branch for the testnet. As the codebase stabilizes before a release, the code is merged from dev to test.
  • hotfix – After a release, a hotfix branch may need to be created to fix a critical bug. Once merged into test and master, it should also be merged into dev. These branches should not be long-lived.


Each release for testnet and production should be tagged. The versioning strategy is not currently part of this document.

Reviewing / Merging

Before a feature or fix is merged into a parent branch, reviews must be approved by repository maintainers. Anyone can review, but approvals from 2 repository maintainers must be completed.

Once approved, it is best (if possible) that the author of the feature or fix merges their branch into the parent branch. Once the merge is completed locally and all unit and CI tests pass, the code is pushed to the parent branch.

Note: It is best to not use the merge feature of the GitHub web interface. Perform the merge locally and push to the server.