*: add duties cache #4227

KaloyanTanev · 2026-01-16T13:46:21Z

WIP

category: feature
ticket: #4009

Copilot

Pull request overview

Implements a duties cache to reduce duplicate beacon-node duty requests (scheduler + VC) by caching proposer/attester/sync-committee duties and routing call sites through cached accessors.

Changes:

Added DutiesCache to app/eth2wrap and wired it into the app’s eth2 client via SetDutiesCache and reorg invalidation.
Updated scheduler, inclusion tracker, and validator API component to use cached duty fetch paths.
Extended beaconmock and client wrappers (multi/lazy/http adapter) plus tests/mocks to support duties-cache interfaces.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
testutil/integration/simnet_test.go	Removes Teku simnet integration bits and related test scaffolding.
testutil/integration/helpers_test.go	Removes `externalIP` helper previously used by Teku simnet wiring.
testutil/beaconmock/options.go	Adds default/option wiring for cached duty funcs in beaconmock.
testutil/beaconmock/beaconmock_fuzz.go	Adds cached duty funcs to fuzz option.
testutil/beaconmock/beaconmock.go	Extends mock client with duties-cache funcs and `UpdateCacheIndices`.
core/validatorapi/validatorapi_test.go	Updates tests to use cached duties funcs.
core/validatorapi/validatorapi.go	Routes duties endpoints through cached duty calls and rewrites pubkey mapping.
core/tracker/inclusion.go	Uses cached attester duties for inclusion tracking.
core/scheduler/scheduler.go	Switches duty resolution to cached duty calls.
core/fetcher/fetcher_test.go	Minor formatting-only adjustments.
core/fetcher/fetcher.go	Minor formatting-only adjustments.
app/vmock.go	Wires duties cache into vmock eth2 provider.
app/sse/listener_internal_test.go	Uses `require.Len` for map length assertion.
app/sse/listener.go	Groups handler func types and minor formatting.
app/featureset/config.go	Minor formatting-only adjustments.
app/eth2wrap/valcache.go	Removes old validator cache file (moved into new cache module).
app/eth2wrap/synthproposer_test.go	Updates tests to provide cached duties funcs on mocks.
app/eth2wrap/synthproposer.go	Extends synth wrapper provider interface to include cached duties provider.
app/eth2wrap/multi_test.go	Adds coverage for new duties-cache forwarding methods.
app/eth2wrap/multi.go	Adds multi-client forwarding for duties-cache APIs.
app/eth2wrap/mocks/client.go	Regenerates mock client to include duties-cache APIs.
app/eth2wrap/lazy_test.go	Adds tests for lazy wrapper duties-cache APIs.
app/eth2wrap/lazy.go	Adds lazy wrapper support for duties-cache APIs.
app/eth2wrap/httpwrap.go	Adds duties-cache hooks to the HTTP adapter wrapper.
app/eth2wrap/genwrap/genwrap.go	Updates generated interface template to include duties-cache APIs.
app/eth2wrap/eth2wrap_gen.go	Updates generated client interface to include duties-cache APIs.
app/eth2wrap/cache_test.go	Adds initial tests for duties cache behavior (proposer only).
app/eth2wrap/cache.go	Introduces new cache module containing validator cache + duties cache implementation.
app/app.go	Wires duties cache into core workflow and hooks reorg invalidation + index updates.

Comments suppressed due to low confidence (1)

app/eth2wrap/cache_test.go:295

The duties cache test only covers proposer duties with a single (epoch, indices) shape. Given the new behavior, it would be valuable to add coverage for: (1) different index subsets in the same epoch (to ensure correct keying/filtering), (2) attester/sync duties cache paths, and (3) chain reorg invalidation (InvalidateCache).

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

core/validatorapi/validatorapi.go

Copilot · 2026-01-23T15:44:02Z

app/eth2wrap/cache.go

+// ProposerDutiesCache returns the cached proposer duties, or fetches them if not available populating the cache.
+func (c *DutiesCache) ProposerDutiesCache(ctx context.Context, epoch eth2p0.Epoch, vidxs []eth2p0.ValidatorIndex) ([]*eth2v1.ProposerDuty, error) {
+	duties, ok := c.cachedProposerDuties(epoch)
+
+	if ok {
+		return duties, nil
+	}


This cache is keyed only by epoch: if duties for an epoch are cached from a request with a subset of validator indices, subsequent calls for the same epoch with a different vidxs will incorrectly return the cached subset. This can produce missing duties for the VC or scheduler. Either key the cache by (epoch, requested indices) or always populate the cache for the configured validatorIndices and filter to the requested vidxs on return (making UpdateCacheIndices meaningful).

Copilot · 2026-01-23T15:44:02Z

app/eth2wrap/cache.go

+// AttesterDutiesCache returns the cached attester duties, or fetches them if not available populating the cache.
+func (c *DutiesCache) AttesterDutiesCache(ctx context.Context, epoch eth2p0.Epoch, vidx []eth2p0.ValidatorIndex) ([]*eth2v1.AttesterDuty, error) {
+	duties, ok := c.cachedAttesterDuties(epoch)
+
+	if ok {
+		return duties, nil
+	}


AttesterDutiesCache has the same issue as ProposerDutiesCache: once an epoch is cached it ignores the requested indices (vidx) and always returns the cached slice. This can cause the validator API to return incomplete duties when different subsets are requested within the same epoch.

Copilot · 2026-01-23T15:44:02Z

app/eth2wrap/cache.go

+	eth2Resp, err := c.eth2Cl.AttesterDuties(ctx, opts)
+	if err != nil {
+		return nil, err
+	}
+
+	c.attesterDuties[epoch] = eth2Resp.Data
+
+	return eth2Resp.Data, nil


AttesterDutiesCache stores eth2Resp.Data directly in the cache without validating entries or copying the slice. If the underlying response contains nil elements or a caller mutates the returned duties, it can corrupt the cached data. Consider validating for nil duties (as done for proposer/sync) and returning/storing a defensive copy.

Copilot · 2026-01-23T15:44:03Z

app/app.go

+	// Setup duties cache, refreshing it every epoch.
+	dutiesCache := eth2wrap.NewDutiesCache(eth2Cl, []eth2p0.ValidatorIndex{})
+	eth2Cl.SetDutiesCache(dutiesCache.ProposerDutiesCache, dutiesCache.AttesterDutiesCache, dutiesCache.SyncCommDutiesCache)
+
+	sseListener.SubscribeChainReorgEvent(dutiesCache.InvalidateCache)
+


DutiesCache is created and hooked into the client, but it is never trimmed on epoch boundaries (only validator cache is trimmed). Since DutiesCache retains maps keyed by epoch, this will grow unbounded over time unless Trim is called periodically (e.g., alongside valCache.Trim() on refresh).

Copilot · 2026-01-23T15:44:03Z

testutil/beaconmock/beaconmock.go

 }

+func (m Mock) UpdateCacheIndices(ctx context.Context, idxs []eth2p0.ValidatorIndex) {
+	m.UpdateCacheIndicesFunc(ctx, idxs)


UpdateCacheIndices calls UpdateCacheIndicesFunc unconditionally. defaultMock doesn't set this function, so calling UpdateCacheIndices on a default beaconmock instance will panic (contradicting the "doesn't panic" intent of defaultMock). Consider defaulting UpdateCacheIndicesFunc to a no-op and/or guarding against nil here.

Suggested change

m.UpdateCacheIndicesFunc(ctx, idxs)

if m.UpdateCacheIndicesFunc != nil {

m.UpdateCacheIndicesFunc(ctx, idxs)

}

Copilot · 2026-01-23T15:44:03Z

core/validatorapi/validatorapi.go

-		if duties[i] == nil {
-			return nil, errors.New("proposer duty cannot be nil")
-		}
+	for _, d := range cachedResp {


ProposerDutiesCache returns pointers; this loop dereferences d without checking for nil. If the cache (or underlying BN response) contains a nil duty, this will panic. Add a nil check (like AttesterDuties/SyncCommitteeDuties do) before duty := *d and return a clear error.

Suggested change

for _, d := range cachedResp {

for _, d := range cachedResp {

if d == nil {

return nil, errors.New("nil proposer duty from cache")

}

sonarqubecloud · 2026-01-25T19:21:01Z

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

KaloyanTanev self-assigned this Jan 16, 2026

KaloyanTanev marked this pull request as draft January 16, 2026 13:46

KaloyanTanev force-pushed the kalo/duties-cache branch from e3878a1 to 697631c Compare January 16, 2026 16:01

KaloyanTanev added 2 commits January 19, 2026 09:14

Add duties cache

fd7b00b

Fix beaconmock

b5f3d01

KaloyanTanev force-pushed the kalo/duties-cache branch from 697631c to b5f3d01 Compare January 19, 2026 07:15

KaloyanTanev added 7 commits January 19, 2026 10:03

Invalidate duties cache on reorg event

a2d6fe7

Add validator indices to calls

609c797

Add cache function to synth proposer

37f11f5

Remove Teku testing

45c2261

Add duties cache to vmock

75306e9

Fix appending to same slice

042f352

Fix tests

75910d9

KaloyanTanev requested a review from Copilot January 23, 2026 15:37

Copilot started reviewing on behalf of KaloyanTanev January 23, 2026 15:38 View session

Copilot AI reviewed Jan 23, 2026

View reviewed changes

KaloyanTanev added 3 commits January 25, 2026 20:45

Fix TestResolveAttDuties test

ad8f4fe

Fix TestSchedulerDuties test

5c3456f

Fix multi tests for cache

eff332f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

*: add duties cache #4227

*: add duties cache #4227

KaloyanTanev commented Jan 16, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

sonarqubecloud bot commented Jan 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

*: add duties cache #4227

Are you sure you want to change the base?

*: add duties cache #4227

Conversation

KaloyanTanev commented Jan 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Jan 25, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants