# Finality and Confidence Levels
Source: https://docs.chain.link/cre/concepts/finality-go
Last Updated: 2025-12-10

> For the complete documentation index, see [llms.txt](/llms.txt).

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 issues
- **`SAFE`** — 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 a native finality tag or a block depth threshold depending on the chain.

| Chain                           | Finality Method              | Block Depth |
| ------------------------------- | ---------------------------- | ----------- |
| 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 ago) | 500         |

## Finality for chain reads

Chain read operations ([`CallContract`](/cre/reference/sdk/evm-client-go#callcontract), [`BalanceAt`](/cre/reference/sdk/evm-client-go#balanceat), [`FilterLogs`](/cre/reference/sdk/evm-client-go#filterlogs), etc.) support confidence levels and custom block depths.

### Using confidence levels

For most read operations, use the standard confidence levels by passing `-2` (latest) or `-3` (finalized) 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:**

You can pass any `*big.Int` directly as the `BlockNumber` parameter. The SDK accepts both special values (like `-2` for latest, `-3` for finalized) and positive integers for explicit block heights. See [Onchain Read](/cre/guides/workflow/using-evm-client/onchain-read-go#custom-block-depths) for examples.

## Finality for chain writes

Chain write operations return a [`WriteReportReply`](/cre/reference/sdk/evm-client-go#evmwritereportreply) when the transaction is included in a block, not when it reaches finality.

### What a successful response means

When [`WriteReportReply`](/cre/reference/sdk/evm-client-go#evmwritereportreply) returns with `TxStatus` equal to `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

> **CAUTION: For mission-critical applications**
>
> If you need absolute certainty that your write transaction reached finality, implement post-write verification by
> reading the blockchain state after a custom number of confirmations. Do not rely solely on `WriteReportReply` for
> finality confirmation.

## 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](/cre/reference/sdk/triggers/evm-log-trigger-go#evmfilterlogtriggerrequest).