Verifiable Events
A verifiable event is the unit of observation that CRE Connect delivers to your application. Every event a channel emits, whether it represents a contract log, a watcher state change, a wallet state change, an operation status, or a query status, is signed by the Chainlink Decentralized Oracle Network (DON) using the Off-Chain Reporting (OCR) protocol. Your application can re-verify that signature locally before acting on the data.
This is the property that makes the events verifiable: the SDK does not ask you to trust CRE Connect's delivery infrastructure. CRE Connect is just a delivery mechanism. The cryptographic proof of authenticity is generated by the DON and travels with the event.
Event envelope
Every event you receive from client.Events.Poll(...) or client.Events.SearchEvents(...) shares the same envelope:
Field | Description |
|---|---|
id | Server-assigned UUID. |
channel_id | The channel that produced this event. |
headers.type | One of the event types listed below. |
headers.proofs | The list of cryptographic proofs attached to the event. CRE Connect events always carry exactly one OCR proof. |
payload | The typed payload, decoded according to headers.type. |
created_at | Timestamp CRE Connect received the event from the DON. |
The headers.proofs array is what makes the event verifiable. Each entry is an OCRProof containing:
| Sub-field | Description |
|---|---|
ocr_report | The raw OCR3 report bytes produced by the workflow. The DON signers signed the hash of this report. |
ocr_context | Replay-protection context (epoch / round / config hash). |
signatures | An array of OCR signatures over keccak256(keccak256(report) ‖ context). |
When you call client.Events.Verify(event) (for watcher.event) or client.Events.VerifyOperationStatus(event) (for operation.status), the SDK:
- Checks that the report binds the event to the correct workflow owner and that its embedded payload hash matches
keccak256(payload.verifiable_event). - Recomputes
reportHash = keccak256(keccak256(ocr_report) ‖ ocr_context). - Recovers the signer address from each signature in
signatures. - Checks that each recovered address belongs to the configured set of valid DON signers.
- Checks that the count of unique valid signatures meets or exceeds
MinRequiredSignatures(default 4).
The full algorithm is documented in Event Verification.
Event types
CRE Connect emits five kinds of events. All of them share the verifiable envelope above; they differ only in what payload contains.
headers.type | Source | Typical payload |
|---|---|---|
watcher.event | A watcher observed a matching log on-chain. | The decoded event from the underlying contract (parameters in raw or extension-decoded form), plus the on-chain transaction hash, block number, and confidence level. |
watcher.status | The lifecycle state of a watcher changed. | The new WatcherEventStatus (pending, active, archiving, archived, failed, archive_failed) and an optional human-readable reason. |
wallet.status | The lifecycle state of a Smart Account wallet changed. | The new WalletEventStatus (pending, deploying, deployed, archived, failed) and metadata about the deployment chain. |
operation.status | The on-chain Smart Account emitted an OperationExecuted log for one of your operations. | The wallet operation ID, the new OperationStatus, and, on confirmation statuses, the chain transaction hash and per-transaction execution result. |
query.status | A chain query moved through its lifecycle. | The query ID, query status, target contract, and terminal verifiable result or error. |
The full structural definition of each payload is in Event Types and Payloads.
What "verifiable" really means
The verifiable property gives you three concrete guarantees:
- Authenticity. A passing
Verify(event)proves that an OCR-signed quorum of DON nodes attested to the underlying observation. A malicious or compromised delivery layer cannot forge an event because it does not have the DON's signing keys. - Integrity. Any tampering with
payload,ocr_report,ocr_context, orsignaturescauses verification to fail. The OCR report binds the event hash, and the signatures bind the report. - Replay protection. The OCR context (epoch / round / config hash) is part of the signed message, so signatures are not reusable across rounds or configurations.
It does not give you:
- Non-repudiation against your tenant. Other tenants of CRE Connect cannot verify for whom an event was generated unless they have access to the same Smart Account / wallet metadata. Verification is about authenticity, not authorization.
- Real-time finality. Verifiability is independent of the confidence level at which the underlying observation was made. A
latestevent can be just as cryptographically valid as afinalizedone, but the chain can still reorganize it away. Operation confirmations make this visible through Multi-Event Finality:confirmed_latest,confirmed_safe, thenconfirmed.
Verification configuration
The SDK configures the verifier as follows by default:
| Setting | Default | Configurable via |
|---|---|---|
MinRequiredSignatures | 4 | crec.WithDONConfig(tenantID, min, signers) (recommended; sets the whole unit at once) or crec.WithEventVerification(min, signers) (deprecated) |
ValidSigners | DefaultValidSigners: the production DON signer set (10 keys) | crec.WithDONConfig(...) or crec.WithEventVerification(...) (deprecated) |
| Workflow owner | No default: you must set it. Verification returns ErrOrgIDOrWorkflowOwnerReq if neither OrgID nor WorkflowOwner is configured. | crec.WithOrgID(...) derives the workflow-owner address from your Org ID; crec.WithWorkflowOwner(...) sets it directly. Per-call: VerifyWithOrgID / VerifyWithWorkflowOwner. |
| CRE tenant ID | events.CreMainlineTenantID ("1"): used only when deriving a workflow owner from an Org ID | crec.WithDONConfig(...) (recommended) or crec.WithCRETenantID(...) (deprecated) |
| Verification enabled | true | crec.WithoutEventVerification() skips the default signer-set backfill; explicitly configured signers still apply. |
The DON configuration values (tenant ID, threshold, signer set) are provided at onboarding and are not SDK constants. See SDK Configuration Options for the full list.
Related
- Event Verification: the algorithm
Events.Verifyruns. - Verify Event Signatures: the runnable SDK recipe.
- Event Types and Payloads: the five payload shapes you'll receive.
- Multi-Event Finality: how operation confirmations gain stronger finality.
- Confidence Levels: the orthogonal property: chain finality vs cryptographic authenticity.