Repository navigation
feat: proxy: tracker: stop re-checking a final L1 info tree leaf on L2 -> L1 (#1987) - #1988
Conversation
…2 -> L1 (#1987) At readyToClaim the tracker re-checks on every tick that the L1 info tree leaf a bridge needs is still there, until the leaf is known final. On L1 -> L2 and L2 -> L2 the final GER injection before it settles that. On L2 -> L1 there is no injection step and l1-info-tree-index returns a bare index, so the leaf was polled until the claim was final. After l1-info-tree-index returns the index on a path with no GER injection step, ReverifySteps now asks the same bridge-service instance for injected-l1-info-leaf with network_id=0 and that index, and marks the leaf step final when block_finalized is true. A final leaf is not re-checked anymore. An omitted block_finalized (unknown, or an older bridge service), a 404 and any error leave the step as it was: only l1-info-tree-index decides whether the leaf is gone. - domain.InjectedGERChecker gains L1InfoLeafFinalized, implemented by sources.GERSource with the existing bridge-service client (mock regenerated with mockery) - no change on L1 -> L2 and L2 -> L2 - docs: table and cost paragraph of "Reorgs: re-evaluation and backward transitions" Closes #1987 Co-Authored-By: Claude Fable 5.2 <[email protected]>
|
@codex review |
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Codex Review: Didn't find any major issues. Nice work! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
…at moved (#1987) The finality of the L1 info leaf is asked for the index l1-info-tree-index returns now, while the step keeps the index stored when it completed. If an L1 reorg moved the leaf to another index, marking the step final on the new leaf would freeze the stored index and stop every later re-check. The finality is now only asked when the returned index is the stored one. Otherwise the step stays not final and is re-checked on every tick, as before #1987. Docs: the cost paragraph says that against a bridge service that never reports block_finalized, an L2 -> L1 tracking makes both requests on every tick until its claim is final. Co-Authored-By: Claude Fable 5.2 <[email protected]>
|
@codex review |
|
Codex Review: Didn't find any major issues. Bravo. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
788be65
into
feat/445-proxy-reorg-activity-tracker
…, #1969, #1970) (#1986) > This PR brings the content of the integration branch `feat/445-proxy-reorg-wave1` to `develop`: the squash commits of #1981 and #1982, cherry-picked unchanged (no conflicts). Both were already reviewed and approved in those PRs; the finality resolver (#1979) and the API contract (#1980) they build on are already in `develop`. > > On top of them, a9c639c fixes a Codex P2 found on this PR: `reverifyClaim` now also compares `BlockTimestamp`, so a claim re-included at the same height in another block takes the new timestamp (test `TestReverifyStepsClaimReincludedAtSameHeight`). This fix is not in #1982 or in the integration branch. > > Three stacked PRs were then squash-merged into this branch: #1991 (1d57fd2, e2e acceptance scenarios), #1988 (788be65, L2->L1 leaf finality) and #1990 (5859d6f, ETag and `304` for the activity revision). ## 🔄 Changes Summary - **Activity scan (#1981, #1968, #1969)**: `GET /tracker/v1/activity/from/{from_address}` - The scan of the bridge service stops at the first bridge that is known **and final**. Non-final bridges are re-read on every refresh: they are corrected in place if they moved to another tx, block or timestamp, and removed if they are gone. - An entry is settled only when the claim is confirmed and both the bridge block (origin) and the claim block (destination) are final. Until then it keeps being refreshed and can go back from `claimed` to `readyToClaim` or `pending`. - No bridge-service error, including the `503` returned while it resolves a reorg, removes anything. - The activity `revision` is kept in the in-memory cache and in SQLite, with the same value for the same data and across restarts. - New metrics: `bridgetracker_activity_reorgs_detected_total`, `..._entries_corrected_total` and `..._entries_removed_total`. - **Tracker (#1982, #1970)**: a tracking is final only when its `Claimed` step is backed by a claim in a final block. Until then, on every engine tick: - the origin block hash is re-checked, and the bridge tx is resolved again if it changed; - the claim is re-checked with `isClaimed()`, and the tracking goes back to `WaitingClaim` if the claim is gone; - at `readyToClaim`, the GER injection and the L1 info leaf are re-checked. - Backward moves are persisted and pushed to WebSocket subscribers. A failing check (an RPC error or a `503`) never moves a tracking backwards. - **L2->L1 leaf finality ([#1988](#1988), #1987)**: at `readyToClaim` on L2->L1, once `l1-info-tree-index` returns the stored index, the tracker asks the same bridge-service instance for `injected-l1-info-leaf?network_id=0` and marks the `WaitingL1InfoLeafAvailable` step final when `block_finalized` is `true`. After that, the leaf is not re-checked. An omitted `block_finalized`, a `404` or an error keep the previous behaviour (re-checked every tick). L1->L2 and L2->L2 are unchanged. - **ETag and `304` on the activity endpoint ([#1990](#1990), last item of #1971)**: every `200` of `GET /tracker/v1/activity/from/{from_address}` carries the activity `revision` as a strong `ETag`, plus `Cache-Control: no-store`. A request whose `If-None-Match` matches gets `304 Not Modified` with no body. `400`, `500` and `503` keep their status and carry no `ETag`. `CurrentAPIRevision` goes from 7 to 8. CORS is only documented: the proxy default `[REST.CORS].AllowedHeaders = ["*"]` already allows `If-None-Match`, and an explicit list must add it. It also fixes the `API.md` rule on when a claim changes the `revision`: only when its tx changes, not when the same tx moves to another block. - **E2E reorg acceptance tests ([#1991](#1991), #1972)**: scenarios A1-A6, B1-B4, C1, D1-D2, E1-E4 and F1-F4 cause real reorgs on the anvil chains of `anvil-2chains` and check the activity endpoint, the tracker endpoint and its WebSocket before and after. Each scenario first asserts that aggkit reported the reorg (`last-reorg-event`). Test code and test env only (`ActivityPollInterval = "5s"` and optional config overrides in `test/e2e/envs/anvil-2chains`). ##⚠️ Breaking Changes - 🔌 **API/CLI**: no names or values are removed, but behaviour changes: - `claimed` is no longer terminal: it can go back to `readyToClaim` or `pending` after a reorg. The terminal state is `claimed_finalized`. - `tracking_status` only reads `finished`, and the WebSocket only closes, once the claim is final. With the claim done but not yet final, it stays `running`. - `creation_timestamp` of an activity entry can change if a reorg moves the bridge to another block. ## 📋 Config Updates - None. The SQLite migration `bridgetracker0005` adds `activity_bridge.revision_hash`. - For a browser to send `If-None-Match` cross-origin, `[REST.CORS].AllowedHeaders` must allow it: the default `["*"]` does, an explicit list must add it. ## 🔌 API Updates ### 🔌 Bridge service API - No changes. ### 🔌 Proxy API - 🔌 **AProxy API Update**: the `api_revision` 7 fields introduced by #1980 are populated now: `finalized`, `claimed_finalized` and `revision` in the activity endpoint, and `claimed_finalized` and `bridge_status.block_finalized` in the tracker endpoints and WebSocket. No endpoints are added or removed. Clients must accept `claimed_finalized` before this is deployed (agglayer/sdk#47, agglayer/agglayer-dev-ui#64). - 🔌 **AProxy API Update (#1990)**: `api_revision` 8, additive. The activity endpoint accepts the optional `If-None-Match` request header, answers `304 Not Modified` (no body) when it matches, and sends `ETag: "<revision>"` and `Cache-Control: no-store` on `200` and `304`. The body does not change. ## ✅ Testing - 🤖 **Automatic**: unit tests from #1981 and #1982. - Activity, run against both stores: bridge removed, bridge re-included in another block, claim reorged out or moved, `503` keeping the state, final entries not re-read, restart in the middle of a non-final state. - Tracker: every backward transition on L1->L2, L2->L1 and L2->L2, origin reorged out and re-included, `503` and transient errors leaving the state unchanged, final trackings making no calls, WebSocket backward updates. - Run locally on this branch: `go build ./...`, `go vet`, `go test -race ./bridgetracker/...`, `go test ./proxy/...`, `make lint`. - 🤖 **Unit tests from #1988**: `TestReverifyStepsL2ToL1LeafFinality`, `TestReverifyStepsLeafFinalityOnlyWithoutInjectionStep`, `TestGERSourceL1InfoLeafFinalized` and `TestEngineL2ToL1FinalLeafIsNotCheckedAgain`. - 🤖 **Unit tests from #1990**: `bridgetracker/api/activity_etag_test.go` (`If-None-Match` variants, the same `ETag` across filters and pages, errors never turned into `304`, registry without a revision, the `304` through the real router). - 🤖 **E2E against real reorgs (#1991)**: the new CI groups `proxy-reorg-activity`, `proxy-reorg-claims`, `proxy-reorg-tracker-revision` and `proxy-reorg-resilience` in `test-go-e2e.yml` run in this PR's CI. ## 🐞 Issues - Closes #1968 - Closes #1969 - Closes #1970 - Closes #1972 - Closes #1987 - Closes #1971 - Part of agglayer/pm#445 ## 🔗 Related PRs - #1981 and #1982: the original PRs, reviewed and approved against the integration branch. - #1979 (finality resolver) and #1980 (API contract): already merged into `develop`. - #1991 (e2e acceptance scenarios), #1988 (L2->L1 leaf finality) and #1990 (ETag and `304`): stacked PRs, reviewed there and squash-merged into this branch. - agglayer/sdk#47 and agglayer/agglayer-dev-ui#64: clients accepting `claimed_finalized`. ## 📝 Notes These design decisions are still open, recorded as implemented: - (a) `tracking_status` only reads `finished` once the claim is final. - (b) An unclaimed bridge in a final block reads `finalized=true` and goes back to `false` when it is claimed, until the claim is final. - (c) An origin tx that is reorged out and not re-included within `UnresolvedTimeout` (30 s by default) ends in a terminal error. - (d) On L2->L1 the L1 info leaf used to be polled on every tick while the bridge is at `readyToClaim`. #1988 now stops once the leaf is reported final. Its own open point is that the leaf's finality is only asked when the index matches the stored one; if the leaf moved after an L1 reorg, it keeps being re-checked every tick. Issues in aggkit found by the e2e tests of #1991 (none is a proxy problem, none is fixed here): - #1992: after an L2 reorg removes a GER injection, the aggoracle does not inject that GER again, so the bridges that depend on it stay unclaimable until a later GER is injected. The tests work around it by forcing a later GER on L1. - The aggsender certifies non-final L2 blocks when `BridgeL2Sync` is at `LatestBlock`. If a certificate carrying a bridge of a non-final block settles and the bridge is then reorged out, the aggsender cannot build another certificate and the network's settlement stops. The tests hold the aggsender during each scenario. No issue opened yet. Other notes: - With several bridge-service instances behind a load balancer, a lagging instance can make non-final activity entries be removed and re-added until they converge. - The generated swagger carries unrelated drift (the `Duration` enum and `block_finalized` in the bridge-service payloads), as noted in #1982. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
🔄 Changes Summary
readyToClaim: the L1 info tree leaf is no longer re-checked on every tick once it is final.GET /bridge/v1/l1-info-tree-indexreturns a bare index, so the leaf was polled everyPollInterval(10 s) until the claim was final.l1-info-tree-indexreturns the index, the tracker asks the same bridge-service instance forGET /bridge/v1/injected-l1-info-leaf?network_id=0&leaf_index=<index>and marks theWaitingL1InfoLeafAvailablestep final whenblock_finalizedistrue. From then on neither request is made for that bridge.block_finalized(unknown, or a bridge service that predates the field), a404and any error keep today's behaviour: the step stays not final and is re-checked on the next tick. The finality request never moves a tracking back; onlyl1-info-tree-indexdecides whether the leaf is gone.domain.InjectedGERCheckergainsL1InfoLeafFinalized(ctx, bridge, leafIndex) (finalized bool, err error), implemented bysources.GERSourcewith the existing bridge-service client. Mock regenerated with mockery.📋 Config Updates
🔌 API Updates
🔌 Bridge service API
injected-l1-info-leafwithnetwork_id=0).🔌 Proxy API
block_finalizedof theWaitingL1InfoLeafAvailablestep can now turntrueon L2 -> L1 before the claim is final.✅ Testing
TestReverifyStepsL2ToL1LeafFinality(domain): final (marked, not asked again on later ticks), not final or omitted, finality check failing, leaf answered at another index, leaf gone, index check failing, claim gone with a final leaf.TestReverifyStepsLeafFinalityOnlyWithoutInjectionStep(domain): L1 -> L2 and L2 -> L2 never ask for the leaf's own finality (strict mocks).TestGERSourceL1InfoLeafFinalized(adapter):network_id=0, the leaf index, the instance that answersl1-info-tree-index; omitted /false/true/404/503.TestEngineL2ToL1FinalLeafIsNotCheckedAgain(engine): the step turning final is persisted and published, and later ticks make no leaf request.make build,make lint(0 issues),go vet ./...,go test -race ./bridgetracker/...,go test ./proxy/... ./bridgeservice/...: all pass.🐞 Issues
🔗 Related PRs
📝 Notes
l1-info-tree-indexreturns the same index the step stored when it completed. If it returns another one (the leaf moved after an L1 reorg), the step stays not final and is re-checked on every tick, as before this PR. Marking it final there would freeze a stalel1_info_tree_indexin the step result. Updating the stored index, or moving the tracking back in that case, is not part of this PR.block_finalized, an L2 -> L1 tracking atreadyToClaimnow makes two requests per tick instead of one until its claim is final (documented in the cost paragraph).InjectedGERCheckerport (both of its methods are oneinjected-l1-info-leafrequest), so no new wiring is needed in the engine or the proxy.🤖 Generated with Claude Code