Repository navigation
feat: proxy: API contract for finality, claimed_finalized and activity revision (#1971) - #1980
Merged
Merged
Conversation
joanestebanr
marked this pull request as ready for review
November 17, 2026 12:06
Collaborator
Author
|
@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. |
|
Codex Review: Didn't find any major issues. More of your lovely PRs please. 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". |
joanestebanr
force-pushed
the
feat/1971-proxy-api-contract
branch
from
November 17, 2026 12:11
525453e to
b6b429c
Compare
joanestebanr
force-pushed
the
feat/1971-proxy-api-contract
branch
from
November 17, 2026 12:38
b6b429c to
79e48cc
Compare
…evision to the tracker API contract Part of agglayer/pm#445 (reorg support in aggkit-proxy), contract only: types, wire format, docs and swagger. Nothing computes the new values yet (see #1967-#1970), so finalized/block_finalized read false, revision reads 0 and claimed_finalized is never produced. - claim_status gains "claimed_finalized", the only final state, on both the tracker (TrackingData) and the activity item; TrackerClaimStatusClaimedFinalized is appended to the enum so existing numeric values do not move, with ParseTrackerClaimStatus and IsClaimed (filterBridges=claimed matches both claimed values) - ActivityItem.finalized (domain.ActivityEntry.Finalized) and BridgeStatus.block_finalized (domain.BridgeInfo.BlockFinalized), always serialized - ActivityResponse.revision, served through the optional domain.ActivityRevisionReader port (implemented by ActivityCache, read before the entries); it increases on an addition, removal, state change or reorg correction, not when an entry only becomes final - CurrentAPIRevision 6 -> 7 with its history entry - docs/bridgetracker/API.md: claim_status state diagram, revision rules and client flow, new fields, fixed stale api_revision sample; swagger regenerated - tests: JSON round trips, wire always-present fields, revision/doc consistency Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…d of a counter Follow-up to the #1971 contract (agglayer/pm#445): revision is now a string, a hash of the address's activity, so it needs no persistence and is the same after a restart, after the address's cache is rebuilt and on every instance holding the same data. Contract only: nothing maintains it in the refresh path yet, so it reads as the empty-activity value. - domain: ActivityRevisionPrefix ("v1:"), EmptyActivityRevision ("v1:" + 64 zeros), HashActivityEntry (SHA-256 over global_index, bridge tx_hash and block_num, claim_status with claimed_finalized counted as claimed, claim tx_hash) and ActivityRevision, the order-independent sum mod 2^256 of the entry hashes with Add/Remove/String, so both stores produce identical values incrementally - ActivityRevisionReader.GetActivityRevision and ActivityResponse.Revision are strings; ActivityCache holds a domain.ActivityRevision per address - docs/bridgetracker/API.md Revision section (hash semantics, what is and is not hashed, lagging instances, back to a previous state), api_revision 7 history entry and swagger - tests: determinism, golden value, order independence, add/remove, claimed vs claimed_finalized, hashed and non-hashed fields Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
joanestebanr
force-pushed
the
feat/1971-proxy-api-contract
branch
from
November 17, 2026 13:59
79e48cc to
5e4a5b4
Compare
arnaubennassar
approved these changes
Nov 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🔄 Changes Summary
Contract only (types, wire format, docs); the values are populated by the follow-up PRs.
claim_statusgets the valueclaimed_finalized, the only final state.claimedcan still go back toreadyToClaimorpendingafter a reorg.filterBridges=claimedreturns both.finalized(bool). Tracker:bridge_status.block_finalized(bool). Always serialized.revision, an opaque string with a hash of the address's activity (v1:+ 64 hex). It is not a counter and is not persisted: same value after a restart and on every instance that holds the same data. Clients compare it for equality only.domain.HashActivityEntryanddomain.ActivityRevision(order-independent accumulator withAdd/Remove), so every store produces the same value.api_revision6 -> 7.claim_statusinto a closed set must acceptclaimed_finalized. Covered by theapi_revisionbump. The new fields are additive.🔌 API Updates
🔌 Proxy API
GET /tracker/v1/activity/from/{from_address}(revision,finalizedper item, newclaim_statusvalue) and the tracker endpoints (bridge_status.block_finalized, newclaim_statusvalue).api_revision7. With this PR alone the new fields carry their empty values (false, the empty-activity revision) andclaimed_finalizedis never produced.✅ Testing
CurrentAPIRevision, its history and the sample inAPI.mdin sync.🐞 Issues
ETag/304is not implemented)🔗 Related PRs
📝 Notes
global_index, the bridge'stx_hashandblock_num,claim_status(withclaimed_finalizedcounted asclaimed) and the claim'stx_hash. Not hashed: the finality flag, timestamps, warnings and errors, the tracker's current step. So the revision does not change when an entry only goes from not final to final.🤖 Generated with Claude Code