Repository navigation
feat: proxy: reorg support in the activity and tracker endpoints (#1968, #1969, #1970) - #1986
Conversation
…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]>
|
@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. |
There was a problem hiding this comment.
💡 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".
… 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]>
|
@codex review |
|
Codex Review: Didn't find any major issues. Swish! 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". |
> **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]>
There was a problem hiding this comment.
💡 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".
| if final { | ||
| changed = true | ||
| steps[i].BlockFinalized = true | ||
| if step.Step == types.StepWaitingGERInjection { |
There was a problem hiding this comment.
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 👍 / 👎.
There was a problem hiding this comment.
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.
…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]>
|
@codex review |
There was a problem hiding this comment.
💡 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".
| 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) |
There was a problem hiding this comment.
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 👍 / 👎.
There was a problem hiding this comment.
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]>
🔄 Changes Summary
GET /tracker/v1/activity/from/{from_address}claimedtoreadyToClaimorpending.503returned while it resolves a reorg, removes anything.revisionis kept in the in-memory cache and in SQLite, with the same value for the same data and across restarts.bridgetracker_activity_reorgs_detected_total,..._entries_corrected_totaland..._entries_removed_total.Claimedstep is backed by a claim in a final block. Until then, on every engine tick:isClaimed(), and the tracking goes back toWaitingClaimif the claim is gone;readyToClaim, the GER injection and the L1 info leaf are re-checked.503) never moves a tracking backwards.readyToClaimon L2->L1, oncel1-info-tree-indexreturns the stored index, the tracker asks the same bridge-service instance forinjected-l1-info-leaf?network_id=0and marks theWaitingL1InfoLeafAvailablestep final whenblock_finalizedistrue. After that, the leaf is not re-checked. An omittedblock_finalized, a404or an error keep the previous behaviour (re-checked every tick). L1->L2 and L2->L2 are unchanged.304on the activity endpoint (#1990, last item of feat: proxy: API: expose finality, claimed_finalized and a per-address revision #1971): every200ofGET /tracker/v1/activity/from/{from_address}carries the activityrevisionas a strongETag, plusCache-Control: no-store. A request whoseIf-None-Matchmatches gets304 Not Modifiedwith no body.400,500and503keep their status and carry noETag.CurrentAPIRevisiongoes from 7 to 8. CORS is only documented: the proxy default[REST.CORS].AllowedHeaders = ["*"]already allowsIf-None-Match, and an explicit list must add it. It also fixes theAPI.mdrule on when a claim changes therevision: only when its tx changes, not when the same tx moves to another block.anvil-2chainsand 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 intest/e2e/envs/anvil-2chains).claimedis no longer terminal: it can go back toreadyToClaimorpendingafter a reorg. The terminal state isclaimed_finalized.tracking_statusonly readsfinished, and the WebSocket only closes, once the claim is final. With the claim done but not yet final, it staysrunning.creation_timestampof an activity entry can change if a reorg moves the bridge to another block.📋 Config Updates
bridgetracker0005addsactivity_bridge.revision_hash.If-None-Matchcross-origin,[REST.CORS].AllowedHeadersmust allow it: the default["*"]does, an explicit list must add it.🔌 API Updates
🔌 Bridge service API
🔌 Proxy API
api_revision7 fields introduced by feat: proxy: API contract for finality, claimed_finalized and activity revision (#1971) #1980 are populated now:finalized,claimed_finalizedandrevisionin the activity endpoint, andclaimed_finalizedandbridge_status.block_finalizedin the tracker endpoints and WebSocket. No endpoints are added or removed. Clients must acceptclaimed_finalizedbefore this is deployed (feat(aggkit): support tracker api_revision 7 (claimed_finalized, finalized, revision) sdk#47, feat: support aggkit-proxy reorg handling (claimed_finalized, revision, non-final claims) agglayer-dev-ui#64).api_revision8, additive. The activity endpoint accepts the optionalIf-None-Matchrequest header, answers304 Not Modified(no body) when it matches, and sendsETag: "<revision>"andCache-Control: no-storeon200and304. The body does not change.✅ Testing
503keeping the state, final entries not re-read, restart in the middle of a non-final state.503and transient errors leaving the state unchanged, final trackings making no calls, WebSocket backward updates.go build ./...,go vet,go test -race ./bridgetracker/...,go test ./proxy/...,make lint.TestReverifyStepsL2ToL1LeafFinality,TestReverifyStepsLeafFinalityOnlyWithoutInjectionStep,TestGERSourceL1InfoLeafFinalizedandTestEngineL2ToL1FinalLeafIsNotCheckedAgain.bridgetracker/api/activity_etag_test.go(If-None-Matchvariants, the sameETagacross filters and pages, errors never turned into304, registry without a revision, the304through the real router).proxy-reorg-activity,proxy-reorg-claims,proxy-reorg-tracker-revisionandproxy-reorg-resilienceintest-go-e2e.ymlrun in this PR's CI.🐞 Issues
🔗 Related PRs
develop.304): stacked PRs, reviewed there and squash-merged into this branch.claimed_finalized.📝 Notes
These design decisions are still open, recorded as implemented:
tracking_statusonly readsfinishedonce the claim is final.finalized=trueand goes back tofalsewhen it is claimed, until the claim is final.UnresolvedTimeout(30 s by default) ends in a terminal error.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):
BridgeL2Syncis atLatestBlock. 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:
Durationenum andblock_finalizedin the bridge-service payloads), as noted in feat: proxy: tracker re-evaluates non-final steps and moves backwards after a reorg (#1970) #1982.🤖 Generated with Claude Code