Checkpoints

Every block hash depends on the block before it. So if you know the hash of block 120,000, you know, in effect, the entire chain up to that point: change any earlier byte and that hash would come out different.

Pearl’s node software ships with such hashes written in. They are checkpoints: one known block hash every 10,000 blocks. A node checks the chain it downloads against them and refuses anything that disagrees.

Try it

Edit an old block in this little chain and watch every later hash change. A checkpoint is simply one of those later hashes, written down in advance.

What are Pearl’s checkpoints?

Twelve pairs of height and block hash, in pearld v1.5.2:

Each hash was checked against Pearl’s public block explorer, and all twelve match. For block 120,000, the research behind this site went further: it fetched the raw block and hashed its header with Pearl’s own code, which gives exactly the checkpoint hash.

When is a checkpoint added?

Once a block is deep enough that nobody expects it to change. The code’s rule of thumb is CheckpointConfirmations = 2016: a candidate must have at least 2,016 blocks on top of it, about four and a half days at the target pace. Then a developer adds the next multiple of 10,000 in a new release.

So the list grows with each release, and older releases simply know fewer checkpoints.

What does a node do with them?

Several things, all in pearld v1.5.2:

1. Match

   A block at a checkpoint height must have exactly the checkpoint’s hash, or it fails with ErrBadCheckpoint, whatever its work.

2. No forks below the latest

   A block that would fork the chain below the latest checkpoint (block 120,000) is refused with ErrForkTooOld. The code comment’s reason: such blocks build on old, easier difficulty and could be used to waste memory and disk. It also means no reorganization can reach below that block.

3. Skip script checks below it

   While catching up, scripts and signatures at or below the latest checkpoint aren’t run: the checkpoint’s hash already pins every transaction through the Merkle roots. Running scripts is the slowest part of checking a block, so this is a big speed-up. Each block’s certificate is still verified.

4. Sync headers in checkpoint-sized steps

   A new node downloads headers, with their certificates, up to the next checkpoint before it fetches the blocks. See messages.

5. Sanity-check claimed difficulty

   Before fully checking an unknown block, a node compares its bits with the last checkpoint’s: over a time D, the target can’t have grown by more than (87/32) per started week. See WTEMA.

Pearl’s DNS seeders use checkpoints too. They only hand out addresses of nodes whose chain reaches at least the latest checkpoint, which weeds out nodes stuck on an old, pre-fork chain. See peers and seeds.

Why one every 10,000 blocks?

The comment next to the list gives the reason: “denser checkpoints cap how much headers-first sync progress a peer disconnect can throw away.” A new node syncs headers one checkpoint-sized stretch at a time. If the peer it’s syncing from drops out halfway, the node has at most one stretch to redo.

On Pearl that matters more than on Bitcoin, because each header travels with its roughly 60 KB certificate, and the node verifies every one.

Doesn’t that mean trusting the developers?

A little, and it’s worth being clear how much.

The checkpoints are in the open source code, and anyone can compare them with the chain, as this page’s research did. A checkpoint can’t make an invalid block valid: blocks below it still need valid certificates and must link up correctly. What it does do is freeze history: a node won’t consider any chain that disagrees with a checkpoint or forks below the latest one, however much work it has. And below the latest checkpoint, transaction scripts aren’t re-checked during sync.

So you trust that the block hashes in the release were the real chain when they were written in, something you can check yourself, in exchange for faster syncing and protection against deep rewrites.

blockHash := header.BlockHash()
if !c.VerifyCheckpoint(blockHeight, &blockHash) {
	return ruleError(ErrBadCheckpoint, str)
}
checkpointNode, err := c.FindPreviousCheckpoint()
if checkpointNode != nil && blockHeight < checkpointNode.Height() {
	return ruleError(ErrForkTooOld, str)
}

checkpoint := b.LatestCheckpoint()
runScripts := true
if checkpoint != nil && node.height <= checkpoint.Height {
	runScripts = false
}