lag tip by x blocks

[nischitpra]

Summary by CodeRabbit

• New Features
  • Added a POLLER_LAG configuration to introduce a controllable delay in block polling, allowing operators to tune indexing/head alignment timing.
• Bug Fixes / Improvements
  • Polling now uses an "effective" block height that accounts for POLLER_LAG while metrics continue to report the actual head; logging now surfaces both actual and effective head values for clarity.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4ac3a079-2663-4d8a-b11e-bb30d7deb573

📥 Commits

Reviewing files that changed from the base of the PR and between 56fa0b3 and b0b892a.

📒 Files selected for processing (2)

• configs/config.go
• internal/committer/poollatest.go

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

Walkthrough

Added a new PollerLag config and updated polling to compute an effectiveLatest = RPC head minus PollerLag (when CommitterIsLive), then use effectiveLatest for fetch, gating, and rightsizing while metrics continue reporting the raw RPC head.

Changes

Cohort / File(s)	Summary
Configuration Addition configs/config.go	Added exported PollerLag uint64 to Config with tags env:"POLLER_LAG" envDefault:"0"; minor spacing/formatting alignment adjustments only.
Polling Logic Update internal/committer/poollatest.go	pollLatest() now reads RPC head as rpcLatest, computes effectiveLatest = max(0, rpcLatest - PollerLag) when CommitterIsLive, uses effectiveLatest for batch fetch (GetValidBlockDataInBatch), gating checks, and rightsizing triggers; metrics still record rpcLatest; debug log includes both rpc_latest_block and effective_latest_block.

Sequence Diagram(s)

sequenceDiagram
  participant Poller
  participant RPC
  participant Committer
  participant LibBlockData
  participant Metrics

  Poller->>RPC: fetch latest block (rpcLatest)
  Poller->>Poller: compute effectiveLatest = rpcLatest - PollerLag (if CommitterIsLive)
  Poller->>Metrics: set CommitterLatestBlockNumber(rpcLatest)
  Poller->>LibBlockData: GetValidBlockDataInBatch(effectiveLatest, nextBlockNumber)
  LibBlockData-->>Poller: block batch
  Poller->>Committer: evaluate gating using effectiveLatest
  Committer-->>Poller: commit decision / nextBlockNumber update

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'lag tip by x blocks' accurately describes the main change: adding a PollerLag configuration field that lags the tip (latest block) by a configurable number of blocks to control indexing behavior.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch np/poller_lag

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@internal/committer/poollatest.go`:
- Around line 30-40: The code currently always applies config.Cfg.PollerLag to
compute effectiveLatest (using rpcLatest), which delays non-live catch-up;
change the logic so PollerLag is only applied when the committer is running in
live mode — keep effectiveLatest = rpcLatest for non-live runs and only set
effectiveLatest = rpcLatest - config.Cfg.PollerLag when live and PollerLag <
rpcLatest; leave the metrics.CommitterLatestBlockNumber update as-is and adjust
the subsequent check involving nextBlockNumber and
config.Cfg.CommitterLagByBlocks to use this live-aware effectiveLatest; apply
the same fix to the duplicated logic around lines 91-95.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4b3c08f6-3c10-4c3c-ab45-86f9c2a0e671

📥 Commits

Reviewing files that changed from the base of the PR and between 0168ca2 and 56fa0b3.

📒 Files selected for processing (2)

• configs/config.go
• internal/committer/poollatest.go