Block header
Protocol and consensus12.4.15+

Block header

The 160-byte Lotus block header, field by field, how its three hash layers give the block hash, and the rules a header must pass.

A Lotus block header is 160 bytes. Its hash is built in three layers, so a device can check the chain and the proof of work with a small part of the header.

Layout #

Fields are serialized in this order. Integers are little-endian.

OffsetSizeFieldMeaning
032hashPrevBlockHash of the parent block; all zeros for the genesis block.
324nBitsCompact encoding of the target the block hash must meet.
366nTimeBlock time, Unix seconds.
422nReservedMust be 0.
448nNonceNonce the miner changes.
521nHeaderVersionVersion of the bytes that follow. Must be 1.
537nSizeSize of the serialized block in bytes.
604nHeightBlock height; the genesis block is 0.
6432hashEpochBlockEpoch block hash, see below.
9632hashMerkleRootMerkle root of the block's transactions.
12832hashExtendedMetadataHash of the extended metadata, see below.

Block hash #

The block hash is three nested single SHA-256 hashes:

Text
layer3 = SHA256(nHeaderVersion || nSize || nHeight || hashEpochBlock || hashMerkleRoot || hashExtendedMetadata)
layer2 = SHA256(nBits || nTime || nReserved || nNonce || layer3)
hash   = SHA256(hashPrevBlock || layer2)
LayerInput sizeLets you check
1, chain64 bytesThat blocks form a chain.
2, proof of work52 bytesThe target, the time and the nonce: enough for proof of work and the difficulty adjustment.
3, transactions108 bytesSize, height, epoch, the transaction Merkle root and the metadata hash.

A miner that changes only the nonce or the time rehashes layers 2 and 1; layer 3 stays fixed.

Epoch block hash #

Epochs are 5,040 blocks long (one week at 2-minute blocks). The rule is:

  • when nHeight is a multiple of 5,040, hashEpochBlock equals hashPrevBlock;
  • otherwise it equals the parent's hashEpochBlock.

So every block of an epoch points to the last block of the previous epoch. A header with another value is rejected with bad-blk-epoch.

Merkle root #

Each leaf is the double SHA-256 of a transaction's hash followed by its transaction id. Leaves are hashed in pairs with double SHA-256 up to the root. A level with an odd number of hashes is completed with a 32-byte zero hash; the last hash is not duplicated.

Extended metadata #

After the header, a block carries a list of metadata fields, then its transactions:

TypeMeaning
compact sizeNumber of fields.
field[]The fields.

Each field is:

TypeMeaning
4 bytesField id.
compact sizeLength of the data.
bytesData.

hashExtendedMetadata is the double SHA-256 of that serialized list. For an empty list it is the double SHA-256 of the single byte 0x00:

Text
9a538906e6466ebd2617d321f71bc94e56056ce213d366773699e28158e00614

A block carries either no field or exactly one field. The only defined fields hold a merged-mining proof:

Field idParent proof
1Scrypt parent, classic tag
2SHA-256d parent, classic tag
3Scrypt parent, positional anchor
4SHA-256d parent, positional anchor

Any other field, or more than one, makes the block invalid (bad-metadata).

Napoleon upgrade

On mainnet, a block with a metadata field is valid only from the Napoleon activation (median time past 1797886200, 21 December 2026, 20:50 UTC). Before it, a mainnet header whose own hash does not meet its target is rejected. See Merged mining.

Header rules #

RuleReject reason
nReserved is 0bad-blk-reserved
nHeaderVersion is 1bad-blk-version
nHeight is the parent's height plus onebad-blk-height
nBits is the value the difficulty algorithm givesbad-diffbits
nTime is later than the median time of the last 11 blockstime-too-old
nTime is at most 2 hours ahead of the node's clocktime-too-new
hashEpochBlock follows the epoch rulebad-blk-epoch
hashExtendedMetadata matches the metadatabad-metadata-hash
nSize is not above the block size limitbad-blk-size

Genesis block #

Mainnet
Hash000000000abc0cde58ee7e919d3d4de183e6844add1fd5d14b4eac89d958f470
Time1624246260 (2021-06-21 03:31:00 UTC)
nBits0x1c100000
Nonce7146261898250975403
Merkle root37f392d88f70cdada6d366a25a7ef90b6711bf2d6b5ffea4f39727dcb90af34c
Size379 bytes
Coinbase messageJohn 1:1 In the beginning was the Logos

Read a header #

Shell
lotus-cli getblockheader 000000000abc0cde58ee7e919d3d4de183e6844add1fd5d14b4eac89d958f470
Source share/www/docs/block-header.md in the lotusd repository
Checked against src/primitives/block.h src/primitives/block.cpp src/validation.cpp src/chainparams.cpp