finality clarifications + custom block depth support for chain reads

Author: khadni

reports/llms-report.json

@@ -1,22 +1,22 @@
 {
-  "startedAt": "2025-12-03T20:30:47.619Z",
+  "startedAt": "2025-12-04T17:22:07.744Z",
   "siteBase": "https://docs.chain.link",
   "sections": [
     {
       "section": "cre-go",
       "pagesProcessed": 84,
       "outputPath": "src/content/cre/llms-full-go.txt",
-      "bytes": 655924,
-      "prevBytes": 655971,
-      "deltaBytes": -47
+      "bytes": 662040,
+      "prevBytes": 655924,
+      "deltaBytes": 6116
     },
     {
       "section": "cre-ts",
       "pagesProcessed": 79,
       "outputPath": "src/content/cre/llms-full-ts.txt",
-      "bytes": 611343,
-      "prevBytes": 611390,
-      "deltaBytes": -47
+      "bytes": 618373,
+      "prevBytes": 611343,
+      "deltaBytes": 7030
     },
     {
       "section": "vrf",
@@ -123,5 +123,5 @@
       "deltaBytes": 0
     }
   ],
-  "finishedAt": "2025-12-03T20:30:51.570Z"
+  "finishedAt": "2025-12-04T17:22:11.997Z"
 }

src/config/sidebar.ts

@@ -419,8 +419,9 @@ export const SIDEBAR: Partial<Record<Sections, SectionEntry[]>> = {
           url: "cre/concepts/typescript-wasm-runtime",
         },
         {
-          title: "Finality and Confidence Levels",
+          title: "Finality & Confidence Levels",
           url: "cre/concepts/finality",
+          highlightAsCurrent: ["cre/concepts/finality-go", "cre/concepts/finality-ts"],
         },
       ],
     },

src/content/cre/concepts/finality-go.mdx

@@ -0,0 +1,94 @@
+---
+section: cre
+title: "Finality and Confidence Levels"
+date: Last Modified
+sdkLang: "go"
+pageId: "concepts-finality"
+metadata:
+  description: "Understand how CRE handles blockchain finality across different chains, including confidence levels, finality tags, and block depth configurations."
+  datePublished: "2025-12-04"
+  lastModified: "2025-12-04"
+---
+
+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-go)** — The `confidence` parameter determines when the trigger fires based on block finality.
+- **[EVM Client contract reads](/cre/reference/sdk/evm-client-go)** — The `blockNumber` parameter lets you query data from `LATEST` or `FINALIZED` blocks, or any specific block number.
+
+## Confidence levels
+
+CRE provides three **abstraction levels** that work consistently across all chains. When you specify `FINALIZED` in your workflow, CRE automatically maps this to a chain-specific implementation—whether that's a native finality tag or a block depth threshold.
+
+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.     |
+
+<Aside type="note" title="Default behavior">
+  If you don't specify a confidence level, CRE defaults to `SAFE` for triggers and `LATEST` for contract reads.
+</Aside>
+
+### 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 CRE confidence levels map to chains
+
+Here's how CRE determines which blocks to use for each confidence level:
+
+#### SAFE and LATEST
+
+When you specify `SAFE` or `LATEST` in your workflows, CRE uses the chain's native `safe` and `latest` block tags respectively for all supported 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         |
+
+## Custom block depths for chain reads
+
+For chain reads, you're not limited to the three predefined confidence levels. The EVM Client also accepts **any explicit block number**, enabling 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
+
+This flexibility is available for all EVM read methods ([`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.).
+
+### When to use custom block depths
+
+Use explicit block numbers when:
+
+- **Regulatory compliance**: Your smart contract interactions require provable, fixed confirmation thresholds that must be documented for auditors
+- **Changing chain parameters**: The chain's finality definition may change over time, but your security model must remain constant
+- **Historical verification**: You need to verify state at a specific moment (e.g., for dispute resolution or forensic analysis)
+
+### 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.
+
+<Aside type="note" title="Limitation: Chain reads only">
+  Custom block numbers are **only available for EVM chain reads**. EVM Log Triggers must use the three confidence levels
+  (`LATEST`, `SAFE`, `FINALIZED`).
+</Aside>

src/content/cre/concepts/finality.mdx src/content/cre/concepts/finality-ts.mdxsrc/content/cre/concepts/finality.mdx renamed to src/content/cre/concepts/finality-ts.mdx

@@ -2,10 +2,12 @@
 section: cre
 title: "Finality and Confidence Levels"
 date: Last Modified
+sdkLang: "ts"
+pageId: "concepts-finality"
 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"
+  datePublished: "2025-12-04"
+  lastModified: "2025-12-04"
 ---
 
 import { Aside, CopyText } from "@components"
@@ -16,11 +18,13 @@ Different blockchains achieve finality in different ways and at different speeds
 
 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.
+- **[EVM Log Triggers](/cre/reference/sdk/triggers/evm-log-trigger-ts)** — The `confidence` parameter determines when the trigger fires based on block finality.
+- **[EVM Client contract reads](/cre/reference/sdk/evm-client-ts)** — The `blockNumber` parameter lets you query data from `LATEST` or `FINALIZED` blocks, or any specific block number.
 
 ## Confidence levels
 
+CRE provides three **abstraction levels** that work consistently across all chains. When you specify `FINALIZED` in your workflow, CRE automatically maps this to a chain-specific implementation—whether that's a native finality tag or a block depth threshold.
+
 When reading from the blockchain or setting up triggers, you can specify one of three confidence levels:
 
 | Confidence Level | Description                                                                         | Use Case                                                                         |
@@ -39,15 +43,15 @@ When reading from the blockchain or setting up triggers, you can specify one of
 - **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
+### How CRE confidence levels map to chains
 
 Here's how CRE determines which blocks to use for each confidence level:
 
-### SAFE and LATEST
+#### SAFE and LATEST
 
 When you specify `SAFE` or `LATEST` in your workflows, CRE uses the chain's native `safe` and `latest` block tags respectively for all supported chains.
 
-### FINALIZED
+#### FINALIZED
 
 - **Finality tag**: Uses the chain's native `finalized` block tag
 - **Block depth**: Waits for a specified number of blocks to pass
@@ -61,3 +65,30 @@ When you specify `SAFE` or `LATEST` in your workflows, CRE uses the chain's nati
 | Ethereum / Ethereum Sepolia     | Finality tag    | —           |
 | OP Mainnet / OP Sepolia         | Finality tag    | —           |
 | Polygon / Polygon Amoy          | Block depth     | 500         |
+
+## Custom block depths for chain reads
+
+For chain reads, you're not limited to the three predefined confidence levels. The EVM Client also accepts **any explicit block number**, enabling 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
+
+This flexibility is available for all EVM read methods ([`CallContract`](/cre/reference/sdk/evm-client-ts#callcontract), [`BalanceAt`](/cre/reference/sdk/evm-client-ts#balanceat), [`FilterLogs`](/cre/reference/sdk/evm-client-ts#filterlogs), etc.).
+
+### When to use custom block depths
+
+Use explicit block numbers when:
+
+- **Regulatory compliance**: Your smart contract interactions require provable, fixed confirmation thresholds that must be documented for auditors
+- **Changing chain parameters**: The chain's finality definition may change over time, 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](/cre/guides/workflow/using-evm-client/onchain-read-ts#custom-block-depths) for the conversion pattern and examples.
+
+<Aside type="note" title="Limitation: Chain reads only">
+  Custom block numbers are **only available for EVM chain reads**. EVM Log Triggers must use the three confidence levels
+  (`LATEST`, `SAFE`, `FINALIZED`).
+</Aside>

src/content/cre/guides/workflow/using-evm-client/onchain-read-go.mdx

@@ -153,9 +153,9 @@ When calling contract read methods, you must specify a block number. There are t
 
 ### Using magic numbers
 
-- **Finalized block**: Use `big.NewInt(-3)` to read from the latest finalized block
+- **Finalized block**: Use `big.NewInt(-3)` to read from the latest finalized block (recommended for production)
 - **Latest block**: Use `big.NewInt(-2)` to read from the latest block
-- **Specific block**: Use `big.NewInt(blockNumber)` to read from a specific block
+- **Specific block**: Use `big.NewInt(blockNumber)` to read from a specific historical block
 
 ### Using rpc constants (alternative)
 
@@ -174,7 +174,57 @@ reqBlockNumber := big.NewInt(rpc.LatestBlockNumber.Int64())
 reqBlockNumber := big.NewInt(rpc.FinalizedBlockNumber.Int64())
 ```
 
-Both approaches are equivalent - use whichever you find more readable in your code.
+### Custom block depths
+
+For use cases requiring fixed confirmation thresholds (e.g., regulatory compliance), you can calculate a custom block depth:
+
+```go
+import (
+    pb "github.com/smartcontractkit/chainlink-protos/cre/go/values/pb"
+)
+
+// Helper to convert protobuf BigInt to standard library big.Int
+func pbBigIntToBigInt(pb *pb.BigInt) *big.Int {
+    if pb == nil {
+        return nil
+    }
+    result := new(big.Int).SetBytes(pb.AbsVal)
+    if pb.Sign < 0 {
+        result.Neg(result)
+    }
+    return result
+}
+
+// Read from 500 blocks ago for custom finality
+latestHeaderPromise := evmClient.HeaderByNumber(runtime, &evm.HeaderByNumberRequest{})
+latestHeader, err := latestHeaderPromise.Await()
+if err != nil {
+    return nil, fmt.Errorf("failed to get latest block: %w", err)
+}
+
+// Convert protobuf BigInt to standard library big.Int
+latestBlockNum := pbBigIntToBigInt(latestHeader.Header.BlockNumber)
+customDepth := big.NewInt(500)
+customBlock := new(big.Int).Sub(latestBlockNum, customDepth)
+
+// Use the custom block number with the contract binding
+valuePromise := storageContract.Get(runtime, customBlock)
+value, err := valuePromise.Await()
+if err != nil {
+    return nil, fmt.Errorf("failed to read from custom block: %w", err)
+}
+```
+
+**Understanding the conversion:**
+
+The `pbBigIntToBigInt` helper converts the SDK's protobuf `*pb.BigInt` type (which stores the value as `AbsVal []byte` and `Sign int64`) to Go's standard library `*big.Int`. This allows you to perform arithmetic operations like subtracting 500 blocks.
+
+<Aside type="note" title="SDK enhancement planned">
+  The SDK team is working on a built-in helper to simplify this conversion. Until then, use the `pbBigIntToBigInt`
+  helper shown above.
+</Aside>
+
+See [Finality and Confidence Levels](/cre/concepts/finality-go) for more details on when to use custom block depths.
 
 ## Complete example
 

src/content/cre/guides/workflow/using-evm-client/onchain-read-ts.mdx

@@ -168,7 +168,7 @@ When calling `callContract()`, you can specify which block to read from:
 
 - **`LAST_FINALIZED_BLOCK_NUMBER`**: Read from the last finalized block (recommended for production)
 - **`LATEST_BLOCK_NUMBER`**: Read from the latest block
-- **Specific block**: Use an object with `{ absVal: "base64EncodedNumber", sign: "1" }` format
+- **Custom block number**: Use a `BigIntJson` object for custom finality depths or historical queries
 
 ```typescript
 import { LAST_FINALIZED_BLOCK_NUMBER, LATEST_BLOCK_NUMBER } from "@chainlink/cre-sdk"
@@ -186,6 +186,68 @@ const contractCall = evmClient.callContract(runtime, {
 }).result()
 ```
 
+#### Custom block depths
+
+For use cases requiring fixed confirmation thresholds (e.g., regulatory compliance) or historical state verification, you can specify an exact block number.
+
+**Example 1 - Read from a specific historical block**:
+
+```typescript
+const historicalBlock = 9767655n
+const contractCall = evmClient.callContract(runtime, {
+  call: encodeCallMsg({...}),
+  blockNumber: {
+    absVal: Buffer.from(historicalBlock.toString(16).padStart(2, '0'), 'hex').toString('base64'),
+  },
+}).result()
+```
+
+**Example 2 - Read from 500 blocks ago for latest block**:
+
+```typescript
+// Helper to convert protobuf BigInt to native bigint
+const protoBigIntToBigInt = (pb: { absVal: Uint8Array; sign: bigint }): bigint => {
+  let result = 0n
+  for (const byte of pb.absVal) {
+    result = (result << 8n) + BigInt(byte)
+  }
+  return pb.sign < 0n ? -result : result
+}
+
+// Example: Read from 500 blocks ago for custom finality
+const latestHeader = evmClient.headerByNumber(runtime, {}).result()
+if (!latestHeader.header?.blockNumber) {
+  throw new Error("Failed to get latest block number")
+}
+
+const latestBlockNum = protoBigIntToBigInt(latestHeader.header.blockNumber)
+const customBlock = latestBlockNum - 500n
+
+const contractCall = evmClient.callContract(runtime, {
+  call: encodeCallMsg({...}),
+  blockNumber: {
+    absVal: Buffer.from(customBlock.toString(16).padStart(2, '0'), 'hex').toString('base64'),
+  },
+}).result()
+```
+
+**Understanding the conversions:**
+
+1. **Protobuf `BigInt` to native `bigint`:** The `protoBigIntToBigInt` helper converts the SDK's protobuf `BigInt` type (which stores the value as `absVal: Uint8Array`) to JavaScript's native `bigint`. This allows you to perform arithmetic like subtracting 500 blocks.
+
+1. **Native `bigint` to `BigIntJson`:** To pass a native `bigint` back to the SDK:
+   - `blockNum.toString(16)` converts to hexadecimal
+   - `.padStart(2, '0')` ensures even-length hex string (required by `Buffer.from`)
+   - `Buffer.from(..., 'hex')` creates a byte array from the hex
+   - `.toString('base64')` converts to base64 format required by `BigIntJson.absVal`
+
+<Aside type="note" title="SDK enhancements planned">
+  The SDK team is working on built-in helpers for both conversions (protobuf `BigInt` ↔ native `bigint` and `bigint` →
+  `BigIntJson`). Until then, use the patterns shown above.
+</Aside>
+
+See [Finality and Confidence Levels](/cre/concepts/finality-ts) for more details on when to use custom block depths.
+
 ### Encoding call messages with `encodeCallMsg()`
 
 The `encodeCallMsg()` helper converts your hex-formatted call data into the base64 format required by the EVM capability: