Repository navigation
feat: proxy: reorg support in the activity and tracker endpoints (#1968, #1969, #1970) - #1986
joanestebanr wants to merge 4 commits into
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 <noreply@anthropic.com>
… 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 <noreply@anthropic.com>
|
@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".
| if claim.ClaimTx != stored.ResultClaim.ClaimTx || claim.BlockNumber != stored.ResultClaim.BlockNumber { | ||
| logger.Infof("%s: the claim moved from tx %s in block %d to tx %s in block %d", | ||
| id, stored.ResultClaim.ClaimTx, stored.ResultClaim.BlockNumber, claim.ClaimTx, claim.BlockNumber) | ||
| tracking = replaceClaim(tracking, claimedIdx, claim) |
There was a problem hiding this comment.
Refresh changed claim timestamps before finalizing
If a reorg re-includes the same claim transaction at the same block height but with a different block timestamp, this condition ignores the refreshed claim record. Consequently, ResultClaim.BlockTimestamp and the claim step's StartDate/EndDate retain the orphaned block's timestamp, even when finalizeClaim subsequently closes the tracking using the fresh record's finality. Include timestamp changes in the replacement check so the REST/WebSocket snapshot does not permanently publish dates from the discarded chain.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Valid, fixed in a9c639c. The re-verification now also replaces the stored claim when only its block timestamp changed (same tx, same height, different block), so ResultClaim.BlockTimestamp and the step's StartDate/EndDate follow the canonical block before finalizeClaim runs. Covered by TestReverifyStepsClaimReincludedAtSameHeight.
… 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 <noreply@anthropic.com>
|
@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". |
🔄 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.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.🔌 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).✅ 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.🐞 Issues
🔗 Related PRs
develop.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.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