Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 75 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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',
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -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'`
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
100 changes: 87 additions & 13 deletions scripts/aggkit-smoke.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -111,12 +113,13 @@
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';

const AGGKIT_URL = process.env['AGGKIT_URL'];
if (!AGGKIT_URL) {
console.error(

Check warning on line 122 in scripts/aggkit-smoke.ts

View workflow job for this annotation

GitHub Actions / test

Unexpected console statement
'AGGKIT_URL env var is required (aggkit-proxy REST base, e.g. http://127.0.0.1:33042,\n' +
'or <haproxy>/aggkitapi).\n' +
'Re-resolve with: kurtosis port print cdk aggkit-proxy-001 rest'
Expand All @@ -136,7 +139,7 @@
const AGGKIT_TRACKER_URL =
process.env['AGGKIT_TRACKER_URL'] ?? (PROXY_MODE ? AGGKIT_URL : undefined);
if (!AGGKIT_TRACKER_URL) {
console.error(

Check warning on line 142 in scripts/aggkit-smoke.ts

View workflow job for this annotation

GitHub Actions / test

Unexpected console statement
'AGGKIT_TRACKER_URL env var is required when PROXY_MODE=false ' +
'(the standalone bridge tracker is its own service on its own ' +
'host:port; it cannot be inferred from AGGKIT_URL).'
Expand All @@ -159,9 +162,9 @@
function assert(cond: unknown, message: string): void {
if (!cond) {
failures++;
console.error(`FAIL: ${message}`);

Check warning on line 165 in scripts/aggkit-smoke.ts

View workflow job for this annotation

GitHub Actions / test

Unexpected console statement
} else {
console.log(`PASS: ${message}`);

Check warning on line 167 in scripts/aggkit-smoke.ts

View workflow job for this annotation

GitHub Actions / test

Unexpected console statement
}
}

Expand Down Expand Up @@ -195,15 +198,15 @@
return client;
}

console.log(

Check warning on line 201 in scripts/aggkit-smoke.ts

View workflow job for this annotation

GitHub Actions / test

Unexpected console statement
`\naggkit-smoke: base=${AGGKIT_URL} trackerUrl=${AGGKIT_TRACKER_URL} proxyMode=${PROXY_MODE} networks=${JSON.stringify(
L2_NETWORK_IDS
)} fromAddress=${FROM_ADDRESS}`
);

console.log(`\n=== 1. Health (GET /) ===`);

Check warning on line 207 in scripts/aggkit-smoke.ts

View workflow job for this annotation

GitHub Actions / test

Unexpected console statement
if (PROXY_MODE) {
console.log(

Check warning on line 209 in scripts/aggkit-smoke.ts

View workflow job for this annotation

GitHub Actions / test

Unexpected console statement
'SKIPPED — aggkit-proxy has no root health route (haproxy strips the ' +
'/aggkitapi prefix and aggkit-proxy only registers ANY /bridge/v1/*any ' +
'-> 404). getHealth() is unused by the aggregator/app and remains a ' +
Expand All @@ -211,7 +214,7 @@
);
} else {
const health = await mustGetClient(primaryNetworkId).getHealth();
console.log(health);

Check warning on line 217 in scripts/aggkit-smoke.ts

View workflow job for this annotation

GitHub Actions / test

Unexpected console statement
assert(health.status === 'ok', 'health.status === "ok"');
assert(
typeof health.version === 'string' && health.version.length > 0,
Expand All @@ -219,12 +222,12 @@
);
}

console.log(

Check warning on line 225 in scripts/aggkit-smoke.ts

View workflow job for this annotation

GitHub Actions / test

Unexpected console statement
`\n=== 2. Sync status across ALL networks {${allNetworkIds.join(', ')}} (GET /bridge/v1/sync-status?network_id=N) ===`
);
for (const networkId of allNetworkIds) {
const sync = await mustGetClient(networkId).getSyncStatus();
console.log(` network ${networkId}: ${JSON.stringify(sync)}`);

Check warning on line 230 in scripts/aggkit-smoke.ts

View workflow job for this annotation

GitHub Actions / test

Unexpected console statement
assert(
sync.l1_info.is_synced === true,
`network ${networkId}: l1_info.is_synced === true`
Expand Down Expand Up @@ -270,21 +273,89 @@
'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<string, number> = {};
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(
'claim_status distribution across the full history:',
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 ===`
);
Expand Down Expand Up @@ -330,9 +401,11 @@
`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,
Expand All @@ -356,7 +429,7 @@
}
// 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
Expand Down Expand Up @@ -398,12 +471,12 @@
);
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(
Expand Down Expand Up @@ -441,15 +514,16 @@
// 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'
);
}
}
Expand Down
Loading
Loading