Repository navigation
Closed
Labels
enhancementNew feature or requestNew feature or request
Description
Context
aggkit-proxy is getting reorg support (agglayer/pm#445). The tracker API goes to api_revision 7 (agglayer/aggkit#1980, with the behaviour in agglayer/aggkit#1981 and agglayer/aggkit#1982). The SDK's aggkit types and docs (src/aggkit/) need to follow.
The first part below is backwards compatible with the current proxy (api_revision 6) and must be released before a proxy with api_revision 7 reaches any environment: a client that does not know claimed_finalized treats a claimed and final bridge as an unknown status.
What changes in the API
claim_statusgets a new value,claimed_finalized: the claim's block is final and the status will not change again. It is the only final state.claimedcan now go back toreadyToClaimorpendingif a reorg removes the claim.- Activity item: new
finalized(boolean, always present). - Activity response: new
revision, an opaque string with a hash of the address's activity (v1:+ 64 hex). It changes when a bridge is added, removed, corrected after a reorg, or changesclaim_status; it does not change when an item only becomes final. Compare for equality only. - Tracker: new
bridge_status.block_finalized(boolean, always present). - Tracker:
tracking_statusonly readsfinishedonce the claim is final. With the claim done but not final it staysrunning, and a tracking can move backwards. filterBridges=claimedreturns bothclaimedandclaimed_finalized.- Activity item:
creation_timestampcan change if a reorg moves the bridge to another block.
Tasks
Compatible with the current proxy (do first):
- Add
'claimed_finalized'toAggkitClaimStatus(src/aggkit/types.ts). - Add the optional fields to the types:
finalizedonAggkitActivityItem,revisionon the activity result,block_finalizedon the tracker's bridge status. Optional, because a proxy atapi_revision6 does not send them. - A helper for "is this bridge claimed?" that is true for both
claimedandclaimed_finalized, so consumers do not compare against'claimed'directly.
Docs and behaviour:
- Update the "terminal semantics" doc of
getBridgeTracking(src/aggkit/client.ts):finishednow means claimed and final. - Update the pagination doc of
getActivity: userevisionto know when to reload the loaded pages, instead of watchingcountand page 1. - Update
scripts/aggkit-smoke.tsand the tests/fixtures. - Release a new version and note the minimum proxy
api_revisionfor the new fields.
Acceptance criteria
- Works unchanged against a proxy at
api_revision6. - Against a proxy at
api_revision7,claimed_finalizedis typed and the new fields are exposed.
Part of agglayer/pm#445.
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity
docs(aggkit): document tracker api_revision 7 in the README