From 3d4cbee18499e2c5e7fdadb44bc71084e926ab76 Mon Sep 17 00:00:00 2001 From: Karim <98668332+khadni@users.noreply.github.com> Date: Wed, 3 Dec 2025 14:52:51 -0500 Subject: [PATCH 01/11] add finality & confidence levels docs --- reports/llms-report.json | 24 +++--- src/config/sidebar.ts | 4 + src/content/cre/concepts/finality.mdx | 63 +++++++++++++++ src/content/cre/llms-full-go.txt | 80 ++++++++++++++++--- src/content/cre/llms-full-ts.txt | 72 +++++++++++++++-- .../cre/reference/sdk/evm-client-go.mdx | 8 +- .../cre/reference/sdk/evm-client-ts.mdx | 8 +- .../sdk/triggers/evm-log-trigger-go.mdx | 6 +- .../sdk/triggers/evm-log-trigger-ts.mdx | 6 +- 9 files changed, 227 insertions(+), 44 deletions(-) create mode 100644 src/content/cre/concepts/finality.mdx diff --git a/reports/llms-report.json b/reports/llms-report.json index 6090a043287..b562ca12950 100644 --- a/reports/llms-report.json +++ b/reports/llms-report.json @@ -1,22 +1,22 @@ { - "startedAt": "2025-12-01T18:57:15.612Z", + "startedAt": "2025-12-03T19:50:28.559Z", "siteBase": "https://docs.chain.link", "sections": [ { "section": "cre-go", - "pagesProcessed": 83, + "pagesProcessed": 84, "outputPath": "src/content/cre/llms-full-go.txt", - "bytes": 651940, + "bytes": 655971, "prevBytes": 651940, - "deltaBytes": 0 + "deltaBytes": 4031 }, { "section": "cre-ts", - "pagesProcessed": 78, + "pagesProcessed": 79, "outputPath": "src/content/cre/llms-full-ts.txt", - "bytes": 607447, + "bytes": 611390, "prevBytes": 607447, - "deltaBytes": 0 + "deltaBytes": 3943 }, { "section": "vrf", @@ -31,8 +31,8 @@ "pagesProcessed": 260, "outputPath": "src/content/ccip/llms-full.txt", "bytes": 2849282, - "prevBytes": 2849278, - "deltaBytes": 4 + "prevBytes": 2849282, + "deltaBytes": 0 }, { "section": "data-feeds", @@ -119,9 +119,9 @@ "pagesProcessed": 55, "outputPath": "src/content/chainlink-local/llms-full.txt", "bytes": 297281, - "prevBytes": 297263, - "deltaBytes": 18 + "prevBytes": 297281, + "deltaBytes": 0 } ], - "finishedAt": "2025-12-01T18:57:19.195Z" + "finishedAt": "2025-12-03T19:50:32.866Z" } diff --git a/src/config/sidebar.ts b/src/config/sidebar.ts index 3d537eb6c0c..5f56ce5e21c 100644 --- a/src/config/sidebar.ts +++ b/src/config/sidebar.ts @@ -418,6 +418,10 @@ export const SIDEBAR: Partial> = { title: "TypeScript Runtime Environment", url: "cre/concepts/typescript-wasm-runtime", }, + { + title: "Finality and Confidence Levels", + url: "cre/concepts/finality", + }, ], }, { diff --git a/src/content/cre/concepts/finality.mdx b/src/content/cre/concepts/finality.mdx new file mode 100644 index 00000000000..2ba69dcd2f1 --- /dev/null +++ b/src/content/cre/concepts/finality.mdx @@ -0,0 +1,63 @@ +--- +section: cre +title: "Finality and Confidence Levels" +date: Last Modified +metadata: + description: "Understand how CRE handles blockchain finality across different chains, including confidence levels, finality tags, and block depth configurations." + datePublished: "2025-12-03" + lastModified: "2025-12-03" +--- + +import { Aside, CopyText } from "@components" + +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. + +You specify confidence levels in two places: + +- **[EVM Log Triggers](/cre/reference/sdk/triggers/evm-log-trigger)** — The `confidence` parameter determines when the trigger fires based on block finality. +- **[EVM Client contract reads](/cre/reference/sdk/evm-client)** — The `blockNumber` parameter lets you query data from `LATEST` or `FINALIZED` blocks. + +## Confidence levels + +When reading from the blockchain or setting up triggers, you can specify one of 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 + +- **Use `FINALIZED`** when: Processing financial transactions, updating critical state, or when incorrect data could cause significant issues. +- **Use `SAFE`** when: You need reasonable confidence without waiting for full finality. Good for most monitoring and alerting use cases. +- **Use `LATEST`** when: Building real-time dashboards, price displays, or other applications where showing the most current data is more important than guaranteed accuracy. + +## How confidence levels work per chain + +CRE translates confidence levels to the appropriate blockchain mechanism: + +### SAFE and LATEST + +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. + +### FINALIZED + +- **Finality tag**: Uses the chain's native `finalized` block tag +- **Block depth**: Waits for a specified number of blocks to pass + +| Chain | Finality Method | Block Depth | +| ------------------------------- | --------------- | ----------- | +| Arbitrum One / Arbitrum Sepolia | Finality tag | — | +| Avalanche / Avalanche Fuji | Finality tag | — | +| Base / Base Sepolia | Finality tag | — | +| BNB Chain / BNB Testnet | Finality tag | — | +| Ethereum / Ethereum Sepolia | Finality tag | — | +| OP Mainnet / OP Sepolia | Finality tag | — | +| Polygon / Polygon Amoy | Block depth | 500 | diff --git a/src/content/cre/llms-full-go.txt b/src/content/cre/llms-full-go.txt index c5ee51d6a01..af264681342 100644 --- a/src/content/cre/llms-full-go.txt +++ b/src/content/cre/llms-full-go.txt @@ -7112,6 +7112,64 @@ Yes. Once you call `runtime.Rand()` and get a `*rand.Rand` object, you can reuse --- +# Finality and Confidence Levels +Source: https://docs.chain.link/cre/concepts/finality +Last Updated: 2025-12-03 + +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. + +You specify confidence levels in two places: + +- **[EVM Log Triggers](/cre/reference/sdk/triggers/evm-log-trigger)** — The `confidence` parameter determines when the trigger fires based on block finality. +- **[EVM Client contract reads](/cre/reference/sdk/evm-client)** — The `blockNumber` parameter lets you query data from `LATEST` or `FINALIZED` blocks. + +## Confidence levels + +When reading from the blockchain or setting up triggers, you can specify one of 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 + +- **Use `FINALIZED`** when: Processing financial transactions, updating critical state, or when incorrect data could cause significant issues. +- **Use `SAFE`** when: You need reasonable confidence without waiting for full finality. Good for most monitoring and alerting use cases. +- **Use `LATEST`** when: Building real-time dashboards, price displays, or other applications where showing the most current data is more important than guaranteed accuracy. + +## How confidence levels work per chain + +CRE translates confidence levels to the appropriate blockchain mechanism: + +### SAFE and LATEST + +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. + +### FINALIZED + +- **Finality tag**: Uses the chain's native `finalized` block tag +- **Block depth**: Waits for a specified number of blocks to pass + +| Chain | Finality Method | Block Depth | +| ------------------------------- | --------------- | ----------- | +| Arbitrum One / Arbitrum Sepolia | Finality tag | — | +| Avalanche / Avalanche Fuji | Finality tag | — | +| Base / Base Sepolia | Finality tag | — | +| BNB Chain / BNB Testnet | Finality tag | — | +| Ethereum / Ethereum Sepolia | Finality tag | — | +| OP Mainnet / OP Sepolia | Finality tag | — | +| Polygon / Polygon Amoy | Block depth | 500 | + +--- + # CRE Templates Source: https://docs.chain.link/cre/templates Last Updated: 2025-11-21 @@ -9110,7 +9168,7 @@ func onCronTrigger(config *Config, runtime cre.Runtime, trigger *cron.Payload) ( } logger.Info("Successfully fetched offchain value", "result", offchainValue) - + // Get the first EVM configuration from the list. evmConfig := config.Evms[0] @@ -9146,7 +9204,7 @@ func onCronTrigger(config *Config, runtime cre.Runtime, trigger *cron.Payload) ( return &MyResult{ FinalResult: finalResult, }, nil - + } func main() { @@ -9451,7 +9509,7 @@ func onCronTrigger(config *Config, runtime cre.Runtime, trigger *cron.Payload) ( } logger.Info("Successfully read onchain value", "result", onchainValue) - + // Step 3: Calculate the final result finalResultInt := new(big.Int).Add(onchainValue, offchainValue) @@ -9474,7 +9532,7 @@ func onCronTrigger(config *Config, runtime cre.Runtime, trigger *cron.Payload) ( logger.Info("Workflow finished successfully!", "result", finalWorkflowResult) return finalWorkflowResult, nil - + } 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 This is the main input object for the `CallContract` function. It acts as a wrapper for the call message and an optional block number. -| Field | Type | Description | -| ------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Call` | `*evm.CallMsg` | Contains the actual details of the function call you want to make. | -| `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). | +| Field | Type | Description | +| ------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Call` | `*evm.CallMsg` | Contains the actual details of the function call you want to make. | +| `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. | #### `evm.CallMsg` @@ -14122,9 +14180,9 @@ The configuration struct for the EVM log trigger. | `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. | | `Confidence` | `ConfidenceLevel` | The block confirmation level to monitor. Can be: | - -