Skip to content

feat: proxy: reorg support in the activity and tracker endpoints (#1968, #1969, #1970) - #1986

Merged
joanestebanr merged 11 commits into
developfrom
feat/445-proxy-reorg-activity-tracker
Nov 19, 2026
Merged

joanestebanr merged 11 commits into
developfrom
feat/445-proxy-reorg-activity-tracker

Conversation

@joanestebanr

@joanestebanr joanestebanr commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

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 (feat: proxy: reorg-aware activity scan and settle only on finalized claims (#1968, #1969) #1981, feat: proxy: activity: reorg-aware scan of bridges (correct or remove non-final entries) #1968, feat: proxy: activity: settle an entry only when bridge and claim are finalized #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 (feat: proxy: tracker re-evaluates non-final steps and moves backwards after a reorg (#1970) #1982, feat: proxy: tracker: re-evaluate non-final steps and allow moving backwards after a reorg #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, feat: proxy: tracker: stop re-checking a final L1 info tree leaf on L2 -> L1 #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, last item of feat: proxy: API: expose finality, claimed_finalized and a per-address revision #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, test: e2e: proxy reorg acceptance scenarios on anvil #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

✅ Testing

🐞 Issues

🔗 Related PRs

📝 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. feat: proxy: tracker: stop re-checking a final L1 info tree leaf on L2 -> L1 (#1987) #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):

  • [BUG] aggoracle: a GER injection removed by an L2 reorg is never injected again #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:

🤖 Generated with Claude Code

joanestebanr and others added 2 commits November 17, 2026 20:47
…laims (#1968, #1969) (#1981)

> **Stacked PR**: based on `feat/445-proxy-reorg-wave1`, which is the
three PRs of the first wave merged together (reorg e2e helpers, finality
resolver, API contract). Review only the commits of this branch; it will
be retargeted to `develop` once those are merged.

## 🔄 Changes Summary
- **Scan** of `GET /bridge/v1/bridges`: stops at the first bridge that
is known **and final**, instead of the first known one. Non-final
bridges are re-read on every refresh: a different `tx_hash`, `block_num`
or `block_timestamp` corrects the entry in place, and a bridge that is
gone is removed. Page 1 is re-read after a multi-page scan, with a
second pass if `count` changed while paging.
- **Settled** = claim confirmed, bridge block final (origin network) and
claim block final (destination network), resolved with the finality
resolver. Until then the entry keeps being refreshed and can go back
from `claimed` to `readyToClaim` or `pending`. Settled entries become
`claimed_finalized` with `finalized=true` and are not checked again.
- No bridge-service error removes anything, including the `503` it
answers while resolving a reorg (it adds a warning and retries on the
next refresh).
- **Revision** kept up to date in the in-memory cache and in SQLite,
with the same value for the same data and after a restart.
- **SQLite store**: `claimed_finalized` in the `claimed` filter and when
parsing a stored status, `GetActivityRevision`, non-final entries can be
overwritten.
- Metrics: `bridgetracker_activity_reorgs_detected_total`,
`..._entries_corrected_total`, `..._entries_removed_total`.

## ⚠️ Breaking Changes
- 🔌 **API/CLI**: no new fields (they come with the contract PR), but
behaviour changes: `claimed` is no longer terminal, and
`creation_timestamp` can change if a reorg moves the bridge to another
block.

## 🔌 API Updates
### 🔌 Proxy API
- 🔌 **AProxy API Update**: `GET
/tracker/v1/activity/from/{from_address}` now populates `finalized`,
`claimed_finalized` and `revision`.

## ✅ Testing
- 🤖 **Automatic**: unit tests, each scenario against both stores (in
memory and SQLite) requiring the same sequence of revisions: bridge
removed, re-included in another block, replaced by another one with the
same `global_index`, final bridge not re-read, scan failure / `503`
keeping the state, claim reorged out (to `readyToClaim` and to
`pending`), claim re-included in another block, final claim (no more
calls), restart in the middle of a non-final state. Scanner tests count
the pages requested.
- Not covered here: e2e against real reorgs (follow-up, #1972).

## 🐞 Issues
- Closes #1968
- Closes #1969
- Part of agglayer/pm#445

## 🔗 Related PRs
- Depends on the PRs for #1966, #1967 and #1971. Sibling of the tracker
PR (#1970); both touch `proxy/cmd/run.go`, `docs/bridgetracker/API.md`
and the generated swagger.

## 📝 Notes
- Migration `bridgetracker0005.sql` adds
`activity_bridge.revision_hash`. In SQLite the revision is the sum of
the row hashes, computed on read.
- `finalized` follows the contract formula (bridge final and, if
claimed, claim final), so an unclaimed bridge in a final block reads
`finalized=true` and goes back to `false` when it is claimed, until the
claim is final. Open for discussion.
- An entry seen only through the RPC fallback is also removed when the
bridge service lists a later deposit of the same sender without it.
- With several bridge-service instances behind a load balancer, a
lagging instance does not return the newest non-final bridges: those
entries are removed and re-added, and the revision flips until it
converges.
- With the RPC down, the resolver logs one warning per non-final entry
per refresh.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
… after a reorg (#1970) (#1982)

> **Stacked PR**: based on `feat/445-proxy-reorg-wave1`, which is the
three PRs of the first wave merged together (reorg e2e helpers, finality
resolver, API contract). Review only the commits of this branch; it will
be retargeted to `develop` once those are merged.

## 🔄 Changes Summary
- **Closing rule**: a tracking is final only when the `Claimed` step is
backed by a claim whose block is final. Then `claim_status` is
`claimed_finalized` and it is never evaluated again. Until then it stays
supervised and can move backwards.
- On every engine tick, for non-final trackings:
- **Origin**: the canonical hash of the origin block is compared with
the stored one. If it changed, the bridge tx is resolved again (and
followed to its new block if it was re-included). Works with the
in-memory and the SQLite registries.
- **Claim**: `isClaimed()`; if it is no longer claimed the tracking goes
back to `WaitingClaim`. A claim that moved to another block replaces the
stored one.
- **Readiness** (at `readyToClaim`): the GER injection and the L1 info
leaf are checked again; if one is gone the tracking goes back to that
step.
- Backward moves are persisted and sent to WebSocket subscribers like
any other change.
- A failing check (RPC error, or the bridge service answering `503`
while it resolves a reorg) leaves the state as it is and is retried on
the next tick; it never moves a tracking backwards.
- `bridge_status.block_finalized` follows the finality of the origin
bridge block.

## ⚠️ Breaking Changes
- 🔌 **API/CLI**: no names or values change, but `tracking_status` only
reads `finished` (and the WebSocket only closes) once the claim is
**final**. With the claim done but not final it stays `running`. Clients
that stopped at `finished` now wait for finality.

## 🔌 API Updates
### 🔌 Proxy API
- 🔌 **AProxy API Update**: tracker endpoints and WebSocket now populate
`claimed_finalized` and `bridge_status.block_finalized`.

## ✅ Testing
- 🤖 **Automatic**: unit tests for each backward transition on the three
paths (L1->L2, L2->L1, L2->L2), origin reorged out and re-included (in
memory and SQLite), claim moved to another block, `503` / transient
errors not changing the state, a final tracking making no calls, a
claimed-not-final tracking still supervised past the retention, and a
subscriber receiving the backward update.
- Not covered here: e2e against real reorgs (follow-up, #1972).

## 🐞 Issues
- Closes #1970
- Part of agglayer/pm#445

## 🔗 Related PRs
- Depends on the PRs for #1966, #1967 and #1971. Sibling of the activity
PR (#1968, #1969); both touch `proxy/cmd/run.go`,
`docs/bridgetracker/API.md` and the generated swagger.

## 📝 Notes
- Cost per tick of a non-final tracking: one block header while the
origin is not final, plus one or two bridge-service calls depending on
the phase (`isClaimed` + `GET /claims` when claimed;
`injected-l1-info-leaf` and `l1-info-tree-index` at `readyToClaim`). A
final tracking costs nothing.
- No schema migration.
- An origin tx that is reorged out and not re-included within
`UnresolvedTimeout` (30 s by default) ends in a terminal error, like a
tx that is never mined.
- Older intermediate steps (GER update, certificate, settlement) are not
re-checked one by one; the origin and leaf / injection checks cover
them.
- On L2->L1 the L1 info leaf has no finality signal, so it is queried on
every tick while the bridge is at `readyToClaim`.
- The swagger was regenerated and carries unrelated drift (the
`Duration` enum, and `block_finalized` of the bridge-service payloads).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
@joanestebanr

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 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-19T09:07:46.390851Z abab9cb Manual request
ℹ️ 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 chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c7a1d9e5ba

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

Comment thread bridgetracker/domain/reorg.go Resolved
… changes after a reorg

A claim re-included at the same height lands in another block whose
timestamp may differ; compare the timestamp too so the claimed step
dates never keep the orphaned block's time.

Co-Authored-By: Claude Opus 5.5 <[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. Swish!

Reviewed commit: a9c639cd92

ℹ️ 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 and others added 3 commits November 18, 2026 15:36
> **Stacked on #1986** (`feat/445-proxy-reorg-activity-tracker`). It
will be retargeted to `develop` once #1986 merges.

## 🔄 Changes Summary
- E2E acceptance tests for reorg support in `aggkit-proxy` (#1972, wave
3 of agglayer/pm#445): they cause real reorgs on the anvil chains of
`anvil-2chains` and check what the activity endpoint, the tracker
endpoint and its WebSocket report before and after. Test code and test
env only; no production code changes.
- Every scenario asserts first that aggkit itself reported the reorg
(`GET /bridge/v1/last-reorg-event`, asked directly) and only then what
the proxy answers, so a failure tells a syncer problem from a proxy one.
Mining is controlled by the tests and every wait polls a condition with
a timeout.
- New files under `test/e2e/`: `proxy_reorg_common_test.go` (helpers),
`proxy_reorg_activity_test.go` (A1-A6), `proxy_reorg_claims_test.go`
(B1-B4, C1), `proxy_reorg_tracker_test.go` (D1, D2),
`proxy_reorg_revision_test.go` (E1-E4), `proxy_reorg_resilience_test.go`
(F1-F4).
- Four CI groups in `test-go-e2e.yml`, each on its own stack:
`proxy-reorg-activity`, `proxy-reorg-claims`,
`proxy-reorg-tracker-revision`, `proxy-reorg-resilience`.

### Scenario status

Local = run on my machine against `aggkit:local` built from this branch,
one `make test-e2e TEST_RUN=...` per CI group, each ending with the
post-test bridge check of `TestMain` passing.

| # | Scenario | Test | Local status |
|---|---|---|---|
| A1 | Bridge from network 1 reorged out before it is final |
`TestProxyReorgActivity` | passing |
| A2 | Same bridge re-included in another block |
`TestProxyReorgActivity` | passing |
| A3 | Bridge replaced by a different one with the same `deposit_count`
| `TestProxyReorgActivity` | passing |
| A4 | L1 -> L2 bridge, reorg on L1 | `TestProxyReorgActivity` | passing
|
| A5 | Bridge from network 2 seen only through the RPC fallback, reorged
out | `TestProxyReorgActivity` | passing |
| A6 | Finalized bridge, shallower reorg | `TestProxyReorgActivity` |
passing |
| B1 | Claim reorged out before it is final | `TestProxyReorgClaims` |
passing |
| B2 | L2 reorg removes the claim and the GER injection |
`TestProxyReorgClaims` | passing |
| B3 | Finalized claim | `TestProxyReorgClaims` | passing |
| B4 | Claim re-included in another block | `TestProxyReorgClaims` |
passing |
| C1 | L2 reorg removes only the GER injection | `TestProxyReorgClaims`
| passing |
| D1 | Tracker: origin transaction disappears while tracking |
`TestProxyReorgTracker` | passing |
| D2 | Tracker: `Claimed` goes back, WebSocket notified |
`TestProxyReorgTracker` | passing |
| D3 | L2 -> L1, L1 reorg of the settlement transaction (optional) | - |
not written |
| E1 | Refreshes with no changes, and not-final -> final |
`TestProxyReorgRevision` | passing |
| E2 | Non-final claim of an old bridge (page > 1) reorged out |
`TestProxyReorgRevision` | passing |
| E3 | Reorg while a client paginates | `TestProxyReorgRevision` |
passing |
| E4 | Two proxies on the same data, one restarted |
`TestProxyReorgRevision` | passing |
| F1 | Bridge service answers `503` during the reorg |
`TestProxyReorgResilience` | passing |
| F2 | Proxy with `DBPath` restarted, reorg while it is down |
`TestProxyReorgResilience` | passing |
| F3 | Bridge service omits `block_finalized` |
`TestProxyReorgResilience` | passing |
| F4 | Burst of repeated reorgs with bridges in flight |
`TestProxyReorgResilience` | passing |

## ⚠️ Breaking Changes
- None.

## 📋 Config Updates
- Test env only (`test/e2e/envs/anvil-2chains`):
- `ActivityPollInterval = "5s"` in both aggkit-proxy configs (the
default is 30s), so the tests wait one short refresh.
- `extra_hosts: host.docker.internal:host-gateway` on
`aggkit-proxy-002`, so the resilience test can put a reverse proxy
between it and the bridge service.
- The config mounts of `aggkit-001` and `aggkit-proxy-002` take an
optional compose variable (`AGGKIT_001_CONFIG`,
`AGGKIT_PROXY_002_CONFIG`, defaulting to the tracked files). The tests
that need another config render it in a temporary directory and recreate
the service with the variable set (`Env.RecreateService`): they never
write to a tracked file, so a killed run leaves the tree clean (checked
by interrupting a run with SIGINT).

## 🔌 API Updates
- None.

## ✅ Testing
- 🤖 **Automatic**: the tests above. Local results are in the table; `go
build ./...`, `go vet ./test/e2e/...` and `make lint` pass. Locally each
test takes between 1 and 2.5 minutes, plus the stack start and the
post-test check.

## 🐞 Issues
- Closes #1972
- Part of agglayer/pm#445

## 🔗 Related PRs
- #1986: the proxy code under test (base of this PR).
- #1978: the reorg helpers these tests build on.
- #1983: the reorg detector problems the tests avoid (they use
`anvil_reorg`, never a rollback to a shorter chain).

## 📝 Notes
- **Assertions that follow open decisions of #1986** (marked `NOTE` in
the code; they test the current behaviour and decide nothing):
  - (a) `tracking_status` reads `finished` only with a final claim (D2).
- (b) an unclaimed bridge in a final block reads `finalized=true`, and a
claimed one is not final until its claim is (A6, B1).
- (c) a reorged-out origin tx that is not re-included ends in a terminal
error after `UnresolvedTimeout`, 30 s (D1, F2).
- (d) nothing is asserted about how often the L2 -> L1 leaf is
re-checked.
- **A5 is the one scenario where aggkit has no reorg to report**:
`aggkit-002` syncs network 2 at `FinalizedBlock`, so it never tracks the
reorged blocks. The test asserts that instead (the bridge service never
served the bridge and `last-reorg-event` did not change) and that the
proxy forgot the bridge through its RPC window.
- **F1 and F3 inject their condition on the wire.** The bridge service
cannot be made to answer `503` or to omit `block_finalized` on demand,
so the test runs a reverse proxy on the host between `aggkit-proxy-002`
and the bridge service of `aggkit-001`. It changes a status code (F1) or
removes one JSON field (F3); everything else is aggkit's own answer.
- **F2** sets `DBPath` on `aggkit-proxy-002` and reads the SQLite file
out of the stopped container to check the stale entry and tracking
really were persisted before the reorg.
- **F4**: the first two rounds of the burst wait until the proxy lists
the bridge they then reorg, so the proxy does hold stale entries; the
other rounds do not wait for anything.
- **B4**: a claim tx re-included in another block keeps the same
`revision` (the hash covers the claim's tx hash, not its block). That
matches the "What goes into the hash" table of
`docs/bridgetracker/API.md`, while the rule above the table reads as if
a claim "re-included in another block" changed it. The test asserts the
table.
- **Found in aggkit while writing the tests (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 (its transaction manager already holds the
injection as mined), so the bridges that depend on it stay unclaimable
until a later GER is injected. The proxy reports them as `pending`,
which is right. B2 and C1 work around it: they recover the bridge by
forcing a later GER on L1 (`forceNewGER`).
- The aggsender of `aggkit-001` builds certificates from the same
non-final L2 data its bridge service serves (`BridgeL2Sync` at
`LatestBlock`). If a certificate that carries a bridge of a non-final
block settles and the bridge is then reorged out, the aggsender cannot
build another certificate (`failed to get local exit root by hash ...:
not found`) and the network's settlement stops for good; the post-test
bridge check of `TestMain` then fails. Each test here holds the
aggsender for its duration (`holdAggsender`: `aggkit-001` runs with
`[AggSender] MaxL2BlockNumber` at the current head, and goes back to its
own config at the end). Whether aggkit should guard against this
combination is not decided here.
- On a paused L2 the GER syncer (`L2GERSync` at `LatestBlock`) does not
process an injection in the head block until another block is mined on
top, so `injected-l1-info-leaf` only serves it then. The tests work with
it.
- A6: "not re-read" in the issue is about the bridge-service listing
below the first final bridge, which is not observable through the API.
The test asserts that the entry and `revision` do not change. B3 does
assert the settled entry is not rechecked (`last_updated_timestamp`
stops).
- Not covered: D3 (optional), and an L1 reorg that removes an L1 info
tree leaf (not observable in this env, as the issue says).
- Small changes to existing test code: `claimL1ToL2` is split so the
claim can be sent without waiting for it to be mined,
`fetchTrackingData` gets a variant with the proxy URL, and the tracker
mirror type gains `block_finalized`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <[email protected]>
…2 -> L1 (#1987) (#1988)

> 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 #1972).

## 🐞 Issues
- Closes #1987
- Part of agglayer/pm#445

## 🔗 Related PRs
- #1986: the reorg support this builds on (open decision (d) there is
what this PR settles).

## 📝 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](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <[email protected]>
…#1990)

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

## 🔄 Changes Summary
- **Activity endpoint** (`GET
/tracker/v1/activity/from/{from_address}`): HTTP conditional requests on
the activity `revision`. This is the last optional item of #1971.
- Every `200` carries the `revision` of its body as the `ETag` header,
between double quotes (a strong entity tag, RFC 9110).
- A request whose `If-None-Match` holds that value is answered `304 Not
Modified`, with the `ETag` and no body, while the revision is unchanged.
`GetActivity` is not called for a `304`.
- The `ETag` is the revision, so it is the same for every
`filterBridges`, `page_number` and `page_size` of an address.
- `If-None-Match` accepts a list of tags, `*` and weak tags (`W/"..."`),
compared weakly as RFC 9110 defines for this header. The bare revision
without quotes does not match.
- A `304` only replaces a `200`. Validation, `flush_cache` and
registering the address (with `includeTracking`) run as before; `400`,
`500` and `503` keep their status and carry no `ETag`.
- A registry that keeps no revision sends no `ETag` and never answers
`304`.
- `CurrentAPIRevision` 7 -> 8, with its history entry.
- `runCommand` writes a response with no body when a command returns no
object.

## ⚠️ Breaking Changes
- None. The body is unchanged and a client that does not send
`If-None-Match` never receives a `304`.

## 📋 Config Updates
- None. For a browser to send `If-None-Match` cross-origin, the operator
must list it in `[REST.CORS].AllowedHeaders` (existing setting).

## 🔌 API Updates
### 🔌 Bridge service API
- No changes.

### 🔌 Proxy API
- 🔌 **AProxy API Update**: `GET
/tracker/v1/activity/from/{from_address}`, additive, `api_revision` 8.
- New response headers on `200` and `304`: `ETag: "<revision>"` and
`Cache-Control: no-store`.
- New optional request header `If-None-Match`, and new response `304 Not
Modified` (no body).
  - No endpoint added or removed, no change to the body.

### 🔌 Others API
- None.

## ✅ Testing
- 🤖 **Automatic**: new unit tests in
`bridgetracker/api/activity_etag_test.go`
  - no header: `200` with the `ETag` of the body's revision;
- `If-None-Match`: current tag, weak tag, `*`, list, several header
lines -> `304`; another revision, unquoted revision, empty header ->
`200`;
- the same `ETag` for different filters and pages (including a page past
the end), and a `304` on each;
  - revision changed -> `200` with the new `ETag`;
  - `flush_cache` and `includeTracking` still applied on a `304`;
- `400` / `503` / `500` never turned into a `304`, and carry no `ETag`
(including a `500` while reading the entries);
  - registry without a revision: no `ETag`, no `304`;
- through the real router: the `304` has an empty body and no
`Content-Type`.
- 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, and no manual test against a browser.

## 🐞 Issues
- Refs #1971 (its last optional item; the issue is left open for its
owner to close)
- Part of agglayer/pm#445

## 🔗 Related PRs
- #1986: the activity revision this builds on.

## 📝 Notes
Decisions validated by the owner:
- **`api_revision` 7 -> 8** is kept. The change is additive; the bump
lets a client tell from `GET /health` whether an instance answers `304`.
- **`Cache-Control: no-store` next to the `ETag`** is kept. The revision
leaves out `finalized`, the `claimed` -> `claimed_finalized` step,
`last_updated_timestamp`, `tracking` and `warnings`, so a `304` means
"nothing the revision covers changed", not "the body is identical".
`no-store` keeps a browser from revalidating a stored `200` on its own
and handing a stale body to a page that never sent `If-None-Match`.
- **CORS**: no code change, documented in `API.md`. `If-None-Match` must
be allowed by `[REST.CORS].AllowedHeaders`: the proxy default `["*"]`
allows it, an explicit list must add it. `ETag` is not exposed to
cross-origin scripts, so a browser client on another origin builds the
tag from the body's `revision`.

Other notes:
- The tag is strong only in syntax: it identifies the revision, not the
bytes of the body. This is documented in `API.md`.
- Doc fix in the revision rules of `API.md`: a bridge re-included in
another block or transaction changes `revision`; a claim changes it only
when its transaction changes, not when the same claim tx moves to
another block (only `claim.tx_hash` is hashed).
- Swagger: only the bridge tracker spec was regenerated (swag v1.16.4),
and the unrelated generator drift (the `Duration` enum, `format` of
integers) is left out.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <[email protected]>
@joanestebanr
joanestebanr marked this pull request as ready for review November 19, 2026 08:33

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5859d6f72d

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

Comment on lines +300 to +303
if final {
changed = true
steps[i].BlockFinalized = true
if step.Step == types.StepWaitingGERInjection {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Refresh the injection record before marking its step final

If a destination-chain reorg re-includes a GER injection in a different block before the next tracker tick, InjectedGERPresent still returns true and can subsequently report it finalized. This branch then freezes the existing step without refreshing ResultInjectedGer.L2InjectedGER or its dates, so REST and WebSocket snapshots permanently retain the orphaned injection block number and timestamp. Unlike the claim re-verification, this check cannot detect a changed location because its port only returns presence and finality. Refresh or compare the injection's location and update the stored result and dates before marking the step final.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in abab9cb.

InjectedGERChecker.InjectedGERPresent now returns the injection the bridge service reports instead of a bare present flag: the GER plus injected_l2_block_num / injected_l2_block_timestamp, read from the same GET injected-l1-info-leaf call. It returns nil when the injection is gone. It still does no L2 scan or header lookup.

In reverifyReadiness, before marking the step final, injectionMoved compares that answer with the stored ResultInjectedGer. It counts as moved when the GER differs (a later leaf's injection now covers the bridge), the L2 block differs, or the L2 timestamp differs (re-included at the same height). Values the bridge service does not report are never compared, so older or Legacy-mode instances never trigger a refresh. When it moved, replaceInjection stores the new result, which is built by newInjectedGERResult, now shared with WaitingGERInjectionResolver. It also sets EndDate and the warning the way the resolver does when the step completes, and resets BlockFinalized. After that, the reported finality is applied. This follows the claim fix in a9c639c.

Tests: TestReverifyStepsInjectionReincludedElsewhere covers four refresh cases: another block reported final, the same height with another timestamp, an unreported timestamp, and another GER. It also checks that an unchanged or unreported location leaves the tracking as it is. Without the fix, the refresh cases fail. TestGERSourceInjectedGERPresent covers the adapter. The go test -race ./bridgetracker/... and make lint runs are clean.

@joanestebanr
joanestebanr enabled auto-merge (squash) November 19, 2026 08:55
…t final after a reorg

A destination-chain reorg can re-include the GER injection in another
block (or let a later leaf's injection cover the bridge) before the next
tracker tick. ReverifySteps only got presence and finality from the
InjectedGERChecker port, so it froze the step as final while the REST
and WS snapshots kept the orphaned L2 block number and timestamp.

InjectedGERPresent now returns the injection the bridge service reports
(GER and injected_l2_block_num/injected_l2_block_timestamp from the same
GET injected-l1-info-leaf it already called), nil when gone. When the
GER, the L2 block or its timestamp differ from the stored result, the
result, EndDate and warning are refreshed the way the resolver sets them
before the step is marked final. Values the bridge service does not
report are never compared, so nothing churns on older instances.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@joanestebanr

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: abab9cbb33

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

Comment thread bridgetracker/activity_refresh.go Outdated
Comment on lines +228 to +232
claim = existing.Claim // keep the last known record until it can be fetched again
}
}
entry.Claim = claim
entry.ClaimFinal = r.claimFinal(ctx, item, existing, claim)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep cached claims non-final when their refresh fails

When a non-final claim has no reported block_finalized value, a reorg can re-include its transaction at the same height with a different timestamp. If ClaimInfo then fails, this branch reuses the orphaned record, but the subsequent claimFinal call can prove the transaction final through the receipt fallback, which compares its hash and height rather than its timestamp. Subsequent refreshes take the existing.ClaimFinal shortcut and never fetch the corrected record, permanently serving the orphaned Claim.BlockTimestamp. The IsClaimed error branch has the same problem. Preserve the cached state on these failures without newly marking the claim final until its record has been refreshed successfully.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in ad7cc87.

When IsClaimed or ClaimInfo fails on an entry that was already claimed, Refresh now keeps the cached claim with its cached finality (keepCachedClaim) and no longer calls claimFinal on it. Only a freshly fetched record can be newly proven final, so an orphaned record is never frozen by the receipt fallback. The next successful refresh fetches the record again and resolves its finality.

Test: TestActivityEntryRefresher_FailedClaimRefreshKeepsCachedFinality covers both failure branches with a strict finality resolver that must not be called, and checks that the cached claim is kept and stays non-final. Both cases fail without the fix. The go test -race ./bridgetracker/... and make lint runs are clean.

…efresh fails

When isClaimed() or the claim record fetch failed, the activity refresher
kept the cached claim but still asked the finality resolver about it. A
cached record may be orphaned (re-included at the same height in another
block, with another timestamp), and the receipt fallback proves finality
by hash and height alone. That marked the stale record final, and the
final-claim shortcut then never fetched the corrected record again.

On those failures the cached claim is now kept with its cached finality
as is: only a freshly fetched record can be newly proven final.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@joanestebanr joanestebanr self-assigned this Nov 19, 2026
@joanestebanr
joanestebanr merged commit 23e6c25 into develop Nov 19, 2026
41 checks passed
@joanestebanr
joanestebanr deleted the feat/445-proxy-reorg-activity-tracker branch November 19, 2026 11:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment