Finality and Confidence Levels
Finality determines when a blockchain transaction is considered irreversible. Until a block is finalized, it could be reorganized (replaced by a different block if the chain temporarily forks), which means any data you read from it might change.
Different blockchains achieve finality in different ways and at different speeds. CRE abstracts these differences through confidence levels, allowing you to specify your finality requirements without needing to know the underlying chain-specific implementation.
Understanding CRE's finality model
CRE provides three confidence levels for reading blockchain data and monitoring events. These levels work consistently across all supported chains.
The three confidence levels
| Confidence Level | Description | Use Case |
|---|---|---|
LATEST | The most recent block. No finality guarantees—the block could still be reorganized. | Non-critical, time-sensitive operations where speed matters more than certainty. |
SAFE | A block that is unlikely to be reorganized, but not yet fully finalized. | A balance between speed and security for most operations. |
FINALIZED | A block that is considered irreversible. This is the safest option. | Critical operations where you need absolute certainty the data won't change. |
Choosing the right level:
FINALIZED— Use for financial transactions, critical state updates, or when incorrect data could cause significant issuesSAFE— Use when you need reasonable confidence without waiting for full finality (good for most monitoring/alerting)LATEST— Use for real-time dashboards or displays where speed matters more than guaranteed accuracy
How confidence levels map to chains
SAFE and LATEST:
CRE uses the chain's native safe and latest block tags respectively for all supported chains.
FINALIZED:
When you specify FINALIZED in your workflow, CRE automatically maps this to its finality method—whether it uses the native finality tag or block depth (with the number of blocks specified for block depth).
| Chain | Finality Method |
|---|---|
| Arbitrum One / Arbitrum Sepolia | Native finalized tag |
| Avalanche / Avalanche Fuji | Native finalized tag |
| Base / Base Sepolia | Native finalized tag |
| BNB Chain / BNB Testnet | Native finalized tag |
| Ethereum / Ethereum Sepolia | Native finalized tag |
| OP Mainnet / OP Sepolia | Native finalized tag |
| Polygon / Polygon Amoy | Block depth (500 blocks) |
Finality for chain reads
Chain read operations (CallContract, BalanceAt, FilterLogs, etc.) support confidence levels and custom block depths.
Using confidence levels
For most read operations, use the standard confidence levels by passing LATEST_BLOCK_NUMBER or LAST_FINALIZED_BLOCK_NUMBER as the blockNumber parameter. If you don't specify a block number, CRE defaults to LATEST.
Note: The SAFE confidence level is not available for chain reads—only LATEST and FINALIZED are supported.
Custom block depths
For use cases requiring fixed confirmation thresholds or historical state verification, you can specify any explicit block number instead of using the predefined confidence levels. This enables you to:
- Implement custom finality rules tailored to your risk profile (e.g., "always wait 1,000 blocks")
- Meet regulatory requirements that mandate fixed, auditable confirmation thresholds
- Query historical state at specific past block heights for analysis or verification
When to use custom block depths:
- Regulatory compliance — Your interactions require provable, fixed confirmation thresholds for auditors
- Changing chain parameters — The chain's finality definition may change, but your security model must remain constant
- Historical verification — You need to verify state at a specific moment
Implementation:
Block numbers must be provided as BigIntJson objects. See Onchain Read for the conversion pattern and examples.
Finality for chain writes
Chain write operations return a WriteReportReply when the transaction is included in a block, not when it reaches finality.
What a successful response means
When WriteReportReply returns with txStatus equal to TX_STATUS_SUCCESS:
- Your transaction was included in a block
- The transaction is not necessarily finalized yet
The reply is returned as soon as the transaction appears in a block, not when the block reaches finality. This is important for time-sensitive workflows, but it means the transaction could still be reorganized.
Reorg handling
If a block containing your transaction is reorganized:
- CRE's Transaction Manager (TXM) automatically resubmits your transaction
- Gas bumping is applied as needed to ensure the transaction is included
- Important: The transaction hash may change during resubmission
- You are not automatically notified if the hash changes
Finality for event triggers
EVM Log Triggers must use the three confidence levels (LATEST, SAFE, or FINALIZED). Custom block depths are not supported for triggers.
By default, triggers use SAFE if no confidence level is specified. For details on configuring trigger confidence levels, see EVM Log Trigger.