Skip to content

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

Draft
joanestebanr wants to merge 4 commits into
developfrom
feat/445-proxy-reorg-activity-tracker
Draft

joanestebanr wants to merge 4 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.

🔄 Changes Summary

⚠️ 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.

🔌 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 has no finality signal, so it is polled on every tick while the bridge is at readyToClaim.

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 <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>
@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-17T19:59:16.869610Z a9c639c 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 Outdated
Comment on lines +214 to +217
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)

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 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 👍 / 👎.

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.

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>
@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".

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant