Mokka consensus

  • Users starred: 14
  • Users forked: 0
  • Users watching: 14
  • Updated at: 2020-04-09 00:50:34


Build Status

Mokka Consensus Algorithm implementation in Node.js.

Concept description (PDF)

consensus features

  • resistant to network splits
  • non-anonymous voting
  • voting validation with musig

implementation features

  • Custom transport layer support: Mokka separate interface implementation and consensus.
  • Fully customizable: you can create your own state machine around Mokka consensus (check out demos for more info).


Via npm

$ npm install mokka --save

From repo

$ npm run build


new Mokka (options)

Returns a new mokka instance. As mokka is agnostic to protocol implementation, you have to create your own. Please check the Custom transport layer section.


  • address (string): an address in custom format. The only rule is that address should include the public key in the end (example: "tcp://")
  • heartbeat (integer): leader heartbeat timeout
  • electionTimeout (integer): candidate election timeout (i.e. vote round)
  • customVoteRule (func): additional voting rule
  • reqMiddleware (func): request middleware (will be triggered on every new packet received)
  • resMiddleware (func): response middleware (will be triggered on every new packet sent)
  • proofExpiration (integer): when the leader's proof token should expire.
  • logger (ILoggerInterface): logger instance. If omitted, then console.log will be used
  • privateKey: the 64 length private key. Please take a look at example key pair generator

mokka.join(multiaddr: string): NodeModel

Add new peer node by uri

await mokka.connect(): Promise

Start consensus. Should be called after all nodes has been added.

mokka.messageApi.packet(type: number, data: any = null): PacketModel

Create new packet, where type is packet type, and data some custom data

mokka.messageApi.decodePacket(message: Buffer): PacketModel

Decode packet from buffer

await mokka.messageApi.message(packet: PacketModel, peerPublicKey: string): Promise

Send message to peer


A Mokka instance emits the following events (available at /components/shared/EventTypes.ts):

  • join: once we add new peer
  • leave: once we remove peer
  • heartbeat_timeout: once we can't receive the heartbeat from leader in certain time (specified in config)
  • state: once the state of node changed (i.e. leader, candidate, follower)

Custom RSM

Mokka is log-less consensus algorithm and doesn't provide any RSM (i.e. replicated log). You have to implement your own. However, there is a good example of RSM implementation, which is similar to RAFT.

Custom transport layer

In order to communicate between nodes, you have to implement the interface by yourself. As an example you can take a look at TCP implementation: src/implementation/TCP. In order to write your own implementation you have to implement 2 methods:

  • The async initialize() function, which fires on mokka start. This method is useful, when you want to open the connection, for instance, tcp one, or connect to certain message broker like rabbitMQ.

  • The async write(address: string, packet: Buffer) function, which fires each time mokka wants to broadcast message to other peer (address param).

Also, keep in mind, that mokka doesn't handle the disconnected / dead peers, which means that mokka will try to make requests to all presented members in cluster, even if they are not available. So, you need to handle it on your own.


running cluster
running private blockchain

Implemented protocols out of the box


However, you still can implement your own protocol.




Copyright (c) 2018-2020 Egor Zuev