Confidence Levels
A confidence level specifies how deep into a chain's consensus an event must be before CRE Connect emits it as a verifiable event. The trade-off is the same on every chain: lower confidence means lower latency but a higher chance of being reorganized away; higher confidence means longer waits but stronger guarantees.
The three levels
Level | Semantics | When to use |
|---|---|---|
latest | The event is included in the most recent block from the chain's perspective. Reorganizations can still drop it. | Read-only dashboards, tail-following loggers, low-stakes notifications. |
safe | The event is included in a "safe" block under the chain's pre-finality definition (post-Merge safe for Ethereum, finalized-by-fast-track on rollups). Reorgs are very unlikely. | Operational alerting, non-financial side effects. |
finalized | The event is in a block the chain treats as economically final. It cannot be reorganized away under honest-majority assumptions. | Anything that triggers irreversible business action: fund flows, regulatory reporting, downstream API calls. |
The exact mapping of safe and finalized depends on the chain. CRE Connect uses the chain's own definition (e.g. Ethereum's safe and finalized block tags, the equivalent rollup-specific tags). Consult the chain's documentation for precise semantics and the latency each level implies on that chain.
Where confidence levels live
Confidence levels appear in several places in CRE Connect, each for a different purpose:
| Location | Field | Purpose |
|---|---|---|
Network metadata (returned by client.ListNetworks(...)) | Network.DefaultConfidenceLevel | The platform-managed default for a network. New watchers on this network start with this level. |
| Watcher resource | Watcher.ConfidenceLevel | The level the watcher is currently using, returned by Get and List. |
| Wallet resource | Wallet.ConfidenceLevel (optional) | The level applied to wallet-related on-chain observations. |
Service-backed watchers (those created with CreateWithService) carry a confidence level chosen by the extension. Read it back from Watcher.ConfidenceLevel after creation.
Multi-event finality for operations
Confidence levels also shape Operation confirmation. An Operation can produce multiple operation.status events as its block matures: confirmed_latest, then confirmed_safe, then confirmed.
This progression lets your application react quickly to low-risk updates while still waiting for stronger finality before irreversible actions. See Multi-Event Finality for the operation-specific model.
What clients can and cannot configure today
- Clients receive the chosen confidence level back in every Watcher and Network response. Use
client.ListNetworks(...)to enumerate the per-network defaults at runtime. - The SDK does not currently send a
confidence_levelfield when creating a watcher.CreateWithServiceandCreateWithABIaccept the chain selector, address, ABI/service, and event list. Confidence is set server-side based on the network default and the service's own default (when applicable). - Event polling and search APIs do not accept a confidence-level filter today. Confidence is a property of the event's source, not a query parameter on the read path.
If your integration requires a non-default confidence level for a specific watcher, contact the CRE Connect team.
How confidence interacts with verification
Confidence and verification are independent properties:
| Property | Provides | Sensitive to |
|---|---|---|
| Verification | Cryptographic authenticity ("the DON observed this") | Tampering |
| Confidence | Chain-level finality ("the chain has agreed on this") | Reorganizations |
A latest-confidence event can pass verification and still be invalidated by a chain reorganization. Similarly, a finalized-confidence event that fails verification is suspect regardless of chain finality. Critical workflows should require both: verification passes and confidence ≥ finalized.
Related
- Watchers: the resource that emits events at a chosen confidence level.
- Multi-Event Finality: how operations report progressive confirmations.
- Verifiable Events: the cryptographic property that is independent of confidence.
- Supported Networks: the per-network defaults exposed via
ListNetworks.