Auto Checkpoints is a lightweight finality mechanism in Komodo-based blockchains based on dynamically created checkpoints as the chain progresses.

A single designated master node for each block issues a synchronization checkpoint, ensuring that no chain reorganisation is permitted below the most recent checkpoint. This effectively guarantees transaction finality up to a checkpoint depth of 4 blocks behind the chain tip.

Komodo’s auto checkpointing implementation is derived from the Gulden (Munt) codebase which, in turn, originates from the Peercoin codebase. Komodo’s auto checkpointing can be used for both KMD mainnet and asset chains.

Code: https://github.com/dimxy/komodo/commit/fb06d552ff466f85b5b831525eee77cd3765660e

Auto checkpointing feature is managed by configuration constants in the codebase.

In the Komodo daemon repository, locate:

src/auto_checkpoints_activation.cpp

Inside this file, update the CSyncCheckpointActivation struct initialization with:

• Activation height or timestamp,

• Master checkpoint public key.

You may need to update values in mainnet_params variable (for KMD) or asset_chains variable (for asset chains).

Once updated, rebuild the daemon and restart all nodes on the network.

Before the activation moment:

Import the master private key on exactly one node using:

importprivkey <masterprivkey> "" false

The "false" param means no wallet rescan is needed, assuming this is a fresh key.
Restart the master node (the master private key is loaded only on node start up).

Verify that the key is correctly imported using:

validateaddress <addr>

where is the address returned by importprivkey. The validateaddress should return the master pubkey.

⚠️ Important:
Only a single node must possess the master private key. If multiple nodes generate checkpoints, the network can diverge into inconsistent forks.

Each node contains the checkpoint master public key, built-in in the code and used to authenticate signed checkpoint messages.

For each newly created or received block, the master node:

• Looks up the block at checkpoint_height = current_tip_height - 4 and constructs a checkpoint using the block hash at that height.

• Signs the checkpoint with the master private key.

• Broadcasts the message as a checkpoint network message.

When a node receives a checkpoint it validates and makes it as the new latest:

Validation

• The checkpoint message signature is validated against the master public key.

• The checkpoint hash must exist in the node’s block index.

• The new checkpoint must be a descendant of the previously accepted checkpoint.

Storage

• The checkpoint is written to the checkpoint file (to be able to restore the last checkpoint on node restart).

• Only the most recent checkpoint is retained.

Chain Activation

If the checkpoint is not on the node’s active chain, the node attempts to reorganize to a chain that includes the last checkpoint.

Pending Checkpoints

If the checkpoint hash is not in the node block index, it is marked pending, and the node requests headers (getheaders) starting from the checkpoint hash.

When processing new blocks, nodes ensure:

• The latest checkpoint block is an ancestor of every newly accepted block.

• Blocks or chains violating this rule are rejected, preventing deep reorganizations.

Only the latest checkpoint matters for block validation.

If a node becomes temporarily disconnected and misses one or more checkpoints:

• Once reconnected, it will begin receiving new checkpoints.

• Even if this node has a longer or higher-work competing chain, it will stop extending that fork if it does not include the last valid checkpoint.

• The node will reorganize onto the chain containing the checkpoint and continue syncing normally.

This ensures network convergence and protects against long-range or deep-fork attacks.

There is a new getcheckpoint RPC returning the latest checkpoint. The existing getblockchaininfo RPC also returns the same latest checkpoint.

There is a running chain (with a master node) to test auto checkpoints:

~/repo/komodo/src/komodod -ac_name=GULDEN -ac_reward=300000000 -ac_nk="96,5" -addnode=65.108.238.59

The main test to verify the basic auto checkpointing feature is to start a mining node, disconnect it for 4+ blocks then reconnect back and ensure the latest checkpoint reappears (in 4 blocks after reconnection) - use the getcheckpoint RPC.

You may continue mining on the node while it is disconnected and after it reconnects back:

• If it is mining, note the fork which the node has created - use getblockchaininfo RPC.
• Ensure that the node stops adding blocks to this fork when the latest checkpoint appears on the node.
• Also ensure the node reorganizes to the best chain with the latest checkpoint.

A node (or a group of nodes) may become temporarily disconnected from the network and miss one or more recent checkpoints. When such nodes reconnect, they will begin receiving new checkpoint announcements again. Even if a disconnected node has built an alternative best chain (fork) with higher accumulated chain work, it will stop extending that fork and will eventually switch to the chain containing the latest valid checkpoint.

For a node to accept a previously missed checkpoint, it must first obtain the missing block headers and the checkpoint block itself, stored in the local block database.

Nodes periodically synchronize block headers with their peers and update their block index accordingly. Under normal conditions, if a node believes it has more total chain work than its peers, it may not request or download blocks from them.

However, when a peer activates a new best chain, it announces the new chain tip to its connected peers. This announcement allows previously disconnected nodes to become aware of the newer chain and begin downloading the corresponding blocks into their block database.

A checkpoint is only accepted once its associated block has been successfully received and stored locally in the block db. As a result, immediately after reconnecting, a node may continue to reject newly announced checkpoints until the checkpoint block itself is announced by peers and retrieved by the node.