Document blockTag possible values

[matbour]

I recently migrated from ethers.js v5 to Viem and I wanted to use the blockTag options to the getBalance action.

I ethers.js v5, blockTag is defined like this:

• latest: Refers to the most recently mined block.
• earliest: Refers to the earliest available block, which is the genesis block for the blockchain.
• pending: Refers to the transactions that are currently in the pending state and have not yet been included in a block.

Viem describes blockTag type as 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized', however I cannot find any documentation about their meaning.

My questions are the following:

1. Does viem uses the same definition for latest, earliest and pending?
2. What does safe and finalized blockTag states mean?

[tmm]

Would be good to add this to the glossary.

[ishfx]

Definitely !

I found this article explaining the missing ones: https://www.alchemy.com/overviews/ethereum-commitment-levels, if it helps!