Skip to content

feat: proxy: API contract for finality, claimed_finalized and activity revision (#1971) - #1980

Merged
joanestebanr merged 4 commits into
developfrom
feat/1971-proxy-api-contract
Nov 17, 2026
Merged

joanestebanr merged 4 commits into
developfrom
feat/1971-proxy-api-contract

Conversation

@joanestebanr

Copy link
Copy Markdown
Collaborator

🔄 Changes Summary

Contract only (types, wire format, docs); the values are populated by the follow-up PRs.

  • claim_status gets the value claimed_finalized, the only final state. claimed can still go back to readyToClaim or pending after a reorg. filterBridges=claimed returns both.
  • Activity item: finalized (bool). Tracker: bridge_status.block_finalized (bool). Always serialized.
  • Activity response: 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.HashActivityEntry and domain.ActivityRevision (order-independent accumulator with Add / Remove), so every store produces the same value.
  • api_revision 6 -> 7.

⚠️ Breaking Changes

  • 🔌 API/CLI: clients that decode claim_status into a closed set must accept claimed_finalized. Covered by the api_revision bump. The new fields are additive.

🔌 API Updates

🔌 Proxy API

  • 🔌 AProxy API Update: GET /tracker/v1/activity/from/{from_address} (revision, finalized per item, new claim_status value) and the tracker endpoints (bridge_status.block_finalized, new claim_status value). api_revision 7. With this PR alone the new fields carry their empty values (false, the empty-activity revision) and claimed_finalized is never produced.

✅ Testing

  • 🤖 Automatic: unit tests for the JSON of the new fields and status, the revision hash (golden value, determinism, order independence, add-then-remove, which fields change it and which do not), and a test that keeps CurrentAPIRevision, its history and the sample in API.md in sync.

🐞 Issues

🔗 Related PRs

  • Populated by the activity and tracker PRs of the same series.

📝 Notes

  • What is hashed per bridge: global_index, the bridge's tx_hash and block_num, claim_status (with claimed_finalized counted as claimed) and the claim's tx_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.
  • Per-entry hashes are combined with a sum mod 2^256 rather than XOR, so two equal hashes do not cancel out.
  • Swagger regenerated keeping only the hunks of this change.

🤖 Generated with Claude Code

@joanestebanr
joanestebanr marked this pull request as ready for review November 17, 2026 12:06
@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-17T12:07:37.385900Z 525453e 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

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: 525453e182

ℹ️ 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
joanestebanr force-pushed the feat/1971-proxy-api-contract branch from 525453e to b6b429c Compare November 17, 2026 12:11
@joanestebanr
joanestebanr force-pushed the feat/1971-proxy-api-contract branch from b6b429c to 79e48cc Compare November 17, 2026 12:38
joanestebanr and others added 2 commits November 17, 2026 14:58
…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
joanestebanr force-pushed the feat/1971-proxy-api-contract branch from 79e48cc to 5e4a5b4 Compare November 17, 2026 13:59
@joanestebanr
joanestebanr merged commit c730ac3 into develop Nov 17, 2026
36 checks passed
@joanestebanr
joanestebanr deleted the feat/1971-proxy-api-contract branch November 17, 2026 19:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants