fix: aggkit-proxy: bali integration: bridge tracker activity endpoint, GER settlement/injection fixes

[joanestebanr]

🔄 Changes Summary

• feat(bridgetracker): new GET /tracker/v1/activity/from/{from_address} endpoint that scans every bridge service known to the bridgeservicefinder (via new Finder.NetworkIDs()) for bridges sent by an address and resolves each one's claim state (ActivityCache, ActivitySource, ActivityQuerier/ActivityBridgeScanner/ActivityClaimChecker ports). Opt-in via includeTracking=true to also register still-unclaimed bridges with the tracker. Endpoint is only registered when wired (proxy/cmd/run.go), and swagger docs are regenerated.
• feat(bridgetracker): StepClaimed is now its own tracked step with a dedicated ClaimedResolver that fetches the claim tx/block from the destination network's bridge service, decoupled from StepWaitingClaim, which now checks isClaimed() on-chain directly through a new ClaimChecker port instead of waiting on the indexed claim record — faster and authoritative, at the cost of not carrying claim tx details itself (that's what the new Claimed step result is for). The on-chain binding/cache logic is factored out of ActivitySource into sources/claim_checker.go (contractClaimCheckers) and shared by both the tracker engine and the activity endpoint.
• fix(bridgetracker): introduce domain.ScannedBridge to track which network's bridge service actually reported a scanned bridge (NetworkID), distinct from Bridge.OriginNetwork (the bridged asset's origin network) — the two diverge when an asset is re-bridged across more than one hop, which was feeding the wrong sourceBridgeNetwork into isClaimed() and the wrong network into TrackingID/the activity endpoint's bridge_network_id for such bridges.
• feat(bridgetracker): new GET /bridge-address[/{network_id}] endpoint, resolving the bridge contract address for one network or every network currently known — opt-in via Config.BridgeAddressResolver, wired in proxy/cmd/run.go off bridgeservicefinder.Finder directly. Backed by a new Config.BridgeAddress override map on bridgeservicefinder.Finder itself (priority: per-network entry, then [0] as the default, then the rollup manager's own on-chain BridgeAddress()).
• feat(bridgetracker): ClaimResult now also carries BlockTimestamp alongside BlockNumber. InjectedGERResult is restructured into L1InfoTreeLeaf (the L1 UpdateL1InfoTree/UpdateL1InfoTreeV2 event that produced the covering leaf) and an optional L2InjectedGER (the actual L2 block/timestamp the GER was injected at on the destination network) — fixing bug: proxy: step WaitingGERInjection as result have the L1 block #1818, where the L1 block was returned in the L2 field's place. When the destination's bridge-service instance doesn't report the L2 injection block itself (injected_l2_block_num/injected_l2_block_timestamp on GET /bridge/v1/injected-l1-info-leaf), GERSource falls back to scanning that network's own GlobalExitRootManagerL2 contract for the UpdateHashChainValue event backwards in chunks, via the new Tracker.L2GlobalExitRootAddress per-network contract address map (a workaround-only fallback, see its doc) — bounded by a new Tracker.L2InjectionLookbackBlocks (default 1,000 blocks) instead of always walking back to genesis.
• fix(bridgetracker): resolve the settled GER correctly when the settlement tx has no UpdateL1InfoTree event: walk backwards on L1 for the most recent earlier one instead of surfacing "not ready" forever, excluding same-block logs from a later transaction, and querying eth_getLogs in chunks that respect providers' 10,000-block range cap.
• fix(bridgetracker): gate certificate settlement on the settlement tx actually being visible on L1 (not just the agglayer client reporting Settled), avoiding a premature TransactionReceipt lookup that would otherwise fail.

⚠️ Breaking Changes

• None. Config.BridgeAddressResolver and the new bridgetracker activity/bridge-address ports are additive/opt-in.

📋 Config Updates

• 🧾 New optional BridgeServiceFinder.BridgeAddress map (networkID → address override), default empty — consulted by the new GET /bridge-address[/{network_id}] endpoint before falling back to the rollup manager's on-chain BridgeAddress(). That endpoint itself is gated by Config.BridgeAddressResolver (Go-level wiring, not a TOML key); unset leaves both routes unregistered.

• 🧾 New optional Tracker.ActivityIdleTimeout (defaults to IdleTimeout if unset) — idle timeout for the activity endpoint's own cache.

• 🧾 New optional Tracker.L2GlobalExitRootAddress (networkID → GlobalExitRootManagerL2 address map, default empty) and Tracker.L2InjectionLookbackBlocks (default 1000) — workaround-only fallback for a destination network whose bridge-service instance predates L2 injection block reporting (fix(bridgeservice): expose real L2 injection block/timestamp on injected-l1-info-leaf #1819); defaults leave behavior unchanged for everyone else.

  [BridgeServiceFinder.BridgeAddress]
  # optional per-network override, consulted in this priority order by Finder.BridgeAddress:
  # BridgeAddress[networkID], then BridgeAddress[0] (default for every other network), then the
  # rollup manager's own on-chain BridgeAddress()
  0 = "0xShared_L1_bridge_address_used_as_the_default"
  5 = "0xNetwork5s_own_bridge_address"
  
  [Tracker]
  ActivityIdleTimeout = "30m"
  L2InjectionLookbackBlocks = 1000
  
  # Workaround only: uncomment for a destination network whose bridge-service instance does not
  # report the L2 block a covering GER was injected at.
  # [Tracker.L2GlobalExitRootAddress]
  # 1 = "0x..."

✅ Testing

• 🤖 Automatic: go build ./... and go test ./bridgetracker/... ./bridgeservicefinder/... ./autoclaim/... ./proxy/... pass, including new/updated regression tests for the activity endpoint (activity_test.go, sources/activity_test.go, cache_test.go), the claimed-step split (resolve_steps_test.go, engine_test.go), the new bridge-address endpoint (bridge_address_test.go), the settlement GER backwards-search fix (settlement_test.go), and the L2 injection fallback/lookback cap (sources_test.go's TestGERSourceInjectedGER_FallsBackToL2Scan and TestFindL2InjectionBlockBackwards, proxy/config/config_test.go).

🐞 Issues

• Fixes bug: proxy: step WaitingGERInjection as result have the L1 block #1818.

🔗 Related PRs

• None.

📝 Notes

• This branch's history still contains commits for bridgeservicefinder's IgnoreNetworkIDs and the l2gersync eth_getLogs chunk-cap fix (originally developed alongside this work) — both landed directly on develop in the meantime (feat: bridgeservicefinder: add IgnoreNetworkIDs to skip dead networks 1809 #1810, fix(l2gersync): adapt isGERRemovedFromL2 scan to RPC eth_getLogs block-range cap #1813), so neither shows up in this PR's diff anymore despite still being present in the branch's git history.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3712ed8ae8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[joanestebanr]

@claude review

[claude]

Claude finished @joanestebanr's task in 4m 1s —— View job

---

✅ Code Review Complete

Reviewed PR #1815: Bali integration fixes and activity endpoint

---

🚀 What's New

This PR introduces a comprehensive activity tracking endpoint (GET /tracker/v1/activity/from/{from_address}) that scans all known bridge services for user bridges and tracks claim status. It also fixes several critical issues in GER settlement/injection tracking, adds a bridge address resolution endpoint, and introduces dead-network handling to skip unreachable networks during startup.

🐛 Bug Fixes

• Fixed bug: proxy: step WaitingGERInjection as result have the L1 block #1818: L2 GER injection block/timestamp now correctly reports actual L2 values instead of L1 block data
• Fixed GER settlement resolution for settlement transactions without UpdateL1InfoTree events (with new backwards search)
• Fixed isGERRemovedFromL2 to handle RPC providers that cap eth_getLogs block ranges via chunked scanning
• Introduced ScannedBridge domain model to correctly track source network ID (where bridge tx occurred) vs asset origin network ID
• Split StepClaimed into separate step with dedicated ClaimedResolver that fetches claim tx details from bridge service
• StepWaitingClaim now uses authoritative on-chain isClaimed() check via new ClaimChecker port

📋 Config Updates

• IgnoreNetworkIDs = [] under [BridgeServiceFinder] / [AutoClaim.BridgeServiceFinder] - Skips known-dead networks during enumeration. Empty array means no networks ignored. Example: IgnoreNetworkIDs = [1001, 1002]
• L2GlobalExitRootAddress = {} under [Tracker] - Maps networkID → GlobalExitRootManagerL2 contract address for L2 injection fallback when bridge service doesn't report it. Empty map disables fallback. Example: L2GlobalExitRootAddress = {1 = "0x...", 2 = "0x..."}
• L2InjectionLookbackBlocks = 1000 under [Tracker] - Limits backwards scan for L2 GER injection to prevent full chain scan on misconfigured networks. Default: 1000 blocks
• ActivityIdleTimeout under [Tracker] - Idle timeout for activity cache entries. Defaults to IdleTimeout value if not set
• Go-level wiring: Config.BridgeAddressResolver, Config.ActivityScanner, Config.ActivityClaims (no TOML keys)

⚠️ Breaking Changes

None - All new features are opt-in or additive with backward-compatible defaults.

---

🔴 Critical Issues (Required Fixes)

Issue 1: Off-by-one error in backwards GER lookup produces 10,001-block queries

Location: bridgetracker/sources/settlement.go:192
Severity: 🔴 P1 - Causes immediate query failures on strict RPC providers
Reported by: Codex automated review

Problem: The backwards search uses fromBlockChunk = toBlock - l1InfoTreeBackwardsSearchChunkSize, which produces an inclusive range [fromBlockChunk, toBlock] of 10,001 blocks (e.g., [15000, 25000]). RPC providers enforcing a 10,000-block eth_getLogs limit reject these queries immediately.

Impact: Every settlement without UpdateL1InfoTree in its own receipt fails to resolve, remaining stuck in error state indefinitely.

Fix:

// Line 192 - Current (WRONG):
fromBlockChunk = toBlock - l1InfoTreeBackwardsSearchChunkSize

// Should be:
fromBlockChunk = toBlock - l1InfoTreeBackwardsSearchChunkSize + 1

This produces exactly 10,000 blocks: [15001, 25000].

Fix this →

---

Issue 2: Missing log position filter allows selecting GER from events AFTER settlement

Location: bridgetracker/sources/settlement.go:206-209
Severity: 🔴 P1 - Returns wrong GER for certificates
Reported by: Codex automated review

Problem: When findEventUpdateL1InfoTreeBackwards finds UpdateL1InfoTree logs in the same block as the settlement, it selects the last log in the entire block without checking whether that log occurred before or after the settlement transaction:

// Line 206-209 - Current code:
if len(logs) > 0 {
    last := logs[len(logs)-1]  // ❌ Could be AFTER settlement!
    // ... extracts GER from last log
}

Impact: If another transaction emits UpdateL1InfoTree later in the settlement block, the tracker associates the certificate with a GER that didn't exist when the settlement executed. This causes wrong GER/leaf index associations and breaks claim resolution.

Fix: Filter logs to only those at or before SettlementLogIndex (analogous to the position filtering in GERSource):

if len(logs) > 0 {
    // Filter to logs before or at settlement position in the same block
    var filtered []gethtypes.Log
    for _, l := range logs {
        if l.BlockNumber < receipt.BlockNumber.Uint64() ||
           (l.BlockNumber == receipt.BlockNumber.Uint64() && l.Index <= result.SettlementLogIndex) {
            filtered = append(filtered, l)
        }
    }
    if len(filtered) == 0 {
        // No UpdateL1InfoTree before settlement in this chunk - continue to next chunk
        if fromBlockChunk == 0 { /* error handling */ }
        toBlock = fromBlockChunk - 1
        continue
    }
    last := filtered[len(filtered)-1]
    // ... extract GER
}

Fix this →

---

Issue 3: Bridge network ID tracking in activity endpoint ✅ FALSE POSITIVE

Location: bridgetracker/sources/activity.go:127
Reported by: Codex automated review

Status: ✅ Code is correct - Codex flagged this incorrectly.

The code properly preserves networkID via ScannedBridge{Bridge: b, NetworkID: networkID} and uses it correctly in IsClaimed() at line 140. The distinction between ScannedBridge.NetworkID (where tx was sent) and Bridge.OriginNetwork (asset origin) is maintained throughout.

---

🟡 Suggestions (Code Quality & Best Practices)

4. Consider adding explicit comment for underflow protection

File: bridgetracker/sources/ger.go:387-390

The lookback calculation already handles underflow correctly:

floor := uint64(0)
if head.Number > lookback {
    floor = head.Number - lookback
}

Suggest adding a comment: // Guard against underflow when chain is shorter than lookback

---

5. Activity cache settled state transitions deserve documentation

File: bridgetracker/activity.go

The logic for when an activity entry stops being refreshed (claimed + claim record fetched) is implicit. Consider adding a state diagram comment or explicit documentation of the "settled" conditions.

---

6. Edge case test coverage for claim step split

Files: bridgetracker/domain/resolve_steps_test.go, bridgetracker/engine_test.go

The split between StepWaitingClaim (on-chain) and StepClaimed (bridge service indexer) is well-tested, but consider adding a test for the window where isClaimed() returns true but the bridge service hasn't indexed the claim tx yet (should stay StepWaitingClaim.Done → StepClaimed.Pending).

---

7. Consider logging or metrics for L2 injection fallback usage

File: bridgetracker/sources/ger.go:341-349

The fallback to scanning L2 for GER injection logs when already logged as a warning, but adding a metric counter would help ops teams track how often old bridge-service instances are encountered.

---

🟢 Positive Observations

1. Excellent domain modeling - ScannedBridge cleanly separates "reporting network" from "asset origin network"
2. Graceful degradation - Activity endpoint returns warnings for failed networks instead of full failure
3. Comprehensive testing - Dedicated test files for new features with good edge case coverage
4. Clear inline documentation - Complex logic (GER fallback, backwards search) has helpful comments
5. Backward compatibility - All new features are opt-in with sensible defaults
6. Pragmatic configuration - IgnoreNetworkIDs handles real-world dead-network scenarios
7. Security-conscious - Block finality requirements prevent reorg issues
8. API design - Activity endpoint properly carries warnings in response, not as errors

---

📊 Testing Assessment

Coverage: ✅ Good

• New endpoints have dedicated test files
• Domain logic changes have corresponding test updates
• Edge cases (malformed logs, missing events) are tested
• Mock-based testing for external dependencies

Gaps (Minor):

• L2 injection fallback with RPC failures during scan
• Activity cache concurrent access patterns
• Bridge address endpoint with empty finder results

---

📝 Summary

This PR delivers significant value with the activity endpoint and fixes important bugs in GER handling. The two critical issues (off-by-one in backwards search and missing log position filter) are must-fix before merge, as they cause incorrect behavior under normal operation. The third Codex issue is a false positive.

Overall code quality is high, with good separation of concerns, comprehensive error handling, and thoughtful backward compatibility.

Recommendation: 🟡 Approve after addressing the 2 critical issues

---

| Branch: feat/fix_bali_integration

[joanestebanr]

Fixed the off-by-one in findEventUpdateL1InfoTreeBackwards (Issue 1 in the review above, same as Codex's discussion_r3872865287) in 0c021aa — each backwards chunk now spans exactly l1InfoTreeBackwardsSearchChunkSize blocks (toBlock - chunkSize + 1), instead of chunkSize+1.

[joanestebanr]

Fixed the same-block GER exclusion issue (also flagged by Codex as discussion_r3872865292) in ce78dab — findEventUpdateL1InfoTreeBackwards now filters out any UpdateL1InfoTree log sharing the settlement's block at or after its own log index before picking the latest one.

[joanestebanr]

Addressed item 6 (edge case test coverage for the claim step split) in a603660: added TestResolveStepsClaimedNotIndexedYet in domain/resolve_steps_test.go, and extended TestEngineLifecycleL2ToL2 in engine_test.go to tick through the window where isClaimed() goes true but the bridge service hasn't indexed the claim tx yet — pinning that StepWaitingClaim completes (Done) while StepClaimed stays its own current step (InProgress, no result) until ClaimFor resolves on a later tick.