Bitcoin Core getchaintips RPC: Fork and Branch Monitoring Guide

This guide explains Bitcoin Core getchaintips RPC in plain English. It shows what the command does, what its result means and what it cannot prove.

Active entry

The active tip has branchlen zero and active status. Verify there is exactly one active entry in a coherent response and compare its hash with getbestblockhash. A mismatch across calls can be a normal tip transition, so sample with timestamps and retry under a bounded consistency procedure.

Branch length

For non-active tips, branchlen describes how many blocks connect the tip back to the active branch point. It is not confirmation count, economic weight or number of affected transactions. Walk header ancestry to locate the fork and measure which monitored payments or templates actually intersect it.

Status meanings

invalid contains an invalid block; headers-only lacks block data; valid-headers has available blocks not fully validated; valid-fork is fully validated but inactive; active is the selected main tip. Preserve these distinctions. A headers-only branch is not evidence of a valid competing chain, and a valid fork is not necessarily dangerous.

Local knowledge

The node reports branches it has learned about and retained. Another node may know different tips because of peers, pruning, restart or attack visibility. Compare several independent nodes and relevant logs. Absence from one response does not prove a branch never existed or was not seen elsewhere.

Alert policy

Short valid forks occur naturally when blocks race. Alert on depth, duration, chainwork proximity, invalid-source patterns and affected business state rather than every second tip. Escalate deep or persistent divergence and pause sensitive services when confirmation assumptions are threatened.

Evidence retention

Record tip hash, height, branch length, status, active tip, chainwork and observation time without storing unrelated peer identities. Preserve detached headers and affected transaction references through the incident. Do not delete a branch record when it disappears from the live RPC response.

How specialists test it

Operators test the command on a non-production node first. They check a normal reply, an invalid request, a timeout and a restart. This shows what the response means and prevents one local result from being mistaken for a network-wide outcome.

Conclusion

getchaintips is the correct local view for competing branch awareness, but it requires status, ancestry, chainwork and multi-node context. Short forks are evidence to evaluate, not automatic proof of attack.