offchain tooling api by tt-cll · Pull Request #1031 · smartcontractkit/chainlink-ccv

tt-cll · 2026-04-17T12:27:36Z

No description provided.

winder · 2026-04-17T12:39:51Z

I'm a little hesitant to bury modules in build/devenv. Should we put this in a new top-level package called platform and treat that directory as a sort of mono-repo?

This is the EVM impl of offchain tooling and it is at the top level :-). Don't know if there's a better home for that

Where should the EVM impl live vs the interface declarations? We can rename chainlink-ccv/deployment to chainlink-ccv/platform if that's clearer

I think this is fine for now, maybe we can have an evm/deployment which has the interface implementations of the offchain deployment interfaces?

I'm imagining that in the future evm could also hold the evm-specific implementations of the chainaccess interfaces as well.

The chainlink-ccv/platform module can then have the subdirectories devenv for the devenv package and deployment for the offchain deployment API?

Copilot

Pull request overview

This PR introduces a CCV “offchain tooling API” layer: chain-family adapters (starting with EVM) plus deployment operations/changesets for generating offchain service configs and managing Job Distributor (JD) job proposals, and updates the devenv tooling to use these new APIs.

Changes:

Add a new deployment module with topology/config models, env-metadata persistence helpers, JD-facing operations (propose/revoke/sync), and changesets (apply verifier/executor configs; generate aggregator/indexer/token-verifier configs).
Add an evm module that registers EVM adapter implementations for the new deployment registries.
Update build/devenv to consume the CCV deployment package (with a TOML-based shim to interop with legacy CCIP topology types where needed).

Reviewed changes

Copilot reviewed 42 out of 44 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
evm/verifier_config.go	EVM adapter resolving verifier-related contract addresses from datastore.
evm/token_verifier_config.go	EVM adapter resolving token-verifier-related addresses from datastore.
evm/register.go	EVM init self-registration (chain type → family, address normalization, adapter registrations).
evm/indexer_config.go	EVM adapter resolving verifier resolver addresses for indexer config generation.
evm/go.mod	New nested Go module for EVM-specific deployment adapters.
evm/executor_config.go	EVM adapter building executor chain configuration from datastore.
evm/aggregator_config.go	EVM adapter scanning deployed committee state + resolving verifier address for aggregator config generation.
deployment/topology.go	New topology model + TOML load/write + validation helpers.
deployment/token_verifier.go	Token verifier generated config schema (JSON).
deployment/shared/types.go	Shared types for jobs/NOPs/scopes + job metadata helpers.
deployment/shared/nodes.go	JD node lookup utilities and guarded node fetching.
deployment/shared/jd_client.go	JD client interface abstraction used by operations.
deployment/shared/chain_validation.go	Helpers to validate NOP chain support and format user-facing errors.
deployment/shared/chain_type_registry.go	Registry for JD chain-type → chain-selectors family + address normalizers.
deployment/sequences/manage_job_proposals.go	Sequence to propose changed jobs and optionally revoke/cleanup orphaned jobs.
deployment/operations/sync_job_proposals/sync_job_proposals.go	Operation to sync proposal statuses/specs from JD and detect drift/orphans.
deployment/operations/revoke_jobs/revoke_jobs.go	Operation to revoke jobs via JD with node-ownership validation.
deployment/operations/propose_jobs/propose_jobs.go	Operation to propose jobs via JD and return proposal metadata.
deployment/operations/fetch_signing_keys/fetch_signing_keys.go	Operation to batch fetch OCR signing addresses from JD chain configs.
deployment/operations/fetch_node_chain_support/fetch_node_chain_support.go	Operation to fetch supported chain selectors per NOP from JD chain configs.
deployment/indexer.go	Indexer generated config schema (JSON).
deployment/go.mod	New nested Go module for deployment tooling and dependencies.
deployment/env_metadata_util.go	Persist/load CCV offchain configs + NOP jobs into datastore env metadata.
deployment/changesets/sync_job_proposals.go	Changeset wrapper around SyncJobProposals operation.
deployment/changesets/generate_token_verifier_config.go	Changeset to generate + store token verifier offchain config from onchain state.
deployment/changesets/generate_indexer_config.go	Changeset to generate + store indexer config by collecting resolver addresses.
deployment/changesets/generate_aggregator_config.go	Changeset to generate + store aggregator committee config from onchain state.
deployment/changesets/apply_verifier_config.go	Changeset to build verifier job specs, propose via JD, and manage revocations/cleanup.
deployment/changesets/apply_executor_config.go	Changeset to build executor job specs, propose via JD, and manage revocations/cleanup.
deployment/aggregator.go	Aggregator generated config schema (JSON).
deployment/adapters/verifier_config.go	Verifier adapter interface + registry keyed by chain family.
deployment/adapters/token_verifier_config.go	Token-verifier adapter interface + registry keyed by chain family.
deployment/adapters/indexer_config.go	Indexer adapter interface + registry + missing-address error type.
deployment/adapters/executor_config.go	Executor adapter interface + registry + helper to collect deployed chains.
deployment/adapters/aggregator_config.go	Aggregator adapter interface + registry for committee discovery and resolver lookup.
build/devenv/topology_compat.go	TOML encode/decode shim to convert CCV topology → legacy CCIP topology types.
build/devenv/offchainloader/loader.go	Switch offchain config loading to CCV deployment metadata types.
build/devenv/jobs/jd.go	Switch devenv job proposal syncing/verification to CCV changesets + shared types.
build/devenv/implcommon.go	Update devenv chain deploy/configure helpers to accept CCV topology (convert when calling CCIP code).
build/devenv/go.mod	Add local replaces + requires for new `deployment` and `evm` modules.
build/devenv/expand_ha_test.go	Update tests to use CCV topology types instead of legacy CCIP offchain types.
build/devenv/environment.go	Wire devenv environment generation to CCV changesets/adapters and import EVM adapters for registration.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-17T20:38:02Z

+	if err := c.NOPTopology.Validate(); err != nil {
+		return fmt.Errorf("nop_topology validation failed: %w", err)
+	}


EnvironmentTopology.Validate dereferences c.NOPTopology without checking for nil. If the topology file omits nop_topology (or it fails to unmarshal), this will panic instead of returning a validation error. Add an explicit nil check for c.NOPTopology (and similarly handle a nil receiver in (*NOPTopology).Validate) and return a descriptive error like nop_topology is required.

makramkd

Pros: chain-agnostic interfaces, following existing patterns. Cons: config struct duplication, EnvironmentTopology seems committee-verifier specific, I feel like it either needs a better home or there needs to be some synergy b/w lane definitions, chain support, and committee verifier configurations, as all have been referred to as "topology" at some point in time and confusion is nigh upon us.

makramkd · 2026-04-20T10:22:03Z

+type AggregatorConfigRegistry struct {
+	mu       sync.Mutex
+	adapters map[string]AggregatorConfigAdapter
+}


A developer ergonomics question: have we thought about potentially combining the registries into one, that ends up registering a struct of all these different interface types, in order to have a single entrypoint?

type Adapters struct { AggregatorConfigAdapter AggregatorConfigAdapter ExecutorConfigAdapter ExecutorConfigAdapter // the rest of them ... } type AdapterRegistry struct { mu sync.Mutex adapters map[string]Adapters } func (r *AdapterRegistry) Register(family string, adapters Adapters) { // register func same as below. }

Yeah I remember us talking about this. We can switch these to a single register to start the pattern. This was mostly a lift and shift from what already existed

makramkd · 2026-04-20T10:23:11Z

+	IndexerAddress []string                      `toml:"indexer_address"`
+	PyroscopeURL   string                        `toml:"pyroscope_url"`
+	Monitoring     MonitoringConfig              `toml:"monitoring"`
+	NOPTopology    *NOPTopology                  `toml:"nop_topology"`


This being a pointer suggests it could be nil (and we'd have to do nil checks in a lot of places). Is this the case or is it actually required?

makramkd · 2026-04-20T10:24:10Z

+// NOPTopology defines the node operator structure and committee membership.
+type NOPTopology struct {
+	NOPs       []NOPConfig                `toml:"nops"`
+	Committees map[string]CommitteeConfig `toml:"committees"`


This NOPTopology type seems weird to me because its committee-verifier specific is it not? Or is the entire EnvironmentTopology structure committee-verifier specific?

makramkd · 2026-04-20T10:25:12Z

+	IndexerQueryLimit uint64                             `toml:"indexer_query_limit"`
+	BackoffDuration   time.Duration                      `toml:"backoff_duration"`
+	LookbackWindow    time.Duration                      `toml:"lookback_window"`
+	ReaderCacheExpiry time.Duration                      `toml:"reader_cache_expiry"`
+	MaxRetryDuration  time.Duration                      `toml:"max_retry_duration"`
+	WorkerCount       int                                `toml:"worker_count"`
+	NtpServer         string                             `toml:"ntp_server"`


These are the previously duplicated executor configs? Or were those somewhere else?

makramkd · 2026-04-20T10:27:02Z

+type BeholderInput struct {
+	InsecureConnection       bool
+	CACertFile               string
+	OtelExporterGRPCEndpoint string
+	OtelExporterHTTPEndpoint string
+	LogStreamingEnabled      bool
+	MetricReaderInterval     int64
+	TraceSampleRatio         float64
+	TraceBatchTimeout        int64
+}


This seems to be duplicated in multiple places, can we import it from somewhere where its canonically defined?

makramkd · 2026-04-20T10:27:30Z

+type SourceSelector = string
+
+type DestinationSelector = string
+
+type Signer struct {
+	Address string `json:"address"`
+}
+
+type QuorumConfig struct {
+	SourceVerifierAddress string   `json:"sourceVerifierAddress"`
+	Signers               []Signer `json:"signers"`
+	Threshold             uint8    `json:"threshold"`
+}
+
+type Committee struct {
+	QuorumConfigs        map[SourceSelector]*QuorumConfig      `json:"quorumConfigs"`
+	DestinationVerifiers map[DestinationSelector]string `json:"destinationVerifiers"`
+}


Duplicated configs?

makramkd · 2026-04-20T10:27:58Z

+type IndexerVerifierConfig struct {
+	Name            string   `json:"name"`
+	IssuerAddresses []string `json:"issuerAddresses"`
+}
+
+type IndexerGeneratedConfig struct {
+	Verifiers []IndexerVerifierConfig `json:"verifiers"`
+}


Ditto here, duplicated? Whats the plan in a follow up?

We need to clean this up in general.

makramkd · 2026-04-20T10:28:09Z

+type TokenVerifierGeneratedConfig struct {
+	PyroscopeURL       string                        `json:"pyroscope_url"`
+	OnRampAddresses    map[string]string             `json:"on_ramp_addresses"`
+	RMNRemoteAddresses map[string]string             `json:"rmn_remote_addresses"`
+	TokenVerifiers     []TokenVerifierEntry          `json:"token_verifiers"`
+	Monitoring         TokenVerifierMonitoringConfig `json:"monitoring"`
+}


Ditto here, duplicated

github-actions · 2026-04-20T12:57:13Z

Code coverage report:

Package	`main`	`tt/offchain`	diff
github.com/smartcontractkit/chainlink-ccv/aggregator	48.46%	48.46%	+0.00%
github.com/smartcontractkit/chainlink-ccv/bootstrap	42.60%	42.60%	+0.00%
github.com/smartcontractkit/chainlink-ccv/cli	65.13%	65.13%	+0.00%
github.com/smartcontractkit/chainlink-ccv/cmd	0.00%	0.00%	+0.00%
github.com/smartcontractkit/chainlink-ccv/common	51.13%	50.74%	-0.39%
github.com/smartcontractkit/chainlink-ccv/executor	45.74%	45.74%	+0.00%
github.com/smartcontractkit/chainlink-ccv/indexer	37.52%	37.52%	+0.00%
github.com/smartcontractkit/chainlink-ccv/integration	47.68%	47.68%	+0.00%
github.com/smartcontractkit/chainlink-ccv/pkg	100.00%	100.00%	+0.00%
github.com/smartcontractkit/chainlink-ccv/pricer	0.00%	0.00%	+0.00%
github.com/smartcontractkit/chainlink-ccv/protocol	65.19%	65.19%	+0.00%
github.com/smartcontractkit/chainlink-ccv/verifier	32.55%	32.56%	+0.01%

offchain tooling api

28e7821

winder reviewed Apr 17, 2026

View reviewed changes

tt-cll added 3 commits April 17, 2026 06:09

evm impl

298b021

deps

0d256ff

lint

d4820eb

tt-cll marked this pull request as ready for review April 17, 2026 20:33

tt-cll requested review from a team and skudasov as code owners April 17, 2026 20:33

Copilot AI review requested due to automatic review settings April 17, 2026 20:33

Copilot started reviewing on behalf of tt-cll April 17, 2026 20:34 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

carte7000 previously approved these changes Apr 17, 2026

View reviewed changes

makramkd reviewed Apr 20, 2026

View reviewed changes

cr comments

085723b

tt-cll dismissed carte7000’s stale review via 085723b April 20, 2026 12:32

add missing file

2434677

makramkd approved these changes Apr 21, 2026

View reviewed changes

carte7000 approved these changes Apr 21, 2026

View reviewed changes

tt-cll enabled auto-merge April 21, 2026 13:28

harry-secure disabled auto-merge April 22, 2026 02:00

harry-secure enabled auto-merge April 22, 2026 02:01

harry-secure disabled auto-merge April 22, 2026 02:06

harry-secure merged commit 8e0ee62 into main Apr 22, 2026
33 of 36 checks passed

harry-secure deleted the tt/offchain branch April 22, 2026 02:08

Conversation

tt-cll commented Apr 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

makramkd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Apr 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants