From 76cfcc91ab366a5e7be6668dba891d21faa71252 Mon Sep 17 00:00:00 2001 From: jesteban <129153821+joanestebanr@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:44:11 +0100 Subject: [PATCH 1/4] feat(aggkit): support tracker api_revision 7 (claimed_finalized, finalized, 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 --- src/aggkit/__tests__/activity.test.ts | 100 ++++++++++++++ src/aggkit/__tests__/claimStatus.test.ts | 118 +++++++++++++++++ src/aggkit/__tests__/tracker.test.ts | 68 ++++++++++ src/aggkit/aggregator.ts | 10 +- src/aggkit/claimStatus.ts | 27 ++++ src/aggkit/client.ts | 55 ++++++-- src/aggkit/index.ts | 32 ++++- src/aggkit/types.ts | 159 +++++++++++++++++++++-- src/index.ts | 1 + 9 files changed, 547 insertions(+), 23 deletions(-) create mode 100644 src/aggkit/__tests__/claimStatus.test.ts create mode 100644 src/aggkit/claimStatus.ts diff --git a/src/aggkit/__tests__/activity.test.ts b/src/aggkit/__tests__/activity.test.ts index 6b95d7b..4cc8534 100644 --- a/src/aggkit/__tests__/activity.test.ts +++ b/src/aggkit/__tests__/activity.test.ts @@ -4,6 +4,7 @@ import { AggkitBridgeClient } from '../client'; import { AggkitBridgeAggregator } from '../aggregator'; import { AggkitApiError } from '../errors'; import { quoteGlobalIndex } from '../parsing'; +import { isAggkitClaimedStatus } from '../claimStatus'; import type { AggkitActivityItem } from '../types'; // --------------------------------------------------------------------------- @@ -323,6 +324,105 @@ describe('AggkitBridgeClient.getActivity', () => { expect(result.warnings).toEqual([]); }); + describe('tracker api_revision 7 (agglayer/sdk#46)', () => { + const REVISION = + 'v1:1ab162228afe25b74655b2bfb280cae4926372f5ac13646f341a30053c4a92f1'; + + it('passes `revision` through untouched', async () => { + mockFetchOnce( + activityBody([makeActivityItem()], { count: 1, revision: REVISION }), + 200 + ); + const result = await client.getActivity({ fromAddress: ADDRESS }); + expect(result.revision).toBe(REVISION); + }); + + it('returns the same `revision` whatever the page and filter requested', async () => { + mockFetchAlways( + activityBody([makeActivityItem()], { count: 7, revision: REVISION }), + 200 + ); + const cheapPoll = await client.getActivity({ + fromAddress: ADDRESS, + pageSize: 1, + }); + const page2 = await client.getActivity({ + fromAddress: ADDRESS, + filterBridges: 'claimed', + pageNumber: 2, + pageSize: 5, + }); + expect(cheapPoll.revision).toBe(REVISION); + expect(page2.revision).toBe(REVISION); + }); + + it('leaves `revision` out (no key) for a tracker at api_revision 6', async () => { + mockFetchOnce(activityBody([makeActivityItem()], { count: 1 }), 200); + const result = await client.getActivity({ fromAddress: ADDRESS }); + expect(result).not.toHaveProperty('revision'); + expect(result.revision).toBeUndefined(); + expect(result.count).toBe(1); + }); + + it('ignores a `revision` that is not a string', async () => { + mockFetchOnce( + activityBody([makeActivityItem()], { count: 1, revision: 7 }), + 200 + ); + const result = await client.getActivity({ fromAddress: ADDRESS }); + expect(result).not.toHaveProperty('revision'); + }); + + it('surfaces claim_status "claimed_finalized" with finalized: true', async () => { + const item = makeActivityItem({ + claim_status: 'claimed_finalized', + finalized: true, + }); + mockFetchOnce(activityBody([item], { revision: REVISION }), 200); + const result = await client.getActivity({ fromAddress: ADDRESS }); + expect(result.bridges[0]?.claim_status).toBe('claimed_finalized'); + expect(result.bridges[0]?.finalized).toBe(true); + }); + + it('keeps a claimed-but-not-final row apart: "claimed" with finalized: false', async () => { + const notFinal = makeActivityItem({ + claim_status: 'claimed', + finalized: false, + }); + const final = makeActivityItem({ + claim_status: 'claimed_finalized', + finalized: true, + }); + mockFetchOnce(activityBody([notFinal, final]), 200); + const result = await client.getActivity({ + fromAddress: ADDRESS, + filterBridges: 'claimed', + }); + // `filterBridges=claimed` returns both states at api_revision 7, and + // the helper treats both as claimed. + expect(result.bridges.map((b) => b.claim_status)).toEqual([ + 'claimed', + 'claimed_finalized', + ]); + expect( + result.bridges.every((b) => isAggkitClaimedStatus(b.claim_status)) + ).toBe(true); + expect(result.bridges.map((b) => b.finalized)).toEqual([false, true]); + }); + + it('leaves `finalized` undefined (not false) on a row from a tracker at api_revision 6', async () => { + mockFetchOnce( + activityBody([makeActivityItem({ claim_status: 'claimed' })]), + 200 + ); + const result = await client.getActivity({ fromAddress: ADDRESS }); + expect(result.bridges[0]).not.toHaveProperty('finalized'); + expect(isAggkitClaimedStatus(result.bridges[0]?.claim_status)).toBe( + true + ); + }); + }); + it('preserves claim_status and an optional joined claim/tracking', async () => { const claimedItem = makeActivityItem({ claim_status: 'claimed', diff --git a/src/aggkit/__tests__/claimStatus.test.ts b/src/aggkit/__tests__/claimStatus.test.ts new file mode 100644 index 0000000..e8429cc --- /dev/null +++ b/src/aggkit/__tests__/claimStatus.test.ts @@ -0,0 +1,118 @@ +import { describe, it, expect, expectTypeOf } from 'vitest'; +import { isAggkitClaimedStatus } from '../claimStatus'; +import { isAggkitClaimedStatus as fromModuleIndex } from '../index'; +import { isAggkitClaimedStatus as fromSdkRoot } from '../../index'; +import type { + AggkitActivityFilter, + AggkitActivityItem, + AggkitActivityResult, + AggkitBridgeStatus, + AggkitClaimStatus, +} from '../types'; + +// --------------------------------------------------------------------------- +// Tracker api_revision 7 (agglayer/sdk#46): the `claimed_finalized` status, +// the "is it claimed?" helper, and type-level acceptance of the new value and +// of the new OPTIONAL fields (a tracker at api_revision 6 does not send them). +// --------------------------------------------------------------------------- + +describe('isAggkitClaimedStatus', () => { + it.each(['claimed', 'claimed_finalized'] as const)( + 'is true for %s', + (status) => { + expect(isAggkitClaimedStatus(status)).toBe(true); + } + ); + + it.each(['pending', 'readyToClaim', 'error'] as const)( + 'is false for %s', + (status) => { + expect(isAggkitClaimedStatus(status)).toBe(false); + } + ); + + it('is false for a missing status (e.g. no `tracking` on the row)', () => { + expect(isAggkitClaimedStatus(undefined)).toBe(false); + expect(isAggkitClaimedStatus(null)).toBe(false); + }); + + it('is false for a value this SDK version does not know', () => { + // A future tracker may add states; an unknown one is not "claimed". + expect(isAggkitClaimedStatus('whatever' as AggkitClaimStatus)).toBe(false); + }); + + it('covers every AggkitClaimStatus', () => { + // Exhaustive by construction: adding a member to the union without + // deciding here whether it counts as claimed is a compile error. + const expected: Record = { + pending: false, + readyToClaim: false, + claimed: true, + claimed_finalized: true, + error: false, + }; + for (const [status, claimed] of Object.entries(expected)) { + expect(isAggkitClaimedStatus(status as AggkitClaimStatus)).toBe(claimed); + } + }); + + it('narrows the status to the two claimed values', () => { + const status = 'claimed_finalized' as AggkitClaimStatus; + if (isAggkitClaimedStatus(status)) { + expectTypeOf(status).toEqualTypeOf<'claimed' | 'claimed_finalized'>(); + } else { + expectTypeOf(status).toEqualTypeOf< + 'pending' | 'readyToClaim' | 'error' + >(); + } + }); + + it('is exported from the aggkit module and from the SDK root', () => { + expect(fromModuleIndex).toBe(isAggkitClaimedStatus); + expect(fromSdkRoot).toBe(isAggkitClaimedStatus); + }); +}); + +describe('tracker api_revision 7 types', () => { + it('AggkitClaimStatus accepts claimed_finalized', () => { + expectTypeOf<'claimed_finalized'>().toMatchTypeOf(); + expectTypeOf().toEqualTypeOf< + 'pending' | 'readyToClaim' | 'claimed' | 'claimed_finalized' | 'error' + >(); + }); + + it('AggkitActivityFilter keeps the five server-side values (claimed_finalized is not a filter)', () => { + expectTypeOf().toEqualTypeOf< + 'all' | 'pending' | 'readyToClaim' | 'claimed' | 'error' + >(); + }); + + it('the new fields are optional, with the wire types', () => { + expectTypeOf().toEqualTypeOf< + boolean | undefined + >(); + expectTypeOf().toEqualTypeOf< + string | undefined + >(); + expectTypeOf().toEqualTypeOf< + boolean | undefined + >(); + }); + + it('accepts both an api_revision 6 and an api_revision 7 shaped value', () => { + // api_revision 6: none of the new fields. + const rev6: Pick & { + bridges: []; + } = { bridges: [], count: 0, warnings: [] }; + expectTypeOf(rev6).toMatchTypeOf(); + + // api_revision 7: all of them. + const rev7 = { + bridges: [], + count: 0, + revision: `v1:${'0'.repeat(64)}`, + warnings: [], + } satisfies AggkitActivityResult; + expect(rev7.revision).toMatch(/^v1:[0-9a-f]{64}$/); + }); +}); diff --git a/src/aggkit/__tests__/tracker.test.ts b/src/aggkit/__tests__/tracker.test.ts index 4168d4a..1d0265b 100644 --- a/src/aggkit/__tests__/tracker.test.ts +++ b/src/aggkit/__tests__/tracker.test.ts @@ -3,6 +3,7 @@ import { describe, it, expect, beforeEach, vi, type Mock } from 'vitest'; import { AggkitBridgeClient } from '../client'; import { AggkitBridgeAggregator } from '../aggregator'; import { AggkitApiError } from '../errors'; +import { isAggkitClaimedStatus } from '../claimStatus'; import type { AggkitTrackingData } from '../types'; // --------------------------------------------------------------------------- @@ -401,6 +402,73 @@ describe('AggkitBridgeClient.getBridgeTracking', () => { }); }); + describe('tracker api_revision 7: finality (agglayer/sdk#46)', () => { + // No live capture of an api_revision 7 tracker exists yet, so these + // bodies are the rc4 `finished` capture with the api_revision 7 fields + // set on top, as agglayer/aggkit's docs/bridgetracker/API.md describes + // them. + function trackingBody( + overrides: Partial, + blockFinalized: boolean + ): string { + const base = JSON.parse( + loadFixture('tracker_l1l2_finished.json') + ) as AggkitTrackingData; + return JSON.stringify({ + ...base, + ...overrides, + bridge_status: base.bridge_status && { + ...base.bridge_status, + block_finalized: blockFinalized, + }, + }); + } + + it('a claimed but not final bridge is still `running`, at the `Claimed` step', async () => { + mockFetchOnce( + trackingBody( + { tracking_status: 'running', claim_status: 'claimed' }, + false + ), + 200 + ); + const data = await client.getBridgeTracking('0xabc'); + + expect(data.tracking_status).toBe('running'); + expect(data.claim_status).toBe('claimed'); + expect(isAggkitClaimedStatus(data.claim_status)).toBe(true); + expect(data.bridge_status?.block_finalized).toBe(false); + expect(data.all_steps?.[data.step_index ?? -1]?.step_name).toBe( + 'Claimed' + ); + }); + + it('`finished` comes with claim_status "claimed_finalized" and block_finalized: true', async () => { + mockFetchOnce( + trackingBody( + { tracking_status: 'finished', claim_status: 'claimed_finalized' }, + true + ), + 200 + ); + const data = await client.getBridgeTracking('0xabc'); + + expect(data.tracking_status).toBe('finished'); + expect(data.claim_status).toBe('claimed_finalized'); + expect(isAggkitClaimedStatus(data.claim_status)).toBe(true); + expect(data.bridge_status?.block_finalized).toBe(true); + }); + + it('a tracker at api_revision 6 sends no `block_finalized` (undefined, not false)', async () => { + mockFetchOnce(loadFixture('tracker_l1l2_finished.json'), 200); + const data = await client.getBridgeTracking('0xabc'); + + expect(data.tracking_status).toBe('finished'); + expect(data.bridge_status).not.toBeNull(); + expect(data.bridge_status).not.toHaveProperty('block_finalized'); + }); + }); + describe('400 ErrorData (tracker error shape, not the bridge-service {"error"} shape)', () => { it('throws AggkitApiError with the {code,message} body parsed as the error message', async () => { mockFetchOnce(loadFixture('tracker_error_400.json'), 400); diff --git a/src/aggkit/aggregator.ts b/src/aggkit/aggregator.ts index e9cc153..48e9354 100644 --- a/src/aggkit/aggregator.ts +++ b/src/aggkit/aggregator.ts @@ -216,13 +216,19 @@ export class AggkitBridgeAggregator { * `AggkitActivityResult` in `types.ts` for the full rationale and the * resulting contract differences (server-side pagination with `count`, `warnings` instead of * `failedNetworks`, a `claim_status: AggkitClaimStatus` — `'pending'` / - * `'readyToClaim'` / `'claimed'` / `'error'`, agglayer/aggkit#1830, PR #1831 - * — plus optional `tracking` instead of the old + * `'readyToClaim'` / `'claimed'` / `'claimed_finalized'` / `'error'`, + * agglayer/aggkit#1830, PR #1831; `'claimed_finalized'` since tracker + * `api_revision` 7 — plus optional `tracking` instead of the old * BRIDGED/LEAF_INCLUDED/READY_TO_CLAIM/CLAIMED derivation). The former * ready-to-claim badge (`getReadyToClaimCount`, REMOVED) is now a * consumer-side derivation over this same result — filter * `claim_status === 'readyToClaim'`, exactly as this result's `bridges` * already has to be interpreted for status display. + * + * Since tracker `api_revision` 7 the result also carries `revision` (when + * to reload the loaded pages) and each row `finalized`; a row is claimed + * when `isAggkitClaimedStatus(claim_status)`, not only when it reads + * `'claimed'`. See `AggkitBridgeClient.getActivity`. */ async getActivity(params: { fromAddress: string; diff --git a/src/aggkit/claimStatus.ts b/src/aggkit/claimStatus.ts new file mode 100644 index 0000000..fe07860 --- /dev/null +++ b/src/aggkit/claimStatus.ts @@ -0,0 +1,27 @@ +/** + * Helpers over `AggkitClaimStatus` (`claim_status` of the bridge tracker's + * activity rows and tracking data). + */ + +import type { AggkitClaimStatus } from './types'; + +/** + * "Is this bridge claimed?" — `true` for both `'claimed'` (claimed, but the + * claim's block can still be removed by a reorg) and `'claimed_finalized'` + * (claimed and final, since tracker `api_revision` 7). + * + * Use it instead of comparing with `'claimed'`: against a tracker at + * `api_revision` 7 a `claim_status === 'claimed'` check stops matching a + * bridge as soon as its claim becomes final. Against a tracker at + * `api_revision` 6, which only ever sends `'claimed'`, it behaves exactly + * like that comparison. + * + * It does not say whether the claim is final: for that, compare with + * `'claimed_finalized'`. `null`/`undefined` (e.g. the `claim_status` of an + * absent `tracking`) are accepted and return `false`. + */ +export function isAggkitClaimedStatus( + status: AggkitClaimStatus | null | undefined +): status is 'claimed' | 'claimed_finalized' { + return status === 'claimed' || status === 'claimed_finalized'; +} diff --git a/src/aggkit/client.ts b/src/aggkit/client.ts index 4159198..76fc12f 100644 --- a/src/aggkit/client.ts +++ b/src/aggkit/client.ts @@ -670,8 +670,10 @@ export class AggkitBridgeClient { * instance's own `this.networkId` implicitly. * * **Terminal semantics** — stop polling once EITHER is true: - * - `tracking_status === 'finished'` (the bridge reached its last step, - * `Claimed`). + * - `tracking_status === 'finished'`: the bridge reached its last step, + * `Claimed`, and — since tracker `api_revision` 7 — the claim's block is + * final (`claim_status === 'claimed_finalized'`). At `api_revision` 6 + * `'finished'` is reported as soon as the claim is seen. * - `tracking_status === 'error'` AND `bridge_status === null` — the * tracker gave up ever resolving the bridge at all (tx not found, or not * a bridge tx). This is distinct from a per-step error inside @@ -682,6 +684,18 @@ export class AggkitBridgeClient { * `bridge_status` populated — which is exactly why the terminal check * must include `bridge_status === null`, not `tracking_status` alone. * + * **Claimed is not terminal** (since tracker `api_revision` 7): with the + * claim done but its block not final yet, the response reads + * `tracking_status: 'running'` with `claim_status: 'claimed'` and + * `step_index` at `Claimed`. Keep polling: a reorg can remove the claim + * and move the tracking BACKWARDS, to `'readyToClaim'` or `'pending'` and + * an earlier step, so do not assume `step_index` or `claim_status` only + * move forward. A UI that just wants to show "claimed" can do so as soon + * as `isAggkitClaimedStatus(claim_status)` is true, and treat it as + * settled once `tracking_status === 'finished'`. + * `bridge_status.block_finalized` (also `api_revision` 7) says whether the + * origin bridge block itself is final. + * * **Polling guidance**: the tracker has no push/subscription channel, only * this REST lookup, so callers must poll. ~5s between calls is a good * default (matches this SDK's own dev-ui consumer) — stop as soon as the @@ -702,9 +716,10 @@ export class AggkitBridgeClient { * original registration, not as a regression to be surfaced to the user. * * **Claim readiness**: `claim_status` (agglayer/aggkit#1823, PR #1829) - * gives `'readyToClaim'`/`'claimed'`/`'error'`/`'pending'` directly — - * prefer it over inspecting `step_index`/`all_steps` by hand to decide - * whether to show a claim button. See `AggkitClaimStatus` in `types.ts`. + * gives `'readyToClaim'`/`'claimed'`/`'claimed_finalized'`/`'error'`/ + * `'pending'` directly — prefer it over inspecting `step_index`/ + * `all_steps` by hand to decide whether to show a claim button. See + * `AggkitClaimStatus` in `types.ts`. */ async getBridgeTracking( txHash: string, @@ -750,13 +765,32 @@ export class AggkitBridgeClient { * `filterBridges` (`'all'` | `'claimed'` | `'pending'` | `'readyToClaim'` | * `'error'`, i.e. `AggkitActivityFilter`) restricts `bridges` to that * `claim_status` server-side. When omitted the parameter is not sent and - * the tracker applies its own default. + * the tracker applies its own default. Since tracker `api_revision` 7, + * `'claimed'` returns both the `'claimed'` and the `'claimed_finalized'` + * rows; `'claimed_finalized'` itself is not a filter value. * * `pageNumber` (1-based, tracker default `1`) and `pageSize` (tracker * default `20`, max `200`) page the result, newest bridge first. `count` * in the result is the total matching `filterBridges` across every page, - * so there are `Math.ceil(count / pageSize)` pages. Pages are not a - * consistent snapshot: see `AggkitActivityResult.count`. + * so there are `Math.ceil(count / pageSize)` pages. + * + * Pages are not a consistent snapshot, and a loaded page can go stale: a + * new bridge shifts the older ones down, and since tracker `api_revision` + * 7 a reorg can remove a row, move it (its `creation_timestamp`, the sort + * key, can change) or take its `claim_status` back. Use `revision` in the + * result (tracker `api_revision` 7; see `AggkitActivityResult.revision`) + * to know when to reload, instead of watching `count` and page 1: + * 1. Load the pages you need and keep the `revision` of the first one. + * 2. Poll cheaply with `pageSize: 1` and compare its `revision` (equality + * only — it is an opaque hash, not a counter). + * 3. If it differs, reload the pages you had loaded. + * 4. After the last page of a traversal, compare again and restart from + * page 1 if it changed meanwhile. Always deduplicate by + * `bridge.global_index`. + * `revision` does not change when a row only becomes final + * (`'claimed'` -> `'claimed_finalized'`, `finalized` -> `true`): reload a + * page to see that. Against a tracker at `api_revision` 6 `revision` is + * `undefined`; fall back to `count` (see `AggkitActivityResult.count`). * * See `AggkitActivityResult`'s module doc in `types.ts` for the full * contract and the trade-offs versus the older `/bridge/v1` client-side @@ -813,9 +847,14 @@ export class AggkitBridgeClient { // pagination (e.g. rc9): it omits `count` AND ignores `page_*`, returning // the whole history, so `bridges.length` is then the exact total. Current // trackers always send `count` alongside a page. + // + // `revision` is sent since tracker api_revision 7. It is passed through + // untouched (it is opaque) and the key is left out, not set to + // `undefined`, when an older tracker does not send it. return { bridges: raw.bridges, count: raw.count ?? raw.bridges.length, + ...(typeof raw.revision === 'string' ? { revision: raw.revision } : {}), warnings: raw.warnings ?? [], }; } diff --git a/src/aggkit/index.ts b/src/aggkit/index.ts index 48d5a01..793f025 100644 --- a/src/aggkit/index.ts +++ b/src/aggkit/index.ts @@ -43,7 +43,9 @@ * — a single request that fans out server-side across every configured * bridge service and returns one unified, deduped, already-claim-checked * list for an address, paginated server-side (`pageNumber`/`pageSize`, total - * in `count`) and filterable by status (`filterBridges`). There is no + * in `count`) and filterable by status (`filterBridges`). Since tracker + * `api_revision` 7 the result carries `revision`, an opaque hash that tells + * a client when the pages it loaded went stale. There is no * `getReadyToClaimCount` — derive a ready-to-claim * count client-side by filtering `claim_status === 'readyToClaim'` * (`AggkitActivityItem.claim_status`, agglayer/aggkit#1830, PR #1831). See @@ -65,6 +67,33 @@ * convention), and steps carry `step_name`, not `step`. rc4's API.md * described these differently; the wire format itself never changed. * + * ## Reorgs and Finality (tracker `api_revision` 7) + * + * aggkit-proxy's tracker API `api_revision` 7 (agglayer/aggkit#1980) makes + * the tracker follow reorgs, which changes what a client may assume: + * + * - `claim_status` (`AggkitClaimStatus`) gains `'claimed_finalized'`: the + * claim's block is final and the status never changes again. It is the + * only final state. `'claimed'` is no longer terminal: a reorg that removes + * the claim takes the bridge back to `'readyToClaim'` or `'pending'`. Use + * `isAggkitClaimedStatus(status)` for "is it claimed?" — it is true for + * both — instead of comparing with `'claimed'`. + * - `AggkitActivityItem.finalized`, `AggkitActivityResult.revision` and + * `AggkitBridgeStatus.block_finalized` are new. They are OPTIONAL in the + * types: a tracker at `api_revision` 7 always sends them, one at + * `api_revision` 6 never does, and `undefined` then means "unknown". + * - `getBridgeTracking`: `tracking_status` reads `'finished'` only once the + * claim is final; until then it stays `'running'` and can move backwards. + * - `getActivity`: `filterBridges: 'claimed'` returns both claimed states, + * and an item's `creation_timestamp` can change if a reorg moves its + * bridge to another block. + * + * Everything above is backwards compatible with a tracker at `api_revision` + * 6 (no new value or field is required), so a client can adopt this SDK + * version before the tracker is upgraded. The reverse is not true: a client + * that does not know `'claimed_finalized'` treats a claimed and final bridge + * as an unknown status, so update clients first. + * * ## Claim Inputs & the Not-Ready Union * * `AggkitBridgeAggregator.getClaimInputs` returns @@ -142,6 +171,7 @@ export { AggkitBridgeClient } from './client'; export { AggkitBridgeAggregator } from './aggregator'; export { AggkitApiError } from './errors'; +export { isAggkitClaimedStatus } from './claimStatus'; export type { AggkitApiErrorArgs } from './errors'; export type { diff --git a/src/aggkit/types.ts b/src/aggkit/types.ts index 673ec17..7103116 100644 --- a/src/aggkit/types.ts +++ b/src/aggkit/types.ts @@ -459,8 +459,10 @@ export interface AggkitAggregatorConfig { * upstream bridge-service call that failed the tracker's own fan-out), * not `AggkitFailedNetwork[]`. * - Status is `claim_status: AggkitClaimStatus` (`'pending'` / - * `'readyToClaim'` / `'claimed'` / `'error'`, agglayer/aggkit#1830, PR - * [#1831](https://github.com/agglayer/aggkit/pull/1831)) — the same + * `'readyToClaim'` / `'claimed'` / `'claimed_finalized'` / `'error'`, + * agglayer/aggkit#1830, PR + * [#1831](https://github.com/agglayer/aggkit/pull/1831); + * `'claimed_finalized'` since tracker `api_revision` 7) — the same * vocabulary and field name as `AggkitTrackingData.claim_status` — plus, * with `includeTracking: true`, the same step-based `AggkitTrackingData` * `getBridgeTracking` returns for a single tx — NOT the 4-value @@ -482,6 +484,13 @@ export interface AggkitAggregatorConfig { * on `claimed !== 'true'` to find claimable bridges must switch to * `claim_status === 'readyToClaim'` (an unclaimed bridge not yet ready to * claim now reports `'pending'`, not `'false'`). + * + * Reorgs (since tracker `api_revision` 7, agglayer/aggkit#1980): rows are no + * longer write-once. Until a row is final it can be corrected, moved back to + * an earlier `claim_status`, or removed — see `AggkitClaimStatus`, + * `AggkitActivityItem.finalized` and `AggkitActivityResult.revision`. All the + * `api_revision` 7 additions are optional in these types, because a tracker + * at `api_revision` 6 does not send them. */ /** One bridge event, as reported by the bridge service the tracker fanned out to. */ @@ -571,12 +580,52 @@ export interface AggkitActivityItem { * conservatively stays `'pending'`, with the failure reported under * `errors.readiness` instead. * + * Since tracker `api_revision` 7 a claimed bridge reads `'claimed'` while + * its claim can still be removed by a reorg (it can go back to + * `'readyToClaim'` or `'pending'`) and `'claimed_finalized'` once it + * cannot. Use `isAggkitClaimedStatus` for "is this bridge claimed?" + * instead of comparing with `'claimed'` — see `AggkitClaimStatus`. + * * BREAKING (PR #1831): this field was named `claimed` and was a plain * tri-state (`'true'` / `'false'` / `'error'`) mirroring only the * destination bridge contract's `isClaimed()` call. */ claim_status: AggkitClaimStatus; + /** + * Since tracker `api_revision` 7 (always sent from then on; `undefined` + * from a tracker at `api_revision` 6, which must be read as "unknown", not + * as `false`). `true` when a reorg can no longer change this row: its + * bridge's block is final and, if it is claimed, its claim's block is + * final too — so `claim_status === 'claimed_finalized'` implies `true`. + * + * An unclaimed row whose bridge is final also reads `true`, and goes back + * to `false` when it is claimed, until the claim is final. So `true` is + * only permanent together with `claim_status === 'claimed_finalized'`. + * + * Going from `false` to `true` does not change + * `AggkitActivityResult.revision`: reload a page to see whether its rows + * became final. + */ + finalized?: boolean; + /** + * Unix seconds; when the bridge was created: its origin deposit block's + * timestamp (or, only while the bridge service has not populated that yet, + * when the tracker first cached the row). It is the sort key of + * `AggkitActivityResult.bridges`. + * + * Not immutable since tracker `api_revision` 7: it changes if a reorg moves + * the bridge to another block or transaction, which can also move the row + * to another position or page. Do not use it as (part of) a row's identity + * — use `bridge.global_index`. + */ creation_timestamp: number; + /** + * Unix seconds; when this row's claim state was last (re)checked, whether + * or not anything changed. It advances on every tracker refresh, so it + * does NOT signal a change — `AggkitActivityResult.revision` does. Since + * tracker `api_revision` 7 it stops advancing once the row reads + * `claim_status === 'claimed_finalized'`, which is never rechecked. + */ last_updated_timestamp: number; /** * Present when the last refresh had something to report; keyed by which @@ -610,7 +659,10 @@ export interface AggkitActivityWarning { /** Result of `AggkitBridgeAggregator.getActivity` / `AggkitBridgeClient.getActivity`. */ export interface AggkitActivityResult { - /** This page of bridges, newest first (`creation_timestamp` descending). */ + /** + * This page of bridges, newest first (`creation_timestamp` descending, + * ties broken by `bridge.global_index` descending). + */ bridges: AggkitActivityItem[]; /** * Total number of bridges matching `filterBridges` across EVERY page, not @@ -623,11 +675,47 @@ export interface AggkitActivityResult { * `bridges.length`, which is then the exact total. * * Pages are not a consistent snapshot: the tracker's background refresh - * can add bridges between two requests, shifting older ones down. A client - * walking every page must deduplicate by `bridge.global_index` and, if - * `count` grew meanwhile, refetch page 1 to pick up the new ones. + * can add bridges between two requests, shifting older ones down (and, + * since tracker `api_revision` 7, a reorg can remove or move them). A + * client walking every page must deduplicate by `bridge.global_index` and + * compare `revision` across the responses: if it changed, start again from + * page 1. Against a tracker that does not send `revision` (`api_revision` + * 6), fall back to refetching page 1 when `count` grew — `count` only + * changes when a bridge is added or removed, so it cannot tell that a + * loaded row changed state. */ count: number; + /** + * Since tracker `api_revision` 7 (always sent from then on; `undefined` + * from a tracker at `api_revision` 6). An opaque content hash of ALL of the + * address's activity (`v1:` + 64 hex characters): the same value whatever + * `filterBridges`, `pageNumber` and `pageSize` the request used. + * + * - It changes when any bridge of the address is added, removed, corrected + * after a reorg (the bridge or its claim re-included in another block or + * transaction) or changes `claim_status`. + * - It does NOT change when a row only becomes final (`finalized` `false` + * to `true`, `'claimed'` to `'claimed_finalized'`), nor on a refresh that + * changes nothing. + * + * Compare the whole string for equality only: it is not a counter and has + * no order, so never parse it or check whether it "grew". It can go back + * to an earlier value when the activity goes back to an earlier content, + * and two tracker instances behind a load balancer can briefly answer + * different values; reloading is always correct. + * + * Client flow: + * 1. Load the pages you need and keep the `revision` of the first + * response. + * 2. To watch for changes, poll cheaply (`pageSize: 1`) and compare its + * `revision` with the one you hold. + * 3. If it differs, reload the pages you had loaded and keep the new + * value. + * 4. After the last page of a traversal, check `revision` again (the last + * response carries it): if it changed during the traversal, restart + * from page 1. + */ + revision?: string; warnings: AggkitActivityWarning[]; } @@ -742,6 +830,14 @@ export type AggkitWrappedTokenResult = AggkitTokenOriginRef & * `TrackingData.tracking_status`: bare string on the wire (fixture-confirmed, * matches aggkit's rc5-corrected API.md) — no numeric value, no * `tracking_status_string` companion. + * + * `'finished'`: the bridge reached its last step, `Claimed`. Since tracker + * `api_revision` 7 it additionally requires the claim's block to be final + * (`claim_status === 'claimed_finalized'`): a bridge that is claimed with a + * claim that is not final yet still reads `'running'` (with `step_index` at + * `Claimed` and `claim_status === 'claimed'`), and a reorg can move it back + * to an earlier step. At `api_revision` 6 `'finished'` is reported as soon as + * the claim is seen. */ export type AggkitTrackingStatus = | 'registered' @@ -845,6 +941,15 @@ export type AggkitTrackerErrorTypeString = * `tracking_status === 'error'` (whether that's a step-level error or the * tracker giving up on the bridge entirely — see `AggkitTrackingData.error`). * - `'claimed'` — the current step (`all_steps[step_index]`) is `Claimed`. + * Since tracker `api_revision` 7 this is NOT final: the claim's block can + * still be removed by a reorg, and the status then goes back to + * `'readyToClaim'` (the claim tx is gone) or `'pending'` (the GER or the L1 + * info tree leaf is gone as well). + * - `'claimed_finalized'` — since tracker `api_revision` 7: claimed, and the + * claim's block is final. The only final state: it never changes again, so + * a client can stop polling a bridge once it reads it. A tracker at + * `api_revision` 6 never sends it (there `'claimed'` is as far as a bridge + * goes). * - `'readyToClaim'` — the current step is `WaitingClaim`. This is the same * condition the SDK's own docs previously told consumers to derive by hand * (see the `AggkitActivityItem`/`getBridgeTracking` JSDoc above) — prefer @@ -856,6 +961,16 @@ export type AggkitTrackerErrorTypeString = * - `'pending'` — every other case, including before the bridge resolves at * all (`tracking_status: 'registered'`). * + * The same vocabulary is used by `AggkitActivityItem.claim_status`. Every + * value but `'claimed_finalized'` is tentative (`'error'` clears as soon as + * the failing check works again). + * + * To ask "is this bridge claimed?" use `isAggkitClaimedStatus`, which is true + * for both `'claimed'` and `'claimed_finalized'`; comparing with `'claimed'` + * alone treats a claimed and final bridge as not claimed. Clients that + * `switch` over this union must handle `'claimed_finalized'` BEFORE they talk + * to a tracker at `api_revision` 7. + * * No fixture yet captures this field (all `__fixtures__/tracker_*.json` * predate #1829). * @@ -875,16 +990,23 @@ export type AggkitClaimStatus = | 'pending' | 'readyToClaim' | 'claimed' + | 'claimed_finalized' | 'error'; /** * Server-side `filterBridges` values of the tracker's activity endpoint - * (`GET /tracker/v1/activity/from/{from_address}?filterBridges=...`): every - * `AggkitClaimStatus`, plus `'all'` (no filtering). Filtering is done by the - * tracker rather than by the consumer so it stays correct across pages - * (`count` is the total matching the filter). + * (`GET /tracker/v1/activity/from/{from_address}?filterBridges=...`): + * `'all'` (no filtering), `'claimed'`, `'pending'`, `'readyToClaim'` and + * `'error'`. Filtering is done by the tracker rather than by the consumer so + * it stays correct across pages (`count` is the total matching the filter). + * + * `'claimed_finalized'` is a `claim_status` but NOT a filter (the tracker + * answers `400` to it): since tracker `api_revision` 7, `'claimed'` returns + * both the `'claimed'` and the `'claimed_finalized'` rows. */ -export type AggkitActivityFilter = 'all' | AggkitClaimStatus; +export type AggkitActivityFilter = + | 'all' + | Exclude; /** * `CertificateData.status`: mapped from the agglayer proto (aggkit @@ -936,6 +1058,18 @@ export interface AggkitBridgeStatus { log_index: number; /** Unix seconds; the origin block's timestamp. */ block_timestamp: number; + /** + * Since tracker `api_revision` 7 (always sent from then on; `undefined` + * from a tracker at `api_revision` 6, which must be read as "unknown", not + * as `false`). `true` once `block_number` is final on the origin network, + * i.e. a reorg can no longer remove the bridge; it never goes back to + * `false`. While it is `false` (not final yet, or not known) a reorg can + * still move the bridge to another block or drop it. + * + * This is the finality of the ORIGIN bridge block only. The claim's + * finality is `claim_status === 'claimed_finalized'`. + */ + block_finalized?: boolean; event: AggkitBridgeStatusEvent; } @@ -1122,7 +1256,8 @@ export interface AggkitTrackingData { /** * Index into `all_steps` of the step that explains `tracking_status`: the * step in progress when `running`, the step in error when `error`, or the - * last step (`Claimed`) when `finished`. + * last step (`Claimed`) once every step is done — `finished`, or, since + * tracker `api_revision` 7, `running` while the claim is not final yet. */ step_index: number | null; /** All expected steps of the bridge's route; `null` until the tracker resolves it. */ diff --git a/src/index.ts b/src/index.ts index de1b885..c438d92 100644 --- a/src/index.ts +++ b/src/index.ts @@ -27,6 +27,7 @@ export { AggkitBridgeClient, AggkitBridgeAggregator, AggkitApiError, + isAggkitClaimedStatus, } from './aggkit'; export type { AggkitApiErrorArgs, From cda5b6c7ee3656b7fc3487e696c240f3c703c36f Mon Sep 17 00:00:00 2001 From: jesteban <129153821+joanestebanr@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:44:16 +0100 Subject: [PATCH 2/4] test(aggkit): make aggkit-smoke aware of tracker api_revision 7 - 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 --- scripts/aggkit-smoke.ts | 100 ++++++++++++++++++++++++++++++++++------ 1 file changed, 87 insertions(+), 13 deletions(-) diff --git a/scripts/aggkit-smoke.ts b/scripts/aggkit-smoke.ts index 2a8ae90..e5a6278 100644 --- a/scripts/aggkit-smoke.ts +++ b/scripts/aggkit-smoke.ts @@ -7,7 +7,9 @@ * test. Exercises: per-network sync-status across {0,1,2}, a real address's * cross-network activity (via the aggregator's `getActivity`, a passthrough * to aggkit's bridgetracker `/tracker/v1/activity`), a known-ground-truth - * claim_status=claimed check, an L2->L2 row's claim_status/tracking state, a LIVE + * claimed check (claim_status `claimed` or, on a tracker at api_revision 7, + * `claimed_finalized`), the api_revision 7 `revision`/`finalized` fields when + * the tracker sends them, an L2->L2 row's claim_status/tracking state, a LIVE * native-gas-token bridge proving the not-ready union (no throw) and * recording-network routing (comments 3847422009 / 3847523270 / 3847600104), * the destination-injected `getClaimInputs` roundtrip for both a sampled @@ -111,6 +113,7 @@ import { import { privateKeyToAccount } from 'viem/accounts'; import { AggkitBridgeClient } from '../src/aggkit/client'; import { AggkitBridgeAggregator } from '../src/aggkit/aggregator'; +import { isAggkitClaimedStatus } from '../src/aggkit/claimStatus'; import type { AggkitClaimInputsResult } from '../src/aggkit/types'; import { bridgeAbi } from '../src/native/bridge/abi/bridge'; @@ -270,14 +273,21 @@ async function main(): Promise { 'getActivity returned at least one activity item for the real from_address' ); - const knownClaimStatuses = ['pending', 'readyToClaim', 'claimed', 'error']; + // `claimed_finalized` is sent by a tracker at api_revision 7 only. + const knownClaimStatuses = [ + 'pending', + 'readyToClaim', + 'claimed', + 'claimed_finalized', + 'error', + ]; const claimStatusCounts: Record = {}; for (const item of activity.bridges) { claimStatusCounts[item.claim_status] = (claimStatusCounts[item.claim_status] ?? 0) + 1; assert( knownClaimStatuses.includes(item.claim_status), - `bridge_hash=${item.bridge.bridge_hash} claim_status "${item.claim_status}" is one of the 4 known states` + `bridge_hash=${item.bridge.bridge_hash} claim_status "${item.claim_status}" is one of the 5 known states` ); } console.log( @@ -285,6 +295,67 @@ async function main(): Promise { claimStatusCounts ); + console.log( + `\n=== 3a. Tracker api_revision 7 fields: revision / finalized (agglayer/sdk#46) ===` + ); + if (activity.revision === undefined) { + // A tracker at api_revision 6 sends neither `revision` nor `finalized`, + // and never `claimed_finalized`. The SDK must work unchanged there. + console.log( + '(no `revision` in the response — tracker at api_revision <= 6; skipping the api_revision 7 checks)' + ); + assert( + activity.bridges.every((item) => item.finalized === undefined), + 'api_revision 6: no activity row carries `finalized`' + ); + assert( + activity.bridges.every( + (item) => item.claim_status !== 'claimed_finalized' + ), + 'api_revision 6: no activity row reads claim_status=claimed_finalized' + ); + } else { + console.log(`revision=${activity.revision}`); + assert( + /^v1:[0-9a-f]{64}$/.test(activity.revision), + 'revision is "v1:" followed by 64 lowercase hex characters' + ); + assert( + activity.bridges.every((item) => typeof item.finalized === 'boolean'), + 'api_revision 7: every activity row carries a boolean `finalized`' + ); + assert( + activity.bridges.every( + (item) => + item.claim_status !== 'claimed_finalized' || item.finalized === true + ), + 'api_revision 7: claim_status=claimed_finalized implies finalized=true' + ); + assert( + activity.bridges.every( + (item) => item.claim_status !== 'claimed' || item.finalized === false + ), + 'api_revision 7: claim_status=claimed (claim not final yet) implies finalized=false' + ); + // `revision` is one value per address, whatever page/filter was asked + // for — the cheap `pageSize: 1` poll a client uses to watch for changes. + // Not asserted equal: on a live chain a new bridge or a claim landing + // between the two requests legitimately changes it. + const cheapPoll = await aggregator.getActivity({ + fromAddress: FROM_ADDRESS, + pageSize: 1, + }); + assert( + typeof cheapPoll.revision === 'string', + 'the cheap pageSize=1 poll carries `revision` too' + ); + console.log( + `cheap poll revision ${ + cheapPoll.revision === activity.revision ? 'unchanged' : 'CHANGED' + } (${cheapPoll.revision})` + ); + } + console.log( `\n=== 3b. L1-origin global_index precision (agglayer/aggkit#1835) + default includeTracking=false ===` ); @@ -330,9 +401,11 @@ async function main(): Promise { `L1-origin bridge.global_index is the exact expected string "18446744073709551618" ` + `(got "${l1OriginRow.bridge.global_index}")` ); + // `claimed`, or `claimed_finalized` on a tracker at api_revision 7 once + // the claim's block is final — both mean "claimed". assert( - l1OriginRow.claim_status === 'claimed', - 'the known L1-origin deposit (global_index=18446744073709551618) derives claim_status=claimed' + isAggkitClaimedStatus(l1OriginRow.claim_status), + 'the known L1-origin deposit (global_index=18446744073709551618) derives a claimed claim_status (claimed or claimed_finalized)' ); assert( l1OriginRow.claim !== undefined, @@ -356,7 +429,7 @@ async function main(): Promise { } // Same default-includeTracking check, generalized across the whole // history fetched above (not just the one L1-origin row): every row's - // claim_status must already be one of the 4 known, directly-usable + // claim_status must already be one of the 5 known, directly-usable // states with no `tracking` field required to interpret it. const rowsWithTracking = activity.bridges.filter( (item) => item.tracking !== undefined @@ -398,12 +471,12 @@ async function main(): Promise { ); if (itemForBridge) { assert( - itemForBridge.claim_status === 'claimed', - `known-claimed bridge (deposit_count=${knownClaimedBridge.deposit_count}) derived claim_status=claimed via getActivity` + isAggkitClaimedStatus(itemForBridge.claim_status), + `known-claimed bridge (deposit_count=${knownClaimedBridge.deposit_count}) derived a claimed claim_status (claimed or claimed_finalized) via getActivity` ); assert( itemForBridge.claim?.tx_hash !== undefined, - 'a claim_status=claimed item carries a joined claim.tx_hash' + 'a claimed item carries a joined claim.tx_hash' ); } else { console.log( @@ -441,15 +514,16 @@ async function main(): Promise { // This round's known-autoclaimed L2-1->L2-2 deposit (also captured in the // unit-test lifecycle fixtures): tx 0xac862504..., deposit_count=2. // Autoclaim landed well before this smoke run, so the derived state - // should be the terminal claim_status=claimed, not still unclaimed. + // should be claimed (`claimed`, or the terminal `claimed_finalized` on a + // tracker at api_revision 7), not still unclaimed. if (l2l2Row.bridge.deposit_count === 2 && l2l2Row.bridge_network_id === 1) { assert( - l2l2Row.claim_status === 'claimed', - 'the known-autoclaimed L2-1->L2-2 deposit (deposit_count=2) derives claim_status=claimed' + isAggkitClaimedStatus(l2l2Row.claim_status), + 'the known-autoclaimed L2-1->L2-2 deposit (deposit_count=2) derives a claimed claim_status (claimed or claimed_finalized)' ); assert( l2l2Row.claim?.tx_hash !== undefined, - 'claim_status=claimed L2->L2 row carries a joined claim.tx_hash' + 'claimed L2->L2 row carries a joined claim.tx_hash' ); } } From b3c6e1863887c9d2d93d9570e7b1008cb88babbf Mon Sep 17 00:00:00 2001 From: jesteban <129153821+joanestebanr@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:44:19 +0100 Subject: [PATCH 3/4] chore: bump version to 1.0.0-beta.34 Refs #46 Co-Authored-By: Claude Fable 5.2 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 25e30be..1baf057 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agglayer/sdk", - "version": "1.0.0-beta.33", + "version": "1.0.0-beta.34", "description": "AggLayer SDK for ARC API and blockchain interactions", "publishConfig": { "access": "public" From 3a5447bea4c5f9a5457c4cde332b3c27183c9c95 Mon Sep 17 00:00:00 2001 From: jesteban <129153821+joanestebanr@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:46:50 +0100 Subject: [PATCH 4/4] docs(aggkit): document tracker api_revision 7 in the README 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 --- README.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 75 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ca4b06e..e0ec849 100644 --- a/README.md +++ b/README.md @@ -325,8 +325,9 @@ const results = await aggregator.getWrappedTokens({ // One request: the tracker fans out server-side across every configured // bridge service and returns one page (newest first) of the address's bridge // history in a unified, deduped, already-claim-checked list. `count` is the -// total across all pages. -const { bridges, count, warnings } = await aggregator.getActivity({ +// total across all pages. `revision` is only sent by a tracker at +// `api_revision` 7 (`undefined` otherwise): see "Reorgs and finality" below. +const { bridges, count, revision, warnings } = await aggregator.getActivity({ fromAddress: '0xFromAddress12345678901234567890123456789012345', pageNumber: 1, // 1-based, default 1 pageSize: 20, // default 20, max 200 @@ -339,10 +340,19 @@ const readyToClaim = bridges.filter( (item) => item.claim_status === 'readyToClaim' ); +// Claimed bridges: use the helper (`import { isAggkitClaimedStatus } from +// '@agglayer/sdk'`), not `claim_status === 'claimed'`. A +// tracker at `api_revision` 7 reports `'claimed_finalized'` once the claim is +// final, and the helper is true for both. +const claimed = bridges.filter((item) => + isAggkitClaimedStatus(item.claim_status) +); + // Or let the tracker filter by bridge status // (`filterBridges=all|claimed|pending|readyToClaim|error`). Prefer this over // client-side filtering: `count` and the pages are computed over the filtered -// set. +// set. `claimed` returns both `'claimed'` and `'claimed_finalized'` rows; +// `claimed_finalized` itself is not a filter value. const { bridges: pending } = await aggregator.getActivity({ fromAddress: '0xFromAddress12345678901234567890123456789012345', filterBridges: 'pending', @@ -351,7 +361,52 @@ const { bridges: pending } = await aggregator.getActivity({ Pages are **not a consistent snapshot**: the tracker can add new bridges between two requests, shifting older ones down. When walking every page, -deduplicate by `bridge.global_index` and, if `count` grew, refetch page 1. +deduplicate by `bridge.global_index` and, if `revision` changed (or, against +a tracker that does not send it, if `count` grew), start again from page 1. + +##### Reorgs and finality (tracker `api_revision` 7) + +A tracker at `api_revision` 7 follows reorgs. Everything in this section is +**optional in the types and only sent by `api_revision` 7**: against a +tracker at `api_revision` 6 the fields are `undefined` (meaning "unknown", +not `false`), `'claimed_finalized'` never appears, and the SDK works +unchanged. + +- `claim_status` has a new value, `'claimed_finalized'`: the claim's block is + final and the status never changes again. It is the only final state. + `'claimed'` is **no longer final**: if a reorg removes the claim, the + bridge goes back to `'readyToClaim'` or `'pending'`. Use + `isAggkitClaimedStatus(status)` for "is it claimed?", and handle + `'claimed_finalized'` wherever you `switch` over `AggkitClaimStatus`. +- `item.finalized` is `true` when a reorg can no longer change the row: its + bridge is final and, if it is claimed, its claim is final too. An unclaimed + row whose bridge is final also reads `true`, and goes back to `false` when + it is claimed, until the claim is final. +- `item.creation_timestamp` (the sort key) can change if a reorg moves the + bridge to another block. Identify a row by `bridge.global_index`. +- `revision` tells you when the pages you loaded went stale. It is an opaque + hash of all of the address's activity (`v1:` + 64 hex characters), the same + for every page and filter. It changes when a bridge is added, removed, + corrected after a reorg or changes `claim_status`; it does **not** change + when a row only becomes final. Compare it for equality only: it is not a + counter. + +```typescript +// 1. Load the pages you need and keep the revision of the first response. +let known = revision; + +// 2. Poll cheaply and compare. +const poll = await aggregator.getActivity({ + fromAddress: '0xFromAddress12345678901234567890123456789012345', + pageSize: 1, +}); +if (poll.revision !== undefined && poll.revision !== known) { + // 3. Something changed somewhere: reload the pages you had loaded. + known = poll.revision; +} +// 4. After the last page of a full traversal, compare again and restart +// from page 1 if it changed meanwhile. +``` `includeTracking` defaults to **`false`**, matching the tracker's own server-side default. Passing `includeTracking: true` is not simply a richer @@ -384,6 +439,17 @@ terminal condition is met: reports `tracking_status: 'error'` too but with `bridge_status` populated and is retried by the tracker on its own). +Since tracker `api_revision` 7, `'finished'` means claimed **and final** +(`claim_status === 'claimed_finalized'`). With the claim done but its block +not final yet, the response stays `tracking_status: 'running'` with +`claim_status: 'claimed'`, and a reorg can move the tracking **backwards** +(to `'readyToClaim'` or `'pending'`, at an earlier step), so do not assume +it only moves forward. To show "claimed" before finality, use +`isAggkitClaimedStatus(trackingData.claim_status)`. The optional +`bridge_status.block_finalized` (also `api_revision` 7 only) says whether +the origin bridge block is final. A tracker at `api_revision` 6 reports +`'finished'` as soon as it sees the claim. + Keep polling through any other non-terminal state, including a regression back to `'registered'` with `all_steps: null` — the FIRST call for a given `(networkId, txHash)` pair registers it with the tracker, and the tracker @@ -416,9 +482,10 @@ short-circuited, but this is not guaranteed either. See `AggkitStepStatus` and `AggkitTrackerErrorType` in `src/aggkit/types.ts`. `TrackingData` also carries `claim_status` -(`'pending' | 'readyToClaim' | 'claimed' | 'error'`, +(`'pending' | 'readyToClaim' | 'claimed' | 'claimed_finalized' | 'error'`, [agglayer/aggkit#1823](https://github.com/agglayer/aggkit/issues/1823), PR -[#1829](https://github.com/agglayer/aggkit/pull/1829)) — use it instead of +[#1829](https://github.com/agglayer/aggkit/pull/1829); +`'claimed_finalized'` only from a tracker at `api_revision` 7) — use it instead of inspecting `step_index`/`all_steps` by hand to decide whether to show a claim button. Same PR adds a `WaitingL1InfoLeafAvailable` step, inserted immediately before `WaitingClaim` on all three routes (L1->L2, L2->L1, @@ -430,7 +497,8 @@ and `AggkitBridgeStep` in `src/aggkit/types.ts`. The activity endpoint's `AggkitActivityItem.claim_status` ([agglayer/aggkit#1830](https://github.com/agglayer/aggkit/issues/1830), PR [#1831](https://github.com/agglayer/aggkit/pull/1831)) now reports this same -`'pending' | 'readyToClaim' | 'claimed' | 'error'` vocabulary, replacing the +`'pending' | 'readyToClaim' | 'claimed' | 'claimed_finalized' | 'error'` +vocabulary, replacing the old `claimed: 'true' | 'false' | 'error'` tri-state — **breaking**: a consumer filtering on `claimed !== 'true'` to find claimable bridges must switch to `claim_status === 'readyToClaim'`. `'readyToClaim'` vs `'pending'`