Skip to content

Commit 3d4cbee

Browse files
khadnikhadni
committed
add finality & confidence levels docs
1 parent 1b02e24 commit 3d4cbee

File tree

9 files changed

+227
-44
lines changed

9 files changed

+227
-44
lines changed

‎reports/llms-report.json‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,22 @@
11
{
2-
"startedAt": "2025-12-01T18:57:15.612Z",
2+
"startedAt": "2025-12-03T19:50:28.559Z",
33
"siteBase": "https://docs.chain.link",
44
"sections": [
55
{
66
"section": "cre-go",
7-
"pagesProcessed": 83,
7+
"pagesProcessed": 84,
88
"outputPath": "src/content/cre/llms-full-go.txt",
9-
"bytes": 651940,
9+
"bytes": 655971,
1010
"prevBytes": 651940,
11-
"deltaBytes": 0
11+
"deltaBytes": 4031
1212
},
1313
{
1414
"section": "cre-ts",
15-
"pagesProcessed": 78,
15+
"pagesProcessed": 79,
1616
"outputPath": "src/content/cre/llms-full-ts.txt",
17-
"bytes": 607447,
17+
"bytes": 611390,
1818
"prevBytes": 607447,
19-
"deltaBytes": 0
19+
"deltaBytes": 3943
2020
},
2121
{
2222
"section": "vrf",
@@ -31,8 +31,8 @@
3131
"pagesProcessed": 260,
3232
"outputPath": "src/content/ccip/llms-full.txt",
3333
"bytes": 2849282,
34-
"prevBytes": 2849278,
35-
"deltaBytes": 4
34+
"prevBytes": 2849282,
35+
"deltaBytes": 0
3636
},
3737
{
3838
"section": "data-feeds",
@@ -119,9 +119,9 @@
119119
"pagesProcessed": 55,
120120
"outputPath": "src/content/chainlink-local/llms-full.txt",
121121
"bytes": 297281,
122-
"prevBytes": 297263,
123-
"deltaBytes": 18
122+
"prevBytes": 297281,
123+
"deltaBytes": 0
124124
}
125125
],
126-
"finishedAt": "2025-12-01T18:57:19.195Z"
126+
"finishedAt": "2025-12-03T19:50:32.866Z"
127127
}

‎src/config/sidebar.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -418,6 +418,10 @@ export const SIDEBAR: Partial<Record<Sections, SectionEntry[]>> = {
418418
title: "TypeScript Runtime Environment",
419419
url: "cre/concepts/typescript-wasm-runtime",
420420
},
421+
{
422+
title: "Finality and Confidence Levels",
423+
url: "cre/concepts/finality",
424+
},
421425
],
422426
},
423427
{

‎src/content/cre/concepts/finality.mdx‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
section: cre
3+
title: "Finality and Confidence Levels"
4+
date: Last Modified
5+
metadata:
6+
description: "Understand how CRE handles blockchain finality across different chains, including confidence levels, finality tags, and block depth configurations."
7+
datePublished: "2025-12-03"
8+
lastModified: "2025-12-03"
9+
---
10+
11+
import { Aside, CopyText } from "@components"
12+
13+
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.
14+
15+
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.
16+
17+
You specify confidence levels in two places:
18+
19+
- **[EVM Log Triggers](/cre/reference/sdk/triggers/evm-log-trigger)** — The `confidence` parameter determines when the trigger fires based on block finality.
20+
- **[EVM Client contract reads](/cre/reference/sdk/evm-client)** — The `blockNumber` parameter lets you query data from `LATEST` or `FINALIZED` blocks.
21+
22+
## Confidence levels
23+
24+
When reading from the blockchain or setting up triggers, you can specify one of three confidence levels:
25+
26+
| Confidence Level | Description | Use Case |
27+
| ---------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
28+
| **`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. |
29+
| **`SAFE`** | A block that is unlikely to be reorganized, but not yet fully finalized. | A balance between speed and security for most operations. |
30+
| **`FINALIZED`** | A block that is considered irreversible. This is the safest option. | Critical operations where you need absolute certainty the data won't change. |
31+
32+
<Aside type="note" title="Default behavior">
33+
If you don't specify a confidence level, CRE defaults to `SAFE` for triggers and `LATEST` for contract reads.
34+
</Aside>
35+
36+
### Choosing the right level
37+
38+
- **Use `FINALIZED`** when: Processing financial transactions, updating critical state, or when incorrect data could cause significant issues.
39+
- **Use `SAFE`** when: You need reasonable confidence without waiting for full finality. Good for most monitoring and alerting use cases.
40+
- **Use `LATEST`** when: Building real-time dashboards, price displays, or other applications where showing the most current data is more important than guaranteed accuracy.
41+
42+
## How confidence levels work per chain
43+
44+
CRE translates confidence levels to the appropriate blockchain mechanism:
45+
46+
### SAFE and LATEST
47+
48+
For all supported chains, `SAFE` and `LATEST` use the chain's native `safe` and `latest` block tags respectively. These are standard JSON-RPC block parameters supported by all CRE-compatible chains.
49+
50+
### FINALIZED
51+
52+
- **Finality tag**: Uses the chain's native `finalized` block tag
53+
- **Block depth**: Waits for a specified number of blocks to pass
54+
55+
| Chain | Finality Method | Block Depth |
56+
| ------------------------------- | --------------- | ----------- |
57+
| Arbitrum One / Arbitrum Sepolia | Finality tag | — |
58+
| Avalanche / Avalanche Fuji | Finality tag | — |
59+
| Base / Base Sepolia | Finality tag | — |
60+
| BNB Chain / BNB Testnet | Finality tag | — |
61+
| Ethereum / Ethereum Sepolia | Finality tag | — |
62+
| OP Mainnet / OP Sepolia | Finality tag | — |
63+
| Polygon / Polygon Amoy | Block depth | 500 |

‎src/content/cre/llms-full-go.txt‎

Lines changed: 69 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7112,6 +7112,64 @@ Yes. Once you call `runtime.Rand()` and get a `*rand.Rand` object, you can reuse
71127112

71137113
---
71147114

7115+
# Finality and Confidence Levels
7116+
Source: https://docs.chain.link/cre/concepts/finality
7117+
Last Updated: 2025-12-03
7118+
7119+
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.
7120+
7121+
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.
7122+
7123+
You specify confidence levels in two places:
7124+
7125+
- **[EVM Log Triggers](/cre/reference/sdk/triggers/evm-log-trigger)** — The `confidence` parameter determines when the trigger fires based on block finality.
7126+
- **[EVM Client contract reads](/cre/reference/sdk/evm-client)** — The `blockNumber` parameter lets you query data from `LATEST` or `FINALIZED` blocks.
7127+
7128+
## Confidence levels
7129+
7130+
When reading from the blockchain or setting up triggers, you can specify one of three confidence levels:
7131+
7132+
| Confidence Level | Description | Use Case |
7133+
| ---------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
7134+
| **`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. |
7135+
| **`SAFE`** | A block that is unlikely to be reorganized, but not yet fully finalized. | A balance between speed and security for most operations. |
7136+
| **`FINALIZED`** | A block that is considered irreversible. This is the safest option. | Critical operations where you need absolute certainty the data won't change. |
7137+
7138+
<Aside type="note" title="Default behavior">
7139+
If you don't specify a confidence level, CRE defaults to `SAFE` for triggers and `LATEST` for contract reads.
7140+
</Aside>
7141+
7142+
### Choosing the right level
7143+
7144+
- **Use `FINALIZED`** when: Processing financial transactions, updating critical state, or when incorrect data could cause significant issues.
7145+
- **Use `SAFE`** when: You need reasonable confidence without waiting for full finality. Good for most monitoring and alerting use cases.
7146+
- **Use `LATEST`** when: Building real-time dashboards, price displays, or other applications where showing the most current data is more important than guaranteed accuracy.
7147+
7148+
## How confidence levels work per chain
7149+
7150+
CRE translates confidence levels to the appropriate blockchain mechanism:
7151+
7152+
### SAFE and LATEST
7153+
7154+
For all supported chains, `SAFE` and `LATEST` use the chain's native `safe` and `latest` block tags respectively. These are standard JSON-RPC block parameters supported by all CRE-compatible chains.
7155+
7156+
### FINALIZED
7157+
7158+
- **Finality tag**: Uses the chain's native `finalized` block tag
7159+
- **Block depth**: Waits for a specified number of blocks to pass
7160+
7161+
| Chain | Finality Method | Block Depth |
7162+
| ------------------------------- | --------------- | ----------- |
7163+
| Arbitrum One / Arbitrum Sepolia | Finality tag | — |
7164+
| Avalanche / Avalanche Fuji | Finality tag | — |
7165+
| Base / Base Sepolia | Finality tag | — |
7166+
| BNB Chain / BNB Testnet | Finality tag | — |
7167+
| Ethereum / Ethereum Sepolia | Finality tag | — |
7168+
| OP Mainnet / OP Sepolia | Finality tag | — |
7169+
| Polygon / Polygon Amoy | Block depth | 500 |
7170+
7171+
---
7172+
71157173
# CRE Templates
71167174
Source: https://docs.chain.link/cre/templates
71177175
Last Updated: 2025-11-21
@@ -9110,7 +9168,7 @@ func onCronTrigger(config *Config, runtime cre.Runtime, trigger *cron.Payload) (
91109168
}
91119169
logger.Info("Successfully fetched offchain value", "result", offchainValue)
91129170

9113-
9171+
91149172
// Get the first EVM configuration from the list.
91159173
evmConfig := config.Evms[0]
91169174

@@ -9146,7 +9204,7 @@ func onCronTrigger(config *Config, runtime cre.Runtime, trigger *cron.Payload) (
91469204
return &MyResult{
91479205
FinalResult: finalResult,
91489206
}, nil
9149-
9207+
91509208
}
91519209

91529210
func main() {
@@ -9451,7 +9509,7 @@ func onCronTrigger(config *Config, runtime cre.Runtime, trigger *cron.Payload) (
94519509
}
94529510
logger.Info("Successfully read onchain value", "result", onchainValue)
94539511

9454-
9512+
94559513
// Step 3: Calculate the final result
94569514
finalResultInt := new(big.Int).Add(onchainValue, offchainValue)
94579515

@@ -9474,7 +9532,7 @@ func onCronTrigger(config *Config, runtime cre.Runtime, trigger *cron.Payload) (
94749532
logger.Info("Workflow finished successfully!", "result", finalWorkflowResult)
94759533

94769534
return finalWorkflowResult, nil
9477-
9535+
94789536
}
94799537

94809538
func fetchMathResult(config *Config, logger *slog.Logger, sendRequester *http.SendRequester) (*big.Int, error) {
@@ -13371,10 +13429,10 @@ func (c *Client) CallContract(runtime cre.Runtime, input *CallContractRequest) c
1337113429

1337213430
This is the main input object for the `CallContract` function. It acts as a wrapper for the call message and an optional block number.
1337313431

13374-
| Field | Type | Description |
13375-
| ------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13376-
| `Call` | `*evm.CallMsg` | Contains the actual details of the function call you want to make. |
13377-
| `BlockNumber` | `*pb.BigInt` | Optional. The block number to query. Defaults to `latest`. Use `-2` for `latest` (the most recent block, which may be subject to re-orgs) or `-3` for `finalized` (a block that is considered immutable and safe from re-orgs). |
13432+
| Field | Type | Description |
13433+
| ------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13434+
| `Call` | `*evm.CallMsg` | Contains the actual details of the function call you want to make. |
13435+
| `BlockNumber` | `*pb.BigInt` | Optional. The block number to query. Defaults to `latest`. Use `-2` for `latest` (the most recent block, which may be subject to re-orgs) or `-3` for `finalized` (a block that is considered immutable and safe from re-orgs). See [Finality and Confidence Levels](/cre/concepts/finality) for details on how finality is determined per chain. |
1337813436

1337913437
#### `evm.CallMsg`
1338013438

@@ -14122,9 +14180,9 @@ The configuration struct for the EVM log trigger.
1412214180
| `Topics` | `[]*evm.TopicValues` | A fixed 4-element array to filter event topics. The first element contains event signatures, and the next three elements contain indexed argument values. An empty array element acts as a wildcard. |
1412314181
| `Confidence` | `ConfidenceLevel` | The block confirmation level to monitor. Can be: <ul><li>**`evm.ConfidenceLevel_CONFIDENCE_LEVEL_SAFE` (default):** A block that is considered unlikely to be reorged but is not yet irreversible.</li><li>**`evm.ConfidenceLevel_CONFIDENCE_LEVEL_LATEST`:** The most recent block. This is the fastest but least secure, as the block could be orphaned. Best for non-critical, time-sensitive actions.</li><li>**`evm.ConfidenceLevel_CONFIDENCE_LEVEL_FINALIZED`:** A block that is considered irreversible. This is the safest option, as the event is guaranteed to be on the canonical chain, but it requires waiting longer for finality.</li></ul> |
1412414182

14125-
14126-
<Aside type="caution" title="SAFE block tag fallback">
14127-
**Some chains do not support the SAFE block tag** (e.g., Shibarium). When you specify `CONFIDENCE_LEVEL_SAFE` on chains that don't support it, CRE automatically falls back to `CONFIDENCE_LEVEL_FINALIZED` for safety. Users are responsible for knowing which chains support the SAFE tag. If you need consistent behavior across all chains, explicitly use `CONFIDENCE_LEVEL_FINALIZED` or `CONFIDENCE_LEVEL_LATEST`.
14183+
<Aside type="note" title="Finality details">
14184+
For details on how each confidence level maps to specific chains and estimated wait times, see [Finality and
14185+
Confidence Levels](/cre/concepts/finality).
1412814186
</Aside>
1412914187

1413014188
### `evm.Log`

0 commit comments

Comments
 (0)