relayer: config simplification by dhfang · Pull Request #1328 · cosmos/ibc

dhfang · 2026-08-10T06:15:28Z

Summary

Reworks the relayer config schema to be connection-first: one entry per IBC connection with two client ends (clientA/clientB).
Previously remote attestors were defined in the relayer's attestorSet config and local attestors were defined in the top level attestor configuration block. Now remote and local attestor definition is consolidated in a top level attestors config.
Removes the relayer's attestorSet config(threshold + attestor list + finality offset, per client end) and instead associates the attestors configured in the top level attestors block with their corresponding light client by associating their self-reported addresses with the addresses queried from the on-chain attestation light client. A misconfigured or stale quorum now fails at startup instead of silently drifting from what the chain actually enforces.
Adds live client counterparty validation to ibc config validate --live: confirms each connection's on-chain registered counterparty actually matches what's configured, in both directions.
The relayer used to rely on the finality offset configured in the attestorSet to determine when a packet commitment is finalized. This PR removes that as a concept and instead just waits till all the attestors report they can attest to the height of a commitment. This happens in the Relayer's CheckSendFinality/CheckTimeoutFinality/CheckWriteAckFinality pipeline stages where they now determine finality by calling LatestProvableHeight() on the attestor light client implementation of the ProofGenerator abstraction.

The refactors required to support the new configuration format are quite large - I added some comments in the diff to help reviewers parse the changes, but let me know if anyone prefers me to split into smaller PRs.

Closes FOU-1219, FOU-1221

…list Replaces relayer.clients[]+routesToRelay[] (joined by alias, with duplicated counterparty fields) with relayer.connections[], each holding two client ends (clientA/clientB) whose counterparty is simply the other end. Replaces attestor.attestations[] + embedded per-client AttestorEntry objects with one top-level attestors[] list (local and remote together), referenced by alias from attestorSet.attestors[]. Updates every downstream consumer of the old shape: pipeline opts, dispatch routing, proofgen attestor resolution, relayer packet handling, bootstrap's dual-mode gate, and the attestor service/local attestor.

Rewrites testdata/sample.yml and the config_test.go/relayer_test.go table-driven cases to match relayer.connections[]/top-level attestors[]. Updates every other test file constructing the old ClientConfig/ RouteConfig/AttestationConfig literals inline.

ibc config validate --live now queries each connection's two chains' routers (ICS02Client.getCounterparty) and confirms the on-chain registered counterparty actually matches clientA/clientB, in both directions -- catching a config that names two clients as counterparties when the chains themselves disagree. Adds chains.Client.GetCounterparty, regenerates its mock.

e2e/internal/harness/ibclink hand-mirrors link's config YAML shape to generate configs for containerized relayer/attestor processes in e2e tests. Since it's a separate Go module, the internal/config refactor didn't surface this as a compile error -- it would have silently kept writing the old clients[]+routesToRelay[]+attestor.attestations[] shape. Updates the file-shape types and buildRelayerFileConfig to emit relayer.connections[] and a unified top-level attestors[] list. Also fixes a real gap the old code never needed: attestors referenced by an explicit RelayerAttestorSet with type: remote were never declared in the unified list (only locals were), which the real schema's cross-validation now requires.

… state

…p test

…solidate live validation and attestor resolution

greptile-apps · 2026-08-10T06:17:37Z

Greptile Summary

The PR replaces static per-client attestor and finality configuration with startup-time on-chain quorum resolution, connection-first bidirectional configuration, and proof-generator-backed finality checks.

Resolves local and remote attestor identities against each light client’s on-chain attestation set.
Models relaying as reciprocal connections and adds live counterparty validation in both directions.
Uses LatestProvableHeight consistently across send, timeout, acknowledgement, and batch processing.
Adds the attestor Info RPC, updated configuration documentation, and extensive unit and integration coverage.

Confidence Score: 5/5

The PR appears safe to merge after the acknowledged branch rebase, with no concrete blocking or independently actionable non-blocking defects identified in the reviewed changes.

The connection model rejects ambiguous client ends, live validation checks both counterparties, startup quorum matching fails safely when configured attestors cannot satisfy on-chain requirements, and finality processors consistently use route-specific provable heights.

Important Files Changed

Filename	Overview
link/internal/service/attestor/resolve.go	Resolves unified local and remote attestor configuration, treating local setup errors strictly and unavailable remote candidates as best-effort omissions.
link/internal/relay/proofgen/attestation/resolve.go	Matches resolved attestors by chain and signer address against each client’s on-chain quorum before constructing its proof generator.
link/internal/livevalidate/connections.go	Validates both configured ends against their on-chain registered counterparty client identifiers.
link/internal/config/relayer.go	Introduces bidirectional connection-first configuration with uniqueness validation for aliases and chain/client endpoints.
link/internal/relay/pipeline/pipeline.go	Wires route-specific proof generators into send, timeout, and acknowledgement finality processors.
link/internal/relay/processors/check_send_finality.go	Gates packet sends on whether their transaction height is within the route’s latest provable height.
link/internal/relay/processors/check_timeout_finality.go	Gates timeout processing using the timestamp associated with the destination route’s latest provable height.
link/internal/relay/processors/check_write_ack_finality.go	Gates acknowledgement relaying on whether the acknowledgement transaction is currently provable.
link/internal/bootstrap/bootstrap.go	Integrates attestor resolution, quorum-backed proof-generator construction, and connection-first relayer startup.
link/internal/service/relayer/service.go	Derives packet destination routing from the configured counterparty end of each connection.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  C[Connection config] --> V[Live counterparty validation]
  A[Configured attestors] --> I[Local identity or remote Info RPC]
  I --> Q[Match on-chain attestation set and threshold]
  V --> G[Build route proof generators]
  Q --> G
  G --> H[LatestProvableHeight]
  H --> S[Send finality]
  H --> T[Timeout finality]
  H --> W[Write-ack finality]
  S --> R[Relay pipeline]
  T --> R
  W --> R

_{Reviews (1): Last reviewed commit: "replace static finality offsets with Lat..." | Re-trigger Greptile}

…into livevalidate

…n-first-config # Conflicts: # e2e/internal/e2etest/traffic_setup.go # e2e/internal/harness/ibclink/attestor.go # link/docs/configuration.md # link/internal/chains/evm/client.go # link/internal/chains/evm/client_test.go # link/internal/relay/dispatch/dispatcher_test.go # link/internal/relay/pipeline/pipeline_test.go # link/internal/service/attestor/service_test.go

…red root config

…tion-first schema

linear-code · 2026-08-10T07:35:30Z

FOU-1219

FOU-1221

dhfang · 2026-08-10T07:38:53Z

-	// Dual mode: if .attestor config is provided, then we can run both relayer and attestor in the same process.
-	// This might be useful for PoC/testing environments or when an operator wants to run the relayer
+	// Attestors
+	local, remote, err := attestor.ResolveFromConfig(ctx, cfg.Attestors, clientSet, signers)


We resolve both local and remote attestors up front now as opposed to the previous flow which was confusing. We previously initialized the attestor grpc service handlers, which internally resolved the local attestors. We'd pipe that attestor service into the ProofGenerators which retrieved local attestors from it and did their own remote attestor resolution as needed.

dhfang · 2026-08-10T07:41:36Z

 	output = pipeline.ProcessConcurrently(ctx, stageConcurrency,
 		NewProcessorMW(deps.Storage, processors.NewCheckPacketCommitment(deps.Chains, deps.Storage)), output)

-	// wait for the send tx to finalize on the source chain


We pipe the ProofGenerators directly into the processors that handle waiting for tx finality so that they can query the LatestProvableHeight method to determine when a packet commitment can be relayed. This replaces static finality offsets configs.

dhfang · 2026-08-10T07:43:29Z

+// MatchAttestors resolves self's on-chain attestation set and returns the
+// attestors that watch counterparty's chain and whose self-reported address
+// appears in it, erroring if too few match to meet the on-chain threshold.
+func MatchAttestors(


We no longer specify in the configs which attestors belong to which light client in the relayer configs. It is replaced with this logic that associates the attestors with their light clients on startup. This lets us get rid of the attestorSet config block entirely. The attestorSet config block was confusing to dog fooders because you configure it under the client for one chain but it actually should be attesting to the counterparty client's chain.

dhfang · 2026-08-10T07:44:09Z

  rpc LatestHeight(LatestHeightRequest) returns (LatestHeightResponse);
+
+  // Returns identity information about a configured attestor.
+  rpc Info(InfoRequest) returns (InfoResponse);


Added an info endpoint to the attestor so that the relayer can discover the attestor's chain id and address on startup.

gjermundgaraba · 2026-08-10T12:21:19Z

+			continue
+		}
+
+		matched = append(matched, a)


might want to dedup here. with two configured attestors with the same attestor key this could "reach quorum" according to this code (misconfiguration probably, but it would create some confusing errors later).

gjermundgaraba · 2026-08-10T12:29:22Z

-	if attestation, ok := cfg.AttestationByName(token); ok {
-		alias = attestation.Signer
+	if attestor, ok := cfg.AttestorByName(token); ok {
+		alias = attestor.Signer


Given:

attestors:

name: attestor-1
type: remote
grpc: attestor.example.com:3000

And:

ibc deploy client
--chain 1
--counterparty-chain 8453
--attestors attestor-1

The failure is:

The CLI finds attestor-1 in attestors[].

link/cmd/ibc/attestors.go:13 tries to resolve its signer.

The resolver fails to find a signer and returns the original string "attestor-1".

The EVM driver receives that string and rejects it as invalid attestor address "attestor-1".

gjermundgaraba · 2026-08-10T12:34:43Z

-	// wait for the send tx to finalize on the source chain
+	// wait for the send tx's packet event to be at or before what the
+	// destination client can currently prove
+	checkSendFinality, err := processors.NewCheckSendFinality(deps.Chains, deps.ProofGenerators, route)


🤖: These per-transfer finality checks duplicate the proof-height/timestamp gates already enforced by BatchRecvPacket, BatchTimeoutPacket, and BatchAckPacket. This adds redundant RPCs and leaves TxHeight plus the finalized-time fields with no independent runtime purpose.

gjermundgaraba · 2026-08-10T12:35:16Z

-	AutoRelay         AutoRelayConfig `yaml:"autoRelay,omitempty"`
+	// AutoRelay configures auto-relay for packets flowing FROM this end's
+	// chain TOWARD the counterparty end.
+	AutoRelay AutoRelayConfig `yaml:"autoRelay,omitempty"`


🤖: autoRelay.enabled and lookback have no runtime readers. In particular, enabled: false does not disable anything, so the config accepts and documents values that silently have no effect.

gjermundgaraba · 2026-08-10T12:35:18Z

+// relays, in both directions. ClientA's counterparty is simply ClientB (and
+// vice versa).
+type ConnectionConfig struct {
+	Alias   string    `yaml:"alias"`


the connection alias is required and uniqueness-validated, but ConnectionByAlias has no production callers and is otherwise only used in diagnostics atm. should we remove it?

gjermundgaraba · 2026-08-10T12:35:19Z

-	return New(attestorsSpecs)
-}
-
 // New Service constructor. Attestors should have unique aliases


code smell? Alias() is identical to Name() for both implementations and only used to key Service. can we drop it?

gjermundgaraba · 2026-08-10T12:35:21Z

-	clients := make(map[string]string, 2*len(cfg.Connections))
-	type localAttestor struct{ chainID, keyFile string }
-	locals := make(map[string]localAttestor)
+	sourceClients := make(map[string]struct{}, 2*len(cfg.Connections))


🤖: sourceClients exists only to validate cfg.Routes; those routes never reach the generated YAML, while Connections already configure both directions. The harness shape therefore suggests route-level control that the relayer config no longer has.

gjermundgaraba · 2026-08-10T12:35:23Z

+			}
+
+			remote = append(remote, a)
+		default:


🤖: The unsupported-type fallback here and the missing-gRPC check in resolveRemote duplicate authoritative config validation. Production callers cannot reach either state, so maintaining the same schema policy in this resolver risks drift.

gjermundgaraba · 2026-08-10T12:35:24Z

 }

+// Locals returns the subset of attestors this process runs itself.
+func (a Attestors) Locals() []AttestorConfig {


looking at how this is used, it's unclear if we need this?

gjermundgaraba · 2026-08-10T12:35:25Z

-	attestorIDs := env.Attestors()
-	attestorSets := make(map[string]*ibclink.RelayerAttestorSet, len(attestorIDs))
-	for _, id := range attestorIDs {
+	declaredAttestors := map[string]bool{}


🤖: Environment.Attestors() enumerates a map whose IDs were already uniqueness-validated, so duplicates cannot reach this loop. declaredAttestors only rechecks an invariant already guaranteed structurally.

dhfang added 13 commits August 7, 2026 11:48

style: wrap long lines flagged by golangci-lint

601b345

refactor(config): rename ClientEndConfig to ClientConfig

6b4c962

chore: untrack unrelated files accidentally added via git add -A

339feb5

rename ClientConfig to ClientEnd for clarity

c5fe4cd

remove attestorSet config; resolve attestor quorum live from on-chain…

ae93b4d

… state

e2e: mirror attestorSet removal in relayer harness; add quorum startu…

450b508

…p test

trim comments added in the attestorSet-removal change

40a136f

make QueryInfo a method on RemoteAttestor instead of a free function

d7cc7c3

replace static finality offsets with LatestProvableHeight checks; con…

3f1030e

…solidate live validation and attestor resolution

dhfang requested a review from a team as a code owner August 10, 2026 06:15

dhfang added 2 commits August 10, 2026 14:25

roll checkAttestorQuorum's signer/attestor resolution all the way up …

2125758

…into livevalidate

dhfang changed the title ~~relayer: live attestor-quorum resolution, connection-first config, finality checks via LatestProvableHeight~~ relayer: config simplification Aug 10, 2026

dhfang added 2 commits August 10, 2026 15:01

fix undefined status constant reference and lint fallout from the sha…

b1c5d29

…red root config

update TestDeployConnection's render-config assertions for the connec…

588921d

…tion-first schema

dhfang commented Aug 10, 2026

View reviewed changes

gjermundgaraba reviewed Aug 10, 2026

View reviewed changes

Uh oh!

Conversation

dhfang commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

greptile-apps Bot commented Aug 10, 2026

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

linear-code Bot commented Aug 10, 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dhfang commented Aug 10, 2026 •

edited

Loading