Skip to content

feat: proxy: tracker: stop re-checking a final L1 info tree leaf on L2 -> L1 (#1987) - #1988

Merged
joanestebanr merged 2 commits into
feat/445-proxy-reorg-activity-trackerfrom
feat/1987-l2l1-leaf-finality
Nov 18, 2026
Merged

joanestebanr merged 2 commits into
feat/445-proxy-reorg-activity-trackerfrom
feat/1987-l2l1-leaf-finality

Conversation

@joanestebanr

@joanestebanr joanestebanr commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #1986 (base branch feat/445-proxy-reorg-activity-tracker). It will be retargeted to develop once #1986 merges.

🔄 Changes Summary

  • Tracker, L2 -> L1 at readyToClaim: the L1 info tree leaf is no longer re-checked on every tick once it is final.
    • Until now only a final GER injection could settle the leaf step. L2 -> L1 has no injection step, and GET /bridge/v1/l1-info-tree-index returns a bare index, so the leaf was polled every PollInterval (10 s) until the claim was final.
    • Now, after l1-info-tree-index returns the index, the tracker asks the same bridge-service instance for GET /bridge/v1/injected-l1-info-leaf?network_id=0&leaf_index=<index> and marks the WaitingL1InfoLeafAvailable step final when block_finalized is true. From then on neither request is made for that bridge.
    • An omitted block_finalized (unknown, or a bridge service that predates the field), a 404 and 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; only l1-info-tree-index decides whether the leaf is gone.
  • No change on L1 -> L2 and L2 -> L2: the leaf's own finality is never asked there.
  • domain.InjectedGERChecker gains L1InfoLeafFinalized(ctx, bridge, leafIndex) (finalized bool, err error), implemented by sources.GERSource with the existing bridge-service client. Mock regenerated with mockery.

⚠️ Breaking Changes

  • None.

📋 Config Updates

  • None.

🔌 API Updates

🔌 Bridge service API

  • No changes. The tracker makes one more read of an existing endpoint (injected-l1-info-leaf with network_id=0).

🔌 Proxy API

  • No changes to endpoints or payloads. block_finalized of the WaitingL1InfoLeafAvailable step can now turn true on L2 -> L1 before the claim is final.

✅ Testing

  • 🤖 Automatic: new unit tests
    • 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 answers l1-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.
  • Run locally on this branch: make build, make lint (0 issues), go vet ./..., go test -race ./bridgetracker/..., go test ./proxy/... ./bridgeservice/...: all pass.
  • Not run: e2e (covered by test: e2e: proxy reorg acceptance scenarios on anvil #1972).

🐞 Issues

🔗 Related PRs

📝 Notes

  • Decision to validate: the finality is only asked when l1-info-tree-index returns 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 stale l1_info_tree_index in the step result. Updating the stored index, or moving the tracking back in that case, is not part of this PR.
  • Against a bridge service that never reports block_finalized, an L2 -> L1 tracking at readyToClaim now makes two requests per tick instead of one until its claim is final (documented in the cost paragraph).
  • The new method lives on the existing InjectedGERChecker port (both of its methods are one injected-l1-info-leaf request), so no new wiring is needed in the engine or the proxy.

🤖 Generated with Claude Code

…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]>
@joanestebanr

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-18T14:38:22.685345Z 2db2321 Draft marked ready
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: b8460e87c3

ℹ️ 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".

…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]>
@joanestebanr

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 2db2321937

ℹ️ 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
joanestebanr marked this pull request as ready for review November 18, 2026 14:36
@joanestebanr
joanestebanr merged commit 788be65 into feat/445-proxy-reorg-activity-tracker Nov 18, 2026
36 checks passed
@joanestebanr
joanestebanr deleted the feat/1987-l2l1-leaf-finality branch November 18, 2026 14:37
joanestebanr added a commit that referenced this pull request Nov 19, 2026
…, #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]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant