• Home
  • Live Data
  • Events
Home Code Reviews Harmony Open Consensus Blockchain Code Review


Harmony Open Consensus Blockchain Code Review


I find it a bit weird that a blockchain with such lofty aspirations makes you scroll all the way to the bottom of their website before they use the word ‘blockchain’ but that’s probably just because I stare at these things all day. They use ‘consensus protocol’ a lot. Is blockchain too boring for them?

Whatever, this is an “Open consensus for 10 billion people”. The “Open infrastructure is a revolutionary high-throughput, low-latency, and low-fee consensus platform designed to power decentralized economies of the future.”

Let me start with my disdain: I remember when Harmony just came out they had claims of 10 million TPS (or was it a hundred million?) all over the place. This put them in a negative light for me. I do however have respect for the team, and think they are sincere technologists, so I’m going to put that bias aside for the time being and just evaluate what we have available.

So we start with the whitepaper;

  • Fully scalable, network, transaction, and state all sharded.
  • Distributed randomness generation (DRG)
  • PoS, linearly scalable BFT algorithm that’s 100 times faster than PBFT. — Ok, I hate claims like this, don’t put this in a technical paper, it’s simply not, it’s not linearly scalable, and its not a hundred times faster.

Let’s unpack linearly scalable quickly. If 1 person can do 1 job, then 2 people can do 2 jobs right? If the job is completely independent of each other, then this statement is technically correct. But what if they become dependent on each other? Or what if person 2 has to confirm with person 1 if they did the job correctly, all of a sudden they can’t perform 2 jobs anymore, but somewhere between 1 and 2 jobs.

Now assume that for each job, each person had to check with all other persons, so if I do a single job, and there are 100 people, I have to check with 100 people if they agreed with my job. How long would it take you, to ask 100 people, all busy with other things, if they agree with your job? Well, that’s consensus. It’s simply not linearly scalable, the more participants, the slower it will go, that’s why dPoS systems are faster, they keep the 100 people to some small number, like 8–20 so that it’s faster to agree.

Getting 10,000 people to agree is… well… when you succeed let me know.

Ok, so moving away from linearly scalable.

  • Adaptive Thresholded PoS
  • Kademlia
  • Cross-shard with atomic locking mechanism

Good description in the whitepaper on consensus, reads well and its well written. The paper is well written.

VRF, and BLS, we have the usual gen 2 blockchain candidates. I do agree with these approaches, I think VRF is critical for sharding and BLS is critical for consensus.

Ok, good paper, great read, I highly recommend it, let’s see what they built;


14 contributors, 29 branches, 2,697 commits. For a new project, when I see those many commits I normally assume a fork.



Initial commit May 22, 2018, so almost a year of development now. First few commits look legit, doesn’t look like any forked code.

So what areas are we interested in;

consensus definitely, contracts is interesting, we will look at core, drand should be good, the rest look like boilerplate, but they did say their p2p is unique, so we can dig into it as well.

Good code organization, good structure, well designed. Code is architected similar to the whitepaper.



When I see chainreader and engine I assume ethereum, they do import ethereum libraries, nothing wrong with using libraries, but let’s see how much is used. ChainReader and Engine are pretty much the default ethereum implementations ones, so we do have a little bit of forkiness going on here.



So what do we expect from consensus? We expect leader selection and BLS with BFT



RLP, params, and common libraries used from ethereum. We have protobuf as well, interesting to see with RLP, engine from consensus/engine which is essentially just ethereum engine, crypto/bls will check here later. /core/state and /core/types look like ethereum core/state and core/types, but we will dissect those later, maybe we have a bit more forkiness than I originally expected.

Not yet sure how a leader is elected, will need to dig in more;



Random channel, we need to hunt it down.



hosts, shard, peers, leader, and bls secret key are pre-defined. Interesting, could be a bad sign, but let’s not jump to conclusions just yet. We need to find this instantiation though.

LDR = leader, VLD — validator, I was wondering about this shorthand.



Seal was what I was interested in, shame it isn’t implemented yet, still this isn’t finished code, so they are still working on it, but this is definitely the meat.

Need to figure out how a leader is selected, otherwise this is a little bit pointless, so let’s jump into the startup sequence for a node.



It’s golang, so we jump into /cmd/ -> Harmony -> main.go



Leaders are predefined? Little bit disappointed by that, but let’s move on;



dRand is the random generation for the beacon chain, definitely interested in it.

Leaders are defined at bootup. I’m unhappy. Let’s continue.



Standard 3 stage commit. This is just BFT with less message overhead because of BLS.



Contracts, we see faucet, lottery, and stake, probably not really anything interesting, but let’s unpack.



Uses the EVM, let’s move on.



Looks like ethereum. Mostly ethereum code, all credit given though. Let’s look at resharding, state_transition (where transactions are applied to the EVM, this is where shards need to live) and tx_pool (since it needs to have shard awareness)



VM context doesn’t know about shards. Interesting.



Genesis knows about shards. So essentially each ethereum network has a chain ID, you have Ethereum, Rinkeby, Ropsten, Kovan. Now think of each one as a shard. That’s all sharding really is. Now add POA’s cross-chain bridge so that tokens can move from one to the other, and you have the beacon chain. Good for multiple tokens, but this does not provide scalability for a single token ecosystem.

A year ago I would have been very excited by this code.

VM doesn’t need awareness of shard state, because it is given a blockchain object to state transition, and the blockchain itself is aware of the shard state.

Ok, let’s unpack the BLS, for this, we need to head over to their bls implementation repo;



Forked from herumi / bls

Some amazing repo’s in Herumi’s github, bls, bls-wasm, mcl, mcl-wasm. As part of this review I’m not going to unpack it, but definitely worth a watch.

VRF is p256 from google. It’s solid, not going to unpack it.

dRand is a mix of VFR, and consensus.

Harmony Open Consensus Code Review Conclusion:

It’s good code, a bit of a hacked ethereum with chainID’s as shards and then using some good ideas around VRF and BLS (Dfinity anyone?).

There is nothing wrong with this, and a year ago this would have been phenomenal code to see. I think I’ve just seen too many code bases like this one. What makes it special? Why is it better than all the rest? It’s definitely another contender, but at this point, how many contenders do we need?

Anyway, good code, I just don’t see the point.

You can chat about Harmony, or create disharmony, in our Telegram group.

Disclaimer: Crypto Briefing code reviews are performed by auditing what is on display in the master branch of the repo’s made available. This was performed as an educational review and any comments in the article are the opinion of the writer. It is normal for code to change rapidly, hence we timestamp our code reviews so that they present a snapshot at a moment in time. Information contained herein should not be used as any comment or advice on the project as a whole.

Harmon Code Review Timestamp: March 27th, 2019



Authors at Crypto Briefing are invested in cryptocurrencies. The author of this post may be invested in digital assets mentioned here.

Andre Cronje
Andre Cronje
Andre is a software architect with 20 years of development experience. After completing his 3 year computer science course in 5 months he was asked to stay on as a lecturer. He moved into telecoms developing big data, high transactional infrastructure, before delving into mobile security and cryptography. His last five years have been spent building bespoke FinTech solutions and leveraging blockchain technology to provide cost-reducing financial products to the unbanked sector in Africa.


Join the conversation on Telegram and Twitter!


More News & Analysis

Get The Best Of Crypto Briefing!

Crypto news flashes, new DARE research, upcoming mainnet launches, market reports, and much more!