1. Home
  2. Docs
  3. Matic
  4. Polygon SDK
  5. consensus




The Consensus module provides an interface for consensus mechanisms.

Currently, the following consensus engines are being worked on:

  • IBFT ✅
  • Clique (⚠️WIP)
  • Ethash (⚠️WIP)
  • PoW (⚠️WIP)

The Polygon SDK wants to maintain a state of modularity and pluggability.
This is why the core consensus logic has been abstracted away, so new consensus mechanisms can be built on top, without compromising on usability and ease of use.

Consensus Interface

consensus/consensus.go// Consensus is the interface for consensustype Consensus interface { // VerifyHeader verifies the header is correct VerifyHeader(parent, header *types.Header) error // Start starts the consensus Start() error // Close closes the connection Close() error}Copy

The Consensus interface is the core of the mentioned abstraction.

  • The VerifyHeader method represents a helper function which the consensus layer exposes to the blockchain layer It is there to handle header verification
  • The Start method simply starts the consensus process, and everything associated with it. This includes synchronization, sealing, everything that needs to be done
  • The Close method closes the consensus connection

Consensus Configuration

consensus/consensus.go// Config is the configuration for the consensustype Config struct { // Logger to be used by the backend Logger *log.Logger // Params are the params of the chain and the consensus Params *chain.Params // Specific configuration parameters for the backend Config map[string]interface{} // Path for the consensus protocol to store information Path string}Copy

There may be times when you might want to pass in a custom location for the consensus protocol to store data, or perhaps a custom key-value map which you want the consensus mechanism to use. This can be achieved through the Config struct, which gets read when a new consensus instance is created.



The blockchain header object, among other fields, has a field called ExtraData.
To review the fields present in the block header, please check out the State in Ethereum section.

IBFT uses this extra field to store operational information regarding the block, answering questions like:

  • “Who signed this block?”
  • “Who are the validators for this block?”

These extra fields for IBFT are defined as follows:consensus/ibft/extra.gotype IstanbulExtra struct { Validators []types.Address Seal []byte CommittedSeal [][]byte}Copy

Signing Data#

In order for the node to sign information in IBFT, it leverages the signHash method

Another notable method is the VerifyCommittedFields method, which verifies that the committed seals are from valid validators


Snapshots, as the name implies, are there to provide a snapshot, or the state of a system at any block height (number).

Snapshots contain a set of nodes who are validators, as well as voting information (validators can vote for other validators). Validators include voting information in the Miner header filed, and change the value of the nonce:

  • Nonce is all 1s if the node wants to remove a validator
  • Nonce is all 0s if the node wants to add a validator

Snapshots are calculated using the processHeaders method

This method is usually called with 1 header, but the flow is the same even with multiple headers.
For each passed in header, IBFT needs to verify that the proposer of the header is the validator. This can be done easily by grabbing the latest snapshot, and checking if the node is in the validator set.

Next, the nonce is checked. The vote is included, and tallied – and if there are enough votes a node is added / removed from the validator set, following which the new snapshot is saved.

Snapshot Store

The snapshot service manages and updates an entity called the snapshotStore, which stores the list of all available snapshots. Using it, the service is able to quickly figure out which snapshot is associated with which block height.consensus/ibft/snapshot.gotype snapshotStore struct { lastNumber uint64 lock sync.Mutex list snapshotSortedList}Copy

IBFT Startup

To start up IBFT, the Polygon SDK firstly needs to set up the IBFT transport

It essentially creates a new topic with IBFT proto, with a new proto buff message.
The messages are meant to be used by validators. The Polygon SDK then subscribes to the topic, and handles messages accordingly.


The message exchanged by validators

The View field in the MessageReq represents the current node position inside the chain. It has a round, and a sequence attribute.

  • round represents the proposer round for the height
  • sequence represents the height of the blockchain

The msgQueue filed in the IBFT implementation has the purpose of storing message requests. It orders messages by the View (firstly by sequence, then by round). The IBFT implementation also possesses different queues for different states in the system.

IBFT States

After the consensus mechanism is started using the Start method, it runs into an infinite loop which simulates a state machine


All nodes initially start in the Sync state.

This is because fresh data needs to be fetched from the blockchain. The client needs to find out if it’s the validator, find the current snapshot. This state resolves any pending blocks.

After the sync finishes, and the client determines it is indeed a validator, it needs to transfer to AcceptState. If the client is not a validator, it will continue syncing, and stay in SyncState


The Accept state always check the snapshot, and the validator set. If the current node is not in the validators set, it moves back to the Sync state.

On the other hand, if the node is a validator, it calculates the proposer. If it turns out that the current node is the proposer, it builds a block, and sends preprepare and then prepare messages.

  • Preprepare messages – messages sent by proposers to validators, to let them know about the proposal
  • Prepare messages – messages where validators agree on a proposal. All nodes receive all prepare messages
  • Commit messages – messages containing commit information for the proposal

If the current node is not a validator, it uses the getNextMessage method to read a message from the previously shown queue.
It waits for the preprepare messages. Once it is confirmed everything is correct, the node moves to the Validate state.


The Validate state is rather simple – all nodes do in this state is read messages and add them to their local snapshot state.

Originally published @ https://sdk-docs.polygon.technology/docs/reference/modules/consensus

Was this article helpful to you? Yes No

How can we help?