Skip to content

feat(aggkit): support tracker api_revision 7 (claimed_finalized, finalized, revision) - #47

Draft
joanestebanr wants to merge 4 commits into
mainfrom
feat/46-aggkit-api-revision-7
Draft

joanestebanr wants to merge 4 commits into
mainfrom
feat/46-aggkit-api-revision-7

Conversation

@joanestebanr

@joanestebanr joanestebanr commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Context

aggkit-proxy is getting reorg support (agglayer/pm#445) and its tracker API goes to api_revision 7 (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_revision 6: no new value or field is required, so it can (and has to) be released before a proxy at api_revision 7 reaches any environment. A client that does not know claimed_finalized treats a claimed and final bridge as an unknown status.

Changes

Types and API (all additive):

  • AggkitClaimStatus gains '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.
  • New optional fields, documented as "since tracker api_revision 7" (a tracker at api_revision 6 does not send them, and undefined means "unknown", not false):
    • AggkitActivityItem.finalized?: boolean
    • AggkitActivityResult.revision?: string
    • AggkitBridgeStatus.block_finalized?: boolean
  • New exported helper isAggkitClaimedStatus(status): true for 'claimed' and 'claimed_finalized' (a type guard; accepts null/undefined). Exported from src/aggkit and from the package root. Use it instead of comparing with 'claimed'.
  • AggkitBridgeClient.getActivity (and the aggregator's passthrough) now returns revision. The client builds its result from bridges/count/warnings, so without this the field was dropped. The key is left out when the tracker does not send it.
  • AggkitActivityFilter keeps its five values ('all' | 'pending' | 'readyToClaim' | 'claimed' | 'error'). It was defined as 'all' | AggkitClaimStatus, which would have started accepting 'claimed_finalized'; the tracker answers 400 to that value (filterBridges=claimed returns both claimed states).

Docs (JSDoc):

  • claim_status: the new value and 'claimed' no longer being final.
  • getBridgeTracking terminal semantics: tracking_status reads 'finished' only once the claim is final; with the claim done but not final it stays 'running', and a tracking can move backwards.
  • getActivity pagination: use revision (poll it with pageSize: 1, reload the loaded pages when it changes, check it again after the last page) instead of watching count and page 1; count remains the fallback for api_revision 6.
  • creation_timestamp can change if a reorg moves the bridge to another block; last_updated_timestamp does not signal a change.
  • New "Reorgs and Finality (tracker api_revision 7)" section in the module doc of src/aggkit/index.ts.
  • README.md (aggkit sections only): the activity example shows revision and the helper, a new "Reorgs and finality (tracker api_revision 7)" subsection covers claimed_finalized, finalized, creation_timestamp and the revision flow, and the tracking section explains the new meaning of finished. It states that all of it is optional and only sent by api_revision 7.

Other:

  • scripts/aggkit-smoke.ts: accepts claimed_finalized, uses the helper for the known-claimed deposits, and has a new section that checks revision/finalized when the tracker sends them (and their absence otherwise).
  • Version bump to 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: ok
  • pnpm run typecheck: ok
  • pnpm run lint: 0 errors (51 no-console warnings in scripts/aggkit-smoke.ts, the same kind as before this PR)
  • pnpm run format:check: ok
  • pnpm run test:run: 239 passed in 7 files
  • pnpm run build: ok; isAggkitClaimedStatus is in the CJS, ESM and .d.ts bundles

New 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: revision passed through, the same for any page and filter, absent for an api_revision 6 body; claimed_finalized and finalized surfaced; finalized left undefined for an api_revision 6 row.
  • tracker.test.ts: claimed but not final (running, block_finalized: false), finished with claimed_finalized, and no block_finalized in the existing api_revision 6 capture.

Not tested:

  • scripts/aggkit-smoke.ts was only type-checked and linted, not run: it needs a live devnet, and no proxy at api_revision 7 is deployed yet.
  • There is no live capture of an api_revision 7 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 the api_revision 6 case.
  • The type-level assertions live in test files, which pnpm run typecheck excludes (tsconfig.json). I compiled them once with an ad hoc tsc config; CI does not.

Notes

Closes #46

🤖 Generated with Claude Code

joanestebanr and others added 3 commits November 17, 2026 17:44
…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>
@joanestebanr

Copy link
Copy Markdown
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>
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.

feat: aggkit: support tracker api_revision 7 (claimed_finalized, finalized, revision)

1 participant