Cumulative difficulty

Work rather than a block count

Difficulty expresses how hard it is to find an acceptable proof-of-work result for a block. Adding the difficulties across a branch gives nodes a basis for comparing histories when branches have different difficulty histories.

The comparison only matters after consensus validation. A branch with an invalid transaction, invalid reward or failing proof of work cannot win merely by declaring a large number.

References: Monero source: cryptonote_core/blockchain.cpp

Using the RPC fields

The daemon RPC exposes cumulative difficulty separately from the next block difficulty. Modern responses include wide values because accumulated work can exceed the range of a 64-bit integer. Monitoring software must preserve the documented precision.

Compare measurements from the same network and identify their chain tips. Comparing a stale node with a synchronized node without their heights and hashes can disguise a synchronization problem as a consensus disagreement.

References: Daemon RPC reference

Example

In a simplified example, one branch adds blocks with difficulties 100 and 100, while another adds 120 and 120 from the same ancestor. The latter adds more cumulative difficulty despite having the same number of blocks.

References: Monero source: cryptonote_core/blockchain.cpp · Daemon RPC reference

Limits and cautions

The number measures required work. It cannot count the exact hashes miners performed. A daemon reporting a larger value does not make invalid blocks valid or establish that its report is accurate.

References: Monero source: cryptonote_core/blockchain.cpp · Daemon RPC reference