Skip to content

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

Closed

Description

@joanestebanr

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_status gets a new value, claimed_finalized: the claim's block is final and the status will not change again. It is the only final state. claimed can now go back to readyToClaim or pending if 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 changes claim_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_status only reads finished once the claim is final. With the claim done but not final it stays running, and a tracking can move backwards.
  • filterBridges=claimed returns both claimed and claimed_finalized.
  • Activity item: creation_timestamp can change if a reorg moves the bridge to another block.

Tasks

Compatible with the current proxy (do first):

  • Add 'claimed_finalized' to AggkitClaimStatus (src/aggkit/types.ts).
  • Add the optional fields to the types: finalized on AggkitActivityItem, revision on the activity result, block_finalized on the tracker's bridge status. Optional, because a proxy at api_revision 6 does not send them.
  • A helper for "is this bridge claimed?" that is true for both claimed and claimed_finalized, so consumers do not compare against 'claimed' directly.

Docs and behaviour:

  • Update the "terminal semantics" doc of getBridgeTracking (src/aggkit/client.ts): finished now means claimed and final.
  • Update the pagination doc of getActivity: use revision to know when to reload the loaded pages, instead of watching count and page 1.
  • Update scripts/aggkit-smoke.ts and the tests/fixtures.
  • Release a new version and note the minimum proxy api_revision for the new fields.

Acceptance criteria

  • Works unchanged against a proxy at api_revision 6.
  • Against a proxy at api_revision 7, claimed_finalized is typed and the new fields are exposed.

Part of agglayer/pm#445.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions