Latest, Safe and Finalized Ethereum Block Tags
Understand latest, safe and finalized block tags, choose a confirmation policy, and keep low-latency displays separate from final records.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
Ethereum clients expose block tags that express different relationships to the chain head. A dashboard and a settlement workflow often need different policies. Treat the tag as part of the request contract rather than a hidden client default.
Separate freshness from confidence
Latest targets the current execution head. Safe and finalized refer to consensus-informed checkpoints when supported by the client and network. They are not fixed numbers of seconds behind latest. Other EVM networks can have different consensus and tag behaviour, so do not transfer an Ethereum policy by name alone.
Worked example: two views of one deposit
A wallet UI shows an observed deposit as pending after a latest-block read. A downstream ledger waits until its block falls under the chosen finalized checkpoint before releasing a settlement event. Both views can reference the same transaction hash while reporting different workflow states. Store the checkpoint used instead of overwriting the earlier observation.
Make the policy observable
Record the requested tag and the returned block number and hash. Test unsupported tags, missing responses and a stalled finalized head. A timeout is a service condition, not evidence that a deposit disappeared. Show freshness separately from settlement eligibility, and document whether callers may request a different policy.
A practical acceptance test
Give the test endpoint three different returned heights for latest, safe and finalized. Check that the selected policy appears in the result and that changing policy changes the queried reference. Then freeze finalized while latest advances. The application should report the observed confidence boundary without inventing a fixed delay or downgrading settlement automatically.
Questions about the topic
Frequently asked questions
Does latest mean irreversible?
No. It identifies the current head and can change.
Is finalized a universal cross-chain tag?
No. Availability and meaning depend on the network and client implementation.
Standards & technical documentation
