Height

Position of a block in the blockchain

Diagram showing the height of a block in the blockchain as its distance from the genesis block.
Current Height:
Note: This is the height of the block at the tip of the blockchain.

The height of a block indicates its position in the blockchain.

It's calculated based on its distance from the genesis block.

Counting starts at zero. So the first block in the blockchain (the genesis block) is block 0.

Usage

How is the height used in Bitcoin?

There are two major adjustments that take place in Bitcoin at specific height intervals.

1. Target Adjustment

2,016 blocks

Diagram showing the target adjustment taking place on every 2016th block.
Next Adjustment 840,672 (588 blocks away)
Current Height 840,084

The target adjusts after every 2,016 blocks (roughly every 2 weeks).

This helps to keep a 10-minute interval between blocks as miners join and leave the network over time.

For example, the first target adjustment took place at block height of 2,016, the second at a height of 4,032, the third at a height of 6,048, and so on.

2. Block Subsidy Halving

210,000 blocks

Diagram showing the block subsidy halving on every 210,000th block.
Next Halving 1,050,000 (209,916 blocks away)
Current Height 840,084

The block subsidy halves after every 210,000 blocks (roughly every 4 years).

This halving of the block subsidy is what creates the fixed supply of bitcoin, as eventually the subsidy will reach zero and no new bitcoins will be issued.

For example, the block subsidy started at 50 BTC. Then at the block height of 210,000 it halved to 25 BTC, and at block height 420,000 it halved to 12.5 BTC, and so on. At block height 6,930,000 (and after 33 halvings in total) the subsidy will reach zero.

Other

The height is used in a few other places in Bitcoin, primarily to do with the eligibility for transactions to get mined:

Locktime

Diagram showing how the locktime field can be used to prevent a transaction from being mined until a specific block height or time in the future.

The locktime field can be used to prevent a transaction from being mined until after a specific height.

For example, if you set a locktime of 500,000 on a transaction, that transaction could only be mined in to a block with a height of 500,001 or above.

Relative Locktime

Diagram showing the sequence field being used to set a relative locktime on the transaction.

Relative locktime can be used to prevent a transaction from being mined until the output it's spending has reached a certain depth in the blockchain.

For example, if you set a relative locktime of 100 blocks on a transaction input spending the output of a transaction in block 500,000, that transaction can only get mined in to a block at a height of 500,101 or above.

Coinbase Transaction

Diagram showing the height of the current block being included inside the coinbase transaction for that block.

Since block 227,836, all coinbase transactions must contain the height of the block they are going to be mined in.

This forces each coinbase transaction to have a unique TXID, as before this it was possible for coinbase transactions in different blocks to have the same TXID.

Referencing

Is the height a unique identifier for a block?

The height is not guaranteed to be a unique identifier for a block.

During the mining process, it's possible that two blocks will get mined at the same time. Therefore, there can be two different blocks competing for the same height in the blockchain:

Diagram showing two blocks competing for the same height at the top of the blockchain.
This is a normal part of how bitcoin works.

Consequently, depending on which block gets built on top of first, there is a chance a block occupying a height close to the top of the chain will change:

Diagram showing a different block occupying a specific height in the blockchain after a chain reorganisation.
This is known as a chain reorganisation.

So whilst the height is a generally useful way to reference a block in the blockchain, it can't always be relied upon to reference a specific block, especially if that block is close to the top of the blockchain.

Commands

bitcoin-cli getblockcount

This command returns the current height of the blockchain.

$ bitcoin-cli getblockcount
840084

The height of the blockchain is currently 840,084. But because counting starts at zero, there are technically 840,085 blocks in the blockchain in total. This is not a terribly useful fact, but I thought I would mention it anyway.

bitcoin-cli getblockhash [height]

This command returns the block hash for a specific height in the blockchain.

$ bitcoin-cli getblockhash 840084
000000000000000000032acb84ff0b9620f8584ce3b6b566c14e363e27d44fa4

As mentioned, the height is not a reliable way to reference blocks near the top of the blockchain. For example, if you were to use bitcoin-cli getblockhash 840084 to get the block hash for the block currently at the top of the chain, the result may change if a chain reorganisation takes place.

If your node holds multiple blocks at the same height, this command will return the block hash for the block that is part of the current longest chain. If there are multiple blocks at the tip of your chain, your node will consider the first block it received as part of the current longest chain (but again, this is liable to change if there is a chain reorganisation).

bitcoin-cli getblockheader [hash]

This command provides basic information about a block, including its height.

$ bitcoin-cli getblockheader 000000000000000000032acb84ff0b9620f8584ce3b6b566c14e363e27d44fa4
{
    "hash": "000000000000000000032acb84ff0b9620f8584ce3b6b566c14e363e27d44fa4",
    "confirmations": 1,
    "height": 840084,
    "version": 702857216,
    "versionHex": "29e4c000",
    "merkleroot": "88c5ed6296081ba289ad728acc2e421029169d95d5ee59a51f5303e241009e11",
    "time": 1713627390,
    "mediantime": 1713623433,
    "nonce": 1929595021,
    "bits": "17034219",
    "difficulty": 86388558925171.02,
    "chainwork": "00000000000000000000000000000000000000007555a2aa93ad61d84ee906c7",
    "nTx": 5208,
    "previousblockhash": "00000000000000000002956ca8c9e1bc3f8b64e2eaa105b76c147644d5ed7f6a"
}

Summary

The height is used to reference a block occupying a specific position in the blockchain.

You're better off using the block hash to reliably reference a block though, as the blocks near the top of the blockchain can change due to chain reorganisations.

However, once a block makes it 3 or more blocks deep in the blockchain it's probably not going to be replaced by another block, and the height becomes good enough as a unique identifier. But still, it's safer to use the block hash if you can.