Repository navigation
feat(aggkit): support tracker api_revision 7 (claimed_finalized, finalized, revision) - #47
Draft
joanestebanr wants to merge 4 commits into
Draft
joanestebanr wants to merge 4 commits into
joanestebanr wants to merge 4 commits into
Conversation
…lized, revision) The aggkit-proxy tracker API goes to api_revision 7 to follow reorgs (agglayer/aggkit#1980, #1981, #1982). Make the aggkit types, client and docs follow it, staying compatible with a tracker at api_revision 6. - AggkitClaimStatus gains 'claimed_finalized', the only final state. 'claimed' can now go back to 'readyToClaim' or 'pending' after a reorg. - New optional fields (a tracker at api_revision 6 does not send them): AggkitActivityItem.finalized, AggkitActivityResult.revision and AggkitBridgeStatus.block_finalized. - getActivity passes `revision` through; it used to build its result from bridges/count/warnings only, so the field would have been dropped. - New exported helper isAggkitClaimedStatus(status), true for 'claimed' and 'claimed_finalized'. - AggkitActivityFilter keeps its five values: 'claimed_finalized' is a status but not a filterBridges value ('claimed' returns both). - Docs: claim_status states, getBridgeTracking terminal semantics ('finished' only once the claim is final, trackings can move backwards), getActivity pagination with `revision`, and creation_timestamp changing after a reorg. Refs #46 Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
- Accept 'claimed_finalized' as a known claim_status and use isAggkitClaimedStatus for the known-claimed deposits, which read 'claimed_finalized' once their claim is final. - New section 3a: when the tracker sends `revision`, check its format, that every row carries a boolean `finalized` consistent with its claim_status, and that the cheap pageSize=1 poll carries `revision` too. Against a tracker at api_revision 6 it checks the fields are absent instead. Refs #46 Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Refs #46 Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Contributor
Author
|
@codex review |
Bring the aggkit sections of the README in line with the JSDoc:
- Cross-Network Activity: `revision` in the example, the claimed filter via
isAggkitClaimedStatus, and a "Reorgs and finality" subsection covering
'claimed_finalized' ('claimed' is no longer final), `finalized`,
`creation_timestamp` changing after a reorg and the `revision` flow for
detecting stale pages. All of it is optional and only sent by a tracker at
api_revision 7.
- Bridge Transaction Tracking: 'finished' means claimed and final since
api_revision 7, trackings can move backwards, `block_finalized`.
- The claim_status vocabulary lists 'claimed_finalized'.
Refs #46
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This was referenced 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.
Context
aggkit-proxyis getting reorg support (agglayer/pm#445) and its tracker API goes toapi_revision7 (agglayer/aggkit#1980, with the behaviour in agglayer/aggkit#1981 and agglayer/aggkit#1982). This PR makes the SDK's aggkit types, client and docs (src/aggkit/) follow it.It is backwards compatible with a tracker at
api_revision6: no new value or field is required, so it can (and has to) be released before a proxy atapi_revision7 reaches any environment. A client that does not knowclaimed_finalizedtreats a claimed and final bridge as an unknown status.Changes
Types and API (all additive):
AggkitClaimStatusgains'claimed_finalized': the claim's block is final and the status never changes again. It is the only final state;'claimed'can now go back to'readyToClaim'or'pending'if a reorg removes the claim.api_revision7" (a tracker atapi_revision6 does not send them, andundefinedmeans "unknown", notfalse):AggkitActivityItem.finalized?: booleanAggkitActivityResult.revision?: stringAggkitBridgeStatus.block_finalized?: booleanisAggkitClaimedStatus(status): true for'claimed'and'claimed_finalized'(a type guard; acceptsnull/undefined). Exported fromsrc/aggkitand from the package root. Use it instead of comparing with'claimed'.AggkitBridgeClient.getActivity(and the aggregator's passthrough) now returnsrevision. The client builds its result frombridges/count/warnings, so without this the field was dropped. The key is left out when the tracker does not send it.AggkitActivityFilterkeeps its five values ('all' | 'pending' | 'readyToClaim' | 'claimed' | 'error'). It was defined as'all' | AggkitClaimStatus, which would have started accepting'claimed_finalized'; the tracker answers400to that value (filterBridges=claimedreturns both claimed states).Docs (JSDoc):
claim_status: the new value and'claimed'no longer being final.getBridgeTrackingterminal semantics:tracking_statusreads'finished'only once the claim is final; with the claim done but not final it stays'running', and a tracking can move backwards.getActivitypagination: userevision(poll it withpageSize: 1, reload the loaded pages when it changes, check it again after the last page) instead of watchingcountand page 1;countremains the fallback forapi_revision6.creation_timestampcan change if a reorg moves the bridge to another block;last_updated_timestampdoes not signal a change.api_revision7)" section in the module doc ofsrc/aggkit/index.ts.README.md(aggkit sections only): the activity example showsrevisionand the helper, a new "Reorgs and finality (trackerapi_revision7)" subsection coversclaimed_finalized,finalized,creation_timestampand therevisionflow, and the tracking section explains the new meaning offinished. It states that all of it is optional and only sent byapi_revision7.Other:
scripts/aggkit-smoke.ts: acceptsclaimed_finalized, uses the helper for the known-claimed deposits, and has a new section that checksrevision/finalizedwhen the tracker sends them (and their absence otherwise).1.0.0-beta.34(separate commit).Testing
Run locally with node v24.19.0 and pnpm 10.30.3, on the head of this branch:
pnpm install --frozen-lockfile: okpnpm run typecheck: okpnpm run lint: 0 errors (51no-consolewarnings inscripts/aggkit-smoke.ts, the same kind as before this PR)pnpm run format:check: okpnpm run test:run: 239 passed in 7 filespnpm run build: ok;isAggkitClaimedStatusis in the CJS, ESM and.d.tsbundlesNew tests:
claimStatus.test.ts: the helper for every status,null/undefined, the type guard, both export paths, and type-level checks of the new value and the optional fields (expectTypeOf).activity.test.ts:revisionpassed through, the same for any page and filter, absent for anapi_revision6 body;claimed_finalizedandfinalizedsurfaced;finalizedleftundefinedfor anapi_revision6 row.tracker.test.ts: claimed but not final (running,block_finalized: false),finishedwithclaimed_finalized, and noblock_finalizedin the existingapi_revision6 capture.Not tested:
scripts/aggkit-smoke.tswas only type-checked and linted, not run: it needs a live devnet, and no proxy atapi_revision7 is deployed yet.api_revision7 response. The new test bodies are synthetic, built from the API document of feat: proxy: API contract for finality, claimed_finalized and activity revision (#1971) aggkit#1980 and #1982; the existing captures act as theapi_revision6 case.pnpm run typecheckexcludes (tsconfig.json). I compiled them once with an ad hoctscconfig; CI does not.Notes
api_revisionfor the new value and fields: 7.tracking_statusonly readsfinishedonce the claim is final.finalized = trueand goes back tofalsewhen it is claimed, until the claim is final.Closes #46
🤖 Generated with Claude Code