feat: add SATP UI inspector

[bhavyamsharmaa]

Problem

cacti-ledger-browser has apps for eth, fabric, and a tutorial app, but no way to inspect SATP cross-chain transfers. Issue #3111 tracked visualization for SATP cross-chain transactions. Only the metrics/dashboard part (Grafana/Prometheus, #3759/#4023) was completed. The inspection UI itself was never built. RafaelAPB noted in #3111 that ledger-browser synergy should be explored, but no follow-up issue was filed.

Proposed solution

Add a new app under packages/cacti-ledger-browser/src/main/typescript/apps for SATP transfers, showing:

• Session/transfer status
• Proofs generated during a transfer
• Gateways and chains involved in a session

This reuses the existing SATP audit/BUNGEE endpoints already exposed by cactus-plugin-satp-hermes. No new backend API surface is required.

Alternatives considered

A standalone dashboard outside ledger-browser. Rejected because ledger-browser already provides the shared UI shell, auth, and layout used by the eth/fabric apps.

Affected package(s)

cactus-plugin-satp-hermes, new package / cross-cutting

Additional context

Related: #3111 (closed; only the metrics/dashboard portion was completed)

[bhavyamsharmaa]

I'll be raising a PR for this shortly.

[RafaelAPB]

@bhavyamsharmaa please review the contribution guidelines. We need first to Triage the issues prior to reviewing PRs.

[RafaelAPB]

@bhavyamsharmaa can you please check the SATP grafana dashboard and CBDC example? Are there components that can be re-used? Perhaps the UI can show the Grafana data.

[bhavyamsharmaa]

Sorry about the "PR shortly" comment — should have waited for triage first.
Checked the Grafana dashboard and CBDC example. No direct code to reuse between them and ledger-browser:

Grafana dashboards (packages/cactus-plugin-satp-hermes/grafana/provisioning/dashboards/) are JSON panels driven by PromQL over OTel metrics — session counts, transaction status/duration, gas/value transferred, connected DLTs. Not React/TS, nothing importable, but gives a good list of what a SATP view should show.
CBDC example frontend (examples/cactus-example-cbdc-bridging-frontend) has a SessionReferencesTable.tsx showing SATP sessions (id, status, substatus, origin/destination ledger). Decent model to follow, but its API client is generated from the CBDC backend's own OpenAPI spec, not the satp-hermes gateway's, so it can't be dropped in as-is.
ledger-browser's eth/fabric apps read from Supabase via persistence plugins (cactus-plugin-persistence-fabric/-ethereum). No SATP equivalent exists yet. A new SATP app would need either a similar persistence plugin, or a direct-REST approach like the CBDC frontend uses.

Simplest near-term option: iframe the existing Grafana dashboard into ledger-browser instead of rebuilding the charts. Alternative: build a proper session-inspection view following the CBDC table's shape, hitting the gateway's REST API directly. Let me know which direction you'd prefer before I start on the design.

[RafaelAPB]

Sorry about the "PR shortly" comment — should have waited for triage first. Checked the Grafana dashboard and CBDC example. No direct code to reuse between them and ledger-browser:

Grafana dashboards (packages/cactus-plugin-satp-hermes/grafana/provisioning/dashboards/) are JSON panels driven by PromQL over OTel metrics — session counts, transaction status/duration, gas/value transferred, connected DLTs. Not React/TS, nothing importable, but gives a good list of what a SATP view should show. CBDC example frontend (examples/cactus-example-cbdc-bridging-frontend) has a SessionReferencesTable.tsx showing SATP sessions (id, status, substatus, origin/destination ledger). Decent model to follow, but its API client is generated from the CBDC backend's own OpenAPI spec, not the satp-hermes gateway's, so it can't be dropped in as-is. ledger-browser's eth/fabric apps read from Supabase via persistence plugins (cactus-plugin-persistence-fabric/-ethereum). No SATP equivalent exists yet. A new SATP app would need either a similar persistence plugin, or a direct-REST approach like the CBDC frontend uses.

Simplest near-term option: iframe the existing Grafana dashboard into ledger-browser instead of rebuilding the charts. Alternative: build a proper session-inspection view following the CBDC table's shape, hitting the gateway's REST API directly. Let me know which direction you'd prefer before I start on the design.

The iframe doesn't make sense. The plugin can request grafana data from the SATP endpoint and then create the visualizations

[bhavyamsharmaa]

Makes sense — no Grafana dependency. Plan: the ledger-browser SATP app calls the gateway's /api/v1/.../satp-hermes/audit REST endpoint directly (returns JSON audit entries for a time window) and computes the same panels client-side — session counts, transaction status/duration, value/gas transferred, connected DLTs — as native React charts, no iframe.

One question: should it use this existing /audit endpoint as-is (aggregating client-side), or would you rather add a new endpoint that returns pre-aggregated metrics? Want to confirm before starting the design.

[RafaelAPB]

One question: should it use this existing /audit endpoint as-is (aggregating client-side), or would you rather add a new endpoint that returns pre-aggregated metrics? Want to confirm before starting the design.

SATP exposes grafana and prometheus endpoints which you can use, together with /audit to fetch data for the visuaizations. Which visualizations are you considering?

[0xbrainkid]

For the first ledger-browser view, I would keep the visualizations close to what an operator needs to answer during or after a transfer, rather than mirroring Grafana panel-for-panel.

A useful minimal set:

• session timeline: current phase, last transition time, success/failure terminal state
• gateway/ledger path: source ledger, destination ledger, gateway pair, and session id links
• proof/audit trail: ordered events from /audit, with proof ids / claim ids surfaced as copyable fields
• failure lens: failed phase, error class, retryable/non-retryable if the audit data exposes it
• value/gas summary: transferred asset/value plus gas/fees where the Prometheus series already has it

The Grafana/Prometheus data seems better for aggregate health (counts, durations, failure rates), while /audit is the better source for the per-transfer forensic view. So I would use both, but make the ledger-browser screen session-centric: select a SATP session, then show the path, proofs, and phase history, with small aggregate panels only as context.

That also gives SATP a cleaner trust surface: the UI is not just "a transaction happened", it shows the evidence trail a reviewer would need to replay why the gateways considered the transfer valid.

[RafaelAPB]

I agree with @0xbrainkid . @bhavyamsharmaa can you please incorporate those points into the ticket? After that, happy to set it to triage ready