Network difficulty by epoch
/stats/mining/difficultyThe network difficulty curve, one point per difficulty epoch. Ergo only readjusts difficulty on epoch boundaries, so every block inside an epoch carries the same value and one record describes all 128 of them. That makes the table cheap enough to keep for years — it is not bounded by the history retention window the other statistics use.
Each epoch carries its height range, its first and last block timestamps, and
hashesPerSecond: the work of the epoch's block intervals divided by the time those same
intervals took. Use it for network hashrate as well as difficulty; the two differ only by
how long the blocks took.
current is the epoch in progress. It is recomputed on every collection cycle rather than
stored, so it is the only entry that can still change, and its complete is false. Stored
epochs stay a full epoch behind the tip so a reorg cannot rewrite one.
Indices count epochs from height 1. With no range the newest limit epochs are returned.
oldestIndex and newestIndex report what the table actually holds, and backfillComplete
says whether it has finished walking back to its floor — on mainnet that floor is the EIP-37
activation, below which epochs were 1024 blocks long and are not described here.
Query parameters
frominteger · int32First epoch index to include. Clamped to
oldestIndex.tointeger · int32Last epoch index to include; defaults to
newestIndexand cannot exceed it.limitinteger · int32default 256How many epochs to return, counted back from
to.
Responses
200The requested epochs, oldest first, plus the epoch in progress.DifficultyEpochHistory▶
▶
sourceMiningCursorrequiredThe processed chain point a statistics result was read from.
heightintegerrequiredblockIdstringrequiredparentIdstringrequiredtimestampinteger · int64requiredThe block's own timestamp in Unix milliseconds, not the time the client read it.
epochLengthintegerrequiredBlocks per epoch. 128 on mainnet since EIP-37, and on testnet throughout.
▶
epochsDifficultyEpoch[]requiredStored epochs in the requested window, oldest first. A gap means that epoch is not held.
indexinteger · int32requiredEpoch number, counting from height 1. Epoch
nspans heights128n + 1to128n + 128.0 – …startHeightintegerrequiredFirst block of the epoch, and the one whose header supplied
difficulty.endHeightintegerrequiredLast block of the epoch, or the current tip while the epoch is still in progress.
startTimestampinteger · int64requiredTimestamp of
startHeight, in Unix milliseconds.endTimestampinteger · int64requiredTimestamp of
endHeight, in Unix milliseconds.difficultystringrequiredRequired difficulty for every block in the range, as an exact decimal integer.
decimal stringcompletebooleanrequiredFalse only for the epoch in progress, whose
endHeightstill moves with the tip.hashesPerSecondstringNetwork hashrate across the epoch:
difficulty × (endHeight − startHeight)divided by the seconds between the two timestamps, so both sides count the same block intervals. Omitted when the range covers no interval or no elapsed time.decimal string
▶
currentDifficultyEpochOne difficulty epoch. Every block from
startHeighttoendHeightcarriesdifficulty, because Ergo only readjusts on epoch boundaries.indexinteger · int32requiredEpoch number, counting from height 1. Epoch
nspans heights128n + 1to128n + 128.0 – …startHeightintegerrequiredFirst block of the epoch, and the one whose header supplied
difficulty.endHeightintegerrequiredLast block of the epoch, or the current tip while the epoch is still in progress.
startTimestampinteger · int64requiredTimestamp of
startHeight, in Unix milliseconds.endTimestampinteger · int64requiredTimestamp of
endHeight, in Unix milliseconds.difficultystringrequiredRequired difficulty for every block in the range, as an exact decimal integer.
decimal stringcompletebooleanrequiredFalse only for the epoch in progress, whose
endHeightstill moves with the tip.hashesPerSecondstringNetwork hashrate across the epoch:
difficulty × (endHeight − startHeight)divided by the seconds between the two timestamps, so both sides count the same block intervals. Omitted when the range covers no interval or no elapsed time.decimal string
oldestIndexinteger · int32Oldest epoch the table holds; absent while it is empty.
newestIndexinteger · int32Newest stored epoch, which stays a full epoch behind the tip. Absent while the table is empty.
backfillCompletebooleanrequiredWhether the table has reached its floor. While false it is still walking backwards and older epochs will appear.
statusstringrequiredHow far collection has got.
readymeans it reached the last checked chain tip.catching-upandrecoveringmean replay or reorg work is still running,stalemeans the last successful check is too old, andunavailablemeans collection failed. Ondisabledorloadingthe numbers are not evidence that the period was quiet.one ofdisabledloadingreadystaleunavailablecatching-uprecovering
400A negative index, a reversed range, or a limit outside 1–512.ApiError▶
errorintegerrequiredError code
reasonstringrequiredError message explaining the reason of the error
detailstringrequirednullableDetailed error description
503History is loading, disabled, busy, or unreadable. Check `mining.status` in /stats before retrying.ApiError▶
errorintegerrequiredError code
reasonstringrequiredError message explaining the reason of the error
detailstringrequirednullableDetailed error description