feat(aggkit): aggkit bridge-service client + multi-network aggregator (incl. bridge tracker, rc5)

[arnaubennassar]

What & why

Adds a self-contained src/aggkit/ module: a typed client and multi-network aggregator for the aggkit bridge service REST API (/bridge/v1). This is the API surface behind the dev-ui's migration off the legacy Bridge Hub API (companion PR agglayer/agglayer-dev-ui#24): everything the UI needs — activity, status derivation, claim proofs, ready-to-claim counts, token metadata, and (later in this PR) bridge tracking — is served from aggkit through this module. The NATIVE module is untouched; the legacy bridge-hub proof path is retained (still used by the NATIVE claim flow) and marked @deprecated.

14 commits, oldest layer first:

1. Bridge-service client + multi-network aggregator (0fa7c77)

• AggkitBridgeClient — typed single-network client (bridges, claims, claim-proof, l1-info-tree-index, token-mappings, sync-status, health) with snake_case query serialization, page_size <= 200 handling, BigInt-safe global_index parsing (raw-text parse), and a typed AggkitApiError.
• AggkitBridgeAggregator — multi-network fan-out with partial-failure reporting (failedNetworks), tiered status derivation (BRIDGED → LEAF_INCLUDED → READY_TO_CLAIM → CLAIMED, with a targeted global_index claims probe to avoid page-1-only false positives), ready-to-claim counting, claim-proof orchestration, and token-metadata composition.
• ERC20.getMetadata() on-chain read helper (aggkit /token-mappings carries no name/symbol/decimals).
• Fixture-driven unit tests (fixtures captured from a live enclave) + a live-enclave smoke script.

2. Claim correctness + proxy fault tolerance (c472bd0)

• New destination-side GER-injection probe (getInjectedL1InfoLeaf) gates READY_TO_CLAIM for L2-destination rows, closing a measured ≥8s premature-READY window whose claim proof would revert GlobalExitRootInvalid on-chain.
• getClaimInputs rebuilt on the destination-injected leaf index rather than the deposit's own L1-info-tree index (previously wrong for every L2-destination claim, incl. L1→L2 manual claims); additive sourceL1InfoTreeIndex field.
• Per-row Tier-2 probe failures degrade to failedNetworks instead of rejecting the whole call; getSyncStatus sends network_id explicitly (unqualified requests 400 through aggkit-proxy).

3. Live smoke script + docs (fef61f2, b706110, 2ec0d5e)

scripts/aggkit-smoke.ts extended to run against aggkit-proxy across networks {0,1,2} (full fan-out activity, real L2→L2 and L2→L1 claim-input checks, opt-in proxy-502 partial-failure section); multi-network proxy configuration and the status lifecycle documented.

4. Bridge tracker API (a8a44a0, c254ec2, 3c6d475, 5ad31b0)

getBridgeTracking — tracker types + client method + aggregator wiring, reconciled against the live-captured wire format (not the docs, which were wrong pre-rc5 — see #1781); terminal-state, step-error, and transient-resolve semantics plus polling guidance documented. This is what the dev-ui tracker UI (companion PR) polls.

5. rc5 phase (fea252e, 76fe6a4, 8094f92, 9a5a5b9, 5bbda2b)

• Tracker JSDoc reframed for rc5's corrected API.md (once mid-phase, once after rc5's fix landed, to keep the barrel doc in sync).
• fix(native): consumer-registered chains now win networkId collisions in the chain registry (see breaking-change note below) — previously the SDK's pre-seeded Ethereum mainnet (networkId 0) shadowed a consumer-registered devnet L1.
• README bridge-tracking section + dangling-ref cleanup; CodeQL ReDoS flag on the baseUrl trailing-slash trim eliminated (regex → linear scan).

Upstream issue context

• bridgetracker: API.md wire-format drift — enums serialize as bare strings, undocumented fields/nesting, expected_duration never emitted aggkit#1781 — tracker API.md had wire-format drift (enums as bare strings, undocumented nesting, expected_duration never emitted). Fixed upstream in rc5 (fix: bridgetracker API.md drift, fail-fast on unset L1GlobalExitRootAddress, unlimited default rate limit (#1781, #1782, #1783) aggkit#1784). Our tracker types were never derived from the buggy docs — they're fixture-derived from live-captured rc4/rc5 wire payloads (30+ payloads checked against 0 violations during review) — so no functional fix was needed here, only a JSDoc pass (76fe6a4) to stop citing the pre-fix API.md text.
• bridgetracker: unset [Tracker].L1GlobalExitRootAddress silently stalls every L1→L2 route at WaitingGERUpdate (zero-address log filter, no fallback, reference recipe affected) aggkit#1782, #1783 — enclave/config-side issues (zero-address GER stall, unenforced rate limit), not applicable to this repo; see the kurtosis-cdk PR.
• bridgetracker: WaitingClaim precedes actual claimability by ~22s — tracker RPC finality defaults (LatestBlock) diverge from L1InfoTreeSync (FinalizedBlock) aggkit#1786 (OPEN) — WaitingClaim precedes real claimability by a measured ~16s gap. No SDK-side change; the client surfaces tracker status as-is, and dev-ui handles the UX mitigation ("Finalizing claim data").

Testing evidence

• npm run typecheck, npm run lint: clean.
• npm run test:run: 113/113 unit tests passing across 5 files, including new registry-precedence tests (registry.test.ts, 6 tests) and the full tracker/aggregator/client suites (33 + 13 + 31 tests). The aggregator suite includes fixture-backed regressions for the L2→L2 premature-window/post-injection transition, the L2→L1 skip path, the 404 message-matching hazard, and the proxy-502 partial-failure path.
• npm run build: green (ESM + CJS + .d.ts all build successfully).
• Live-enclave smoke script (scripts/aggkit-smoke.ts) exercises the client + aggregator against a real kurtosis devnet, both direct and through aggkit-proxy across networks {0,1,2} (migration-phase baseline run: 117 checks PASS / 0 FAIL).
• Registry-precedence tests include explicit proof-of-no-regression cases: no request is made to the default RPC when a consumer override wins the collision, confirming the fix doesn't change behavior for non-colliding consumers.
• Adversarial review (10-item attack list, run across all three repos' diffs) flagged one fixable issue here: stale barrel JSDoc referencing pre-fix rc5 API.md wording, fixed in 76fe6a4 and re-verified (typecheck/lint clean, 113/113 tests). Full attack-list writeup lives in a local plans workspace, not linkable — summarized here.

Breaking-change notes

None for existing consumers — the entire aggkit module is additive (new type/value exports only), and the NATIVE surface is untouched. The chain-registry fix (8094f92) only changes behavior when a consumer explicitly registers a chain whose networkId collides with one of the SDK's built-in defaults — previously the built-in default silently won that collision; now the consumer's registration wins, which is the documented/expected precedence. No default-registry behavior changes for consumers who don't register overrides. Legacy fetchMerkleProof is retained (the NATIVE claim flow still uses it) and marked @deprecated.

Reviewer notes

• Merging this PR does not auto-publish — release is a manual workflow_dispatch workflow, not triggered on merge to main.
• Merge ordering: agglayer-dev-ui's companion PR consumes this SDK via a file:../sdk local snapshot dependency during development, so it should be reviewed/merged in this order: sdk → dev-ui. kurtosis-cdk's companion change is independent of both (deploys the enclave-side backend + tracker).
• Companion PRs (same change set): feat: migrate bridge backend from Bridge Hub API to aggkit bridge service (+ bridge tracker UI, rc5) agglayer-dev-ui#24 (backend migration + tracker UI, depends on this PR), feat(bridge_ui): opt-in aggkit bridge-service backend via aggkit-proxy, 2-L2 enclave + bridge tracker (rc7) 0xPolygon/kurtosis-cdk#929 (enclave-side aggkit backend + bridge-tracker deploy; independent, can merge in any order relative to sdk/dev-ui).

Citation sweep (agglayer/aggkit#1791)

Contributes to agglayer/aggkit#1791.

Local design-doc citations in this branch were replaced with self-contained comments in commits 3879690 (sweep) + 5680d83 (review fix), with no behavior change: dist proven byte-identical after comment-stripping, 115/115 tests passing.

Merging this PR does not complete agglayer/aggkit#1793 — the sdk release is a separate manual workflow_dispatch step (.github/workflows/release.yml), and the dev-ui dependency swap to the published version must follow it. agglayer/aggkit#1793 is tracked independently and gets closed manually once both of those steps have happened.

Other issues to close

Closes agglayer/aggkit#1800.

[MaximusHaximus]

Added some things I noticed in-line -- also posted briefly in Slack about the global_index issue 💖

Fundamentally, I think it would be ideal if the client was defined and published from the aggkit repository that owns the actual REST API interface, and this SDK used a versioned copy of that client rather than the client existing here, built entirely into the SDK - it solves a lot of issues at once. I'm going to open a PR against Aggkit repo showing what that would look like as an example 👍

[MaximusHaximus]

Spotted another occurrence of the global_index where it is not being manually fixed in the SDK; checked the source code and verified it would be silently corrupted by the JSON.parse(). Weirdly, the comment in types.ts even insists that it's already a string even though it isn't as far as I can tell in RC9. My only theory is that the swagger doc was trusted instead of the code being double-checked, or I'm looking at stale code references -- so I included links back to the code where I found the issue in aggkit. 🤔

Added a few other things in-line also

[joanestebanr]

@MaximusHaximus

Spotted another occurrence of the global_index where it is not being manually fixed in the SDK; checked the source code and verified it would be silently corrupted by the JSON.parse(). Weirdly, the comment in types.ts even insists that it's already a string even though it isn't as far as I can tell in RC9. My only theory is that the swagger doc was trusted instead of the code being double-checked, or I'm looking at stale code references -- so I included links back to the code where I found the issue in aggkit. 🤔

The issue related to global_index has been fixed in bridge service: agglayer/aggkit#1835

It has also been released in https://github.com/agglayer/aggkit/releases/tag/v0.11.0-rc10

Let us known if there is anything else left to address

[MaximusHaximus]

❇️ all my prior feedback is addressed --- approving, I don't see anything blocking here.

The inline comments are all nits / non-blocking bookkeeping — take them or leave them 🤷 :)

One thing I think should be fixed before merge: the PR description is pretty out of date now. It still describes getReadyToClaimCount(), the BRIDGED/LEAF_INCLUDED/READY_TO_CLAIM/CLAIMED derivation, failedNetworks, "113/113 tests" (it's 188 now), and "NATIVE surface is untouched".

It also doesn't mention anything that landed from #32/#33/#35/#36/#37/#39 — the tracker-backed getActivity (no pagination, warnings, claim_status), the required aggkitProxyUrl, the rc9 floor, the two ! breaking commits, or the skipped step status.

Would be great to rewrite it to describe what's actually merging, so anyone (or any agent 🤣) reading the history later gets the right picture 👍

[MaximusHaximus]

Non-blocking: aggkit#1786 closed as completed on 09-15, so the "OPEN" and "until #1786 itself closes" wording here is stale now. Worth finding which aggkit release carries the fix, then either bumping the floor to it or rewording the caveat. It matters a bit more now that readyToClaim comes from the tracker instead of the SDK's own GER-injection check. getClaimInputs still guards against acting early, so the worst case is a claimable: false, not a revert 👍

[MaximusHaximus]

Non-blocking, optional: #1835 is in rc10 and rc11 now. If the floor moves for #1786 anyway, this workaround's own removal condition is met and it can go.

[MaximusHaximus]

nit: design §2.2/§2.6 still points at a local design doc. Same at L435 and types.ts:197. Inline the rationale or drop the pointer.

[MaximusHaximus]

nit: same dangling design §2.2/§2.6 citation as client.ts:213.

[MaximusHaximus]

nit: there are ~45 references like comment 3847422009 / PR #33 review across src/ (plus C1/C2/C3 audit labels in the test names). They go stale the moment this merges, and nobody reading the code later will have the context. Would be nice to strip them and keep only the why.

[MaximusHaximus]

nit: history narrative ("Was kind: 'not-injected'…"). Same with "It used to loop…" in getActivity's JSDoc and the FIXED: block in getTokenMetadata. That belongs in commit messages, not in the code.

[MaximusHaximus]

Non-blocking bookkeeping: #30 and #31 both describe code that doesn't exist any more (client-side pagination/fan-out, getReadyToClaimCount). Close them, or rescope to what still applies. The one real leftover I see is that the tracker returns an address's entire history in one response, unpaginated. #38 is also still open even though #39 fixed it.

[MaximusHaximus]

nit: as unknown as Record<string, unknown> double cast. After the in check, reading the value through a Record<string, unknown>-typed binding (or Reflect.get) avoids the cast chain.

[MaximusHaximus]

nit: txHash goes into the path without encodeURIComponent. getActivity does encode fromAddress. Harmless for well-formed hashes, but it should be consistent.